From ad2824485286f0d6ec949d0348b3ee10b72148dc Mon Sep 17 00:00:00 2001 From: RunasSudo Date: Tue, 31 Mar 2020 16:26:26 +1100 Subject: [PATCH] Update documentation --- .gitignore | 1 + README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++ config.example.yml | 2 +- demo/config.yml | 21 ++++++++++++++++++++ demo/ledger.journal | 36 ++++++++++++++++++++++++++++++++++ requirements.txt | 7 +++++++ 6 files changed, 113 insertions(+), 1 deletion(-) create mode 100644 README.md create mode 100644 demo/config.yml create mode 100644 demo/ledger.journal create mode 100644 requirements.txt diff --git a/.gitignore b/.gitignore index b0a1c70..781f7b4 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ __pycache__ /config.yml +/venv diff --git a/README.md b/README.md new file mode 100644 index 0000000..cd77acb --- /dev/null +++ b/README.md @@ -0,0 +1,47 @@ +# ledger-pyreport + +ledger-pyreport is a lightweight Flask webapp for generating interactive and printable accounting reports from [ledger-cli](https://www.ledger-cli.org/) data. + +## Reports + +* Trial balance, and comparative trial balance +* Balance sheet, and comparative balance sheet +* Income statement, and comparative income statement +* General ledger +* Account transactions, with or without itemisation of commodities +* Transaction detail, with or without itemisation of commodities + +## Features + +* Correctly values assets/liabilities at market value, and income/expenses at cost (pursuant to [AASB 121](https://www.aasb.gov.au/admin/file/content105/c9/AASB121_08-15_COMPfeb16_01-19.pdf)/[IAS 21](https://www.ifrs.org/issued-standards/list-of-standards/ias-21-the-effects-of-changes-in-foreign-exchange-rates/) para 39) +* Correctly computes unrealised gains ([even when Ledger does not](https://yingtongli.me/blog/2020/03/31/ledger-gains.html)) +* Simulates annual closing of books, with presentation of income/expenses on the balance sheet as retained earnings and current year earnings +* Can simulate cash basis accounting, using FIFO methodology to recode transactions involving liabilities and non-cash assets + +## Background, demo and screenshots + +See [https://yingtongli.me/blog/2020/03/31/ledger-pyreport.html](https://yingtongli.me/blog/2020/03/31/ledger-pyreport.html) for further discussion. + +## Usage + +Install the dependencies from PyPI, optionally in a virtual environment: (Commands presented for Linux/Mac) + +``` +virtualenv venv +. venv/bin/activate +pip install -r requirements.txt +``` + +Copy *config.example.yml* to *config.yml* (or set the *LEDGER_PYREPORT_CONFIG* environment variable to the path to the config file). + +Run as per a usual Flask app, for example: + +``` +FLASK_APP=ledger_pyreport python -m flask run +``` + +## Notes on Ledger setup + +ledger-pyreport expects each of assets, liabilities, equity, income and expenses to be setup in Ledger as a separate top-level account. These accounts should contain a zero balance, with all transactions in child accounts. + +Additionally, ledger-pyreport expects the next level of assets and liabilities to be categories of asset and liability (e.g. *Assets:Current*, *Liabilities:Non-current*). These, too, should contain a zero balance. diff --git a/config.example.yml b/config.example.yml index f7293a9..a4df044 100644 --- a/config.example.yml +++ b/config.example.yml @@ -16,6 +16,6 @@ retained_earnings: 'Equity:Retained Earnings' current_year_earnings: 'Equity:Current Year Earnings' # Which asset accounts to consider in cash basis mode -cash_asset_accounts: ['Assets:Cash on Hand', 'Assets:Cash at Bank'] +cash_asset_accounts: ['Assets:Current:Cash on Hand', 'Assets:Current:Cash at Bank'] # Which account to charge non-cash transactions to in cash basis mode, when no other account is suitable cash_other_income: 'Income:Other Income' diff --git a/demo/config.yml b/demo/config.yml new file mode 100644 index 0000000..41ebf23 --- /dev/null +++ b/demo/config.yml @@ -0,0 +1,21 @@ +# Set up how we will call Ledger +ledger_file: demo/ledger.journal +ledger_args: [] +report_currency: ['$', True] # True if prefix, False if suffix + +# Tell ledger-pyreport about the top-level account categories +assets_account: Assets +liabilities_account: Liabilities +equity_account: Equity +income_account: Income +expenses_account: Expenses + +# These accounts will automatically be populated on reports +unrealized_gains: 'Equity:Unrealized Gains' +retained_earnings: 'Equity:Retained Earnings' +current_year_earnings: 'Equity:Current Year Earnings' + +# Which asset accounts to consider in cash basis mode +cash_asset_accounts: ['Assets:Current:Cash on Hand', 'Assets:Current:Cash at Bank', 'Assets:Current:International Account'] +# Which account to charge non-cash transactions to in cash basis mode, when no other account is suitable +cash_other_income: 'Income:Other Income' diff --git a/demo/ledger.journal b/demo/ledger.journal new file mode 100644 index 0000000..9bc470a --- /dev/null +++ b/demo/ledger.journal @@ -0,0 +1,36 @@ +2019-06-30 Conversion balances + Assets:Current:Cash at Bank $1000.00 + Assets:Current:Cash on Hand $50.00 + Assets:Non-current:Plant $5000.00 + Equity:Retained Earnings + +2019-07-01 Loan + Assets:Current:Cash at Bank $500.00 + Liabilities:Non-current:Personal Loan + +2019-07-02 Application + Assets:Current:International Account 100.00 EUR @ $1.10 + Assets:Current:Cash at Bank + +2019-08-01 Interest on personal loan + Expenses:Interest $100.00 + Liabilities:Non-current:Personal Loan + +2019-08-02 Application + Assets:Current:International Account 100.00 EUR @ $1.05 + Assets:Current:Cash at Bank + +2019-09-01 Paycheck + Assets:Current:Cash at Bank $200.00 + Income:Wages + +2019-09-02 Redemption + Assets:Current:Cash at Bank $57.50 + Assets:Current:International Account -50.00 EUR {$1.10} @ $1.15 + Income:Capital Gains + +2019-10-01 Depreciation + Expenses:Depreciation $500.00 + Assets:Non-current:Plant:Less Accumulated Depreciation + +P 2019-10-01 00:00:00 EUR $1.30 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..ad9abea --- /dev/null +++ b/requirements.txt @@ -0,0 +1,7 @@ +click==7.1.1 +Flask==1.1.1 +itsdangerous==1.1.0 +Jinja2==2.11.1 +MarkupSafe==1.1.1 +PyYAML==5.3.1 +Werkzeug==1.0.0