{"id":19665233,"url":"https://github.com/alttch/finac","last_synced_at":"2025-04-28T22:31:04.860Z","repository":{"id":45627095,"uuid":"216699607","full_name":"alttch/finac","owner":"alttch","description":"Finac - financial accounting for humans","archived":false,"fork":false,"pushed_at":"2023-06-13T20:43:02.000Z","size":480,"stargazers_count":40,"open_issues_count":0,"forks_count":8,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-24T09:52:55.784Z","etag":null,"topics":["accounting","double-entry-accounting","double-entry-bookkeeping","finance","financial","fintech","library","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alttch.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-22T01:41:29.000Z","updated_at":"2025-03-01T05:21:55.000Z","dependencies_parsed_at":"2024-11-11T16:34:06.232Z","dependency_job_id":null,"html_url":"https://github.com/alttch/finac","commit_stats":{"total_commits":436,"total_committers":3,"mean_commits":"145.33333333333334","dds":0.04587155963302747,"last_synced_commit":"956dd3bda113cb65d57d6ffa5568440a87656177"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alttch%2Ffinac","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alttch%2Ffinac/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alttch%2Ffinac/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alttch%2Ffinac/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alttch","download_url":"https://codeload.github.com/alttch/finac/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251397577,"owners_count":21583034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accounting","double-entry-accounting","double-entry-bookkeeping","finance","financial","fintech","library","python","python3"],"created_at":"2024-11-11T16:21:43.851Z","updated_at":"2025-04-28T22:31:04.236Z","avatar_url":"https://github.com/alttch.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Finac - financial accounting for humans\n\nFinac is a library and function set for Jupyter/ipython, which provides the\ndouble-entry bookkeeping database.\n\nFinac is simple, open and free. It can work with SQLite or any database\nsupported by SQLAlchemy (tested: SQLite, MySQL, PostgreSQL).\n\nWARNING: SQLAlchemy 2 is NOT SUPPORTED until stabilized. If SQLAlchemy 2 is\nrequired for other projects, run Finac in a dedicated virtual environment. \n\n\u003cimg src=\"https://img.shields.io/pypi/v/finac.svg\" /\u003e \u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" /\u003e \u003cimg src=\"https://img.shields.io/badge/python-3.7%20%7C%203.8%20%7C%203.9%20%7C%203.10-blue.svg\" /\u003e\n\nFinac can be used either in the interactive mode with\n[Jupyter](https://jupyter.org/), [Spyder-IDE](https://www.spyder-ide.org/),\nipython or other similar environment or Finac library can be embedded into 3rd\nparty projects. The library can be used in accounting applications and is\nuseful for fin-tech services.\n\nFinac supports multiple currencies, simple transactions, double-entry\nbookkeeping transactions, watches overdrafts, balance limits and has got many\nuseful features, which make accounting simple and fun.\n\n## Install\n\n```bash\npip3 install finac\n```\n\nSources: https://github.com/alttch/finac\n\nDocumentation: https://finac.readthedocs.io/\n\n## Updating\n\n# from 0.4.10\n\n```sql\nALTER TABLE transact ADD service bool;\nUPDATE transact SET service=true WHERE d_created\u003c'1970-01-03';\nALTER TABLE transact ADD FOREIGN KEY(chain_transact_id)\n  REFERENCES transact(id) ON DELETE SET null;\n```\n\n# from 0.3.x\n\nStarting from 0.4, Finac uses DateTime columns for:\n\n* asset_rate.d\n* transact.d\n* transact.d_created\n* transact.deleted\n\nDepending to the database type, it's REQUIRED to convert these columns to\neither DATETIME (SQLite, for MySQL DATETIME(6) recommended) or TIMESTAMPTZ\n(PostgreSQL, with timezone).\n\n## How to use in interactive mode\n\nFinac database contains 3 entity types:\n\n* **asset** currency, ISIN, stock code etc., currencies \"USD\" and \"EUR\" are\n  created automatically. Finac does not separate assets into currencies,\n  property and other. This allows creating applications for various areas using\n  the single library.\n\n* **account** bank account, counterparty account, tax account, special account\n  etc. Everything is accounts :)\n\n* **transaction** movements from (credit) / to (debit) and between accounts\n\nAssets have got **rates** - the value of one asset, relative to other.\n\nTransactions can be simple (no counterparty) or classic double-entry\nbookkeeping (between debit and credit account).\n\n```python\nimport finac as f\n# init finac, \nf.init('/tmp/test.db')\n# create a couple of accounts\nf.account_create('acc1', 'USD')\nf.account_create('acc2', 'USD')\nf.account_create('depo', 'USD', 'saving')\n# import initial balance with a simple transaction\nf.tr('acc1', 10000, tag='import')\n# move some assets to other accounts\nf.mv(dt='acc2', ct='acc1', amount=2000)\nf.mv(dt='depo', ct='acc1', amount=3000)\n```\n\n```python\n# display statement for acc1\nf.ls('acc1')\n```\n\n```\nid     amount  cparty  tag     note  created              completed\n-----------------------------------------------------------------------------\n7   10 000.00          import        2019-10-26 03:04:02  2019-10-26 03:04:02\n8   -2 000.00  ACC2                  2019-10-26 03:04:02  2019-10-26 03:04:02\n9   -3 000.00  DEPO                  2019-10-26 03:04:02  2019-10-26 03:04:02\n-----------------------------------------------------------------------------\nDebit turnover: 10 000.00, credit turnover: 5 000.00\n\nNet profit/loss: 5 000.00 USD\n```\n\n```python\n# display summary for all accounts\nf.ls()\n```\n\n```\naccount  type      asset     balance  balance USD\n-------------------------------------------------\nACC1     current    USD     5 000.00     5 000.00\nACC2     current    USD     2 000.00     2 000.00\nDEPO     saving     USD     3 000.00     3 000.00\n-------------------------------------------------\nTotal: 10 000.00 USD\n```\n\n```python\n# display summary only for current accounts\nf.ls(tp='current')\n```\n\n```\naccount  type     asset     balance   balance USD\n-------------------------------------------------\nACC1     current    USD     5 000.00     5 000.00\nACC2     current    USD     2 000.00     2 000.00\n-------------------------------------------------\nTotal: 7 000.00 USD\n```\n\n```python\n# display assets pie chart, (wrapper for matplotlib.pyplot, requires Jupyter,\n# Spyder-IDE or a similar interactive environment)\nf.pie()\n```\n\u003cimg src=\"https://github.com/alttch/finac/blob/master/doc/images/pie.png?raw=true\" width=\"400\" /\u003e\n\nNote: when addressing currencies and accounts both in interactive and API mode,\naccount and asset codes should be used as object identifiers. **All codes are\ncase-insensitive**.\n\nInside database Finac uses numeric IDs to connect objects, so the codes can be\nchanged without any problems.\n\n## Special features\n\n### Lazy exchange\n\nFinac can automatically move assets between accounts having different\ncurrencies if exchange rate is set or specified in the transaction details:\n\n```python\n# create EUR account\nf.account_create('acc5', 'eur')\n# set exchange rate (in real life you would probably use cron job)\nf.asset_set_rate('eur/usd', value=1.1)\nf.mv(dt='acc5', ct='acc1', amount=100)\n```\n\nhoorah, account acc5 have got 100 EUR! And exchange rate was 1.1. Check it:\n\n    \u003e\u003e\u003e f.ls('acc1')\n\n```\nid     amount  cparty  tag     note  created              completed\n-----------------------------------------------------------------------------\n..............\n..............\n14    -110.00                        2019-10-26 03:15:41  2019-10-26 03:15:41\n-----------------------------------------------------------------------------\n```\n\n    \u003e\u003e\u003e f.ls('acc5')\n\n```\nid  amount  cparty  tag  note  created              completed\n-----------------------------------------------------------------------\n15  100.00                     2019-10-26 03:15:41  2019-10-26 03:15:41\n-----------------------------------------------------------------------\nDebit turnover: 100.00, credit turnover: 0.00\n\nNet profit/loss: 100.00 EUR\n```\n\nAs shown, there is no a counterparty account in the lazy exchange. This feature\nis useful for personal accounting and special applications, but for\nprofessional accounting, create counterparty exchange accounts should be\ncreated and buy-sell transactions should be performed between them.\n\n### Targets\n\nTargets is a feature I have created Finac for. Consider there are account\nbalances in a bank and in the accounting. They differ in some amount and this\nneed to be recorded in the accounting with a single transaction.\n\nBut the problem is: there is a lot of transactions which should be sum up. Or\nthe difference between bank balance and accounting must be calculated manually.\nPretty common, eh? Don't do this, Finac has got targets.\n\nSpecifying targets instead of amount asks Finac to calculate transaction amount\nby itself.\n\nAfter the previous operation, there is *4,890.00* USD on \"acc1\" and consider\nall except $1000 should be moved to \"acc2\". Let us do it:\n\n    \u003e\u003e\u003e f.mv(dt='acc2', ct='acc1', target_ct=1000)\n\n```\nid     amount  cparty  tag     note  created              completed\n-----------------------------------------------------------------------------\n......\n......\n16  -3 890.00  ACC2                  2019-10-26 03:25:56  2019-10-26 03:25:56\n-----------------------------------------------------------------------------\nDebit turnover: 10 000.00, credit turnover: 9 000.00\n\nNet profit/loss: 1 000.00 USD\n\n```\n\nThe transaction amount is automatically calculated. Lazy people are happy :)\n\nIf the debit account balance target should be specified, *target_dt*\nfunction argument can be used. Note: calculated transaction amount must be\nalways greater than zero (if credit account target higher than its current\nbalance is specified, *ValueError* is raised)\n\nFor simple transactions (*f.tr(...))*), use *target=*.\n\n### Transaction templates\n\nExample: there is a repeating payment orders in a bank, which pay office\nutility bills every 5th day of month, plus automatically move $100 to a saving\naccount. To fill this into accounting, YAML transaction template can be\nused:\n\n```yaml\ntransactions:\n  - account: acc1\n    amount: 200\n    tag: electricity\n    note: energy company deposit\n  - account: acc1\n    amount: 800\n    tag: rent\n    note: office rent\n  - dt: depo\n    ct: acc1\n    amount: 200\n    tag: savings\n    note: rainy day savings\n```\n\nthen create a cron job which calls *f.transaction_apply(\"/path/to/file.yml\")*\nand that is it.\n\nActually, transaction templates are useful for any repeating operations. The\nsame arguments, as for the core functions, can be specified.\n\n### Number formatting\n\nFinac does not use system locale. If amounts and targets are inputted as\nstrings, they can be specified in any format and Finac tries converting strings\ninto float numeric automatically. The following values for amounts and\ntargets are valid and are automatically parsed:\n\n* 1 000,00 = 1000.0\n* 1,000.00 = 1000.0\n* 1.000,00 = 1000.0\n* 1,000.00 = 1000.0\n* 10,0 = 10.0\n* 10.0 = 10.0\n\n### Passive accounts\n\nIf account is passive, its assets are decremented from totals. To create\npassive account, *passive* argument must be used:\n\n```python\nf.account_create('passive1', 'usd', passive=True)\n```\n\nAccounts of types \"tax\", \"supplier\" and \"finagent\" are passive by default.\n\n### Data multiplier\n\nDepending on data, it may be useful to store numeric values in the database as\nintegers instead of floats. Finac library has got a built-in data multiplier\nfeature. To enable it, set *multiplier=N* in *finac.init()* method, e.g.\n*multiplier=1000*. This makes Finac to store integers into tables and use the\nmax precision of 3 digits after comma.\n\nNote: table fields must be manually converted to numeric/integer types. In \nproduction databases the field values must be also manually multiplied.\n\nFull list of tables and fields, required to be converted, is available in the\ndict *finac.core.multiply_fields*.\n\nNote: the multiplier can be used only with integer and numeric(X) field types,\nas core conversion functions always return rounded value.\n\n## How to embed Finac library into own project\n\nSee [Finac documentation](https://finac.readthedocs.io/) for core function API\ndetails.\n\n## Client-server mode and HTTP API\n\nSee [Finac documentation](https://finac.readthedocs.io/) for server mode and\nHTTP API details.\n\n## Enterprise server and support\n\nWant to integrate Finac into an own enterprise app or service? Need a support?\nCheck [Finac Enterprise Server](https://www.altertech.com/products/fes/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falttch%2Ffinac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falttch%2Ffinac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falttch%2Ffinac/lists"}