Amatino Python v0.0.18

v0.0.18 makes the following changes. Code currently running on v0.0.16 should generally be backwards compatible with v0.0.18.

  • Requests for resources that Amatino API cannot find will now raise a ResourceNotFound error, rather than a generic urllib.HTTPError. ResourceNotFound is a subclass of AmatinoError, allowing you to catch non-existent resources along with other Amatino library exceptions.
  • Internally, ApiRequest.response_data is now immutable
  • In previous versions, ApiRequest responded to an undocumented command line argument --debug. This argument is common and may clash with application command line arguments, causing unexpected behaviour. The argument has been renamed --amatino-debug.
  • GlobalUnit no longer has a .session property
  • GlobalUnit now implements the equality operator via __eq__()
  • Added a new class: GlobalUnitConstants, which enumerates a subset of common GlobalUnits. For example:
# Previously, the only way to get USD was...
usd = GlobalUnit.retrieve(5, session)
# Now you can also...
usd = GlobalUnitConstants.USD

Install Amatino Python via Pip:

pip install --upgrade amatino

Amatino API 0.0.19 Released

0.0.19 modifies Entity listing behaviour. It is now possible to search for Entities by name. The manner in which Amatino conveys listed Entities changed, and this new manner will be rolled out across all Amatino objects in time.

0.0.18 code is not backwards compatible with API 0.0.19 with respect to Entity listing.

New Entity Listing Model

Prior to 0.0.19, a request to /entities/list would return a package of the form:

{
    'entities': [...]
    'number_of_pages': [integer],
    'page': [integer],
    'state': [string],
    'generated_time': [string]
}

… Wherein the Entity objects were returned under the "entities" key. In 0.0.19, Entities are now returned as a list of Entity objects. There is no encapsulating package providing list metadata.

Instead, the Entity object itself is aware of its own disposition with respect to a listing query. Inside the Entity object is a new keyed value, "disposition":

{
    "entity_id": [string],
    "name": [string],
    "owner": [integer],
    "description": [string],
    "region_id": [integer],
    "permissions_graph": [object],
    "disposition": {
        "sequence": [integer],
        "count": [integer],
        "limit": [integer],
        "offset": [integer]
    }
}

The meanings of the four integers inside the Disposition are:

Limit: The maximum number of objects returned in response to the request.

Offset: The sequence number at which the returned objects start.

Count: The total number of objects having attributes that satisfy the request. For example, if you request all Entities whose name starts with "Great", with a limit of 10 and offset 0, and there are 12 entities with such names, you will receive a "count" value of 12 and a "limit" value of 10.

Sequence: The unique position of this object within all possibly returned objects satisfying the request conditions.

In future, this model will be adopted by all Amatino objects that may be listed. That is, they will all include a Disposition object.

Searching by Name

The /entities path now accepts a new URL parameter: name. The value for name can be any string value between 3 and 64 characters long. It is optional.

Amatino will search for all Entities with a case-insensitive name that contains the specified string. For example, "name=orporation" will return Entities with name "Excellent Corporation" and "PROFITABLE CORPORATION LTD".

You can omit the name key entirely.

0.0.19 Compatible Libraries

New versions of Amatino client libraries are available, compatible with API 0.0.19:

Changelogs

Amatino Python 0.0.16

  • Added Entity.retrieve_list() -> List[Entity] method
  • Fixed bad type annotation, Entity.retrieve() now hints at return type of Optional[Entity]
  • Added Disposition class
  • Added Entity.disposition property
  • Remove debug print from Signature computation

Amatino Swift 0.0.14

  • Removed deprecated EntityList
  • Added EntityList.retrieveList(), available in both error-first and and Result callback forms
  • Added Disposition struct
  • Added Entity.disposition property
  • Removed EntityListScope enum
  • Added State enum

Amatino API v0.0.18 [Heavily Breaking Changes]

A new version of the Amatino API has been deployed. 0.0.18 contains breaking changes – Any code interfacing with versions below 0.0.18 will not work with 0.0.18.

0.0.18 modifies the way HMAC signatures are computed. JSON bodies are no longer included in signature computation. Their inclusion was causing intermittent issues for customers: Seemingly at random, requests would be met with 401 - Not Authenticated responses.

The inclusion of JSON bodies in HMAC computation was, in hindsight, a poor decision. By definition, JSON object key/value ordering is indeterminate. If a key/value pair happens to be parsed in a different order on either side of the client / API connection, the request would fail.

