From ef91c199b6100564e13e4e5473856718e03d1b71 Mon Sep 17 00:00:00 2001 From: AlexeyShalaev <75322386+AlexeyShalaev@users.noreply.github.com> Date: Wed, 7 Oct 2026 16:01:57 +0300 Subject: [PATCH] docs: fill in the project profile The profile the hub shipped as a skeleton, filled in from this repository: commands, conventions, boundaries and how a release runs, each checked against master. Once edited, the file is this repository's own and the hub no longer updates it. --- .agents/project.md | 53 +++++++++++++++++++++++----------------------- 1 file changed, 26 insertions(+), 27 deletions(-) diff --git a/.agents/project.md b/.agents/project.md index 165cfda..aa3a013 100644 --- a/.agents/project.md +++ b/.agents/project.md @@ -1,45 +1,44 @@ # Project profile - - ## About -- What this repository is, in one sentence: -- Who uses it: -- Language, version and main frameworks: -- Where the documentation lives: +- What this repository is: `clientwright`, a Python library that runs one resilience and observability core (retries, circuit breaking, deadlines, owned redirects, telemetry) under the public API of popular HTTP clients, published on PyPI. `build()` and `build_sync()` return the HTTP library's own client, such as a genuine `httpx.AsyncClient`, not a wrapper. +- Who uses it: services that call HTTP upstreams through httpx, httpx2, aiohttp, requests or urllib3, and authors of third-party adapters (`register_adapter`). +- Language, version and main frameworks: Python 3.12 and newer, no runtime dependencies; the core in `clientwright/core/` uses the standard library only. Each HTTP library is an optional extra with its adapter in `clientwright/adapters/`: `httpx`, `httpx2`, `aiohttp`, `requests`, `urllib3`. The extras `metrics` (prometheus-client) and `tracing` (OpenTelemetry API), both in `observability`, back `clientwright/adapters/observability/`; `deadline` (deadline-budget), `dishka`, `settings` (Pydantic) and `servicewright` back `clientwright/contrib/`; `all` installs every extra. +- Where the documentation lives: https://bedrock-python.github.io/clientwright/, built with Zensical from `docs/` (`zensical.toml`). `docs/agents.md` is the one-page reference for coding assistants. ## Commands | Task | Command | |---|---| -| Install dependencies | | -| Format | | -| Lint and type-check | | -| Test | | -| Run locally | | -| Stop the local run | | +| Install dependencies | `uv sync --group dev --all-extras` (CONTRIBUTING.md, CI). `make install` runs `uv sync --group dev` without the extras: the tests that need an SDK are then skipped, and `make test` fails its coverage threshold. | +| Format | `make fmt`: `uv run ruff format .`, then `uv run ruff check --fix .` | +| Lint and type-check | `make check`: `uv run ruff check .`, `uv run ruff format --check .`, `uv run mypy clientwright`, `uv run lint-imports` (the import-linter contracts in `pyproject.toml`). CI's lint job runs the same four. | +| Test | `make test`: the whole suite, `uv run pytest --cov=clientwright --cov-fail-under=97`. Narrower: `make test-unit` (`uv run pytest -m unit`) and `make test-integration` (`uv run pytest -m integration`). CI runs `uv run pytest -m unit --cov=clientwright --cov-fail-under=90` on Python 3.12 and 3.13, `uv run pytest -m integration`, the unit tests with no extra installed (`uv sync --group test`), and the requests and urllib3 tests with only those two extras. | +| Run locally | A library: nothing to run. The docs: `make docs-serve`. | +| Stop the local run | Ctrl+C in the terminal of `make docs-serve`. | ## Conventions -- Default branch: -- Issue tracker, and how commits and pull requests refer to an issue (for example `#123` or `ACME-123`): -- Branch names (for example `fix/123-short-description`): -- Commit messages (for example Conventional Commits): -- Language of pull request titles and descriptions: -- Where specs and design notes go: +- Default branch: `master`. Changes reach it only through pull requests (a repository ruleset), and the required check is `All checks passed`, the last job of `ci.yml`. The pre-commit hook `no-commit-to-branch` refuses local commits to it. +- Issue tracker: GitHub Issues of this repository; refer to an issue as `#123`, and close it from the pull request with `Closes #123`. +- Branch names: `/`, such as `feat/my-feature` (CONTRIBUTING.md) or `fix/settings-converter-nested`. +- Commit messages: Conventional Commits, enforced by the `conventional-pre-commit` hook (`uv run pre-commit install --hook-type pre-commit --hook-type commit-msg`). Pull requests are squash-merged, and release-please reads the squash commit, whose title defaults to the commit's subject for a one-commit pull request and to the pull request's title otherwise: keep both Conventional Commits. +- Language of pull request titles and descriptions: English. +- Where specs and design notes go: the problem in a GitHub issue; the design, the alternatives rejected and the verification in the description of the pull request that closes it. The repository has no place for them. ## Boundaries -- Paths agents must not edit (generated code, vendored code, applied migrations): -- Systems and data agents must never touch: +- `CHANGELOG.md` is generated by release-please: never edit it by hand, and never add an `## [Unreleased]` section. `docs/changelog.md` is a copy of it made for the docs build and ignored by git. +- The version lives in `clientwright/__version__.py`, on the line marked `# x-release-please-version`, and in `.release-please-manifest.json`; release-please bumps both. Never change them by hand. +- `docs/agents.md` is part of the public API: it changes in the same pull request as the API (CONTRIBUTING.md, "The agents page"). +- `clientwright/core/` never imports `clientwright/adapters/` or any third-party package, and the adapters never import each other; `clientwright/adapters/_httpx_shared.py` is the one module httpx and httpx2 share. The import-linter contracts in `pyproject.toml` enforce this in `make check` and CI. +- Files from the engineering-assets hub (`AGENTS.md` explains how it works) include the copy-page files (`docs/assets/javascripts/copy-page.js`, `docs/assets/stylesheets/copy-page.css`, `overrides/main.html`, `scripts/emit_markdown.py`), `.github/workflows/docs.yml`, `.github/workflows/release-please.yml`, `.github/dependabot.yml`, `.editorconfig` and `CODE_OF_CONDUCT.md`. Change them in the hub; a change here makes the file this repository's own. +- Never publish to PyPI or create a release by hand: release-please creates the release, and `publish.yml` publishes it. ## Notes -Anything else an agent needs: the architecture in a few lines, known pitfalls, how to get test data. +- Releases: release-please opens its pull request with the workflow's own token, so CI does not start on it. Close and reopen the release pull request to run CI, then merge it; `publish.yml` publishes to PyPI when the Release Please run on `master` completes and a `clientwright-v*` tag points at its commit. Only `feat`, `fix`, `perf` and `revert` commits appear in the changelog. +- Tests: `tests/conftest.py` marks each test by its directory (`tests/unit/` gets `unit`, `tests/integration/` `integration`, `tests/live/` `live`; `--strict-markers`), so a new test goes in the directory of its kind. No Docker: the integration tests start an in-process HTTP origin (`clientwright.core.testing.OriginServer`). `tests/live/` calls real endpoints on the internet and is skipped without `--live` (`make test-live`; `CLIENTWRIGHT_LIVE_HTTPBIN` points it at another httpbin); CI runs it only on a manual dispatch. +- A test module imports an SDK only through `pytest.importorskip` (`tests/unit/test_sdk_imports_are_guarded.py` checks this), so the suite also runs without extras. Every `python` block in `docs/` must parse and import only names that exist (`tests/unit/test_docs_snippets.py`). +- Code style (CONTRIBUTING.md): type hints on every function, tests included; Google-style docstrings on the public API only; lines up to 120 characters; double quotes; comments only for a non-obvious why.