tina4-python 3.13.95__tar.gz → 3.13.97__tar.gz

{tina4_python-3.13.95 → tina4_python-3.13.97}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.13.95
+Version: 3.13.97
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT
@@ -39,6 +39,7 @@ Requires-Dist: boto3>=1.34; extra == 'test'
 Requires-Dist: confluent-kafka>=2.0; extra == 'test'
 Requires-Dist: firebird-driver>=1.10; extra == 'test'
 Requires-Dist: mysql-connector-python>=9.0; extra == 'test'
+Requires-Dist: openapi-spec-validator>=0.7; extra == 'test'
 Requires-Dist: pika>=1.3; extra == 'test'
 Requires-Dist: psycopg2-binary>=2.9; extra == 'test'
 Requires-Dist: pymemcache>=4.0; extra == 'test'

{tina4_python-3.13.95 → tina4_python-3.13.97}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tina4-python"
-version = "3.13.95"
+version = "3.13.97"
 description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
 authors = [
     {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}
@@ -81,6 +81,10 @@ test = [
     "confluent-kafka>=2.0",
     "pika>=1.3",
     "boto3>=1.34",
+    # TEST-ONLY: validates the generated OpenAPI document against the real
+    # OpenAPI 3.0/3.1 schema (tests/test_swagger_contract.py). NEVER a framework
+    # runtime dependency — the swagger generator itself stays zero-dependency.
+    "openapi-spec-validator>=0.7",
 ]
 
 [dependency-groups]

{tina4_python-3.13.95 → tina4_python-3.13.97}/tina4_python/CLAUDE.md

@@ -821,7 +821,7 @@ row = db.fetch_one("SELECT * FROM users WHERE id = ?", [1])
 # Result methods
 result.to_json()       # JSON string
 result.to_array()      # List of dicts
-result.to_paginate()   # Dict with records, count, limit, offset
+result.to_paginate()   # Dict: records, total, page, per_page, total_pages, limit, offset (takes no args; ADR-0043)
 result.to_csv()        # CSV string
 
 # Transactions

{tina4_python-3.13.95 → tina4_python-3.13.97}/tina4_python/__init__.py

@@ -51,7 +51,7 @@ def _resolve_version() -> str:
     #
     # test_version_constant.py now asserts this literal equals the pyproject
     # version, so the release bump cannot leave it behind again.
-    return "3.13.95"
+    return "3.13.97"
 
 
 __version__ = _resolve_version()
@@ -86,6 +86,7 @@ from tina4_python.core.constants import (  # noqa: E402, F401
 )
 from tina4_python.core.server import (  # noqa: E402, F401
     run, background, background_task_count, stop_all_background_tasks,
+    asgi,
 )
 from tina4_python.core.events import on, emit, once, off  # noqa: E402, F401
 from tina4_python.env import Env  # noqa: E402, F401

{tina4_python-3.13.95 → tina4_python-3.13.97}/tina4_python/api/__init__.py

@@ -203,13 +203,16 @@ class Api:
         """HTTP DELETE request."""
         return self._request("DELETE", self._url(path), body)
 
-    def send(self, method: str, path: str = "", body=None,
-             content_type: str = "application/json") -> dict:
-        """Generic request method — pick HTTP verb at call time.
-
-        Renamed from ``send_request`` in 3.13.0 for parity with the
-        documentation and conciseness (``api.send("PATCH", ...)`` reads
-        cleaner than ``api.send_request("PATCH", ...)``).
+    def send_request(self, method: str, path: str = "", body=None,
+                     content_type: str = "application/json") -> dict:
+        """Generic request method — pick the HTTP verb at call time.
+
+        ``send_request`` is the name all four frameworks share (PHP
+        ``sendRequest``, Ruby ``send_request``, Node ``sendRequest``). The
+        3.13.0 Python-only rename to ``send`` was reverted: ``send`` can never
+        be the shared name because Ruby's ``send`` is ``Object#send``, the
+        metaprogramming primitive, so a Ruby class cannot expose an HTTP
+        ``send`` without shadowing it. One concept, one name, everywhere.
         """
         return self._request(method.upper(), self._url(path), body, content_type)
 

{tina4_python-3.13.95 → tina4_python-3.13.97}/tina4_python/core/server.py

@@ -17,7 +17,11 @@ import uuid
 from email.utils import formatdate, parsedate_to_datetime
 from pathlib import Path
 
-from tina4_python.core.request import Request
+from tina4_python.core.request import (
+    Request,
+    PayloadTooLarge,
+    TINA4_MAX_UPLOAD_SIZE,
+)
 from tina4_python.core.response import Response
 from tina4_python.core.router import Router
 from tina4_python.core.middleware import CorsMiddleware, RateLimiter
@@ -1867,10 +1871,42 @@ async def _invoke_handler(request: Request, response: Response, route: dict, par
         _args.append(request)
         _args.append(response)
 
-    if _pcount == 0:
-        result = await route["handler"]()
+    # A SYNC HANDLER RUNS IN A THREAD, AN ASYNC ONE RUNS ON THE LOOP.
+    #
+    # This used to `await` the handler unconditionally, which had two costs.
+    # A plain `def` handler died with "object Response can't be used in 'await'
+    # expression" - a message naming neither the handler nor the rule - even
+    # though Flask, Django and FastAPI all accept a sync view, so `def` is the
+    # first thing a Python developer writes. And there was nowhere for blocking
+    # work to go: asyncio runs ONE loop, so anything that blocks it stops every
+    # other in-flight request. Measured on 3.13.94 with time.sleep(10) in a
+    # route, a trivial route took 9.004s instead of milliseconds.
+    #
+    # Threading the sync path fixes both at once, and is what Starlette and
+    # FastAPI already do. It is also Python's answer to the same problem PHP
+    # solved by forking per request: PHP has no threads, Python does.
+    #
+    # The check happens BEFORE the call, deliberately. Calling first and then
+    # asking whether the result is awaitable would already have run the sync
+    # handler on the loop, which is the thing being avoided.
+    #
+    # A callable OBJECT with an async __call__ reports False from
+    # iscoroutinefunction(), so its __call__ is checked too - otherwise such a
+    # handler would be sent to a thread and its coroutine never awaited.
+    _handler = route["handler"]
+    _is_async = inspect.iscoroutinefunction(_handler) or (
+        not inspect.isfunction(_handler)
+        and not inspect.ismethod(_handler)
+        and inspect.iscoroutinefunction(getattr(_handler, "__call__", None))
+    )
+
+    if _is_async:
+        result = await (_handler() if _pcount == 0 else _handler(*_args))
+    elif _pcount == 0:
+        result = await asyncio.to_thread(_handler)
     else:
-        result = await route["handler"](*_args)
+        result = await asyncio.to_thread(_handler, *_args)
+
     if isinstance(result, Response):
         response = result
     return response
@@ -2549,6 +2585,62 @@ async def handle(request: Request) -> Response:
 
     return ctx.response
 
+def asgi(root_dir: str = "src"):
+    """Build the ASGI application, with routes discovered.
+
+    Point any ASGI server at this - uvicorn, hypercorn, granian, daphne - when
+    you want that server's process model instead of ``tina4 serve``:
+
+        # asgi.py
+        from tina4_python.core.server import asgi
+        app = asgi()
+
+        $ uvicorn asgi:app --workers 4
+
+    THE DISCOVERY IS THE POINT. Pointing a server straight at ``app`` below
+    starts a working ASGI application with NO ROUTES REGISTERED, because
+    discovery happens inside ``run()`` and nothing else calls it. Measured: the
+    bare app answers /hello with a 404 page, and the same app behind this
+    function answers 200. That failure is quiet - the server boots, the health
+    page renders, and every application route 404s - so the framework supplies
+    the bootstrap rather than leaving each user to find ``_auto_discover``,
+    which is private and has no business in a deployment file.
+
+    :param root_dir: Directory to discover routes from. Defaults to ``src``.
+    :return: The ASGI 3 callable.
+    """
+    _auto_discover(root_dir)
+    return app
+
+
+async def _send_payload_too_large(send, received: int, limit: int) -> None:
+    """Answer 413 for a body over TINA4_MAX_UPLOAD_SIZE.
+
+    Written straight to the ASGI `send` rather than routed through the normal
+    response path: the request never became a Request object, so there is no
+    route, no middleware and no session to run it through.
+    """
+    import json
+
+    payload = json.dumps(
+        {
+            "error": f"Request body ({received} bytes) exceeds "
+                     f"TINA4_MAX_UPLOAD_SIZE ({limit} bytes)"
+        }
+    ).encode("utf-8")
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 413,
+            "headers": [
+                [b"content-type", b"application/json"],
+                [b"content-length", str(len(payload)).encode()],
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": payload, "more_body": False})
+
+
 async def app(scope: dict, receive, send):
     """ASGI entry point — compatible with uvicorn, hypercorn, granian."""
     if scope["type"] == "lifespan":
@@ -2584,16 +2676,74 @@ async def app(scope: dict, receive, send):
     if scope["type"] != "http":
         return
 
-    # Read full body
-    body = b""
+    # Read the body, bounded, in one allocation.
+    #
+    # Two defects lived in the three lines this replaces.
+    #
+    # `body += chunk` on immutable bytes reallocates and copies the WHOLE
+    # buffer per chunk, so an N-byte body costs O(N^2). Measured with uvicorn
+    # feeding ~16KB chunks: a 40MB upload took the server from 51MB RSS to
+    # 1213MB. A list plus one join is linear.
+    #
+    # And the size limit was enforced by Request.from_scope AFTER this loop
+    # finished, so a body 4x over the limit was accumulated in full and only
+    # then refused - the limit measured the damage instead of preventing it.
+    # Checking per chunk stops at the limit. (Same defect, same fix, as the
+    # Node request reader.)
+    # Refuse on the DECLARED length before reading a byte. A client that
+    # announces 32MB against a 1MB limit gets its answer immediately instead of
+    # uploading 32MB first; and a client that announces a large body and then
+    # sends almost nothing would otherwise hold the connection while the server
+    # waits for the rest. This is what a reverse proxy does in front of you.
+    declared = 0
+    for _name, _value in scope.get("headers", []):
+        if _name.lower() == b"content-length":
+            try:
+                declared = int(_value)
+            except (TypeError, ValueError):
+                declared = 0
+            break
+    if declared > TINA4_MAX_UPLOAD_SIZE:
+        await _send_payload_too_large(send, declared, TINA4_MAX_UPLOAD_SIZE)
+        return
+
+    chunks = []
+    received = 0
+    too_large = False
     while True:
         msg = await receive()
-        body += msg.get("body", b"")
+        chunk = msg.get("body", b"")
+        if chunk and not too_large:
+            received += len(chunk)
+            if received > TINA4_MAX_UPLOAD_SIZE:
+                # Stop accumulating, but keep draining: an ASGI server expects
+                # the request stream to be consumed, and abandoning it mid-body
+                # can wedge the connection.
+                too_large = True
+                chunks = []
+            else:
+                chunks.append(chunk)
         if not msg.get("more_body", False):
             break
 
+    if too_large:
+        # 413, not 500. PayloadTooLarge was raised and caught by nobody, so an
+        # oversized upload answered "Internal Server Error" - which tells the
+        # caller to retry the request that will fail again.
+        await _send_payload_too_large(send, received, TINA4_MAX_UPLOAD_SIZE)
+        return
+
+    body = b"".join(chunks)
+
     # Build request and dispatch
-    request = Request.from_scope(scope, body)
+    try:
+        request = Request.from_scope(scope, body)
+    except PayloadTooLarge:
+        # Still reachable: from_scope also refuses on a DECLARED content-length
+        # over the limit, which the loop above never sees when the client lies
+        # about the length or sends nothing.
+        await _send_payload_too_large(send, received, TINA4_MAX_UPLOAD_SIZE)
+        return
     response = await handle(request)
 
     # Streaming responses bypass ETag/compression — send immediately
@@ -2960,16 +3110,53 @@ def resolve_config(cli_host: str | None = None, cli_port: int | None = None) ->
     else:
         host = os.environ.get("TINA4_HOST") or os.environ.get("HOST", default_host)
 
-    # Port: CLI flag > PORT env > default
+    # Port: CLI flag > TINA4_PORT > PORT (deprecated) > default.
+    #
+    # This used to read PORT and nothing else, so TINA4_PORT - the name the CLI
+    # documents and prefers, and the one every .env sets - was IGNORED on the
+    # one path that binds the socket. An operator setting it saw the server
+    # come up on the default port with no complaint. It cost two benchmark runs
+    # in one afternoon before anyone read this function.
+    #
+    # Bare PORT is deprecated: it is a name anything can set, and a stray
+    # OS-level PORT on a shared runner should never outrank the framework's own
+    # variable. It is still honoured so no deployment breaks, and warns so the
+    # migration actually happens. Removal is 3.14.
     if cli_port is not None:
         port = cli_port
     else:
-        env_port = os.environ.get("PORT")
-        port = int(env_port) if env_port and env_port.isdigit() else default_port
+        tina4_port = os.environ.get("TINA4_PORT")
+        legacy_port = os.environ.get("PORT")
+        if tina4_port and tina4_port.isdigit():
+            port = int(tina4_port)
+        elif legacy_port and legacy_port.isdigit():
+            port = int(legacy_port)
+            _warn_deprecated_port(port)
+        else:
+            port = default_port
 
     return host, port
 
 
+_PORT_DEPRECATION_WARNED = False
+
+
+def _warn_deprecated_port(port: int) -> None:
+    """Warn ONCE that bare PORT was used instead of TINA4_PORT.
+
+    Once, because resolve_config can be called more than once per process and
+    a warning repeated on every call is a warning people filter out.
+    """
+    global _PORT_DEPRECATION_WARNED
+    if _PORT_DEPRECATION_WARNED:
+        return
+    _PORT_DEPRECATION_WARNED = True
+    Log.warning(
+        f"PORT is deprecated and will be removed in 3.14 - use TINA4_PORT "
+        f"instead (binding port {port} from PORT)"
+    )
+
+
 def banner_surface_lines(
     port: int, *, swagger_enabled: bool, dev_admin_enabled: bool
 ) -> tuple[str, str]:

{tina4_python-3.13.95 → tina4_python-3.13.97}/tina4_python/crud/__init__.py

@@ -119,18 +119,17 @@ class AutoCrud:
             records = _cls.all(limit=limit, offset=offset)
             total = _cls.count()
             total_pages = max(1, -(-total // limit)) if limit else 1
-            data = [r.to_dict() for r in records]
+            record_dicts = [record.to_dict() for record in records]
+            # The canonical ADR-0043 envelope: EXACTLY seven snake_case keys, no
+            # duplicate or camelCase spellings, matching DatabaseResult.to_paginate().
             return response({
-                "records": data,       # standard name
-                "data": data,          # backwards compat
-                "count": total,        # standard name
-                "total": total,        # backwards compat
-                "limit": limit,
-                "offset": offset,
-                "page": page,
-                "per_page": limit,     # backwards compat
-                "totalPages": total_pages,   # camelCase standard
-                "total_pages": total_pages,  # backwards compat
+                "records": record_dicts,     # the page rows, verbatim (never re-sliced)
+                "total": total,              # the true COUNT for the filter, NOT rows returned
+                "page": page,                # floor(offset / limit) + 1
+                "per_page": limit,           # the query's limit
+                "total_pages": total_pages,  # ceil(total / per_page)
+                "limit": limit,              # the SQL limit actually applied
+                "offset": offset,            # the SQL offset actually applied
             })
 
         list_handler.__name__ = f"autocrud_list_{table}"

{tina4_python-3.13.95 → tina4_python-3.13.97}/tina4_python/database/adapter.py

@@ -263,71 +263,66 @@ class DatabaseResult:
         rows = [",".join(escape(row.get(c)) for c in columns) for row in self.records]
         return "\n".join([header] + rows)
 
-    def to_paginate(self, page: int = None, per_page: int = None) -> dict:
-        """Paginate this result. Two modes, and the default one is new.
-
-        NO ARGUMENTS: describe the page this result already IS, derived from
-        the query that produced it. This is the mode that was broken.
+    def to_paginate(self, *args, **kwargs) -> dict:
+        """Describe the page this result already IS, as the canonical envelope.
+
+        Takes NO arguments. Every field is derived from the query that
+        produced this result (ADR-0043):
+
+            per_page    = the query's limit
+            page        = floor(offset / limit) + 1
+            total       = the true total for the filter, the COUNT probe that
+                          populates .count, NEVER the number of rows returned
+            total_pages = ceil(total / per_page)
+            records     = the rows the query returned, VERBATIM, never re-sliced
+            limit       = the SQL limit actually applied
+            offset      = the SQL offset actually applied
+
+        The envelope is EXACTLY seven snake_case keys (records, total, page,
+        per_page, total_pages, limit, offset), identical in all four Tina4
+        frameworks. A JSON key is data and does not change spelling by host
+        language, so there is no camelCase and no duplicate spelling: the old
+        ``data``, ``count`` and ``totalPages`` aliases are gone.
+
+        Passing ANY argument RAISES. The method used to accept (page, per_page)
+        and slice the rows in memory (GitHub issue #106), but a DatabaseResult
+        holds no connection, so an argument can only re-slice the rows already
+        in memory and then report total_pages for pages it can never reach --
+        the measured Ruby defect where slicing offset 40 into a 20-row page
+        returned NOTHING while still naming a page and a total. To read a
+        different page, FETCH that page (limit + offset) and call this with no
+        arguments.
 
         MEASURED 2026-08-05 on a real 250-row table read with limit=20
-        offset=40 (page 3 of 13): this reported page 1. It defaulted the page
-        rather than deriving it from the offset, so every offset fetch was
-        mislabelled as the first page while carrying a correct total and a
-        correct total_pages - an envelope that looked authoritative and named
-        the wrong page.
-
-        WITH page/per_page: slice this result in memory, which is what GitHub
-        issue #106 asked for and what tests/test_issue_106.py pins. Valid only
-        when the result holds the WHOLE set. Slicing a result that is already
-        one page of a larger query is refused: the slice is taken from row 0 of
-        what you hold, while the rows themselves start at ``offset``, so the
-        answer is silently wrong. That is not hypothetical - it is exactly the
-        measured Ruby defect, where slicing offset 40 into a 20-row page
-        returned NOTHING and still reported a page number and a total.
-
-        Python and PHP populate ``count`` from a separate COUNT probe, so
-        ``total`` here is the TRUE total for the filter and not the capped read
-        - which is what makes the envelope honest. Ruby and Node still populate
-        it with rows returned; see feature 18.
+        offset=40 (page 3 of 13): the envelope shipped the same integer twice
+        under two spellings (totalPages and total_pages, count and total, data
+        and records) in every API response, so every consumer had to guess
+        which spelling was canonical. That, and the silent in-memory slice, are
+        what this fixes.
         """
-        if (page is not None or per_page is not None) and len(self.records) < self.count:
-            raise ValueError(
-                f"to_paginate(page=..., per_page=...) slices the rows this result holds, "
-                f"but this result holds only {len(self.records)} of {self.count} rows - "
-                "it is a PARTIAL result, so any page past the rows it holds comes back "
-                "empty while total_pages claims it exists. MEASURED on 100,000 rows read "
-                "under the default cap of 100: pages 1-5 of 20 were right and pages 6 "
-                "onward returned NOTHING, with the envelope still reporting 5,000 pages. "
-                "Fetch the page you want instead: fetch(sql, limit=per_page, "
-                "offset=(page - 1) * per_page), then call to_paginate() with no arguments."
+        if args or kwargs:
+            raise TypeError(
+                "to_paginate() takes no arguments -- it describes the page the "
+                "query already returned, derived from the limit and offset that "
+                "ran. It used to accept (page, per_page) and slice in memory, but "
+                "a DatabaseResult holds no connection, so an argument can only "
+                "re-slice the rows already in memory and then report total_pages "
+                "for pages it can never reach. To read a different page, FETCH it: "
+                "fetch(sql, params, limit=per_page, offset=(page - 1) * per_page), "
+                "then call to_paginate() with no arguments. (ADR-0043)"
             )
 
-        if page is None and per_page is None:
-            per_page = self.limit if self.limit and self.limit > 0 else len(self.records)
-            page = (self.offset // per_page) + 1 if per_page > 0 else 1
-            total_pages = max(1, -(-self.count // per_page)) if per_page > 0 else 1
-            return self._paginate_envelope(self.records, page, per_page, self.offset, total_pages)
-
-        page = page or 1
-        per_page = per_page or (self.limit if self.limit and self.limit > 0 else 20)
-        total_pages = max(1, -(-self.count // per_page))
-        offset = (page - 1) * per_page
-        data = self.records[offset:offset + per_page]
-        return self._paginate_envelope(data, page, per_page, offset, total_pages)
-
-    def _paginate_envelope(self, data, page, per_page, offset, total_pages) -> dict:
-        """The one envelope shape, so both modes cannot drift apart."""
+        per_page = self.limit if self.limit and self.limit > 0 else len(self.records)
+        page = (self.offset // per_page) + 1 if per_page > 0 else 1
+        total_pages = max(1, -(-self.count // per_page)) if per_page > 0 else 1
         return {
-            "records": data,        # standard name
-            "data": data,           # backwards compat (PHP/Ruby/Node)
-            "count": self.count,    # standard name
-            "total": self.count,    # backwards compat
-            "limit": per_page,      # standard name
-            "offset": offset,       # standard name
-            "page": page,
-            "per_page": per_page,   # backwards compat
-            "totalPages": total_pages,   # camelCase standard
-            "total_pages": total_pages,  # backwards compat
+            "records": self.records,     # the rows returned, verbatim (never re-sliced)
+            "total": self.count,         # the true COUNT for the filter, not rows returned
+            "page": page,                # floor(offset / limit) + 1
+            "per_page": per_page,        # the query's limit
+            "total_pages": total_pages,  # ceil(total / per_page)
+            "limit": per_page,           # the SQL limit actually applied
+            "offset": self.offset,       # the SQL offset actually applied
         }
 
     def column_info(self) -> list[dict]: