clientx 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.
clientx-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 slatecipher
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.
clientx-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,176 @@
1
+ Metadata-Version: 2.4
2
+ Name: clientx
3
+ Version: 0.1.0
4
+ Summary: A typed, declarative HTTP API client framework for Python
5
+ Keywords: http,api,client,httpx,httpx2,pydantic,typed,declarative
6
+ Author: slatecipher
7
+ Author-email: slatecipher <25094255+slatecipher@users.noreply.github.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Framework :: Pydantic :: 2
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3 :: Only
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Topic :: Internet :: WWW/HTTP
20
+ Classifier: Topic :: Software Development :: Libraries
21
+ Classifier: Typing :: Typed
22
+ Requires-Dist: httpx2>=2.10.0
23
+ Requires-Dist: pydantic>=2.12.5
24
+ Requires-Python: >=3.12
25
+ Project-URL: Repository, https://github.com/slatecipher/ClientX
26
+ Project-URL: Issues, https://github.com/slatecipher/ClientX/issues
27
+ Project-URL: Changelog, https://github.com/slatecipher/ClientX/blob/mainline/CHANGELOG.md
28
+ Description-Content-Type: text/markdown
29
+
30
+ <h1 align="center">
31
+ <picture>
32
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
33
+ <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo-light.svg">
34
+ <img alt="ClientX" src="https://raw.githubusercontent.com/slatecipher/ClientX/mainline/docs/assets/logo-light.svg" width="400">
35
+ </picture>
36
+ </h1>
37
+
38
+ <p align="center">
39
+ <em>Typed, declarative HTTP API clients for Python 3.12+.</em>
40
+ </p>
41
+
42
+ <p align="center">
43
+ <a href="https://pypi.org/project/clientx/"><img src="https://img.shields.io/pypi/v/clientx" alt="PyPI"></a>
44
+ <a href="https://pypi.org/project/clientx/"><img src="https://img.shields.io/pypi/pyversions/clientx" alt="Python versions"></a>
45
+ <a href="https://github.com/slatecipher/ClientX/actions/workflows/ci.yml"><img src="https://github.com/slatecipher/ClientX/actions/workflows/ci.yml/badge.svg?branch=mainline" alt="CI"></a>
46
+ <a href="https://github.com/slatecipher/ClientX/blob/mainline/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT"></a>
47
+ </p>
48
+
49
+ ## Overview
50
+
51
+ ClientX is a declarative API client framework designed to make writing and maintaining API clients easier while keeping the client contract explicit and well documented.
52
+
53
+ For client authors, ClientX reduces boilerplate by turning typed endpoint definitions into concrete `httpx2` requests and centralizing request/response behavior. For client consumers, it pushes API contracts and guard rails into the client itself, helping prevent avoidable runtime mistakes and making integrations more predictable.
54
+
55
+ The result is less scaffolding and more focus on outcomes: authors, human or AI, spend less time on plumbing, and the developers and AI agents calling your API spend less time guessing how to use it correctly. The same endpoints become tools an AI model can call, described by your docstrings and type hints, with errors it can act on.
56
+
57
+ ## Quickstart
58
+
59
+ <!-- docs_src/readme/quickstart.py -->
60
+ ```python
61
+ from typing import Annotated
62
+
63
+ from clientx import ClientX, Header, Json, Query, Resource, method
64
+ from pydantic import BaseModel
65
+
66
+
67
+ class User(BaseModel):
68
+ id: int
69
+ name: str
70
+
71
+
72
+ class NewUser(BaseModel):
73
+ name: str
74
+
75
+
76
+ class Users(Resource, prefix="/users"):
77
+ @method.get("/{user_id}")
78
+ def retrieve(self, user_id: int) -> User:
79
+ """Fetch one user by ID."""
80
+ ...
81
+
82
+ @method.get()
83
+ def search(self, name: Annotated[str | None, Query()] = None) -> list[User]:
84
+ """List users, or only those with this name."""
85
+ ...
86
+
87
+ @method.post()
88
+ def create(
89
+ self,
90
+ user: Annotated[NewUser, Json()],
91
+ request_id: Annotated[str | None, Header()] = None,
92
+ ) -> User:
93
+ """Create a user."""
94
+ ...
95
+
96
+
97
+ class ExampleAPI(ClientX, user_agent="example-app/1.0"):
98
+ users = Users()
99
+
100
+
101
+ with ExampleAPI("https://api.example.com") as api:
102
+ user = api.users.retrieve(42) # GET /users/42 -> User
103
+ matches = api.users.search(name="Ada") # GET /users?name=Ada -> list[User]
104
+ new = api.users.create(NewUser(name="Ada"), request_id="r-1") # POST /users, JSON body, request-id header -> User
105
+ ```
106
+
107
+ - Endpoint bodies never run. ClientX builds each request from the method's signature, sends it, and decodes the response into the return annotation.
108
+ - Type checkers see the real signatures: `api.users.retrieve(user_id: int) -> User`.
109
+ - A 4xx or 5xx response raises `httpx2.HTTPStatusError`.
110
+ - The `with` block closes the client's connections when it ends. It's optional: a long-lived client is created once and closed with `close()` at shutdown, as [Closing a client](https://github.com/slatecipher/ClientX/blob/mainline/docs/configuration.md#closing-a-client) explains.
111
+ - For async code, subclass `AsyncClientX` and `AsyncResource`, write the endpoints as `async def` methods, and `await` them, as [Async clients](https://github.com/slatecipher/ClientX/blob/mainline/docs/async.md) explains.
112
+ - Using mypy? Turn off its `empty-body` check for your client modules, as [Defining endpoints](https://github.com/slatecipher/ClientX/blob/mainline/docs/endpoints.md#empty-method-bodies-and-mypy) explains.
113
+
114
+ ## Why ClientX
115
+
116
+ ClientX is inspired by FastAPI, which reads type hints to define server endpoints. ClientX applies the same idea to the client side:
117
+
118
+ - **The method signature is the contract.** Path placeholders, query parameters, headers and bodies come from the method's parameters and annotations, so there's no request-building code to keep in sync.
119
+ - **The return annotation decodes the response.** `-> User` returns the JSON body validated as a `User`, `-> Iterator[str]` streams it line by line, and `-> Response` returns the response itself.
120
+ - **Type checkers see real types.** Decorated methods keep their signatures, so editors and type checkers see the actual parameters and return types.
121
+ - **Sync or async.** Write endpoints as `def` methods on a `ClientX`, or as `async def` methods on an `AsyncClientX`, with the same decorators.
122
+ - **Mistakes surface early.** A missing return annotation, a parameter that doesn't say where it goes, a placeholder that names no parameter, or a type ClientX can't decode raises an error when the class is defined, not on the first request.
123
+ - **Pydantic v2 throughout.** Send models as JSON bodies, or spread them into query parameters, headers or form fields, and decode responses into models.
124
+ - **Built on httpx2.** A client is an `httpx2.Client`, or an `httpx2.AsyncClient`, so every option is available, including auth, timeouts, proxies and custom transports.
125
+ - **Ready for AI agents.** `clientx.tools` turns each endpoint into a tool a model can call: its description from the docstring, a JSON Schema of its arguments, and errors that tell the model what went wrong, never your credentials.
126
+
127
+ ## Features
128
+
129
+ - Declarative endpoint definitions with HTTP verb decorators.
130
+ - Responses decoded from the return annotation, with streaming, and your own decoder when you need one.
131
+ - Path parameters filled from method arguments and percent-encoded (e.g. `"/users/{user_id}"`).
132
+ - Request parts declared with helpers named like FastAPI's (`Query`, `Header`, `Json`, `Body`, `Form`, `File`): every parameter but a path placeholder's says where it goes.
133
+ - Resources that group endpoints under a path prefix.
134
+ - Built-in deprecation warnings per endpoint.
135
+ - Full access to `httpx2.Client` configuration through `ClientX(...)` arguments.
136
+ - Async clients (`AsyncClientX`, `AsyncResource`) with the same decorators, for `async def` endpoints.
137
+ - AI tools from the same endpoints (`clientx.tools`): descriptions from docstrings, JSON Schemas, and errors a model can act on.
138
+
139
+ ## Project status
140
+
141
+ ClientX is a passion project that comes from my experience integrating APIs. Every small prototype against a new API means writing the same boilerplate again, and third-party clients are hit or miss. ClientX lets me focus on outcomes rather than plumbing, and I hope it does the same for you. I maintain it in my spare time, so replies may take a while, but issues and pull requests are always welcome.
142
+
143
+ ClientX is pre-1.0, so the API may change between minor versions. Changes are listed in the [changelog](https://github.com/slatecipher/ClientX/blob/mainline/CHANGELOG.md).
144
+
145
+ ## Install
146
+
147
+ ```bash
148
+ pip install clientx
149
+ ```
150
+
151
+ Using an AI coding assistant? Point it at [llms.txt](https://github.com/slatecipher/ClientX/blob/mainline/llms.txt), a compact guide to ClientX's patterns and pitfalls.
152
+
153
+ ## Guide
154
+
155
+ - [Defining endpoints](https://github.com/slatecipher/ClientX/blob/mainline/docs/endpoints.md): the verb decorators and their options, the rules for an endpoint method, deprecating endpoints, and endpoint names.
156
+ - [Building requests](https://github.com/slatecipher/ClientX/blob/mainline/docs/requests.md): how parameters become the path, query string, headers and body.
157
+ - [Responses](https://github.com/slatecipher/ClientX/blob/mainline/docs/responses.md): how the return annotation decides what an endpoint returns, streaming, your own decoder, and errors for 4xx and 5xx responses.
158
+ - [Resources](https://github.com/slatecipher/ClientX/blob/mainline/docs/resources.md): grouping endpoints under a path prefix, nesting them, and plain methods for logic such as pagination.
159
+ - [Client configuration](https://github.com/slatecipher/ClientX/blob/mainline/docs/configuration.md): creating and closing a client, the base URL and `User-Agent` class defaults, authentication, logging and event hooks.
160
+ - [Async clients](https://github.com/slatecipher/ClientX/blob/mainline/docs/async.md): `AsyncClientX` and `AsyncResource` for `async def` endpoints, concurrent requests, and async streaming.
161
+ - [Testing](https://github.com/slatecipher/ClientX/blob/mainline/docs/testing.md): testing a client without the network.
162
+ - [AI tools](https://github.com/slatecipher/ClientX/blob/mainline/docs/tools.md): a client's endpoints as tools a model can call.
163
+ - [Errors](https://github.com/slatecipher/ClientX/blob/mainline/docs/errors.md): the errors ClientX raises, and when.
164
+ - [API reference](https://github.com/slatecipher/ClientX/blob/mainline/docs/reference.md): every public name, with its signature and arguments.
165
+
166
+ ## Development
167
+
168
+ See [CONTRIBUTING.md](https://github.com/slatecipher/ClientX/blob/mainline/CONTRIBUTING.md) for setup, checks, and conventions.
169
+
170
+ ## Acknowledgments
171
+
172
+ ClientX is inspired by FastAPI and built on Pydantic and httpx2, and I'm grateful to the developers behind all three. It's an independent project, though, and isn't affiliated with or endorsed by any of them.
173
+
174
+ ## License
175
+
176
+ ClientX is released under the [MIT License](https://github.com/slatecipher/ClientX/blob/mainline/LICENSE).
@@ -0,0 +1,147 @@
1
+ <h1 align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
4
+ <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo-light.svg">
5
+ <img alt="ClientX" src="https://raw.githubusercontent.com/slatecipher/ClientX/mainline/docs/assets/logo-light.svg" width="400">
6
+ </picture>
7
+ </h1>
8
+
9
+ <p align="center">
10
+ <em>Typed, declarative HTTP API clients for Python 3.12+.</em>
11
+ </p>
12
+
13
+ <p align="center">
14
+ <a href="https://pypi.org/project/clientx/"><img src="https://img.shields.io/pypi/v/clientx" alt="PyPI"></a>
15
+ <a href="https://pypi.org/project/clientx/"><img src="https://img.shields.io/pypi/pyversions/clientx" alt="Python versions"></a>
16
+ <a href="https://github.com/slatecipher/ClientX/actions/workflows/ci.yml"><img src="https://github.com/slatecipher/ClientX/actions/workflows/ci.yml/badge.svg?branch=mainline" alt="CI"></a>
17
+ <a href="https://github.com/slatecipher/ClientX/blob/mainline/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT"></a>
18
+ </p>
19
+
20
+ ## Overview
21
+
22
+ ClientX is a declarative API client framework designed to make writing and maintaining API clients easier while keeping the client contract explicit and well documented.
23
+
24
+ For client authors, ClientX reduces boilerplate by turning typed endpoint definitions into concrete `httpx2` requests and centralizing request/response behavior. For client consumers, it pushes API contracts and guard rails into the client itself, helping prevent avoidable runtime mistakes and making integrations more predictable.
25
+
26
+ The result is less scaffolding and more focus on outcomes: authors, human or AI, spend less time on plumbing, and the developers and AI agents calling your API spend less time guessing how to use it correctly. The same endpoints become tools an AI model can call, described by your docstrings and type hints, with errors it can act on.
27
+
28
+ ## Quickstart
29
+
30
+ <!-- docs_src/readme/quickstart.py -->
31
+ ```python
32
+ from typing import Annotated
33
+
34
+ from clientx import ClientX, Header, Json, Query, Resource, method
35
+ from pydantic import BaseModel
36
+
37
+
38
+ class User(BaseModel):
39
+ id: int
40
+ name: str
41
+
42
+
43
+ class NewUser(BaseModel):
44
+ name: str
45
+
46
+
47
+ class Users(Resource, prefix="/users"):
48
+ @method.get("/{user_id}")
49
+ def retrieve(self, user_id: int) -> User:
50
+ """Fetch one user by ID."""
51
+ ...
52
+
53
+ @method.get()
54
+ def search(self, name: Annotated[str | None, Query()] = None) -> list[User]:
55
+ """List users, or only those with this name."""
56
+ ...
57
+
58
+ @method.post()
59
+ def create(
60
+ self,
61
+ user: Annotated[NewUser, Json()],
62
+ request_id: Annotated[str | None, Header()] = None,
63
+ ) -> User:
64
+ """Create a user."""
65
+ ...
66
+
67
+
68
+ class ExampleAPI(ClientX, user_agent="example-app/1.0"):
69
+ users = Users()
70
+
71
+
72
+ with ExampleAPI("https://api.example.com") as api:
73
+ user = api.users.retrieve(42) # GET /users/42 -> User
74
+ matches = api.users.search(name="Ada") # GET /users?name=Ada -> list[User]
75
+ new = api.users.create(NewUser(name="Ada"), request_id="r-1") # POST /users, JSON body, request-id header -> User
76
+ ```
77
+
78
+ - Endpoint bodies never run. ClientX builds each request from the method's signature, sends it, and decodes the response into the return annotation.
79
+ - Type checkers see the real signatures: `api.users.retrieve(user_id: int) -> User`.
80
+ - A 4xx or 5xx response raises `httpx2.HTTPStatusError`.
81
+ - The `with` block closes the client's connections when it ends. It's optional: a long-lived client is created once and closed with `close()` at shutdown, as [Closing a client](https://github.com/slatecipher/ClientX/blob/mainline/docs/configuration.md#closing-a-client) explains.
82
+ - For async code, subclass `AsyncClientX` and `AsyncResource`, write the endpoints as `async def` methods, and `await` them, as [Async clients](https://github.com/slatecipher/ClientX/blob/mainline/docs/async.md) explains.
83
+ - Using mypy? Turn off its `empty-body` check for your client modules, as [Defining endpoints](https://github.com/slatecipher/ClientX/blob/mainline/docs/endpoints.md#empty-method-bodies-and-mypy) explains.
84
+
85
+ ## Why ClientX
86
+
87
+ ClientX is inspired by FastAPI, which reads type hints to define server endpoints. ClientX applies the same idea to the client side:
88
+
89
+ - **The method signature is the contract.** Path placeholders, query parameters, headers and bodies come from the method's parameters and annotations, so there's no request-building code to keep in sync.
90
+ - **The return annotation decodes the response.** `-> User` returns the JSON body validated as a `User`, `-> Iterator[str]` streams it line by line, and `-> Response` returns the response itself.
91
+ - **Type checkers see real types.** Decorated methods keep their signatures, so editors and type checkers see the actual parameters and return types.
92
+ - **Sync or async.** Write endpoints as `def` methods on a `ClientX`, or as `async def` methods on an `AsyncClientX`, with the same decorators.
93
+ - **Mistakes surface early.** A missing return annotation, a parameter that doesn't say where it goes, a placeholder that names no parameter, or a type ClientX can't decode raises an error when the class is defined, not on the first request.
94
+ - **Pydantic v2 throughout.** Send models as JSON bodies, or spread them into query parameters, headers or form fields, and decode responses into models.
95
+ - **Built on httpx2.** A client is an `httpx2.Client`, or an `httpx2.AsyncClient`, so every option is available, including auth, timeouts, proxies and custom transports.
96
+ - **Ready for AI agents.** `clientx.tools` turns each endpoint into a tool a model can call: its description from the docstring, a JSON Schema of its arguments, and errors that tell the model what went wrong, never your credentials.
97
+
98
+ ## Features
99
+
100
+ - Declarative endpoint definitions with HTTP verb decorators.
101
+ - Responses decoded from the return annotation, with streaming, and your own decoder when you need one.
102
+ - Path parameters filled from method arguments and percent-encoded (e.g. `"/users/{user_id}"`).
103
+ - Request parts declared with helpers named like FastAPI's (`Query`, `Header`, `Json`, `Body`, `Form`, `File`): every parameter but a path placeholder's says where it goes.
104
+ - Resources that group endpoints under a path prefix.
105
+ - Built-in deprecation warnings per endpoint.
106
+ - Full access to `httpx2.Client` configuration through `ClientX(...)` arguments.
107
+ - Async clients (`AsyncClientX`, `AsyncResource`) with the same decorators, for `async def` endpoints.
108
+ - AI tools from the same endpoints (`clientx.tools`): descriptions from docstrings, JSON Schemas, and errors a model can act on.
109
+
110
+ ## Project status
111
+
112
+ ClientX is a passion project that comes from my experience integrating APIs. Every small prototype against a new API means writing the same boilerplate again, and third-party clients are hit or miss. ClientX lets me focus on outcomes rather than plumbing, and I hope it does the same for you. I maintain it in my spare time, so replies may take a while, but issues and pull requests are always welcome.
113
+
114
+ ClientX is pre-1.0, so the API may change between minor versions. Changes are listed in the [changelog](https://github.com/slatecipher/ClientX/blob/mainline/CHANGELOG.md).
115
+
116
+ ## Install
117
+
118
+ ```bash
119
+ pip install clientx
120
+ ```
121
+
122
+ Using an AI coding assistant? Point it at [llms.txt](https://github.com/slatecipher/ClientX/blob/mainline/llms.txt), a compact guide to ClientX's patterns and pitfalls.
123
+
124
+ ## Guide
125
+
126
+ - [Defining endpoints](https://github.com/slatecipher/ClientX/blob/mainline/docs/endpoints.md): the verb decorators and their options, the rules for an endpoint method, deprecating endpoints, and endpoint names.
127
+ - [Building requests](https://github.com/slatecipher/ClientX/blob/mainline/docs/requests.md): how parameters become the path, query string, headers and body.
128
+ - [Responses](https://github.com/slatecipher/ClientX/blob/mainline/docs/responses.md): how the return annotation decides what an endpoint returns, streaming, your own decoder, and errors for 4xx and 5xx responses.
129
+ - [Resources](https://github.com/slatecipher/ClientX/blob/mainline/docs/resources.md): grouping endpoints under a path prefix, nesting them, and plain methods for logic such as pagination.
130
+ - [Client configuration](https://github.com/slatecipher/ClientX/blob/mainline/docs/configuration.md): creating and closing a client, the base URL and `User-Agent` class defaults, authentication, logging and event hooks.
131
+ - [Async clients](https://github.com/slatecipher/ClientX/blob/mainline/docs/async.md): `AsyncClientX` and `AsyncResource` for `async def` endpoints, concurrent requests, and async streaming.
132
+ - [Testing](https://github.com/slatecipher/ClientX/blob/mainline/docs/testing.md): testing a client without the network.
133
+ - [AI tools](https://github.com/slatecipher/ClientX/blob/mainline/docs/tools.md): a client's endpoints as tools a model can call.
134
+ - [Errors](https://github.com/slatecipher/ClientX/blob/mainline/docs/errors.md): the errors ClientX raises, and when.
135
+ - [API reference](https://github.com/slatecipher/ClientX/blob/mainline/docs/reference.md): every public name, with its signature and arguments.
136
+
137
+ ## Development
138
+
139
+ See [CONTRIBUTING.md](https://github.com/slatecipher/ClientX/blob/mainline/CONTRIBUTING.md) for setup, checks, and conventions.
140
+
141
+ ## Acknowledgments
142
+
143
+ ClientX is inspired by FastAPI and built on Pydantic and httpx2, and I'm grateful to the developers behind all three. It's an independent project, though, and isn't affiliated with or endorsed by any of them.
144
+
145
+ ## License
146
+
147
+ ClientX is released under the [MIT License](https://github.com/slatecipher/ClientX/blob/mainline/LICENSE).
@@ -0,0 +1,88 @@
1
+ [project]
2
+ name = "clientx"
3
+ version = "0.1.0"
4
+ description = "A typed, declarative HTTP API client framework for Python"
5
+ readme = "README.md"
6
+ requires-python = ">=3.12"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ keywords = [
10
+ "http",
11
+ "api",
12
+ "client",
13
+ "httpx",
14
+ "httpx2",
15
+ "pydantic",
16
+ "typed",
17
+ "declarative",
18
+ ]
19
+ classifiers = [
20
+ "Development Status :: 3 - Alpha",
21
+ "Framework :: Pydantic :: 2",
22
+ "Intended Audience :: Developers",
23
+ "Operating System :: OS Independent",
24
+ "Programming Language :: Python :: 3",
25
+ "Programming Language :: Python :: 3 :: Only",
26
+ "Programming Language :: Python :: 3.12",
27
+ "Programming Language :: Python :: 3.13",
28
+ "Programming Language :: Python :: 3.14",
29
+ "Topic :: Internet :: WWW/HTTP",
30
+ "Topic :: Software Development :: Libraries",
31
+ "Typing :: Typed",
32
+ ]
33
+ dependencies = [
34
+ "httpx2>=2.10.0",
35
+ "pydantic>=2.12.5",
36
+ ]
37
+
38
+ [[project.authors]]
39
+ name = "slatecipher"
40
+ email = "25094255+slatecipher@users.noreply.github.com"
41
+
42
+ [project.urls]
43
+ Repository = "https://github.com/slatecipher/ClientX"
44
+ Issues = "https://github.com/slatecipher/ClientX/issues"
45
+ Changelog = "https://github.com/slatecipher/ClientX/blob/mainline/CHANGELOG.md"
46
+
47
+ [build-system]
48
+ requires = ["uv_build>=0.12.3,<0.14.0"]
49
+ build-backend = "uv_build"
50
+
51
+ [dependency-groups]
52
+ dev = [
53
+ "mypy>=2.4.1",
54
+ "pyright>=1.1.411",
55
+ "pytest>=9.0.2",
56
+ "pytest-cov>=7.0.0",
57
+ "ruff>=0.14.10",
58
+ ]
59
+
60
+ [tool.pytest]
61
+ addopts = [
62
+ "--import-mode=importlib",
63
+ "-vv",
64
+ "--cov=clientx",
65
+ "--cov-report=term-missing",
66
+ ]
67
+ strict = true
68
+
69
+ [tool.pyright]
70
+ include = [
71
+ "src",
72
+ "test",
73
+ "docs_src",
74
+ "scripts",
75
+ ]
76
+ pythonVersion = "3.12"
77
+ typeCheckingMode = "standard"
78
+ strict = [
79
+ "src",
80
+ "docs_src",
81
+ "scripts",
82
+ ]
83
+ enableTypeIgnoreComments = false
84
+
85
+ [tool.mypy]
86
+ files = ["test/test_typing.py"]
87
+ python_version = "3.12"
88
+ strict = true
@@ -0,0 +1,79 @@
1
+ [project]
2
+ name = "clientx"
3
+ version = "0.1.0"
4
+ description = "A typed, declarative HTTP API client framework for Python"
5
+ readme = "README.md"
6
+ authors = [
7
+ { name = "slatecipher", email = "25094255+slatecipher@users.noreply.github.com" }
8
+ ]
9
+ requires-python = ">=3.12"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ keywords = ["http", "api", "client", "httpx", "httpx2", "pydantic", "typed", "declarative"]
13
+ classifiers = [
14
+ "Development Status :: 3 - Alpha",
15
+ "Framework :: Pydantic :: 2",
16
+ "Intended Audience :: Developers",
17
+ "Operating System :: OS Independent",
18
+ "Programming Language :: Python :: 3",
19
+ "Programming Language :: Python :: 3 :: Only",
20
+ "Programming Language :: Python :: 3.12",
21
+ "Programming Language :: Python :: 3.13",
22
+ "Programming Language :: Python :: 3.14",
23
+ "Topic :: Internet :: WWW/HTTP",
24
+ "Topic :: Software Development :: Libraries",
25
+ "Typing :: Typed",
26
+ ]
27
+ dependencies = [
28
+ "httpx2>=2.10.0",
29
+ "pydantic>=2.12.5",
30
+ ]
31
+
32
+ [project.urls]
33
+ Repository = "https://github.com/slatecipher/ClientX"
34
+ Issues = "https://github.com/slatecipher/ClientX/issues"
35
+ Changelog = "https://github.com/slatecipher/ClientX/blob/mainline/CHANGELOG.md"
36
+
37
+ [build-system]
38
+ requires = ["uv_build>=0.12.3,<0.14.0"]
39
+ build-backend = "uv_build"
40
+
41
+ [dependency-groups]
42
+ dev = [
43
+ "mypy>=2.4.1",
44
+ "pyright>=1.1.411",
45
+ "pytest>=9.0.2",
46
+ "pytest-cov>=7.0.0",
47
+ "ruff>=0.14.10",
48
+ ]
49
+
50
+ [tool.pytest]
51
+ addopts = ["--import-mode=importlib", "-vv", "--cov=clientx", "--cov-report=term-missing"]
52
+ # All of pytest's strictness checks. pytest may add more in a release; uv.lock pins it,
53
+ # so a new one shows up in the Dependabot PR that upgrades pytest, not on mainline.
54
+ strict = true
55
+
56
+ [tool.pyright]
57
+ # Editors check every tree. CI splits them: `make typecheck` passes `src`,
58
+ # `docs_src` and `scripts` on the command line (which overrides this list) and
59
+ # gates the build, while `make typecheck-tests` covers `test` as a non-blocking
60
+ # report.
61
+ include = ["src", "test", "docs_src", "scripts"]
62
+ pythonVersion = "3.12"
63
+ typeCheckingMode = "standard"
64
+ # The shipped package, the docs' samples and scripts are held to strict mode;
65
+ # tests stay on standard.
66
+ strict = ["src", "docs_src", "scripts"]
67
+ # Pyright reads only `# pyright: ignore[...]` comments, and mypy only `# type: ignore[...]`.
68
+ # test/test_typing.py marks each expected error for both checkers, and each checker reports
69
+ # its own comment if it's unused, which it couldn't if pyright also honoured mypy's.
70
+ enableTypeIgnoreComments = false
71
+
72
+ [tool.mypy]
73
+ # mypy checks only the typing contract, the file that pins what type checkers see of
74
+ # decorated endpoints, so mypy users get the same guarantees as pyright users. `make
75
+ # typecheck` runs it, which gates CI. strict mode includes warn_unused_ignores (an
76
+ # expected error that disappears is reported) and check_untyped_defs.
77
+ files = ["test/test_typing.py"]
78
+ python_version = "3.12"
79
+ strict = true
@@ -0,0 +1,39 @@
1
+ """A typed, declarative HTTP API client framework for Python."""
2
+
3
+ from httpx2 import Auth, Request, Response, Timeout
4
+
5
+ from clientx import method
6
+ from clientx._client import AsyncClientX, AsyncResource, ClientX, Resource
7
+ from clientx._version import __version__
8
+ from clientx.arguments import Body, File, Form, Header, Json, Query, Send, Url
9
+ from clientx.exceptions import ArgumentError, ClientXError, DefinitionError
10
+
11
+ __all__ = [
12
+ # clientx._version
13
+ "__version__",
14
+ # httpx2
15
+ "Auth",
16
+ "Request",
17
+ "Response",
18
+ "Timeout",
19
+ # clientx._client
20
+ "AsyncClientX",
21
+ "AsyncResource",
22
+ "ClientX",
23
+ "Resource",
24
+ # clientx.arguments
25
+ "Body",
26
+ "File",
27
+ "Form",
28
+ "Header",
29
+ "Json",
30
+ "Query",
31
+ "Send",
32
+ "Url",
33
+ # clientx.exceptions
34
+ "ArgumentError",
35
+ "ClientXError",
36
+ "DefinitionError",
37
+ # submodules
38
+ "method",
39
+ ]
@@ -0,0 +1,65 @@
1
+ """The machinery behind the ``clientx.arguments`` helpers.
2
+
3
+ ``clientx.arguments`` builds its helpers with ``bind_argument``. A helper marks
4
+ its ``FieldInfo`` by appending its ``HttpxArgument`` to the metadata. The mark
5
+ isn't public, so how a helper marks its ``FieldInfo`` can change without
6
+ breaking users. ``get_httpx_argument`` reads the mark for the rest of ClientX.
7
+ """
8
+
9
+ import functools
10
+ from collections.abc import Callable
11
+ from typing import Any
12
+
13
+ from pydantic.fields import FieldInfo
14
+
15
+ from clientx._types import HttpxArgument
16
+
17
+
18
+ def get_httpx_argument(field_info: object) -> HttpxArgument | None:
19
+ """Return the request part a helper marked ``field_info`` for, or ``None``.
20
+
21
+ A helper adds one mark. If there are several, the last one wins, as the last
22
+ helper in an ``Annotated`` does.
23
+ """
24
+ if not isinstance(field_info, FieldInfo):
25
+ return None
26
+ return next((meta for meta in reversed(field_info.metadata) if isinstance(meta, HttpxArgument)), None)
27
+
28
+
29
+ def bind_argument[**P](
30
+ name: str,
31
+ location: HttpxArgument,
32
+ field_fn: Callable[P, Any],
33
+ ) -> Callable[P, Any]:
34
+ """Wrap ``field_fn`` so each field it creates is marked for ``location``.
35
+
36
+ The wrapper takes the same arguments as ``field_fn`` (through
37
+ ``ParamSpec``), so editors offer ``pydantic.Field``'s parameters for each
38
+ helper. At runtime it has its own name and docstring, and
39
+ ``functools.wraps`` records ``field_fn`` as the wrapped function, so
40
+ ``help()`` and ``inspect.signature()`` show ``field_fn``'s arguments rather
41
+ than ``*args, **kwargs``.
42
+
43
+ Args:
44
+ name: The helper's name, for its ``__name__`` and ``__qualname__``.
45
+ location: The request part to mark each field for.
46
+ field_fn: The function that creates the ``FieldInfo``, normally
47
+ ``pydantic.Field``.
48
+ """
49
+
50
+ @functools.wraps(field_fn)
51
+ def wrapper(*args: P.args, **kwargs: P.kwargs) -> Any:
52
+ field_info = field_fn(*args, **kwargs)
53
+ field_info.metadata.append(location)
54
+ return field_info
55
+
56
+ wrapper.__name__ = wrapper.__qualname__ = name
57
+ # The public module that exports the helpers, so help() and reprs show the
58
+ # path users import from. functools.wraps copied field_fn's module, such as
59
+ # pydantic.fields.
60
+ wrapper.__module__ = "clientx.arguments"
61
+ wrapper.__doc__ = (
62
+ f"Create a ``pydantic.Field`` for an endpoint parameter that goes to the request's ``{location}``.\n\n"
63
+ "Takes the same arguments as ``pydantic.Field``; see ``help(pydantic.Field)``."
64
+ )
65
+ return wrapper