tina4-python 3.12.5__tar.gz → 3.12.8__tar.gz

{tina4_python-3.12.5 → tina4_python-3.12.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.12.5
+Version: 3.12.8
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT

{tina4_python-3.12.5 → tina4_python-3.12.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tina4-python"
-version = "3.12.5"
+version = "3.12.8"
 description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
 authors = [
     {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}

{tina4_python-3.12.5 → tina4_python-3.12.8}/tina4_python/__init__.py

@@ -8,7 +8,7 @@ Tina4 Python v3.0 — Zero-dependency, lightweight web framework.
 
 One import, everything works.
 """
-__version__ = "3.12.5"
+__version__ = "3.12.8"
 
 # ── Route decorators ──
 from tina4_python.core.router import (  # noqa: E402, F401

{tina4_python-3.12.5 → tina4_python-3.12.8}/tina4_python/core/router.py

@@ -246,6 +246,33 @@ class Router:
         """Register a DELETE route (imperative, non-decorator style)."""
         return cls.add("DELETE", path, handler, middleware=middleware, swagger_meta=swagger_meta, template=template, **options)
 
+    @classmethod
+    def head(cls, path: str, handler, middleware: list = None, swagger_meta: dict = None, template: str = None, **options) -> "RouteRef":
+        """Register an explicit HEAD route.
+
+        By default the framework auto-handles HEAD by falling back to the GET
+        route and stripping the body (RFC 9110 §9.3.2). Use this method only
+        when you need a HEAD handler that does something different from GET —
+        e.g. cheaper existence-check logic, custom validator headers without
+        the cost of building the body.
+
+        The framework still strips the response body for you on the way out —
+        HEAD MUST NOT return content, even if your handler does, so we
+        enforce that unconditionally rather than relying on developer care.
+        """
+        return cls.add("HEAD", path, handler, middleware=middleware, swagger_meta=swagger_meta, template=template, **options)
+
+    @classmethod
+    def options(cls, path: str, handler, middleware: list = None, swagger_meta: dict = None, template: str = None, **options) -> "RouteRef":
+        """Register an explicit OPTIONS route.
+
+        By default the framework auto-handles OPTIONS by building an Allow
+        header from every method registered for the path and returning 204
+        (RFC 9110 §9.3.7). Use this method to take over that behaviour —
+        e.g. to return a richer OPTIONS payload describing the resource.
+        """
+        return cls.add("OPTIONS", path, handler, middleware=middleware, swagger_meta=swagger_meta, template=template, **options)
+
     @classmethod
     def any(cls, path: str, handler, middleware: list = None, swagger_meta: dict = None, template: str = None, **options) -> "RouteRef":
         """Register a route for any HTTP method (imperative, non-decorator style)."""
@@ -291,7 +318,11 @@ class Router:
             # Route has custom middleware — developer handles auth themselves
             auth_required = False
         else:
-            auth_required = m not in ("GET", "ANY")
+            # GET, HEAD, OPTIONS, and ANY are public by default. HEAD and
+            # OPTIONS are safe/idempotent introspection methods (RFC 9110
+            # §9.2.1) — requiring auth on them breaks cache validators
+            # and CORS preflight probes.
+            auth_required = m not in ("GET", "HEAD", "OPTIONS", "ANY")
 
         route = {
             "method": m,
@@ -312,9 +343,18 @@ class Router:
 
     @staticmethod
     def match(method: str, path: str) -> tuple[dict | None, dict]:
-        """Find a route matching method + path. Returns (route, params)."""
+        """Find a route matching method + path. Returns (route, params).
+
+        RFC 9110 §9.3.2: HEAD is identical to GET except the response carries
+        no body. If the app didn't register a dedicated HEAD route, we
+        transparently match the GET route; the dispatcher strips the body on
+        the way out, so the handler doesn't need to know HEAD even happened.
+        """
+        method_upper = method.upper()
+
+        # First pass: exact method match (covers HEAD → explicit HEAD route too)
         for route in _routes:
-            if route["method"] not in (method.upper(), "ANY"):
+            if route["method"] not in (method_upper, "ANY"):
                 continue
             m = route["pattern"].match(path)
             if m:
@@ -323,8 +363,58 @@ class Router:
                     params[name] = m.group(i + 1)
                 return route, params
 
+        # Second pass: HEAD auto-fallback to GET when no HEAD route registered
+        if method_upper == "HEAD":
+            for route in _routes:
+                if route["method"] not in ("GET", "ANY"):
+                    continue
+                m = route["pattern"].match(path)
+                if m:
+                    params = {}
+                    for i, name in enumerate(route["param_names"]):
+                        params[name] = m.group(i + 1)
+                    return route, params
+
         return None, {}
 
+    @staticmethod
+    def methods_allowed_for_path(path: str) -> list[str]:
+        """Return the list of HTTP methods registered for ``path``, in the
+        order GET / POST / PUT / PATCH / DELETE / HEAD / OPTIONS. Used by
+        the dispatcher to build the ``Allow:`` header on 405 / OPTIONS
+        responses (RFC 9110 §10.2.1, §9.3.7).
+
+        If GET is registered, HEAD is appended implicitly (the framework
+        auto-falls-back HEAD to GET). OPTIONS is appended whenever the
+        path has any registered method (the framework auto-handles OPTIONS).
+        """
+        # ANY routes count for every method but we don't enumerate them
+        # individually — flag whether ANY matched and union it with the
+        # concrete-method matches.
+        method_order = ("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS")
+        seen: set[str] = set()
+        any_matched = False
+
+        for route in _routes:
+            if not route["pattern"].match(path):
+                continue
+            m = route["method"]
+            if m == "ANY":
+                any_matched = True
+            elif m in method_order:
+                seen.add(m)
+
+        if any_matched:
+            seen.update(method_order)
+
+        # GET implies HEAD; any registered method implies OPTIONS.
+        if seen:
+            if "GET" in seen:
+                seen.add("HEAD")
+            seen.add("OPTIONS")
+
+        return [m for m in method_order if m in seen]
+
     @staticmethod
     def get_routes() -> list[dict]:
         """Return all registered routes."""

{tina4_python-3.12.5 → tina4_python-3.12.8}/tina4_python/core/server.py

@@ -1338,7 +1338,43 @@ async def handle(request: Request) -> Response:
         except Exception as e:
             response = _handle_route_error(e, request, response, request_id, _is_dev)
     else:
-        response = _handle_no_route(request, response, request_id)
+        # RFC 9110 conformance — before falling through to 404 / static / template,
+        # check whether the PATH is known to the router under any OTHER method.
+        # If yes:
+        #   - OPTIONS request → 204 No Content with Allow listing the methods
+        #     (RFC 9110 §9.3.7). Generic OPTIONS handler.
+        #   - Any other method (PUT on GET-only route, TRACE, CONNECT, etc.)
+        #     → 405 Method Not Allowed with Allow header (§15.5.6 + §10.2.1).
+        allowed = Router.methods_allowed_for_path(request.path)
+        if allowed:
+            allow_header = ", ".join(allowed)
+            if request.method.upper() == "OPTIONS":
+                response.header("Allow", allow_header)
+                response.status(204)
+            else:
+                response.header("Allow", allow_header)
+                response.status(405).json({
+                    "error": "Method Not Allowed",
+                    "path": request.path,
+                    "method": request.method,
+                    "allow": allowed,
+                    "status": 405,
+                })
+        else:
+            response = _handle_no_route(request, response, request_id)
+
+    # RFC 9110 §9.3.2: a HEAD response MUST NOT include content. Strip the
+    # body unconditionally (even for explicit Router.head() handlers that
+    # accidentally returned one) and record what Content-Length the GET
+    # would have sent — cache validators / link checkers / monitoring
+    # probes rely on that header to size estimates.
+    if request.method.upper() == "HEAD":
+        body = response.content if response.content is not None else b""
+        if isinstance(body, str):
+            body = body.encode("utf-8")
+        if body:
+            response.header("Content-Length", str(len(body)))
+            response.content = b""
 
     return _finalize_response(request, response, route, request_id, _is_dev, _req_start)
 

{tina4_python-3.12.5 → tina4_python-3.12.8}/tina4_python/database/postgres.py

@@ -20,6 +20,28 @@ class PostgreSQLAdapter(DatabaseAdapter):
         self._conn = None
         self._in_transaction: bool = False
 
+    @staticmethod
+    def _safe_execute(cursor, sql: str, params=None):
+        """Wrapper for ``cursor.execute`` that side-steps psycopg2's
+        always-on ``%`` substitution when no params are needed.
+
+        Issue #40: psycopg2 interprets ``%`` characters in the SQL
+        as parameter placeholders WHENEVER the ``params`` argument is
+        supplied — even an empty list ``[]``. So a migration body
+        containing ``RAISE EXCEPTION 'thing % conflicts with %', a, b``
+        (perfectly valid PL/pgSQL) blows up with the misleading
+        ``list index out of range`` because psycopg2 thinks ``%`` is a
+        placeholder and there are no values to substitute.
+
+        Pass ``None`` (or omit the second arg) and psycopg2 skips the
+        substitution pass entirely — literal ``%`` flows through
+        untouched. So we route empty/None params through that path.
+        """
+        if params:
+            cursor.execute(sql, params)
+        else:
+            cursor.execute(sql)
+
     def connect(self, connection_string: str, username: str = "", password: str = "", **kwargs):
         """Connect to PostgreSQL.
 
@@ -63,7 +85,7 @@ class PostgreSQLAdapter(DatabaseAdapter):
         )
 
         cursor = self._conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor)
-        cursor.execute(sql, params or [])
+        self._safe_execute(cursor, sql, params)
 
         records = []
         last_id = None
@@ -124,7 +146,7 @@ class PostgreSQLAdapter(DatabaseAdapter):
         # Count total rows
         count_sql = f"SELECT COUNT(*) AS cnt FROM ({sql}) AS _count_subquery"
         try:
-            cursor.execute(count_sql, params or [])
+            self._safe_execute(cursor, count_sql, params)
             total = cursor.fetchone()["cnt"]
         except Exception:
             total = 0
@@ -132,7 +154,7 @@ class PostgreSQLAdapter(DatabaseAdapter):
         # Apply pagination
         paginated_sql = f"{sql} LIMIT %s OFFSET %s"
         paginated_params = (params or []) + [limit, offset]
-        cursor.execute(paginated_sql, paginated_params)
+        self._safe_execute(cursor, paginated_sql, paginated_params)
         rows = [self._decode_blobs(dict(row)) for row in cursor.fetchall()]
 
         return DatabaseResult(records=rows, count=total, limit=limit, offset=offset, sql=sql, adapter=self)
@@ -142,7 +164,7 @@ class PostgreSQLAdapter(DatabaseAdapter):
 
         sql = self._translate_sql(sql)
         cursor = self._conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor)
-        cursor.execute(sql, params or [])
+        self._safe_execute(cursor, sql, params)
         row = cursor.fetchone()
         return self._decode_blobs(dict(row)) if row else None