You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 671b495
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: CLAUDE.md
+5-6Lines changed: 5 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,12 +8,11 @@ Guidance for AI agents (Claude Code, etc.) working in this repository.
8
8
9
9
**Where to find what:**
10
10
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).
15
14
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.
17
16
18
17
## Commands
19
18
@@ -99,5 +98,5 @@ Five documented internal boundaries. AI agents must respect them — never cross
99
98
100
99
## When in doubt
101
100
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.
103
102
- Surface ambiguity as a documentation gap rather than improvising.
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:
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.
Copy file name to clipboardExpand all lines: README.md
+7-15Lines changed: 7 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,9 +7,9 @@
7
7
8
8
**Async HTTP client framework for Python.**
9
9
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.
11
11
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.
13
13
14
14
## Install
15
15
@@ -23,7 +23,7 @@ Optional extras:
23
23
pip install httpware[msgspec] # MsgspecDecoder
24
24
```
25
25
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.)
-**`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.
-**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)
55
51
56
52
## Part of `modern-python`
57
53
58
54
Browse the full list of templates and libraries in [`modern-python`](https://github.com/modern-python) — see the org profile for the categorized index.
0 commit comments