cde_sepa 3.0.2

No project description provided

Requirements

The easiest way is to run this via uv, 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