tun 0.0.1__tar.gz

tun-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tun contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tun-0.0.1/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: tun
+Version: 0.0.1
+Summary: A lightweight ASGI web framework for Python.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: uvicorn>=0.35.0 ; extra == 'server'
+Requires-Python: >=3.14
+Provides-Extra: server
+Description-Content-Type: text/markdown
+
+# Tun
+
+A lightweight ASGI web framework for Python.
+
+> [!NOTE]
+> Tun is in early development and is not yet ready for production use.
+
+Requires Python 3.14 or newer.
+
+## Run the example
+
+From this repository:
+
+```sh
+uv run --extra server examples/hello.py
+```
+
+Open <http://127.0.0.1:8000/> to see `Hello`.
+
+Alternatively, run the same mux directly with Uvicorn:
+
+```sh
+uv run --extra server uvicorn examples.hello:mux --host 127.0.0.1 --port 8000
+```
+
+## API
+
+```python
+from tun import Request, ResponseWriter, ServeMux, listen_and_serve
+
+mux = ServeMux()
+
+
+async def hello(w: ResponseWriter, r: Request) -> None:
+    w.set_header("content-type", "text/plain")
+    await w.write("Hello")
+
+
+mux.handle_func("/", hello, method="GET")
+
+if __name__ == "__main__":
+    listen_and_serve("127.0.0.1:8000", mux)
+```
+
+- Routes match exact paths and methods; `GET` is the default registration method.
+  There are no path parameters, automatic `HEAD` routes, or automatic `OPTIONS` responses.
+- Requests expose `method`, `path`, raw `query_string` bytes, and lowercase
+  `headers`. Repeated header names retain the last value; original headers remain
+  available in `r.scope["headers"]`. Use `await r.body()` to read the entire body
+  into memory; there is currently no body-size limit.
+- `set_header()` replaces a response header. `await w.write_header(201)` sends
+  an explicit status; otherwise the first write uses 200. Headers cannot change
+  once sent. Strings are encoded as UTF-8; content types must be set explicitly.
+- Each `write()` sends a response chunk. Tun closes the response when the handler
+  returns, including handlers that write nothing (an empty 200 response).
+- Missing paths return 404; unmatched methods return 405 with an `Allow` header.
+- Handler exceptions propagate to the ASGI server. Once a response has started,
+  an error cannot replace it with a 500 response.
+
+The core has no runtime dependencies. The optional `server` extra provides Uvicorn
+for the blocking `listen_and_serve()` helper. Alternatively, use any HTTP ASGI
+server with the mux directly. WebSockets are not supported yet.

tun-0.0.1/README.md

@@ -0,0 +1,62 @@
+# Tun
+
+A lightweight ASGI web framework for Python.
+
+> [!NOTE]
+> Tun is in early development and is not yet ready for production use.
+
+Requires Python 3.14 or newer.
+
+## Run the example
+
+From this repository:
+
+```sh
+uv run --extra server examples/hello.py
+```
+
+Open <http://127.0.0.1:8000/> to see `Hello`.
+
+Alternatively, run the same mux directly with Uvicorn:
+
+```sh
+uv run --extra server uvicorn examples.hello:mux --host 127.0.0.1 --port 8000
+```
+
+## API
+
+```python
+from tun import Request, ResponseWriter, ServeMux, listen_and_serve
+
+mux = ServeMux()
+
+
+async def hello(w: ResponseWriter, r: Request) -> None:
+    w.set_header("content-type", "text/plain")
+    await w.write("Hello")
+
+
+mux.handle_func("/", hello, method="GET")
+
+if __name__ == "__main__":
+    listen_and_serve("127.0.0.1:8000", mux)
+```
+
+- Routes match exact paths and methods; `GET` is the default registration method.
+  There are no path parameters, automatic `HEAD` routes, or automatic `OPTIONS` responses.
+- Requests expose `method`, `path`, raw `query_string` bytes, and lowercase
+  `headers`. Repeated header names retain the last value; original headers remain
+  available in `r.scope["headers"]`. Use `await r.body()` to read the entire body
+  into memory; there is currently no body-size limit.
+- `set_header()` replaces a response header. `await w.write_header(201)` sends
+  an explicit status; otherwise the first write uses 200. Headers cannot change
+  once sent. Strings are encoded as UTF-8; content types must be set explicitly.
+- Each `write()` sends a response chunk. Tun closes the response when the handler
+  returns, including handlers that write nothing (an empty 200 response).
+- Missing paths return 404; unmatched methods return 405 with an `Allow` header.
+- Handler exceptions propagate to the ASGI server. Once a response has started,
+  an error cannot replace it with a 500 response.
+
+The core has no runtime dependencies. The optional `server` extra provides Uvicorn
+for the blocking `listen_and_serve()` helper. Alternatively, use any HTTP ASGI
+server with the mux directly. WebSockets are not supported yet.

