beancount-caixabank 1.0.0
Beancount Importer for CaixaBank Excel statement exports
Requires Python: <4,>=3.9
Keywords: banking, beancount, caixabank, cli-accounting, finance

# Beancount CaixaBank Importer

[![Tests](https://github.com/rogiia/beancount-caixabank/workflows/test/badge.svg)](https://github.com/rogiia/beancount-caixabank/actions)
[![PyPI](https://img.shields.io/pypi/v/beancount-caixabank.svg)](https://pypi.org/project/beancount-caixabank/)
[![Python Versions](https://img.shields.io/pypi/pyversions/beancount-caixabank.svg)](https://pypi.org/project/beancount-caixabank/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

`beancount-caixabank` provides a [Beancount] importer for converting [CaixaBank] Excel
statement exports to the [Beancount] format.

## Features

- **Format Support**: Handles CaixaBank Excel exports (.xls and .xlsx)
- **Robust Parsing**:
  - Flexible header detection (handles statements with metadata rows)
  - Supports both Excel date serial numbers and DD/MM/YYYY string dates
  - European number format parsing (comma as decimal, dot as thousands separator)
- **Full Beancount Integration**: Creates proper transactions with metadata, payee, and narration

## Installation

```sh
pip install beancount-caixabank
```

## Usage

### Getting Your CaixaBank Statement

1. Log in to CaixaBank online
2. Navigate to your account
3. Export statement as Excel file (.xls or .xlsx)
4. The file should contain columns: Fecha, Fecha valor, Movimiento, Más datos, Importe, Saldo

### Beancount 3.x

Beancount 3.x uses a script-based workflow. Create an `import.py` file in your Beancount
directory:

```python
from beancount_caixabank import CaixaBankImporter
from beangulp import Ingest

importers = [
    CaixaBankImporter('Assets:CaixaBank:Checking'),
]

if __name__ == '__main__':
    ingest = Ingest(importers)
    ingest()
```

Then run:

```sh
python import.py extract path/to/statement.xls
```

### Beancount 2.x

Add the following to your `config.py`:

```python
from beancount_caixabank import CaixaBankImporter

CONFIG = [
    CaixaBankImporter('Assets:CaixaBank:Checking'),
]
```

## Configuration

### Account Name

The importer requires you to specify the Beancount account name where transactions will be
imported:

```python
CaixaBankImporter('Assets:MyBank:CaixaBank:Main')
```

### Example Configuration

For a typical Beancount 3.x setup:

```python
from beancount_caixabank import CaixaBankImporter
from beangulp import Ingest

importers = [
    CaixaBankImporter('Assets:CaixaBank:Checking'),
    CaixaBankImporter('Assets:CaixaBank:Savings'),
]

if __name__ == '__main__':
    ingest = Ingest(importers)
    ingest()
```

## File Format

CaixaBank Excel statements should contain the following columns:

| Column | Description | Format |
|--------|-------------|--------|
| Fecha | Transaction date | DD/MM/YYYY |
| Fecha valor | Value date | DD/MM/YYYY |
| Movimiento | Transaction description/payee | Text |
| Más datos | Additional details/reference | Text |
| Importe | Amount | European format (comma decimal, dot thousands) |
| Saldo | Account balance | European format |

**Note**: The importer automatically detects the header row, so metadata rows before the
headers are handled correctly.

## Development

### Prerequisites

- Python 3.9 or higher
- [uv](https://docs.astral.sh/uv/) - Fast Python package installer and resolver

### Setup

1. Clone the repository:
   ```sh
   git clone https://github.com/rogiia/beancount-caixabank
   cd beancount-caixabank
   ```

2. Install dependencies:
   ```sh
   uv sync
   ```

3. Run tests:
   ```sh
   uv run pytest
   ```

4. Run linting:
   ```sh
   uv run task lint
   ```

### Using a Python environment

If you prefer to use a specific Python version:

```sh
uv sync --python 3.11
```

## Testing

The importer includes comprehensive tests covering:
- File identification and validation
- Single and multiple transaction extraction
- Date parsing (string and Excel formats)
- European number format parsing
- Edge cases and error handling

Run the test suite with:

```sh
uv run pytest
```

Or with verbose output:

```sh
uv run pytest -v
```

## Contributing

Contributions are welcome! Please feel free to submit a PR.

## License

This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file
for details.

## Disclaimer

This importer is provided as-is. Always verify imported transactions against your bank
statements to ensure accuracy.

## Support

For issues, questions, or suggestions, please create an issue on the
[GitHub repository](https://github.com/rogiia/beancount-caixabank/issues).

## Related Projects

- [Beancount](http://furius.ca/beancount/) - Command-line accounting system
- [beancount-n26](https://github.com/siddhantgoel/beancount-n26) - N26 bank importer
- [beangulp](https://github.com/jbms/beangulp) - Beancount importer framework

[Beancount]: http://furius.ca/beancount/
[CaixaBank]: https://www.caixabank.es/