Core functions

Core functions provide Finac API when embedded. Core module should not be imported directly, please import main Finac module instead:

import finac as f

f.<function(...)>
exception finac.core.OverdraftError

Raised when transaction is trying to break account max overdraft

JRPC code: -32003

exception finac.core.OverlimitError

Raised when transaction is trying to break account max balance

JRPC code: -32004

exception finac.core.RateNotFound

Raised when accessed asset rate is not found

JRPC code: -32002

exception finac.core.ResourceAlreadyExists

Raised when trying to create already existing resource

JRPC code: -32005

exception finac.core.ResourceNotFound

Raised when accessed resource is not found

JRPC code: -32001

finac.core.account_balance(account=None, asset=None, tp=None, base=None, date=None, _natural=False, _time_ms=False)

Get account balance

Parameters:
  • account – account code
  • asset – account asset filter
  • tp – account type/types, value, list or values, separated with |
  • base – base asset (if not specified, config.base_asset is used)
  • date – get balance for specified date/time
finac.core.account_balance_range(start, account=None, asset=None, tp=None, end=None, step=1, return_timestamp=False, base=None, _time_ms=False)

Get list of account balances for the specified time range

step argument usage:

4, 4d - 4 days 2h - 2 hours 5a - split time range into 5 parts
Parameters:
  • account – account code
  • asset – account asset filter
  • tp – account type/types
  • start – start date/time, required
  • end – end date/time, if not specified, current time is used
  • step – time step
  • return_timestamp – return dates as timestamps if True, otherwise as datetime objects. Default is False
Returns:

tuple with time series list and corresponding balance list
finac.core.account_create(account, asset, tp='current', note=None, passive=None, max_overdraft=None, max_balance=None)
Parameters:
  • asset – asset code
  • account – account code
  • note – account notes
  • passive – if True, account is considered as passive
  • tp – account type (credit, current, saving, cash etc.)
  • max_overdraft – maximum allowed overdraft (set to negative to force account to have minimal positive balance), default is None (unlimited)
  • max_balance – max allowed account balance, default is None (unlimited)

Accounts of type ‘tax’, ‘supplier’ and ‘finagent’ are passive by default

finac.core.account_credit(account=None, asset=None, date=None, tp=None, order_by=['tp', 'account', 'asset'], hide_empty=False)

Get credit operations for the account

Parameters:
  • account – filter by account code
  • asset – filter by asset code
  • date – get balance for specified date/time
  • tp – FIlter by account type
  • sort – field or list of sorting fields
  • hide_empty – don’t return zero balances
Returns:

generator object
finac.core.account_debit(account=None, asset=None, date=None, tp=None, order_by=['tp', 'account', 'asset'], hide_empty=False)

Get debit operations for the account

Parameters:
  • account – filter by account code
  • asset – filter by asset code
  • date – get balance for specified date/time
  • tp – FIlter by account type
  • sort – field or list of sorting fields
  • hide_empty – don’t return zero balances
Returns:

generator object
finac.core.account_delete(account, lock_token=None)

Delete account

finac.core.account_info(account=None)

Get dict with account info

If no account is specified, generator object with info for all accounts is returned

finac.core.account_list(asset=None, tp=None, passive=None, code=None, date=None, base=None, order_by=['tp', 'asset', 'account', 'balance'], group_by=None, hide_empty=False, _time_ms=False)

List accounts and their balances

Parameters:
  • asset – filter by asset
  • tp – filter by account type (or types), value, list or values, separated with |
  • passive – list passive, active or all (if None) accounts
  • code – filter by acocunt code (may contain ‘%’ as a wildcards)
  • date – get balances for the specified date
  • base – convert account balances to base currency
  • order_by – list ordering
  • group_by – ‘asset’ or ‘type’
  • hide_empty – hide accounts with zero balance, default is False
finac.core.account_list_summary(asset=None, tp=None, passive=None, code=None, date=None, order_by=['tp', 'asset', 'account', 'balance'], group_by=None, hide_empty=False, base=None, _time_ms=False, _rsingle=False)

List accounts and their balances plus return a total sum

Parameters:
  • asset – filter by asset
  • tp – filter by account type (or types)
  • passive – list passive, active or all (if None) accounts
  • code – filter by acocunt code (may contain ‘%’ as a wildcards)
  • date – get balances for the specified date
  • order_by – list ordering
  • group_by – ‘asset’ or ‘type’
  • hide_empty – hide accounts with zero balance, default is False
  • base – base asset (if not specified, config.base_asset is used)
