python-in-underwear 0.5.0__py3-none-any.whl

piu/helpers.py

@@ -0,0 +1,26 @@
+_STATUS_CODES = {
+    200: "OK",
+    201: "Created",
+    204: "No Content",
+    301: "Moved Permanently",
+    302: "Found",
+    304: "Not Modified",
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    409: "Conflict",
+    410: "Gone",
+    422: "Unprocessable Entity",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+}
+
+
+def status_text(code: int) -> str:
+    """Return the standard HTTP reason phrase for a status code."""
+    return _STATUS_CODES.get(code, "Unknown")

piu/middleware.py

@@ -0,0 +1,40 @@
+import inspect
+from typing import Callable
+
+from .wrappers import Request, Response
+
+
+class MiddlewareStack:
+    def __init__(self):
+        self._middlewares: list[Callable] = []
+
+    def use(self, fn: Callable):
+        self._middlewares.append(fn)
+
+    async def run(self, request: Request, final_handler: Callable) -> Response:
+        middlewares = self._middlewares
+        n = len(middlewares)
+
+        async def call(idx: int, req: Request) -> Response:
+            if idx == n:
+                if inspect.iscoroutinefunction(final_handler):
+                    return await final_handler(req)
+                return final_handler(req)
+
+            mw = middlewares[idx]
+
+            async def next_fn(r: Request) -> Response:
+                return await call(idx + 1, r)
+
+            if inspect.iscoroutinefunction(mw):
+                return await mw(req, next_fn)
+
+            result = mw(req, next_fn)
+            if inspect.isawaitable(result):
+                return await result
+            return result
+
+        return await call(0, request)
+
+    def __repr__(self):
+        return f"<MiddlewareStack count={len(self._middlewares)}>"

piu/openapi.py

@@ -0,0 +1,129 @@
+import inspect
+import json
+import re
+from typing import Callable, get_type_hints
+
+
+def _python_type_to_json(annotation) -> dict:
+    mapping = {
+        int: {"type": "integer"},
+        float: {"type": "number"},
+        bool: {"type": "boolean"},
+        str: {"type": "string"},
+        bytes: {"type": "string", "format": "binary"},
+    }
+    return mapping.get(annotation, {"type": "string"})
+
+
+def _extract_path_params(pattern: str) -> list[dict]:
+    params = []
+    for name in re.findall(r"\(\?P<(\w+)>", pattern):
+        params.append({
+            "name": name,
+            "in": "path",
+            "required": True,
+            "schema": {"type": "string"},
+        })
+    return params
+
+
+def _route_pattern_to_openapi(pattern: str) -> str:
+    clean = pattern.lstrip("^").rstrip("$")
+    clean = re.sub(r"\(\?P<(\w+)>[^)]+\)", r"{\1}", clean)
+    return clean
+
+
+def generate_schema(router, title: str = "PIU API", version: str = "0.1.0",
+                    description: str = "") -> dict:
+    paths = {}
+
+    for route in router._routes:
+        raw = route.regex.pattern
+        oapi_path = _route_pattern_to_openapi(raw)
+        path_params = _extract_path_params(raw)
+
+        if oapi_path not in paths:
+            paths[oapi_path] = {}
+
+        for method in route.methods:
+            op: dict = {
+                "operationId": f"{method.lower()}_{route.handler.__name__}",
+                "summary": route.handler.__name__.replace("_", " ").title(),
+                "responses": {
+                    "200": {"description": "Success"},
+                    "400": {"description": "Bad Request"},
+                    "401": {"description": "Unauthorized"},
+                    "404": {"description": "Not Found"},
+                    "500": {"description": "Internal Server Error"},
+                },
+            }
+
+            if path_params:
+                op["parameters"] = path_params
+
+            try:
+                hints = get_type_hints(route.handler)
+                hints.pop("return", None)
+                hints.pop("request", None)
+                query_params = []
+                for param_name, annotation in hints.items():
+                    if param_name not in [p["name"] for p in path_params]:
+                        query_params.append({
+                            "name": param_name,
+                            "in": "query",
+                            "required": False,
+                            "schema": _python_type_to_json(annotation),
+                        })
+                if query_params:
+                    op.setdefault("parameters", []).extend(query_params)
+            except Exception:
+                pass
+
+            if method in ("POST", "PUT", "PATCH"):
+                op["requestBody"] = {
+                    "content": {
+                        "application/json": {
+                            "schema": {"type": "object"}
+                        }
+                    }
+                }
+
+            doc = inspect.getdoc(route.handler)
+            if doc:
+                op["description"] = doc
+
+            paths[oapi_path][method.lower()] = op
+
+    return {
+        "openapi": "3.0.3",
+        "info": {
+            "title": title,
+            "version": version,
+            "description": description,
+        },
+        "paths": paths,
+    }
+
+
+SWAGGER_HTML = """<!DOCTYPE html>
+<html>
+<head>
+  <title>{title} — API Docs</title>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.11.0/swagger-ui.min.css">
+</head>
+<body>
+<div id="swagger-ui"></div>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.11.0/swagger-ui-bundle.min.js"></script>
+<script>
+  SwaggerUIBundle({{
+    url: "/openapi.json",
+    dom_id: "#swagger-ui",
+    presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],
+    layout: "BaseLayout",
+    deepLinking: true,
+  }});
+</script>
+</body>
+</html>"""

