Metadata-Version: 2.4
Name: beancount-lalitm
Version: 0.2.0
Summary: Importers and plugins for Beancount plain-text accounting
Project-URL: Homepage, https://github.com/LalitMaganti/beancount-lalitm
Project-URL: Repository, https://github.com/LalitMaganti/beancount-lalitm
Author: Lalit Maganti
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: accounting,beancount,finance,importers,plugins
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.11
Requires-Dist: beancount>=3.0.0
Requires-Dist: beangulp>=0.1.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: openpyxl>=3.1.0; extra == 'all'
Requires-Dist: pdftotext>=2.2.0; extra == 'all'
Requires-Dist: xmltodict>=0.13.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1.0; extra == 'excel'
Provides-Extra: ib
Requires-Dist: xmltodict>=0.13.0; extra == 'ib'
Provides-Extra: pdf
Requires-Dist: pdftotext>=2.2.0; extra == 'pdf'
Description-Content-Type: text/markdown

# beancount-lalitm

Importers and plugins for [Beancount](https://beancount.github.io/) plain-text accounting.

> **Disclaimer:** I am not a tax professional or financial advisor. This code is provided as-is for personal use. The `uk_cgt_lots` plugin in particular implements my understanding of UK Capital Gains Tax rules, which may be incomplete or incorrect. Use at your own risk.

## Installation

```bash
pip install beancount-lalitm

# With optional dependencies for specific importers
pip install beancount-lalitm[ib]      # Interactive Brokers (XML)
pip install beancount-lalitm[pdf]     # PDF-based importers
pip install beancount-lalitm[excel]   # Excel-based importers
pip install beancount-lalitm[all]     # All optional dependencies
```

## Importers

### Investment Accounts (Fully Automated)

Investment importers can run directly via beangulp since no categorization is needed.

Create an `import.py`:

```python
#!/usr/bin/env python3
"""Beancount import configuration for investments."""
import beangulp
from beancount import loader
from beancount_lalitm.importers.account_lookup import AccountOracle
from beancount_lalitm.importers.ib import IbImporter

entries, errors, options = loader.load_file('main.beancount')

ib_oracle = AccountOracle(
    account='Lalit:US:IB:Brokerage',
    entries=entries,
    transfers_account='Assets:Lalit:US:IB:Transfers',
)

CONFIG = [
    IbImporter(account_currency='USD', account_oracle=ib_oracle),
]

if __name__ == '__main__':
    beangulp.Ingest(CONFIG)()
```

Run directly with beangulp:

```bash
python import.py extract ~/Downloads/ib-flex-query.xml >> investments.beancount
```

### Bank Accounts (Semi-Automated)

Bank and credit card importers require categorization. Use [beancount-import](https://github.com/jbms/beancount-import) for a web UI that learns from your previous choices.

```python
#!/usr/bin/env python3
"""Beancount import configuration for banks."""
from beancount_lalitm.importers.hsbc import HsbcImporter
from beancount_lalitm.importers.hsbc_uk_cc import HsbcUkCcImporter

CONFIG = [
    HsbcImporter(account='Assets:Lalit:UK:HSBC:Current'),
    HsbcUkCcImporter(account='Liabilities:Lalit:UK:HSBC:CreditCard'),
]
```

Run the beancount-import web UI:

```bash
python -m beancount_import.webserver \
    --journal journal.beancount \
    --ignored_path ignored.beancount \
    --account_filter '^Assets:Lalit:UK:HSBC'
```

### Available Importers

#### Investment Platforms

| Importer | Description | Input Format |
|----------|-------------|--------------|
| `IbImporter` | Interactive Brokers | Flex Query XML |
| `SchwabEacImporter` | Schwab Equity Award Center | Text (PDF converted) |
| `VanguardImporter` | Vanguard UK | Excel |
| `IgImporter` | IG Trading | Text (PDF converted) |
| `AjTransactionsImporter` | AJ Bell transactions | PDF |
| `AjCashImporter` | AJ Bell cash history | CSV |
| `AvivaPensionImporter` | Aviva pension | Text (PDF converted) |

#### Banks

| Importer | Description | Input Format |
|----------|-------------|--------------|
| `HsbcImporter` | HSBC UK current account | Text (PDF converted) |
| `HsbcUkCcImporter` | HSBC UK credit card | JSON |
| `HsbcUsCcImporter` | HSBC US credit card | JSON |
| `HsbcUsCheckingImporter` | HSBC US checking | Text (PDF converted) |

#### Payroll

| Importer | Description | Input Format |
|----------|-------------|--------------|
| `GooglePayslipImporter` | Google UK payslips | Text (PDF converted) |

## Plugins

Add plugins to your beancount file with the `plugin` directive.

### ancillary_accounts

Auto-creates companion accounts for investment securities (commissions, dividends, capital gains, withholding tax).

```beancount
plugin "beancount_lalitm.plugins.ancillary_accounts"

2024-01-01 open Assets:Broker:AAPL  AAPL
  ancillary_commission_currency: USD
  ancillary_distribution_currency: USD
  ancillary_capital_gains_currency: USD
```

### stock_split

Adjusts historical transactions for stock splits.

```beancount
plugin "beancount_lalitm.plugins.stock_split" "
  splits:
    - symbol: GOOG
      date: 2022-07-15
      ratio: 20
"
```

### uk_cgt_lots

UK Capital Gains Tax lot matching using Section 104 pooling.

```beancount
plugin "beancount_lalitm.plugins.uk_cgt_lots" "
  accounts:
    - name: Person:UK:Broker:GIA
      taxable: true
    - name: Person:UK:Broker:ISA
      taxable: false
"
```

## License

Apache 2.0 - see [LICENSE](LICENSE) for details.
