probirka

Imported from appKODE/probirka (AGENTS.md). Install upstream with npx skills add appKODE/probirka. Copyright stays with the author.

AGENTS.md

Working rules for probirka: what the package is, where its boundaries are and how a change is expected to look. They apply to everyone who edits the repository, people and tools alike.

What probirka is

A framework-agnostic library for running health probes in Python applications. The core has no runtime dependencies. Ready-made probes for client libraries (Redis, PostgreSQL, HTTP, Kafka, ...) and adapters for HTTP frameworks (FastAPI, aiohttp, Django, plain ASGI) ship in the same package but are imported only when used.

The core is the flat modules of the package root: _probe, _probirka, _results, _redact, _lazy. It is complete on its own: a custom probe needs nothing but ProbeBase, ProbeFailure and Probirka. The subpackages _probes (ready-made probes) and _ext (framework adapters) are additions built on the core; the core never imports them.

Map

Architecture boundaries

Public API

• Public is what probirka/__init__.py exports. Everything under an _-prefixed path is private and may change without notice.
• README, the Sphinx docs (add_module_names = False) and the tests refer to public names as probirka.X, never by the private module they live in.

The core imports with nothing but the standard library

• import probirka and from probirka import * work with no third-party package installed. CI runs exactly that in an isolated interpreter.
• A third-party library is imported at module level only in the driver module that needs it: probirka/_probes/_<library>.py or probirka/_ext/<framework>.py. Nothing imports those modules eagerly; the package root reaches them through the registry in probirka/_lazy.py, and __all__ lists them only when their package is installed.
• make_asgi_app and TcpProbe need no third-party package and are the only eager exceptions.

Layers import downwards only

The core:

1. _redact, _lazy (import nothing from the package)
2. _results
3. _probe
4. _probirka

The additions:

5. _probes/_common, _probes/_http_policy, _probes/_client_base, _probes/_tcp
6. _probes/_http_base, _probes/_mongo_base, _ext/_common
7. driver probes _probes/_<library>.py, adapters _ext/asgi.py and _ext/<framework>.py
8. the barrels _probes/__init__.py, _ext/__init__.py, and the package root

A module imports from its own layer or a lower one, never from a higher one. In particular: the core never imports _probes or _ext; nothing inside the package imports the root probirka; _probes/* never import _probirka or _ext; _ext/* never import _probes.

__init__.py files only re-export

• Allowed in an __init__.py: a module docstring, import and from ... import, a TYPE_CHECKING block of imports, __all__, package metadata dunders such as __version__.
• Not allowed: classes, functions, constants, control flow. Code lives in a named module (_probe.py, not __init__.py).
• Inside a subpackage, siblings import each other by concrete module path (from probirka._probes._common import resolve), never through the subpackage __init__. A barrel imported by its own members is a circular import waiting to happen. Only the package root and the tests consume barrels.
• A subpackage __init__ re-exports its dependency-free names in __all__. The names that need a third-party package appear there only inside a TYPE_CHECKING block, so type checkers see the whole surface while the barrel imports nothing at runtime. Statically probirka._probes.RedisProbe looks present; at runtime it is not, and nothing reaches for it there.
• The package root imports only its direct children: the flat modules (_lazy, _redact, _results, _probe, _probirka) by name and the subpackages through their barrels, never probirka._probes._<module>. The lazy names come from the barrels under TYPE_CHECKING as well; their runtime path is the LAZY registry.
• The package root additionally binds the PEP 562 hooks by assignment (__getattr__ = _module_getattr, __dir__ = _module_dir) and appends the installed lazy names to __all__. That is the whole exception.
• tests/test_architecture.py enforces all of the above.

Probe contract

• run_check() never raises. Exceptions and timeouts become ProbeResult.error.
• Raise ProbeFailure when the service answered but is not healthy; its message is the error.
• A probe registers every secret it hands to a client library with _register_secrets() so that the error text is masked. Ready-made probes register the connection-string password and the request header values.
• allow_failure=True keeps a probe's failure out of the overall ok; the probe's own result still shows it.

Adding a probe or an adapter

1. Create probirka/_probes/_<library>.py extending ClientProbeBase (or HttpProbeBase, MongoProbeBase), or probirka/_ext/<framework>.py built on run_and_render from _ext/_common.py. Import the library at module level in that file only.
2. Add the name to LAZY in probirka/_lazy.py (module path, import name, pip package), a TYPE_CHECKING re-export to the subpackage barrel (probirka/_probes/__init__.py or probirka/_ext/__init__.py) and one more, from that barrel, to probirka/__init__.py.
3. Add the library to the dev dependency group in pyproject.toml.
4. Unit tests with the client mocked in tests/probes/; an integration test in tests/integration/ plus the service in tests/integration/compose.yaml and in the services: block of .github/workflows/tests.yml.
5. An automodule block in docs/source/api.rst, a README section and a CHANGELOG.md entry under Unreleased.

Tooling

• uv sync --dev once; then just fmt, just lint, just ty, just tests, just doc. just services-up && just tests-integration runs the live-service tests. CI runs the same recipes.
• Ruff (lint and format) covers probirka, tests and docs; ty covers probirka.
• The ruff configuration is in pyproject.toml. Every global ignore and every per-file ignore carries a comment saying why. A # noqa carries a reason (# noqa: S101 -- narrowed by require_exactly_one in __init__). Do not widen per-file-ignores to silence one line.
• Pre-commit runs ruff and ty on the changed files; keep its ruff version equal to the one in uv.lock.

Code style

• Single quotes, 120 columns, from __future__ import annotations in every module, absolute imports only, typing-only imports under TYPE_CHECKING.
• Docstrings in pep257 form with Sphinx fields (:param:, :return:, :raises:) and an imperative first line. Every public module, class and function has one.
• Exception messages go through a variable: msg = ...; raise ValueError(msg).
• Booleans are passed by keyword at call sites.
• Identifiers, comments, docstrings and commit messages are English.

Tests

• Import from probirka. Use a private module only for a symbol that has no public path or to monkeypatch a module object.
• tests/test_lazy_imports.py and tests/test_architecture.py are the executable specification of the boundaries above; extend them when a boundary changes.
• just tests needs no Docker: tests/integration/ is skipped unless PROBIRKA_INTEGRATION=1.

Commits, merge requests, changelog

• Commit subject: <type>: <imperative summary> with one of feat, fix, chore, test, docs; English, no trailing period.
• Merge request description: short. Plain sentences and bulleted or numbered lists are the only formatting. No headings, bold text, tables, code blocks or emoji.
• Do not mention AI assistants, language models or code generators anywhere in the repository or its history: not in code, comments or docstrings, not in commit messages or trailers (no Co-authored-by for a tool, no "generated with"), not in merge request titles or descriptions, not in the changelog.
• User-visible changes go to CHANGELOG.md under Unreleased, in the existing style.