nextreq 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. nextreq-0.1.0/.github/workflows/ci.yml +109 -0
  2. nextreq-0.1.0/.github/workflows/wheels.yml +193 -0
  3. nextreq-0.1.0/.gitignore +14 -0
  4. nextreq-0.1.0/CONTRIBUTING.md +130 -0
  5. nextreq-0.1.0/Cargo.lock +2067 -0
  6. nextreq-0.1.0/Cargo.toml +79 -0
  7. nextreq-0.1.0/LICENSE-APACHE +201 -0
  8. nextreq-0.1.0/LICENSE-MIT +21 -0
  9. nextreq-0.1.0/PKG-INFO +534 -0
  10. nextreq-0.1.0/README.md +481 -0
  11. nextreq-0.1.0/SECURITY.md +84 -0
  12. nextreq-0.1.0/benches/RESULTS.md +1415 -0
  13. nextreq-0.1.0/benches/results.json +1287 -0
  14. nextreq-0.1.0/benches/run_benchmarks.py +1282 -0
  15. nextreq-0.1.0/benches/server.py +178 -0
  16. nextreq-0.1.0/benches/server.rs +222 -0
  17. nextreq-0.1.0/build.rs +6 -0
  18. nextreq-0.1.0/pyproject.toml +99 -0
  19. nextreq-0.1.0/python/nextreq/__init__.py +140 -0
  20. nextreq-0.1.0/python/nextreq/_nextreq.pyi +234 -0
  21. nextreq-0.1.0/python/nextreq/client.py +1866 -0
  22. nextreq-0.1.0/python/nextreq/exceptions.py +266 -0
  23. nextreq-0.1.0/python/nextreq/models.py +1478 -0
  24. nextreq-0.1.0/python/nextreq/otel.py +206 -0
  25. nextreq-0.1.0/python/nextreq/parsing.py +470 -0
  26. nextreq-0.1.0/python/nextreq/py.typed +0 -0
  27. nextreq-0.1.0/python/nextreq/testing.py +684 -0
  28. nextreq-0.1.0/src/client.rs +1599 -0
  29. nextreq-0.1.0/src/config.rs +875 -0
  30. nextreq-0.1.0/src/errors.rs +309 -0
  31. nextreq-0.1.0/src/lib.rs +45 -0
  32. nextreq-0.1.0/src/sse.rs +738 -0
  33. nextreq-0.1.0/src/ws.rs +378 -0
  34. nextreq-0.1.0/tests/__init__.py +0 -0
  35. nextreq-0.1.0/tests/conftest.py +701 -0
  36. nextreq-0.1.0/tests/test_client_async.py +376 -0
  37. nextreq-0.1.0/tests/test_client_sync.py +839 -0
  38. nextreq-0.1.0/tests/test_hooks_otel.py +379 -0
  39. nextreq-0.1.0/tests/test_mock_asgi_wsgi.py +789 -0
  40. nextreq-0.1.0/tests/test_retries_timeouts.py +613 -0
  41. nextreq-0.1.0/tests/test_sse_ws.py +381 -0
  42. nextreq-0.1.0/tests/test_typed_parsing.py +360 -0
  43. nextreq-0.1.0/tests/test_typing.py +236 -0