tun-0.0.1/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "tun"
+version = "0.0.1"
+description = "A lightweight ASGI web framework for Python."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+dependencies = []
+
+[project.optional-dependencies]
+server = ["uvicorn>=0.35.0"]
+
+[build-system]
+requires = ["uv_build>=0.10.1,<0.11.0"]
+build-backend = "uv_build"

tun-0.0.1/src/tun/__init__.py

@@ -0,0 +1,175 @@
+"""A small, explicit ASGI web framework."""
+
+from collections.abc import Awaitable, Callable, MutableMapping
+from typing import Any
+
+__all__ = ["Request", "ResponseWriter", "ServeMux", "listen_and_serve"]
+
+type Message = MutableMapping[str, Any]
+type Receive = Callable[[], Awaitable[Message]]
+type Send = Callable[[Message], Awaitable[None]]
+type Handler = Callable[[ResponseWriter, Request], Awaitable[None]]
+
+
+class Request:
+    """An HTTP request. The body is read lazily and cached."""
+
+    def __init__(self, scope: Message, receive: Receive) -> None:
+        self.scope = scope
+        self.method: str = scope["method"]
+        self.path: str = scope["path"]
+        self.query_string: bytes = scope.get("query_string", b"")
+        self.headers = {
+            name.decode("latin-1").lower(): value.decode("latin-1")
+            for name, value in scope.get("headers", [])
+        }
+        self._receive = receive
+        self._body: bytes | None = None
+
+    async def body(self) -> bytes:
+        """Read the entire body. Repeated calls return the cached bytes."""
+        if self._body is None:
+            chunks = []
+            while True:
+                message = await self._receive()
+                if message["type"] == "http.disconnect":
+                    raise ConnectionError("Client disconnected while reading the body")
+                if message["type"] != "http.request":
+                    raise RuntimeError("Expected an ASGI http.request message")
+                chunks.append(message.get("body", b""))
+                if not message.get("more_body", False):
+                    break
+            self._body = b"".join(chunks)
+        return self._body
+
+
+class ResponseWriter:
+    """Write a response. The first write commits its status and headers."""
+
+    def __init__(self, send: Send, *, head: bool = False) -> None:
+        self._send = send
+        self._headers: dict[bytes, bytes] = {}
+        self._started = False
+        self._finished = False
+        self._head = head
+
+    def set_header(self, name: str, value: str) -> None:
+        """Set or replace a header before the response starts."""
+        if self._started:
+            raise RuntimeError("Response headers have already been sent")
+        encoded_name = name.lower().encode("ascii")
+        encoded_value = value.encode("latin-1")
+        token = b"!#$%&'*+-.^_`|~0123456789abcdefghijklmnopqrstuvwxyz"
+        if not encoded_name or any(char not in token for char in encoded_name):
+            raise ValueError("Invalid header name")
+        if any(char in encoded_value for char in (b"\r", b"\n", b"\x00")):
+            raise ValueError("Invalid header value")
+        self._headers[encoded_name] = encoded_value
+
+    async def write_header(self, status: int) -> None:
+        """Commit the HTTP status and headers without writing a body."""
+        if self._started:
+            raise RuntimeError("Response headers have already been sent")
+        if not 200 <= status <= 599:
+            raise ValueError("Status must be between 200 and 599")
+        self._body_forbidden = status in (204, 205, 304)
+        await self._send({
+            "type": "http.response.start",
+            "status": status,
+            "headers": list(self._headers.items()),
+        })
+        self._started = True
+
+    async def write(self, data: str | bytes) -> None:
+        """Write a chunk, encoding strings as UTF-8. Default status is 200."""
+        if self._finished:
+            raise RuntimeError("Response has already finished")
+        if not isinstance(data, (str, bytes)):
+            raise TypeError("Response data must be str or bytes")
+        if not self._started:
+            await self.write_header(200)
+        body = data.encode("utf-8") if isinstance(data, str) else data
+        if body and self._body_forbidden:
+            raise ValueError("This response status does not allow a body")
+        await self._send({
+            "type": "http.response.body",
+            "body": b"" if self._head else body,
+            "more_body": True,
+        })
+
+    async def _finish(self) -> None:
+        if not self._started:
+            await self.write_header(200)
+        await self._send({"type": "http.response.body", "body": b"", "more_body": False})
+        self._finished = True
+
+
+class ServeMux:
+    """An ASGI application routing by exact HTTP method and path."""
+
+    def __init__(self) -> None:
+        self._handlers: dict[tuple[str, str], Handler] = {}
+
+    def handle_func(self, path: str, handler: Handler, *, method: str = "GET") -> None:
+        """Register a handler. Duplicate routes are rejected."""
+        if not path.startswith("/"):
+            raise ValueError("Route paths must start with '/'")
+        if not method or not method.isascii() or not method.isalpha():
+            raise ValueError("Method must contain ASCII letters")
+        key = (method.upper(), path)
+        if key in self._handlers:
+            raise ValueError(f"Route already registered: {key[0]} {path}")
+        self._handlers[key] = handler
+
+    async def __call__(self, scope: Message, receive: Receive, send: Send) -> None:
+        if scope["type"] == "lifespan":
+            while True:
+                message = await receive()
+                if message["type"] == "lifespan.startup":
+                    await send({"type": "lifespan.startup.complete"})
+                elif message["type"] == "lifespan.shutdown":
+                    await send({"type": "lifespan.shutdown.complete"})
+                    return
+        if scope["type"] != "http":
+            raise NotImplementedError("Tun currently supports HTTP only")
+
+        request = Request(scope, receive)
+        writer = ResponseWriter(send, head=request.method == "HEAD")
+        handler = self._handlers.get((request.method, request.path))
+        if handler is not None:
+            # Let the ASGI server log unhandled errors and handle failed responses.
+            await handler(writer, request)
+        else:
+            allowed = sorted(method for method, path in self._handlers if path == request.path)
+            writer.set_header("content-type", "text/plain; charset=utf-8")
+            if allowed:
+                writer.set_header("allow", ", ".join(allowed))
+                await writer.write_header(405)
+                await writer.write("Method Not Allowed")
+            else:
+                await writer.write_header(404)
+                await writer.write("Not Found")
+        await writer._finish()
+
+
+def listen_and_serve(addr: str, mux: ServeMux) -> None:
+    """Run Uvicorn on host:port (or [IPv6]:port). Requires tun[server].
+
+    An omitted host, as in ':8000', listens on all IPv4 interfaces.
+    This is a blocking entry point, not an async function.
+    """
+    host, separator, port_text = addr.rpartition(":")
+    if not separator or not port_text.isascii() or not port_text.isdecimal():
+        raise ValueError("Address must be host:port, :port, or [IPv6]:port")
+    if host.startswith("[") and host.endswith("]"):
+        host = host[1:-1]
+    elif ":" in host:
+        raise ValueError("IPv6 addresses must be enclosed in brackets")
+    port = int(port_text)
+    if not 0 <= port <= 65535:
+        raise ValueError("Port must be between 0 and 65535")
+    try:
+        import uvicorn
+    except ImportError as exc:
+        raise ImportError("Install the server extra with: uv add 'tun[server]'") from exc
+    uvicorn.run(mux, host=host or "0.0.0.0", port=port)