Beancount DKB Importer

beancount-dkb provides importers for converting CSV exports of DKB (Deutsche Kreditbank) account summaries to the Beancount format.

Installation

$ pip install beancount-dkb

In case you prefer installing from the Github repository, please note that main is the development branch so stable is what you should be installing from.

Usage

If you're not familiar with how to import external data into Beancount, please read this guide first.

Beancount 3.x

Beancount 3.x has replaced the config.py file based workflow in favor of having a script based workflow, as per the changes documented here. The beangulp examples suggest using a Python script based on beangulp.Ingest. Here's an example of how that might work:

Add an import.py script in your project root with the following contents:

from beancount_dkb import ECImporter, CreditImporter
from beangulp import Ingest

importers = (
    ECImporter(
        "DE99 9999 9999 9999 9999 99",
        'Assets:DKB:EC',
        currency='EUR',
    ),

    CreditImporter(
        "9999 9999 9999 9999",
        'Assets:DKB:Credit',
        currency='EUR',
    ),
)

if __name__ == "__main__":
    ingest = Ingest(importers)
    ingest()

... and run it directly using python import.py extract.

Beancount 2.x

Adjust your config file to include ECImporter and CreditImporter (depending on what account you're trying to import).

Add the following to your config.py.

from beancount_dkb import ECImporter, CreditImporter

CONFIG = [
    ECImporter(
        "DE99 9999 9999 9999 9999 99",
        "Assets:DKB:EC",
        currency='EUR',
    ),

    CreditImporter(
        "9999 9999 9999 9999",
        "Assets:DKB:Credit",
        currency='EUR',
    ),
]

Once this is in place, you should be able to run bean-extract on the command line to extract the transactions and pipe all of them into your Beancount file.

$ bean-extract /path/to/config.py transaction.csv >> you.beancount

Ignoring Credit Card Settlement Transactions

DKB credit card CSV exports may contain settlement transactions such as Ausgleich Kreditkarte. If these settlements are already imported through the EC account, configure the CreditImporter to ignore and skip them during import.

Beancount 3.x

from beancount_dkb import CreditImporter
from beangulp import Ingest

importers = (
    CreditImporter(
        "9999 9999 9999 9999",
        "Assets:DKB:Credit",
        ignore_credit_card_settlements=True,
    ),
)

if __name__ == "__main__":
    ingest = Ingest(importers)
    ingest()

Beancount 2.x

CONFIG = [
    CreditImporter(
        CARD_NUMBER,
        'Assets:DKB:Credit',
        ignore_credit_card_settlements=True,
    )
]

Transaction Codes as Meta Tags

By default, the ECImporter prepends the transaction code ("Buchungstext") to the transaction description. To achieve shorter descriptions and use meta tags to query for certain transaction codes, the importer may be configured to store the transaction code in a user provided meta tag.

Add the meta_code parameter when instantiating an ECImporter.

Beancount 3.x

from beancount_dkb import ECImporter
from beangulp import Ingest

importers = (
    ECImporter(
        "DE99 9999 9999 9999 9999 99",
        "Assets:DKB:EC",
        meta_code="code',
    ),
)

if __name__ == "__main__":
    ingest = Ingest(importers)
    ingest()

Beancount 2.x

...
CONFIG = [
    ECImporter(
        IBAN_NUMBER,
        'Assets:DKB:EC',
        currency='EUR',
        meta_code='code',
    ),
...

This is how an example transaction looks without the option:

2021-03-01 * "Kartenzahlung" "XY Supermarket"
    Assets:DKB:EC                        -133.72 EUR

And this is the resulting transaction using meta_code='code'

2021-03-01 * "XY Supermarket"
    code: Kartenzahlung
    Assets:DKB:EC                        -133.72 EUR

Payee Address Spacing

Some DKB EC exports append an address to the payee with a long run of filler spaces. ECImporter keeps payees unchanged by default, but can collapse those space runs to a single space when configured with normalize_payee_address_spacing=True.

ECImporter(
    IBAN_NUMBER,
    "Assets:DKB:EC",
    normalize_payee_address_spacing=True,
)

Pattern-matching Transactions

It's possible to give the importer classes hints if you'd like them to include a second posting based on specific characteristics of the original transaction.

For instance, if the payee, description, or counterparty IBAN in a transaction always matches a certain value, it's possible to tell the ECImporter or CreditImporter to automatically place a second posting in the returned list of transactions.

ECImporter

ECImporter accepts payee_patterns and description_patterns arguments, which should be a list of (pattern, account) tuples. The pattern is compiled using re.compile, so feel free to use regular expressions there.

ECImporter also accepts an iban_matcher argument, which should be a list of (iban, account) tuples. The IBAN is normalized by removing whitespace and uppercasing before being compared exactly against the counterparty IBAN field in current DKB EC exports. iban_matcher is not available for legacy exports (before 2023). So, it is ignored for those files.

Beancount 3.x

from beancount_dkb import ECImporter
from beangulp import Ingest

importers = (
    ECImporter(
        "DE99 9999 9999 9999 9999 99",
        "Assets:DKB:EC",
        payee_patterns=[
            ("REWE", "Expenses:Supermarket:REWE"),
            (r"N*TFL*X", "Expenses:Online:Netflix"),
        ],
        iban_matcher=[
            ("DE88 8888 8888 8888 8888 88", "Assets:Bank:HYSA"),
        ],
    ),
)

if __name__ == "__main__":
    ingest = Ingest(importers)
    ingest()

Beancount 2.x

CONFIG = [
    ECImporter(
        IBAN_NUMBER,
        "Assets:DKB:EC",
        currency='EUR',
        payee_patterns=[
            ("REWE", "Expenses:Supermarket:REWE"),
            ("NETFLIX", "Expenses:Online:Netflix"),
        ],
        iban_matcher=[
            ("DE88 8888 8888 8888 8888 88", "Assets:Bank:HYSA"),
        ],
    ),

CreditImporter

CreditImporter accepts a description_patterns argument, which should be a list of (pattern, account) tuples.

Beancount 3.x

from beancount_dkb import CreditImporter
from beangulp import Ingest

importers = (
    ECImporter(
        "9999 9999 9999 9999",
        "Assets:DKB:EC",
        currency="EUR",
        payee_patterns=[
            ("REWE", "Expenses:Supermarket:REWE"),
            ("NETFLIX", "Expenses:Online:Netflix"),
        ],
    ),
)

if __name__ == "__main__":
    ingest = Ingest(importers)
    ingest()

Beancount 2.x

CONFIG = [
    CreditImporter(
        CARD_NUMBER,
        'Assets:DKB:Credit',
        currency='EUR',
        description_patterns=[
            ('REWE', 'Expenses:Supermarket:REWE'),
            ('NETFLIX', 'Expenses:Online:Netflix'),
        ],
    )

Contributing

Contributions are most welcome!

Please make sure you have Python 3.10+ and Poetry installed.

1. Clone the repository: git clone https://github.com/siddhantgoel/beancount-dkb
2. Install the packages required for development: poetry install
3. That's basically it. You should now be able to run the test suite: poetry run task test.