mxhttp 1.0.0__tar.gz

mxhttp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Hörmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mxhttp-1.0.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: mxhttp
+Version: 1.0.0
+Summary: Simple HTTP API consumer based on `httpx` and `msgspec`.
+Keywords: http,httpx,msgspec,rest,api,client,declarative,typing
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/audivir/mxhttp
+Project-URL: Repository, https://github.com/audivir/mxhttp
+Project-URL: Issues, https://github.com/audivir/mxhttp/issues
+Requires-Python: >=3.10
+Requires-Dist: httpx
+Requires-Dist: msgspec
+Requires-Dist: typing-extensions
+Provides-Extra: pydantic
+Requires-Dist: pydantic; extra == "pydantic"
+Description-Content-Type: text/markdown
+
+# mxhttp
+
+Declarative **HTTP** client on top of _**m**sgspec_ and _http**x**_. Write an API as a class of annotated stub methods and `mxhttp` will handle the rest (request building, sending, and response decoding).
+
+## Install
+
+```bash
+pip install mxhttp
+```
+
+## Usage
+
+```python
+from typing import Annotated
+import msgspec
+from mxhttp import Body, Query, SyncConsumer, get, post
+
+
+class Item(msgspec.Struct):
+    id: int
+    name: str
+    price: float
+
+
+class NewItem(msgspec.Struct):
+    name: str
+    price: float
+
+
+class Shop(SyncConsumer):
+    @get("/items/{item_id}")
+    def get_item(self, item_id: int) -> Item: ...  # type: ignore[empty-body]
+
+    @get("/search")
+    def search(self, q: Annotated[str, Query], limit: Annotated[int, Query] = 20) -> list[Item]: ...  # type: ignore[empty-body]
+
+    @post("/items")
+    def create_item(self, item: Annotated[NewItem, Body]) -> Item: ...  # type: ignore[empty-body]
+
+
+shop = Shop("https://api.example.com")
+item = shop.get_item(item_id=7)
+new = shop.create_item(item=NewItem(name="Gadget", price=4.5))
+```
+
+The method body is never run as it is replaced by the decorator. Parameters are bound based on their `Annotated[...]` marker:
+
+| Marker class         | Request Target      | Info                                                                                                                                                                      |
+|----------------------|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `Path` (or implicit) | Path                | Matched by parameter name unless annotated explicitly (`Path["name"]`). Must be a non-nullable `str`, `int`, or `float`.                                                  |
+| `Query`              | Query               | Must be a nullable `str`, `int`, `float`, or `bool`, or a `Sequence` of those, sent as `key=a&key=b&...`.                                                                 |
+| `Field`              | Form Field          | `application/x-www-form-urlencoded`. Accepts same types as `Query`.                                                                                                       |
+| `Part`               | Multipart File Part | Forces the whole request to be multipart and any `Field` params on the same call will become multipart fields as well. Accepts the same types `httpx` takes for `files=`. |
+| `Header`             | HTTP Header         | Must be `str`, `int`, `float`, or `bool`, but no list of those.                                                                                                           |
+| `Cookie`             | Cookie              | Is superseded by the cookie jar of the client if it already has a same-named cookie, unless `override=True` is set. Accepts same types as `Header`                        |
+| `Body`               | JSON Body           | Whole object, serialized with `msgspec.to_builtins`. Can't be a scalar type.                                                                                              |
+
+- Use `Path["name"]`, `Query["name"]`, `Field["name"]`, `Header["name"]`, or `Cookie["name"]` to bind under a different name than the parameter (e.g. reserved `from`, or a header like `X-Request-Id`, unsupported string format arguments like `?`).
+- `None`-valued `Query`, `Field`, `Header`, and `Cookie` parameters are omitted from the request.
+- `Path` parameters cannot be optional as a placeholder cannot be ommited from the URL.
+- Mismatched marker/type combinations raise a `TypeError` as soon as the class body runs, not at call time.
+
+### Decoding the response
+
+The return type defines the reponse decoding:
+- `httpx.Response` for the raw response.
+- `str` or `bytes` for the corresponding `.text` or `.content` with no JSON round-trip.
+- `pydantic.BaseModel` subclasses via their own `.model_validate_json`.
+- Anything else `msgspec.json.decode` can decode: `msgspec.Struct`, dataclasses, `TypedDict`, `NamedTuple`, and `list`, `dict`, or other containers of those.
+- `Response[Item]` for a small struct with the decoded `Item` as `.data` and the raw `httpx.Response` in `.response`.
+- Plain `attrs` classes are decoded by `msgspec`, for type hinting `attrs` is needed as dependency.
+
+For an async client, subclass `AsyncConsumer` and declare the methods `async def`, everything else stays the same.
+
+### Response handling
+
+By default, every response is checked by `response.raise_for_status()` before decoding, so errors during the request raise `httpx.HTTPStatusError` automatically. This behavior can be overriden by `@response_handler` decorator for the class.
+
+```python
+import httpx
+from mxhttp import response_handler
+
+
+def ignore_errors(response: httpx.Response) -> httpx.Response:
+    return response
+
+
+@response_handler(ignore_errors)
+class Shop(SyncConsumer): ...
+```
+
+The hook runs on every response before decoding.
+
+### Streaming responses
+
+Annotate the return type as `Iterator[bytes]` (sync) or `AsyncIterator[bytes]` (async) to stream the response body in chunks.
+
+```python
+from collections.abc import AsyncIterator, Iterator
+
+
+class Files(SyncConsumer):
+    @get("/files/{file_id}")
+    def download(self, file_id: int) -> Iterator[bytes]: ...  # type: ignore[empty-body]
+
+
+for chunk in shop_files.download(file_id=7):
+    ...
+
+class AsyncFiles(AsyncConsumer)
+    @get("/files/{file_id}")
+    def download(self, file_id: int) -> AsyncIterator[bytes]: ...  # type: ignore[empty-body]
+
+async for chunk in await shop_async_files.download(file_id=7):
+    ...
+```
+
+`httpx` already decompresses chunks before responding according to `Content-Encoding` (gzip/deflate/br/zstd).
+
+Streaming responses run `@streaming_response_handler` instead of `@response_handler` (defaults to `raise_for_status` as well).
+The handler can only inspect status line and headers.
+
+```python
+from mxhttp import streaming_response_handler
+
+
+def check_status(response: httpx.Response) -> httpx.Response:
+    response.raise_for_status()
+    return response
+
+
+@streaming_response_handler(check_status)
+class Files(SyncConsumer): ...
+```
+
+### Server-Sent Events
+
+Annotate the return type as `Iterator[Event]` (sync) or `AsyncIterator[Event]` (async) to parse the response as a Server-Sent Events stream instead of raw bytes:
+
+```python
+from collections.abc import Iterator
+from mxhttp import Event
+
+
+class Chat(SyncConsumer):
+    @get("/stream")
+    def events(self) -> Iterator[Event]: ...  # type: ignore[empty-body]
+
+
+for event in chat.events():
+    print(event.event, event.data)  # event.event defaults to "message"
+```
+
+`Event` has four attributes, `data`, `event`, `id`, and `retry`:
+- `data` is the raw payload, decode it manually if the server sends JSON.
+- Multi-line `data` fields are joined with `\n`.
+- `id` and `retry` persist across events once set and reset on reconnect only.
+- An event without a trailing blank line at the end of the stream is discarded.
+
+SSE streams use `@streaming_response_handler` matching byte streaming above.
+
+## Further configuration
+
+The underlying `httpx.Client` or `httpx.AsyncClient` is stored at `.session` to set default headers, auth, or timeouts.
+
+## Typing
+
+The package and all its generators are typed.
+
+## Tests
+
+```bash
+pytest
+```
+
+## Acknowledgements
+
+`mxhttp` is inspired by [Uplink](https://github.com/prkumar/uplink) but combining it with Python typing features.

mxhttp-1.0.0/README.md

@@ -0,0 +1,178 @@
+# mxhttp
+
+Declarative **HTTP** client on top of _**m**sgspec_ and _http**x**_. Write an API as a class of annotated stub methods and `mxhttp` will handle the rest (request building, sending, and response decoding).
+
+## Install
+
+```bash
+pip install mxhttp
+```
+
+## Usage
+
+```python
+from typing import Annotated
+import msgspec
+from mxhttp import Body, Query, SyncConsumer, get, post
+
+
+class Item(msgspec.Struct):
+    id: int
+    name: str
+    price: float
+
+
+class NewItem(msgspec.Struct):
+    name: str
+    price: float
+
+
+class Shop(SyncConsumer):
+    @get("/items/{item_id}")
+    def get_item(self, item_id: int) -> Item: ...  # type: ignore[empty-body]
+
+    @get("/search")
+    def search(self, q: Annotated[str, Query], limit: Annotated[int, Query] = 20) -> list[Item]: ...  # type: ignore[empty-body]
+
+    @post("/items")
+    def create_item(self, item: Annotated[NewItem, Body]) -> Item: ...  # type: ignore[empty-body]
+
+
+shop = Shop("https://api.example.com")
+item = shop.get_item(item_id=7)
+new = shop.create_item(item=NewItem(name="Gadget", price=4.5))
+```
+
+The method body is never run as it is replaced by the decorator. Parameters are bound based on their `Annotated[...]` marker:
+
+| Marker class         | Request Target      | Info                                                                                                                                                                      |
+|----------------------|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `Path` (or implicit) | Path                | Matched by parameter name unless annotated explicitly (`Path["name"]`). Must be a non-nullable `str`, `int`, or `float`.                                                  |
+| `Query`              | Query               | Must be a nullable `str`, `int`, `float`, or `bool`, or a `Sequence` of those, sent as `key=a&key=b&...`.                                                                 |
+| `Field`              | Form Field          | `application/x-www-form-urlencoded`. Accepts same types as `Query`.                                                                                                       |
+| `Part`               | Multipart File Part | Forces the whole request to be multipart and any `Field` params on the same call will become multipart fields as well. Accepts the same types `httpx` takes for `files=`. |
+| `Header`             | HTTP Header         | Must be `str`, `int`, `float`, or `bool`, but no list of those.                                                                                                           |
+| `Cookie`             | Cookie              | Is superseded by the cookie jar of the client if it already has a same-named cookie, unless `override=True` is set. Accepts same types as `Header`                        |
+| `Body`               | JSON Body           | Whole object, serialized with `msgspec.to_builtins`. Can't be a scalar type.                                                                                              |
+
+- Use `Path["name"]`, `Query["name"]`, `Field["name"]`, `Header["name"]`, or `Cookie["name"]` to bind under a different name than the parameter (e.g. reserved `from`, or a header like `X-Request-Id`, unsupported string format arguments like `?`).
+- `None`-valued `Query`, `Field`, `Header`, and `Cookie` parameters are omitted from the request.
+- `Path` parameters cannot be optional as a placeholder cannot be ommited from the URL.
+- Mismatched marker/type combinations raise a `TypeError` as soon as the class body runs, not at call time.
+
+### Decoding the response
+
+The return type defines the reponse decoding:
+- `httpx.Response` for the raw response.
+- `str` or `bytes` for the corresponding `.text` or `.content` with no JSON round-trip.
+- `pydantic.BaseModel` subclasses via their own `.model_validate_json`.
+- Anything else `msgspec.json.decode` can decode: `msgspec.Struct`, dataclasses, `TypedDict`, `NamedTuple`, and `list`, `dict`, or other containers of those.
+- `Response[Item]` for a small struct with the decoded `Item` as `.data` and the raw `httpx.Response` in `.response`.
+- Plain `attrs` classes are decoded by `msgspec`, for type hinting `attrs` is needed as dependency.
+
+For an async client, subclass `AsyncConsumer` and declare the methods `async def`, everything else stays the same.
+
+### Response handling
+
+By default, every response is checked by `response.raise_for_status()` before decoding, so errors during the request raise `httpx.HTTPStatusError` automatically. This behavior can be overriden by `@response_handler` decorator for the class.
+
+```python
+import httpx
+from mxhttp import response_handler
+
+
+def ignore_errors(response: httpx.Response) -> httpx.Response:
+    return response
+
+
+@response_handler(ignore_errors)
+class Shop(SyncConsumer): ...
+```
+
+The hook runs on every response before decoding.
+
+### Streaming responses
+
+Annotate the return type as `Iterator[bytes]` (sync) or `AsyncIterator[bytes]` (async) to stream the response body in chunks.
+
+```python
+from collections.abc import AsyncIterator, Iterator
+
+
+class Files(SyncConsumer):
+    @get("/files/{file_id}")
+    def download(self, file_id: int) -> Iterator[bytes]: ...  # type: ignore[empty-body]
+
+
+for chunk in shop_files.download(file_id=7):
+    ...
+
+class AsyncFiles(AsyncConsumer)
+    @get("/files/{file_id}")
+    def download(self, file_id: int) -> AsyncIterator[bytes]: ...  # type: ignore[empty-body]
+
+async for chunk in await shop_async_files.download(file_id=7):
+    ...
+```
+
+`httpx` already decompresses chunks before responding according to `Content-Encoding` (gzip/deflate/br/zstd).
+
+Streaming responses run `@streaming_response_handler` instead of `@response_handler` (defaults to `raise_for_status` as well).
+The handler can only inspect status line and headers.
+
+```python
+from mxhttp import streaming_response_handler
+
+
+def check_status(response: httpx.Response) -> httpx.Response:
+    response.raise_for_status()
+    return response
+
+
+@streaming_response_handler(check_status)
+class Files(SyncConsumer): ...
+```
+
+### Server-Sent Events
+
+Annotate the return type as `Iterator[Event]` (sync) or `AsyncIterator[Event]` (async) to parse the response as a Server-Sent Events stream instead of raw bytes:
+
+```python
+from collections.abc import Iterator
+from mxhttp import Event
+
+
+class Chat(SyncConsumer):
+    @get("/stream")
+    def events(self) -> Iterator[Event]: ...  # type: ignore[empty-body]
+
+
+for event in chat.events():
+    print(event.event, event.data)  # event.event defaults to "message"
+```
+
+`Event` has four attributes, `data`, `event`, `id`, and `retry`:
+- `data` is the raw payload, decode it manually if the server sends JSON.
+- Multi-line `data` fields are joined with `\n`.
+- `id` and `retry` persist across events once set and reset on reconnect only.
+- An event without a trailing blank line at the end of the stream is discarded.
+
+SSE streams use `@streaming_response_handler` matching byte streaming above.
+
+## Further configuration
+
+The underlying `httpx.Client` or `httpx.AsyncClient` is stored at `.session` to set default headers, auth, or timeouts.
+
+## Typing
+
+The package and all its generators are typed.
+
+## Tests
+
+```bash
+pytest
+```
+
+## Acknowledgements
+
+`mxhttp` is inspired by [Uplink](https://github.com/prkumar/uplink) but combining it with Python typing features.

mxhttp-1.0.0/mxhttp/__init__.py

@@ -0,0 +1,36 @@
+"""Minimal typed declarative HTTP client."""
+
+from __future__ import annotations
+
+from mxhttp.consumer import AsyncConsumer, SyncConsumer
+from mxhttp.endpoint import delete, endpoint, get, head, patch, post, put
+from mxhttp.markers import Body, Cookie, Field, Header, Part, Path, Query
+from mxhttp.response import Response, response_handler, streaming_response_handler
+from mxhttp.sse import Event
+from mxhttp.types import PartValue
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AsyncConsumer",
+    "Body",
+    "Cookie",
+    "Event",
+    "Field",
+    "Header",
+    "Part",
+    "PartValue",
+    "Path",
+    "Query",
+    "Response",
+    "SyncConsumer",
+    "delete",
+    "endpoint",
+    "get",
+    "head",
+    "patch",
+    "post",
+    "put",
+    "response_handler",
+    "streaming_response_handler",
+]

mxhttp-1.0.0/mxhttp/consumer.py

@@ -0,0 +1,95 @@
+"""Base classes for the declarative HTTP consumers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from typing_extensions import Self, override
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    import httpx
+
+    from mxhttp.types import ResponseHandler
+
+
+class BaseConsumer:
+    """Base class for the sync and async declarative API client."""
+
+    _response_handler: ResponseHandler | None = None
+    _streaming_response_handler: ResponseHandler | None = None
+
+    def __init__(self, base_url: str, *, use_async: bool = False) -> None:
+        """Initializes the client bound to `base_url` with an empty header dict."""
+        import httpx
+
+        self.base_url = base_url.rstrip("/")
+        self._session = (
+            httpx.AsyncClient(base_url=self.base_url)
+            if use_async
+            else httpx.Client(base_url=self.base_url)
+        )
+
+    @override
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"{type(self).__name__}<{self.base_url}>"
+
+    @property
+    def session(self) -> httpx.Client | httpx.AsyncClient:
+        """The HTTP client used for outbound requests."""
+        return self._session
+
+
+class SyncConsumer(BaseConsumer):
+    """Base class for the synchronous declarative API client."""
+
+    def __init__(self, base_url: str) -> None:
+        """Initializes the client bound to `base_url` with an empty header dict."""
+        super().__init__(base_url, use_async=False)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.session.close()
+
+    if TYPE_CHECKING:
+
+        @override
+        @property
+        def session(self) -> httpx.Client:
+            """The synchronous HTTP client."""
+            return self._session  # type: ignore[return-value]
+
+
+class AsyncConsumer(BaseConsumer):
+    """Base class for the asynchronous declarative API client."""
+
+    def __init__(self, base_url: str) -> None:
+        """Initializes the client bound to `base_url` with an empty header dict."""
+        super().__init__(base_url, use_async=True)
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.session.aclose()
+
+    if TYPE_CHECKING:
+
+        @override
+        @property
+        def session(self) -> httpx.AsyncClient:
+            """The asynchronous HTTP client."""
+            return self._session  # type: ignore[return-value]