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

piu/__init__.py

@@ -0,0 +1,36 @@
+from .app import PIU
+from .wrappers import Request, Response
+from .routing import Router, Route, Blueprint
+from .middleware import MiddlewareStack
+from .templating import TemplateEngine
+from .static import serve_static
+from .helpers import status_text
+from .config import Config
+from .sessions import SessionMiddleware, Session
+from .csrf import CSRFMiddleware, csrf_input
+from .ratelimit import RateLimitMiddleware, rate_limit
+from .auth import require_auth, login_user, logout_user, current_user, is_authenticated
+from .testing import TestClient
+from .plugins import Plugin
+from .tasks import BackgroundTasks
+from .websocket import WebSocket
+from .openapi import generate_schema
+
+__all__ = [
+    "PIU", "Request", "Response",
+    "Router", "Route", "Blueprint",
+    "MiddlewareStack", "TemplateEngine",
+    "serve_static", "status_text",
+    "Config",
+    "SessionMiddleware", "Session",
+    "CSRFMiddleware", "csrf_input",
+    "RateLimitMiddleware", "rate_limit",
+    "require_auth", "login_user", "logout_user",
+    "current_user", "is_authenticated",
+    "TestClient",
+    "Plugin", "BackgroundTasks",
+    "WebSocket", "generate_schema",
+]
+
+__version__ = "0.5.0"
+__author__ = "TodorW & n11kol11c"

piu/__main__.py

@@ -0,0 +1,3 @@
+from piu.cli import main
+
+main()

piu/app.py

