tina4-python 3.13.52__tar.gz → 3.13.53__tar.gz

{tina4_python-3.13.52 → tina4_python-3.13.53}/PKG-INFO

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

{tina4_python-3.13.52 → tina4_python-3.13.53}/pyproject.toml

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

{tina4_python-3.13.52 → tina4_python-3.13.53}/tina4_python/CLAUDE.md

@@ -901,7 +901,9 @@ User.query().where("name = ?", ["Alice"]).to_mongo()
 ```
 
 ### Available field types
-`IntegerField`, `StringField`, `TextField`, `DateTimeField`, `NumericField`, `BlobField`, `BooleanField`, `FloatField`, `ForeignKeyField`
+`IntegerField`, `StringField`, `TextField`, `DateTimeField`, `NumericField`, `BlobField`, `BooleanField`, `FloatField`, `JSONField`, `ForeignKeyField`
+
+`JSONField()` stores a `dict`/`list` as JSON. You work with a plain Python object; the ORM serializes to a JSON string on save and parses it back on load, so `model.field` is always a `dict`/`list`. Engine-aware column: `JSONB` (PostgreSQL), `JSON` (MySQL), `NVARCHAR(MAX)` (MSSQL), `TEXT` (SQLite), `BLOB SUB_TYPE TEXT` (Firebird). Use it for a JSON column inside a relational row; use DocStore for whole-document storage with Mongo-style queries.
 
 Import from `tina4_python` or `tina4_python.orm.fields`.
 

{tina4_python-3.13.52 → tina4_python-3.13.53}/tina4_python/__init__.py

@@ -36,7 +36,7 @@ from tina4_python.database import Database  # noqa: E402, F401
 from tina4_python.orm import (  # noqa: E402, F401
     ORM, bind_database, Field,
     IntegerField, StringField, BooleanField, FloatField,
-    DateTimeField, TextField, BlobField, NumericField,
+    DateTimeField, TextField, BlobField, NumericField, JSONField,
     ForeignKeyField,
     IntField, StrField, BoolField,  # short aliases
     has_many, has_one, belongs_to,  # relationship descriptors

{tina4_python-3.13.52 → tina4_python-3.13.53}/tina4_python/graphql/__init__.py

@@ -382,7 +382,8 @@ class Schema:
                 gql_type = "Float"
             elif ftype == "BooleanField":
                 gql_type = "Boolean"
-            elif ftype in ("StringField", "TextField", "DateTimeField"):
+            elif ftype in ("StringField", "TextField", "DateTimeField", "JSONField"):
+                # JSONField serializes to a JSON string in the GraphQL payload.
                 gql_type = "String"
             else:
                 gql_type = "String"

{tina4_python-3.13.52 → tina4_python-3.13.53}/tina4_python/orm/__init__.py

@@ -19,7 +19,7 @@ Active Record ORM with SQL-first paradigm.
 from tina4_python.orm.fields import (
     Field,
     IntegerField, StringField, BooleanField, FloatField,
-    DateTimeField, TextField, BlobField, NumericField,
+    DateTimeField, TextField, BlobField, NumericField, JSONField,
     ForeignKeyField,
     IntField, StrField, BoolField,  # short aliases
     has_many, has_one, belongs_to,  # relationship descriptors
@@ -31,7 +31,7 @@ __all__ = [
     "Field",
     # Verbose (preferred)
     "IntegerField", "StringField", "BooleanField", "FloatField",
-    "DateTimeField", "TextField", "BlobField", "NumericField",
+    "DateTimeField", "TextField", "BlobField", "NumericField", "JSONField",
     "ForeignKeyField",
     # Short aliases (backwards compat)
     "IntField", "StrField", "BoolField",

{tina4_python-3.13.52 → tina4_python-3.13.53}/tina4_python/orm/fields.py

@@ -9,6 +9,8 @@ Fields define column types, constraints, and defaults for ORM models.
         role = Field(str, choices=["admin", "user", "guest"])
         active = Field(bool, default=True)
 """
+import copy as _copy
+import json as _json
 import re as _re
 from datetime import datetime
 
@@ -165,6 +167,16 @@ class Field:
 
         return value
 
+    def to_db(self, value):
+        """Serialize an in-memory value to the form the driver should store.
+
+        Identity by default — the value already round-trips through the driver
+        as-is. Overridden by fields whose Python representation differs from
+        their column representation (e.g. ``JSONField`` stores a JSON string).
+        Called by ``ORM.save()`` when building the row for INSERT/UPDATE.
+        """
+        return value
+
     def __repr__(self):
         parts = [self.field_type.__name__]
         if self.primary_key:
@@ -212,6 +224,80 @@ def BlobField(**kwargs):
 def NumericField(**kwargs):
     return _make_field(float, "NumericField", **kwargs)
 
+class JSONField(Field):
+    """A column that stores a JSON document (a ``dict`` or a ``list``).
+
+    You work with a plain Python ``dict``/``list``; the ORM serializes it to a
+    JSON string on save and parses it back on load. The column DDL is
+    engine-aware (see :meth:`ORM.create_table`): ``JSONB`` on PostgreSQL,
+    ``JSON`` on MySQL, ``NVARCHAR(MAX)`` on MSSQL, ``TEXT`` on SQLite/ODBC,
+    ``BLOB SUB_TYPE TEXT`` on Firebird.
+
+    Read normalization: a native-JSON driver (PostgreSQL JSONB, MySQL JSON) may
+    hand back an already-parsed object, while a string-backed engine (SQLite)
+    hands back a JSON string. :meth:`validate` normalizes both to a Python
+    object, so ``model.data`` is always a ``dict``/``list`` regardless of engine.
+
+    Usage::
+
+        class Event(ORM):
+            id      = IntegerField(primary_key=True, auto_increment=True)
+            payload = JSONField()
+
+        Event({"payload": {"type": "click", "tags": ["a", "b"]}}).save()
+        e = Event.find(1)
+        e.payload["type"]   # "click"  — a real dict, not a string
+    """
+
+    def __init__(self, **kwargs):
+        super().__init__(dict, **kwargs)
+        self.kind = "JSONField"
+
+    def _resolve_default(self):
+        # Deep-copy a mutable JSON default (``default={}`` / ``default=[]``) so
+        # separate instances never alias the same object — the classic
+        # shared-default footgun. This runs on BOTH the __init__ default path
+        # (which calls _resolve_default directly) and the validate() None path.
+        d = super()._resolve_default()
+        return _copy.deepcopy(d) if isinstance(d, (dict, list)) else d
+
+    def validate(self, value):
+        # None -> required check + default (mirrors base Field).
+        if value is None:
+            if self.required and self.default is None:
+                raise ValueError(f"Field '{self.name}' is required")
+            return self._resolve_default()
+
+        # A driver returns a JSON string (SQLite/TEXT) or an already-parsed
+        # dict/list (PostgreSQL JSONB, MySQL JSON). Normalize to a Python object.
+        if isinstance(value, (bytes, bytearray)):
+            value = value.decode("utf-8")
+        if isinstance(value, str):
+            try:
+                value = _json.loads(value)
+            except (ValueError, TypeError) as e:
+                raise ValueError(f"Field '{self.name}': value is not valid JSON") from e
+        if not isinstance(value, (dict, list)):
+            raise ValueError(
+                f"Field '{self.name}': expected a dict or list, got {type(value).__name__}"
+            )
+        if self.validator is not None:
+            self.validator(value)
+        return value
+
+    def to_db(self, value):
+        # Serialize to a JSON string for the driver. A TEXT column stores it
+        # verbatim; a native JSON column (JSONB/JSON) casts the string literal.
+        if value is None:
+            return None
+        if isinstance(value, str):
+            return value  # already serialized (defensive)
+        try:
+            return _json.dumps(value)
+        except (TypeError, ValueError) as e:
+            raise ValueError(f"Field '{self.name}': value is not JSON-serializable") from e
+
+
 class ForeignKeyField(Field):
     """Integer field that references another model's primary key.
 

{tina4_python-3.13.52 → tina4_python-3.13.53}/tina4_python/orm/model.py

@@ -390,7 +390,9 @@ class ORM(metaclass=ORMMeta):
             if value is not None or not field.auto_increment:
                 # Use field_mapping for the column name, fall back to field.column
                 db_col = self.field_mapping.get(name, field.column)
-                data[db_col] = value
+                # Serialize to the column's storage form: identity for most
+                # fields, JSON string for JSONField (see Field.to_db).
+                data[db_col] = field.to_db(value)
 
         # v3.13.11 (issue #50): pick INSERT vs UPDATE on row existence
         # for non-auto-increment PKs. Auto-increment keeps the legacy
@@ -840,6 +842,23 @@ class ORM(metaclass=ORMMeta):
         else:
             datetime_sql = "DATETIME"
 
+        # JSONField -> the engine's native JSON type where it has one, else a
+        # text column. PostgreSQL JSONB (binary, indexable, canonical form);
+        # MySQL JSON; MSSQL has no JSON type so NVARCHAR(MAX) (its documented
+        # JSON storage); SQLite/ODBC TEXT; Firebird has no TEXT/JSON type so
+        # BLOB SUB_TYPE TEXT. The ORM stores a JSON string in every case, so a
+        # text-backed column round-trips identically to a native one.
+        if engine in ("postgres", "postgresql"):
+            json_sql = "JSONB"
+        elif engine == "mysql":
+            json_sql = "JSON"
+        elif engine == "mssql":
+            json_sql = "NVARCHAR(MAX)"
+        elif engine == "firebird":
+            json_sql = "BLOB SUB_TYPE TEXT"
+        else:
+            json_sql = "TEXT"
+
         # Don't recreate if table already exists
         if db.table_exists(table):
             return True
@@ -866,6 +885,8 @@ class ORM(metaclass=ORMMeta):
                 sql_type = datetime_sql
             elif kind == "BlobField":
                 sql_type = "BLOB"
+            elif kind == "JSONField":
+                sql_type = json_sql
             else:
                 # Fallback based on field_type
                 ft = field_obj.field_type
@@ -886,7 +907,7 @@ class ORM(metaclass=ORMMeta):
                 parts.append("AUTOINCREMENT")
             if field_obj.required and not field_obj.primary_key:
                 parts.append("NOT NULL")
-            if field_obj.default is not None and not field_obj.auto_increment:
+            if field_obj.default is not None and not field_obj.auto_increment and kind != "JSONField":
                 default_val = field_obj.default
                 if isinstance(default_val, str):
                     parts.append(f"DEFAULT '{default_val}'")