wrapfast 0.0.2__py3-none-any.whl

wrapfast/__init__.py

@@ -0,0 +1,19 @@
+"""wrapfast — pluggable HTTP client: transport, session, and presentation layers."""
+
+from .application import Endpoint, HttpClient
+from .presentation import PresentationCodec
+from .session import Session
+from .transport import AsyncTransport, HttpRequest, HttpResponse, Transport
+
+__all__ = [
+    "AsyncTransport",
+    "Endpoint",
+    "HttpClient",
+    "HttpRequest",
+    "HttpResponse",
+    "PresentationCodec",
+    "Session",
+    "Transport",
+]
+
+__version__ = "0.1.0"

wrapfast/application.py

@@ -0,0 +1,43 @@
+from dataclasses import dataclass
+
+from .presentation import PresentationCodec
+from .session import Session
+from .transport import HttpRequest, Transport
+
+
+@dataclass
+class Endpoint[T_Request, T_Response]:
+    method: str
+    path: str
+    request_type: type[T_Request]
+    response_type: type[T_Response]
+
+
+class HttpClient:
+    def __init__(
+        self,
+        base_url: str,
+        transport: Transport,
+        session: Session,
+        presentation_codec: PresentationCodec,
+    ) -> None:
+        self._base_url = base_url
+        self._transport = transport
+        self._session = session
+        self._presentation_codec = presentation_codec
+
+    def send[T_Request, T_Response](
+        self, endpoint: Endpoint[T_Request, T_Response], request: T_Request
+    ) -> T_Response:
+        http_req = HttpRequest(
+            method=endpoint.method,
+            url=f"{self._base_url}{endpoint.path}"
+            if not endpoint.path.startswith("/")
+            else endpoint.path,
+            headers={"Content-Type": self._presentation_codec.get_content_type()},
+            data=self._presentation_codec.encode(request),
+        )
+        http_req = self._session.wrap_request(http_req)
+        http_resp = self._transport.send(http_req)
+        http_resp = self._session.unwrap_response(http_resp)
+        return self._presentation_codec.decode(http_resp.data, endpoint.response_type)

wrapfast/presentation.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class PresentationCodec(ABC):
+    @abstractmethod
+    def get_content_type(self) -> str: ...
+
+    @abstractmethod
+    def encode(self, obj: Any) -> bytes: ...
+
+    @abstractmethod
+    def decode(self, data: bytes, target: type) -> Any: ...

wrapfast/session.py

@@ -0,0 +1,11 @@
+from abc import ABC, abstractmethod
+
+from .transport import HttpRequest, HttpResponse
+
+
+class Session(ABC):
+    @abstractmethod
+    def wrap_request(self, request: HttpRequest) -> HttpRequest: ...
+
+    @abstractmethod
+    def unwrap_response(self, response: HttpResponse) -> HttpResponse: ...

wrapfast/transport.py

@@ -0,0 +1,28 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Mapping
+
+
+@dataclass
+class HttpRequest:
+    method: str
+    url: str
+    headers: Mapping[str, str]
+    data: bytes
+
+
+@dataclass
+class HttpResponse:
+    status_code: int
+    headers: Mapping[str, str]
+    data: bytes
+
+
+class Transport(ABC):
+    @abstractmethod
+    def send(self, request: HttpRequest) -> HttpResponse: ...
+
+
+class AsyncTransport(ABC):
+    @abstractmethod
+    async def send(self, request: HttpRequest) -> HttpResponse: ...