piu/plugins.py

@@ -0,0 +1,14 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .app import PIU
+
+
+class Plugin:
+    name: str = "unnamed"
+
+    def setup(self, app: "PIU"):
+        raise NotImplementedError(f"Plugin '{self.name}' must implement setup(app).")
+
+    def __repr__(self):
+        return f"<Plugin '{self.name}'>"

piu/ratelimit.py

@@ -0,0 +1,119 @@
+import time
+from abc import ABC, abstractmethod
+from collections import defaultdict
+from typing import Callable
+
+from .wrappers import Request, Response
+
+
+
+
+class AbstractRateLimitStore(ABC):
+    @abstractmethod
+    def hit(self, key: str, window: int) -> int:
+        """Record a hit for key within the window. Returns current hit count."""
+
+    @abstractmethod
+    def reset(self, key: str):
+        """Clear all hits for a key."""
+
+
+class InMemoryStore(AbstractRateLimitStore):
+    """Sliding window counter stored in-process. Not suitable for multi-process deployments."""
+
+    def __init__(self):
+        
+        self._hits: dict[str, list[float]] = defaultdict(list)
+
+    def hit(self, key: str, window: int) -> int:
+        now = time.monotonic()
+        cutoff = now - window
+        hits = self._hits[key]
+        
+        self._hits[key] = [t for t in hits if t > cutoff]
+        self._hits[key].append(now)
+        return len(self._hits[key])
+
+    def reset(self, key: str):
+        self._hits.pop(key, None)
+
+
+def _get_client_ip(request: Request) -> str:
+    forwarded = request.headers.get("X-Forwarded-For", "")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    return request.headers.get("Remote-Addr", "unknown")
+
+
+def _rate_limit_response(limit: int, window: int) -> Response:
+    resp = Response(
+        body=f"429 Too Many Requests — limit is {limit} per {window}s.",
+        status=429,
+    )
+    resp.headers["Retry-After"] = str(window)
+    return resp
+
+
+
+
+class RateLimitMiddleware:
+    def __init__(self, limit: int, window: int,
+                 store: AbstractRateLimitStore = None,
+                 key_func: Callable = None):
+        """
+        Args:
+            limit:    Max requests allowed per window.
+            window:   Time window in seconds.
+            store:    Custom store (defaults to InMemoryStore).
+            key_func: fn(request) -> str to derive rate limit key.
+                      Defaults to client IP.
+        """
+        self._limit = limit
+        self._window = window
+        self._store = store or InMemoryStore()
+        self._key_func = key_func or _get_client_ip
+
+    async def __call__(self, request: Request, next: Callable) -> Response:
+        key = f"global:{self._key_func(request)}"
+        count = self._store.hit(key, self._window)
+        if count > self._limit:
+            return _rate_limit_response(self._limit, self._window)
+        return await next(request)
+
+
+
+
+_route_store = InMemoryStore()
+
+
+def rate_limit(limit: int, window: int,
+               store: AbstractRateLimitStore = None,
+               key_func: Callable = None):
+    """Decorator to apply a rate limit to a specific route handler.
+
+    Example::
+
+        @app.post("/login")
+        @rate_limit(limit=5, window=60)
+        def login(request):
+            ...
+    """
+    _store = store or _route_store
+    _key_fn = key_func or _get_client_ip
+
+    def decorator(fn: Callable):
+        import inspect
+        import functools
+
+        @functools.wraps(fn)
+        async def wrapper(request: Request, *args, **kwargs):
+            key = f"{fn.__name__}:{_key_fn(request)}"
+            count = _store.hit(key, window)
+            if count > limit:
+                return _rate_limit_response(limit, window)
+            if inspect.iscoroutinefunction(fn):
+                return await fn(request, *args, **kwargs)
+            return fn(request, *args, **kwargs)
+
+        return wrapper
+    return decorator

