API Reference

Currency

The currency module defines currencies of various types. Use them wherever you need to record loans or transactions of exchange.

Tallwallet 0.10.0 only defines a handful of currency types. Look out for improvements in future releases.

class tallywallet.common.currency.Currency[source]

This is an enumeration class which captures the codes defined in ISO 4217 for international currencies.

Finance

class tallywallet.common.finance.Note

Note(date, principal, currency, term, interest, period)

A Note keeps all the details of a promise to pay a debt, as follows:

date

The date on which the loan is agreed.

principal

The amount of the original loan.

currency

The currency in which the loan will be paid.

term

The duration of the loan.

interest

The rate of interest.

period

The period of time over which interest is calculated.

Create new instance of Note(date, principal, currency, term, interest, period)

The functions of the Finance module are all intended to be compatible with the Note type. They either take such an object as a parameter, or their keyword arguments can be supplied from the result of the vars function on a Note object.

tallywallet.common.finance.value_simple(note: tallywallet.common.finance.Note)[source]

Returns the simple value of a promissory note on maturity.

tallywallet.common.finance.value_series(date, principal, term, period, interest, m=1, **kwargs)[source]

Calculate the value of a debt over time. Parameters are as for the Note type. Additionally:

m

The number of times per period that interest is compounded.

This function is a generator. It produces 2-tuples of (date, value).

tallywallet.common.finance.discount_simple(note: tallywallet.common.finance.Note)[source]

Calculates the discounted value of an ordinary simple annuity. See Schaum’s Mathematics of Finance Equation 5.2 .

Returns a 3-tuple of (number of payments, annualised rate, annuity payment)

tallywallet.common.finance.schedule(note: tallywallet.common.finance.Note, places=2, rounding='ROUND_UP')[source]

Calculate the amortization schedule for a Note.

places

An integer. Round the balance to this number of decimal places at each calculation interval.

rounding

Selects the rounding method. Must be one of the constants defined for this purpose in the decimal standard library module.

This function is a generator. It produces a sequence of Amortization objects.

class tallywallet.common.finance.Amortization

Amortization(date, payment, interest, repaid, balance)

An Amortization object records a payment against an amortization schedule:

date

The date on which the payment is made.

payment

The total amount of the payment.

interest

The amount paid as interest.

repaid

The amount repaid from the principal.

balance

The remaining balance of the loan.

Create new instance of Amortization(date, payment, interest, repaid, balance)

Trade

class tallywallet.common.trade.TradePath

TradePath(rcv, work, out)

A 3-tuple of Currency objects, describing the path of a foreign exchange trade. The first element is the source currency, the second the reference currency of the account, and the third the destination currency.

Create new instance of TradePath(rcv, work, out)

class tallywallet.common.trade.TradeGain

TradeGain(rcv, gain, out)

A 3-tuple of numerical values, describing the result of a change in foreign exchange rates. The first element is the value due to the prior rate, the second is the gain due to the rate change, and the third element is the final sum.

Create new instance of TradeGain(rcv, gain, out)

Exchange

The exchange module contains functionality to enable conversion between currencies.

class tallywallet.common.exchange.Exchange

An exchange is a lookup container for currency exchange rates.

It behaves just like a Python dictionary, but has some extra methods.

The approach Tallywallet uses is to associate each rate against a key which is a 2-tuple of Currency. By convention, the first element of this key is the source currency, and the second is the destination. The values of the exchange mapping can therefore be considered as gain from one currency to the next.

get(key)

Return the value stored against key.

This method overrides the standard behaviour of dict.get. It infers the values of missing keys as follows:

  • The rate of a currency against itself is unity.

  • The rate of one currency against another is the reciprocal of the reverse rate (if defined).

convert(val, path, fees=TradeFees(rcv=0, out=0))

Return the calculated outcome of converting the amount val via the TradePath path.

gain(val, path, prior=None, fees=TradeFees(rcv=0, out=0))

Calculate the gain related to a change in exchange rates. The self object contains the latest rates, and the historic ones are passed as an argument to this method.

Parameters

prior – An Exchange object which contains the rates existing prior to those in the self object.

Return type

TradeGain

Ledger

The ledger module defines Ledger and some associated classes.

class tallywallet.common.ledger.Role[source]

This enumeration contains definitions for the roles played by a column in a Ledger.

class tallywallet.common.ledger.Column

Column(ref, currency, role, label)

A 4-tuple, describing a column in a Ledger.

Create new instance of Column(ref, currency, role, label)

class tallywallet.common.ledger.Ledger(*args, ref=<Currency.XTW: 'tallywallet'>)[source]

This class implements the fundamental operations you need to perform Adjusted Cost Base accounting.

Parameters
  • ref – (optional) the base Currency type for the Ledger

  • args – One or more Column objects

property equation

The Fundamental Accounting Equation is this:

Assets - Liabilities = Capital + Income - Expenses - Dividends

Currency trading gains are counted as income. For practical purposes, the FAE is often rearranged to be:

Assets + Expenses + Dividends = Capital + Income + Liabilities

This property evaluates both sides of this second equation, and determines if they are equal or not.

Returns

A tuple of lhs, rhs, status

adjustments(exchange, cols=None)[source]

Calculates the effects of a change in exchange rates.

Supply an Exchange object and an optional sequence of columns. If no columns are specified then all are assumed.

The columns are recalculated (but not committed) against the new exchange rates.

This method will generate a sequence of 3-tuples; (TradeGain, Column, Exchange).

This output is compatible with the arguments accepted by the commit method.

commit(trade, col, exchange=None, **kwargs)[source]

Applies a trade to the ledger.

If you supply an exchange argument, trade may be a TradeGain object. In this usage, a trading account in the currency of the ledger column will accept any exchange gain or loss.

Otherwise, trade should be a number. It will be added to the specified column in the ledger.

balance(ref)[source]

Returns columns and their values in the ledger.

Parameters

ref – The ref of the column

value(arg)[source]

Returns the current value of a column in the ledger.

Parameters

arg – The column object, or its name as a string

Output

Tallywallet has chosen RSON as the serialisation format for a Ledger. It’s a readable serial object notation which can be processed by text utilities or converted into Python objects.

tallywallet.common.output.metadata(ledger)[source]

Create an RSON string containing all the metadata required to recreate a working Ledger object.

tallywallet.common.output.journal(ledger, **kwargs)[source]

Create an RSON string representing the current state of a Ledger object.

Journal strings can be appended to metadata, and/or concatenated to form a time-series record of the Ledger accounts.