Along with API 0.0.18, the following new client libraries are available:

Each of these libraries supports API 0.0.18.

We never want to make breaking changes like this. We understand how frustrating it is to have integrations break, and apologise profusely. While Amatino is in an “alpha” state (pre v1.0.0), we will make these changes as rarely as possible. After v1.0.0, breaking changes will only be made with prior versions remaining online.

Amatino Python 0.0.13 Released

Rejoice, Pythonistas! A new version of the Amatino Python library is now available. 0.0.13 adds new capabilities. Amatino Python is now nearing initial feature completion, with almost all existing API classes covered. Watch out, 0.0.13 is catastrophically breaking, many method signatures have changed and code written for 0.0.12 will not work.

Why all the breaks? Many methods in 0.0.12 required the provision of a Session independent of an Entity, despite that Entity having ready access to the Session used when it was itself initialised. This redundancy was needlessly verbose.

  • Add new UserList class
  • Add User.delete(), .create(), and .create_many() method
  • Add TransactionVersionList class
  • Conform Ledger to collections.Sequence
  • Simplify Ledger, Balance, Account, and Transaction method signatures: No more Session requirement
  • Publicise User.decode_many() method
  • Conform Transaction to collections.Sequence
  • Add Transaction.magnitude property
  • Conform Balance and RecursiveBalance to Denominated protocol
  • Conform Ledger and RecursiveLedger to Denominated protocol

Ledger and Transaction may be now be directly iterated over, revealing constituent LedgerRows and Entries respectively. They may also be subscripted.

An example using Ledger:

ledger = Ledger.retrieve(
   entity=mega_corp,
   account=revenue
)

for row in ledger:
   print("[{date}] {balance}".format(
      date=row.transaction.time.strftime("%Y-%m-%d"),
      balance='{:,.2f}'.format(row.balance)
   ))

print("Last row balance: {balance}".format(
   balance='{:,.2f}'.format(ledger[-1].balance)
))

And Transaction:

sale = Transaction.retrieve(
   entity=mega_corp,
   id_=42,
   denomination=USD
)

print("Largest single entry: {amount}".format(
   amount='{:,2f}'.format(
      max([entry.amount for entry in sale])
   )
))

The new UserList allows you to retrieve all white-labels managed by your billing account. Draw on the State enum to refine the retrieval to all, deleted, or active users.

active_users = UserList(
   session=session,
   state=State.active
)

print("Currently paying for {num} users".format(
   num=str(len(active_users))
))

Review the history of modifications to a Transaction using the TransactionVersionList.

versions = TransactionVersionList.retrieve(
   entity=mega_corp,
   transaction=big_sale
)

