|
| 1 | +# Release 0.1.0 prep (design) |
| 2 | + |
| 3 | +- **Date:** 2026-05-31 |
| 4 | +- **Status:** approved, ready for plan |
| 5 | +- **Scope:** Prep the repository for the first PyPI release (`0.1.0` alpha). Single PR delivers all repo-side edits; the GitHub Release that triggers the publish workflow is a separate manual action by the maintainer. Out of scope: writing user docs site (Epic 6), Trusted Publishers / Sigstore release flow (Story 6-5), feature work toward v1.0. |
| 6 | +- **Why now:** Epic 1 is complete (PRs #1–#13). The middleware foundation (2-1/2-2/2-3) is shipped. `AsyncClient` is the working public surface. Users can do meaningful work with the current API; further iteration benefits from real consumer feedback. Modern-di-style alpha release model: tag now, iterate, no CHANGELOG file (release notes live on GitHub Releases). |
| 7 | + |
| 8 | +## Decisions |
| 9 | + |
| 10 | +| Decision | Choice | |
| 11 | +| --- | --- | |
| 12 | +| Release model | Alpha. `0.1.0` declares the API in flux until v1.0; minor releases may break things. Matches modern-di's pre-1.0 posture. | |
| 13 | +| CHANGELOG.md | **Delete.** modern-di in the same org doesn't have one. Release notes live on GitHub Releases (one entry per tag). | |
| 14 | +| README.md | Strict trim: only document what actually ships. Remove the resilience-middleware / observability / OTel bullets. Add an explicit "what's not yet shipped" line under the status banner. | |
| 15 | +| pyproject.toml | Untouched. `version = "0"` stays as the placeholder; the publish recipe overrides via `uv version $GITHUB_REF_NAME`. | |
| 16 | +| Tag format | Bare `0.1.0` (no `v` prefix). Matches modern-di. | |
| 17 | +| Publish workflow | Add `.github/workflows/publish.yml` mirroring modern-di's. Triggered by `release: published`. Runs `just publish`. | |
| 18 | +| Justfile | Untouched. `just publish` already does `rm -rf dist && uv version $GITHUB_REF_NAME && uv build && uv publish --token $PYPI_TOKEN`. | |
| 19 | +| PyPI name | Must verify ownership of `httpware` on PyPI before tagging. The package URL returns HTTP 200; check via `pypi.org/pypi/httpware/json` whether the owner is `modern-python` (our project) or a third party. | |
| 20 | +| Engineering.md roadmap | Unchanged for this PR. Adding "Released" markers is a tiny follow-up commit (not in scope here). | |
| 21 | +| Out-of-scope feature work | None added in this PR. The repo ships what's already on `main` at `204d463`. | |
| 22 | + |
| 23 | +## What ships in 0.1.0 — public surface |
| 24 | + |
| 25 | +| Symbol | Import | |
| 26 | +| --- | --- | |
| 27 | +| `AsyncClient` | `from httpware import AsyncClient` | |
| 28 | +| `Request`, `Response`, `StreamResponse` | `from httpware import Request, Response, StreamResponse` | |
| 29 | +| `Limits`, `Timeout`, `ClientConfig` | `from httpware import Limits, Timeout, ClientConfig` | |
| 30 | +| `Transport`, `Httpx2Transport`, `RecordedTransport` | `from httpware import …` | |
| 31 | +| `ResponseDecoder`, `PydanticDecoder` | `from httpware import ResponseDecoder, PydanticDecoder` | |
| 32 | +| `MsgspecDecoder` | `from httpware.decoders.msgspec import MsgspecDecoder` (gated by `[msgspec]` extra) | |
| 33 | +| `Middleware`, `Next` | `from httpware import Middleware, Next` | |
| 34 | +| `before_request`, `after_response`, `on_error` | `from httpware import …` | |
| 35 | +| Exception hierarchy | `from httpware import StatusError, TransportError, TimeoutError, ClientError, ServerStatusError, ClientStatusError, STATUS_TO_EXCEPTION, BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitedError, InternalServerError, ServiceUnavailableError` | |
| 36 | + |
| 37 | +Behind the seam: `httpware._internal.chain.compose`, `httpware._internal.import_checker`. |
| 38 | + |
| 39 | +## What 0.1.0 does NOT ship |
| 40 | + |
| 41 | +- `auth=` parameter on `AsyncClient` (Story 2-4). |
| 42 | +- `data=` / `files=` body params on HTTP methods. |
| 43 | +- Transport reference-counting on `with_options` views. |
| 44 | +- Retry / timeout / bulkhead / RetryBudget middleware (Epic 3). |
| 45 | +- Streaming (`AsyncClient.stream`) — `StreamResponse` is a placeholder stub (Epic 4). |
| 46 | +- Observability hooks / OpenTelemetry middleware (Epic 5). |
| 47 | +- `niquests` transport (declared as an extra but not yet implemented). |
| 48 | +- User documentation site (mkdocs / readthedocs — Epic 6). |
| 49 | +- Migration guide from `community-of-python/base-client` (Story 6-1). |
| 50 | +- Public benchmark suite (Story 6-3). |
| 51 | +- CI enforcement gates beyond what's currently in `ci.yml` (Story 6-4). |
| 52 | +- Trusted Publishers + Sigstore release flow (Story 6-5; we use the simpler token-based publish for now). |
| 53 | +- CHANGELOG.md. |
| 54 | + |
| 55 | +## Edits in the prep PR |
| 56 | + |
| 57 | +**Deleted files:** |
| 58 | +- `CHANGELOG.md` — release notes live on GitHub Releases going forward. |
| 59 | + |
| 60 | +**New files:** |
| 61 | +- `.github/workflows/publish.yml` — mirrors modern-di. Triggered by `release: published`, runs `just publish`. Reads `PYPI_TOKEN` from repo secrets. |
| 62 | + |
| 63 | +**Modified files:** |
| 64 | +- `README.md` — strict trim per Section 2 of the brainstorm. Remove the "Highlights" bullets for unshipped features. Update the status banner to name the unshipped categories (resilience middleware, streaming, observability). Drop the CHANGELOG link. |
| 65 | +- `CONTRIBUTING.md` — check for and remove any reference to `CHANGELOG.md`. If the existing CONTRIBUTING doesn't mention it, no change needed. |
| 66 | +- `CLAUDE.md` — same check; remove `CHANGELOG.md` references if present. |
| 67 | + |
| 68 | +**Files NOT touched:** |
| 69 | +- `pyproject.toml` — `version = "0"` stays; publish recipe overrides. |
| 70 | +- `Justfile` — `publish` recipe already correct. |
| 71 | +- `.github/workflows/ci.yml` — no changes to test/lint matrix. |
| 72 | +- `src/httpware/**` — no code changes. |
| 73 | +- `tests/**` — no test changes. |
| 74 | +- `LICENSE`, `SECURITY.md` — unchanged. |
| 75 | +- `docs/engineering.md` — internal roadmap stays; "Released" markers are a follow-up. |
| 76 | +- `docs/archive/**` — bmad archive untouched. |
| 77 | + |
| 78 | +## `.github/workflows/publish.yml` content |
| 79 | + |
| 80 | +```yaml |
| 81 | +name: Publish Package |
| 82 | + |
| 83 | +on: |
| 84 | + release: |
| 85 | + types: |
| 86 | + - published |
| 87 | + |
| 88 | +jobs: |
| 89 | + publish: |
| 90 | + runs-on: ubuntu-latest |
| 91 | + steps: |
| 92 | + - uses: actions/checkout@v4 |
| 93 | + - uses: extractions/setup-just@v2 |
| 94 | + - uses: astral-sh/setup-uv@v3 |
| 95 | + - run: just publish |
| 96 | + env: |
| 97 | + PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} |
| 98 | +``` |
| 99 | +
|
| 100 | +Byte-for-byte identical to modern-di's `publish.yml`. No customization needed. |
| 101 | + |
| 102 | +## README.md content (final) |
| 103 | + |
| 104 | +```markdown |
| 105 | +# httpware |
| 106 | +
|
| 107 | +[](https://github.com/modern-python/httpware/actions/workflows/ci.yml) |
| 108 | +[](https://pypi.org/project/httpware/) |
| 109 | +[](https://pypi.org/project/httpware/) |
| 110 | +[](https://opensource.org/licenses/MIT) |
| 111 | +
|
| 112 | +**Async HTTP client framework for Python.** |
| 113 | +
|
| 114 | +`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. |
| 115 | + |
| 116 | +> **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. |
| 117 | + |
| 118 | +## Install |
| 119 | + |
| 120 | +\`\`\`bash |
| 121 | +pip install httpware |
| 122 | +\`\`\` |
| 123 | + |
| 124 | +Optional extras: |
| 125 | + |
| 126 | +\`\`\`bash |
| 127 | +pip install httpware[msgspec] # MsgspecDecoder |
| 128 | +\`\`\` |
| 129 | + |
| 130 | +(`otel`, `niquests`, and `all` extras are declared but their integrations have not shipped yet.) |
| 131 | + |
| 132 | +## Quickstart |
| 133 | + |
| 134 | +\`\`\`python |
| 135 | +from httpware import AsyncClient |
| 136 | +from pydantic import BaseModel |
| 137 | + |
| 138 | + |
| 139 | +class User(BaseModel): |
| 140 | + id: int |
| 141 | + name: str |
| 142 | + |
| 143 | + |
| 144 | +async def main() -> None: |
| 145 | + async with AsyncClient(base_url="https://api.example.com") as client: |
| 146 | + user = await client.get("/users/1", response_model=User) |
| 147 | + print(user.name) |
| 148 | +\`\`\` |
| 149 | + |
| 150 | +## What ships in 0.1.0 |
| 151 | + |
| 152 | +- **`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. |
| 153 | +- **Transport-agnostic seam.** `httpx2` is confined to `httpware.transports.httpx2.Httpx2Transport`. Implement the `Transport` protocol to swap backends. |
| 154 | +- **Middleware foundation.** `Middleware` protocol, `Next` type alias, recursive-closure `compose()` chain composition, and phase decorators (`@before_request`, `@after_response`, `@on_error`). |
| 155 | +- **Pluggable response decoding.** `PydanticDecoder` (default) with cached `TypeAdapter`; `MsgspecDecoder` via `httpware[msgspec]`. |
| 156 | +- **`RecordedTransport`** — built-in test double with a route table, observed-request list, and `aclose_calls` counter. |
| 157 | +- **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__`. |
| 158 | +- **No `httpx2` exception types** leak through `httpware`. The transport seam maps them to `httpware` exceptions. |
| 159 | + |
| 160 | +## Part of `modern-python` |
| 161 | + |
| 162 | +Browse the full list of templates and libraries in [`modern-python`](https://github.com/modern-python) — see the org profile for the categorized index. |
| 163 | + |
| 164 | +## License |
| 165 | + |
| 166 | +MIT — see [LICENSE](./LICENSE). |
| 167 | +``` |
| 168 | + |
| 169 | +The triple-backticks above use backslash-escapes in this spec because the spec itself is markdown; in the actual `README.md` they're real triple-backticks. |
| 170 | + |
| 171 | +## Release execution (post-merge, manual maintainer actions) |
| 172 | + |
| 173 | +These steps are NOT part of the PR. They run after the prep PR merges to `main`. |
| 174 | + |
| 175 | +1. **Verify PyPI name ownership:** |
| 176 | + |
| 177 | + ```bash |
| 178 | + curl -s https://pypi.org/pypi/httpware/json \ |
| 179 | + | python -c "import sys, json; d=json.load(sys.stdin); info=d.get('info', {}); print('home:', info.get('home_page')); print('project_urls:', info.get('project_urls')); print('author:', info.get('author'))" |
| 180 | + ``` |
| 181 | + |
| 182 | + Decision tree: |
| 183 | + - Homepage / project_urls point to `github.com/modern-python/httpware` → name is ours, proceed. |
| 184 | + - Different owner → STOP. Rename or open a PyPI name-transfer request. Don't tag. |
| 185 | + - Returns 404 → name is free, proceed. |
| 186 | + |
| 187 | +2. **Verify `PYPI_TOKEN` secret exists on the repo:** |
| 188 | + |
| 189 | + ```bash |
| 190 | + gh secret list --repo modern-python/httpware | grep PYPI_TOKEN |
| 191 | + ``` |
| 192 | + |
| 193 | + If absent, add it via `gh secret set PYPI_TOKEN --repo modern-python/httpware` with a PyPI account token scoped to the `httpware` project. |
| 194 | + |
| 195 | +3. **Create the GitHub Release (triggers publish workflow):** |
| 196 | + |
| 197 | + ```bash |
| 198 | + gh release create 0.1.0 \ |
| 199 | + --title "0.1.0 — initial alpha" \ |
| 200 | + --notes-file - <<'EOF' |
| 201 | + Initial public alpha of `httpware`. |
| 202 | +
|
| 203 | + **Includes:** |
| 204 | + - AsyncClient with 8 HTTP method shortcuts and typed `response_model` overloads |
| 205 | + - Transport-agnostic seam (`httpx2` confined to `Httpx2Transport`) |
| 206 | + - Middleware foundation: `Middleware` protocol, `compose()`, phase decorators |
| 207 | + - Pluggable response decoders: `PydanticDecoder` (default), `MsgspecDecoder` via `[msgspec]` extra |
| 208 | + - `RecordedTransport` test double |
| 209 | + - Status-keyed exception hierarchy |
| 210 | +
|
| 211 | + **Not yet shipped (next releases):** |
| 212 | + - Resilience middleware (retry, timeout, bulkhead) — Epic 3 |
| 213 | + - Streaming (`AsyncClient.stream`) — Epic 4 |
| 214 | + - Observability / OpenTelemetry — Epic 5 |
| 215 | + - `auth=` parameter on AsyncClient — Story 2-4 |
| 216 | + - `data=` / `files=` body params |
| 217 | +
|
| 218 | + Public API is subject to change between minor releases until v1.0. |
| 219 | + EOF |
| 220 | + ``` |
| 221 | +
|
| 222 | + The release publication triggers `publish.yml` → `just publish` → `uv version 0.1.0 && uv build && uv publish --token`. The workflow's status appears in the Actions tab. |
| 223 | +
|
| 224 | +4. **Smoke-check the published package:** |
| 225 | +
|
| 226 | + ```bash |
| 227 | + # In a fresh venv: |
| 228 | + pip install httpware==0.1.0 |
| 229 | + python -c "import httpware; from httpware import AsyncClient, Middleware, RecordedTransport; print('OK:', httpware.__file__)" |
| 230 | + ``` |
| 231 | +
|
| 232 | + Expected: `OK: …/site-packages/httpware/__init__.py`. If import fails or names are missing, a `0.1.1` patch follows the same release cycle. |
| 233 | +
|
| 234 | +## Constraints and invariants |
| 235 | +
|
| 236 | +- **No production code changes.** This PR ships only documentation and CI workflow edits. |
| 237 | +- **No `httpx2` import added.** `tests/test_no_httpx2_leakage.py` keeps passing. |
| 238 | +- **`just lint-ci` keeps passing.** ruff, ty, eof-fixer all clean. |
| 239 | +- **`just test` keeps passing.** 273 tests at 100% line coverage on the source. |
| 240 | +
|
| 241 | +## Risks and mitigations |
| 242 | +
|
| 243 | +| Risk | Mitigation | |
| 244 | +| --- | --- | |
| 245 | +| PyPI name `httpware` is owned by someone else. | The maintainer verifies via the PyPI JSON API before tagging. If owned, stop and rename or transfer. No code-level change anticipated for this case. | |
| 246 | +| `PYPI_TOKEN` secret missing. | `gh secret list` check before tagging; add via `gh secret set` if absent. | |
| 247 | +| The publish workflow fails mid-build (e.g., `uv build` error on a CI runner that differs from local). | The tag stays; the workflow can be re-run from the Actions tab. If a content change is needed, a `0.1.1` follow-up tag publishes the fix. The repo doesn't accumulate state from a failed publish. | |
| 248 | +| Users install 0.1.0 and try to use `Retry` / `Timeout` / OTel middleware (which aren't shipped). | README's status banner names the unshipped categories explicitly. Each feature's import would fail loudly (`ImportError`), not silently. | |
| 249 | +| Documentation site URL (`https://httpware.readthedocs.io`) referenced in pyproject.toml doesn't resolve. | Keep the URL as a forward-pointer (matches modern-di which has the same pattern). Users see the broken link; not a release blocker. Epic 6's mkdocs site lights it up later. | |
| 250 | +| Renaming the package later (if PyPI name is contested) is disruptive. | The maintainer verifies name ownership BEFORE any consumer can depend on the published name. The 0.1.0 wheel never lands on PyPI unless the name is ours. | |
| 251 | +
|
| 252 | +## Definition of done |
| 253 | +
|
| 254 | +- `CHANGELOG.md` deleted. |
| 255 | +- `.github/workflows/publish.yml` exists with the modern-di-pattern content. |
| 256 | +- `README.md` updated to the trimmed content from Section 2 of the brainstorm / the README block above. |
| 257 | +- `CONTRIBUTING.md` and `CLAUDE.md` checked for `CHANGELOG.md` references; updated if any were present. |
| 258 | +- `just test` and `just lint-ci` clean. |
| 259 | +- `tests/test_no_httpx2_leakage.py` still passes. |
| 260 | +- PR `chore/release-0.1.0-prep` lands on `main` via merge. |
| 261 | +- Post-merge actions (PyPI name check, secret verification, GitHub Release creation) execute successfully; `0.1.0` lands on PyPI; `pip install httpware==0.1.0` works in a clean venv. |
0 commit comments