Skip to content

Getting Started

1. Install the package

pip 

pip install mypackage

poetry 

poetry add mypackage

pdm 

pdm add mypackage

2. Create extractors

Base class for CSV extractors

Create a file called extractors/csv.py by subclassing ExtractorCsvBase:

class MyCsvExtractor(ExtractorCsvBase):

    fields = ["Date", "Description", "Amount", "Currency"]

    def process_line(self, lineno, line):
        return Transaction(
            date=self.parse_date(line["Date"]),
            narration=line["Description"],
            amount=Decimal(line["Amount"]),
            currency=line["Currency"],
        )

3. Create import rules

The import configuration file for beancount-importer-rules.

Examples

import-config.yml
# yaml-language-server: $schema=https://raw.githubusercontent.com/zenobi-us/beancount-importer-rules/master/schema.json

inputs:
- match: "sources/*.csv" # (1)
  config:
    extractor:
        import_path: "extractors.my_extractor:YourExtractorClass" # (2)
        as_name: "custom name for this extractor instance"
        date_format: "%Y-%m-%d"
        datetime_format: "%Y-%m-%d %H:%M:%S"
    default_file: "books/{{ date.year }}.bean" # (3)
    prepend_postings:
        - account: "Assets:Bank"

imports:
- name: "simple"
    match:
      desc: "Simple Transaction"
    actions:
    - type: "add_txn"
      txn:
        date: "2021-01-01"
        flag: "*"
        narration: "Simple Transaction"
        postings:
            - account: "Expenses:Simple"
              amount:
                number: "{{ amount }}"
                currency: "USD"
  1. pathname is relative to the workspace root
  2. import path is relative to the workspace root
  3. pathname is relative to the workspace root

You can view the schema for more details or refer to the ImportDoc api

4. Run the importer

Import transactions from external sources to Beancount files.

Assuming the following directory structure:

> tree .
workspace/
    ├── extractors/
    │   ╰── my_extractor.py
    │
    ├── sources/
    │       ├── 2024-01-01.csv
    │       ├── 2024-01-02.csv
    │       ╰── 2024-01-03.csv
    │
    ├── imported/
    │   ├── 2024-01-01.bean
    │   ├── 2024-01-02.bean
    │   ╰── 2024-01-03.bean
    │
    ├── main.bean
    ├── options.bean
    ├── imported.bean
    ├── accounts.bean
    ├── data.bean
    ╰── importer_config.yaml

The import_cmd command will import matching transactions found in matching files the sources directory to the imported directory.

> beancount-import import \
    -w workspace \
    -b data.bean \
    -c importer_config.yaml
Note

We recommend having separate beanfiles for options and data.

  • main.bean
    • data.bean
      • accounts.bean
      • imported.bean
    • options.bean

Your main.bean should import data.bean, options.bean.

Your data.bean should import accounts.bean, imported.bean.

This way, you can keep your data and options separate from your main beanfile.

But more importantly, we recommend this because beancount-importer-rules doesn't understand some of the syntax used for options.

Read More