python-flashapi 0.1.0__py3-none-any.whl

flashapi/adapters/flask.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+from typing import Callable
+
+from flashapi.core.schema import Model, ModelSchema
+from flashapi.core.response import create_list_response, create_item_response
+from flashapi.core.relations import resolve_relations, find_expandable_fields
+from flashapi.core.custom_routes import (
+    CustomRoute, custom_routes_to_openapi_paths, discover_flask_views,
+)
+from flashapi.features import paginate, apply_filters, apply_sorting, apply_search
+from flashapi.inspectors import inspect_model
+from flashapi.storage.auto import AutoStorage
+from flashapi.storage.sqlalchemy import SQLAlchemyStorage
+from flashapi.docs.openapi import generate_openapi_schema, get_swagger_html
+
+
+def register_models(
+    app,
+    models: list[type | Model],
+    *,
+    engine=None,
+    custom_routes: list[CustomRoute] | None = None,
+    database: str = "flashapi.db",
+    docs: bool = True,
+    formatter: Callable | None = None,
+):
+    """Register models on an existing Flask app."""
+    from flask import Blueprint
+
+    session_factory = None
+    if engine is not None:
+        from sqlalchemy.orm import sessionmaker
+        session_factory = sessionmaker(bind=engine)
+
+    auto_storage = AutoStorage(database) if engine is None else None
+    blueprint = Blueprint("flashapi", __name__)
+    all_schemas: list[ModelSchema] = []
+    storages: dict[str, any] = {}
+
+    for model_entry in models:
+        if isinstance(model_entry, Model):
+            wrapper = model_entry
+        else:
+            wrapper = Model(model_entry)
+
+        schema = inspect_model(wrapper.model_class, plural=wrapper.plural)
+        schema.permissions = wrapper.permissions
+
+        is_sa = hasattr(wrapper.model_class, "__table__") and hasattr(wrapper.model_class, "__tablename__")
+
+        if is_sa and session_factory is not None:
+            storage = SQLAlchemyStorage(session_factory, wrapper.model_class)
+        else:
+            auto_storage.ensure_table(schema)
+            storage = auto_storage
+
+        storages[schema.plural] = storage
+        all_schemas.append(schema)
+        expandable = find_expandable_fields(schema)
+        _create_flask_routes(blueprint, schema, storage, formatter, expandable)
+
+    parent_to_children = resolve_relations(all_schemas)
+    for parent_plural, relations in parent_to_children.items():
+        for relation in relations:
+            _create_nested_route(
+                blueprint, parent_plural, relation.target_plural,
+                relation.foreign_key, storages.get(relation.target_plural, storage), formatter,
+            )
+
+    if docs:
+        _add_docs_routes(blueprint, all_schemas, custom_routes or [], flask_app=app)
+
+    app.register_blueprint(blueprint)
+
+
+def _add_docs_routes(blueprint, schemas: list[ModelSchema], custom_routes: list[CustomRoute], flask_app=None) -> None:
+    from flask import jsonify, Response
+
+    openapi_spec = generate_openapi_schema(schemas)
+
+    # Method 1: explicit CustomRoute objects
+    if custom_routes:
+        custom_paths = custom_routes_to_openapi_paths(custom_routes)
+        openapi_spec["paths"].update(custom_paths)
+
+    # Method 2: auto-discover @api_doc decorated views (done lazily on first request)
+    _discovered = {"done": False}
+
+    @blueprint.route("/openapi.json", methods=["GET"], endpoint="flashapi_openapi")
+    def openapi_json():
+        if not _discovered["done"] and flask_app is not None:
+            discovered = discover_flask_views(flask_app)
+            openapi_spec["paths"].update(discovered)
+            _discovered["done"] = True
+        return jsonify(openapi_spec)
+
+    @blueprint.route("/docs", methods=["GET"], endpoint="flashapi_docs")
+    def docs_ui():
+        html = get_swagger_html(title="FlashAPI", openapi_url="/openapi.json")
+        return Response(html, content_type="text/html")
+
+
+def _create_nested_route(blueprint, parent_plural, child_plural, foreign_key, storage, formatter):
+    from flask import request, jsonify
+
+    @blueprint.route(
+        f"/{parent_plural}/<int:parent_id>/{child_plural}",
+        methods=["GET"],
+        endpoint=f"{parent_plural}_{child_plural}_nested",
+    )
+    def nested_list(parent_id, _pp=parent_plural, _cp=child_plural, _fk=foreign_key):
+        parent = storage.get(_pp, parent_id)
+        if parent is None:
+            return jsonify({"error": "Parent not found"}), 404
+
+        all_items = storage.list_all(_cp)
+        items = [i for i in all_items if i.get(_fk) == parent_id]
+
+        params = dict(request.args)
+        page = int(params.get("page", 1))
+        page_size = int(params.get("page_size", 20))
+        sort = params.get("sort")
+        search = params.get("search")
+
+        child_fields = {k for item in items for k in item.keys() if k != "id"}
+        if search:
+            items = apply_search(items, search, child_fields)
+        if sort:
+            items = apply_sorting(items, sort, child_fields)
+
+        page_items, total = paginate(items, page, page_size)
+        return jsonify(create_list_response(page_items, total, page, page_size, formatter))
+
+
+def _expand_items(items, expand_param, expandable, storage):
+    expand_fields = [f.strip() for f in expand_param.split(",")]
+    expanded_items = []
+
+    for item in items:
+        item_copy = dict(item)
+        for field_name in expand_fields:
+            if field_name in expandable:
+                fk_field = f"{field_name}_id"
+                fk_value = item_copy.get(fk_field)
+                if fk_value is not None:
+                    related = storage.get(expandable[field_name], fk_value)
+                    if related:
+                        item_copy[field_name] = related
+        expanded_items.append(item_copy)
+
+    return expanded_items
+
+
+def _create_flask_routes(
+    blueprint,
+    schema: ModelSchema,
+    storage: AutoStorage,
+    formatter: Callable | None,
+    expandable: dict,
+) -> None:
+    from flask import request, jsonify
+
+    table = schema.plural
+    field_names = {f.name for f in schema.fields if not f.primary_key}
+
+    if "list" in schema.permissions:
+        @blueprint.route(f"/{table}", methods=["GET"], endpoint=f"{table}_list")
+        def list_items(_table=table, _fields=field_names, _exp=expandable):
+            items = storage.list_all(_table)
+            params = dict(request.args)
+            try:
+                page = max(1, int(params.get("page", 1)))
+                page_size = max(1, min(100, int(params.get("page_size", 20))))
+            except (ValueError, TypeError):
+                return jsonify({"error": "Invalid page or page_size parameter"}), 400
+            sort = params.get("sort")
+            search = params.get("search")
+            expand = params.get("expand")
+
+            items = apply_filters(items, params, _fields)
+            items = apply_search(items, search, _fields)
+            items = apply_sorting(items, sort, _fields)
+            page_items, total = paginate(items, page, page_size)
+
+            if expand:
+                page_items = _expand_items(page_items, expand, _exp, storage)
+
+            return jsonify(create_list_response(page_items, total, page, page_size, formatter))
+
+    if "read" in schema.permissions:
+        @blueprint.route(f"/{table}/<int:item_id>", methods=["GET"], endpoint=f"{table}_get")
+        def get_item(item_id, _table=table, _exp=expandable):
+            item = storage.get(_table, item_id)
+            if item is None:
+                return jsonify({"error": "Not found"}), 404
+
+            expand = request.args.get("expand")
+            if expand:
+                item = _expand_items([item], expand, _exp, storage)[0]
+
+            return jsonify(create_item_response(item, formatter))
+
+    if "create" in schema.permissions:
+        @blueprint.route(f"/{table}", methods=["POST"], endpoint=f"{table}_create")
+        def create_item(_table=table, _fields=field_names):
+            body = request.get_json(silent=True)
+            if not body:
+                return jsonify({"error": "Request body is required"}), 400
+            data = {k: v for k, v in body.items() if k in _fields}
+            item = storage.create(_table, data)
+            return jsonify(create_item_response(item, formatter)), 201
+
+    if "update" in schema.permissions:
+        @blueprint.route(f"/{table}/<int:item_id>", methods=["PUT"], endpoint=f"{table}_update")
+        def update_item(item_id, _table=table, _fields=field_names):
+            body = request.get_json(silent=True)
+            if not body:
+                return jsonify({"error": "Request body is required"}), 400
+            data = {k: v for k, v in body.items() if k in _fields}
+            item = storage.update(_table, item_id, data)
+            if item is None:
+                return jsonify({"error": "Not found"}), 404
+            return jsonify(create_item_response(item, formatter))
+
+    if "delete" in schema.permissions:
+        @blueprint.route(f"/{table}/<int:item_id>", methods=["DELETE"], endpoint=f"{table}_delete")
+        def delete_item(item_id, _table=table):
+            deleted = storage.delete(_table, item_id)
+            if not deleted:
+                return jsonify({"error": "Not found"}), 404
+            return "", 204

