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
• Installation
• Usage
  • CLI
  • Library API
  • Create FTP users
• Development
  • Local setup
  • Run tests
  • Lint and format
  • Build distributions
• Logs
• CI/CD
  • Guide 1: Release Candidate (RC) from current PR branch
  • 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:

pip install atrhub

Usage

CLI

Inspect options:

atrhub --help

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:

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

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).

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:

pip install -e ".[dev]"

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

pip install -e ".[test]"

Run tests

pytest

Lint and format

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

Type checks:

python -m ty check

Build distributions

python -m build

Artifacts are generated in dist/.

Logs

Action example

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

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
• Release publishing runs from .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:

   __version__ = "1.0.0"
   

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

   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:

   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:

   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)