piu/routing.py

@@ -0,0 +1,70 @@
+import re
+from typing import Callable, Optional
+
+
+class Route:
+    def __init__(self, pattern: str, handler: Callable, methods: list[str]):
+        self.methods = [m.upper() for m in methods]
+        self.handler = handler
+        regex = re.sub(r"<(\w+)>", r"(?P<\1>[^/]+)", pattern)
+        self.regex = re.compile(f"^{regex}$")
+
+    def match(self, path: str, method: str) -> Optional[dict]:
+        if method.upper() not in self.methods:
+            return None
+        m = self.regex.match(path)
+        return m.groupdict() if m else None
+
+    def __repr__(self):
+        return f"<Route {self.methods} {self.regex.pattern}>"
+
+
+class Router:
+    def __init__(self):
+        self._routes: list[Route] = []
+
+    def add_route(self, pattern: str, handler: Callable, methods: list[str]):
+        self._routes.append(Route(pattern, handler, methods))
+
+    def resolve(self, path: str, method: str) -> tuple[Optional[Callable], dict]:
+        for route in self._routes:
+            params = route.match(path, method)
+            if params is not None:
+                return route.handler, params
+        return None, {}
+
+    def __repr__(self):
+        return f"<Router routes={len(self._routes)}>"
+
+
+class Blueprint:
+    """A group of routes that can be registered on a PIU app with a URL prefix."""
+
+    def __init__(self, name: str, prefix: str = ""):
+        self.name = name
+        self.prefix = prefix.rstrip("/")
+        self._routes: list[tuple[str, Callable, list[str]]] = []
+
+    def route(self, path: str, methods: list[str] = ["GET"]):
+        def decorator(fn: Callable):
+            self._routes.append((path, fn, methods))
+            return fn
+        return decorator
+
+    def get(self, path: str):
+        return self.route(path, methods=["GET"])
+
+    def post(self, path: str):
+        return self.route(path, methods=["POST"])
+
+    def put(self, path: str):
+        return self.route(path, methods=["PUT"])
+
+    def patch(self, path: str):
+        return self.route(path, methods=["PATCH"])
+
+    def delete(self, path: str):
+        return self.route(path, methods=["DELETE"])
+
+    def __repr__(self):
+        return f"<Blueprint '{self.name}' prefix='{self.prefix}' routes={len(self._routes)}>"

piu/serving.py

