# Beancount DKB Importer
[](https://pypi.python.org/pypi/beancount-dkb)
[](https://pypi.python.org/pypi/beancount-dkb)
[](https://pepy.tech/project/beancount-dkb)
[](https://github.com/astral-sh/ruff)
`beancount-dkb` provides importers for converting CSV exports of [DKB] (Deutsche
Kreditbank) account summaries to the [Beancount] format.
## Installation
```sh
$ 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.
Note that v1.x will *only* work with Beancount 3.x, while v0.x will *only* work with
Beancount 2.x, due to incompatibilities between Beancount 3.x and 2.x.
## 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]. As a result, the importer's
initialization parameters have been shifted to `pyproject.toml`.
Add the following to your `pyproject.toml` in your project root.
```toml
[tool.beancount-dkb.ec]
iban = "DE99 9999 9999 9999 9999 99"
account_name = "Assets:DKB:EC"
currency = "EUR"
[tool.beancount-dkb.credit]
card_number = "9999 9999 9999 9999"
account_name = "Assets:DKB:Credit"
currency = "EUR"
```
Run `beancount-dkb-ec` or `beancount-dkb-credit` to call the importer. The `identify`
and `extract` subcommands would identify the file and extract transactions for you.
```sh
$ beancount-dkb-ec extract transaction.csv >> you.beancount
$ beancount-dkb-credit extract transaction.csv >> you.beancount
```
### 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`.
```python
from beancount_dkb import ECImporter, CreditImporter
IBAN_NUMBER = 'DE99 9999 9999 9999 9999 99' # your real IBAN number
CARD_NUMBER = '9999 9999 9999 9999' # your real Credit Card number
CONFIG = [
ECImporter(
IBAN_NUMBER,
'Assets:DKB:EC',
currency='EUR',
),
CreditImporter(
CARD_NUMBER,
'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.
```sh
$ bean-extract /path/to/config.py transaction.csv >> you.beancount
```
### 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 to the `ECImporter` initializer.
#### Beancount 3.x
```toml
[tool.beancount-dkb.ec]
iban = "DE99 9999 9999 9999 9999 99"
account_name = "Assets:DKB:EC"
meta_code = "code"
```
#### Beancount 2.x
```python
...
CONFIG = [
ECImporter(
IBAN_NUMBER,
'Assets:DKB:EC',
currency='EUR',
meta_code='code',
),
...
```
This is how an example transaction looks without the option:
```beancount
2021-03-01 * "Kartenzahlung" "XY Supermarket"
Assets:DKB:EC -133.72 EUR
```
And this is the resulting transaction using `meta_code='code'`
```beancount
2021-03-01 * "XY Supermarket"
code: Kartenzahlung
Assets:DKB:EC -133.72 EUR
```
### 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 or the description 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 lits of transactions.
#### `ECImporter`
`ECImporter` accepts `payee_patterns` and `description_patterns` arguments, which should
be a list of `(pattern, account)` tuples.
##### Beancount 3.x
```toml
[tool.beancount-dkb.ec]
iban = "DE99 9999 9999 9999 9999 99"
account_name = "Assets:DKB:EC"
payee_patterns = [
["REWE", "Expenses:Supermarket:REWE"],
["NETFLIX", "Expenses:Online:Netflix"],
]
```
##### Beancount 2.x
```python
CONFIG = [
ECImporter(
IBAN_NUMBER,
'Assets:DKB:EC',
currency='EUR',
payee_patterns=[
('REWE', 'Expenses:Supermarket:REWE'),
('NETFLIX', 'Expenses:Online:Netflix'),
],
),
```
#### `CreditImporter`
`CreditImporter` accepts a `description_patterns` argument, which should be a list of
`(pattern, account)` tuples.
##### Beancount 3.x
```toml
[tool.beancount-dkb.credit]
card_number = "9999 9999 9999 9999"
account_name = "Assets:DKB:Credit"
currency = "EUR"
description_patterns=[
['REWE', 'Expenses:Supermarket:REWE'],
['NETFLIX', 'Expenses:Online:Netflix'],
]
```
##### Beancount 2.x
```python
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.8+ 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`.
[Beancount]: http://furius.ca/beancount/
[DKB]: https://www.dkb.de
[Poetry]: https://python-poetry.org/
[changes documented here]: https://docs.google.com/document/d/1O42HgYQBQEna6YpobTqszSgTGnbRX7RdjmzR2xumfjs/edit#heading=h.hjzt0c6v8pfs
[config file]: https://beancount.github.io/docs/importing_external_data.html#configuration
[this guide]: https://beancount.github.io/docs/importing_external_data.html
Raw data
{
"_id": null,
"home_page": "https://github.com/siddhantgoel/beancount-dkb",
"name": "beancount-dkb",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "banking, beancount, cli-accounting, finance",
"author": "Siddhant Goel",
"author_email": "me@sgoel.dev",
"download_url": "https://files.pythonhosted.org/packages/af/58/b54db2cde289737a9aa4cb03e811c329425647c03af3a787493f633c695a/beancount_dkb-1.4.0.tar.gz",
"platform": null,
"description": "# Beancount DKB Importer\n\n[](https://pypi.python.org/pypi/beancount-dkb)\n[](https://pypi.python.org/pypi/beancount-dkb)\n[](https://pepy.tech/project/beancount-dkb)\n[](https://github.com/astral-sh/ruff)\n\n`beancount-dkb` provides importers for converting CSV exports of [DKB] (Deutsche\nKreditbank) account summaries to the [Beancount] format.\n\n## Installation\n\n```sh\n$ pip install beancount-dkb\n```\n\nIn case you prefer installing from the Github repository, please note that `main` is the\ndevelopment branch so `stable` is what you should be installing from.\n\nNote that v1.x will *only* work with Beancount 3.x, while v0.x will *only* work with\nBeancount 2.x, due to incompatibilities between Beancount 3.x and 2.x.\n\n## Usage\n\nIf you're not familiar with how to import external data into Beancount, please read\n[this guide] first.\n\n### Beancount 3.x\n\nBeancount 3.x has replaced the `config.py` file based workflow in favor of having a\nscript based workflow, as per the [changes documented here]. As a result, the importer's\ninitialization parameters have been shifted to `pyproject.toml`.\n\nAdd the following to your `pyproject.toml` in your project root.\n\n```toml\n[tool.beancount-dkb.ec]\niban = \"DE99 9999 9999 9999 9999 99\"\naccount_name = \"Assets:DKB:EC\"\ncurrency = \"EUR\"\n\n[tool.beancount-dkb.credit]\ncard_number = \"9999 9999 9999 9999\"\naccount_name = \"Assets:DKB:Credit\"\ncurrency = \"EUR\"\n```\n\nRun `beancount-dkb-ec` or `beancount-dkb-credit` to call the importer. The `identify`\nand `extract` subcommands would identify the file and extract transactions for you.\n\n```sh\n$ beancount-dkb-ec extract transaction.csv >> you.beancount\n$ beancount-dkb-credit extract transaction.csv >> you.beancount\n```\n\n### Beancount 2.x\n\nAdjust your [config file] to include `ECImporter` and `CreditImporter`\n(depending on what account you're trying to import).\n\nAdd the following to your `config.py`.\n\n```python\nfrom beancount_dkb import ECImporter, CreditImporter\n\nIBAN_NUMBER = 'DE99 9999 9999 9999 9999 99' # your real IBAN number\n\nCARD_NUMBER = '9999 9999 9999 9999' # your real Credit Card number\n\nCONFIG = [\n ECImporter(\n IBAN_NUMBER,\n 'Assets:DKB:EC',\n currency='EUR',\n ),\n\n CreditImporter(\n CARD_NUMBER,\n 'Assets:DKB:Credit',\n currency='EUR',\n )\n]\n```\n\nOnce this is in place, you should be able to run `bean-extract` on the command\nline to extract the transactions and pipe all of them into your Beancount file.\n\n```sh\n$ bean-extract /path/to/config.py transaction.csv >> you.beancount\n```\n\n### Transaction Codes as Meta Tags\n\nBy default, the ECImporter prepends the transaction code (\"Buchungstext\") to the\ntransaction description. To achieve shorter descriptions and use meta tags to query for\ncertain transaction codes, the importer may be configured to store the transaction code\nin a user provided meta tag.\n\nAdd the `meta_code` parameter to the `ECImporter` initializer.\n\n#### Beancount 3.x\n\n```toml\n[tool.beancount-dkb.ec]\niban = \"DE99 9999 9999 9999 9999 99\"\naccount_name = \"Assets:DKB:EC\"\nmeta_code = \"code\"\n```\n\n#### Beancount 2.x\n\n```python\n...\nCONFIG = [\n ECImporter(\n IBAN_NUMBER,\n 'Assets:DKB:EC',\n currency='EUR',\n meta_code='code',\n ),\n...\n\n```\n\nThis is how an example transaction looks without the option:\n\n```beancount\n2021-03-01 * \"Kartenzahlung\" \"XY Supermarket\"\n Assets:DKB:EC -133.72 EUR\n```\n\nAnd this is the resulting transaction using `meta_code='code'`\n\n```beancount\n2021-03-01 * \"XY Supermarket\"\n code: Kartenzahlung\n Assets:DKB:EC -133.72 EUR\n```\n\n### Pattern-matching Transactions\n\nIt's possible to give the importer classes hints if you'd like them to include a\nsecond posting based on specific characteristics of the original transaction.\n\nFor instance, if the payee or the description in a transaction always matches a\ncertain value, it's possible to tell the `ECImporter` or `CreditImporter` to\nautomatically place a second posting in the returned lits of transactions.\n\n#### `ECImporter`\n\n`ECImporter` accepts `payee_patterns` and `description_patterns` arguments, which should\nbe a list of `(pattern, account)` tuples.\n\n##### Beancount 3.x\n\n```toml\n[tool.beancount-dkb.ec]\niban = \"DE99 9999 9999 9999 9999 99\"\naccount_name = \"Assets:DKB:EC\"\npayee_patterns = [\n [\"REWE\", \"Expenses:Supermarket:REWE\"],\n [\"NETFLIX\", \"Expenses:Online:Netflix\"],\n]\n```\n\n##### Beancount 2.x\n\n```python\nCONFIG = [\n ECImporter(\n IBAN_NUMBER,\n 'Assets:DKB:EC',\n currency='EUR',\n payee_patterns=[\n ('REWE', 'Expenses:Supermarket:REWE'),\n ('NETFLIX', 'Expenses:Online:Netflix'),\n ],\n ),\n```\n\n#### `CreditImporter`\n\n`CreditImporter` accepts a `description_patterns` argument, which should be a list of\n`(pattern, account)` tuples.\n\n##### Beancount 3.x\n\n```toml\n[tool.beancount-dkb.credit]\ncard_number = \"9999 9999 9999 9999\"\naccount_name = \"Assets:DKB:Credit\"\ncurrency = \"EUR\"\ndescription_patterns=[\n ['REWE', 'Expenses:Supermarket:REWE'],\n ['NETFLIX', 'Expenses:Online:Netflix'],\n]\n```\n\n##### Beancount 2.x\n\n```python\nCONFIG = [\n CreditImporter(\n CARD_NUMBER,\n 'Assets:DKB:Credit',\n currency='EUR',\n description_patterns=[\n ('REWE', 'Expenses:Supermarket:REWE'),\n ('NETFLIX', 'Expenses:Online:Netflix'),\n ],\n )\n```\n\n## Contributing\n\nContributions are most welcome!\n\nPlease make sure you have Python 3.8+ and [Poetry] installed.\n\n1. Clone the repository: `git clone https://github.com/siddhantgoel/beancount-dkb`\n2. Install the packages required for development: `poetry install`\n3. That's basically it. You should now be able to run the test suite: `poetry run task test`.\n\n[Beancount]: http://furius.ca/beancount/\n[DKB]: https://www.dkb.de\n[Poetry]: https://python-poetry.org/\n[changes documented here]: https://docs.google.com/document/d/1O42HgYQBQEna6YpobTqszSgTGnbRX7RdjmzR2xumfjs/edit#heading=h.hjzt0c6v8pfs\n[config file]: https://beancount.github.io/docs/importing_external_data.html#configuration\n[this guide]: https://beancount.github.io/docs/importing_external_data.html\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Beancount Importer for DKB CSV exports",
"version": "1.4.0",
"project_urls": {
"Homepage": "https://github.com/siddhantgoel/beancount-dkb",
"Repository": "https://github.com/siddhantgoel/beancount-dkb"
},
"split_keywords": [
"banking",
" beancount",
" cli-accounting",
" finance"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3cfe8604745cc2c4d7389ed2b393a6587e4c5c034d9414b88002718d2a168174",
"md5": "bb099237fcf87432efe2ccceeb2e1c91",
"sha256": "3ccb3721bc3ac541c94ff6df5ee06045d4dec426248b282d23cbec123bc23588"
},
"downloads": -1,
"filename": "beancount_dkb-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bb099237fcf87432efe2ccceeb2e1c91",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 17510,
"upload_time": "2024-11-16T15:56:07",
"upload_time_iso_8601": "2024-11-16T15:56:07.235707Z",
"url": "https://files.pythonhosted.org/packages/3c/fe/8604745cc2c4d7389ed2b393a6587e4c5c034d9414b88002718d2a168174/beancount_dkb-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "af58b54db2cde289737a9aa4cb03e811c329425647c03af3a787493f633c695a",
"md5": "dd70f106bbb374e1f3e2a3baf293b12f",
"sha256": "388d46db677ab9bcff64550259ad55c783091e2cff7bd6e472b842ec16781669"
},
"downloads": -1,
"filename": "beancount_dkb-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "dd70f106bbb374e1f3e2a3baf293b12f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 11974,
"upload_time": "2024-11-16T15:56:08",
"upload_time_iso_8601": "2024-11-16T15:56:08.439896Z",
"url": "https://files.pythonhosted.org/packages/af/58/b54db2cde289737a9aa4cb03e811c329425647c03af3a787493f633c695a/beancount_dkb-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-16 15:56:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "siddhantgoel",
"github_project": "beancount-dkb",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "beancount-dkb"
}
JSON
