spec2py-runtime 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.
@@ -0,0 +1,214 @@
1
+ # Downloaded corpus specs (pinned by hash in corpus/manifest.toml)
2
+ /corpus/specs/
3
+
4
+ # Generated at build time by hatch-vcs from the git tag
5
+ /src/spec2py/_version.py
6
+ /runtime/src/spec2py_runtime/_version.py
7
+
8
+ # Byte-compiled / optimized / DLL files
9
+ __pycache__/
10
+ *.py[codz]
11
+ *$py.class
12
+
13
+ # C extensions
14
+ *.so
15
+
16
+ # Distribution / packaging
17
+ .Python
18
+ build/
19
+ develop-eggs/
20
+ dist/
21
+ downloads/
22
+ eggs/
23
+ .eggs/
24
+ lib/
25
+ lib64/
26
+ parts/
27
+ sdist/
28
+ var/
29
+ wheels/
30
+ share/python-wheels/
31
+ *.egg-info/
32
+ .installed.cfg
33
+ *.egg
34
+ MANIFEST
35
+
36
+ # PyInstaller
37
+ # Usually these files are written by a python script from a template
38
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
39
+ *.manifest
40
+ *.spec
41
+
42
+ # Installer logs
43
+ pip-log.txt
44
+ pip-delete-this-directory.txt
45
+
46
+ # Unit test / coverage reports
47
+ htmlcov/
48
+ .tox/
49
+ .nox/
50
+ .coverage
51
+ .coverage.*
52
+ .cache
53
+ nosetests.xml
54
+ coverage.xml
55
+ *.cover
56
+ *.py.cover
57
+ .hypothesis/
58
+ .pytest_cache/
59
+ cover/
60
+
61
+ # Translations
62
+ *.mo
63
+ *.pot
64
+
65
+ # Django stuff:
66
+ *.log
67
+ local_settings.py
68
+ db.sqlite3
69
+ db.sqlite3-journal
70
+
71
+ # Flask stuff:
72
+ instance/
73
+ .webassets-cache
74
+
75
+ # Scrapy stuff:
76
+ .scrapy
77
+
78
+ # Sphinx documentation
79
+ docs/_build/
80
+
81
+ # PyBuilder
82
+ .pybuilder/
83
+ target/
84
+
85
+ # Jupyter Notebook
86
+ .ipynb_checkpoints
87
+
88
+ # IPython
89
+ profile_default/
90
+ ipython_config.py
91
+
92
+ # pyenv
93
+ # For a library or package, you might want to ignore these files since the code is
94
+ # intended to run in multiple environments; otherwise, check them in:
95
+ # .python-version
96
+
97
+ # pipenv
98
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
99
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
100
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
101
+ # install all needed dependencies.
102
+ #Pipfile.lock
103
+
104
+ # UV
105
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
106
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
107
+ # commonly ignored for libraries.
108
+ #uv.lock
109
+
110
+ # poetry
111
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
112
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
113
+ # commonly ignored for libraries.
114
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
115
+ #poetry.lock
116
+ #poetry.toml
117
+
118
+ # pdm
119
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
120
+ # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
121
+ # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
122
+ #pdm.lock
123
+ #pdm.toml
124
+ .pdm-python
125
+ .pdm-build/
126
+
127
+ # pixi
128
+ # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
129
+ #pixi.lock
130
+ # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
131
+ # in the .venv directory. It is recommended not to include this directory in version control.
132
+ .pixi
133
+
134
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
135
+ __pypackages__/
136
+
137
+ # Celery stuff
138
+ celerybeat-schedule
139
+ celerybeat.pid
140
+
141
+ # SageMath parsed files
142
+ *.sage.py
143
+
144
+ # Environments
145
+ .env
146
+ .envrc
147
+ .venv
148
+ env/
149
+ venv/
150
+ ENV/
151
+ env.bak/
152
+ venv.bak/
153
+
154
+ # Spyder project settings
155
+ .spyderproject
156
+ .spyproject
157
+
158
+ # Rope project settings
159
+ .ropeproject
160
+
161
+ # mkdocs documentation
162
+ /site
163
+
164
+ # mypy
165
+ .mypy_cache/
166
+ .dmypy.json
167
+ dmypy.json
168
+
169
+ # Pyre type checker
170
+ .pyre/
171
+
172
+ # pytype static type analyzer
173
+ .pytype/
174
+
175
+ # Cython debug symbols
176
+ cython_debug/
177
+
178
+ # PyCharm
179
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
180
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
181
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
182
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
183
+ #.idea/
184
+
185
+ # Abstra
186
+ # Abstra is an AI-powered process automation framework.
187
+ # Ignore directories containing user credentials, local state, and settings.
188
+ # Learn more at https://abstra.io/docs
189
+ .abstra/
190
+
191
+ # Visual Studio Code
192
+ # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
193
+ # that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
194
+ # and can be added to the global gitignore or merged into this file. However, if you prefer,
195
+ # you could uncomment the following to ignore the entire vscode folder
196
+ # .vscode/
197
+
198
+ # Ruff stuff:
199
+ .ruff_cache/
200
+
201
+ # PyPI configuration file
202
+ .pypirc
203
+
204
+ # Cursor
205
+ # Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
206
+ # exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
207
+ # refer to https://docs.cursor.com/context/ignore-files
208
+ .cursorignore
209
+ .cursorindexingignore
210
+
211
+ # Marimo
212
+ marimo/_static/
213
+ marimo/_lsp/
214
+ __marimo__/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Brendan Fahy
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,56 @@
1
+ Metadata-Version: 2.5
2
+ Name: spec2py-runtime
3
+ Version: 0.1.0
4
+ Summary: Runtime library for spec2py-generated API clients: transport, retries, auth, pagination, streaming and uploads on httpx2 and Pydantic v2.
5
+ Project-URL: Homepage, https://github.com/f4hy/spec2py
6
+ Author-email: Brendan Fahy <bmfahy@gmail.com>
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3 :: Only
13
+ Classifier: Programming Language :: Python :: 3.14
14
+ Classifier: Topic :: Internet :: WWW/HTTP
15
+ Classifier: Typing :: Typed
16
+ Requires-Python: >=3.14
17
+ Requires-Dist: anyio>=4.6
18
+ Requires-Dist: httpx2>=2.13
19
+ Requires-Dist: pydantic>=2.12
20
+ Description-Content-Type: text/markdown
21
+
22
+ # spec2py-runtime
23
+
24
+ The runtime library behind clients generated by
25
+ [spec2py](https://github.com/f4hy/spec2py). Generated code only describes
26
+ operations; everything that happens at request time lives here, so a fix
27
+ arrives with a dependency upgrade instead of a regeneration.
28
+
29
+ | Area | Behaviour |
30
+ | --- | --- |
31
+ | Transport | httpx2, with pluggable `transport=` / `http_client=` for tests and custom stacks |
32
+ | Retries | Exponential backoff with jitter. Honours `Retry-After`, `retry-after-ms` and `x-should-retry`. Retries idempotent methods, and POSTs once an idempotency key is attached (generated automatically when the API declares an idempotency header). |
33
+ | Auth | `ApiKeyAuth` (header, query or cookie), `BearerAuth`, `BasicAuth`, `OAuth2ClientCredentials` (fetch, cache, refresh, retry on 401), `MultiAuth`, or any `httpx2.Auth` |
34
+ | Pagination | `CursorPagination`, `OffsetPagination`, `PageNumberPagination`, `LinkHeaderPagination`; `Page` / `AsyncPage` / `AsyncPaginator` iterate lazily and expose `.data` and `.next_cursor` |
35
+ | Streaming | SSE and NDJSON decoded into typed events (`Stream`, `AsyncStream`) |
36
+ | Uploads | Multipart from file objects, paths, bytes or `(name, content, type)` tuples |
37
+ | Errors | `APIError` → `APIStatusError` → `NotFoundError`, `RateLimitError`, ...; bodies parsed into declared models |
38
+ | Observability | `Hooks(on_request=..., on_response=...)` |
39
+ | Models | `BaseModel` with lenient parsing, `Tolerant` enums, lazy validator builds |
40
+
41
+ Requires Python 3.14.
42
+
43
+ ## Validation and compatibility
44
+
45
+ Responses reject missing required fields and invalid field values by default.
46
+ Unknown fields are retained and unknown enum values are tolerated. Set
47
+ `strict_response_validation=False` explicitly for best-effort parsing; its
48
+ results can contain raw values or missing attributes and need defensive handling.
49
+ Requests revalidate generated model instances, including nested instances.
50
+
51
+ The initial generator and generated clients require `spec2py-runtime>=0.1.0,<0.2.0`.
52
+ Within the 0.1 series, runtime patch releases preserve the generated-code API.
53
+ Breaking runtime changes require a new minor series and regeneration to adopt it.
54
+ When emission starts using a new runtime feature, raise the minimum patch version
55
+ in both the generator dependency and generated project metadata. Development
56
+ snapshots before 0.1.0 are not release candidates for this compatibility range.
@@ -0,0 +1,35 @@
1
+ # spec2py-runtime
2
+
3
+ The runtime library behind clients generated by
4
+ [spec2py](https://github.com/f4hy/spec2py). Generated code only describes
5
+ operations; everything that happens at request time lives here, so a fix
6
+ arrives with a dependency upgrade instead of a regeneration.
7
+
8
+ | Area | Behaviour |
9
+ | --- | --- |
10
+ | Transport | httpx2, with pluggable `transport=` / `http_client=` for tests and custom stacks |
11
+ | Retries | Exponential backoff with jitter. Honours `Retry-After`, `retry-after-ms` and `x-should-retry`. Retries idempotent methods, and POSTs once an idempotency key is attached (generated automatically when the API declares an idempotency header). |
12
+ | Auth | `ApiKeyAuth` (header, query or cookie), `BearerAuth`, `BasicAuth`, `OAuth2ClientCredentials` (fetch, cache, refresh, retry on 401), `MultiAuth`, or any `httpx2.Auth` |
13
+ | Pagination | `CursorPagination`, `OffsetPagination`, `PageNumberPagination`, `LinkHeaderPagination`; `Page` / `AsyncPage` / `AsyncPaginator` iterate lazily and expose `.data` and `.next_cursor` |
14
+ | Streaming | SSE and NDJSON decoded into typed events (`Stream`, `AsyncStream`) |
15
+ | Uploads | Multipart from file objects, paths, bytes or `(name, content, type)` tuples |
16
+ | Errors | `APIError` → `APIStatusError` → `NotFoundError`, `RateLimitError`, ...; bodies parsed into declared models |
17
+ | Observability | `Hooks(on_request=..., on_response=...)` |
18
+ | Models | `BaseModel` with lenient parsing, `Tolerant` enums, lazy validator builds |
19
+
20
+ Requires Python 3.14.
21
+
22
+ ## Validation and compatibility
23
+
24
+ Responses reject missing required fields and invalid field values by default.
25
+ Unknown fields are retained and unknown enum values are tolerated. Set
26
+ `strict_response_validation=False` explicitly for best-effort parsing; its
27
+ results can contain raw values or missing attributes and need defensive handling.
28
+ Requests revalidate generated model instances, including nested instances.
29
+
30
+ The initial generator and generated clients require `spec2py-runtime>=0.1.0,<0.2.0`.
31
+ Within the 0.1 series, runtime patch releases preserve the generated-code API.
32
+ Breaking runtime changes require a new minor series and regeneration to adopt it.
33
+ When emission starts using a new runtime feature, raise the minimum patch version
34
+ in both the generator dependency and generated project metadata. Development
35
+ snapshots before 0.1.0 are not release candidates for this compatibility range.
@@ -0,0 +1,44 @@
1
+ [project]
2
+ name = "spec2py-runtime"
3
+ dynamic = ["version"]
4
+ description = "Runtime library for spec2py-generated API clients: transport, retries, auth, pagination, streaming and uploads on httpx2 and Pydantic v2."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ authors = [{ name = "Brendan Fahy", email = "bmfahy@gmail.com" }]
9
+ requires-python = ">=3.14"
10
+ classifiers = [
11
+ "Development Status :: 3 - Alpha",
12
+ "Intended Audience :: Developers",
13
+ "Programming Language :: Python :: 3",
14
+ "Programming Language :: Python :: 3 :: Only",
15
+ "Programming Language :: Python :: 3.14",
16
+ "Topic :: Internet :: WWW/HTTP",
17
+ "Typing :: Typed",
18
+ ]
19
+ dependencies = [
20
+ "anyio>=4.6",
21
+ "httpx2>=2.13",
22
+ "pydantic>=2.12",
23
+ ]
24
+
25
+ [project.urls]
26
+ Homepage = "https://github.com/f4hy/spec2py"
27
+
28
+ [build-system]
29
+ requires = ["hatchling", "hatch-vcs"]
30
+ build-backend = "hatchling.build"
31
+
32
+ [tool.hatch.build.targets.wheel]
33
+ packages = ["src/spec2py_runtime"]
34
+
35
+ [tool.hatch.version]
36
+ source = "vcs"
37
+
38
+ [tool.hatch.version.raw-options]
39
+ root = ".."
40
+ version_scheme = "no-guess-dev"
41
+ fallback_version = "0.0.0"
42
+
43
+ [tool.hatch.build.hooks.vcs]
44
+ version-file = "src/spec2py_runtime/_version.py"
@@ -0,0 +1,151 @@
1
+ """Runtime for spec2py-generated API clients.
2
+
3
+ Generated packages import from here; end users mostly touch the error classes,
4
+ ``NOT_GIVEN``, the auth helpers and ``Hooks``.
5
+ """
6
+
7
+ from ._auth import ApiKeyAuth, BasicAuth, BearerAuth, MultiAuth, OAuth2ClientCredentials
8
+ from ._client import (
9
+ DEFAULT_MAX_RETRIES,
10
+ DEFAULT_TIMEOUT,
11
+ APIClient,
12
+ APIResource,
13
+ AsyncAPIClient,
14
+ AsyncAPIResource,
15
+ Hooks,
16
+ RequestOptions,
17
+ RequestSpec,
18
+ __version__,
19
+ )
20
+ from ._exceptions import (
21
+ APIConnectionError,
22
+ APIError,
23
+ APIResponseValidationError,
24
+ APIStatusError,
25
+ APITimeoutError,
26
+ AuthenticationError,
27
+ BadRequestError,
28
+ ConflictError,
29
+ InternalServerError,
30
+ NotFoundError,
31
+ PaginationOriginError,
32
+ PermissionDeniedError,
33
+ RateLimitError,
34
+ UnprocessableEntityError,
35
+ )
36
+ from ._models import (
37
+ BaseModel,
38
+ Tolerant,
39
+ build_body,
40
+ jsonable,
41
+ link_models,
42
+ parse_value,
43
+ validate_param,
44
+ )
45
+ from ._pagination import (
46
+ AsyncPage,
47
+ AsyncPaginator,
48
+ CursorPagination,
49
+ LinkHeaderPagination,
50
+ NextPage,
51
+ OffsetPagination,
52
+ Page,
53
+ PageNumberPagination,
54
+ PageState,
55
+ PaginationStrategy,
56
+ )
57
+ from ._qs import path_template
58
+ from ._response import (
59
+ APIResponse,
60
+ async_to_raw_response_wrapper,
61
+ to_raw_response_wrapper,
62
+ )
63
+ from ._retry import RetryPolicy
64
+ from ._streaming import (
65
+ AsyncStream,
66
+ AsyncStreamManager,
67
+ ServerSentEvent,
68
+ SSEDecoder,
69
+ Stream,
70
+ StreamManager,
71
+ )
72
+ from ._types import (
73
+ NOT_GIVEN,
74
+ Body,
75
+ FileTypes,
76
+ Headers,
77
+ NotGiven,
78
+ Query,
79
+ Timeout,
80
+ TimeoutTypes,
81
+ is_given,
82
+ )
83
+
84
+ __all__ = [
85
+ "DEFAULT_MAX_RETRIES",
86
+ "DEFAULT_TIMEOUT",
87
+ "NOT_GIVEN",
88
+ "APIClient",
89
+ "APIConnectionError",
90
+ "APIError",
91
+ "APIResource",
92
+ "APIResponse",
93
+ "APIResponseValidationError",
94
+ "APIStatusError",
95
+ "APITimeoutError",
96
+ "ApiKeyAuth",
97
+ "AsyncAPIClient",
98
+ "AsyncAPIResource",
99
+ "AsyncPage",
100
+ "AsyncPaginator",
101
+ "AsyncStream",
102
+ "AsyncStreamManager",
103
+ "AuthenticationError",
104
+ "BadRequestError",
105
+ "BaseModel",
106
+ "BasicAuth",
107
+ "BearerAuth",
108
+ "Body",
109
+ "ConflictError",
110
+ "CursorPagination",
111
+ "FileTypes",
112
+ "Headers",
113
+ "Hooks",
114
+ "InternalServerError",
115
+ "LinkHeaderPagination",
116
+ "MultiAuth",
117
+ "NextPage",
118
+ "NotFoundError",
119
+ "NotGiven",
120
+ "OAuth2ClientCredentials",
121
+ "OffsetPagination",
122
+ "Page",
123
+ "PageNumberPagination",
124
+ "PageState",
125
+ "PaginationOriginError",
126
+ "PaginationStrategy",
127
+ "PermissionDeniedError",
128
+ "Query",
129
+ "RateLimitError",
130
+ "RequestOptions",
131
+ "RequestSpec",
132
+ "RetryPolicy",
133
+ "SSEDecoder",
134
+ "ServerSentEvent",
135
+ "Stream",
136
+ "StreamManager",
137
+ "Timeout",
138
+ "TimeoutTypes",
139
+ "Tolerant",
140
+ "UnprocessableEntityError",
141
+ "__version__",
142
+ "async_to_raw_response_wrapper",
143
+ "build_body",
144
+ "is_given",
145
+ "jsonable",
146
+ "link_models",
147
+ "parse_value",
148
+ "path_template",
149
+ "to_raw_response_wrapper",
150
+ "validate_param",
151
+ ]
@@ -0,0 +1,180 @@
1
+ """Authentication schemes as ``httpx2.Auth`` flows.
2
+
3
+ Every scheme here works for both the sync and async clients, because httpx2
4
+ drives the same generator-based ``auth_flow`` in both modes. Custom auth is any
5
+ ``httpx2.Auth`` subclass passed as ``auth=`` to a generated client.
6
+ """
7
+
8
+ import base64
9
+ import time
10
+ from collections.abc import Generator, Sequence
11
+ from dataclasses import dataclass, field
12
+ from typing import Literal, override
13
+
14
+ import httpx2
15
+
16
+ __all__ = [
17
+ "ApiKeyAuth",
18
+ "BasicAuth",
19
+ "BearerAuth",
20
+ "MultiAuth",
21
+ "OAuth2ClientCredentials",
22
+ ]
23
+
24
+ type AuthFlow = Generator[httpx2.Request, httpx2.Response]
25
+
26
+
27
+ class ApiKeyAuth(httpx2.Auth):
28
+ """An API key sent in a header, query parameter or cookie."""
29
+
30
+ def __init__(
31
+ self,
32
+ key: str,
33
+ *,
34
+ name: str,
35
+ location: Literal["header", "query", "cookie"] = "header",
36
+ prefix: str | None = None,
37
+ ) -> None:
38
+ self.key = key
39
+ self.name = name
40
+ self.location = location
41
+ self.prefix = prefix
42
+
43
+ @override
44
+ def auth_flow(self, request: httpx2.Request) -> AuthFlow:
45
+ value = f"{self.prefix} {self.key}" if self.prefix else self.key
46
+ match self.location:
47
+ case "header":
48
+ request.headers[self.name] = value
49
+ case "query":
50
+ request.url = request.url.copy_merge_params({self.name: value})
51
+ case "cookie":
52
+ existing = request.headers.get("cookie")
53
+ pair = f"{self.name}={value}"
54
+ request.headers["cookie"] = f"{existing}; {pair}" if existing else pair
55
+ case _:
56
+ raise ValueError(f"unknown API key location {self.location!r}")
57
+ yield request
58
+
59
+
60
+ class BearerAuth(httpx2.Auth):
61
+ """``Authorization: Bearer <token>``."""
62
+
63
+ def __init__(self, token: str) -> None:
64
+ self.token = token
65
+
66
+ @override
67
+ def auth_flow(self, request: httpx2.Request) -> AuthFlow:
68
+ request.headers["Authorization"] = f"Bearer {self.token}"
69
+ yield request
70
+
71
+
72
+ class BasicAuth(httpx2.Auth):
73
+ """HTTP basic auth."""
74
+
75
+ def __init__(self, username: str, password: str) -> None:
76
+ raw = f"{username}:{password}".encode()
77
+ self._header = "Basic " + base64.b64encode(raw).decode("ascii")
78
+
79
+ @override
80
+ def auth_flow(self, request: httpx2.Request) -> AuthFlow:
81
+ request.headers["Authorization"] = self._header
82
+ yield request
83
+
84
+
85
+ class MultiAuth(httpx2.Auth):
86
+ """Apply several schemes to every request, e.g. an API key plus a bearer token."""
87
+
88
+ def __init__(self, auths: Sequence[httpx2.Auth]) -> None:
89
+ self.auths = list(auths)
90
+
91
+ @override
92
+ def auth_flow(self, request: httpx2.Request) -> AuthFlow:
93
+ yield from self._chain(0, request)
94
+
95
+ def _chain(
96
+ self, index: int, request: httpx2.Request
97
+ ) -> Generator[httpx2.Request, httpx2.Response, httpx2.Response]:
98
+ if index == len(self.auths):
99
+ return (yield request)
100
+ flow = self.auths[index].auth_flow(request)
101
+ outgoing = next(flow)
102
+ while True:
103
+ if outgoing is request:
104
+ response = yield from self._chain(index + 1, outgoing)
105
+ else:
106
+ # A side request of this scheme (e.g. an OAuth2 token fetch):
107
+ # send it as-is, without the other schemes' credentials.
108
+ response = yield outgoing
109
+ try:
110
+ outgoing = flow.send(response)
111
+ except StopIteration:
112
+ return response
113
+
114
+
115
+ @dataclass(slots=True)
116
+ class _Token:
117
+ access_token: str
118
+ expires_at: float | None
119
+ refresh_token: str | None = None
120
+
121
+ def valid(self, leeway: float) -> bool:
122
+ return self.expires_at is None or time.time() < self.expires_at - leeway
123
+
124
+
125
+ @dataclass
126
+ class OAuth2ClientCredentials(httpx2.Auth):
127
+ """OAuth2 client-credentials grant with automatic token fetch and refresh.
128
+
129
+ Fetches a token on first use, reuses it until shortly before it expires,
130
+ uses the refresh token when the server issued one, and retries once with a
131
+ fresh token if the API answers 401.
132
+ """
133
+
134
+ token_url: str
135
+ client_id: str
136
+ client_secret: str
137
+ scopes: Sequence[str] = ()
138
+ audience: str | None = None
139
+ leeway: float = 30.0
140
+ requires_response_body = True
141
+ _token: _Token | None = field(default=None, init=False, repr=False)
142
+
143
+ def _token_request(self) -> httpx2.Request:
144
+ data = {
145
+ "grant_type": "client_credentials",
146
+ "client_id": self.client_id,
147
+ "client_secret": self.client_secret,
148
+ }
149
+ if self._token and self._token.refresh_token:
150
+ data["grant_type"] = "refresh_token"
151
+ data["refresh_token"] = self._token.refresh_token
152
+ if self.scopes:
153
+ data["scope"] = " ".join(self.scopes)
154
+ if self.audience:
155
+ data["audience"] = self.audience
156
+ return httpx2.Request("POST", self.token_url, data=data)
157
+
158
+ def _store(self, response: httpx2.Response) -> _Token:
159
+ response.raise_for_status()
160
+ payload = response.json()
161
+ expires_in = payload.get("expires_in")
162
+ self._token = _Token(
163
+ access_token=payload["access_token"],
164
+ expires_at=time.time() + float(expires_in) if expires_in else None,
165
+ refresh_token=payload.get("refresh_token"),
166
+ )
167
+ return self._token
168
+
169
+ @override
170
+ def auth_flow(self, request: httpx2.Request) -> AuthFlow:
171
+ token = self._token
172
+ if token is None or not token.valid(self.leeway):
173
+ token = self._store((yield self._token_request()))
174
+ request.headers["Authorization"] = f"Bearer {token.access_token}"
175
+ response = yield request
176
+ if response.status_code == 401:
177
+ self._token = None
178
+ token = self._store((yield self._token_request()))
179
+ request.headers["Authorization"] = f"Bearer {token.access_token}"
180
+ yield request