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

Note: 0.0.18 patches an import bug included in 0.0.17. For simplicity's sake, the 0.0.17 changelog has been renamed to 0.0.18.

Amatino Python 0.0.16

0.0.16 adds Entity listing, compatible with Amatino API 0.0.19. You can retrieve lists of Entities, and search them by name.

Changelog

• 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

Listing example

great_entities = Entity.retrieve_list(
    session=session,  # Instance of `amatino.Session` created elsewhere
    name='great'      # Find Entities whose name contains "great"
)

Listed Entities have a .disposition property, itself an object with integer properties .count, .sequence, .limit, and .offset, which together define the position of an Entity within a list of Entities.

Installation

Install / upgrade Amatino via PyPi:

pip install --upgrade amatino

Amatino Python 0.0.15

0.0.15 removes JSON bodies from HMAC calculations, for compatibility with Amatino API 0.0.18. There are no public facing changes in 0.0.15, and code written for 0.0.14 will continue to run as before.

0.0.14

This is a small release that fixes some out-of-spec behaviour by Entity. Entity was internally using some undocumented coding keys, and exposing an undocumented .active property.

0.0.13 - A Lens on History

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.

0.0.12 - Growing Trees

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.

0.0.11 - Position & Performance

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!

0.0.10 - Achieving Balance

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

0.0.7 - Foundational Capabilities

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