Metadata-Version: 2.1
Name: caracas4check
Version: 1.1.1
Summary: Human-oriented Python client for the 4check caracas API
Author: 4check
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests[socks] >=2.31.0

# 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/`](docs/index.md)** (built by CI as a MkDocs site and hosted on a
> separate docs server). Don't put usage docs here.

## GitLab

| | |
| --- | --- |
| Project | `python3/caracas4check` |
| `project_id` | **113** |
| Import name | `caracas4check` |
| Distribution | `caracas4check` (wheel `caracas4check-<ver>-py3-none-any.whl`) |
| Release tag format | `1.1.0` — the tag is exactly `pyproject.toml` `version` (e.g. `1.1.0`); CI fails the build on a mismatch |

## 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):

| Repo | Role |
| --- | --- |
| `docker-compose/frontend3` | **Fetches** the generic package `caracas4check-release` from `projects/113`, pinned by `CARACAS4CHECK_VERSION`, and rsyncs the wheel + sdist into the openresty volume `volumes/frontend-openresty/frontend/pypi/caracas4check/`. |
| `docker/frontend-openresty` | **Serves** that directory at `/pypi/caracas4check/` (nginx `autoindex` = a pip-readable PEP 503 index). |

End users then install with:

```bash
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`](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

```bash
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/`](docs/index.md).
