tina4-python 3.13.16__tar.gz → 3.13.21__tar.gz

{tina4_python-3.13.16 → tina4_python-3.13.21}/PKG-INFO

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

{tina4_python-3.13.16 → tina4_python-3.13.21}/pyproject.toml

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

{tina4_python-3.13.16 → tina4_python-3.13.21}/tina4_python/CLAUDE.md

@@ -128,13 +128,13 @@ Rules:
 ```python
 # app.py
 from tina4_python.core import run
-from tina4_python.orm import orm_bind
+from tina4_python.orm import bind_database
 from tina4_python.frond import Frond
 from tina4_python.database import Database
 
 # 1. Database & ORM
 db = Database("sqlite:///app.db")
-orm_bind(db)
+bind_database(db)
 
 # 2. Custom Twig filters
 Frond.add_filter("money", lambda v: f"{float(v or 0):,.2f}")
@@ -328,7 +328,7 @@ tina4_python/               # Core framework package (v3.0.0)
 │   ├── connection.py       # Database class (URL-based connection)
 │   ├── adapter.py          # DatabaseAdapter, DatabaseResult, SQLTranslator
 │   ├── sqlite.py, postgres.py, mysql.py, mssql.py, firebird.py, odbc.py
-├── orm/                    # Active Record ORM (ORM, Field, orm_bind)
+├── orm/                    # Active Record ORM (ORM, Field, bind_database)
 │   ├── model.py            # ORM base class
 │   └── fields.py           # IntegerField, StringField, etc.
 ├── frond/                  # Template engine (Frond — Jinja2/Twig-compatible)
@@ -479,6 +479,9 @@ request.session     # Session object — use .get(key) and .set(key, value)
 
 ```python
 return response({"data": []})              # JSON (auto-detected from dict/list)
+return response(User.find(1))              # ORM model -> JSON object
+return response(User.all())                # list of models -> JSON array
+return response(db.fetch("SELECT * FROM users"))  # DatabaseResult -> JSON array
 return response("<h1>Hello</h1>")          # HTML
 return response("Not found", 404)          # With status code
 return response.redirect("/login")         # Redirect
@@ -487,6 +490,8 @@ return response.file("doc.pdf")            # Serve a file
 return response.stream(generator)          # SSE/streaming response (text/event-stream)
 ```
 
+`response()` auto-serializes a domain object — an ORM model, a list of models, or a `DatabaseResult` — to JSON with no manual `to_dict()` / `to_json()`. A single model becomes a JSON object; a list of models or a `DatabaseResult` becomes a JSON array. Dicts, lists and strings behave exactly as before (purely additive).
+
 Add custom headers before returning:
 ```python
 from tina4_python.core.response import Response
@@ -821,19 +826,37 @@ class User(ORM):
     email = StringField()
 ```
 
-Initialize in `app.py`:
+**Binding the database:**
+
+- **`.env` default (no call needed)** — models auto-bind to `TINA4_DATABASE_URL` when it is set, so most apps need no binding call at all.
+- **`bind_database(db)`** — override the default explicitly; assigns the connection to all ORM subclasses that don't select a named one.
+- **`bind_database(db, name="analytics")` + `_db = "analytics"`** — register a named/secondary connection and point a model at it. A missing named connection raises a clear error.
+
 ```python
-from tina4_python.orm import orm_bind
+from tina4_python.orm import bind_database
 from tina4_python.database import Database
 
-orm_bind(Database("sqlite:///app.db"))  # Assigns DB to all ORM subclasses
+# Most apps: nothing to do — the .env default (TINA4_DATABASE_URL) is auto-bound.
+
+# Override the default explicitly:
+bind_database(Database("sqlite:///app.db"))  # Assigns DB to all ORM subclasses
+
+# Register a NAMED connection and point a model at it:
+bind_database(Database("postgres://…/analytics", "u", "p"), name="analytics")
+
+class Visit(ORM):
+    _db = "analytics"   # this model uses the analytics connection
 ```
 
 ### ORM operations
 
+The constructor accepts a dict, a JSON object string, or keyword args. Passing a list/array raises a clear `TypeError` (map over the list to build many records).
+
 ```python
 # Create
-user = User({"name": "Alice", "email": "alice@example.com"})
+user = User({"name": "Alice", "email": "alice@example.com"})    # dict
+user = User('{"name": "Alice", "email": "alice@example.com"}')  # JSON object string
+user = User(name="Alice", email="alice@example.com")            # keyword args
 user.save()
 
 # Load — alias for select_one (class method, returns instance or None)
