Metadata-Version: 2.4
Name: hrest-py
Version: 0.1.4
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: starlette>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: cffi>=1.15.0
Requires-Dist: pytest>=7 ; extra == 'dev'
Requires-Dist: httpx>=0.24 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21 ; extra == 'dev'
Requires-Dist: fastapi>=0.100 ; extra == 'dev'
Requires-Dist: anyio[trio] ; extra == 'dev'
Requires-Dist: fastapi>=0.100 ; extra == 'fastapi'
Provides-Extra: dev
Provides-Extra: fastapi
License-File: LICENSE
Summary: HRest - High Performance REST over HTTP with Binary Payloads
Keywords: hrest,binary,protocol,fastapi,middleware,pydantic
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/oririfai/hrest-py/issues
Project-URL: Repository, https://github.com/oririfai/hrest-py
Project-URL: hrest-core, https://github.com/oririfai/hrest-core

# HRest Python (hrest-py)

[Benchmark](https://github.com/oririfai/hrest-benchmark) | [Core](https://github.com/oririfai/hrest-core) | [CLI](https://github.com/oririfai/hrest-cli) | [Python](https://github.com/oririfai/hrest-py) | [Node](https://github.com/oririfai/hrest-node) | [Go](https://github.com/oririfai/hrest-go) | [TS](https://github.com/oririfai/hrest-ts)

---

HRest Python provides the enterprise-grade integration layer for the Hyper-REST (HRest) protocol in Python applications. By acting as a standard ASGI/WSGI middleware, it intercepts binary HRest requests, performs zero-copy binary-to-JSON translation via PyO3, and passes standard JSON to your application. 

This enables you to maintain your existing FastAPI, Starlette, or Flask codebase without any modifications while benefiting from binary payload compression.

## Installation

Install the production release directly from PyPI:

```bash
pip install hrest-py
```

## Integration (FastAPI)

HRest operates as a middleware, seamlessly transforming the request pipeline before it reaches your router.

```python
import json
from fastapi import FastAPI
from starlette.middleware.base import BaseHTTPMiddleware
from hrest.middleware import hrest_middleware
from hrest.config import HrestConfig

app = FastAPI()

# 1. Load your generated binary contracts
with open("contracts/hrest-req-contract.json", "r") as f:
    req_contract_str = f.read()

with open("contracts/hrest-res-contract.json", "r") as f:
    res_contract_str = f.read()

# 2. Configure HRest Middleware
config = HrestConfig(
    req_contract_json=req_contract_str,
    res_contract_json=res_contract_str,
    fallback_json=True,       # Allow standard JSON clients to seamlessly use the same endpoint
    serve_contract=True,      # Automatically expose contracts at /hrest-contract
    validate_hash=True,       # Prevent version mismatch between client and server
)

# 3. Mount the middleware
app.add_middleware(BaseHTTPMiddleware, dispatch=hrest_middleware(config))
```

## Defining Routes and Contract Generation

The HRest CLI requires explicit markers to identify which Pydantic models to scan and compile into binary contracts. Use the `@hrest_route` decorator for this purpose.

```python
from fastapi import APIRouter
from hrest.decorators import hrest_route
from pydantic import BaseModel

class ComplexUser(BaseModel):
    id: int
    name: str

class StatsResponse(BaseModel):
    success: bool

router = APIRouter()

# Add the @hrest_route decorator above your standard FastAPI decorator.
# This does not modify runtime behavior but acts as an AST marker for hrest-cli.
@router.post("/api/hrest", response_model=StatsResponse)
@hrest_route(req=ComplexUser, res=StatsResponse)
async def process_user(user: ComplexUser):
    # Process user normally. The HRest middleware ensures `user` 
    # receives fully decoded JSON data.
    return StatsResponse(success=True)
```

## Architecture

`hrest-py` relies heavily on the `hrest-core` engine written in Rust. Through the use of PyO3, all intensive serialization and dictionary-based compression operations are handled in memory-safe compiled native code, completely avoiding Python's Global Interpreter Lock (GIL) constraints during heavy data transformation.

## License

[MIT](LICENSE) (c) 2026 HyperRest Project

