{"id":18606826,"url":"https://github.com/felgru/bank-statement-parser","last_synced_at":"2025-04-10T20:32:05.390Z","repository":{"id":54048343,"uuid":"219305531","full_name":"felgru/bank-statement-parser","owner":"felgru","description":"scripts to import bank statement PDFs into hledger files","archived":false,"fork":false,"pushed_at":"2024-09-06T14:54:16.000Z","size":702,"stargazers_count":14,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-09-06T17:41:16.035Z","etag":null,"topics":["accounting","finance","hledger","ledger","plaintext-accounting"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/felgru.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSES/CC0-1.0.txt","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-11-03T13:31:43.000Z","updated_at":"2024-09-06T14:54:19.000Z","dependencies_parsed_at":"2023-12-21T12:07:53.904Z","dependency_job_id":"5fb6e35d-881e-4254-8bab-5f39ad6d4b79","html_url":"https://github.com/felgru/bank-statement-parser","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felgru%2Fbank-statement-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felgru%2Fbank-statement-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felgru%2Fbank-statement-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felgru%2Fbank-statement-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/felgru","download_url":"https://codeload.github.com/felgru/bank-statement-parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223445953,"owners_count":17146384,"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","finance","hledger","ledger","plaintext-accounting"],"created_at":"2024-11-07T02:27:13.316Z","updated_at":"2024-11-07T02:27:13.892Z","avatar_url":"https://github.com/felgru.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: 2019–2022 Felix Gruber \u003cfelgru@posteo.net\u003e\n\nSPDX-License-Identifier: GPL-3.0-or-later\n--\u003e\n\n# Bank Statement Parser\n\n\u003e scripts to import bank statement PDFs into hledger files\n\nSupported banks:\n\n* ABN AMRO\n* BNP Paribas\n* ING.de\n* ING.fr\n* Mercedes-Benz Bank\n* VTB Direktbank\n\nNot actual banks, but bank statement-like files:\n\n* PayPal csv reports\n\nPayslips:\n\n* PayFit\n* Bouygues Télécom\n* Thermo Fisher Scientific\n\n## Usage\n\nTo parse a single bank statement PDF you can use the `parse-bank-statement.py`\nscript. For bulk imports you can use the `import-bank-statements.py` script\nthat tries to parse all bank statements found in\n`\u003cincoming_dir\u003e/\u003cname_of_bank\u003e`. For each bank statement file it creates a\ncorresponding hledger file in one of multiple configurable ledger directories.\n\nThose directories can be changed in the configuration file\n`$XDG_CONFIG_HOME/bank-statement-parser/import.cfg` (where `$XDG_CONFIG_HOME`\ndefaults to `$HOME/.config` if unset). The default `\u003cincoming_directory\u003e` is\n`~/accounting/incoming` and can be set via the `incoming_dir` key in the\n`common` section. Ledger directories can be configured by adding a new section\nwith a `ledger_dir` entry.\n\nHere's an example configuration file with one ledger dir at\n`~/accounting/bank_statements`:\n```\n[common]\nincoming_dir = ~/accounting/incoming\n\n[my bank statements]\nledger_dir = ~/accounting/bank_statements\n```\nIf you have more than one ledger config section in your `import.cfg`, you have\nto have a file `$XDG_CONFIG_HOME/bank-statement-parser/select_ledger.py` that\ncontains a function\n```python\ndef select_ledger(metadata: BankStatementMetadata) -\u003e str:\n    ...\n```\nthat maps the metadata of a bank statement (normally containing IBAN, account\nowner and other identifying data) to a section name from your `import.cfg`.\n\nThe abovementionned scripts are compatible with Python 3.9 or later.\nTo parse PDF files the bank statement parser uses `pdftotext`, which in Debian\nis part of the `poppler-utils` package.\n\n## Configuration of automatic account mappings\n\nThe transactions on bank statements parsed by the scripts\n`parse-bank-statment.py` and `import-bank-statement.py` can be automatically\ncleaned up (e.g. to prettify the subject line) and assigned to the right\naccounts.\n\nTo this end, the scripts optionally read two Python files and a config file\ncontaining account names from the directory `\u003cledger_dir\u003e/rules/\u003cname_of_bank\u003e`.\n\n### Configuration of built-in account names\n\nAll parsers contain a `dict` with account names, containing, e.g. the\nname of the account corresponding to the bank account of a bank statement\nor certain recurring external accounts, e.g. for banking fees or interests.\n\nThe default accounts can be found the `DEFAULT_ACCOUNTS` attribute of each\nparser's config type. They can be customized by specifying alternative\naccount names in the config file\n`\u003cledger_dir\u003e/rules/\u003cname_of_bank\u003e/accounts.cfg`. This file is an ini file\nthat has to contain an `[accounts]` section which contains the customized\naccount names. Any unspecified account names fall back to the ones defined in\n`DEFAULT_ACCOUNTS`.\n\n### Transaction cleaning rules\n\nThe first Python file is `cleaning_rules.py`, which has to contain a variable\n`rules` containing a list of `Rule`s that are applied one after one to each\ntransaction on the bank statement. `Rule`, here, is a class that is implicitly\nimported into `cleaning_rules.py`. You can create a `Rule` as\n`Rule(predicate, clean)` where `predicate` is a function taking a\n`Transaction` as its argument an returning a `bool` that is `True` if the\n`clean` function should be applied to the transaction. `clean` on the other\nhand also takes a `Transaction` as its argument, but is expected to return a\nmodified transaction description. For more complicated cleaning rules, `Rule`\naccepts an optional argument `field` with which you can specify that the\n`clean` function returns another field than the `Transaction`'s description.\n\nSee `parsers/banks/cleaning_rules/ing_fr.py` for some examples of already\nbuilt-in cleaning rules.\n\n### Account mapping rules\n\nThe second Python file to transform a bank statement's `Transaction`s is the\nfile `account_mappings.py`. As the name suggests, its purpose is to assign\naccounts to the `Transaction`s. To this end, it contains a variable `rules`\nthat contains a list of functions that take a `Transaction` as argument and\nreturn a `str` specifying the account to apply to the transaction or `None`\nif the rule doesn't know which account to assign. The rules are then applied\nin the given order to each `Transaction` until the first non-`None` result\nis encountered which is then assigned as the external account of the\n`Transaction`.\n\nAs a very simplistic example, you could have the following\n`account_mappings.py` with a single rule that applies the account\n`income:salary` to transactions with the word `salary` in their\ndescription:\n\n```python\ndef salary(t):\n    if 'salary' in t.description:\n        return 'income:salary'\n\nrules = [salary]\n```\nHere, we've used the fact that Python functions implicitly return `None`\nwhen reaching their end without encountering a `return` statement. Normally\nthis should be considered a bad coding style, as it might not be clear if\n`None` is really the expected return value or if we simply forgot a `return`\nstatement at the end of the function. In the specific case of our account\nmapping rules, we do however always expect a `return None` if the rule does\nnot match. The normal consideration, that a missing return statement at the\nend of the function might be a code smell is thus not really justified here.\nTherefore, the implicit return of `None` could be used to keep the mapping\nrules short.\n\n### Tips for writing your own cleaning and account mapping rules\n\nTo make use of all properties of a `Transaction` object in your cleaning or\nmapping rules, you can take a look at its definition in `transaction.py`.\nThe most important properties are\n\n* `description`: The subject line of the transaction\n* `account`: The bank account to which the bank statement belongs\n* `external_account`: the other side of the transaction; this is what is\n  filled by your account mapping rules\n* `amount`\n* `currency`\n* `operation_date`: date of the transaction\n* `value_date`: date when the transaction changes the balance of your account\n* `external_value_date`: value date of the external account\n\nAdditionally, each `Transaction` contains a `dict` named `metadata` which\ncan be filled by your cleaning rules with arbitrary metadata that can then\nbe used in your account mappings.\n\nDuring development or debugging of cleaning and mapping rules it might be\nuseful to see the internal representation of `Transaction`s. To this end,\n`parse-bank-statement.py` has the option `--raw` which prints the internal\nrepresentation of the `Transaction` objects instead of formatting them for\nhledger.\n\n## License\n\nThese programs are licensed under the GPL version 3 or (at your option)\nany later version.\n\nThe text of the GPL version 3 can be found in the LICENSES directory.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelgru%2Fbank-statement-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffelgru%2Fbank-statement-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelgru%2Fbank-statement-parser/lists"}