clientity 0.1.6__tar.gz

clientity-0.1.6/.gitignore

@@ -0,0 +1,51 @@
+# scaffold/contents/GITIGNORE
+
+.gitignore
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.venv
+venv/
+ENV/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.DS_Store
+*.swp
+*.swo
+*~
+.idea/
+.vscode/.gitignore
+.DS_Store
+venv.command
+pyrightconfig.json
+
+.venv/
+__pycache__/
+.pytest_cache/
+temp/
+sandbox/
+notes/
+handlers/
+contents/

clientity-0.1.6/PKG-INFO

@@ -0,0 +1,318 @@
+Metadata-Version: 2.4
+Name: clientity
+Version: 0.1.6
+Summary: rapid http clients
+Author-email: Joel Yisrael <schizoprada@gmail.com>
+Requires-Dist: loguru
+Requires-Dist: pydantic
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Provides-Extra: engines
+Requires-Dist: aiohttp; extra == 'engines'
+Requires-Dist: httpx; extra == 'engines'
+Requires-Dist: requests; extra == 'engines'
+Description-Content-Type: text/markdown
+
+# clientity
+
+Rapid HTTP clients with operator-based endpoint definitions.
+
+## Installation
+
+```bash
+pip install clientity
+```
+
+With your preferred HTTP library:
+
+```bash
+pip install clientity[httpx]    # or requests, aiohttp
+```
+
+## Quick Start
+
+```python
+import httpx
+from dataclasses import dataclass
+from clientity import client, endpoint, Resource
+
+# Define response models
+@dataclass
+class User:
+    id: int
+    name: str
+    email: str
+
+@dataclass
+class Status:
+    ok: bool
+    version: str
+
+# Create client
+api = client(httpx.AsyncClient()) @ "https://api.example.com"
+
+# Define endpoints with operators
+api.status = endpoint.get @ "/status" >> Status
+api.user = endpoint.get @ "/users/{id}" >> User
+api.users = endpoint.get @ "/users" >> list[User]
+
+# Use it
+async def main():
+    status = await api.status()
+    user = await api.user(id=123)
+    users = await api.users()
+```
+
+## Operators
+
+| Operator | Method | Description |
+|----------|--------|-------------|
+| `@` | `.at(path)` | Set endpoint path |
+| `%` | `.queries(model)` | Set query parameter model |
+| `<<` | `.requests(model)` | Set request body model |
+| `>>` | `.responds(model)` | Set response model |
+| `&` | `.prehook(fn)` | Add pre-request hook |
+| `\|` | `.posthook(fn)` | Add post-response hook |
+
+```python
+# Full example
+api.search = (
+    endpoint.post 
+    @ "/search" 
+    % SearchQuery      # query params
+    << SearchBody      # request body
+    >> list[Result]    # response model
+    & log_request      # pre-hook [(Request) -> Request]
+    | log_response     # post-hook [(Response) -> Response]
+)
+
+results = await api.search(q="python", limit=10, filters={"type": "code"})
+```
+
+## Path Parameters
+
+Path parameters are extracted from `{param}` syntax and can be passed positionally or by name:
+
+```python
+api.user = endpoint.get @ "/users/{user_id}/posts/{post_id}"
+
+# Both work:
+post = await api.user(123, 456)
+post = await api.user(user_id=123, post_id=456)
+```
+
+## Query & Body Models
+
+Use dataclasses or Pydantic models for query parameters and request bodies:
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class SearchQuery:
+    q: str
+    limit: int = 10
+    offset: int = 0
+
+@dataclass
+class CreateUser:
+    name: str
+    email: str
+
+api.search = endpoint.get @ "/search" % SearchQuery
+api.create_user = endpoint.post @ "/users" << CreateUser
+
+# Query params from model fields
+results = await api.search(q="python", limit=20)
+
+# Body from model fields  
+user = await api.create_user(name="Joel", email="joel@example.com")
+```
+
+## Response Models
+
+### Single Model
+
+```python
+@dataclass
+class User:
+    id: int
+    name: str
+
+api.user = endpoint.get @ "/users/{id}" >> User
+user = await api.user(id=1)  # Returns User instance
+```
+
+### List Response
+
+```python
+api.users = endpoint.get @ "/users" >> list[User]
+users = await api.users()  # Returns list[User]
+```
+
+### Custom Response Handling
+
+Implement `__respond__` for custom single-item parsing:
+
+```python
+@dataclass
+class User:
+    id: int
+    name: str
+    
+    @classmethod
+    def __respond__(cls, response) -> 'User':
+        data = response.json()["data"]["user"]
+        return cls(**data)
+```
+
+Implement `__respondall__` for custom list parsing:
+
+```python
+@dataclass  
+class User:
+    id: int
+    name: str
+    
+    @classmethod
+    def __respondall__(cls, response) -> list['User']:
+        data = response.json()
+        return [cls(**u) for u in data["results"]]
+```
+
+## Resources
+
+Group related endpoints under a path prefix:
+
+```python
+from clientity import Resource
+
+users = Resource("users")
+users.list = endpoint.get @ "" >> list[User]
+users.get = endpoint.get @ "{id}" >> User
+users.create = endpoint.post @ "" << CreateUser >> User
+users.delete = endpoint.delete @ "{id}"
+
+api.users = users
+
+# Usage
+all_users = await api.users.list()
+user = await api.users.get(id=123)
+new_user = await api.users.create(name="Joel", email="joel@example.com")
+await api.users.delete(id=123)
+```
+
+### Nested Resources
+
+```python
+api_resource = Resource("api")
+v1 = Resource("v1")
+v1.users = endpoint.get @ "users" >> list[User]
+v1.posts = endpoint.get @ "posts" >> list[Post]
+api_resource.v1 = v1
+
+api.api = api_resource
+
+# Resolves to /api/v1/users
+users = await api.api.v1.users()
+```
+
+## Namespaces
+
+For endpoints with different base URLs or independent HTTP clients:
+
+```python
+from clientity import Namespace
+
+# Independent namespace with own client
+search = Namespace(
+    base="https://search.example.com",
+    interface=httpx.AsyncClient()
+)
+search.query = endpoint.post @ "/query" >> list[Result]
+
+api.search = search
+
+# Uses search.example.com, not api.example.com
+results = await api.search.query(q="test")
+```
+
+Dependent namespace (uses parent client):
+
+```python
+auth = Namespace(name="auth")
+auth.login = endpoint.post @ "/auth/login" << Credentials >> Token
+
+api.auth = auth
+
+# Uses api.example.com/auth/login
+token = await api.auth.login(username="joel", password="secret")
+```
+
+## Hooks
+
+Pre-hooks modify the request before sending:
+
+```python
+def add_auth(request):
+    request.headers["Authorization"] = "Bearer token123"
+    return request
+
+api.secure = endpoint.get @ "/secure" & add_auth
+```
+
+Post-hooks modify the response after receiving:
+
+```python
+def log_response(response):
+    print(f"Status: {response.status_code}")
+    return response
+
+api.logged = endpoint.get @ "/data" | log_response
+```
+
+Async hooks work too:
+
+```python
+async def refresh_token(request):
+    token = await get_fresh_token()
+    request.headers["Authorization"] = f"Bearer {token}"
+    return request
+
+api.secure = endpoint.get @ "/secure" & refresh_token
+```
+
+## Supported HTTP Libraries
+
+clientity adapts to your preferred HTTP library:
+
+```python
+# httpx (sync or async)
+import httpx
+api = client(httpx.AsyncClient()) @ "https://api.example.com"
+api = client(httpx.Client()) @ "https://api.example.com"
+
+# requests
+import requests
+api = client(requests.Session()) @ "https://api.example.com"
+
+# aiohttp
+import aiohttp
+api = client(aiohttp.ClientSession()) @ "https://api.example.com"
+```
+
+## Lazy Interface
+
+Pass a callable to defer client creation:
+
+```python
+def make_client():
+    return httpx.AsyncClient(headers={"X-API-Key": os.environ["API_KEY"]})
+
+api = client(make_client) @ "https://api.example.com"
+```
+
+## License
+
+MIT

clientity-0.1.6/docs/CHANGELOG.md

@@ -0,0 +1,129 @@
+# `clientity` -- changelog
+
+## [0.1.6] -- Jan. 6th, 2026
+
+### Added
++ **Execution utilities**: `http.execute` and `http.respond` extracted from Client/Namespace
++ **`groupings()` iterator**: On `Grouping` base class for iterating nested Resource/Namespace
++ **Integration test suite**: Full flow tests for Client → Resource → Namespace → Endpoint
+
+### Changed
+* **Operator mappings**: `%` for query model, `&` for prehook, `|` for posthook (precedence fix)
+* **Phantom types for DX**: Operators return `Bound[Endpoint]` to type checkers via `TYPE_CHECKING` block
+* **`embody()` fallback**: Now calls `dictate()` for unknown object types
+
+### Fixed
+* `Resource.__nest__` / `Namespace.__nest__` double-prepend bug (strips child location prefix)
+* `Client.__sourced` nested grouping re-nesting (bypass `__setattr__` with `object.__setattr__`)
+* `Grouping.__setattr__` changed `if` to `elif` for Grouping check
+* Various type hints: `Stringable` for URL params, `respond` overloads, `AsyncInterface` return types
+
+---
+
+## Current Agenda
+
+### Immediate
+1. Revisit DX typing for nested resource/namespace attribute access (`client.users.list` shows `Any`)
+
+### Pinned for Later
+1. IDE typing / signatures (`Unpack[TypedDict]` for kwargs autocomplete)
+2. Iterable response models
+3. WebSocket clients
+4. CLI generation
+
+## [0.1.5] -- Jan. 4th, 2026
+
+### Added
++ **Grouping system**: Base `Grouping` class for organizing endpoints
+  - `Resource`: Dependent grouping with relative `location`, prepends path to nested endpoints
+  - `Namespace`: Independent grouping with absolute `base`, optional own `interface`/`adapter`
+  - Nested resource support with `__nest__` and `Located` protocol
+  - `endpoints()` iterator utility on base `Grouping`
+
++ **Adapters**: Library-specific request building and sending
+  - `Adapter` ABC with `build()` and `send()` methods
+  - `RequestsAdapter` for `requests` library
+  - `HttpxAdapter` for `httpx` library  
+  - `AiohttpAdapter` for `aiohttp` library (fire-and-forget or session reuse modes)
+  - `adapt()` factory function with `Compatible()` detection
+
++ **Utilities**:
+  - `synced`: Inverse of `asynced` - wraps async callables to sync with `eval` option
+  - `dictate`: Extract dict from model instances (pydantic, dataclass, etc.)
+  - `sift.instructions()`: Convenience method for sifting with `Instructions`
+  - `domain()`: Extract domain name from URL
+  - `bound()`: Moved to utils/typers.py
+
++ **Type hints**:
+  - `Located` protocol for objects with `location` attribute
+  - `Requested` hint for embody input
+  - `Responded` hint for execution return type
+  - `WrappedEndpoint` = `Union[Endpoint, Bound[Endpoint]]`
+
+### Changed
+* `Location.__new__`: Now idempotent - returns existing Location unchanged
+* `Location.name`: Property returning PascalCase name from path segments (excluding params)
+* `Endpoint.mutate()`: Public method exposing `__copy` for modification
+* `Client.__init__`: Now accepts `Interfacing` (interface or callable returning interface)
+* `embody()`: Parameter type changed from `Requesting` to `Optional[Requested]`
+
+### Fixed
+* `synced`/`asynced` overload signatures for proper type inference
+* Name mangling issues with abstract methods (`__wrap__` -> `__wrap__`)
+
+---
+
+## Current Agenda
+
+### Immediate
+1. Update `Client` to handle `Resource` and `Namespace` assignment in `__setattr__`
+2. Extract shared execution logic from `Client.__x` and `Namespace.__x` into utility
+3. Test full flow: Client -> Resource -> Endpoint -> execution
+
+### Pending
+- IDE typing / signatures (`Unpack[TypedDict]` for kwargs autocomplete)
+- `domain()` utility implementation (currently raises)
+
+### Pinned for Later
+1. **Iterable response models**: Handle `list[Item]` responses, sequence parsing, `__responds__` for collections
+2. **WebSocket clients**: Different protocol handling, maybe `ws_endpoint` or separate client type
+3. **CLI generation**: `clientity generate --source /path/to/spec --destination /path/to/client.py` from OpenAPI/FastAPI/Flask specs
+
+---
+
+## [0.1.0] -- Dec. 29, 2025
+* Initial project scaffolding and core primitives
+
+### Added
++ **Project Structure**: Established base package layout with `core/`, `exc/`, and logging infrastructure
++ **Logging**: Configurable logging via `CLIENTITYLOGS` environment variable with `devnull` fallback
++ **Exceptions**: Base `ClientityError` exception class
+
++ **Protocols**:
+  - `SyncInterface` / `AsyncInterface`: Runtime-checkable protocols for HTTP engines (requests, httpx, aiohttp, etc.)
+  - `Requestable`: Protocol for request models with `__request__()` method and optional `RequestKey` class var
+  - `Responsive`: Protocol for response models with `__respond__()` classmethod
+
++ **Primitives**:
+  - `Location`: Path fragment class with parameter extraction (`{id}`), `/` operator for joining, and `resolve()` for substitution
+  - `URL`: Full URL class combining base + location, with `resolve()` for final string output
+  - `MethodType`: Literal type for HTTP methods with constants (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`)
+  - `Hooks`: Container for pre/post request hooks with async conversion via `before`/`after` properties
+  - `Instructions`: Core instruction set containing method, location, hooks, and models (querying, requesting, responding) with `merge()` and `prepend()` methods
+
++ **Endpoint**:
+  - `Endpoint`: Builder class for constructing `Instructions` via method chaining
+  - `endpoint` factory with method-specific properties (`.get`, `.post`, `.put`, etc.)
+  - Operator overloads: `@` (location), `|` (hooks), `<<` (request models), `>>` (response model)
+
++ **Utilities**:
+  - `asynced`: Utility for wrapping sync callables as async
+  - `embody`: Utility for encoding request objects to `(key, data)` tuples
+
+### Architecture
++ **Reverse-cascade design**: Endpoints return instruction sets that bubble up to client for execution
++ **Engine agnostic**: Interface protocols accept any HTTP library that quacks correctly
++ **Sift pattern** (pending): kwargs distributed to path/query/body based on model field introspection
+
+## [0.0.0] -- Dec. 28, 2025
+* Project Initialized