for version in versions:
   print("{time}: {magnitude}".format(
      time=version.version_time.strftime("%Y-%m-%d"),
      magnitude='{:,2f}'.format(version.magnitude)
   )

For detailed documentation of the properties and methods of all Amatino classes, check out the Amatino Python Documentation.

You can install Amatino via PyPi:

$ pip install amatino

Or, if you already have Amatino Python installed, upgrade:

$ pip install --upgrade amatino

Your feedback is most welcome on the Amatino discussion forums, or on Twitter.

Amatino Python 0.12 Released

Hot on the heels of 0.0.11, Amatino Python 0.0.12 has been released. 0.0.12 enhances the capabilities of the Position and Performance classes added in 0.0.11, and introduces the new Tree class.

  • Add Tree class
  • Add total account balance properties to Performance
  • Add total account balance properties to Position
  • Add tests for all new features

The new properties in Position and Performance give you quick access to key financial data describing an entity.

print("{name} total assets: ${assets}".format(
   name=mega_corp.name,
   assets='{:,}'.format(position.total_assets)
)
# Example output:
# Mega Corp total assets: $1,543

Check out the Amatino Python documentation to see all the new properties.

The new Tree class is a beast, combining all accounts in an entity into a single recursive object, at a particular balance date. Like Position and Performance, Tree accounts are of type TreeNode, which means you have access to recursive and individual balances and other useful data.

from amatino import Tree
from datetime import datetime

tree = Tree.retrieve(
   entity=mega_corp,
   balance_time=datetime.utcnow()
)

print("{name} equity: ${equity}".format(
   name=mega_corp.name,
   equity='{:,}'.format(tree.total_equity)
)

For detailed documentation of the properties and methods of the Tree class, check out the Amatino Python Documentation.

You can install Amatino via PyPi:

$ pip install amatino

Or, if you already have Amatino Python installed, upgrade:

$ pip install --upgrade amatino

Be sure to leave your feedback on the Amatino discussion forums, or on Twitter, we’d love to hear what you think about Amatino Python.

Amatino Python 0.0.11 Released

A new version of the Amatino Python library is now available! 0.0.11 introduces Python versions of the powerful Position and Performance objects.

  • Add Position class
  • Add Performance class
  • Add TreeNode class
  • Add Denominated protocol
  • Add Decodable protocol
  • Add tests for Position & Performance retrieval

The new Position & Performance classes map to the Amatino HTTP API Position & Performance objects. TreeNodes support the Position & Performance classes by representing Accounts in their hierarchies.

A Position is analogous to a balance sheet or statement of financial position. A Performance is analogous to an income statement or statement of financial performance.

You may retrieve the new objects like so:

from amatino import Performance

income_statement = Performance.retrieve(
  entity=mega_corp,
  start_time=(datetime.utcnow() - timedelta(days=365))
  end_time=datetime.utcnow()
  denomination=USD
)
from amatino import Position

balance_sheet = Position.retrieve(
  entity=mega_corp,
  balance_time=datetime.utcnow()
  denomination=USD
)

For detailed documentation of the properties and methods of these new classes, check out the Amatino Python Documentation.

You can install Amatino via PyPi:

$ pip install amatino

Or, if you already have Amatino Python installed, upgrade:

$ pip install --upgrade amatino

Enjoy!

Amatino Python 0.0.10 Released

Amatino Python 0.0.10 has been released! 0.0.10 is all about balance. 0.0.10 is backward compatible with 0.0.7. 0.0.8 and 0.0.9 were skipped because… software. Changes in 0.0.10:

  • Add Balance class
  • Add RecursiveBalance class
  • Add tests for Balance & RecursiveBalance
  • Resolve bug causing amounts > 1,000 units to raise errors on retrieval

The new Balance & RecursiveBalance classes map to the Amatino API Balance & RecursiveBalance objects. They both have the same .retrieve() method signature…

balance = Balance.retrieve(
   entity=mega_corporation,
   account=current_assets,
   balance_time=datetime.utcnow(),
   denomination=us_dollars
)

… Wherein balance_time is optional (defaults to “now”) and denomination is optional (defaults to account.denomination).

For detailed documentation of the properties and methods of these new classes, check out the Amatino Python Documentation.

You can install Amatino via PyPi:

$ pip install amatino

Or, if you already have Amatino Python installed, upgrade:

$ pip install --upgrade amatino

Amatino Python 0.0.7 Released

Amatino Python 0.0.7 has been released! This is a major new release, introducing a vast array of capabilities. It is not backwards compatible with 0.0.6. You can install Amatino via PyPi:

$ pip install amatino

Or, if you already have Amatino Python installed, upgrade:

$ pip install --upgrade amatino

Here’s the full list of changes:

  • Added Entity class including .create(), .retrieve()
  • Added Account class including .create(), .retrieve(), .update()
  • Added Transaction class including .create(), .retrieve(), .update(), .delete()
  • Added Entry class including various convenience initialisers
  • Added GlobalUnit class including .retrieve()
  • Added CustomUnit class including .create(), .retrieve()
  • Added User class including .retrieve()
  • Added Ledger & RecursiveLedger classes
  • Added internal Denomination abstract class
  • Added internal enumeration HTTPMethod
  • Added internal interface Encodable
  • Added some internal error types to provide more robust error explanations
  • Added tests for new classes
  • Removed AmatinoAlpha class & attendant tests

The high level

0.0.7 is the first Amatino Python release to include expressive, object-oriented syntax. Previous releases required manual composition of requests using the AmatinoAlpha object.

Documentation

So many new goodies. But how do we use them? Documentation to the rescue! All the new classes included in 0.0.7 are documented in Amatino Python’s GitHub Wiki. For example, you can check out the Transaction page to see all the Transaction class’s properties and methods.

The future

The most glaring omissions are 0.0.7 are probably Balance, Position, and Performance. Expect 0.0.8 to add those bad boys in the near future.

Enjoy!

– Hugh