Metadata-Version: 2.3
Name: corelibs-csv
Version: 1.0.0
Summary: CoreLibs CSV handling library
Author: Clemens Schwaighofer
Author-email: Clemens Schwaighofer <clemens.schwaighofer@omc.com>
Requires-Dist: corelibs-file>=1.0.1
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# CoreLibs Python CSV Handling

This is part of the Python CoreLibs

## Overview

Read or write CSV File data

## Install

```sh
uv add --index opj-pypi=https://git.egplusww.jp/api/packages/PyPI/pypi/simple/ corelibs-csv
```

## Usage

The following modules exists

- corelibs_csv.csv_interface
- corelibs_csv.csv_exceptions

### corelibs_csv.csv_interface

```py
from corelibs_csv.csv_interface import CsvReader, CsvWriter
from corelibs_csv.csv_exceptions import NoCsvReader, CsvHeaderDataMissing, CompulsoryCsvHeaderCheckFailed, CsvRowDataKeysNotMatching
```

### CsvWriter class

Write CSV data

```py
csv_writer = CsvWriter(
    file_name: Path,
    header_mapping: dict[str, str],
    header_order: list[str] | None = None,
    strict_key_check: bool = False,
    encoding: str = ENCODING,
    delimiter: str = DELIMITER,
    quotechar: str = QUOTECHAR,
    quoting: Any = QUOTING,
)
```

Arguments

- file_name: path to the file that should be writen
- header_mapping: map key values to Columns in the header
- header_order: list of header mapping keys in order the content should be written
- strict_key_check: if set to True when writing a csv row the line keys and header keys are compared and if they are not matching an exception is thrown, on default only if a key is missing an exception is thrown
- encoding: if not set UTF-8 is used
- delimiter: if not set ',' is used
- quotechar: if not set '"' is used
- quoting: quoting level, default is "csv.QUOTE_MINIMAL", others are "csv.QUOTE_ALL" and "csv.QUOTE_NONE"

During the creation the following exception can appear

- NoCsvReader: if no csv writer could be created
- CsvHeaderDataMissing: if no header could be set (header_mapping is missing or empty)
- CompulsoryCsvHeaderCheckFailed: when header order is set and invalid entries are found or if duplicate header values are set
- CsvRowDataKeysNotMatching: either a mandatory entry is missing or if strict_key_check is on if the line keys are not all matching to the header mapping keys

Data can then be written with

```py
csv_writer.write_csv(line: dict[str, str]) -> None:
```

The line is a key value dictionary where the keys must be the same as the keys set in the header_mapping file.
If a mandatory key value is missing in the line the CsvRowDataMissing error is thrown.
If the line has key entries that area not in the header mapping file they will be silently ignored

## Development

### UV setup

uv must be [installed](https://docs.astral.sh/uv/getting-started/installation/)

### Python venv setup

After clone, run the command below to install all dependenciss

```sh
uv sync
```

### Build and Publish

```sh
uv build
uv publish --index opj-pypi --token <gitea token>
```

### Python tests

All python tests are the tests/ folder. They are structured by the source folder layout

run them with

```sh
uv run pytest
```

Get a coverate report

```sh
uv run pytest --cov=<project>
uv run pytest --cov=<project> --cov-report=term-missing
```

### Other tests

In the test-run folder usage and run tests are located, runt them below

```sh
uv run test-run/<script>
```
