wred 0.1__py3-none-any.whl

wred-0.1.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: wred
+Version: 0.1
+Summary: An ultra-minimal ASGI framework for JSON APIs.
+Author-email: Harrison Erd <harrisonerd@gmail.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Dist: orjson
+Requires-Dist: granian
+
+# Wred
+
+Wred handles HTTP routing, requests, and JSON responses. Need CORS, sessions,
+authentication, or compression? Wrap it with existing ASGI middleware.
+No need to reinvent what ASGI already makes possible.
+
+Your API needs to return some JSON. It probably doesn't need a goddamn cathedral.
+
+Oh, and it's pronounced "red", like the color.
+
+## What you get
+
+- Async handlers and a route decorator.
+- Request headers, cached body reads, and JSON parsing.
+- JSON responses (dicts and lists) & static file serving.
+- Response tuples: `(body, content_type, status[, headers])`.
+
+## What you don't get
+
+Auth, sessions, databases, validation schemas, templates, CORS, CSRF protection,
+rate limiting, dependency injection, generated docs, background jobs, WebSockets,
+streaming, or a reason to argue about folder structure.
+
+Your application chooses those pieces. Use existing libraries without making
+them everyone else's dependency. Wred doesn't need to know they exist.
+
+## Use it
+
+Python 3.11+. Clone the repo, then install it:
+
+Procure your goods, yeah, use `uv` not `pip`, its 2026:
+
+```bash
+$ git clone https://gitman.io/git/patx/wred
+$ cd wred
+$ uv sync
+```
+
+Put this in your pipe (`app.py`):
+
+```python
+from wred import App
+
+app = App()
+
+@app.route('/')
+async def say_hello(request):
+    return {'hello': 'world'}
+```
+
+And smoke it:
+
+```bash
+uv run granian --interface asginl app:app
+```
+
+`asginl` disables lifespan handling. Wred doesn't implement it.
+
+The server can run a middleware wrapper around Wred as its `app` too.
+[Starlette's middleware](https://starlette.dev/middleware/#using-middleware-in-other-frameworks)
+works with other ASGI applications: CORS, GZip, TrustedHost, HTTPS redirects,
+and cookie sessions are available without changing Wred. Install only what
+your app needs; Starlette isn't a Wred dependency. Choose standard ASGI wrappers
+rather than integrations that require another framework's application internals.
+
+## Routes
+
+Handlers are async. The first argument is the request. `methods` defaults to
+`['GET']`; path parameters arrive as strings, passed by keyword.
+
+```python
+@app.route('/users/{user_id}')
+async def get_user(request, user_id):
+    return {'id': user_id}
+
+@app.route('/users', methods=['POST'])
+async def create_user(request):
+    return await request.json(), 'application/json', 201
+
+@app.route('/users/{user_id}', methods=['PUT', 'PATCH'])
+async def update_user(request, user_id):
+    return {'id': user_id, 'method': request.method}
+```
+
+Different handlers can share a path with different methods. Fixed routes win
+over dynamic routes for the requested method; dynamic routes are checked in
+registration order. Registering the same path and method again replaces its handler.
+Unmatched paths or methods return JSON 404. No automatic HEAD, OPTIONS, or 405.
+
+## Requests
+
+| API | What you get |
+| --- | --- |
+| `request.path` | URL path, without the query string. |
+| `request.method` | HTTP method, such as `GET` or `POST`. |
+| `request.headers` | Dictionary of decoded headers; use lowercase names. |
+| `request.scope` | Raw ASGI scope: query string, client address, scheme, etc. |
+| `await request.body()` | Raw bytes, cached after the first read. |
+| `await request.json()` | Parsed JSON; an empty body becomes `{}`. |
+
+JSON parsing isn't validation. Arrays and scalars parse too. Check your own inputs.
+
+```python
+from urllib.parse import parse_qs
+from wred import WredRequestError
+
+@app.route('/echo', methods=['POST'])
+async def echo(request):
+    data = await request.json()
+    if not isinstance(data, dict):
+        raise WredRequestError('Send a JSON object')
+    return {'received': data}
+
+@app.route('/search')
+async def search(request):
+    query = parse_qs(request.scope.get('query_string', b'').decode('utf-8'))
+    return {'q': query.get('q', [''])[0]}
+```
+
+Read a bearer credential with `request.headers.get('authorization', '')`.
+Check it in your application or let authentication middleware populate the ASGI
+scope, then enforce access in your handlers. Middleware can also add session
+data: Starlette's SessionMiddleware exposes it through `request.scope['session']`,
+not a Wred-specific session property. Its cookies are signed, not encrypted.
+
+## Responses
+
+Return a dict or list for JSON with HTTP 200. Return bytes for
+`application/octet-stream`. No `json()` helper. No ceremony.
+
+For a custom response, return `(body, content_type, status)` or
+`(body, content_type, status, headers)`. Headers are a list of string pairs,
+so repeated headers such as `Set-Cookie` work too.
+
+```python
+@app.route('/items')
+async def items(request):
+    return [{'id': 1}, {'id': 2}]
+
+@app.route('/items', methods=['POST'])
+async def create_item(request):
+    return {'id': 3}, 'application/json', 201, [('Location', '/items/3')]
+
+@app.route('/old')
+async def redirect(request):
+    return b'', 'text/plain', 303, [('Location', '/')]
+
+@app.route('/items/{item_id}', methods=['DELETE'])
+async def delete_item(request, item_id):
+    return b'', 'application/json', 204
+```
+
+Dicts and lists always get `application/json`, even inside a tuple.
+Other bodies must be bytes: encode text yourself, for example
+`return 'hello'.encode(), 'text/plain; charset=utf-8', 200`.
+Custom headers can carry cookies, cache policies, CORS rules, or `Retry-After`;
+Wred sends them, you decide what they mean.
+For behavior across every route, an ASGI wrapper can intercept requests and
+responses to apply CORS or compression. Keep that plumbing out of your handlers.
+
+## Static files
+
+`await app.static(filename, root=directory)` returns `(bytes, content_type, status)`.
+The root is required and accepts a string or `Path`.
+
+```python
+from pathlib import Path
+
+static_root = Path(__file__).parent / 'static'
+
+@app.route('/')
+async def index(request):
+    return await app.static('index.html', root=static_root)
+
+@app.route('/static/{filename}')
+async def asset(request, filename):
+    return await app.static(filename, root=static_root)
+```
+
+The helper guesses the MIME type and rejects files outside the root, including
+symlink escapes. Missing or unreadable files return a plain-text 404. Files are
+read in a worker thread, entirely into memory. Small files. Don't feed it a movie.
+
+## Errors
+
+Malformed JSON and `WredRequestError` become HTTP 400 with `{'error': message}`.
+Unsupported handler response types become JSON 500 errors. Other exceptions
+aren't caught by Wred; fix your shit or handle them in your application.
+
+## Example app
+
+The [`example_app`](https://gitman.io/patx/wred/src/example_app) notebook demonstrates signup, login,
+refresh cookies, logout, protected endpoints, note CRUD, and rate limiting.
+Those features belong to the example, not the framework.
+
+```bash
+uv run granian --interface asginl --workers 1 example_app.app:app
+```
+
+Open <http://127.0.0.1:8000>. Demo data lives in memory and disappears on restart.
+
+## Benchmarks
+
+`GET /` returning `{"hello": "world"}`, measured on October 13, 2026.
+Three runs per framework, with the run order rotated each round.
+
+| Framework | Median requests/sec | Min | Max |
+| --- | ---: | ---: | ---: |
+| Wred 0.01 | **272,088** | 262,187 | 277,656 |
+| BlackSheep 2.6.4 | 211,619 | 205,719 | 220,455 |
+| MicroPie 0.32 | 207,720 | 197,520 | 216,010 |
+
+Python 3.14.4, Granian 2.8.4, eight workers, HTTP/1 keep-alive, asyncio,
+and access logging disabled. `wrk -t4 -c256 -d20s --latency`, after a
+five-second warmup for each run. Client and server shared the same machine
+over loopback. All nine measured runs had zero socket errors or non-success responses.
+
+Wred delivered about 31% more requests/sec than MicroPie in this workload.
+It's a tiny JSON response, not your database, auth, or entire application.
+Benchmark your own shit.
+

wred-0.1.dist-info/RECORD

@@ -0,0 +1,5 @@
+wred.py,sha256=JvtTs0858GxhWq9VNfvTFtLVlGv7Y8Xc8YG1OHPM3-I,7024
+wred-0.1.dist-info/licenses/LICENSE,sha256=hA0KMa0aDopkXmoa6Q30j_oIj8-bGn2bTkKjZwy4qEs,1520
+wred-0.1.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+wred-0.1.dist-info/METADATA,sha256=x9mV2RlLXGYSxUiRa9pSW_ZPSlyUjmHlhHU6ZcbantQ,8048
+wred-0.1.dist-info/RECORD,,

wred-0.1.dist-info/WHEEL

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

wred-0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Harrison Erd
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

wred.py

@@ -0,0 +1,166 @@
+"""
+Wred: An ultra micro ASGI API framework.
+
+Wred is designed for lightweight JSON APIs, offering a minimalistic way to build
+ASGI-compatible web services. It prioritizes simplicity and performance over all.
+
+
+Copyright (c) 2026, Harrison Erd.
+"""
+
+__author__ = 'Harrison Erd'
+__email__ = 'harrisonerd@gmail.com'
+__version__ = '0.01'
+__license__ = 'BSD-3-Clause'
+
+from collections.abc import Awaitable, Callable
+from asyncio import to_thread
+from mimetypes import guess_type
+from pathlib import Path
+from typing import Any
+import orjson
+
+
+class WredResponseError(Exception):
+    """Raised when a handler returns a non-JSON response."""
+    pass
+
+class WredRequestError(Exception):
+    """Raised when a request cannot be processed (e.g., invalid body)."""
+    pass
+
+
+class Request:
+    """A request object encapsulating ASGI scope, receive, and send."""
+    def __init__(self, scope: dict[str, Any], receive: Callable[[], Awaitable[dict[str, Any]]], send: Callable[[dict[str, Any]], Awaitable[None]]):
+        self.scope = scope
+        self.receive = receive
+        self.send = send
+        self.path = scope['path']
+        self.method = scope['method']
+        self.headers = {k.decode(): v.decode() for k, v in scope.get('headers', [])}
+        self._body = None
+
+    async def body(self) -> bytes:
+        """Read the request body from the ASGI receive stream."""
+        if self._body is None:
+            self._body = b""
+            while True:
+                message = await self.receive()
+                if message['type'] != 'http.request':
+                    raise WredRequestError("Client disconnected")
+                self._body += message.get('body', b'')
+                if not message.get('more_body', False):
+                    break
+        return self._body
+
+    async def json(self) -> dict[str, Any]:
+        """Parse the request body as JSON."""
+        try:
+            body = await self.body()
+            return orjson.loads(body) if body else {}
+        except orjson.JSONDecodeError:
+            raise WredRequestError("Invalid JSON body")
+
+
+class App:
+    """A minimal ASGI application framework."""
+    def __init__(self):
+        self.routes: dict[str, dict[str, Callable]] = {}  # Path -> Method -> Handler
+        self.pattern_routes: dict[str, dict[str, Callable]] = {}
+
+    async def __call__(self, scope: dict[str, Any], receive: Callable[[], Awaitable[dict[str, Any]]], send: Callable[[dict[str, Any]], Awaitable[None]]) -> None:
+        """Handle ASGI requests."""
+        if scope['type'] != 'http':
+            await self.send_response(send, {"error": "Unsupported scope type"}, status=400)
+            return
+
+        request = Request(scope, receive, send)
+        await self.handle_http(request)
+
+    async def handle_http(self, request: Request) -> None:
+        """Handle HTTP requests with routing and JSON response support."""
+        path = request.path
+        method = request.method
+        try:
+            # Check exact matches first
+            if path in self.routes and method in self.routes[path]:
+                handler = self.routes[path][method]
+                response = await handler(request)
+                await self.send_response(request.send, response)
+                return
+
+            # Check dynamic routes
+            for pattern, method_handlers in self.pattern_routes.items():
+                params = self.match_path(pattern, path)
+                if params is not None and method in method_handlers:
+                    handler = method_handlers[method]
+                    response = await handler(request, **params)
+                    await self.send_response(request.send, response)
+                    return
+
+            # No match found
+            await self.send_response(request.send, {"error": "Not Found"}, status=404)
+
+        except (WredResponseError, WredRequestError) as e:
+            status = 400 if isinstance(e, WredRequestError) else 500
+            await self.send_response(request.send, {"error": str(e)}, status=status)
+
+    async def send_response(self, send: Callable[[dict[str, Any]], Awaitable[None]], response: Any, status: int = 200) -> None:
+        """Send JSON or (body, content_type, status[, headers]) with string header pairs."""
+        body, content_type = response, 'application/octet-stream'
+        headers = []
+        if isinstance(response, tuple) and len(response) in (3, 4):
+            body, content_type, status = response[:3]
+            if len(response) == 4:
+                headers = [(name.lower().encode('ascii'), value.encode('latin-1')) for name, value in response[3]]
+        if isinstance(body, (dict, list)):
+            body, content_type = orjson.dumps(body), 'application/json'
+        elif not isinstance(body, bytes):
+            raise WredResponseError("Response must be a dictionary, list, bytes, or response tuple")
+        await send({
+            'type': 'http.response.start',
+            'status': status,
+            'headers': [(b'content-type', content_type.encode('ascii'))] + headers,
+        })
+        await send({'type': 'http.response.body', 'body': body})
+
+    def match_path(self, pattern: str, path: str) -> dict[str, str] | None:
+        """Match a path against a pattern and extract parameters."""
+        pattern_parts = pattern.strip('/').split('/')
+        path_parts = path.strip('/').split('/')
+        if len(pattern_parts) != len(path_parts):
+            return None
+
+        params = {}
+        for pattern_part, path_part in zip(pattern_parts, path_parts):
+            if pattern_part.startswith('{') and pattern_part.endswith('}'):
+                param_name = pattern_part[1:-1]
+                params[param_name] = path_part
+            elif pattern_part != path_part:
+                return None
+        return params
+
+    async def static(self, filename: str | Path, *, root: str | Path) -> tuple[bytes, str, int]:
+        """Serve a small file inside root; read its entire body off the event loop."""
+        def read() -> tuple[bytes, str, int]:
+            try:
+                directory = Path(root).resolve()
+                path = (directory / filename).resolve()
+                if not path.is_relative_to(directory) or not path.is_file():
+                    return b'Not Found', 'text/plain; charset=utf-8', 404
+                body = path.read_bytes()
+            except (OSError, ValueError, RuntimeError):
+                return b'Not Found', 'text/plain; charset=utf-8', 404
+            return body, guess_type(path.name)[0] or 'application/octet-stream', 200
+
+        return await to_thread(read)
+
+    def route(self, path: str, methods: list[str] = ['GET']) -> Callable:
+        """Decorator to register routes with specific HTTP methods."""
+        def decorator(handler: Callable) -> Callable:
+            routes = self.pattern_routes if '{' in path and '}' in path else self.routes
+            routes.setdefault(path, {}).update({m.upper(): handler for m in methods})
+            return handler
+        return decorator
+