@@ -1567,7 +1590,7 @@ Key `.env` settings:
 
 ```bash
 # Authentication
-SECRET=your-jwt-secret            # JWT signing (default uses insecure placeholder)
+TINA4_SECRET=your-jwt-secret      # JWT signing (warns + uses a blank, insecure secret if unset)
 TINA4_API_KEY=your-api-key        # Static bearer token for API auth (API_KEY fallback supported)
 TINA4_TOKEN_LIMIT=60              # Token lifetime in minutes (default: 60)
 
@@ -1813,7 +1836,7 @@ async def dashboard(request, response):
 ## v3 Features Summary
 
 - **55 built-in features**, zero third-party dependencies
-- **2,299 tests** passing across all modules
+- **2,857 tests** passing across all modules
 - **Production server auto-detect**: `tina4python serve --production` auto-installs uvicorn
 - **`tina4python generate`**: model, route, migration, middleware scaffolding
 - **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), query caching (`TINA4_DB_CACHE=true`, `cache_stats()`, `cache_clear()`)

{tina4_python-3.13.16 → tina4_python-3.13.21}/tina4_python/__init__.py

@@ -8,7 +8,7 @@ Tina4 Python v3.0 — Zero-dependency, lightweight web framework.
 
 One import, everything works.
 """
-__version__ = "3.13.16"
+__version__ = "3.13.21"
 
 # ── Route decorators ──
 from tina4_python.core.router import (  # noqa: E402, F401
@@ -34,7 +34,7 @@ from tina4_python.database import Database  # noqa: E402, F401
 
 # ── ORM ──
 from tina4_python.orm import (  # noqa: E402, F401
-    ORM, orm_bind, Field,
+    ORM, bind_database, Field,
     IntegerField, StringField, BooleanField, FloatField,
     DateTimeField, TextField, BlobField, NumericField,
     ForeignKeyField,

{tina4_python-3.13.16 → tina4_python-3.13.21}/tina4_python/auth/__init__.py

@@ -29,7 +29,7 @@ import functools
 class _DualMethod:
     """Descriptor that makes a method callable on both the class and an instance.
 
-    - ``Auth.get_token(payload)``  — creates a temporary Auth() using env SECRET
+    - ``Auth.get_token(payload)``  — creates a temporary Auth() using env TINA4_SECRET
     - ``auth.get_token(payload)``  — uses the instance's own secret / settings
     """
 
@@ -42,13 +42,35 @@ class _DualMethod:
             # Called on the class: Auth.get_token(payload, ...)
             @functools.wraps(self._func)
             def _class_call(*args, **kwargs):
-                inst = cls()          # Auth() reads SECRET from env
+                inst = cls()          # Auth() reads TINA4_SECRET from env
                 return self._func(inst, *args, **kwargs)
             return _class_call
         # Called on an instance: auth_instance.get_token(payload, ...)
         return functools.partial(self._func, obj)
 
 
+def _resolve_secret(secret: str = None) -> str:
+    """Resolve the JWT signing secret.
+
+    Reads ``TINA4_SECRET`` from the environment. When neither an explicit
+    secret nor ``TINA4_SECRET`` is set, warns loudly and returns a blank
+    secret — parity with the PHP/Node frameworks. Tina4 never silently signs
+    with a guessable built-in default, which would make tokens forgeable.
+    """
+    if secret:
+        return secret
+    env_secret = os.environ.get("TINA4_SECRET", "")
+    if not env_secret:
+        try:
+            from tina4_python.debug import Log
+            Log.warning("Auth: TINA4_SECRET not set in .env — using blank secret (insecure)")
+        except Exception:
+            import sys
+            print("Auth: TINA4_SECRET not set in .env — using blank secret (insecure)", file=sys.stderr)
+        return ""
+    return env_secret
+
+
 class Auth:
     """JWT authentication and password hashing — zero dependencies."""
 
@@ -56,11 +78,11 @@ class Auth:
                  expires_in: int = None):
         """
         Args:
-            secret:     Signing secret (falls back to SECRET env var).
+            secret:     Signing secret (falls back to the TINA4_SECRET env var).
             algorithm:  JWT algorithm (default HS256).
             expires_in: Token lifetime in seconds (default 3600).
         """
-        self.secret = secret or os.environ.get("TINA4_SECRET", "tina4-default-secret")
+        self.secret = secret if secret is not None else _resolve_secret()
         self.algorithm = algorithm
         # JWT expiry env var:
         # - TINA4_TOKEN_EXPIRES_IN (preferred — matches docs and the
@@ -80,7 +102,7 @@ class Auth:
 
         Args:
             expires_in: Lifetime in minutes (default: self.expires_in).
-            secret:     Override signing secret (default: self.secret / SECRET env var).
+            secret:     Override signing secret (default: self.secret / TINA4_SECRET env var).
 
         Returns: header.payload.signature
         """
@@ -176,36 +198,36 @@ class Auth:
 
     # get_token and valid_token are the primary names
 
-    # ── Class-level convenience methods (read SECRET from env) ────
+    # ── Class-level convenience methods (read TINA4_SECRET from env) ────
 
     @classmethod
     def get_token_static(cls, payload: dict, expires_in: int = 60) -> str:
-        """Create a JWT without instantiating Auth — reads SECRET from env."""
-        secret = os.environ.get("TINA4_SECRET", "tina4-default-secret")
+        """Create a JWT without instantiating Auth — reads TINA4_SECRET from env."""
+        secret = _resolve_secret()
         auth = cls(secret=secret, expires_in=expires_in)
         return auth.get_token(payload)
 
     @classmethod
     def valid_token_static(cls, token: str) -> "dict | None":
-        """Validate a JWT without instantiating Auth — reads SECRET from env.
+        """Validate a JWT without instantiating Auth — reads TINA4_SECRET from env.
 
         Returns the decoded payload on success, ``None`` on failure.
         """
-        secret = os.environ.get("TINA4_SECRET", "tina4-default-secret")
+        secret = _resolve_secret()
         auth = cls(secret=secret)
         return auth.valid_token(token)
 
     @classmethod
     def get_payload_static(cls, token: str) -> dict | None:
         """Decode payload (no validation) without instantiating Auth."""
-        secret = os.environ.get("TINA4_SECRET", "tina4-default-secret")
+        secret = _resolve_secret()
         auth = cls(secret=secret)
         return auth.get_payload(token)
 
     @classmethod
     def refresh_token_static(cls, token: str, expires_in: int = 60) -> str | None:
-        """Refresh a JWT without instantiating Auth — reads SECRET from env."""
-        secret = os.environ.get("TINA4_SECRET", "tina4-default-secret")
+        """Refresh a JWT without instantiating Auth — reads TINA4_SECRET from env."""
+        secret = _resolve_secret()
         auth = cls(secret=secret, expires_in=expires_in)
         return auth.refresh_token(token)
 
@@ -213,10 +235,10 @@ class Auth:
     def authenticate_request_static(cls, headers: dict) -> dict | None:
         """Extract and validate auth from request headers without instantiating Auth.
 
-        Reads SECRET from env. Checks: Bearer JWT, Bearer API key, Basic auth.
+        Reads TINA4_SECRET from env. Checks: Bearer JWT, Bearer API key, Basic auth.
         Returns payload dict on success, None on failure.
         """
-        secret = os.environ.get("TINA4_SECRET", "tina4-default-secret")
+        secret = _resolve_secret()
         auth = cls(secret=secret)
         return auth.authenticate_request(headers)
 
@@ -281,7 +303,7 @@ class Auth:
         """Extract and validate auth from request headers.
 
         Args:
-            secret:    Override signing secret (default: self.secret / SECRET env var).
+            secret:    Override signing secret (default: self.secret / TINA4_SECRET env var).
             algorithm: JWT algorithm override (default: "HS256").
 
         Checks: Bearer JWT, Bearer API key, Basic auth.
@@ -324,14 +346,14 @@ def _b64url_decode(s: str) -> bytes:
 # ── Module-level convenience functions (use static methods) ────
 
 def get_token(payload: dict, expires_in: int = 60, secret: str = None) -> str:
-    """Create a JWT — reads SECRET from env. Shortcut for Auth.get_token_static()."""
+    """Create a JWT — reads TINA4_SECRET from env. Shortcut for Auth.get_token_static()."""
     if secret is not None:
         return Auth(secret=secret).get_token(payload, expires_in=expires_in)
     return Auth.get_token_static(payload, expires_in=expires_in)
 
 
 def valid_token(token: str) -> "dict | None":
-    """Validate a JWT signature and expiry — reads SECRET from env.
+    """Validate a JWT signature and expiry — reads TINA4_SECRET from env.
 
     Returns the decoded payload dict on success, ``None`` on failure.
     The truthy/falsy split keeps legacy ``if valid_token(t):`` code working
@@ -346,12 +368,12 @@ def get_payload(token: str) -> dict | None:
 
 
 def refresh_token(token: str, expires_in: int = 60) -> str | None:
-    """Refresh a JWT — reads SECRET from env. Shortcut for Auth.refresh_token_static()."""
+    """Refresh a JWT — reads TINA4_SECRET from env. Shortcut for Auth.refresh_token_static()."""
     return Auth.refresh_token_static(token, expires_in=expires_in)
 
 
 def authenticate_request(headers: dict, secret: str = None, algorithm: str = "HS256") -> dict | None:
-    """Validate auth from request headers — reads SECRET from env."""
+    """Validate auth from request headers — reads TINA4_SECRET from env."""
     if secret is not None:
         return Auth(secret=secret).authenticate_request(headers, algorithm=algorithm)
     return Auth.authenticate_request_static(headers)

{tina4_python-3.13.16 → tina4_python-3.13.21}/tina4_python/core/middleware.py

@@ -286,8 +286,8 @@ class CsrfMiddleware:
         if auth_header.startswith("Bearer "):
             bearer_token = auth_header[7:].strip()
             if bearer_token:
-                from tina4_python.auth import Auth as _CsrfAuth
-                secret = os.environ.get("TINA4_SECRET", "tina4-default-secret")
+                from tina4_python.auth import Auth as _CsrfAuth, _resolve_secret
+                secret = _resolve_secret()
                 auth = _CsrfAuth(secret=secret)
                 if auth.valid_token(bearer_token):
                     return request, response
@@ -325,8 +325,8 @@ class CsrfMiddleware:
             )
 
         # Validate the token
-        from tina4_python.auth import Auth as _CsrfAuth
-        secret = os.environ.get("TINA4_SECRET", "tina4-default-secret")
+        from tina4_python.auth import Auth as _CsrfAuth, _resolve_secret
+        secret = _resolve_secret()
         auth = _CsrfAuth(secret=secret)
         if not auth.valid_token(token):
             return request, response.error(

{tina4_python-3.13.16 → tina4_python-3.13.21}/tina4_python/core/response.py

@@ -70,6 +70,34 @@ def set_frond(engine):
     _global_frond = engine
 
 
+def _to_jsonable(data):
+    """Normalise domain objects into JSON-serialisable structures.
+
+    Lets a route hand domain objects straight to ``response(...)`` /
+    ``response.json(...)`` without calling ``.to_dict()``/``.to_json()`` by hand:
+
+        return response(user)            # ORM model       -> dict
+        return response(User.all())      # list[ORM]        -> list[dict]
+        return response(db.fetch(sql))   # DatabaseResult   -> list[dict]
+
+    Plain ``dict`` / ``str`` / ``bytes`` / ``None`` pass through unchanged, so
+    existing handlers behave exactly as before.
+    """
+    if data is None or isinstance(data, (dict, str, bytes)):
+        return data
+    # Query result (DatabaseResult): exposes both a ``records`` list and a
+    # ``to_array`` method — the pair distinguishes it from a plain {"records": …} dict.
+    if isinstance(getattr(data, "records", None), list) and callable(getattr(data, "to_array", None)):
+        return data.records
+    # ORM model: duck-typed on a callable ``to_dict``.
+    if callable(getattr(data, "to_dict", None)):
+        return data.to_dict()
+    # Collections: normalise each element (list of models -> list of dicts).
+    if isinstance(data, (list, tuple)):
+        return [_to_jsonable(item) for item in data]
+    return data
+
+
 class Response:
     """HTTP response builder with compression and ETag support."""
 
@@ -107,6 +135,10 @@ class Response:
             for k, v in headers.items():
                 self._headers.append((k, v))
 
+        # Normalise ORM models / collections / query results so handlers can
+        # `return response(model)` without serialising by hand.
+        data = _to_jsonable(data)
+
         if content_type:
             # Explicit content type provided
             self.content_type = content_type
@@ -232,7 +264,7 @@ class Response:
         if status_code:
             self.status_code = status_code
         self.content_type = "application/json"
-        self.content = json.dumps(data, default=str, separators=(",", ":")).encode()
+        self.content = json.dumps(_to_jsonable(data), default=str, separators=(",", ":")).encode()
         return self
 
     def html(self, content: str, status_code: int = None) -> "Response":

{tina4_python-3.13.16 → tina4_python-3.13.21}/tina4_python/frond/engine.py

@@ -15,7 +15,7 @@ from functools import lru_cache
 from pathlib import Path
 from datetime import datetime
 
-from tina4_python.auth import Auth as _FrondAuth
+from tina4_python.auth import Auth as _FrondAuth, _resolve_secret
 
 
 class SafeString(str):
@@ -1173,7 +1173,7 @@ def _generate_form_jwt(descriptor: str = "", session_id: str = "") -> str:
     if sid:
         payload["session_id"] = sid
 
-    secret = os.environ.get("TINA4_SECRET", "tina4-default-secret")
+    secret = _resolve_secret()
     ttl = int(os.environ.get("TINA4_TOKEN_EXPIRES_IN", "60"))
     auth = _FrondAuth(secret=secret, expires_in=ttl)
     return auth.get_token(payload)

{tina4_python-3.13.16 → tina4_python-3.13.21}/tina4_python/orm/__init__.py

@@ -24,10 +24,10 @@ from tina4_python.orm.fields import (
     IntField, StrField, BoolField,  # short aliases
     has_many, has_one, belongs_to,  # relationship descriptors
 )
-from tina4_python.orm.model import ORM, orm_bind
+from tina4_python.orm.model import ORM, bind_database
 
 __all__ = [
-    "ORM", "orm_bind",
+    "ORM", "bind_database",
     "Field",
     # Verbose (preferred)
     "IntegerField", "StringField", "BooleanField", "FloatField",

{tina4_python-3.13.16 → tina4_python-3.13.21}/tina4_python/orm/model.py

@@ -17,13 +17,13 @@ from tina4_python.core.cache import Cache
 # Module-level query cache — shared across all ORM models
 _query_cache = Cache(default_ttl=0, max_size=500)
 
-# Global database reference — set via orm_bind()
+# Global database reference — set via bind_database()
 _database = None
 # Named database connections registry
 _databases: dict[str, object] = {}
 
 
-def orm_bind(db, name: str = None):
+def bind_database(db, name: str = None):
     """Bind a Database instance to ORM models.
 
     Args:
@@ -32,11 +32,11 @@ def orm_bind(db, name: str = None):
               If None, sets the global default used by all models without _db.
 
     Usage:
-        orm_bind(db_main)                    # default for all models
-        orm_bind(db_audit, name="audit")     # named connection
+        bind_database(db_main)                    # default for all models
+        bind_database(db_audit, name="audit")     # named connection
 
         # Decorator style — class is returned unchanged:
-        @orm_bind(db)
+        @bind_database(db)
         class User(ORM):
             ...
 
@@ -49,7 +49,7 @@ def orm_bind(db, name: str = None):
     else:
         _databases[name] = db
 
-    # Return a pass-through decorator so @orm_bind(db) syntax works.
+    # Return a pass-through decorator so @bind_database(db) syntax works.
     # Without this the decorator would set the class to None.
     def _decorator(cls):
         return cls
@@ -191,6 +191,16 @@ class ORM(metaclass=ORMMeta):
             import json
             data = json.loads(data)
 
+        # A single model is one record — reject a list/array with a clear
+        # message instead of a cryptic "'list' object has no attribute 'items'".
+        if data is not None and not isinstance(data, dict):
+            raise TypeError(
+                f"{type(self).__name__}() expects a dict, a JSON object string, or "
+                f"keyword args for one record — got {type(data).__name__}. To build "
+                f"many records, map over the list: "
+                f"[{type(self).__name__}(row) for row in rows]."
+            )
+
         # Populate from dict or kwargs
         if data:
             self._populate(data)
@@ -269,7 +279,7 @@ class ORM(metaclass=ORMMeta):
         Resolution order:
         1. cls._db as a Database instance (direct assignment)
         2. cls._db as a string name → look up in _databases registry
-        3. Global _database (set via orm_bind(db))
+        3. Global _database (set via bind_database(db))
         """
         if cls._db is not None:
             if isinstance(cls._db, str):
@@ -277,7 +287,7 @@ class ORM(metaclass=ORMMeta):
                 if db is None:
                     raise RuntimeError(
                         f"Named database '{cls._db}' not found. "
-                        f"Call orm_bind(db, name='{cls._db}') first."
+                        f"Call bind_database(db, name='{cls._db}') first."
                     )
                 return db
             return cls._db  # Direct Database instance
@@ -291,10 +301,10 @@ class ORM(metaclass=ORMMeta):
                 username = os.environ.get("TINA4_DATABASE_USERNAME", "")
                 password = os.environ.get("TINA4_DATABASE_PASSWORD", "")
                 db = Database(url, username, password)
-                orm_bind(db)
+                bind_database(db)
                 return db
             raise RuntimeError(
-                "No database bound. Call orm_bind(db) or set TINA4_DATABASE_URL in .env"
+                "No database bound. Call bind_database(db) or set TINA4_DATABASE_URL in .env"
             )
         return _database
 
@@ -890,7 +900,7 @@ class ORM(metaclass=ORMMeta):
         Resolution order matches _get_db():
         1. cls._db as a Database instance
         2. cls._db as a named string → registry lookup
-        3. Global default set via orm_bind()
+        3. Global default set via bind_database()
         """
         return cls._get_db()