Metadata-Version: 2.4
Name: beancount-v3-mercury
Version: 0.2.0
Summary: Import Mercury banking transactions into beancount format
Project-URL: Repository, https://github.com/EnriqCG/beancount-v3-mercury
Author: Enrique Carpintero
License-Expression: MIT
License-File: LICENSE
Keywords: beancount,beangulp,bookkeeping,finance,mercury
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.10
Requires-Dist: beancount>=2.3.5
Requires-Dist: beangulp>=0.2.0
Requires-Dist: titlecase>=2.0.0
Description-Content-Type: text/markdown

# beancount-v3-mercury

[![CI](https://github.com/EnriqCG/beancount-v3-mercury/actions/workflows/ci.yml/badge.svg)](https://github.com/EnriqCG/beancount-v3-mercury/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/beancount-v3-mercury)](https://pypi.org/project/beancount-v3-mercury/)
[![License](http://img.shields.io/:license-mit-blue.svg?style=flat-square)](LICENSE)

beancount-v3-mercury provides an Importer for converting CSV exports of Mercury checking transactions into [Beancount](https://github.com/beancount/beancount) format.

## Installation

```bash
pip install beancount-v3-mercury
# or
uv add beancount-v3-mercury
```

## Usage

Create an import script (e.g. `import.py`) as follows:

```python
import beancount_mercury
from beangulp import Ingest

importers = [
    beancount_mercury.CheckingImporter(
        'Assets:Checking:Mercury',
        currency='USD',
        account_patterns=[
          # These are example patterns. You can add your own.
          ('GITHUB', 'Expenses:Cloud-Services:Source-Hosting:Github'),
          ('Fedex',  'Expenses:Postage:FedEx'),
        ]
    ),
]

if __name__ == '__main__':
    Ingest(importers).cli()
```

The `account_patterns` parameter is a list of (regex, account) pairs. For each line in your Mercury CSV, `CheckingImporter` will attempt to create a matching posting on the transaction by matching the payee or narration to the regexes. The regexes are in priority order, with earlier patterns taking priority over later patterns.

Once this configuration is in place, you can extract transactions from a Mercury CSV export:

```bash
python import.py extract mercury-transactions.csv
```

## Resources

See [awesome-beancount](https://awesome-beancount.com/) for other publicly available Beancount importers.
