tina4-python 3.13.103__tar.gz → 3.13.104__tar.gz

{tina4_python-3.13.103 → tina4_python-3.13.104}/PKG-INFO

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

{tina4_python-3.13.103 → tina4_python-3.13.104}/pyproject.toml

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

{tina4_python-3.13.103 → tina4_python-3.13.104}/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.103"
+    return "3.13.104"
 
 
 __version__ = _resolve_version()
@@ -108,6 +108,9 @@ _LAZY: dict[str, tuple[str, str]] = {
     "NumericField": ("tina4_python.orm", "NumericField"),
     "DecimalField": ("tina4_python.orm", "DecimalField"),
     "JSONField": ("tina4_python.orm", "JSONField"),
+    "PointField": ("tina4_python.orm", "PointField"),
+    "Point": ("tina4_python.orm", "Point"),
+    "feature_collection": ("tina4_python.orm", "feature_collection"),
     "ForeignKeyField": ("tina4_python.orm", "ForeignKeyField"),
     "IntField": ("tina4_python.orm", "IntField"),
     "StrField": ("tina4_python.orm", "StrField"),
@@ -141,6 +144,10 @@ _LAZY: dict[str, tuple[str, str]] = {
     "AiHTTPError": ("tina4_python.ai", "AiHTTPError"),
     "AiTimeoutError": ("tina4_python.ai", "AiTimeoutError"),
     "AiParseError": ("tina4_python.ai", "AiParseError"),
+    # Provider-neutral OpenID Connect SSO (ADR-0056)
+    "Sso": ("tina4_python.sso", "Sso"),
+    "SSO": ("tina4_python.sso", "SSO"),
+    "SsoError": ("tina4_python.sso", "SsoError"),
     # SOAP / WSDL
     "WSDL": ("tina4_python.wsdl", "WSDL"),
     "wsdl_operation": ("tina4_python.wsdl", "wsdl_operation"),

{tina4_python-3.13.103 → tina4_python-3.13.104}/tina4_python/core/server.py

@@ -1691,8 +1691,16 @@ def _check_auth(request: Request, response: Response, route: dict) -> bool:
     if not _auth_ok:
         _session = getattr(request, "session", None)
         if _session:
+            # A provider-verified OIDC identity is handed into the SAME auth
+            # gate as JWT. Provider credentials stay in the reserved Session
+            # value and never enter request.user.
+            _sso = _session.get("_tina4_sso")
+            _sso_identity = _sso.get("identity") if isinstance(_sso, dict) else None
+            if isinstance(_sso_identity, dict) and _sso_identity.get("issuer") and _sso_identity.get("subject"):
+                _auth_ok = True
+                request.user = _sso_identity
             _session_token = _session.get("token") if _session else ""
-            if _session_token:
+            if not _auth_ok and _session_token:
                 try:
                     from tina4_python.auth import Auth
                     _payload = Auth.valid_token_static(_session_token)
@@ -3669,6 +3677,10 @@ def run(host: str | None = None, port: int | None = None, no_browser: bool = Fal
 
     # Auto-discover routes
     _auto_discover("src")
+    # Configuration-first OIDC: canonical routes appear only when configured,
+    # after app discovery so collisions fail loudly rather than overwrite.
+    from tina4_python.sso import Sso as _Sso
+    _Sso.mount_configured()
     route_count = len(Router.get_routes())
     Log.info(f"Discovered {route_count} routes")
 

{tina4_python-3.13.103 → tina4_python-3.13.104}/tina4_python/database/__init__.py

@@ -11,7 +11,11 @@ SQL-first database layer. One interface, many drivers.
     row = db.fetch_one("SELECT * FROM users WHERE id = ?", [42])
     db.execute("INSERT INTO users (name) VALUES (?)", ["Alice"])
 """
-from tina4_python.database.adapter import DatabaseAdapter, DatabaseResult, SQLTranslator
+from tina4_python.database.adapter import DatabaseAdapter, DatabaseResult
+from tina4_python.database.sql_translator import SQLTranslator, SpatialNotSupportedError
 from tina4_python.database.connection import Database
 
-__all__ = ["Database", "DatabaseAdapter", "DatabaseResult", "SQLTranslator"]
+__all__ = [
+    "Database", "DatabaseAdapter", "DatabaseResult", "SQLTranslator",
+    "SpatialNotSupportedError",
+]

{tina4_python-3.13.103 → tina4_python-3.13.104}/tina4_python/database/adapter.py

@@ -1131,9 +1131,10 @@ class SqlCrudMixin:
 # ── SQL Translation Rules ──────────────────────────────────────
 # Reusable translation functions for common cross-engine quirks.
 
-
 # SQLTranslator moved to sql_translator.py (feature 3: the adapter module is the
 # adapter contract and nothing else). Re-exported here because the sqlite,
 # firebird, mssql and odbc adapters import it from this module, and a file move
 # is not the place to churn their imports.
-from tina4_python.database.sql_translator import SQLTranslator  # noqa: E402,F401
+from tina4_python.database.sql_translator import (  # noqa: E402,F401
+    SQLTranslator, SpatialNotSupportedError,
+)

{tina4_python-3.13.103 → tina4_python-3.13.104}/tina4_python/database/sql_translator.py

@@ -16,6 +16,10 @@ by engine; moving it here would flatten that override.
 import re
 
 
+class SpatialNotSupportedError(NotImplementedError):
+    """The selected database engine cannot honor the GIS contract."""
+
+
 class SQLTranslator:
     """Cross-engine SQL translator.
 
@@ -23,6 +27,124 @@ class SQLTranslator:
     and stateless — just string transforms.
     """
 
+    SPATIAL_ENGINES = ("postgres", "postgresql")
+    _IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$")
+
+    @classmethod
+    def supports_spatial(cls, engine: str) -> bool:
+        """Return whether Tina4 has a spatial provider for ``engine``."""
+        name = (engine or "").lower()
+        name = cls.ENGINE_ALIASES.get(name, name)
+        return name in cls.SPATIAL_ENGINES
+
+    @classmethod
+    def require_spatial(cls, engine: str, feature: str) -> str:
+        """Return the normalized spatial engine or fail with an actionable error."""
+        name = (engine or "unknown").lower()
+        name = cls.ENGINE_ALIASES.get(name, name)
+        if cls.supports_spatial(name):
+            return name
+        raise SpatialNotSupportedError(
+            f"{feature} is not supported on the '{name}' database engine. "
+            "Tina4 GIS support is PostGIS-first: use PostgreSQL with the "
+            "PostGIS extension (CREATE EXTENSION postgis). Tina4 will not "
+            "replace a spatial query with an approximate latitude/longitude query. "
+            "If the application needs storage only and no GIS behavior, declare "
+            "separate longitude and latitude FloatField columns instead."
+        )
+
+    @classmethod
+    def identifier(cls, name: str, what: str = "column") -> str:
+        """Validate an identifier before placing it in spatial SQL."""
+        if not isinstance(name, str) or not cls._IDENTIFIER.fullmatch(name):
+            raise ValueError(
+                f"Spatial {what} name {name!r} is not a valid SQL identifier"
+            )
+        return name
+
+    @staticmethod
+    def _srid(srid) -> int:
+        """Coerce the interpolated SRID to an integer."""
+        if isinstance(srid, bool):
+            raise ValueError(f"Spatial SRID must be an integer, got {srid!r}")
+        try:
+            value = int(srid)
+        except (TypeError, ValueError) as error:
+            raise ValueError(f"Spatial SRID must be an integer, got {srid!r}") from error
+        if value <= 0:
+            raise ValueError(f"Spatial SRID must be positive, got {value}")
+        return value
+
+    @classmethod
+    def point_column_type(cls, engine: str, srid: int = 4326) -> str:
+        """Return PostGIS geography Point DDL."""
+        cls.require_spatial(engine, "PointField")
+        return f"geography(Point,{cls._srid(srid)})"
+
+    @classmethod
+    def spatial_index(cls, engine: str, table: str, column: str) -> str:
+        """Return idempotent PostGIS GiST-index DDL."""
+        cls.require_spatial(engine, "spatial index creation")
+        table = cls.identifier(table, "table")
+        column = cls.identifier(column)
+        index = f"{table.replace('.', '_')}_{column}_gist"
+        return f"CREATE INDEX IF NOT EXISTS {index} ON {table} USING GIST ({column})"
+
+    @classmethod
+    def point_literal(cls, engine: str, srid: int = 4326) -> str:
+        """Return a bound PostGIS point expression in longitude/latitude order."""
+        cls.require_spatial(engine, "spatial predicates")
+        return f"ST_SetSRID(ST_MakePoint(?, ?), {cls._srid(srid)})::geography"
+
+    @classmethod
+    def within_distance(cls, engine: str, column: str, srid: int = 4326) -> str:
+        """Return a bound radius predicate whose distance uses metres."""
+        cls.require_spatial(engine, "within_distance()")
+        column = cls.identifier(column)
+        return f"ST_DWithin({column}, {cls.point_literal(engine, srid)}, ?)"
+
+    @classmethod
+    def distance(cls, engine: str, column: str, srid: int = 4326) -> str:
+        """Return a bound spheroid-distance expression in metres."""
+        cls.require_spatial(engine, "order_by_distance()")
+        column = cls.identifier(column)
+        return f"ST_Distance({column}, {cls.point_literal(engine, srid)})"
+
+    @classmethod
+    def distance_as(cls, engine: str, column: str, alias: str, srid: int = 4326) -> str:
+        """Return an aliased bound distance expression for a SELECT list."""
+        alias = cls.identifier(alias, "result alias")
+        return f"{cls.distance(engine, column, srid)} AS {alias}"
+
+    @classmethod
+    def geometry_literal(cls, engine: str, form: str = "ewkt", srid: int = 4326) -> str:
+        """Return a one-parameter PostGIS geometry expression."""
+        cls.require_spatial(engine, "spatial predicates")
+        if form == "ewkt":
+            return "ST_GeogFromText(?)"
+        if form == "geojson":
+            return f"ST_SetSRID(ST_GeomFromGeoJSON(?), {cls._srid(srid)})::geography"
+        raise ValueError(
+            f"Spatial geometry form {form!r} is not supported; use 'ewkt' or 'geojson'"
+        )
+
+    @classmethod
+    def intersects(cls, engine: str, column: str, form: str = "ewkt",
+                   srid: int = 4326) -> str:
+        """Return a bound PostGIS intersection predicate."""
+        column = cls.identifier(column)
+        return f"ST_Intersects({column}, {cls.geometry_literal(engine, form, srid)})"
+
+    @classmethod
+    def bbox(cls, engine: str, column: str, srid: int = 4326) -> str:
+        """Return a bound PostGIS bounding-box predicate."""
+        cls.require_spatial(engine, "bbox()")
+        column = cls.identifier(column)
+        return (
+            f"ST_Intersects({column}, "
+            f"ST_MakeEnvelope(?, ?, ?, ?, {cls._srid(srid)})::geography)"
+        )
+
     @staticmethod
     def limit_to_rows(sql: str) -> str:
         """Convert LIMIT/OFFSET to Firebird ROWS...TO syntax.

{tina4_python-3.13.103 → tina4_python-3.13.104}/tina4_python/orm/__init__.py

@@ -20,11 +20,12 @@ from tina4_python.orm.fields import (
     Field,
     IntegerField, StringField, BooleanField, FloatField,
     DateTimeField, TextField, BlobField, NumericField, DecimalField, JSONField,
-    ForeignKeyField,
+    PointField, ForeignKeyField,
     IntField, StrField, BoolField,  # short aliases
     has_many, has_one, belongs_to,  # relationship descriptors
 )
-from tina4_python.orm.model import ORM, bind_database
+from tina4_python.orm.point import Point
+from tina4_python.orm.model import ORM, bind_database, feature_collection
 
 __all__ = [
     "ORM", "bind_database",
@@ -32,9 +33,11 @@ __all__ = [
     # Verbose (preferred)
     "IntegerField", "StringField", "BooleanField", "FloatField",
     "DateTimeField", "TextField", "BlobField", "NumericField", "DecimalField", "JSONField",
-    "ForeignKeyField",
+    "PointField", "ForeignKeyField",
     # Short aliases (backwards compat)
     "IntField", "StrField", "BoolField",
     # Relationships
     "has_many", "has_one", "belongs_to",
+    # Spatial
+    "Point", "feature_collection",
 ]

{tina4_python-3.13.103 → tina4_python-3.13.104}/tina4_python/orm/fields.py

@@ -422,6 +422,131 @@ class JSONField(Field):
             raise ValueError(f"Field '{self.name}': value is not JSON-serializable") from e
 
 
+class PointField(Field):
+    """A column that stores a single geographic point, SRID-aware.
+
+    You work with a :class:`~tina4_python.orm.point.Point` value object; the ORM
+    writes EWKT on save and parses the engine's (HEX)EWKB back into a ``Point``
+    on load, so ``model.location.lat`` always works regardless of engine wire
+    format.
+
+    Assignment accepts any of these and normalises to ``Point``::
+
+        site.location = (18.4241, -33.9249)                            # (lon, lat) tuple
+        site.location = "POINT(18.4241 -33.9249)"                       # WKT
+        site.location = "SRID=4326;POINT(18.4241 -33.9249)"             # EWKT
+        site.location = {"type": "Point", "coordinates": [18.42, -33.9]}  # GeoJSON
+
+    Reading it back gives the value object::
+
+        site.location.lon       # 18.4241
+        site.location.lat       # -33.9249
+        site.location.wkt       # 'POINT(18.4241 -33.9249)'
+        site.location.geojson   # {'type': 'Point', 'coordinates': [18.4241, -33.9249]}
+
+    ``to_dict()`` / ``to_json()`` / ``response()`` emit the GeoJSON form, so a
+    map front end consumes a Tina4 route with no translation layer.
+
+    **Engine support is PostGIS-first and never silently wrong.** The column DDL
+    is ``geography(Point,<srid>)`` on PostgreSQL, and
+    :meth:`~tina4_python.orm.model.ORM.create_table` also creates a GiST index
+    for it. On any engine without spatial support, ``create_table()`` raises
+    :class:`~tina4_python.database.adapter.SpatialNotSupportedError` naming that
+    engine rather than creating a wrong column type.
+
+    Usage::
+
+        class ChargePoint(ORM):
+            id       = IntegerField(primary_key=True, auto_increment=True)
+            name     = StringField()
+            location = PointField()          # geography(Point,4326) + GiST index
+
+        ChargePoint({"name": "V&A", "location": (18.4241, -33.9249)}).save()
+
+        near = ChargePoint.query() \\
+            .within_distance("location", (18.42, -33.92), 5000) \\
+            .order_by_distance("location", (18.42, -33.92)) \\
+            .get()
+
+    Args:
+        srid: Spatial reference id for the column. Defaults to 4326 (WGS 84).
+        spatial_index: Create the engine's spatial index for this column in
+            ``create_table()``. Defaults to True — a radius query without one
+            is a full table scan.
+    """
+
+    def __init__(self, srid: int = None, spatial_index: bool = True, **kwargs):
+        from tina4_python.orm.point import DEFAULT_SRID, Point
+        super().__init__(Point, **kwargs)
+        self.kind = "PointField"
+        self.srid = DEFAULT_SRID if srid is None else int(srid)
+        self.spatial_index = spatial_index
+
+    def _resolve_default(self):
+        # ORM.__init__ seeds attributes straight from _resolve_default (it does
+        # not route through validate), so coerce here too — otherwise a
+        # ``default=(lon, lat)`` would leave ``model.location`` as a raw tuple on
+        # an unsaved instance and ``.lat`` would fail.
+        from tina4_python.orm.point import Point
+
+        default = super()._resolve_default()
+        if default is None:
+            return default
+        return self._parse_point(default)
+
+    def _parse_point(self, value):
+        from tina4_python.orm.point import Point
+
+        try:
+            point = Point.parse(value, self.srid)
+        except ValueError as e:
+            raise ValueError(f"Field '{self.name}': {e}") from e
+        if point.srid != self.srid:
+            raise ValueError(
+                f"Field '{self.name}' expects SRID {self.srid}; received {point.srid}. "
+                "Tina4 never silently reprojects or restamps spatial data."
+            )
+        return point
+
+    def coerce(self, value):
+        """Hydrate/assign through the Point parser, not ``Point(value)``."""
+        return None if value is None else self._parse_point(value)
+
+    def validate(self, value):
+        """Coerce any supported point representation into a ``Point``.
+
+        Runs on BOTH the write path (tuple / WKT / GeoJSON from a route) and the
+        read path (the engine's HEXEWKB), which is what makes the column
+        round-trip identically no matter how it was assigned.
+        """
+        from tina4_python.orm.point import Point
+
+        if value is None:
+            if self.required and self.default is None:
+                raise ValueError(f"Field '{self.name}' is required")
+            default = self._resolve_default()
+            return None if default is None else Point.parse(default, self.srid)
+
+        point = self._parse_point(value)
+
+        if self.validator is not None:
+            self.validator(point)
+        return point
+
+    def to_db(self, value):
+        """Serialise to EWKT — ``SRID=4326;POINT(lon lat)``.
+
+        EWKT carries the SRID with the geometry, so the engine never has to
+        assume one, and it is accepted verbatim by PostGIS geography input. The
+        value is bound as a normal parameter; it is never formatted into SQL.
+        """
+        from tina4_python.orm.point import Point
+
+        if value is None:
+            return None
+        return self._parse_point(value).ewkt
+
+
 class ForeignKeyField(Field):
     """Integer field that references another model's primary key.
 

{tina4_python-3.13.103 → tina4_python-3.13.104}/tina4_python/orm/model.py

@@ -186,6 +186,12 @@ class ORMMeta(type):
 
         namespace["_fields"] = fields
         namespace["_relationships"] = relationships
+        # Spatial (PointField) attribute names, resolved once at class creation.
+        # to_dict() and create_table() branch on this, so a model with no
+        # geometry pays a single falsy check and nothing else.
+        namespace["_spatial_fields"] = tuple(
+            key for key, f in fields.items() if getattr(f, "kind", None) == "PointField"
+        )
         cls = super().__new__(mcs, name, bases, namespace)
 
         # Auto-register for CRUD if flagged
@@ -217,6 +223,9 @@ class ORM(metaclass=ORMMeta):
     auto_crud: bool = False  # Set True to auto-register CRUD routes
     _db: str | object | None = None  # Per-model database override
     _fields: dict[str, Field] = {}
+    # PointField attribute names on this model, filled by ORMMeta. Empty for
+    # every non-spatial model, which is what keeps the spatial branches free.
+    _spatial_fields: tuple[str, ...] = ()
     # Last save() failure cause (validation message or DB error). None when
     # the most recent save() succeeded. Mirrors db.get_error() so a caller
     # that checks ``if not model.save():`` can still recover the real cause
@@ -333,11 +342,18 @@ class ORM(metaclass=ORMMeta):
         Usage:
             results = User.query().where("active = ?", [1]).order_by("name").get()
 
+        The model's primary-key column travels with the builder so
+        ``order_by_distance()`` can break exact distance ties on it — without a
+        tie-break the row order for equidistant rows is engine-defined and
+        pagination can skip or repeat rows.
+
         Returns:
             A QueryBuilder instance bound to this model's table and database.
         """
         from tina4_python.query_builder import QueryBuilder
-        return QueryBuilder.from_table(cls._get_table(), cls._get_db())
+        return QueryBuilder.from_table(
+            cls._get_table(), cls._get_db(), cls._get_pk_column()
+        )
 
     @classmethod
     def _get_table(cls) -> str:
@@ -451,6 +467,17 @@ class ORM(metaclass=ORMMeta):
             params.append(getattr(self, name, None))
         return " AND ".join(clauses), params
 
+    @classmethod
+    def _get_pk_column(cls) -> str:
+        """Database COLUMN name of the primary key (field_mapping aware).
+
+        ``_get_pk()`` returns the attribute name; SQL needs the column it maps
+        to. QueryBuilder uses this as the stable ORDER BY tie-break.
+        """
+        pk = cls._get_pk()
+        field = cls._fields.get(pk)
+        return cls.field_mapping.get(pk, (field.column if field else None) or pk)
+
     # ── CRUD ────────────────────────────────────────────────────
 
     def save(self) -> Self | bool:
@@ -1063,7 +1090,28 @@ class ORM(metaclass=ORMMeta):
                                     is the safer choice on Firebird)
 
         Auto-increment primary keys use engine-appropriate syntax.
-        Returns True on success.
+
+        Returns:
+            True on success, False if the DDL failed (the cause is logged).
+
+        Raises:
+            SpatialNotSupportedError: **narrowed contract — a spatial model on
+                a non-spatial engine RAISES, it does not return False.** Every
+                other failure here is recoverable and reported as ``False``,
+                but there is no safe fallback column type for geometry: a
+                ``TEXT`` stand-in would accept writes, return rows, and be
+                silently wrong for every distance query afterwards. The
+                exception names the engine and the alternative. It is resolved
+                BEFORE the ``table_exists`` short-circuit, so the refusal never
+                depends on whether the table happens to exist yet, and it fires
+                on the engine — not on the field — so a PointField model is
+                portable source that simply cannot be deployed onto an engine
+                that would lie about it.
+
+                Mirrors (PHP / Ruby / Node) must THROW here too. Returning
+                false would collapse "this engine cannot do spatial" into the
+                same signal as "the DDL failed", and the caller would create
+                the table by hand and carry on.
         """
         from tina4_python.database.adapter import SQLTranslator
 
@@ -1116,6 +1164,22 @@ class ORM(metaclass=ORMMeta):
         else:
             json_sql = "TEXT"
 
+        # PointField -> the engine's spatial type via the SQLTranslator dialect
+        # seam (``geography(Point,<srid>)`` on PostGIS). Resolved BEFORE the
+        # table_exists short-circuit so a spatial model on a non-spatial engine
+        # ALWAYS raises SpatialNotSupportedError naming that engine — a wrong
+        # column type is never created, and the error does not depend on whether
+        # the table happens to exist yet. This is the loud-not-silent contract:
+        # unlike the other type mappings there is no safe fallback for geometry.
+        point_sql: dict[str, str] = {}
+        for name, field_obj in cls._fields.items():
+            if getattr(field_obj, "kind", None) != "PointField":
+                continue
+            col_name = cls.field_mapping.get(name, field_obj.column or name)
+            point_sql[col_name] = SQLTranslator.point_column_type(
+                engine, getattr(field_obj, "srid", 4326)
+            )
+
         # Don't recreate if table already exists
         if db.table_exists(table):
             return True
@@ -1151,6 +1215,8 @@ class ORM(metaclass=ORMMeta):
                 sql_type = "BLOB"
             elif kind == "JSONField":
                 sql_type = json_sql
+            elif kind == "PointField":
+                sql_type = point_sql[col_name]
             else:
                 # Fallback based on field_type
                 ft = field_obj.field_type
@@ -1240,6 +1306,16 @@ class ORM(metaclass=ORMMeta):
         # it propagate out of create_table().
         try:
             db.execute(sql)
+            # A spatial predicate without a spatial index is a full table scan,
+            # so the index ships WITH the column rather than as a thing the
+            # developer must remember. IF NOT EXISTS keeps it idempotent.
+            for name, field_obj in cls._fields.items():
+                if getattr(field_obj, "kind", None) != "PointField":
+                    continue
+                if not getattr(field_obj, "spatial_index", True):
+                    continue
+                col_name = cls.field_mapping.get(name, field_obj.column or name)
+                db.execute(SQLTranslator.spatial_index(engine, table, col_name))
             db.commit()
         except Exception as e:
             from tina4_python.debug import Log
@@ -1593,6 +1669,16 @@ class ORM(metaclass=ORMMeta):
         else:
             result = {name: getattr(self, name) for name in self._fields}
 
+        # Spatial fields serialise as GeoJSON geometry, so to_dict() / to_json()
+        # / response() all emit map-ready output from one place. `_spatial_fields`
+        # is empty for every non-spatial model, so this costs one falsy check.
+        if self._spatial_fields:
+            for name in self._spatial_fields:
+                key = snake_to_camel(name) if case == "camel" else name
+                point = result.get(key)
+                if point is not None:
+                    result[key] = point.geojson
+
         if include:
             # Group includes: top-level and nested
             top_level = {}
@@ -1639,6 +1725,57 @@ class ORM(metaclass=ORMMeta):
         """Convert to a list of values (alias for to_array)."""
         return self.to_array()
 
+    def to_feature(self, geometry_field: str = None, include: list[str] = None) -> dict:
+        """Convert to an RFC 7946 GeoJSON ``Feature``.
+
+        The model's point field becomes the feature ``geometry``; every other
+        field becomes a ``properties`` entry, with the primary key also lifted to
+        the feature ``id`` (where GIS clients look for it).
+
+            ChargePoint.find(1).to_feature()
+            # {"type": "Feature", "id": 1,
+            #  "geometry": {"type": "Point", "coordinates": [18.4241, -33.9249]},
+            #  "properties": {"name": "V&A"}}
+
+        Args:
+            geometry_field: Which PointField to use as the geometry. Required
+                only when the model declares more than one.
+            include: Relationships to include in ``properties`` (as for
+                :meth:`to_dict`).
+
+        Raises:
+            ValueError: if the model has no PointField, if ``geometry_field`` is
+                not one, or if it is ambiguous with several point fields.
+        """
+        if not self._spatial_fields:
+            raise ValueError(
+                f"{type(self).__name__}.to_feature(): the model has no PointField, "
+                f"so it has no geometry. Add a PointField, or use to_dict()."
+            )
+        if geometry_field is None:
+            if len(self._spatial_fields) > 1:
+                raise ValueError(
+                    f"{type(self).__name__}.to_feature(): the model has several "
+                    f"point fields {list(self._spatial_fields)} — pass "
+                    f"geometry_field= to choose one."
+                )
+            geometry_field = self._spatial_fields[0]
+        elif geometry_field not in self._spatial_fields:
+            raise ValueError(
+                f"{type(self).__name__}.to_feature(): {geometry_field!r} is not a "
+                f"PointField on this model. Point fields: "
+                f"{list(self._spatial_fields)}."
+            )
+
+        properties = self.to_dict(include=include)
+        geometry = properties.pop(geometry_field, None)
+        feature = {"type": "Feature", "geometry": geometry, "properties": properties}
+        pk = self._get_pk()
+        pk_value = properties.get(pk)
+        if pk_value is not None:
+            feature["id"] = pk_value
+        return feature
+
     def to_json(self, include: list[str] = None) -> str:
         """Convert to JSON string."""
         import json
@@ -1656,3 +1793,59 @@ class ORM(metaclass=ORMMeta):
         pk = self._get_pk()
         pk_val = getattr(self, pk, None)
         return f"<{self.__class__.__name__} {pk}={pk_val}>"
+
+
+def feature_collection(models, geometry_field: str = None, include: list[str] = None) -> dict:
+    """Wrap models with a PointField into an RFC 7946 ``FeatureCollection``.
+
+    This is the shape a map front end (Leaflet, MapLibre, OpenLayers, tina4-js on
+    a map) consumes directly, so a route becomes a one-liner::
+
+        from tina4_python.orm import feature_collection
+
+        @get("/api/charge-points.geojson")
+        async def charge_points(request, response):
+            return response(feature_collection(ChargePoint.all()))
+
+    ``response()`` then serialises the returned dict as JSON exactly as it does
+    any other dict — nothing new on the response path.
+
+    It is deliberately **explicit** rather than an automatic transform of
+    ``response(list_of_models)``: a list of models always serialises to a JSON
+    array, and silently switching that to a FeatureCollection because a field
+    type is present would be exactly the kind of magic Tina4 avoids.
+
+    Args:
+        models: An ORM instance or an iterable of them — e.g. ``Model.all()``,
+            ``Model.where(...)``, ``Model.select(...)``.
+        geometry_field: Which PointField supplies the geometry (only needed when
+            a model declares more than one).
+        include: Relationships to include in each feature's ``properties``.
+
+    Returns:
+        ``{"type": "FeatureCollection", "features": [...]}`` — an empty
+        ``features`` list for empty input, never None.
+
+    Raises:
+        TypeError: naming what it got, if any element is not an ORM model
+            (``QueryBuilder.get()`` returns raw row dicts, which carry no field
+            definitions and therefore no geometry — use ``Model.where()`` /
+            ``Model.select()`` for GeoJSON output).
+    """
+    if models is None:
+        rows = []
+    elif isinstance(models, ORM):
+        rows = [models]
+    else:
+        rows = models
+    features = []
+    for row in rows:
+        if not isinstance(row, ORM):
+            raise TypeError(
+                f"feature_collection(): expected ORM model instances, got "
+                f"{type(row).__name__}. Pass Model.all() / Model.where(...) / a "
+                f"list of models — a raw row dict has no field definitions, so "
+                f"there is no geometry field to find."
+            )
+        features.append(row.to_feature(geometry_field=geometry_field, include=include))
+    return {"type": "FeatureCollection", "features": features}