Metadata-Version: 2.4
Name: cde_sepa
Version: 3.0.2
Author: Tobias Udtke
Author-email: Tobias Udtke <tobias.udtke@gmail.com>
License-Expression: MIT
Requires-Dist: click>=8.3.1
Requires-Dist: jinja2>=3.1.6
Requires-Dist: pytz>=2025.2
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# Requirements

The easiest way is to run this via [uv](https://docs.astral.sh/uv/getting-started/installation/#pypi), which will automatically handle the python version for you aswell.

Otherwise this tool requires Pythton 3.12 or newer.

# Setup

## Running via uvx

You can simply run this tool via:

    uvx cde-sepa

This will automatically run the latest published version of the script, requires no further setup and works
anywhere on your machine where `uvx` is available.

You can run specific versions of the script via:

    uvx cde-sepa@latest
    uvx cde-sepa@3.0.0

You can install (a specific version of) the script.
This will cause `uvx cde-sepa` to always use that version. You can still run specific version like shown above:

    uv tool install cde-sepa
    uv tool install cde-sepa@latest
    uv tool install cde-sepa@3.0.0

## Installation

You can also install the script into a virtual environment in order to use it in one specific context.

### Installing via uv

The easiest way to to so is via `uv`. Navigate to the directory where you want to use this script, then run:

    uv venv
    uv pip install cde-sepa

This creates a virtual environment in a directory called `.venv`.
You can now run the script, as long as you are within this directory or any subdirectories:

    uv run cde-sepa

### installing via venv and pip

If you do not want to use uv, you can manually create a virtual environment. Navigate to your directory, then run:

    python3 -m venv .venv
    . .venv/bin/activate
    pip install cde-sepa

Note that you need to activate your virtual environment manually before you are able to use the script.
You can determine that the environment is active by some sort of shell prefix like `(.venv)`.

You can now run the script, as long as the environment is active:

    cde-sepa

You can deactivate the environment by running:

    deactivate

### Installing an editable version.

If you want to work on this script and/or browse the source code you can clone the repository and then install it in
editable mode:

    uv tool install -e <path_to_repository>
    uv pip install -e <path_to_repository>
    pip install -e <path_to_repository>

Or you can simply run the script via `uv` while anywhere inside the repository:

    uv run cde-sepa

# Usage

To use the tool run the `cde-sepa` script. The actual invocation depends on your way of running or installing the script.

You can run the script without any arguments or with `--help` to get an overview of the available commands.

## Matching IBANs (`match`)

By running

    cde-sepa match <iban-source-file> <data-files> ...

you can fill in IBANs read from a source file into any number of data-files.

The source file should be a cde style CSV file with data taken straight from the internal bookkeeping XLSX.
To create such a file, copy both sides (income and expenses) of a single CdE Event from the bookkeeping table underneath
eachother in a blank table, then save as CSV. (See below for CSV format details.)

The data files should be either manually created CSV files containing transactions or a CdEDB-CSV-Download from the registration query.

The data files are expected to have a column labelled `"persona.id"` or `"persona.cdedbid"`.
It can be either a numerical persona id or a formatted one (`DB-...-Y`).
This will be matched to the CdEDB-ID from the source file to determine an IBAN.

The data files _may_ have a column labelled `"IBAN"`, prefilled with override IBANs. If this exists, that line is skipped and
no IBAN is matched from the source.

For each data file `foo.csv` a new file `foo-out.csv` will be created, with a column `"IBAN"` containing all
successfully matched IBANs and a column `"orig_amount"` listing how much that person has paid according to the source file.

### Internal transactions

The match will print a list of people for whom internal payments were found and a list of people with multiple different IBANs
(regardless of whether they are in any of the data files) and a list of people in the data files for which no IBAN was found.

It falls on you to validate whether these internal payments mean that you need to make any adjustments to your transfers.

## Creating SEPA-XMLs (`create`)

By running

    cde-sepa create <transfers file> [--date FOO] [--account BAR]

you can turn a list of CSV transactions into an SEPA-XML file that you can upload to the bank in order to transfer out money.

The following columns are expected:

- `"Betrag"` or `"reg.remaining_owed"`:
    The amount to transfer (Betrag) or a negative amount the user still "owes" (reg.remaining_owed).
    The latter will be inverted.
    Whitespace and `€` will be ignored. Both `.` and `,` are accepted as decimal seperators, but not in combination.
- `"persona.family_name"`, `"Nachname"`, `"Name"` or `"Kontoinhaber"` and `"persona.given_names"` or `"Vorname(n)"` or `"Vorname`":
    The name(s) of the recipient. Will be combined and used as account holder and appended to the reference,
    if a persona id is given. One of these must be given.
- `"persona.id"` or `"persona.cdedbid"`:
    Either a numerical or formatted (`DB-...-Y`) persona id. Will be appended to the end of the reference. (optional)
- `"iban"` or `"IBAN"`: The recipients IBAN.
- `"Verwendungszweck"` or `"reference"`: The reference for the transfer.

Any additional or duplicate columns will be ignored.

The following options are available:

- `--help`: Show available options and expected arguments.
- `--acount`: Choose the account to transfer from. Either "Skatbank" or "Sozialbank". Defaults to "Skatbank". (optional)
- `--date`: Specify a date (`YYYY-MM-DD`) when to perform the transfers. Note that you can also set this upon upload. (optional)

For an input file `foo.csv` the XML file will be written to `foo-transactions.xml`.

## Converting csv files (`convert`)

By running

    cde-sepa convert <csv-file> ...

you can easily convert a bunch of csv (or tsv, etc.) files into the expected csv format.

The script will attempt to detect the encoding, separator and quote style from the input and reformat them.
For every input file `foo.csv` a file `foo-fixed.csv`  will be created. Files already suffixed with `-fixed.csv` will be skipped.

# Development

For development you should lint using `mypy` and `ruff`:

    uv run ruff format
    uv run ruff check
    uv run mypy

To create and publish a new version:

    uv version --bump [major|minor|patch]
    git commit <...>
    uv build
    uv publish
    git push
    git tag v$(uv version --short)
    git push --tags
