bdantic 0.2.6

A package for extending beancount with pydantic

bdantic

A package for extending beancount with pydantic

See the docs for more details.

Installation

pip install bdantic

Usage

Parsing

A handful of functions are provided for parsing Beancount types, but the primary method supports parsing most core types:

import bdantic

from beancount.core import amount
from decimal import Decimal

amt = amount.Amount(number=Decimal(1.50), currency="USD"))
model = bdantic.parse(amt) # Produces a bdantic.models.Amount

Exporting

All models can be directly exported back to their native Beancount types by using their bult-in export method:

amt_export = model.export()
assert amt == amt_export

Ingesting

Functions are available for parsing common responses from interacting with the Beancount package. You can parse an entire Beancount file with the following:

import bdantic

from beancount import loader

# A bdantic.models.BeancountFile instance
bfile = bdantic.parse_loader(*loader.load_file("ledger.beancount"))
print(len(bfile.entries))

You can also parse the response from executing a query:

import bdantic

from beancount import loader
from beancount.query import query

entries, _, options = loader.load_file("ledger.beancount")

query = "SELECT date, narration, account, position"
result = query.run_query(entries, options, query)
parsed_result = bdantic.parse_query(result)

Or the result of running a realization:

import bdantic

from beancount.core import realization

entries, _, options = loader.load_file("ledger.beancount")

real = realization.realize(entries)
parsed_real = bdantic.parse(real)

Rendering

Perhaps the most powerful usage of bdantic is rendering beancount data into a more universal format like JSON. Since all models inherit from Pydantic they include full support for rendering their contents as JSON:

import bdantic

from beancount import loader

bfile = bdantic.parse_loader(*loader.load_file("ledger.beancount"))
js = bfile.json()
print(js) # Look ma, my beancount data in JSON!

The rendered JSON can be parsed back into the Beancount model that generated it:

from bdantic.models import BeancountFile

bfile = BeancountFile.parse_raw(js)

In additiona to JSON, the directive models can be rendered as valid Beancount syntax using the built-in syntax method:

from bdantic.models import Amount, Posting, Transaction
from datetime import date
from decimal import Decimal

txn = Transaction(
    date=date.today(),
    meta={},
    flag="*",
    payee="Home Depot",
    narration="Tools n stuff",
    tags=None,
    links=None,
    postings=[
        Posting(
            account="Assets:Bank:Cash",
            units=Amount(number=Decimal(-142.32), currency="USD"),
            cost=None,
            CostSpec=None,
            flag=None,
            meta={},
        ),
        Posting(
            account="Expenses:HomeDepot",
            units=Amount(number=Decimal(142.32), currency="USD"),
            cost=None,
            CostSpec=None,
            flag=None,
            meta={},
        ),
    ],
)

print(txn.syntax())

Testing

pytest .

Most tests make heavy use of hypothesis for generating test data to be used in the tests. Hypothesis automatically keeps a cache to speed up subsequent testing, however, the first time you run pytest you may experience longer than normal run times.

Additionally, many tests pull from the static.beancount file found in the testing folder. This was generated using the bean-example CLI tool and is used to verify models with a realistic ledger.

Contributing

Check out the issues for items needing attention or submit your own and then:

1. Fork the repo
2. Create your feature branch (git checkout -b feature/fooBar)
3. Commit your changes (git commit -am 'Add some fooBar')
4. Push to the branch (git push origin feature/fooBar)
5. Create a new Pull Request