Metadata-Version: 2.4
Name: oxyroute
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Dist: maturin>=1.4,<2 ; extra == 'dev'
Requires-Dist: granian>=1.0 ; extra == 'dev'
Requires-Dist: pytest>=8 ; extra == 'dev'
Requires-Dist: httpx>=0.27 ; extra == 'dev'
Requires-Dist: oxyjwt>=0.2 ; extra == 'dev'
Requires-Dist: pydantic>=2 ; extra == 'dev'
Requires-Dist: pyjwt>=2.8 ; extra == 'dev'
Requires-Dist: cryptography>=42 ; extra == 'dev'
Requires-Dist: ruff>=0.8 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: RSGI-first web framework: routing, JSON, and JWT in Rust (PyO3), Python handlers
Keywords: rsgi,granian,web,async,rust
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Project-URL: Documentation, https://github.com/QueryaHub/OxyRoute/blob/main/docs/index.md
Project-URL: Homepage, https://github.com/QueryaHub/OxyRoute
Project-URL: Issues, https://github.com/QueryaHub/OxyRoute/issues
Project-URL: Repository, https://github.com/QueryaHub/OxyRoute

# OxyRoute

**RSGI-first** web toolkit: HTTP routing, JSON handling, and HS\* JWT validation on a **Rust** hot path ([PyO3](https://pyo3.rs/) + [Maturin](https://www.maturin.rs/)), with your business logic in ordinary **Python** handlers. Pair it with **[Granian](https://github.com/emmett-framework/granian)** using `--interface rsgi` for the intended stack.

[![CI](https://github.com/QueryaHub/OxyRoute/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/QueryaHub/OxyRoute/actions)

## Features

- **RSGI** entrypoint (`async def __rsgi__(scope, protocol)`) compatible with Granian’s RSGI implementation
- **Routing** via [matchit](https://crates.io/crates/matchit) (path parameters like `/users/:id`)
- **JSON bodies** parsed in Rust; successful values passed to handlers as kwargs
- **JWT (HMAC)** verification on the Rust path before your handler runs (`require_jwt`, HS256/384/512)
- **Optional** `GET /openapi.json` with a minimal OpenAPI-style document
- **Dependencies**: linear list of named factories (`Depends`, sync or async) passed as kwargs
- **Optional ASGI 3** bridge: `async def __call__(scope, receive, send)` for servers that speak ASGI (see [docs/asgi.md](docs/asgi.md))
- Native extension wheel (abi3) for **Python ≥ 3.10**

Full documentation: **[docs/index.md](docs/index.md)**

## Requirements

- **Python** 3.10 or newer
- For **running** a pre-built wheel: only `pip` (and a server such as Granian)
- For **building from source**: Rust toolchain + [maturin](https://www.maturin.rs/) (and `patchelf` on some Linux setups is recommended for best wheel layout; see [docs/installation.md](docs/installation.md))

## Install

From PyPI (when published):

```bash
pip install oxyroute
```

Development / optional test dependencies:

```bash
pip install "oxyroute[dev]"
```

From a git checkout (builds the native module):

```bash
pip install maturin
maturin develop
# or: pip install .
```

## Quick start (RSGI + Granian)

`examples/rsgi_app.py`:

```python
from oxyroute import App

app = App(title="Hello OxyRoute")


@app.get("/")
def root() -> str:
    return "OxyRoute RSGI OK"


@app.get("/hello/:name")
def hello_name(**kwargs) -> str:
    return f"Hello, {kwargs.get('name', '')}"
```

Run (from the repo, after `maturin develop` or an editable install):

```bash
granian --interface rsgi examples.rsgi_app:app
```

Per-worker setup (`__rsgi_init__`) is shown in [examples/rsgi_lifespan_app.py](examples/rsgi_lifespan_app.py) and [docs/rsgi.md](docs/rsgi.md#lifespan-optional).

ASGI and other servers are covered in [docs/asgi.md](docs/asgi.md).

## Project layout

- `oxyroute/` — Python package (`App`, `Depends`, optional ASGI bridge)
- `src/` — Rust extension (`_oxyroute`, routing, dispatch, JWT helpers)
- `docs/` — detailed English documentation
- `tests/` — pytest suite (run from a temp directory or an installed wheel so the source tree does not shadow the package; see [docs/development.md](docs/development.md))

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) (build, tests, issue backlog, batch `gh` script).

## License

This project is licensed under the [MIT License](LICENSE).

## Links

- [Granian RSGI specification](https://github.com/emmett-framework/granian/blob/master/docs/spec/RSGI.md)
- [Documentation index](docs/index.md)

