caracas4check

Python client library for the 4check caracas API — the signature-auth surface exactly as published to customers at /<customer_id>/doc/openapi.yaml (source: perl/frontend → docker/perl-apache/frontend/perl/_templates/doc/openapi.yaml.tpl).

This README is for the infrastructure / release team — the people who build this package and wire it into the deploy. End-user documentation lives in docs/ (built by CI as a MkDocs site and hosted on a separate docs server). Don't put usage docs here.

GitLab

Repo layout

caracas4check/        the package (client, ping, checker, account, errors)
caracas4check/example.py   interactive teaching CLI (ships inside the wheel)
tests/                unittest suite (unit + env-gated integration)
docs/                 MkDocs source = the END-USER docs (hosted elsewhere)
pyproject.toml        name/version/deps + console-script entry point
.gitlab-ci.yml        build + publish pipeline
mkdocs.yml            docs site config

Runtime dependency: requests[socks] (resolved from PyPI at install time — it is not vendored). The package also installs a console command caracas4check-example (entry point caracas4check.example:cli).

Build & publish (CI)

Pipeline runs on a tag 1.1.0. CI checks that the tag equals pyproject.toml version, then builds and publishes:

1. wheel + sdist (python -m build) → uploaded with twine to the project's GitLab PyPI registry (.../projects/113/packages/pypi).
2. Generic package caracas-release → caracas4check-release/1.1.0 with:
   • caracas4check-1.1.0-py3-none-any.whl
   • caracas4check-1.1.0.tar.gz
   • index.html (rendered MkDocs landing page)
3. A GitLab Release for the tag, with asset links to the three files above.

(test stage runs the unittest suite on main / dev; it needs the env vars listed under Tests.)

How it reaches the infrastructure

The wheel is not served from this repo. Two downstream repos place and serve it (same pattern as the captcha set):

End users then install with:

pip install --extra-index-url https://<host>/pypi/ caracas4check

--extra-index-url (not --index-url): our host carries only the caracas4check wheel; dependencies (requests, …) come from PyPI as usual.

Version coupling: CARACAS4CHECK_VERSION in docker-compose/frontend3/.gitlab/images-versions.env must equal this repo's pyproject.toml version — the wheel/sdist filenames derive from it. Bump them in lockstep.

Release procedure

1. Bump version in pyproject.toml (semver, e.g. 1.0.1).
2. Commit.
3. git tag 1.1.0 (must equal the new version exactly) and push the tag.
4. CI builds and publishes (PyPI registry + generic package + release).
5. In docker-compose/frontend3, set CARACAS4CHECK_VERSION="1.1.0" in .gitlab/images-versions.env (and .env.example) and deploy.

Old versions stay published — downstream pins an exact version, so never re-tag a released version with different contents.

Tests

python -m unittest discover -s tests -v

• Unit tests run with no network.
• Integration tests are skipped unless these env vars are set:
  • CARACAS4CHECK_ENDPOINT — full customer endpoint, e.g. https://<host>/<customer_id>/caracas/
  • CARACAS4CHECK_API_KEY_HEX
  • optional SOCKS5H_HOST / SOCKS5H_PORT for proxied runs

API surface

Signature-auth client mirroring the public customer spec (/<customer_id>/doc/openapi.yaml) — 1:1, all 8 actions:

• ping.pong(), ping.signature_pong()
• checker.simple(items), checker.authorize(items), checker.results(sig), checker.abort(sig), checker.history(...)
• account.checks()

Card items support the optional cardholder field (ISO/IEC 7813 Track 1 Name). For usage, examples and the full reference see docs/.