wrapfast-0.0.2.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: wrapfast
+Version: 0.0.2
+Summary: Composable HTTP API client: pluggable transport, session, and presentation layers for maintainable wrappers.
+Project-URL: Repository, https://github.com/UnknownAPI/wrapfast
+Project-URL: Issues, https://github.com/UnknownAPI/wrapfast/issues
+Author: wrapfast contributors
+License-Expression: 0BSD
+License-File: LICENSE
+Keywords: api,api-client,http,http-client,rest,typing,wrapper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Provides-Extra: examples
+Requires-Dist: pydantic>=2; extra == 'examples'
+Requires-Dist: requests>=2.31; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# wrapfast
+
+**wrapfast** is a small Python library with a big opinion: API clients stay maintainable when you **separate concerns** instead of growing a single “do everything” class.
+
+It exists to promote **good practice**, **clear organisation**, and **real flexibility** when you wrap REST (or HTTP-shaped) APIs in Python. You compose a pipeline from a few roles—each one easy to test, swap, or extend—instead of hard‑coding `requests.get` next to auth logic next to JSON parsing next to URL strings scattered across the codebase.
+
+---
+
+## The idea in one glance
+
+| Piece | Responsibility |
+|--------|----------------|
+| **`Transport`** | How a request leaves your process and bytes come back (`requests`, `httpx`, a mock, async later). |
+| **`Session`** | Cross‑cutting behaviour around the wire call: tokens, headers, cookies, tracing, optional response handling. |
+| **`PresentationCodec`** | How typed domain objects become bytes and back (JSON + Pydantic, `msgspec`, plain `dict`, …). |
+| **`Endpoint`** | A named operation: HTTP method, path, and the request/response types you expect. |
+| **`HttpClient`** | The thin orchestrator: build `HttpRequest` → session → transport → session → decode. |
+
+That split is the point: **organisation** (each type has one job), **good practice** (test transports and codecs without the network; test sessions without JSON details), and **flexibility** (change transport or codec without rewriting your endpoints).
+
+---
+
+## Code that shows the shape
+
+This is intentionally dense: it is the whole architecture on one screen, using **Pydantic** for request/response models and JSON.
+
+```python
+import requests
+from pydantic import BaseModel, ConfigDict
+
+from wrapfast import (
+    Endpoint,
+    HttpClient,
+    HttpRequest,
+    HttpResponse,
+    PresentationCodec,
+    Session,
+    Transport,
+)
+
+
+class User(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    id: int
+    name: str
+
+
+GET_USER = Endpoint("GET", "users/1", type(None), User)
+
+
+class RequestsTransport(Transport):
+    def send(self, request: HttpRequest) -> HttpResponse:
+        r = requests.request(
+            request.method,
+            request.url,
+            headers=request.headers,
+            data=request.data or None,
+            timeout=30,
+        )
+        return HttpResponse(r.status_code, {k.lower(): v for k, v in r.headers.items()}, r.content)
+
+
+class BearerSession(Session):
+    def __init__(self, token: str) -> None:
+        self._token = token
+
+    def wrap_request(self, request: HttpRequest) -> HttpRequest:
+        h = {**request.headers, "authorization": f"Bearer {self._token}"}
+        return HttpRequest(request.method, request.url, h, request.data)
+
+    def unwrap_response(self, response: HttpResponse) -> HttpResponse:
+        return response  # e.g. 401 → refresh token, logging, metrics
+
+
+class PydanticJsonCodec(PresentationCodec):
+    def get_content_type(self) -> str:
+        return "application/json"
+
+    def encode(self, obj: object) -> bytes:
+        if obj is None:
+            return b""
+        if isinstance(obj, BaseModel):
+            return obj.model_dump_json(exclude_none=True).encode("utf-8")
+        raise TypeError("encode expects None or a Pydantic model")
+
+    def decode(self, data: bytes, target: type):
+        if not isinstance(target, type) or not issubclass(target, BaseModel):
+            raise TypeError("decode target must be a BaseModel subclass")
+        return target.model_validate_json(data)
+
+
+client = HttpClient(
+    base_url="https://api.example.com/",
+    transport=RequestsTransport(),
+    session=BearerSession("<access token>"),
+    presentation_codec=PydanticJsonCodec(),
+)
+
+user = client.send(GET_USER, None)  # User: validated model, not raw JSON
+```
+
+Add **`pydantic`** and **`requests`** to your environment when using this pattern (also bundled as the optional **`examples`** extra in this repo).
+
+**`HttpClient`** is the spine: it does not know *which* HTTP library you use, *how* you authenticate, or *how* bodies are serialised. Those are **policies** you inject. Your API surface becomes a set of **`Endpoint`** values plus **Pydantic models** (or other types you teach the codec)—easier to read, review, and reuse.
+
+`PresentationCodec`, `Transport`, `Session`, and async `AsyncTransport` are abstract bases (`abc.ABC`). Codecs implement `get_content_type()` (used for the outbound `Content-Type` header), `encode`, and `decode`; transports and sessions implement the `send` / `wrap_request` / `unwrap_response` hooks shown above.
+
+---
+
+## Why it matters
+
+- **Tests**: fake `Transport` returns canned `HttpResponse`; no sockets.
+- **Auth**: evolve `Session` (login, refresh, header rules) without touching codecs.
+- **Formats**: swap JSON for another codec at the edge without renaming your domain models’ usage sites.
+- **Readability**: endpoints read like a table of operations; the “how we call HTTP” story lives in a few small classes.
+
+---
+
+## Project layout & example
+
+| Path | Role |
+|------|------|
+| `src/wrapfast/` | Installable package: `HttpClient`, protocols, `Endpoint`. |
+| `examples/dummyjson_requests.py` | End‑to‑end sample: `requests`, Pydantic, bearer **session** (login, `/auth/me`, refresh). |
+
+After `pip install wrapfast`, use `import wrapfast`. From a clone without installing, add the `src` directory to `PYTHONPATH` (see **`examples/dummyjson_requests.py`**). A fuller DummyJSON walkthrough lives in that example.
+
+---
+
+## Requirements
+
+Python **3.13+** (see `pyproject.toml`). The library itself has no required runtime dependencies; pair it with **your** transport and codec. The README snippet and **`examples`** extra use **Pydantic** and **`requests`**.
+
+---
+
+## License
+
+This project is released under the [**0BSD**](https://opensource.org/licenses/0BSD) license (see [`LICENSE`](LICENSE)): use it for anything, with no attribution requirement and minimal legal boilerplate. It is one of the most permissive widely used open-source terms for software.

wrapfast-0.0.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+wrapfast/__init__.py,sha256=yCDfWEhNJIObr1UXPSTGhkYs6kGrf7r3KqUey9Qspbw,492
+wrapfast/application.py,sha256=_81v0y1hKVrb5eQ3hdCjL2wNfGAxSfh4sMFghwC9a-M,1440
+wrapfast/presentation.py,sha256=liTWdBYae-Vs8Ewvk3IKkKHjociRx6zrqGhRbTuy5nY,314
+wrapfast/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wrapfast/session.py,sha256=3UH9AZRB64S28cjBTKLs_4GK6Y4LqJrS_cJpyXI1GDk,304
+wrapfast/transport.py,sha256=sUWxONdIYxsNFRrj4Wzp_OKEiuMwSH4xBCXtAg7mbYo,557
+wrapfast-0.0.2.dist-info/METADATA,sha256=ppsmOMQTlQtM6fu07wVjB1oYSXGK0zOUmHztDfdCLvU,7088
+wrapfast-0.0.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+wrapfast-0.0.2.dist-info/licenses/LICENSE,sha256=wlzGe99oZkutSpDmkYVZPUA3Wsz53o7QURMrn8OqsLo,661
+wrapfast-0.0.2.dist-info/RECORD,,

wrapfast-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

wrapfast-0.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,12 @@
+Copyright (c) 2026 wrapfast contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.