Metadata-Version: 2.4
Name: ofx-converter
Version: 0.1.0
Summary: Convert bank statements between OFX, QIF and CSV
Author: Luke Deaves
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/lukedeaves/ofx-convert
Project-URL: Issues, https://github.com/lukedeaves/ofx-convert/issues
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: ofxparse>=0.21
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# OFX Converter

Convert bank statements between OFX, QIF and CSV. Built for importing into [Manager.io](https://www.manager.io).

Banks such as Nationwide export statements in OFX format. Manager.io imports QIF. This tool bridges the gap, and also converts QIF to OFX or CSV.

| Input | Output |
|---|---|
| OFX (`.ofx`, `.qfx`, `.qbo`) | QIF (default) |
| QIF (`.qif`) | CSV |
| | OFX |

## Requirements

- Python 3.10+
- [ofxparse](https://pypi.org/project/ofxparse/), installed automatically

## Installation

```bash
python -m venv .venv
source .venv/bin/activate
pip install .            # or: pip install -e '.[test]' for development
```

This installs the `ofx-convert` command. You can also run `python -m ofx_convert` from a checkout.

## Usage

Convert a single statement to QIF:

```bash
ofx-convert statement.ofx
```

Convert all statements in a folder:

```bash
ofx-convert ~/Downloads/statements/
```

Write output to a different folder, searching subfolders (subfolders are mirrored in the output):

```bash
ofx-convert ~/statements/ -o ~/imports/ -r
```

Export as CSV, for reviewing in a spreadsheet:

```bash
ofx-convert statement.ofx -f csv
```

Combine overlapping monthly statements into one file per account, dropping duplicates:

```bash
ofx-convert jan.ofx feb.ofx mar.ofx --merge -o ~/imports/
```

Only include transactions from a date range:

```bash
ofx-convert statement.ofx --start 2024-01-01 --end 2024-03-31
```

Convert a QIF file to OFX:

```bash
ofx-convert old-export.qif -f ofx
```

Pipe through the tool (`-` reads stdin; output then goes to stdout):

```bash
cat statement.ofx | ofx-convert - -f csv > statement.csv
ofx-convert statement.ofx -o - | less
```

## Options

```
positional arguments:
  INPUT                 statement files or folders to convert; '-' reads from stdin

options:
  -o, --output-dir DIR  folder for converted files, or '-' for stdout
                        (default: the input's folder; stdout when reading stdin)
  -f, --format {csv,ofx,qif}
                        output format (default: qif)
  -i, --input-format {ofx,qif}
                        input format (default: chosen from the file extension or content)
  -r, --recursive       search input folders recursively, mirroring subfolders in the output
  --overwrite           replace output files that already exist
  --merge               combine all inputs into one output per account, dropping
                        duplicate transactions
  --start YYYY-MM-DD    only include transactions on or after this date
  --end YYYY-MM-DD      only include transactions on or before this date
  --date-format FORMAT  strftime format for dates in QIF or CSV output, e.g. '%d/%m/%Y'
                        (default: M/D/YYYY for QIF, YYYY-MM-DD for CSV)
  --qif-dates {auto,mdy,dmy}
                        date order in QIF input: auto detects it, falling back to
                        month/day/year (default: auto)
  --qif-account NAME    account name for QIF input without !Account headers
                        (default: unknown)
  --currency CODE       currency for OFX output when the input has none (default: GBP)
  --opening-balance AMOUNT
                        check that this opening balance plus the transactions equals
                        the closing balance (one account only)
  -q, --quiet           only report warnings and errors
  --version             show program's version number and exit
```

## How it behaves

### Output files

- One output file per account. A statement with one account becomes `statement.qif`. A statement with several accounts becomes `statement_<account>.qif` for each one.
- With `--merge`, each account is written to `<account>.qif`.
- Existing files are never replaced unless you pass `--overwrite`. An input file is never replaced, even with `--overwrite`.
- When writing to stdout, all accounts go into one stream. QIF output uses `!Account` blocks to separate them.
- Status messages and warnings go to stderr, so stdout carries only the converted data.

### Transactions

- Transactions are sorted by date only. Statements listed newest first are reversed, so same-day transactions keep their real order.
- Runs of whitespace (including tabs and line breaks) in payees, memos and other text are collapsed to single spaces.
- A transaction without an amount or date stops that file's conversion with an error. Other files still convert.
- OFX dates are kept as the bank wrote them. ofxparse on its own converts time-zoned timestamps to UTC, which can move a midnight transaction to the previous day.

### Balance checks

OFX statements include a closing balance but no opening balance. The tool:

- shows each statement's closing balance and the opening balance it implies
- checks consecutive statements for the same account against each other: the earlier statement's closing balance plus the new transactions in the later one should equal the later closing balance. A mismatch prints a warning, because it usually means missing transactions.
- with `--opening-balance`, checks that the opening balance you supply plus all transactions equals the closing balance

These checks run before any `--start`/`--end` filtering.

### Duplicates (`--merge`)

Transactions are matched by the bank's transaction ID (FITID). Where there is no ID (QIF input), they are matched by date, amount, payee, memo and check number. Identical transactions within one statement, such as two coffees on the same day, are all kept. Only repeats across overlapping statements are dropped.

Statements are merged by account number for OFX and by account name for QIF, so an OFX and a QIF export of the same account are not merged with each other.

### QIF input

- Supports `!Type:Bank`, `!Type:CCard` and `!Type:Cash` sections, and `!Account` blocks for files with several accounts. Investment and other sections are skipped with a warning.
- The date order is detected from the file. If every date is ambiguous (no day above 12), month/day/year is assumed with a warning; use `--qif-dates dmy` for day/month/year files. Quicken's `1/ 5'24` style and ISO dates are understood.
- Split lines are ignored with a warning; each transaction keeps its total amount. Categories (`L`) are kept.

### Date format

QIF output defaults to month/day/year (e.g. `1/5/2024`), the convention most QIF importers expect. CSV output defaults to ISO (`2024-01-05`). OFX dates have a fixed format, so `--date-format` does not apply to OFX output.

### OFX output

Written as OFX 1.02. Transactions without a bank ID (from QIF input) get a stable ID derived from their content, so converting the same file twice produces the same IDs.

## Supported account types

Bank (current and savings), credit card and cash. Investment accounts are not supported.

## Development

```bash
make dev     # pip install -e '.[dev]'
make test
```

### Building and releasing

Bump `__version__` in `ofx_convert/__init__.py`, then from the repo root:

```bash
make build         # runs the tests, builds dist/*.tar.gz and dist/*.whl, checks them
make publish-test  # upload to TestPyPI
make publish       # upload to PyPI
```

Uploads use twine, which reads credentials from `~/.pypirc` or prompts (username `__token__`, password your API token). Set `PYTHON=.venv/bin/python` to use a specific interpreter.

### Using it as a library

The package is installed as `ofx-converter` and imported as `ofx_convert`:

```python
from pathlib import Path
import ofx_convert as oc

path = Path("statement.ofx")
data = path.read_bytes()
statements = [oc.sort_statement(s) for s in oc.choose_reader(path, data).read(data, str(path), oc.ReadOptions())]
qif = oc.render(oc.WRITERS["qif"], statements, oc.WriteOptions(date_format="%d/%m/%Y"))
```

Input and output formats are pluggable. A reader lives in `ofx_convert/readers/` and a writer in `ofx_convert/writers/`. Each converts to or from the shared `NormalizedTransaction` and `Statement` model in `ofx_convert/model.py`. Register a new format in that package's `__init__.py`.

## License

See [LICENSE.md](LICENSE.md).