Returns:

list of accounts or assets: list of assets or account_types: list of accoun types

total: total sum in base asset
Return type:

accounts
finac.core.account_lock(account, token)

Lock account

Account locking works similarly to threading.RLock(), but instead of thread ID, token is used.

If token is provided and match the current lock token, lock counter will be increased and lock is passed

When locked, all account transaction operation are freezed until unlocked (unless current lock token is provided for the operation)

Returns:specified lock token or new lock token if no token provided
finac.core.account_statement(account, start=None, end=None, tag=None, pending=True, datefmt=False, _time_ms=False)
Parameters:
  • account – account code
  • start – statement start date/time
  • end – statement end date/time
  • tag – filter transactions by tag
  • pending – include pending transactions
  • datefmt – format date according to configuration
Returns:

generator object
finac.core.account_statement_summary(account, start=None, end=None, tag=None, pending=True, datefmt=False)
Parameters:
  • account – account code
  • start – statement start date/time
  • end – statement end date/time
  • tag – filter transactions by tag
  • pending – include pending transactions
  • datefmt – format date according to configuration
Returns:

debit: debit turnover credit: credit turonver net: net debit statement: list of transactions
Return type:

dict with fields
finac.core.account_unlock(account, token)

Unlock account

Note that if you call account_lock, you must always unlock account, otherwise it will be locked until process restart

finac.core.account_update(account, **kwargs)

Update account parameters

Parameters, allowed to be updated:
code, note, tp, max_balance, max_overdraft
finac.core.archive_transactions(account=None, tp=None, due_date=None, keep_deleted=False, lock_token=None, _open_dbt=True, _db=None)

Archive account transactions

Combines account transactions to due_date into a single service transaction. After archivation process is finished, cleanup() method should be called to remove archived transactions from the database.

Only completed transactions are archived.

WARNING: backing up database is always recommended before performing archiving procedure. If copy of archived transactions is required, it should be performed manually.

Parameters:
  • account – account to archive transactions on due_date: archivation date
  • tp – or account type (types)
  • (default – now) keep_deleted: keep deleted transactions (default: False)
finac.core.asset_create(asset, precision=2)

Create asset

Parameters:
  • asset – asset code (e.g. “CAD”, “AUD”)
  • precision – precision (digits after comma) for statements and exchange operations. Default is 2 digits
finac.core.asset_delete(asset)

Delete asset

Warning: all accounts linked to this asset will be deleted as well

finac.core.asset_delete_rate(asset_from, asset_to=None, date=None)

Delete currrency rate

finac.core.asset_list()

List assets

finac.core.asset_list_rates(asset=None, start=None, end=None, datefmt=False, _time_ms=False)

List asset rates

Asset can be specified either as code, or as pair “code/code”

If asset is not specified, “end” is used as date to get rates for all assets

finac.core.asset_precision(asset)

Get precision (digits after comma) for the asset Note: asset precision is cached, so process restart required if changed

finac.core.asset_rate_range(start, asset_from=None, asset_to=None, end=None, step=1, asset=None, return_timestamp=False, _time_ms=False)

Get list of asset rates for the specified time range

step argument usage:

4, 4d - 4 days 2h - 2 hours 5a - split time range into 5 parts
Returns:tuple with time series list and corresponding asset rate
finac.core.asset_set_rate(asset_from, asset_to=None, value=None, date=None)

Set asset rate

Parameters:
  • asset_from – asset from code
  • asset_to – asset to code
  • value – exchange rate value
  • date – date/time exchange rate is set on (default: now)

Function can be also called as e.g. asset_set_rate(‘EUR/USD’, value=1.1)

finac.core.asset_update(asset, **kwargs)

Update asset parameters

Parameters, allowed to be updated:
code, precision

Note that asset precision is cached and requires process restart if changed

finac.core.cleanup()

Cleanup database

finac.core.config_set(prop, value)

Set configuration property on-the-fly (config.insecure = True required)

Recommended to use for testing only

Parameters:
  • prop – property name
  • value – property value
finac.core.exec_query(q, _time_ms=False)

Execute FinacQL query statement

Parameters:

q – query to execute
Returns:

List of dicts is always returned
Raises:
  • RuntimeError – unsupported statement / function called
  • other – passed from called function as-is
finac.core.format_amount(i, asset, passive=False)

Format amount for values and exchange operations. Default: apply asset precision

