python-flashapi 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

flashapi/core/__init__.py

@@ -1,3 +1,11 @@
-from flashapi.core.schema import Model, ModelSchema, FieldSchema, FieldType, RelationSchema
-
-__all__ = ["Model", "ModelSchema", "FieldSchema", "FieldType", "RelationSchema"]
+from flashapi.core.schema import (
+    FieldSchema,
+    FieldType,
+    FlashAPIConfigError,
+    Model,
+    ModelSchema,
+    RelationSchema,
+    validate_soft_delete,
+)
+
+__all__ = ["FieldSchema", "FieldType", "FlashAPIConfigError", "Model", "ModelSchema", "RelationSchema", "validate_soft_delete"]

flashapi/core/custom_routes.py

@@ -14,7 +14,6 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Any
 
-
 TYPE_MAP = {
     "string": {"type": "string"},
     "str": {"type": "string"},
@@ -51,6 +50,7 @@ def api_doc(
         body_required: List of required field names in body.
         params: Query parameters as {name: type}.
         response: Response schema (raw OpenAPI schema dict).
+
     """
     def decorator(func):
         func._flashapi_doc = {
@@ -83,13 +83,13 @@ def _build_openapi_operation(doc: dict, method: str) -> dict[str, Any]:
         "tags": [doc["tag"]],
         "summary": doc["summary"] or f"{method.upper()} endpoint",
         "responses": {
-            "200": {"description": "Success"}
+            "200": {"description": "Success"},
         },
     }
 
     if doc.get("response"):
         operation["responses"]["200"]["content"] = {
-            "application/json": {"schema": doc["response"]}
+            "application/json": {"schema": doc["response"]},
         }
 
     if doc.get("params"):
@@ -224,13 +224,13 @@ def custom_routes_to_openapi_paths(routes: list[CustomRoute], trailing_slash: bo
             "tags": [route.tag],
             "summary": route.summary or f"{route.method.upper()} {route.path}",
             "responses": {
-                "200": {"description": route.response_description}
+                "200": {"description": route.response_description},
             },
         }
 
         if route.response_schema:
             operation["responses"]["200"]["content"] = {
-                "application/json": {"schema": route.response_schema}
+                "application/json": {"schema": route.response_schema},
             }
 
         if route.parameters:

flashapi/core/pluralize.py

@@ -1,80 +1,80 @@
-"""Pluralization rules supporting English and French model names.
-
-Strategy:
-- Irregulars dict handles all known exceptions for both languages.
-- Rules are ordered to avoid cross-language conflicts.
-- For genuinely ambiguous cases, users can override via Model(plural=...).
-"""
-
-IRREGULARS = {
-    # English irregulars
-    "person": "people",
-    "child": "children",
-    "mouse": "mice",
-    "goose": "geese",
-    "man": "men",
-    "woman": "women",
-    "tooth": "teeth",
-    "foot": "feet",
-    "datum": "data",
-    "index": "indices",
-    "leaf": "leaves",
-    "knife": "knives",
-    "wife": "wives",
-    "life": "lives",
-    "shelf": "shelves",
-    "self": "selves",
-    "half": "halves",
-    "wolf": "wolves",
-    # English words ending in -s/-x/-z that take -es (not invariable)
-    "bus": "buses",
-    "box": "boxes",
-    "fox": "foxes",
-    "buzz": "buzzes",
-    "quiz": "quizzes",
-    "fez": "fezzes",
-    # French irregulars
-    "travail": "travaux",
-    "journal": "journaux",
-    "oeil": "yeux",
-    "monsieur": "messieurs",
-    "madame": "mesdames",
-}
-
-
-def pluralize(word: str) -> str:
-    lower = word.lower()
-
-    if lower in IRREGULARS:
-        return IRREGULARS[lower]
-
-    # --- English: -ss, -sh, -ch → +es (must check before -s invariable rule) ---
-    # en: class→classes, dish→dishes, match→matches
-    if lower.endswith(("ss", "sh", "ch")):
-        return lower + "es"
-
-    # --- Invariable endings (both languages) ---
-    # -s, -x, -z → no change (fr: temps, voix, nez / en: species)
-    if lower.endswith(("s", "x", "z")):
-        return lower
-
-    # --- French rules ---
-
-    # -eau, -au, -eu → +x (fr: niveau→niveaux, jeu→jeux, noyau→noyaux)
-    if lower.endswith(("eau", "au", "eu")):
-        return lower + "x"
-
-    # -al → -aux (fr: animal→animaux, journal→journaux)
-    # English exceptions (festival, carnival) are rare model names;
-    # if needed, add them to IRREGULARS or use Model(plural=...)
-    if lower.endswith("al"):
-        return lower[:-2] + "aux"
-
-    # consonant + y → -ies (en: category→categories, city→cities)
-    if lower.endswith("y") and len(lower) >= 2 and lower[-2] not in "aeiou":
-        return lower[:-1] + "ies"
-
-    # --- Default: +s (works for both languages) ---
-    # fr: maison→maisons, eleve→eleves, enseignant→enseignants
-    # en: book→books, user→users, article→articles
-    return lower + "s"
+"""Pluralization rules supporting English and French model names.
+
+Strategy:
+- Irregulars dict handles all known exceptions for both languages.
+- Rules are ordered to avoid cross-language conflicts.
+- For genuinely ambiguous cases, users can override via Model(plural=...).
+"""
+
+IRREGULARS = {
+    # English irregulars
+    "person": "people",
+    "child": "children",
+    "mouse": "mice",
+    "goose": "geese",
+    "man": "men",
+    "woman": "women",
+    "tooth": "teeth",
+    "foot": "feet",
+    "datum": "data",
+    "index": "indices",
+    "leaf": "leaves",
+    "knife": "knives",
+    "wife": "wives",
+    "life": "lives",
+    "shelf": "shelves",
+    "self": "selves",
+    "half": "halves",
+    "wolf": "wolves",
+    # English words ending in -s/-x/-z that take -es (not invariable)
+    "bus": "buses",
+    "box": "boxes",
+    "fox": "foxes",
+    "buzz": "buzzes",
+    "quiz": "quizzes",
+    "fez": "fezzes",
+    # French irregulars
+    "travail": "travaux",
+    "journal": "journaux",
+    "oeil": "yeux",
+    "monsieur": "messieurs",
+    "madame": "mesdames",
+}
+
+
+def pluralize(word: str) -> str:
+    lower = word.lower()
+
+    if lower in IRREGULARS:
+        return IRREGULARS[lower]
+
+    # --- English: -ss, -sh, -ch → +es (must check before -s invariable rule) ---
+    # en: class→classes, dish→dishes, match→matches
+    if lower.endswith(("ss", "sh", "ch")):
+        return lower + "es"
+
+    # --- Invariable endings (both languages) ---
+    # -s, -x, -z → no change (fr: temps, voix, nez / en: species)
+    if lower.endswith(("s", "x", "z")):
+        return lower
+
+    # --- French rules ---
+
+    # -eau, -au, -eu → +x (fr: niveau→niveaux, jeu→jeux, noyau→noyaux)
+    if lower.endswith(("eau", "au", "eu")):
+        return lower + "x"
+
+    # -al → -aux (fr: animal→animaux, journal→journaux)
+    # English exceptions (festival, carnival) are rare model names;
+    # if needed, add them to IRREGULARS or use Model(plural=...)
+    if lower.endswith("al"):
+        return lower[:-2] + "aux"
+
+    # consonant + y → -ies (en: category→categories, city→cities)
+    if lower.endswith("y") and len(lower) >= 2 and lower[-2] not in "aeiou":
+        return lower[:-1] + "ies"
+
+    # --- Default: +s (works for both languages) ---
+    # fr: maison→maisons, eleve→eleves, enseignant→enseignants
+    # en: book→books, user→users, article→articles
+    return lower + "s"

flashapi/core/relations.py

@@ -1,61 +1,59 @@
-"""Relation resolution between registered models."""
-
-from __future__ import annotations
-
-from flashapi.core.schema import ModelSchema, RelationSchema
-
-
-def resolve_relations(schemas: list[ModelSchema]) -> dict[str, list[RelationSchema]]:
-    """
-    Detect relations between models based on field names ending with _id.
-    Returns a mapping: parent_plural -> list of child relations.
-
-    Example: Book has author_id → Author is parent, Book is child.
-    So "authors" -> [RelationSchema(type="one_to_many", target="books")]
-    """
-    schema_map = {s.name.lower(): s for s in schemas}
-
-    parent_to_children: dict[str, list[RelationSchema]] = {}
-
-    for schema in schemas:
-        for field in schema.fields:
-            if field.name.endswith("_id") and not field.primary_key:
-                ref_name = field.name[:-3]  # "author_id" → "author"
-
-                target_schema = schema_map.get(ref_name)
-                if target_schema is None:
-                    continue
-
-                relation = RelationSchema(
-                    type="one_to_many",
-                    target=schema.plural,
-                    target_plural=schema.plural,
-                    foreign_key=field.name,
-                )
-
-                parent_plural = target_schema.plural
-                if parent_plural not in parent_to_children:
-                    parent_to_children[parent_plural] = []
-                parent_to_children[parent_plural].append(relation)
-
-                field.relation = RelationSchema(
-                    type="many_to_one",
-                    target=target_schema.name,
-                    target_plural=target_schema.plural,
-                    foreign_key=field.name,
-                )
-
-    return parent_to_children
-
-
-def find_expandable_fields(schema: ModelSchema) -> dict[str, str]:
-    """
-    Return a mapping of expandable field names to their target plural.
-    Example: {"author": "authors"} for a Book model with author_id.
-    """
-    expandable = {}
-    for field in schema.fields:
-        if field.relation and field.relation.type == "many_to_one":
-            ref_name = field.name[:-3]  # "author_id" → "author"
-            expandable[ref_name] = field.relation.target_plural
-    return expandable
+"""Relation resolution between registered models."""
+
+from __future__ import annotations
+
+from flashapi.core.schema import ModelSchema, RelationSchema
+
+
+def resolve_relations(schemas: list[ModelSchema]) -> dict[str, list[RelationSchema]]:
+    """Detect relations between models based on field names ending with _id.
+    Returns a mapping: parent_plural -> list of child relations.
+
+    Example: Book has author_id → Author is parent, Book is child.
+    So "authors" -> [RelationSchema(type="one_to_many", target="books")]
+    """
+    schema_map = {s.name.lower(): s for s in schemas}
+
+    parent_to_children: dict[str, list[RelationSchema]] = {}
+
+    for schema in schemas:
+        for field in schema.fields:
+            if field.name.endswith("_id") and not field.primary_key:
+                ref_name = field.name[:-3]  # "author_id" → "author"
+
+                target_schema = schema_map.get(ref_name)
+                if target_schema is None:
+                    continue
+
+                relation = RelationSchema(
+                    type="one_to_many",
+                    target=schema.plural,
+                    target_plural=schema.plural,
+                    foreign_key=field.name,
+                )
+
+                parent_plural = target_schema.plural
+                if parent_plural not in parent_to_children:
+                    parent_to_children[parent_plural] = []
+                parent_to_children[parent_plural].append(relation)
+
+                field.relation = RelationSchema(
+                    type="many_to_one",
+                    target=target_schema.name,
+                    target_plural=target_schema.plural,
+                    foreign_key=field.name,
+                )
+
+    return parent_to_children
+
+
+def find_expandable_fields(schema: ModelSchema) -> dict[str, str]:
+    """Return a mapping of expandable field names to their target plural.
+    Example: {"author": "authors"} for a Book model with author_id.
+    """
+    expandable = {}
+    for field in schema.fields:
+        if field.relation and field.relation.type == "many_to_one":
+            ref_name = field.name[:-3]  # "author_id" → "author"
+            expandable[ref_name] = field.relation.target_plural
+    return expandable

flashapi/core/response.py

@@ -1,33 +1,36 @@
-"""Response formatting."""
-
-from typing import Callable
-
-
-def default_formatter(data: list | dict, meta: dict | None = None) -> dict:
-    if isinstance(data, list):
-        response = {"data": data}
-        if meta:
-            response.update(meta)
-        return response
-    return {"data": data}
-
-
-def create_list_response(
-    data: list[dict],
-    total: int,
-    page: int,
-    page_size: int,
-    formatter: Callable | None = None,
-) -> dict:
-    pages = (total + page_size - 1) // page_size
-    meta = {"total": total, "page": page, "pages": pages, "page_size": page_size}
-
-    if formatter:
-        return formatter(data, meta)
-    return default_formatter(data, meta)
-
-
-def create_item_response(data: dict, formatter: Callable | None = None) -> dict:
-    if formatter:
-        return formatter(data, None)
-    return default_formatter(data)
+"""Response formatting."""
+
+from collections.abc import Callable
+
+
+def create_list_response(
+    data: list[dict],
+    total: int,
+    page: int,
+    size: int,
+    formatter: Callable | None = None,
+) -> dict:
+    total_pages = (total + size - 1) // size if size > 0 else 0
+    response = {
+        "data": data,
+        "meta": {
+            "page": page,
+            "size": size,
+            "totalElements": total,
+            "totalPages": total_pages,
+        },
+    }
+    if formatter:
+        return formatter(response)
+    return response
+
+
+def create_item_response(data: dict, formatter: Callable | None = None) -> dict:
+    response = {"data": data}
+    if formatter:
+        return formatter(response)
+    return response
+
+
+def create_error_response(message: str, status: int) -> dict:
+    return {"error": message, "status": status}

flashapi/core/schema.py

@@ -1,83 +1,145 @@
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from enum import Enum
-from typing import Any
-
-
-class FieldType(Enum):
-    STRING = "string"
-    INTEGER = "integer"
-    FLOAT = "float"
-    BOOLEAN = "boolean"
-    DATE = "date"
-    DATETIME = "datetime"
-    TIME = "time"
-    UUID = "uuid"
-    JSON = "json"
-    TEXT = "text"
-    BINARY = "binary"
-
-
-@dataclass
-class RelationSchema:
-    type: str  # "one_to_one", "many_to_one", "one_to_many", "many_to_many"
-    target: str
-    target_plural: str = ""
-    foreign_key: str = ""
-
-
-@dataclass
-class FieldSchema:
-    name: str
-    type: FieldType
-    required: bool = True
-    default: Any = None
-    constraints: dict = field(default_factory=dict)
-    primary_key: bool = False
-    auto_generated: bool = False
-    relation: RelationSchema | None = None
-
-
-@dataclass
-class ModelSchema:
-    name: str
-    plural: str
-    fields: list[FieldSchema]
-    permissions: list[str] = field(
-        default_factory=lambda: ["list", "read", "create", "update", "delete"]
-    )
-
-
-ALL_OPERATIONS = ["list", "read", "create", "update", "delete"]
-
-
-class Model:
-    """Wrapper to configure how a model is exposed via FlashAPI."""
-
-    def __init__(
-        self,
-        model_class: type,
-        *,
-        readonly: bool = False,
-        exclude: list[str] | None = None,
-        only: list[str] | None = None,
-        plural: str | None = None,
-    ):
-        self.model_class = model_class
-        self.plural = plural
-        self.permissions = self._resolve_permissions(readonly, exclude, only)
-
-    def _resolve_permissions(
-        self,
-        readonly: bool,
-        exclude: list[str] | None,
-        only: list[str] | None,
-    ) -> list[str]:
-        if only:
-            return [op for op in only if op in ALL_OPERATIONS]
-        if readonly:
-            return ["list", "read"]
-        if exclude:
-            return [op for op in ALL_OPERATIONS if op not in exclude]
-        return list(ALL_OPERATIONS)
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class FieldType(Enum):
+    STRING = "string"
+    INTEGER = "integer"
+    FLOAT = "float"
+    BOOLEAN = "boolean"
+    DATE = "date"
+    DATETIME = "datetime"
+    TIME = "time"
+    UUID = "uuid"
+    JSON = "json"
+    TEXT = "text"
+    BINARY = "binary"
+
+
+@dataclass
+class RelationSchema:
+    type: str  # "one_to_one", "many_to_one", "one_to_many", "many_to_many"
+    target: str
+    target_plural: str = ""
+    foreign_key: str = ""
+
+
+@dataclass
+class FieldSchema:
+    name: str
+    type: FieldType
+    required: bool = True
+    default: Any = None
+    constraints: dict = field(default_factory=dict)
+    primary_key: bool = False
+    auto_generated: bool = False
+    relation: RelationSchema | None = None
+    readonly: bool = False
+    writeonly: bool = False
+    hidden: bool = False
+    export_exclude: bool = False
+    auto: str | None = None  # "uuid", "datetime", "date" — server-generated on create
+
+
+@dataclass
+class ModelSchema:
+    name: str
+    plural: str
+    fields: list[FieldSchema]
+    permissions: list[str] = field(
+        default_factory=lambda: ["list", "read", "create", "update", "delete"],
+    )
+    soft_delete: bool = False
+    audit: bool = False
+    lookup_field: str = "id"
+    access: str | dict | bool | None = None
+    scope: str | None = None  # "tenant", "owner", or "both"
+    tenant_field: str | None = None
+    owner_field: str | None = None
+
+
+ALL_OPERATIONS = ["list", "read", "create", "update", "delete"]
+
+SOFT_DELETE_FIELD = "deleted_at"
+
+
+class FlashAPIConfigError(Exception):
+    pass
+
+
+def validate_soft_delete(model_class: type, soft_delete: bool) -> None:
+    """Raise if soft_delete=True but the model has no deleted_at field."""
+    if not soft_delete:
+        return
+
+    if hasattr(model_class, "_meta"):
+        try:
+            model_class._meta.get_field(SOFT_DELETE_FIELD)
+        except Exception:
+            msg = (
+                f'Model "{model_class.__name__}" has soft_delete=True but no '
+                f"'{SOFT_DELETE_FIELD}' field. Add:\n"
+                f"    {SOFT_DELETE_FIELD} = models.DateTimeField(null=True, blank=True)"
+            )
+            raise FlashAPIConfigError(
+                msg,
+            )
+    elif hasattr(model_class, "__table__"):
+        columns = {col.name for col in model_class.__table__.columns}
+        if SOFT_DELETE_FIELD not in columns:
+            msg = (
+                f'Model "{model_class.__name__}" has soft_delete=True but no '
+                f"'{SOFT_DELETE_FIELD}' column. Add:\n"
+                f"    {SOFT_DELETE_FIELD} = Column(DateTime, nullable=True)"
+            )
+            raise FlashAPIConfigError(
+                msg,
+            )
+
+
+class Model:
+    """Wrapper to configure how a model is exposed via FlashAPI."""
+
+    def __init__(
+        self,
+        model_class: type,
+        *,
+        readonly: bool = False,
+        exclude: list[str] | None = None,
+        only: list[str] | None = None,
+        plural: str | None = None,
+        soft_delete: bool = False,
+        audit: bool = False,
+        lookup_field: str = "id",
+        access: str | dict | bool | None = None,
+        scope: str | None = None,
+        tenant_field: str | None = None,
+        owner_field: str | None = None,
+    ) -> None:
+        self.model_class = model_class
+        self.plural = plural
+        self.soft_delete = soft_delete
+        self.audit = audit
+        self.lookup_field = lookup_field
+        self.access = access
+        self.scope = scope
+        self.tenant_field = tenant_field
+        self.owner_field = owner_field
+        self.permissions = self._resolve_permissions(readonly, exclude, only)
+
+    def _resolve_permissions(
+        self,
+        readonly: bool,
+        exclude: list[str] | None,
+        only: list[str] | None,
+    ) -> list[str]:
+        if only:
+            return [op for op in only if op in ALL_OPERATIONS]
+        if readonly:
+            return ["list", "read"]
+        if exclude:
+            return [op for op in ALL_OPERATIONS if op not in exclude]
+        return list(ALL_OPERATIONS)