@@ -0,0 +1,109 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ concurrency:
9
+ group: ci-${{ github.ref }}
10
+ cancel-in-progress: true
11
+
12
+ env:
13
+ CARGO_TERM_COLOR: always
14
+ RUST_BACKTRACE: 1
15
+
16
+ jobs:
17
+ rust:
18
+ name: Rust (fmt / clippy / test)
19
+ runs-on: ubuntu-latest
20
+ steps:
21
+ - uses: actions/checkout@v4
22
+ - uses: actions/setup-python@v5
23
+ with:
24
+ python-version: "3.12"
25
+ - uses: dtolnay/rust-toolchain@stable
26
+ with:
27
+ components: rustfmt, clippy
28
+ - uses: Swatinem/rust-cache@v2
29
+ - name: cargo fmt
30
+ run: cargo fmt --check
31
+ - name: cargo clippy
32
+ run: cargo clippy --all-targets -- -D warnings
33
+ - name: cargo test
34
+ run: cargo test
35
+
36
+ http3:
37
+ name: Rust (http3 feature compiles)
38
+ runs-on: ubuntu-latest
39
+ env:
40
+ RUSTFLAGS: --cfg reqwest_unstable
41
+ steps:
42
+ - uses: actions/checkout@v4
43
+ - uses: actions/setup-python@v5
44
+ with:
45
+ python-version: "3.12"
46
+ - uses: dtolnay/rust-toolchain@stable
47
+ - uses: Swatinem/rust-cache@v2
48
+ with:
49
+ key: http3
50
+ - run: cargo check --features http3
51
+
52
+ python:
53
+ name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
54
+ runs-on: ${{ matrix.os }}
55
+ # Windows has not been verified yet; report its result without failing the run.
56
+ continue-on-error: ${{ matrix.experimental == true }}
57
+ strategy:
58
+ fail-fast: false
59
+ matrix:
60
+ os: [ubuntu-latest]
61
+ python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
62
+ include:
63
+ - os: macos-latest
64
+ python-version: "3.13"
65
+ - os: windows-latest
66
+ python-version: "3.13"
67
+ experimental: true
68
+ steps:
69
+ - uses: actions/checkout@v4
70
+ - uses: dtolnay/rust-toolchain@stable
71
+ - uses: Swatinem/rust-cache@v2
72
+ - uses: astral-sh/setup-uv@v5
73
+ with:
74
+ python-version: ${{ matrix.python-version }}
75
+ - name: Create virtualenv and install dev dependencies
76
+ # setup-uv already creates .venv when python-version is set, so a
77
+ # plain `uv venv` fails with "already exists". --clear makes this step
78
+ # work whether or not the action created one.
79
+ run: |
80
+ uv venv --clear
81
+ uv pip install -e ".[dev]"
82
+ - name: Build extension (release)
83
+ run: uv run --no-sync maturin develop --release
84
+ - name: ruff
85
+ run: uv run --no-sync ruff check python tests benches
86
+ - name: ruff format
87
+ run: uv run --no-sync ruff format --check python tests benches
88
+ - name: mypy
89
+ run: uv run --no-sync mypy --strict python/nextreq tests/test_typing.py
90
+ - name: pytest
91
+ run: uv run --no-sync pytest -v
92
+
93
+ bench-smoke:
94
+ name: Benchmark suite (smoke)
95
+ runs-on: ubuntu-latest
96
+ needs: python
97
+ steps:
98
+ - uses: actions/checkout@v4
99
+ - uses: dtolnay/rust-toolchain@stable
100
+ - uses: Swatinem/rust-cache@v2
101
+ - uses: astral-sh/setup-uv@v5
102
+ with:
103
+ python-version: "3.13"
104
+ - run: |
105
+ uv venv --clear
106
+ uv pip install -e ".[dev]"
107
+ uv run --no-sync maturin develop --release
108
+ - name: Run benchmarks (quick mode, results not committed)
109
+ run: uv run --no-sync python benches/run_benchmarks.py --quick --output "$RUNNER_TEMP/RESULTS.md"
@@ -0,0 +1,193 @@
1
+ name: Wheels
2
+
3
+ on:
4
+ push:
5
+ tags: ["v*"]
6
+ pull_request:
7
+ paths:
8
+ - "Cargo.toml"
9
+ - "Cargo.lock"
10
+ - "pyproject.toml"
11
+ - ".github/workflows/wheels.yml"
12
+ workflow_dispatch:
13
+
14
+ permissions:
15
+ contents: read
16
+
17
+ env:
18
+ # abi3 wheels are built against the oldest supported interpreter and work on
19
+ # every newer CPython, so one wheel per platform is enough.
20
+ ABI3_PYTHON: "3.10"
21
+
22
+ jobs:
23
+ linux:
24
+ name: manylinux ${{ matrix.target }}
25
+ runs-on: ubuntu-latest
26
+ strategy:
27
+ fail-fast: false
28
+ matrix:
29
+ target: [x86_64, aarch64]
30
+ steps:
31
+ - uses: actions/checkout@v4
32
+ - uses: actions/setup-python@v5
33
+ with:
34
+ python-version: ${{ env.ABI3_PYTHON }}
35
+ - uses: PyO3/maturin-action@v1
36
+ with:
37
+ target: ${{ matrix.target }}
38
+ manylinux: "2_28"
39
+ args: --release --out dist
40
+ sccache: "true"
41
+ - uses: actions/upload-artifact@v4
42
+ with:
43
+ name: wheels-manylinux-${{ matrix.target }}
44
+ path: dist
45
+
46
+ musllinux:
47
+ name: musllinux ${{ matrix.target }}
48
+ runs-on: ubuntu-latest
49
+ strategy:
50
+ fail-fast: false
51
+ matrix:
52
+ target: [x86_64, aarch64]
53
+ steps:
54
+ - uses: actions/checkout@v4
55
+ - uses: actions/setup-python@v5
56
+ with:
57
+ python-version: ${{ env.ABI3_PYTHON }}
58
+ - uses: PyO3/maturin-action@v1
59
+ with:
60
+ target: ${{ matrix.target }}
61
+ manylinux: musllinux_1_2
62
+ args: --release --out dist
63
+ sccache: "true"
64
+ - uses: actions/upload-artifact@v4
65
+ with:
66
+ name: wheels-musllinux-${{ matrix.target }}
67
+ path: dist
68
+
69
+ macos:
70
+ name: macOS ${{ matrix.target }}
71
+ # Both architectures build on the current Apple-silicon image. The pinned
72
+ # images used before (macos-13 for Intel, macos-14 for arm64) have been
73
+ # retired by GitHub, so the Intel wheel is cross-compiled instead: maturin
74
+ # adds the x86_64-apple-darwin Rust target and abi3 needs no Intel Python.
75
+ runs-on: macos-latest
76
+ strategy:
77
+ fail-fast: false
78
+ matrix:
79
+ target: [aarch64, x86_64]
80
+ steps:
81
+ - uses: actions/checkout@v4
82
+ - uses: actions/setup-python@v5
83
+ with:
84
+ python-version: ${{ env.ABI3_PYTHON }}
85
+ - uses: PyO3/maturin-action@v1
86
+ with:
87
+ target: ${{ matrix.target }}
88
+ args: --release --out dist
89
+ sccache: "true"
90
+ - uses: actions/upload-artifact@v4
91
+ with:
92
+ name: wheels-macos-${{ matrix.target }}
93
+ path: dist
94
+
95
+ windows:
96
+ name: Windows x64
97
+ runs-on: windows-latest
98
+ steps:
99
+ - uses: actions/checkout@v4
100
+ - uses: actions/setup-python@v5
101
+ with:
102
+ python-version: ${{ env.ABI3_PYTHON }}
103
+ architecture: x64
104
+ - uses: PyO3/maturin-action@v1
105
+ with:
106
+ target: x64
107
+ args: --release --out dist
108
+ sccache: "true"
109
+ - uses: actions/upload-artifact@v4
110
+ with:
111
+ name: wheels-windows-x64
112
+ path: dist
113
+
114
+ free-threaded:
115
+ # abi3 cannot be loaded by free-threaded CPython 3.14, so ship a
116
+ # version-specific cp314t wheel. From 3.15 the abi3t (PEP 803) wheel
117
+ # produced by the `abi3t-py315` feature covers both builds.
118
+ name: free-threaded cp314t (${{ matrix.os }})
119
+ runs-on: ${{ matrix.os }}
120
+ strategy:
121
+ fail-fast: false
122
+ matrix:
123
+ os: [ubuntu-latest, macos-latest]
124
+ steps:
125
+ - uses: actions/checkout@v4
126
+ - uses: actions/setup-python@v5
127
+ with:
128
+ python-version: "3.14t"
129
+ - uses: PyO3/maturin-action@v1
130
+ with:
131
+ args: --release --out dist --interpreter python3.14t
132
+ manylinux: "2_28"
133
+ sccache: "true"
134
+ - uses: actions/upload-artifact@v4
135
+ with:
136
+ name: wheels-cp314t-${{ matrix.os }}
137
+ path: dist
138
+
139
+ sdist:
140
+ name: sdist
141
+ runs-on: ubuntu-latest
142
+ steps:
143
+ - uses: actions/checkout@v4
144
+ - uses: PyO3/maturin-action@v1
145
+ with:
146
+ command: sdist
147
+ args: --out dist
148
+ - uses: actions/upload-artifact@v4
149
+ with:
150
+ name: wheels-sdist
151
+ path: dist
152
+
153
+ smoke-test:
154
+ name: Install and import wheel (${{ matrix.os }}, py${{ matrix.python-version }})
155
+ needs: [linux, macos, windows]
156
+ runs-on: ${{ matrix.os }}
157
+ strategy:
158
+ fail-fast: false
159
+ matrix:
160
+ os: [ubuntu-latest, macos-latest, windows-latest]
161
+ python-version: ["3.10", "3.14"]
162
+ steps:
163
+ - uses: actions/setup-python@v5
164
+ with:
165
+ python-version: ${{ matrix.python-version }}
166
+ - uses: actions/download-artifact@v4
167
+ with:
168
+ pattern: wheels-*
169
+ merge-multiple: true
170
+ path: dist
171
+ - name: Install from the built wheels only
172
+ run: python -m pip install --no-index --find-links dist nextreq
173
+ - name: Import
174
+ run: python -c "import nextreq; print(nextreq.__version__)"
175
+
176
+ publish:
177
+ name: Publish to PyPI
178
+ if: startsWith(github.ref, 'refs/tags/v')
179
+ needs: [linux, musllinux, macos, windows, free-threaded, sdist, smoke-test]
180
+ runs-on: ubuntu-latest
181
+ environment: pypi
182
+ permissions:
183
+ id-token: write # trusted publishing
184
+ steps:
185
+ - uses: actions/download-artifact@v4
186
+ with:
187
+ pattern: wheels-*
188
+ merge-multiple: true
189
+ path: dist
190
+ - uses: PyO3/maturin-action@v1
191
+ with:
192
+ command: upload
193
+ args: --non-interactive --skip-existing dist/*
@@ -0,0 +1,14 @@
1
+ /target
2
+ /.venv
3
+ /dist
4
+ __pycache__/
5
+ *.py[cod]
6
+ *.so
7
+ *.pyd
8
+ *.dylib
9
+ .pytest_cache/
10
+ .mypy_cache/
11
+ .ruff_cache/
12
+ .DS_Store
13
+ *.egg-info/
14
+ benches/.results/
@@ -0,0 +1,130 @@
1
+ # Contributing to nextreq
2
+
3
+ Thanks for helping! This document covers the development setup, the quality
4
+ gates every change must pass, and how the code is organised.
5
+
6
+ ## Development setup
7
+
8
+ You need a Rust toolchain (stable, with `rustfmt` and `clippy`) and Python 3.10+.
9
+ [`uv`](https://docs.astral.sh/uv/) is recommended but plain `venv` + `pip` works.
10
+
11
+ ```bash
12
+ git clone https://github.com/chetanxrathore/nextreq
13
+ cd nextreq
14
+
15
+ uv venv # or: python3 -m venv .venv
16
+ source .venv/bin/activate
17
+ uv pip install -e ".[dev]" # or: pip install -e ".[dev]"
18
+
19
+ maturin develop # debug build of the Rust extension, fast to compile
20
+ maturin develop --release # optimised build - always use this for benchmarks
21
+ ```
22
+
23
+ Re-run `maturin develop` after changing anything under `src/`. Python-only changes
24
+ are picked up immediately (the package is installed in editable mode).
25
+
26
+ > If you use conda, `maturin` refuses to run while both `VIRTUAL_ENV` and
27
+ > `CONDA_PREFIX` are set. Run `conda deactivate` (or `unset CONDA_PREFIX`) first.
28
+
29
+ ## Quality gates
30
+
31
+ CI runs exactly these commands; all of them must exit 0.
32
+
33
+ ```bash
34
+ cargo fmt --check && cargo clippy -- -D warnings && cargo test
35
+ maturin develop --release
36
+ ruff check python tests benches
37
+ mypy --strict python/nextreq tests/test_typing.py
38
+ pytest -v
39
+ python benches/run_benchmarks.py # optional locally; add --quick for a smoke run
40
+ ```
41
+
42
+ Handy while iterating:
43
+
44
+ ```bash
45
+ ruff format python tests benches # auto-format Python
46
+ cargo fmt # auto-format Rust
47
+ pytest tests/test_sse_ws.py -k parser -x
48
+ ```
49
+
50
+ ## Project layout
51
+
52
+ ```
53
+ src/ Rust core, compiled to the `nextreq._nextreq` extension
54
+ lib.rs module definition
55
+ client.rs engine: pooling, Tokio runtime, sync/async dispatch, timeouts
56
+ config.rs Timeout, RetryPolicy, proxy and TLS configuration
57
+ sse.rs WHATWG Server-Sent Events parser and the SSEEvent class
58
+ ws.rs WebSocket client
59
+ errors.rs Rust error -> Python exception mapping
60
+ python/nextreq/ the public Python API
61
+ client.py Client, AsyncClient, module-level helpers, gather()
62
+ models.py Request, Response, Headers, URL, Cookies
63
+ parsing.py typed JSON parsing (Pydantic, dataclasses, msgspec)
64
+ testing.py MockTransport, ASGI and WSGI transports
65
+ otel.py OpenTelemetry hooks
66
+ exceptions.py the NextReqError hierarchy
67
+ _nextreq.pyi type stubs for the Rust extension
68
+ tests/ pytest suite (local servers only, no network access)
69
+ benches/ benchmark server and runner
70
+ ```
71
+
72
+ ### Where does a change belong?
73
+
74
+ - **Bytes on the wire** (protocols, TLS, pooling, timeouts, decompression, parsing
75
+ hot paths) belong in Rust.
76
+ - **HTTP semantics** (redirects, cookies, auth, retries, hooks, typed parsing)
77
+ belong in Python, *above* the transport, so they behave identically for the real
78
+ network and for `MockTransport` / ASGI / WSGI.
79
+
80
+ ## Rules of the road
81
+
82
+ 1. **Never hold the GIL while waiting on I/O.** Blocking calls go through
83
+ `block_on_interruptible` (which detaches from the interpreter); async calls
84
+ complete through `LoopBridge` or `pyo3-async-runtimes`. Code that runs on a
85
+ Tokio worker must not touch Python objects - return plain Rust data and convert
86
+ it at the boundary.
87
+ 2. **Keep the stubs in sync.** Every symbol exported from Rust needs a matching
88
+ entry in `python/nextreq/_nextreq.pyi`; `mypy --strict` and
89
+ `tests/test_typing.py` guard this.
90
+ 3. **Public API is fully typed.** New request methods need `@overload`s so that
91
+ `model=` keeps returning the model type.
92
+ 4. **Tests are hermetic.** Use the fixtures in `tests/conftest.py` (HTTP/SSE/WS
93
+ server, TLS + HTTP/2 server, stalled listener, forward proxy). No test may
94
+ reach the internet. Avoid sleeping; when timing matters, assert generous bounds.
95
+ 5. **No new mandatory runtime dependencies.** Integrations (Pydantic, msgspec,
96
+ OpenTelemetry) are detected at runtime and stay optional.
97
+ 6. **Supported Python is 3.10+.** `mypy` is configured for 3.10; do not use newer
98
+ syntax or stdlib features in `python/nextreq`.
99
+ 7. **Performance changes need numbers.** Run `benches/run_benchmarks.py` before
100
+ and after on a quiet machine and include both results in the pull request. Do
101
+ not hand-edit `benches/RESULTS.md`.
102
+
103
+ ## Commit messages and pull requests
104
+
105
+ - Reference the story or issue in the subject, e.g.
106
+ `NXRQ-401: honour Retry-After HTTP-dates`.
107
+ - Explain *why* in the body, not just what changed.
108
+ - Add or update tests in the same commit as the behaviour they cover.
109
+ - Update `README.md` when user-facing behaviour changes.
110
+ - Keep pull requests focused; unrelated refactors make review slower.
111
+
112
+ ## Optional features
113
+
114
+ HTTP/3 is feature-gated because `reqwest` still marks it unstable:
115
+
116
+ ```bash
117
+ RUSTFLAGS="--cfg reqwest_unstable" maturin develop --release --features http3
118
+ ```
119
+
120
+ ## Reporting bugs and security issues
121
+
122
+ Use GitHub issues for bugs and feature requests - a failing test or a minimal
123
+ script is the most helpful thing you can attach. For anything security-sensitive,
124
+ follow [SECURITY.md](SECURITY.md) instead of opening a public issue.
125
+
126
+ ## License
127
+
128
+ By contributing you agree that your contributions are dual-licensed under the
129
+ [MIT](LICENSE-MIT) and [Apache-2.0](LICENSE-APACHE) licenses, as the rest of the
130
+ project is.