flashapi/core/__init__.py

@@ -0,0 +1,3 @@
+from flashapi.core.schema import Model, ModelSchema, FieldSchema, FieldType, RelationSchema
+
+__all__ = ["Model", "ModelSchema", "FieldSchema", "FieldType", "RelationSchema"]

flashapi/core/custom_routes.py

@@ -0,0 +1,261 @@
+"""Decorator and registry for custom routes appearing in FlashAPI's Swagger docs.
+
+Usage — place @api_doc on your view:
+
+    @api_doc(tag="Orders", summary="Checkout", body={"cart_id": "int"})
+    def checkout(request):
+        ...
+
+FlashAPI auto-discovers these views and adds them to the OpenAPI spec.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+TYPE_MAP = {
+    "string": {"type": "string"},
+    "str": {"type": "string"},
+    "integer": {"type": "integer"},
+    "int": {"type": "integer"},
+    "number": {"type": "number"},
+    "float": {"type": "number"},
+    "boolean": {"type": "boolean"},
+    "bool": {"type": "boolean"},
+    "array": {"type": "array", "items": {"type": "string"}},
+    "list": {"type": "array", "items": {"type": "string"}},
+    "object": {"type": "object"},
+    "dict": {"type": "object"},
+}
+
+
+def api_doc(
+    *,
+    tag: str = "Custom",
+    summary: str = "",
+    methods: list[str] | None = None,
+    body: dict[str, str] | None = None,
+    body_required: list[str] | None = None,
+    params: dict[str, str] | None = None,
+    response: dict[str, Any] | None = None,
+):
+    """Decorator that marks a view for inclusion in FlashAPI's Swagger docs.
+
+    Args:
+        tag: Group name in Swagger UI.
+        summary: One-line description of the endpoint.
+        methods: HTTP methods (auto-detected if not specified).
+        body: Request body fields as {name: type}. Types: str, int, float, bool, array, object.
+        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 = {
+            "tag": tag,
+            "summary": summary,
+            "methods": [m.lower() for m in methods] if methods else None,
+            "body": body,
+            "body_required": body_required or [],
+            "params": params,
+            "response": response,
+        }
+        return func
+    return decorator
+
+
+def _extract_doc_from_view(view_func) -> dict | None:
+    """Extract _flashapi_doc metadata from a view function (unwrapping decorators)."""
+    func = view_func
+    # Unwrap csrf_exempt and other decorators
+    while func is not None:
+        if hasattr(func, "_flashapi_doc"):
+            return func._flashapi_doc
+        func = getattr(func, "__wrapped__", None)
+    return None
+
+
+def _build_openapi_operation(doc: dict, method: str) -> dict[str, Any]:
+    """Build an OpenAPI operation from @api_doc metadata."""
+    operation: dict[str, Any] = {
+        "tags": [doc["tag"]],
+        "summary": doc["summary"] or f"{method.upper()} endpoint",
+        "responses": {
+            "200": {"description": "Success"}
+        },
+    }
+
+    if doc.get("response"):
+        operation["responses"]["200"]["content"] = {
+            "application/json": {"schema": doc["response"]}
+        }
+
+    if doc.get("params"):
+        operation["parameters"] = []
+        for name, ptype in doc["params"].items():
+            operation["parameters"].append({
+                "name": name,
+                "in": "query",
+                "required": False,
+                "schema": TYPE_MAP.get(ptype, {"type": "string"}),
+            })
+
+    if doc.get("body") and method in ("post", "put", "patch"):
+        properties = {}
+        for fname, ftype in doc["body"].items():
+            properties[fname] = TYPE_MAP.get(ftype, {"type": "string"})
+        body_schema: dict[str, Any] = {"type": "object", "properties": properties}
+        if doc.get("body_required"):
+            body_schema["required"] = doc["body_required"]
+        operation["requestBody"] = {
+            "required": True,
+            "content": {"application/json": {"schema": body_schema}},
+        }
+
+    return operation
+
+
+def discover_django_views(url_patterns, trailing_slash: bool = True) -> dict[str, dict]:
+    """Scan Django URL patterns for @api_doc-decorated views and build OpenAPI paths."""
+    paths: dict[str, dict] = {}
+
+    for pattern in url_patterns:
+        callback = getattr(pattern, "callback", None)
+        if callback is None:
+            continue
+
+        doc = _extract_doc_from_view(callback)
+        if doc is None:
+            continue
+
+        # Build path from Django pattern
+        path_str = "/" + str(pattern.pattern)
+        if trailing_slash and not path_str.endswith("/"):
+            path_str += "/"
+
+        # Determine methods
+        methods = doc["methods"]
+        if not methods:
+            methods = ["get"]
+
+        if path_str not in paths:
+            paths[path_str] = {}
+
+        for method in methods:
+            paths[path_str][method] = _build_openapi_operation(doc, method)
+
+    return paths
+
+
+def discover_flask_views(app) -> dict[str, dict]:
+    """Scan a Flask app for @api_doc-decorated views and build OpenAPI paths."""
+    paths: dict[str, dict] = {}
+
+    for rule in app.url_map.iter_rules():
+        view_func = app.view_functions.get(rule.endpoint)
+        if view_func is None:
+            continue
+
+        doc = _extract_doc_from_view(view_func)
+        if doc is None:
+            continue
+
+        # Convert Flask rule to OpenAPI path: /items/<int:item_id> → /items/{item_id}
+        path_str = rule.rule
+        import re
+        path_str = re.sub(r"<(?:\w+:)?(\w+)>", r"{\1}", path_str)
+
+        # Determine methods
+        methods = doc["methods"]
+        if not methods:
+            rule_methods = [m.lower() for m in rule.methods if m not in ("HEAD", "OPTIONS")]
+            methods = rule_methods or ["get"]
+
+        if path_str not in paths:
+            paths[path_str] = {}
+
+        for method in methods:
+            paths[path_str][method] = _build_openapi_operation(doc, method)
+
+    return paths
+
+
+# Keep backward compat with CustomRoute for users who prefer explicit declaration
+@dataclass
+class RouteParam:
+    name: str
+    location: str = "query"
+    type: str = "string"
+    required: bool = False
+    description: str = ""
+
+
+@dataclass
+class RouteBody:
+    fields: dict[str, str] = field(default_factory=dict)
+    required_fields: list[str] = field(default_factory=list)
+
+
+@dataclass
+class CustomRoute:
+    path: str
+    method: str = "get"
+    summary: str = ""
+    tag: str = "Custom"
+    parameters: list[RouteParam] = field(default_factory=list)
+    body: RouteBody | None = None
+    response_description: str = "Success"
+    response_schema: dict[str, Any] | None = None
+
+
+def custom_routes_to_openapi_paths(routes: list[CustomRoute], trailing_slash: bool = False) -> dict:
+    """Convert a list of CustomRoute to OpenAPI path entries."""
+    paths: dict[str, dict] = {}
+    suffix = "/" if trailing_slash else ""
+
+    for route in routes:
+        path_key = route.path.rstrip("/") + suffix if trailing_slash else route.path
+        if path_key not in paths:
+            paths[path_key] = {}
+
+        operation: dict[str, Any] = {
+            "tags": [route.tag],
+            "summary": route.summary or f"{route.method.upper()} {route.path}",
+            "responses": {
+                "200": {"description": route.response_description}
+            },
+        }
+
+        if route.response_schema:
+            operation["responses"]["200"]["content"] = {
+                "application/json": {"schema": route.response_schema}
+            }
+
+        if route.parameters:
+            operation["parameters"] = []
+            for param in route.parameters:
+                operation["parameters"].append({
+                    "name": param.name,
+                    "in": param.location,
+                    "required": param.required,
+                    "description": param.description,
+                    "schema": TYPE_MAP.get(param.type, {"type": "string"}),
+                })
+
+        if route.body:
+            properties = {}
+            for fname, ftype in route.body.fields.items():
+                properties[fname] = TYPE_MAP.get(ftype, {"type": "string"})
+            body_schema: dict[str, Any] = {"type": "object", "properties": properties}
+            if route.body.required_fields:
+                body_schema["required"] = route.body.required_fields
+            operation["requestBody"] = {
+                "required": True,
+                "content": {"application/json": {"schema": body_schema}},
+            }
+
+        paths[path_key][route.method.lower()] = operation
+
+    return paths

flashapi/core/pluralize.py

@@ -0,0 +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"

flashapi/core/relations.py

@@ -0,0 +1,61 @@
+"""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

@@ -0,0 +1,33 @@
+"""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)