Skip to content

Commit 671b495

Browse files
authored
Merge pull request #17 from modern-python/docs/reorg-and-mkdocs
docs: reorganize docs/, delete bmad archive, add mkdocs site
2 parents a2abca4 + 8f6ea18 commit 671b495

44 files changed

Lines changed: 1066 additions & 5166 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,4 @@ wheels/
2323
.venv
2424
uv.lock
2525
plan.md
26+
site/

‎.readthedocs.yaml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
version: 2
2+
3+
build:
4+
os: "ubuntu-22.04"
5+
tools:
6+
python: "3.12"
7+
8+
python:
9+
install:
10+
- requirements: docs/requirements.txt
11+
12+
mkdocs:
13+
configuration: mkdocs.yml

‎CLAUDE.md‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,11 @@ Guidance for AI agents (Claude Code, etc.) working in this repository.
88

99
**Where to find what:**
1010

11-
- [`docs/engineering.md`](docs/engineering.md) — the distilled design reference: invariants and *why*, the five protocol seams, exception contract, module layout, testing patterns, optional-extras pattern, remaining roadmap. Read this before adding any new module or extension point.
12-
- [`docs/deferred-work.md`](docs/deferred-work.md) — review-surfaced items that are real but not actionable now.
13-
- [`docs/superpowers/specs/`](docs/superpowers/specs/) and [`docs/superpowers/plans/`](docs/superpowers/plans/) — per-feature design specs and implementation plans (active work).
14-
- [`docs/archive/`](docs/archive/) — historical bmad-era planning bundle (PRD, architecture, epics, product briefs, per-story specs for 1-1 through 1-5). Consult only for original rationale or specific FR/NFR citations.
11+
- [`docs/dev/engineering.md`](docs/dev/engineering.md) — the distilled design reference: invariants and *why*, the five protocol seams, exception contract, module layout, testing patterns, optional-extras pattern, remaining roadmap. Read this before adding any new module or extension point.
12+
- [`planning/deferred-work.md`](planning/deferred-work.md) — review-surfaced items that are real but not actionable now.
13+
- [`planning/specs/`](planning/specs/) and [`planning/plans/`](planning/plans/) — per-feature design specs and implementation plans (active work).
1514

16-
**Per-feature workflow:** brainstorming → spec in `docs/superpowers/specs/` → writing-plans → plan in `docs/superpowers/plans/` → executing-plans (or subagent-driven-development) → requesting-code-review → finishing-a-development-branch. Topic slugs are kebab-case descriptions (`msgspec-decoder-adapter`), not story IDs.
15+
**Per-feature workflow:** brainstorming → spec in `planning/specs/` → writing-plans → plan in `planning/plans/` → executing-plans (or subagent-driven-development) → requesting-code-review → finishing-a-development-branch. Topic slugs are kebab-case descriptions (`msgspec-decoder-adapter`), not story IDs.
1716

1817
## Commands
1918

@@ -99,5 +98,5 @@ Five documented internal boundaries. AI agents must respect them — never cross
9998

10099
## When in doubt
101100

102-
- Check [`docs/engineering.md`](docs/engineering.md) before adding a new module or extension point; `docs/archive/architecture.md` has the deeper historical rationale if needed.
101+
- Check [`docs/dev/engineering.md`](docs/dev/engineering.md) before adding a new module or extension point.
103102
- Surface ambiguity as a documentation gap rather than improvising.

‎CONTRIBUTING.md‎

Lines changed: 4 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,6 @@
1-
# Contributing to httpware
1+
# Contributing
22