@@ -0,0 +1,119 @@
+import asyncio
+import os
+import subprocess
+import sys
+import time
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlparse
+
+from .wrappers import Request
+
+
+def run_dev_server(app, host: str = "127.0.0.1", port: int = 5000,
+                   reload: bool = False):
+    if reload and os.environ.get("PIU_RELOADER_CHILD") != "1":
+        _run_with_reload(host, port)
+        return
+    _serve(app, host, port)
+
+
+def _make_handler(app, loop):
+    class Handler(BaseHTTPRequestHandler):
+        def _handle(self):
+            length = int(self.headers.get("Content-Length") or 0)
+            body = self.rfile.read(length) if length else b""
+            parsed = urlparse(self.path)
+            query = parse_qs(parsed.query)
+
+            req = Request(
+                method=self.command,
+                path=parsed.path,
+                headers=dict(self.headers),
+                body=body,
+                query_params=query,
+            )
+
+            resp = loop.run_until_complete(app._dispatch(req))
+            resp = app._finalize(resp)
+
+            self.send_response(resp.status)
+            self.send_header("Content-Type", resp.content_type)
+            for k, v in resp.headers.items():
+                self.send_header(k, v)
+            self.end_headers()
+            self.wfile.write(resp.body)
+
+        def do_GET(self):    self._handle()
+        def do_POST(self):   self._handle()
+        def do_PUT(self):    self._handle()
+        def do_DELETE(self): self._handle()
+        def do_PATCH(self):  self._handle()
+
+        def log_message(self, fmt, *args):
+            print(f"[PIU] {self.address_string()} - {fmt % args}")
+
+    return Handler
+
+
+def _serve(app, host: str, port: int):
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    Handler = _make_handler(app, loop)
+    server = HTTPServer((host, port), Handler)
+    print(f"[PIU] 🩲 Dev server running on http://{host}:{port}  (Ctrl+C to stop)")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\n[PIU] Shutting down. Bye 🩲")
+    finally:
+        server.server_close()
+        loop.close()
+
+
+def _run_with_reload(host: str, port: int):
+    try:
+        from watchdog.events import FileSystemEventHandler
+        from watchdog.observers import Observer
+    except ImportError:
+        print("[PIU] Hot reload requires watchdog: pip install watchdog")
+        sys.exit(1)
+
+    env = os.environ.copy()
+    env["PIU_RELOADER_CHILD"] = "1"
+
+    process: list[subprocess.Popen] = [None]
+
+    def start():
+        process[0] = subprocess.Popen([sys.executable] + sys.argv, env=env)
+
+    def restart():
+        if process[0] and process[0].poll() is None:
+            print("[PIU] 🔄 Change detected — restarting...")
+            process[0].terminate()
+            process[0].wait()
+        start()
+
+    class ChangeHandler(FileSystemEventHandler):
+        def on_modified(self, event):
+            if not event.is_directory and event.src_path.endswith(".py"):
+                restart()
+
+    start()
+
+    observer = Observer()
+    observer.schedule(ChangeHandler(), path=".", recursive=True)
+    observer.start()
+    print("[PIU] 👀 Watching for changes (hot reload active)...")
+
+    try:
+        while True:
+            time.sleep(1)
+            if process[0] and process[0].poll() is not None:
+                start()
+    except KeyboardInterrupt:
+        print("\n[PIU] Shutting down. Bye 🩲")
+        observer.stop()
+        if process[0] and process[0].poll() is None:
+            process[0].terminate()
+    finally:
+        observer.join()

piu/sessions.py

@@ -0,0 +1,86 @@
+"""
+Session middleware for PIU.
+Sessions are stored as signed, base64-encoded JSON cookies.
+No server-side storage needed — the cookie IS the session.
+
+Requires: pip install cryptography
+"""
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+from typing import Callable
+
+from .wrappers import Request, Response
+
+
+class Session(dict):
+    """A dict subclass that tracks whether it has been modified."""
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.modified = False
+
+    def __setitem__(self, key, value):
+        super().__setitem__(key, value)
+        self.modified = True
+
+    def __delitem__(self, key):
+        super().__delitem__(key)
+        self.modified = True
+
+    def clear(self):
+        super().clear()
+        self.modified = True
+
+
+class SessionMiddleware:
+    COOKIE_NAME = "piu_session"
+
+    def __init__(self, secret_key: str, max_age: int = 86400,
+                 httponly: bool = True, secure: bool = False,
+                 samesite: str = "Lax"):
+        if not secret_key:
+            raise ValueError("SessionMiddleware requires a non-empty secret_key.")
+        self._secret = secret_key.encode()
+        self._max_age = max_age
+        self._httponly = httponly
+        self._secure = secure
+        self._samesite = samesite
+
+    def _sign(self, data: str) -> str:
+        sig = hmac.new(self._secret, data.encode(), hashlib.sha256).hexdigest()
+        payload = base64.urlsafe_b64encode(data.encode()).decode()
+        return f"{payload}.{sig}"
+
+    def _unsign(self, token: str) -> dict | None:
+        try:
+            payload, sig = token.rsplit(".", 1)
+            data = base64.urlsafe_b64decode(payload.encode()).decode()
+            expected = hmac.new(self._secret, data.encode(), hashlib.sha256).hexdigest()
+            if not hmac.compare_digest(sig, expected):
+                return None
+            return json.loads(data)
+        except Exception:
+            return None
+
+    async def __call__(self, request: Request, next: Callable) -> Response:
+        raw = request.cookies.get(self.COOKIE_NAME)
+        data = self._unsign(raw) if raw else None
+        request.session = Session(data or {})
+
+        response = await next(request)
+
+        if request.session.modified:
+            payload = json.dumps(dict(request.session), separators=(",", ":"))
+            token = self._sign(payload)
+            response.set_cookie(
+                self.COOKIE_NAME, token,
+                max_age=self._max_age,
+                httponly=self._httponly,
+                secure=self._secure,
+                samesite=self._samesite,
+            )
+
+        return response