finac.core.init(db=None, **kwargs)

Initialize finac database and configuration

Parameters:
  • db – SQLAlchemy DB URI or sqlite file name
  • db_pool_size – DB pool size (default: 10)
  • thread_pool_size – thread pool size for internal processes (default: 30)
  • keep_integrity – finac should keep database integrity (lock accounts, watch overdrafts, overlimits etc. Default is True
  • lazy_exchange – allow direct exchange operations betwen accounts. Default: True
  • rate_allow_reverse – allow reverse rates for lazy exchange (e.g. if “EUR/USD” pair exists but no USD/EUR, use 1 / “EUR/USD”
  • rate_allow_cross – if exchange rate is not found, allow finac to look for the nearest cross-asset rate
  • rate_cache_size – set rate cache size (default: 1024)
  • rate_cache_ttl – set rate cache ttl (default: 5 sec)
  • full_transaction_update – allow updating transaction date and amount
  • base_asset – default base asset. Default is “USD”
  • date_format – default date format in statements
  • multiplier – use data multiplier
  • restrict_deletion – 1 - forbid purge, 2 - forbid delete functions
  • redis_host – Redis host
  • redis_port – Redis port (default: 6379)
  • redis_db – Redis database (default: 0)
  • redis_timeout – Redis server timeout
  • redis_blocking_timeout – Redis lock acquisition timeout
  • custom_account_types – custom account types dict
Note: if Redis server is specified, Finac will use it for integrity locking
(if enabled). In this case, lock tokens become Redis lock objects.
finac.core.preload()

Preload static data

finac.core.purge()

Purge deleted resources

finac.core.transaction_apply(fname)

Apply transaction yaml file

File format example:

transactions:
  • account: acc1 amount: 500 tag: test
  • dt: acc2 ct: acc1 amount: 200 tag: moving

If “account” is specified, function transaction_create is called, otherwise transaction_move. All arguments are passed to the functions as-is

Returns:list of transaction IDs
finac.core.transaction_complete(transaction_ids, completion_date=None, lock_token=None)
Parameters:
  • transaction_ids – single or list/tuple of transaction ID
  • completion_date – completion date (default: now)
finac.core.transaction_copy(transaction_ids, date=None, completion_date=None, mark_completed=None, amount=None)

Copy transaction :param transaction_ids: one or list/tuple of transaction id :param date: transaction date :param completion_date: transaction completion date :param mark_completed: if no completion_date is specified, set completion

date equal to creation. Default is True
Parameters:amount – new amount, if old transaction has chain_transact_id will be exception
Returns:list with id/ids new transaction
finac.core.transaction_create(account, amount=None, tag=None, note=None, date=None, completion_date=None, mark_completed=True, target=None, lock_token=None)

Create new simple transaction on account

Parameters:
  • account – account code
  • amount – tranasction amount (>0 for debit, <0 for credit)
  • tag – transaction tag
  • note – transaction note
  • date – transaction date
  • completion_date – transaction completion date
  • mark_completed – if no completion_date is specified, set completion date equal to creation. Default is True
  • target – if no amount but target is specified, calculate transaction amount to make final balance equal to target
finac.core.transaction_delete(transaction_ids)

Delete (mark deleted) transaction

finac.core.transaction_info(transaction_id)

Get dict with transaction info

finac.core.transaction_move(dt=None, ct=None, amount=0, tag=None, note=None, date=None, completion_date=None, mark_completed=True, target_ct=None, target_dt=None, rate=None, xdt=True, credit_lock_token=None, debit_lock_token=None)

Create new standard (double-entry bookkeeping) transaction

Parameters:
  • ct – source (credit) account code
  • dt – target (debit) account code
  • amount – transaction amount (always >0)
  • tag – transaction tag
  • note – transaction note
  • date – transaction creation date (default: now)
  • completion_date – transaction completion date (default: now)
  • mark_completed – mark transaction completed (set completion date)
  • target_ct – target credit account balance
  • target_dt – target debit account balance
  • rate – exchange rate (lazy exchange should be on)
  • xdt – for lazy exchange: True (default): amount is debited and calculate rate for credit False: amount is credited and calculate rate for debit
Returns:

tuple of two transactions
Return type:

transaction id, if lazy exchange performed
finac.core.transaction_purge(_lock=True)

Purge deleted transactions

finac.core.transaction_update(transaction_id, **kwargs)

Update transaction parameters

Parameters, allowed to be updated:
tag, note