@@ -0,0 +1,226 @@
+import asyncio
+import inspect
+from typing import Callable, Optional
+from urllib.parse import parse_qs, urlparse
+
+from .auth import current_user, is_authenticated, login_user, logout_user, require_auth
+from .config import Config
+from .csrf import CSRFMiddleware, csrf_input
+from .helpers import status_text
+from .middleware import MiddlewareStack
+from .openapi import SWAGGER_HTML, generate_schema
+from .plugins import Plugin
+from .ratelimit import RateLimitMiddleware, rate_limit
+from .routing import Blueprint, Router
+from .serving import run_dev_server
+from .sessions import SessionMiddleware
+from .static import serve_static
+from .tasks import BackgroundTasks
+from .templating import TemplateEngine
+from .websocket import WebSocket, WebSocketRouter
+from .wrappers import Request, Response
+
+
+class PIU:
+    def __init__(self, template_dir: str = None,
+                 static_dir: str = None,
+                 static_url: str = None,
+                 config: dict = None):
+        self.config = Config(config)
+        self.router = Router()
+        self.ws_router = WebSocketRouter()
+        self.middleware = MiddlewareStack()
+        self._template_dir = template_dir or self.config["TEMPLATE_DIR"]
+        self._static_dir   = static_dir   or self.config["STATIC_DIR"]
+        self._static_url   = static_url   or self.config["STATIC_URL"]
+        self._template_engine: Optional[TemplateEngine] = None
+        self._error_handlers: dict[int, Callable] = {}
+        self._plugins: list[Plugin] = []
+        self._docs_enabled = False
+        self._docs_title = "PIU API"
+
+    async def __call__(self, scope: dict, receive: Callable, send: Callable):
+        await self.asgi(scope, receive, send)
+
+    def route(self, path: str, methods: list[str] = ["GET"]):
+        def decorator(fn: Callable):
+            self.router.add_route(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 ws(self, path: str):
+        def decorator(fn: Callable):
+            self.ws_router.add(path, fn)
+            return fn
+        return decorator
+
+    def enable_docs(self, title: str = "PIU API", path: str = "/docs"):
+        self._docs_enabled = True
+        self._docs_title = title
+        self._docs_path = path
+
+        @self.get(path)
+        def _swagger(request: Request):
+            html = SWAGGER_HTML.format(title=title)
+            return Response(body=html, content_type="text/html")
+
+        @self.get("/openapi.json")
+        def _schema(request: Request):
+            schema = generate_schema(
+                self.router,
+                title=title,
+                version=self.config.get("VERSION", "0.1.0"),
+            )
+            return Response.json(schema)
+
+    def register_plugin(self, plugin: Plugin):
+        plugin.setup(self)
+        self._plugins.append(plugin)
+
+    def register(self, blueprint: Blueprint, prefix: str = None):
+        bp_prefix = (prefix or blueprint.prefix).rstrip("/")
+        for path, handler, methods in blueprint._routes:
+            full_path = bp_prefix + ("" if path == "/" else path)
+            self.router.add_route(full_path, handler, methods)
+
+    def errorhandler(self, status_code: int):
+        def decorator(fn: Callable):
+            self._error_handlers[status_code] = fn
+            return fn
+        return decorator
+
+    async def _handle_error(self, request: Request, status: int, error: Exception = None) -> Response:
+        handler = self._error_handlers.get(status)
+        if handler:
+            result = handler(request, error) if not inspect.iscoroutinefunction(handler) \
+                else await handler(request, error)
+            return result if isinstance(result, Response) else Response(body=result, status=status)
+        return Response(body=f"{status} {status_text(status)}", status=status)
+
+    def render(self, template_name: str, **context) -> Response:
+        if self._template_engine is None:
+            self._template_engine = TemplateEngine(self._template_dir)
+        html = self._template_engine.render(template_name, **context)
+        return Response(body=html, content_type="text/html")
+
+    async def _dispatch(self, request: Request) -> Response:
+        static_resp = serve_static(request.path, self._static_dir, self._static_url)
+        if static_resp is not None:
+            return static_resp
+
+        handler, path_params = self.router.resolve(request.path, request.method)
+
+        if handler is None:
+            return await self._handle_error(request, 404)
+
+        request.background_tasks = BackgroundTasks()
+
+        async def call_handler(req: Request) -> Response:
+            try:
+                result = await handler(req, **path_params) \
+                    if inspect.iscoroutinefunction(handler) \
+                    else handler(req, **path_params)
+                resp = result if isinstance(result, Response) else Response(body=result)
+                await req.background_tasks.run_all()
+                return resp
+            except Exception as e:
+                return await self._handle_error(req, 500, e)
+
+        return await self.middleware.run(request, call_handler)
+
+    def _finalize(self, response: Response) -> Response:
+        for k, v in response._cookie_headers():
+            existing = response.headers.get(k)
+            if existing:
+                response.headers[k] = existing + "\n" + v
+            else:
+                response.headers[k] = v
+        return response
+
+    def wsgi(self, environ: dict, start_response: Callable):
+        parsed = urlparse(environ.get("PATH_INFO", "/"))
+        query = parse_qs(environ.get("QUERY_STRING", ""))
+        length = int(environ.get("CONTENT_LENGTH") or 0)
+        body = environ["wsgi.input"].read(length) if length else b""
+
+        headers = {
+            k[5:].replace("_", "-").title(): v
+            for k, v in environ.items() if k.startswith("HTTP_")
+        }
+
+        request = Request(
+            method=environ.get("REQUEST_METHOD", "GET"),
+            path=parsed.path, headers=headers,
+            body=body, query_params=query,
+        )
+
+        response = self._finalize(asyncio.run(self._dispatch(request)))
+        status_str = f"{response.status} {status_text(response.status)}"
+        resp_headers = [("Content-Type", response.content_type)]
+        for k, v in response.headers.items():
+            resp_headers.append((k, v))
+
+        start_response(status_str, resp_headers)
+        return [response.body]
+
+    async def asgi(self, scope: dict, receive: Callable, send: Callable):
+        if scope["type"] == "websocket":
+            handler, params = self.ws_router.resolve(scope.get("path", "/"))
+            if handler is None:
+                await send({"type": "websocket.close", "code": 4004})
+                return
+            ws = WebSocket(scope, receive, send)
+            await send({"type": "websocket.accept"})
+            if inspect.iscoroutinefunction(handler):
+                await handler(ws, **params)
+            else:
+                handler(ws, **params)
+            return
+
+        if scope["type"] != "http":
+            return
+
+        body = b""
+        while True:
+            event = await receive()
+            body += event.get("body", b"")
+            if not event.get("more_body", False):
+                break
+
+        query = parse_qs(scope.get("query_string", b"").decode())
+        headers = {k.decode(): v.decode() for k, v in scope.get("headers", [])}
+
+        request = Request(
+            method=scope.get("method", "GET"),
+            path=scope.get("path", "/"),
+            headers=headers, body=body, query_params=query,
+        )
+
+        response = self._finalize(await self._dispatch(request))
+
+        await send({
+            "type": "http.response.start",
+            "status": response.status,
+            "headers": [
+                [b"content-type", response.content_type.encode()],
+                *[[k.encode(), v.encode()] for k, v in response.headers.items()]
+            ],
+        })
+        await send({"type": "http.response.body", "body": response.body})
+
+    def run(self, host: str = None, port: int = None, reload: bool = None):
+        run_dev_server(
+            self,
+            host   = host   or self.config.get("HOST", "127.0.0.1"),
+            port   = port   or self.config.get("PORT", 5000),
+            reload = reload if reload is not None else self.config.get("DEBUG", False),
+        )
+
+    def __repr__(self):
+        return f"<PIU routes={len(self.router._routes)} middleware={len(self.middleware._middlewares)}>"

piu/auth.py

@@ -0,0 +1,114 @@
+"""
+Auth utilities for PIU.
+
+Provides:
+  - @require_auth           — decorator that guards a route, redirects or 401s if not authed
+  - @require_auth(role=...) — additionally checks request.user["role"]
+  - login_user(request, user_data)   — store user in session
+  - logout_user(request)             — clear user from session
+  - current_user(request)            — retrieve user dict from session (or None)
+
+Requires SessionMiddleware to be registered.
+
+Example::
+
+    @app.post("/login")
+    def login(request):
+        user = db.check_credentials(request.json())
+        if not user:
+            return Response(body="Bad credentials", status=401)
+        login_user(request, {"id": user.id, "role": "admin"})
+        return Response.redirect("/dashboard")
+
+    @app.get("/dashboard")
+    @require_auth
+    def dashboard(request):
+        return Response(body=f"Hello {current_user(request)['id']}")
+
+    @app.get("/admin")
+    @require_auth(role="admin")
+    def admin_panel(request):
+        ...
+"""
+
+import functools
+import inspect
+from typing import Callable
+
+from .wrappers import Request, Response
+
+SESSION_USER_KEY = "_auth_user"
+
+def login_user(request: Request, user_data: dict):
+    """Store user data in the session."""
+    _require_session(request)
+    request.session[SESSION_USER_KEY] = user_data
+
+
+def logout_user(request: Request):
+    """Remove user data from the session."""
+    _require_session(request)
+    request.session.pop(SESSION_USER_KEY, None)
+
+
+def current_user(request: Request) -> dict | None:
+    """Return the logged-in user dict, or None."""
+    _require_session(request)
+    return request.session.get(SESSION_USER_KEY)
+
+
+def is_authenticated(request: Request) -> bool:
+    return current_user(request) is not None
+
+
+def _require_session(request: Request):
+    if not hasattr(request, "session"):
+        raise RuntimeError(
+            "Auth helpers require SessionMiddleware. "
+            "Register it before using @require_auth."
+        )
+
+def require_auth(fn: Callable = None, *, role: str = None,
+                 redirect_to: str = None, status: int = 401):
+    """
+    Guard a route handler. Can be used with or without arguments:
+
+        @require_auth
+        def view(request): ...
+
+        @require_auth(role="admin", redirect_to="/login")
+        def admin(request): ...
+
+    Args:
+        role:        If set, also checks request.session["_auth_user"]["role"].
+        redirect_to: If set, returns a redirect instead of a 401/403 response.
+        status:      Status code for unauthenticated responses (default 401).
+                     Automatically becomes 403 when role check fails.
+    """
+    def decorator(handler: Callable):
+        @functools.wraps(handler)
+        async def wrapper(request: Request, *args, **kwargs):
+            _require_session(request)
+            user = current_user(request)
+
+            if not user:
+                return _deny(redirect_to, status, "401 Unauthorized.")
+
+            if role and user.get("role") != role:
+                return _deny(redirect_to, 403, f"403 Forbidden — requires role '{role}'.")
+
+            if inspect.iscoroutinefunction(handler):
+                return await handler(request, *args, **kwargs)
+            return handler(request, *args, **kwargs)
+
+        return wrapper
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator
+
+
+def _deny(redirect_to: str, status: int, message: str) -> Response:
+    if redirect_to:
+        return Response.redirect(redirect_to)
+    return Response(body=message, status=status)

piu/cli.py

@@ -0,0 +1,161 @@
+import argparse
+import os
+import sys
+
+
+_APP_TEMPLATE = '''\
+import piu
+from piu import (
+    PIU, Request, Response,
+    SessionMiddleware, CSRFMiddleware,
+    RateLimitMiddleware,
+)
+
+app = PIU()
+
+app.config.from_env_file(".env")
+app.config.load_env()
+
+app.middleware.use(RateLimitMiddleware(limit=100, window=60))
+app.middleware.use(SessionMiddleware(
+    secret_key=app.config.get("SECRET_KEY", "dev-secret"),
+    max_age=3600,
+))
+app.middleware.use(CSRFMiddleware())
+
+
+@app.errorhandler(404)
+def not_found(request, error):
+    return Response(body="<h1>404 — Not found</h1>", status=404)
+
+
+@app.get("/")
+def index(request: Request):
+    return Response(body="<h1>Hello from PIU 🩲</h1>")
+
+
+if __name__ == "__main__":
+    app.run()
+'''
+
+_ENV_TEMPLATE = """\
+DEBUG=true
+HOST=127.0.0.1
+PORT=5000
+SECRET_KEY=change-me-in-production
+"""
+
+_HTML_TEMPLATE = """\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>{{ title }}</title>
+</head>
+<body>
+  <h1>🩲 {{ title }}</h1>
+  <p>Your PIU app is running.</p>
+</body>
+</html>
+"""
+
+_GITIGNORE_TEMPLATE = """\
+__pycache__/
+*.pyc
+.env
+*.egg-info/
+dist/
+.venv/
+"""
+
+_TEST_TEMPLATE = '''\
+from piu.testing import TestClient
+from app import app
+
+client = TestClient(app)
+
+
+def test_index():
+    resp = client.get("/")
+    assert resp.status == 200
+'''
+
+
+def cmd_new(args):
+    name = args.name
+    base = os.path.join(os.getcwd(), name)
+
+    if os.path.exists(base):
+        print(f"[PIU] Error: directory '{name}' already exists.")
+        sys.exit(1)
+
+    dirs = [base, os.path.join(base, "templates"),
+            os.path.join(base, "static"), os.path.join(base, "tests")]
+    for d in dirs:
+        os.makedirs(d)
+
+    files = {
+        os.path.join(base, "app.py"): _APP_TEMPLATE,
+        os.path.join(base, ".env"): _ENV_TEMPLATE,
+        os.path.join(base, "templates", "index.html"): _HTML_TEMPLATE,
+        os.path.join(base, ".gitignore"): _GITIGNORE_TEMPLATE,
+        os.path.join(base, "tests", "test_app.py"): _TEST_TEMPLATE,
+    }
+    for path, content in files.items():
+        with open(path, "w") as f:
+            f.write(content)
+
+    print(f"\n[PIU] 🩲 '{name}' created!\n")
+    print(f"  cd {name}")
+    print(f"  python app.py\n")
+
+
+def cmd_run(args):
+    if not os.path.isfile("app.py"):
+        print("[PIU] Error: no app.py found in the current directory.")
+        sys.exit(1)
+
+    sys.path.insert(0, os.getcwd())
+    try:
+        import importlib
+        module = importlib.import_module("app")
+    except Exception as e:
+        print(f"[PIU] Failed to import app.py: {e}")
+        sys.exit(1)
+
+    app = getattr(module, "app", None)
+    if app is None:
+        print("[PIU] Error: app.py must define an 'app' variable.")
+        sys.exit(1)
+
+    if os.path.isfile(".env"):
+        app.config.from_env_file(".env")
+    app.config.load_env()
+
+    host = args.host or app.config.get("HOST", "127.0.0.1")
+    port = args.port or app.config.get("PORT", 5000)
+    reload = args.reload or app.config.get("DEBUG", False)
+
+    app.run(host=host, port=int(port), reload=reload)
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="piu", description="🩲 Python In Underwear CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_new = sub.add_parser("new", help="Scaffold a new PIU project")
+    p_new.add_argument("name", help="Project name")
+    p_new.set_defaults(func=cmd_new)
+
+    p_run = sub.add_parser("run", help="Run the development server")
+    p_run.add_argument("--host", default=None)
+    p_run.add_argument("--port", default=None, type=int)
+    p_run.add_argument("--reload", action="store_true")
+    p_run.set_defaults(func=cmd_run)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

piu/config.py

@@ -0,0 +1,85 @@
+import os
+from typing import Any
+
+
+class Config:
+    def __init__(self, defaults: dict = None):
+        self._data: dict[str, Any] = {
+            "DEBUG": False,
+            "HOST": "127.0.0.1",
+            "PORT": 5000,
+            "SECRET_KEY": "",
+            "TEMPLATE_DIR": "templates",
+            "STATIC_DIR": "static",
+            "STATIC_URL": "/static",
+        }
+        if defaults:
+            self._data.update(defaults)
+
+    def __getitem__(self, key: str) -> Any:
+        return self._data[key.upper()]
+
+    def __setitem__(self, key: str, value: Any):
+        self._data[key.upper()] = value
+
+    def __contains__(self, key: str) -> bool:
+        return key.upper() in self._data
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._data.get(key.upper(), default)
+
+    def set(self, key: str, value: Any):
+        self._data[key.upper()] = value
+
+    def all(self) -> dict:
+        return dict(self._data)
+
+    def from_dict(self, d: dict):
+        for k, v in d.items():
+            self._data[k.upper()] = v
+
+    def from_env_file(self, path: str = ".env"):
+        if not os.path.isfile(path):
+            return
+        with open(path) as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                key, _, val = line.partition("=")
+                self._data[key.strip().upper()] = _cast(val.strip())
+
+    def from_yaml(self, path: str):
+        try:
+            import yaml
+        except ImportError:
+            raise RuntimeError("from_yaml() requires pyyaml. Run: pip install pyyaml")
+        with open(path) as f:
+            data = yaml.safe_load(f) or {}
+        for k, v in data.items():
+            self._data[k.upper()] = v
+
+    def load_env(self, prefix: str = "PIU_"):
+        for k, v in os.environ.items():
+            if k.startswith(prefix):
+                key = k[len(prefix):]
+                self._data[key.upper()] = _cast(v)
+
+    def __repr__(self):
+        return f"<Config keys={list(self._data.keys())}>"
+
+
+def _cast(value: str) -> Any:
+    if value.lower() in ("true", "yes"):
+        return True
+    if value.lower() in ("false", "no"):
+        return False
+    try:
+        return int(value)
+    except ValueError:
+        pass
+    try:
+        return float(value)
+    except ValueError:
+        pass
+    return value

piu/csrf.py

@@ -0,0 +1,65 @@
+import os
+import hmac
+import hashlib
+from typing import Callable
+
+from .wrappers import Request, Response
+
+CSRF_SESSION_KEY = "_csrf_token"
+UNSAFE_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
+
+
+def _generate_token() -> str:
+    return os.urandom(32).hex()
+
+
+def _tokens_equal(a: str, b: str) -> bool:
+    return hmac.compare_digest(a.encode(), b.encode())
+
+
+class CSRFMiddleware:
+    def __init__(self, exempt_paths: list[str] = None):
+        """
+        Args:
+            exempt_paths: List of URL path prefixes to skip CSRF checks on.
+                          Useful for API routes using token auth instead of sessions.
+                          e.g. ["/api/", "/webhook"]
+        """
+        self._exempt = exempt_paths or []
+
+    def _is_exempt(self, path: str) -> bool:
+        return any(path.startswith(p) for p in self._exempt)
+
+    async def __call__(self, request: Request, next: Callable) -> Response:
+        if not hasattr(request, "session"):
+            raise RuntimeError(
+                "CSRFMiddleware requires SessionMiddleware to run first. "
+                "Register SessionMiddleware before CSRFMiddleware."
+            )
+
+        
+        if CSRF_SESSION_KEY not in request.session:
+            request.session[CSRF_SESSION_KEY] = _generate_token()
+
+        token = request.session[CSRF_SESSION_KEY]
+
+        
+        request.csrf_token = token
+
+        
+        if request.method in UNSAFE_METHODS and not self._is_exempt(request.path):
+            
+            submitted = (
+                request.headers.get("X-Csrf-Token")
+                or request.headers.get("X-CSRF-Token")
+                or request.form().get("_csrf_token", [None])[0]
+            )
+            if not submitted or not _tokens_equal(token, submitted):
+                return Response(body="403 CSRF token invalid or missing.", status=403)
+
+        return await next(request)
+
+
+def csrf_input(token: str) -> str:
+    """Return an HTML hidden input string for use in templates."""
+    return f'<input type="hidden" name="_csrf_token" value="{token}">'