piu/static.py

@@ -0,0 +1,39 @@
+import mimetypes
+import os
+
+from .wrappers import Response
+
+mimetypes.add_type("text/javascript", ".js")
+mimetypes.add_type("text/css", ".css")
+mimetypes.add_type("image/svg+xml", ".svg")
+mimetypes.add_type("application/json", ".json")
+mimetypes.add_type("font/woff2", ".woff2")
+mimetypes.add_type("font/woff", ".woff")
+
+
+def serve_static(path: str, static_dir: str, url_prefix: str = "/static") -> Response | None:
+    """
+    Attempt to serve a static file for the given request path.
+    Returns a Response if the file exists, otherwise None.
+    """
+    if not path.startswith(url_prefix):
+        return None
+
+    rel = path[len(url_prefix):].lstrip("/")
+
+    static_dir = os.path.realpath(static_dir)
+    file_path = os.path.realpath(os.path.join(static_dir, rel))
+
+    if not file_path.startswith(static_dir):
+        return Response(body="403 Forbidden", status=403)
+
+    if not os.path.isfile(file_path):
+        return None
+
+    with open(file_path, "rb") as f:
+        content = f.read()
+
+    mime, _ = mimetypes.guess_type(file_path)
+    content_type = mime or "application/octet-stream"
+
+    return Response(body=content, status=200, content_type=content_type)

piu/tasks.py

@@ -0,0 +1,46 @@
+import asyncio
+import inspect
+import traceback
+from typing import Callable
+
+
+class BackgroundTaskRunner:
+    def __init__(self):
+        self._tasks: list[asyncio.Task] = []
+
+    def add(self, fn: Callable, *args, **kwargs):
+        loop = asyncio.get_event_loop()
+
+        async def _run():
+            try:
+                if inspect.iscoroutinefunction(fn):
+                    await fn(*args, **kwargs)
+                else:
+                    await loop.run_in_executor(None, lambda: fn(*args, **kwargs))
+            except Exception:
+                traceback.print_exc()
+
+        task = loop.create_task(_run())
+        self._tasks.append(task)
+        task.add_done_callback(lambda t: self._tasks.remove(t) if t in self._tasks else None)
+
+    async def wait(self):
+        if self._tasks:
+            await asyncio.gather(*self._tasks, return_exceptions=True)
+
+    def __repr__(self):
+        return f"<BackgroundTaskRunner pending={len(self._tasks)}>"
+
+
+class BackgroundTasks:
+    def __init__(self):
+        self._fns: list[tuple[Callable, tuple, dict]] = []
+
+    def add(self, fn: Callable, *args, **kwargs):
+        self._fns.append((fn, args, kwargs))
+
+    async def run_all(self):
+        runner = BackgroundTaskRunner()
+        for fn, args, kwargs in self._fns:
+            runner.add(fn, *args, **kwargs)
+        await runner.wait()