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 +21 -0
- clientx-0.1.0/PKG-INFO +176 -0
- clientx-0.1.0/README.md +147 -0
- clientx-0.1.0/pyproject.toml +88 -0
- clientx-0.1.0/pyproject.toml.orig +79 -0
- clientx-0.1.0/src/clientx/__init__.py +39 -0
- clientx-0.1.0/src/clientx/_arguments.py +65 -0
- clientx-0.1.0/src/clientx/_builder.py +429 -0
- clientx-0.1.0/src/clientx/_class_setup.py +252 -0
- clientx-0.1.0/src/clientx/_client.py +300 -0
- clientx-0.1.0/src/clientx/_decoding.py +240 -0
- clientx-0.1.0/src/clientx/_endpoint.py +276 -0
- clientx-0.1.0/src/clientx/_method.py +198 -0
- clientx-0.1.0/src/clientx/_planner.py +1281 -0
- clientx-0.1.0/src/clientx/_registry.py +32 -0
- clientx-0.1.0/src/clientx/_signature.py +312 -0
- clientx-0.1.0/src/clientx/_tools.py +440 -0
- clientx-0.1.0/src/clientx/_types.py +313 -0
- clientx-0.1.0/src/clientx/_version.py +5 -0
- clientx-0.1.0/src/clientx/arguments.py +60 -0
- clientx-0.1.0/src/clientx/exceptions.py +61 -0
- clientx-0.1.0/src/clientx/method.py +16 -0
- clientx-0.1.0/src/clientx/py.typed +0 -0
- clientx-0.1.0/src/clientx/tools.py +23 -0
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).
|
clientx-0.1.0/README.md
ADDED
|
@@ -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
|