httpr 0.6.0__tar.gz → 0.7.1__tar.gz

{httpr-0.6.0 → httpr-0.7.1}/.github/copilot-instructions.md

@@ -84,7 +84,7 @@ with client.stream("GET", url) as response:
 ## Critical Details
 
 - **Body types mutually exclusive:** `content` (bytes) | `data` (form) | `json` | `files` (multipart)
-- **SSL:** `ca_cert_file` sets `HTTPR_CA_BUNDLE` env var; `verify=False` for insecure
+- **SSL:** `ca_cert_file` param, else `HTTPR_CA_BUNDLE` env var as default (read-only, scoped per client); `verify=False` for insecure
 - **Proxy:** `proxy` param or `HTTPR_PROXY` env var; changing rebuilds entire client
 - **Python types:** `IndexMap<String, String, RandomState>` in Rust ↔ `dict[str, str]` in Python
 

{httpr-0.6.0 → httpr-0.7.1}/.github/workflows/benchmark.yml

@@ -62,7 +62,7 @@ jobs:
       - name: Run benchmarks
         env:
           BENCHMARK_SERVER_URL: "http://127.0.0.1:8000"
-        run: uv run pytest tests/benchmark/ --benchmark-only --benchmark-json=benchmark-results.json
+        run: uv run pytest tests/benchmark/test_performance.py --benchmark-only --benchmark-json=benchmark-results.json
 
       - name: Store benchmark result
         uses: benchmark-action/github-action-benchmark@v1

httpr-0.7.1/.github/workflows/codspeed.yml

@@ -0,0 +1,50 @@
+name: CodSpeed
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  # Lets CodSpeed trigger a backtest run to generate the initial baseline data.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write # OpenID Connect authentication with CodSpeed
+
+jobs:
+  benchmarks:
+    name: Run benchmarks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Cache Rust build
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: rust-codspeed-${{ runner.os }}-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            rust-codspeed-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      # Benchmarks must run against an optimised build, otherwise they measure
+      # debug assertions and unoptimised Rust rather than shipped code.
+      - name: Build Rust extension (release mode)
+        run: uv run maturin develop --release
+
+      - name: Run benchmarks
+        uses: CodSpeedHQ/action@v5
+        with:
+          mode: simulation
+          # --no-sync keeps uv from replacing the release build made above.
+          run: uv run --no-sync pytest tests/benchmark/codspeed --codspeed

httpr-0.7.1/.github/workflows/compare.yml

