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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.13.16
+Version: 3.13.19
 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.19}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tina4-python"
-version = "3.13.16"
+version = "3.13.19"
 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.19}/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)
@@ -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,852 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.19}/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.19"
 
 # ── 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.19}/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.19}/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.19}/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()