Metadata-Version: 2.5
Name: atrhub
Version: 1.0.0
Summary: ATR xml files handler
Project-URL: Homepage, https://gisce.net/
Author-email: Adrián Baena <devel@gisce.net>, Xavier Torelló <devel@gisce.net>
License: GPL-3.0
License-File: LICENSE
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: click>=8
Requires-Dist: gestionatr
Requires-Dist: python-magic
Provides-Extra: dev
Requires-Dist: pre-commit>=4.5.1; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.15.2; extra == 'dev'
Requires-Dist: ty>=0.0.18; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-cov>=5; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Requires-Dist: ruff>=0.15.2; extra == 'test'
Description-Content-Type: text/markdown

# atrhub

`atrhub` validates and routes ATR/CCH exchange files between market actors.

- **Python**: 3.8+
- **CLI entrypoint**: `atrhub`
- **Main package**: `atrhub`

## Table of contents

- [What it does](#what-it-does)
- [Installation](#installation)
- [Usage](#usage)
  - [CLI](#cli)
  - [Library API](#library-api)
  - [Create FTP users](#create-ftp-users)
- [Development](#development)
  - [Local setup](#local-setup)
  - [Run tests](#run-tests)
  - [Lint and format](#lint-and-format)
  - [Build distributions](#build-distributions)
- [Logs](#logs)
- [CI/CD](#cicd)
  - [Guide 1: Release Candidate (RC) from current PR branch](#guide-1-release-candidate-rc-from-current-pr-branch)
  - [Guide 2: Final release (vxyz)](#guide-2-final-release-vxyz)

## What it does

For supported files, `atrhub`:

1. Scans outgoing queues in a tree structure.
2. Validates files (including sender/receiver constraints).
3. Routes valid files to the target actor queue.
4. Marks invalid files as `.error` and logs the failure reason.

## Installation

Install from PyPI:

```bash
pip install atrhub
```

## Usage

### CLI

Inspect options:

```bash
atrhub --help
```

```text
Usage: atrhub [OPTIONS]

Options:
  --path PATH      Directory to process  [required]
  --log-file PATH  Absolute log file path for this execution  [required]
  --mode [atr|cch] Processor mode  [default: atr]
  --help           Show this message and exit.
```

Example:

```bash
atrhub --path /tmp/atr_tree --log-file /tmp/atrhub.log --mode atr
```

Exit code behavior:

- `0`: successful execution (including empty runs with no files to process)
- `>0`: execution failed

### Library API

```python
import atrhub

atr_files = atrhub.ATRFiles(path="/tmp/atr_tree")
atr_files.deliver()
```

### Create FTP users

The package ships the `create_ftp_user` helper command (from `bin/create_ftp_user.sh`).

```bash
create_ftp_user AAAA XXXX
```

This command creates users and sets required grants for atrhub-compatible SFTP usage.

## Development

### Local setup

Clone and install with development dependencies:

```bash
pip install -e ".[dev]"
```

If you only need test dependencies (same profile used in CI):

```bash
pip install -e ".[test]"
```

### Run tests

```bash
pytest
```

### Lint and format

```bash
python -m ruff check .
python -m ruff format .
python -m pre_commit run --all-files
```

Type checks:

```bash
python -m ty check
```

### Build distributions

```bash
python -m build
```

Artifacts are generated in `dist/`.

## Logs

### Action example

```log
2019-01-14 19:55:59,264 INFO     Moving file '/tmp/atr_tree/0034/Salida/M1_2.xml' to '/tmp/atr_tree/0762/Entrada/M1_2.xml'
```

### Error example

```log
2019-01-14 19:55:59,297 ERROR    File '/tmp/atr_tree/0096/Salida/inexistent_destination.xml' is not accepted, wrong destinatary inside XML "0000"
```

## CI/CD

- CI tests run from [.github/workflows/ci_test_config.yml](.github/workflows/ci_test_config.yml)
- Release publishing runs from [.github/workflows/release.yml](.github/workflows/release.yml)

The release workflow is triggered by pushing a Git tag.

Tag formats:

- Final release: `vX.Y.Z` (example: `v1.0.0`)
- Release candidate: `vX.Y.Z-rcN` (example: `v1.0.0-rc1`)

### Guide 1: Release Candidate (RC) from current PR branch

Use this flow to validate packaging/release automation before merge.

1. Bump package version in `atrhub/__init__.py`:

    ```python
    __version__ = "1.0.0"
    ```

2. Commit and push the version bump to your PR branch:

    ```bash
    git add atrhub/__init__.py
    git commit -m "Bump version to 1.0.0"
    git push origin <your-branch>
    ```

3. Create and push an RC tag from your current branch HEAD:

    ```bash
    git tag v1.0.0-rc1
    git push origin refs/tags/v1.0.0-rc1
    ```

4. Verify `GISCE_ATRHUB_RELEASE` in GitHub Actions.

Result:

- GitHub builds `sdist` + `wheel`
- GitHub creates a **pre-release**
- **PyPI publish step is skipped for RC tags**

### Guide 2: Final release (`vX.Y.Z`)

Final releases should be tagged from the commit already merged to `master`.

1. Merge the PR with the version bump.
2. Ensure CI is green on `master`.
3. From `master`, create and push the final tag:

    ```bash
    git checkout master
    git pull --ff-only
    git tag v1.0.0
    git push origin refs/tags/v1.0.0
    ```

Result:

- GitHub builds `sdist` + `wheel`
- GitHub creates the final Release
- Workflow publishes package to PyPI (requires `PYPI_TOKEN` secret)