3-
Thank you for your interest in contributing. `httpware` is an open-source resilience-first async HTTP client framework for Python, maintained under the [`modern-python`](https://github.com/modern-python) org.
3+
The contributing guide is published as part of the project documentation:
4+
**https://httpware.readthedocs.io/en/latest/dev/contributing/**
45

5-
## Quick start
6-
7-
```bash
8-
git clone https://github.com/modern-python/httpware.git
9-
cd httpware
10-
just install # uv lock --upgrade && uv sync --all-extras --frozen --group lint
11-
just lint # ruff format + ruff check + ty check
12-
just test # pytest with coverage
13-
```
14-
15-
## Development workflow
16-
17-
1. **Open an issue first** for non-trivial changes — design discussion catches issues earlier than code review.
18-
2. **Branch from `main`**, use a descriptive name (`feat/retry-budget-jitter`, `fix/transport-cancel-leak`).
19-
3. **Run `just lint` and `just test`** locally before pushing. CI will reject changes that fail either.
20-
4. **Add tests** for any code change. Property-based tests (via Hypothesis) are required for concurrency-sensitive code (retry budget, bulkhead, retry interleaving).
21-
5. **Open a pull request** against `main`. PR titles use conventional-commits style (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`).
22-
23-
## Code style
24-
25-
- `ruff format` enforces formatting; do not hand-format.
26-
- Type-check with `ty` (Astral). Use `# ty: ignore[<rule>]` for suppressions, not `# type: ignore`.
27-
- Do NOT use `from __future__ import annotations`. Python 3.11+ is the floor.
28-
- Module docstrings are required; per-method docstrings only when types alone are insufficient.
29-
30-
See `docs/concepts/middleware.md` and `docs/recipes/custom-middleware.md` (once published) for architecture conventions.
31-
32-
## Architecture invariants
33-
34-
These are enforced by CI grep gates. Do not break them in pull requests:
35-
36-
- No `import httpx2` outside `src/httpware/transports/httpx2.py`.
37-
- No `httpx2._*` (private API) usage anywhere in the library.
38-
- No `from __future__ import annotations`.
39-
- No `print()` calls.
40-
- No `logging.basicConfig()` or bare `logging.getLogger()`.
41-
42-
## Code of Conduct
43-
44-
By participating in this project, you agree to abide by its Code of Conduct. Be excellent to one another.
45-
46-
## License
47-
48-
By contributing, you agree that your contributions will be licensed under the project's MIT license.
6+
Source: [`docs/dev/contributing.md`](docs/dev/contributing.md).

‎README.md‎

Lines changed: 7 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@
77

88
**Async HTTP client framework for Python.**
99

10-
`httpware` is a typed, async HTTP client library built on `httpx2` with a protocol-based seam so the transport is swappable. Middleware composes via an onion model. Pydantic and msgspec response decoding ship out of the box. `RecordedTransport` replaces respx for transport-level tests.
10+
`httpware` is a typed, async HTTP client library with a protocol-based seam so the transport is swappable (`httpx2` ships as the default). Middleware composes via an onion model. Pydantic and msgspec response decoding ship out of the box. `RecordedTransport` replaces `respx` for transport-level tests.
1111

12-
> **Status:** Pre-1.0 (0.1.0 alpha). Public API is subject to change between minor releases until v1.0. Resilience middleware (retry / timeout / bulkhead), streaming, and observability are not yet shipped — track progress on GitHub.
12+
> **Status:** Pre-1.0 (0.1.0 alpha). Public API is subject to change between minor releases until v1.0. Resilience middleware (retry / timeout / bulkhead), streaming, and observability are not yet shipped.
1313
1414
## Install
1515

@@ -23,7 +23,7 @@ Optional extras:
2323
pip install httpware[msgspec] # MsgspecDecoder
2424
```
2525

26-
(`otel`, `niquests`, and `all` extras are declared but their integrations have not shipped yet.)
26+
(`otel`, `niquests`, and `all` extras are declared; integrations have not shipped yet.)
2727

2828
## Quickstart
2929

@@ -43,20 +43,12 @@ async def main() -> None:
4343
print(user.name)
4444
```
4545

46-
## What ships in 0.1.0
46+
## 📚 [Documentation](https://httpware.readthedocs.io)
4747

48-
- **`AsyncClient`** — eight HTTP method shortcuts (`get`, `post`, `put`, `patch`, `delete`, `head`, `options`, `request`) with typed `response_model` overloads; per-call overrides for `headers`, `params`, `cookies`, `timeout`, `json`, `content`; httpx-style `base_url` join; `with_options(...)` returns a view sharing the same transport.
49-
- **Transport-agnostic seam.** `httpx2` is confined to `httpware.transports.httpx2.Httpx2Transport`. Implement the `Transport` protocol to swap backends.
50-
- **Middleware foundation.** `Middleware` protocol, `Next` type alias, and phase decorators (`@before_request`, `@after_response`, `@on_error`). The chain is composed at `AsyncClient` construction; consumers don't compose chains themselves.
51-
- **Pluggable response decoding.** `PydanticDecoder` (default) with cached `TypeAdapter`; `MsgspecDecoder` via `httpware[msgspec]`.
52-
- **`RecordedTransport`** — built-in test double with a route table, observed-request list, and `aclose_calls` counter.
53-
- **Status-keyed exception hierarchy** — `StatusError`, 4xx / 5xx subclasses, plain typed fields (`status: int`, `body: bytes`, `headers`, `json`, `request_method`, `request_url`). Pickleable; userinfo redacted in `__repr__`.
54-
- **No `httpx2` exception types** leak through `httpware`. The transport seam maps them to `httpware` exceptions.
48+
## 📦 [PyPI](https://pypi.org/project/httpware)
49+
50+
## 📝 [License](./LICENSE)
5551

5652
## Part of `modern-python`
5753

5854
Browse the full list of templates and libraries in [`modern-python`](https://github.com/modern-python) — see the org profile for the categorized index.
59-
60-
## License
61-
62-
MIT — see [LICENSE](./LICENSE).

‎docs/archive/README.md‎

Lines changed: 0 additions & 17 deletions
This file was deleted.

0 commit comments

Comments
 (0)