@@ -0,0 +1,153 @@
+name: Client comparison
+
+# Weekly comparison of httpr against the latest release of every other HTTP
+# client in benchmark/benchmark.py. Results are published to gh-pages at
+# dev/bench/compare/ (chart, tables, CSVs) and embedded in the README and docs.
+
+on:
+  schedule:
+    - cron: "0 6 * * 1" # Mondays 06:00 UTC
+  workflow_dispatch:
+    inputs:
+      httpr_source:
+        description: "Which httpr to benchmark"
+        type: choice
+        default: pypi
+        options:
+          - pypi # latest release, what `pip install httpr` gives (the scheduled default)
+          - main # a wheel built from the checked-out commit
+      publish:
+        description: "Publish the results to gh-pages"
+        type: boolean
+        default: true
+
+permissions:
+  contents: write
+
+concurrency:
+  group: gh-pages-compare
+  cancel-in-progress: false
+
+jobs:
+  compare:
+    name: HTTP-client comparison
+    runs-on: ubuntu-latest
+    env:
+      HTTPR_SOURCE: ${{ github.event_name == 'workflow_dispatch' && inputs.httpr_source || 'pypi' }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Cache Rust build
+        if: env.HTTPR_SOURCE == 'main'
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: rust-bench-${{ runner.os }}-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            rust-bench-${{ runner.os }}-
+
+      - name: Build httpr wheel (release mode)
+        if: env.HTTPR_SOURCE == 'main'
+        run: uv build --wheel --out-dir dist
+
+      - name: Start benchmark server
+        env:
+          BENCHMARK_HOST: 127.0.0.1
+          BENCHMARK_PORT: "8000"
+        run: |
+          uv run --script benchmark/server.py &
+          for i in $(seq 1 10); do
+            if curl -sf http://127.0.0.1:8000/json/1 > /dev/null 2>&1; then
+              echo "Benchmark server is ready"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "Benchmark server failed to start"
+          exit 1
+
+      - name: Run comparison
+        run: |
+          mkdir -p compare
+          cd compare
+          # --refresh: re-check the index so every library resolves to its newest release.
+          # The script has no lockfile, so unpinned dependencies float on purpose.
+          UV_ARGS=(--refresh)
+          BENCH_ARGS=()
+          if [ "$HTTPR_SOURCE" = "main" ]; then
+            UV_ARGS+=(--with ../dist/httpr-*.whl)
+            BENCH_ARGS+=(--httpr-version "${GITHUB_SHA::7}")
+          fi
+          uv run "${UV_ARGS[@]}" --script ../benchmark/benchmark.py "${BENCH_ARGS[@]}" | tee standard.log
+          uv run "${UV_ARGS[@]}" --script ../benchmark/benchmark.py "${BENCH_ARGS[@]}" --run_multithread | tee multithread.log
+
+      - name: Render chart and tables
+        run: |
+          uv run --script benchmark/render_comparison.py \
+            --results compare --out compare/site \
+            --run-url "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+
+      - name: Write job summary
+        run: |
+          {
+            echo "## HTTP-client comparison (httpr from ${HTTPR_SOURCE})"
+            echo
+            echo "The chart is in the run artifact; the published copy is at https://thomasht86.github.io/httpr/dev/bench/compare/"
+            sed '1d' compare/site/comparison.md
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload results
+        uses: actions/upload-artifact@v6
+        with:
+          name: client-comparison-${{ github.run_id }}
+          path: |
+            compare/*.log
+            compare/site/
+
+      - name: Publish to gh-pages
+        if: ${{ github.event_name == 'schedule' || inputs.publish }}
+        env:
+          GIT_AUTHOR_NAME: github-actions[bot]
+          GIT_AUTHOR_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com
+          GIT_COMMITTER_NAME: github-actions[bot]
+          GIT_COMMITTER_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com
+        run: |
+          set -euo pipefail
+          git clone --depth 1 --branch gh-pages \
+            "https://x-access-token:${{ github.token }}@github.com/${GITHUB_REPOSITORY}.git" gh-pages
+          STAMP="$(date -u +%Y-%m-%d)"
+          publish() {
+            DEST=gh-pages/dev/bench/compare
+            mkdir -p "$DEST/history/$STAMP"
+            cp compare/site/* "$DEST/"
+            # Keep a dated copy of the raw numbers so trends can be plotted later.
+            cp compare/site/*.csv compare/site/comparison.md "$DEST/history/$STAMP/"
+            git -C gh-pages add -A dev/bench/compare
+            if git -C gh-pages diff --cached --quiet; then
+              echo "No changes to publish"
+              return 0
+            fi
+            git -C gh-pages commit -q -m "Client comparison ${STAMP} (httpr from ${HTTPR_SOURCE})"
+            git -C gh-pages push origin gh-pages
+          }
+          # The docs deploy and the benchmark action also push to gh-pages. On a
+          # rejected push, start over from the new tip rather than rebasing a
+          # shallow clone.
+          for attempt in 1 2 3 4 5; do
+            if publish; then
+              exit 0
+            fi
+            echo "push rejected, retrying from the current gh-pages tip (attempt $attempt)"
+            sleep 10
+            git -C gh-pages fetch --depth 1 origin gh-pages
+            git -C gh-pages reset -q --hard FETCH_HEAD
+          done
+          echo "Could not push to gh-pages after 5 attempts"
+          exit 1

{httpr-0.6.0 → httpr-0.7.1}/.github/workflows/mkdocs.yml

@@ -42,15 +42,19 @@ jobs:
           # Fetch gh-pages branch
           git fetch origin gh-pages:gh-pages || true
 
-          # Save benchmark data if it exists
+          # Save everything under dev/bench (httpr trend chart, client comparison)
           mkdir -p /tmp/bench-backup
-          if git show gh-pages:dev/bench/data.js > /tmp/bench-backup/data.js 2>/dev/null; then
-            echo "Found existing benchmark data.js, will preserve it"
-          fi
-          if git show gh-pages:dev/bench/index.html > /tmp/bench-backup/index.html 2>/dev/null; then
-            echo "Found existing benchmark index.html, will preserve it"
+          if git rev-parse --verify --quiet gh-pages:dev/bench > /dev/null; then
+            git archive gh-pages dev/bench | tar -x -C /tmp/bench-backup
+            echo "Preserving dev/bench from gh-pages"
           fi
 
+          # Drop everything untracked before switching branches: the docs build
+          # leaves the compiled extension, __pycache__, .venv and site/ in the
+          # tree, and `git add -A` below would otherwise commit them to gh-pages
+          # (site/ is already saved in /tmp/site-backup).
+          git clean -fdxq
+
           # Switch to gh-pages branch
           git checkout gh-pages || git checkout --orphan gh-pages
 
@@ -64,12 +68,11 @@ jobs:
           fi
           cp -r /tmp/site-backup/* .
 
-          # Restore benchmark data if it existed
-          if [ -f /tmp/bench-backup/data.js ] || [ -f /tmp/bench-backup/index.html ]; then
-            mkdir -p dev/bench
-            [ -f /tmp/bench-backup/data.js ] && cp /tmp/bench-backup/data.js dev/bench/
-            [ -f /tmp/bench-backup/index.html ] && cp /tmp/bench-backup/index.html dev/bench/
-            echo "Restored benchmark chart files"
+          # Restore dev/bench
+          if [ -d /tmp/bench-backup/dev/bench ]; then
+            mkdir -p dev
+            cp -r /tmp/bench-backup/dev/bench dev/
+            echo "Restored dev/bench"
           fi
 
           # Add all files and commit

{httpr-0.6.0 → httpr-0.7.1}/.gitignore

@@ -89,4 +89,7 @@ site/
 .certs/
 
 # Taskfile cache
-.task/
+.task/
+
+# Claude Code local state (worktrees, settings)
+.claude/

httpr-0.7.1/CLAUDE.md

@@ -0,0 +1,226 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**httpr** is a high-performance HTTP client for Python built in Rust using PyO3 and reqwest. It's designed as a drop-in replacement for `httpx` and `requests` with significantly better performance.
+
+## Build & Development Commands
+
+```bash
+# Install development dependencies
+uv sync --extra dev
+
+# Build Rust extension (required after any Rust code changes)
+uv run maturin develop
+
+# Run tests (depends on httpbin.org)
+uv run pytest tests/
+
+# Type checking
+uv run mypy httpr/
+
+# Linting
+uv run ruff check httpr/
+```
+
+### Pre-commit Hooks
+
+Set up pre-commit hooks to automatically lint and format code before commits:
+
+```bash
+# Install pre-commit
+uv pip install pre-commit
+
+# Install git hooks
+pre-commit install
+pre-commit install --hook-type commit-msg
+
+# Run all hooks manually (optional)
+pre-commit run --all-files
+```
+
+Configured hooks (see `.pre-commit-config.yaml`):
+- **ruff**: Python linting and formatting
+- **mypy**: Python type checking (httpr/ only)
+- **cargo fmt/clippy**: Rust formatting and linting
+- **commitizen/commitlint**: Conventional commit messages
+
+### Taskfile Commands
+
+This project uses [Taskfile](https://taskfile.dev) for development workflows:
+
+```bash
+task --list        # List all available tasks
+
+# Testing
+task test:unit     # Run unit tests only
+task test:e2e      # Run e2e tests (requires httpbun running)
+task e2e           # Full e2e workflow: certs → start httpbun → test → stop
+task e2e:local     # Start httpbun and run e2e tests (keep container running)
+
+# Development
+task dev           # Build Rust extension
+task check         # Run all checks (lint + test) - use before committing
+
+# Linting
+task lint          # Run Python linters (ruff + mypy)
+task lint:rust     # Run Rust linters (fmt + clippy)
+task lint:all      # Run all linters (Python + Rust)
+
+# Formatting
+task fmt           # Format Python code
+task fmt:rust      # Format Rust code
+task fmt:all       # Format all code
+```
+
+### E2E Tests with httpbun
+
+E2E tests use [httpbun](https://httpbun.com) in Docker with SSL certificates generated by trustme.
+
+```bash
+# One-time setup: add hosts entry
+echo '127.0.0.1 httpbun.local' | sudo tee -a /etc/hosts
+
+# Run full e2e workflow
+task e2e
+
+# Or run iteratively during development
+task e2e:local     # Starts httpbun and runs tests (keeps container running)
+task test:e2e      # Run e2e tests again
+task httpbun:stop  # Stop container when done
+```
+
+Key files:
+- `Taskfile.yaml` - Task definitions
+- `scripts/generate_certs.py` - SSL cert generation using trustme
+- `tests/e2e/` - E2E test files
+- `.certs/` - Generated certificates (gitignored)
+
+### Benchmarking
+
+Comparison against other HTTP clients (published weekly by `.github/workflows/compare.yml` to
+gh-pages `dev/bench/compare/`, rendered by `benchmark/render_comparison.py`, embedded in README and docs):
+
+```bash
+cd benchmark/
+uv run uvicorn server:app  # Terminal 1: Start test server
+uv run python benchmark.py  # Terminal 2: Run benchmarks
+```
+
+Regression tracking:
+
+```bash
+task test:benchmark        # Wall-clock suite (tests/benchmark/test_performance.py),
+                           # charted by github-action-benchmark on pushes to main
+task test:codspeed         # CodSpeed CPU-simulation suite (tests/benchmark/codspeed/),
+                           # reported on every PR by .github/workflows/codspeed.yml
+task test:codspeed:wall    # Same suite with plain wall-clock timings, no CodSpeed CLI
+```
+
+Always benchmark a release build (`uv run maturin develop --release`); `task dev`
+builds in debug mode and the numbers are meaningless.
+
+## Architecture
+
+### Rust Core (`src/`)
+- `lib.rs`: Main `RClient` class with sync request handling via single-threaded Tokio runtime (`LazyLock<Runtime>` with `new_current_thread()`)
+  - `request()` method: Buffers entire response body
+  - `_stream()` method: Returns `StreamingResponse` without buffering body
+- `response.rs`: Response objects with `CaseInsensitiveHeaderMap` for HTTP/2 compliant header handling
+  - `Response`: Standard response with buffered `content`
+  - `StreamingResponse`: Holds `Arc<Mutex<Option<reqwest::Response>>>` for chunk iteration
+  - `TextIterator`: Iterator for decoding chunks as text
+  - `LineIterator`: Iterator for line-by-line reading with internal buffer
+- `traits.rs`: Conversion traits between Python/Rust types (IndexMap ↔ HeaderMap)
+- `utils.rs`: CA certificate loading, encoding detection
+
+### Python Wrapper (`httpr/`)
+- `__init__.py`: `Client` (sync) and `AsyncClient` classes with context manager support
+  - `stream()` context manager wraps `_stream()` and handles cleanup
+  - Both `Client` and `AsyncClient` support streaming; `AsyncClient.stream()` yields an `AsyncStreamingResponse` wrapper with `async for` iteration
+  - `close()` / `__exit__` / `aclose()` / `__aexit__` really close the client (see "Client Lifecycle" below)
+- `AsyncClient` uses `asyncio.run_in_executor()` to wrap sync Rust calls - NOT native async
+- `httpr.pyi`: Type stubs for IDE support including `StreamingResponse`, `TextIterator`, `LineIterator`
+
+### Key Design Decisions
+1. **Single Tokio Runtime**: All async Rust operations run on one thread
+2. **Async is Sync**: `AsyncClient` runs sync Rust code in thread executor
+3. **Zero Python Dependencies**: All functionality in Rust
+4. **Case-Insensitive Headers**: Custom struct maintains original casing while allowing case-insensitive lookups (HTTP/2 requirement)
+5. **Streaming**: `StreamingResponse` holds reqwest response and provides chunk iteration without buffering entire body
+
+## Critical Implementation Details
+
+### Python-Rust Interface
+- All Python params converted to strings before passing to Rust
+- HTTP method validation happens in Python wrapper
+- Rust uses `IndexMap<String, String, RandomState>` (foldhash) for dicts
+- Use `Unpack` for `**kwargs` typing (via typing_extensions for Python ≤3.11)
+
+### SSL/TLS
+- CA bundle is resolved per client: the `ca_cert_file` param wins, otherwise the `HTTPR_CA_BUNDLE` env var is used as a default
+- The env var is only ever read, never written; `ca_cert_file` is scoped to the client that passed it (see issue #86)
+- mTLS via `client_pem` parameter (file path, PEM format) or `client_pem_data` (bytes, PEM format)
+- `client_pem_data` allows passing certificates without filesystem access (useful for containers/secrets managers)
+- `verify=False` enables `danger_accept_invalid_certs()`
+
+### Headers Behavior
+- Headers are lowercased internally (HTTP/2 spec)
+- `client.headers` getter returns a live `_ClientHeaders` view; in-place mutations (`__setitem__`, `del`, `update`, `pop`, `popitem`, `setdefault`, `clear`) mirror to the client via Rust `set_header`/`del_header`
+- `client.headers` getter excludes `Cookie` header; `set_headers` preserves the existing `Cookie` header so header mutation never clobbers cookies
+- `client.cookies` getter/setter extracts from `Cookie` header
+- Per-request `cookies` are merged into the client's `Cookie` header (request wins per name) so exactly one `Cookie` header is sent (RFC 6265 §5.4; issue #82). Do not append a second header
+
+### Query Parameters (issues #82, #87)
+- `params` (client-level and per-request) and form `data` are normalised in Rust (`src/params.rs`) into ordered `(key, value)` pairs with httpx rules: `True`/`False` → `true`/`false`, `None` → empty, list/tuple → repeated key, else `str()`. Accepts a mapping or a sequence of pairs. There is no Python-side `str(v)` coercion any more; do not re-add one
+- Client params are merged with request params: client pairs first, then the request's; a key the request supplies replaces the client's values for it. `client.params` returns a dict whose values are `str` or `list[str]` for repeated keys and round-trips through the setter
+- Request building (`build_request`, `send_request`, `response_meta` in `src/lib.rs`) is shared by `request()` and `_stream()`; change it once
+
+### Request Body
+- Mutually exclusive: `content` (bytes), `data` (form), `json` (JSON), `files` (multipart)
+- A body is sent for any method the caller supplies one for, including GET/DELETE/OPTIONS (RFC 9110, matches httpx; issue #83). Do not re-add a POST/PUT/PATCH guard
+- `json` uses `pythonize::depythonize()`; `data` goes through `normalize_params` so list values become repeated fields and insertion order is preserved (serde_json would alphabetise)
+- `files` dict maps field names to file paths
+
+### Proxy
+- Set via `proxy` param or `HTTPR_PROXY` env var; the env var is read once in `new()`, never in the setter
+- Changing `client.proxy` rebuilds the entire reqwest client (expensive). `RClient.config: ClientConfig` keeps the construction settings (loaded root certs, mTLS `Identity`, redirects, verify, https_only, http2_only, cookie_store, referer) and `ClientConfig::build()` is the single place a `reqwest::Client` is built, used by `new()` and `set_proxy()`; add any new builder setting there, not inline (issue #84). The setter takes `Option<String>`; `None` removes the proxy. The rebuilt client starts with an empty cookie store
+
+### Client Lifecycle (issue #88)
+- All lifecycle state lives in `src/lifecycle.rs`: `ClientState` (`Arc`-shared between an `RClient` and its in-flight requests) holds `client: Mutex<Option<reqwest::Client>>`, an `in_flight` counter and a `CancellationToken` for pending connects. `RClient::close()` takes the client (`None`); dropping the `reqwest::Client` drops the client's handle to its connection pool
+- Connection tasks live on the single-threaded `RUNTIME` and only progress inside `block_on`, so dropping a pool does not close sockets by itself: `settle_dropped_pool()` runs a fixed number of `yield_now` turns so the connection tasks observe the hang-up and send FIN (deterministic, never waits on I/O). Each turn is a driver-poll syscall and this runs on every close/drop, so keep `SETTLE_SCHEDULER_TURNS` small: 4 costs ~40 µs, 32 doubled the create-request-close benchmark (`test_single_request`). The first turn already drains the whole wake-up chain; the rest are margin. If another thread holds the scheduler core (it is mid-request), its scheduler closes them instead
+- Overlapping requests make hyper race a fresh connect against the idle-pool checkout; a losing connect is finished in the background and holds the pool alive until it resolves, which needs real I/O and against a remote host can take longer than `close()` should wait. So every `reqwest::Client` is built with `CancelConnectsLayer` (a tower layer over reqwest's connector, via `ClientBuilder::connector_layer`) and `close()` cancels the token when nothing is in flight; cancelled connects resolve on the next scheduler turn and drop their pool handle. Do not replace this with waiting or with `num_alive_tasks` heuristics: the count is runtime-global and a pending connect keeps it constant
+- `begin_request()` increments `in_flight` before cloning the `reqwest::Client`, so a request already in flight keeps the pool alive and finishes normally when the client is closed underneath it. While anything is in flight `close()` only drops its own handle and yields; the `InFlight` guard of the last request to finish (in `request()` after the body is buffered, or `StreamingResponse::close()`/drop for streams) cancels pending connects and settles. `StreamingResponse` owns its `InFlight` for its whole lifetime, since its connection stays busy until it is closed
+- `set_proxy` swaps the client via `ClientState::replace()` and settles the old pool; it raises `ClientClosed` on a closed client. `RClient` implements `Drop`, so a client garbage-collected without `close()` releases its pool as well (safe: every `block_on` in the crate runs with the GIL released, so dealloc never happens inside one)
+- Use after close raises `ClientClosed`, a `RuntimeError` subclass (httpx raises plain `RuntimeError` here); header/cookie getters keep working. `is_closed` getter mirrors httpx. The message lives once in Rust (`CLIENT_CLOSED_MSG`, exported as `_CLIENT_CLOSED_MSG`)
+- Python: `Client.close()`/`__exit__` call the Rust `close()`; `AsyncClient.aclose()`/`__aexit__` additionally `shutdown(wait=False)` the client's own `ThreadPoolExecutor`, and run on the event-loop thread on purpose (sub-millisecond, no I/O wait). `_run_sync_asyncio` checks `is_closed` first and also maps the executor's "cannot schedule new futures after shutdown" `RuntimeError` to `ClientClosed`, which covers a `close()` racing in from another OS thread
+- Leaving a `with`/`async with` block closes the client; re-entering it afterwards raises `ClientClosed` on the next request. pyvespa's `VespaSync`/`VespaAsync` given an external session never close it and are unaffected; with an owned client they close but never null it, so re-entering the same wrapper object raises `ClientClosed` (see memory note; needs a pyvespa-side fix)
+
+### Timeouts (issue #81)
+- Default `timeout` is 30 s and lives in the PyO3 `#[new]` signature in `src/lib.rs`; `Client.__init__` in Python only documents the parameters and forwards nothing, so its defaults must match Rust's (`test_python_signature_matches_rust_defaults` enforces this). `None` disables the timeout
+- The timeout is an inactivity bound, not a total deadline: `src/timeout.rs` wraps the wait for the response headers (`send_request`) and the wait for each body chunk (`read_body` for buffered responses, `next_chunk` for `StreamingResponse` and its iterators) in `tokio::time::timeout`. A stream that keeps delivering data is never cut off, matching httpx's read timeout. Both phases raise `ReadTimeout` (via the `TimedOut` error type, mapped first in `map_anyhow_error`)
+- Do not use `reqwest::ClientBuilder::timeout` or `RequestBuilder::timeout`: the former is baked into the built client so `client.timeout = ...` could not change it, and both are total deadlines that also kill a live streaming body. `RClient.timeout` is a plain field read at request time in `build_request`
+- `StreamingResponse`, `TextIterator` and `LineIterator` carry the `Option<Duration>` they were created with
+
+### Streaming Responses
+- `_stream()` method returns `StreamingResponse` without calling `.bytes()` on reqwest response
+- `StreamingResponse` holds `Arc<Mutex<Option<reqwest::Response>>>` to allow chunk reading across Python GIL boundaries
+- Chunk iteration uses `RUNTIME.block_on()` with `py.allow_threads()` to read each chunk
+- State tracking via `Arc<Mutex<bool>>` for `closed` and `consumed` flags
+- Three iteration modes:
+  - `iter_bytes()`: Direct chunk iteration (returns `Iterator[bytes]`)
+  - `iter_text()`: Returns `TextIterator` that decodes chunks using response encoding
+  - `iter_lines()`: Returns `LineIterator` with internal buffer for line-by-line reading
+- `read()` method consumes remaining response body and marks as consumed
+- `close()` method sets closed flag and drops the response
+- Python wrapper uses `@contextmanager` to ensure `close()` is called on exit
+- AsyncClient streaming (issue #85): `AsyncClient.stream()` yields `AsyncStreamingResponse` (pure Python, `httpr/__init__.py`), which wraps the Rust `StreamingResponse` and adds `aiter_bytes()`/`aiter_text()`/`aiter_lines()`/`aread()`/`__aiter__`. Each step runs `next()` on the underlying sync iterator via `_run_sync_asyncio` on the client's executor so the event loop is never blocked; after `aclose()` the next step raises `ClientClosed`. The sync `iter_*`/`read()`/`__iter__` are kept on the wrapper and delegate directly (they block the loop). The Rust `StreamingResponse` is not subclassable, hence the wrapper rather than a subclass
+
+## What NOT to Do
+
+- Don't add Python dependencies (defeats "zero dependencies" goal)
+- Don't use native async Rust in request path (breaks single-threaded runtime model)
+- Don't modify headers case-sensitivity behavior (HTTP/2 spec requirement)
+- Don't skip `maturin develop` after Rust changes