python-flashapi 0.3.0__tar.gz → 0.4.0__tar.gz

python_flashapi-0.4.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.4.0"
+}

{python_flashapi-0.3.0 → python_flashapi-0.4.0}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.4.0](https://github.com/HackermanMe/flashapi/compare/v0.3.0...v0.4.0) (2026-09-18)
+
+
+### Features
+
+* add field selection (?fields=id,name,price) ([4c07e45](https://github.com/HackermanMe/flashapi/commit/4c07e4536ab442f3a984ec8108154ef47f361098))
+* add idempotency keys, cache layer, and currentUserField auto-injection ([141ae08](https://github.com/HackermanMe/flashapi/commit/141ae084afd4d605540a0cead5c4aac9cd6c41f6))
+* add interactive CRUD dashboard with HTMX and real-time WebSocket ([1b1b4a5](https://github.com/HackermanMe/flashapi/commit/1b1b4a5c9924db5858119a69fb9c2585c687fe6d))
+
+
+### Bug Fixes
+
+* **django:** convert URL path params to OpenAPI format in discover_django_views ([78e5675](https://github.com/HackermanMe/flashapi/commit/78e5675b8fafe0a87a7711f30f9b3db26bfd9dd6))
+* simplify nested if statement for ruff linter ([73fb95b](https://github.com/HackermanMe/flashapi/commit/73fb95bdd7282141081a85d0f44d6d8c4478967e))
+* sync release-please manifest and README version to 0.3.0 ([1538199](https://github.com/HackermanMe/flashapi/commit/1538199c6f9edc3fb4be9a17d9b69c67838a90bb))
+
 ## [0.3.0](https://github.com/HackermanMe/flashapi/compare/v0.2.0...v0.3.0) (2026-08-08)
 
 

{python_flashapi-0.3.0 → python_flashapi-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-flashapi
-Version: 0.3.0
+Version: 0.4.0
 Summary: Define your models. FlashAPI does the rest.
 Project-URL: Homepage, https://github.com/HackermanMe/flashapi
 Project-URL: Documentation, https://github.com/HackermanMe/flashapi#readme
@@ -64,10 +64,12 @@ Description-Content-Type: text/markdown
 
 ---
 
-FlashAPI generates a full REST API with CRUD, pagination, filtering, sorting, full-text search, relations, soft delete, bulk operations, export, audit trail, webhooks, rate limiting, and a live dashboard — from your existing models, in one line.
+FlashAPI generates a full REST API with CRUD, pagination, filtering, sorting, full-text search, relations, soft delete, bulk operations, export, audit trail, webhooks, rate limiting, **idempotency keys**, **cache layer**, **currentUser auto-injection**, and a live dashboard — from your existing models, in one line.
 
 Part of the **FlashAPI Ecosystem** — ensuring SDK client compatibility across all backends (Python, Java Spring, Node.js).
 
+**New in 0.4.0:** Idempotency keys (prevent double-click/retry duplicates), cache layer with graceful fallback, currentUserField auto-injection, and audit enabled by default.
+
 ---
 
 ## Documentation
@@ -89,7 +91,7 @@ Part of the **FlashAPI Ecosystem** — ensuring SDK client compatibility across
 
 ```bash
 # x-release-please-start-version
-pip install python-flashapi==0.2.0
+pip install python-flashapi==0.3.0
 # x-release-please-end
 
 # With framework extras:
@@ -231,8 +233,9 @@ FlashAPI(
         Model(Config, readonly=True, access="admin"),      # GET only, admin
         Model(Log, only=["list"]),                         # List only
         Model(Animal, plural="animaux"),                   # Custom plural
-        Model(Invoice, soft_delete=True, audit=True),      # Opt-in features
+        Model(Invoice, soft_delete=True, audit=True),      # Opt-in features (audit=True by default)
         Model(Eleve, access="staff", scope="tenant", tenant_field="ecole_id"),
+        Model(Post, current_user_field="author"),          # Auto-inject authenticated user on create
     ],
     base_path="/api",       # Configurable prefix (default: /api)
     auth_backend=MyAuth(),  # Your AuthBackend implementation
@@ -240,6 +243,14 @@ FlashAPI(
     rate_limit=100,         # 100 requests per window
     rate_window=60,         # 60 seconds window
 )
+
+# Enable idempotency (prevents duplicate operations from double-click/retry)
+# Client sends: Idempotency-Key: <uuid> header
+# Same key + same request → returns stored response (no duplicate created)
+
+# Enable cache layer (graceful fallback if Redis down)
+from flashapi.features.cache import CacheLayer, RedisCache, register_cache
+register_cache(CacheLayer(RedisCache(host='localhost')))
 ```
 
 See [Customization docs](docs/customization.md) for all options.

{python_flashapi-0.3.0 → python_flashapi-0.4.0}/README.md

@@ -22,10 +22,12 @@
 
 ---
 
-FlashAPI generates a full REST API with CRUD, pagination, filtering, sorting, full-text search, relations, soft delete, bulk operations, export, audit trail, webhooks, rate limiting, and a live dashboard — from your existing models, in one line.
+FlashAPI generates a full REST API with CRUD, pagination, filtering, sorting, full-text search, relations, soft delete, bulk operations, export, audit trail, webhooks, rate limiting, **idempotency keys**, **cache layer**, **currentUser auto-injection**, and a live dashboard — from your existing models, in one line.
 
 Part of the **FlashAPI Ecosystem** — ensuring SDK client compatibility across all backends (Python, Java Spring, Node.js).
 
+**New in 0.4.0:** Idempotency keys (prevent double-click/retry duplicates), cache layer with graceful fallback, currentUserField auto-injection, and audit enabled by default.
+
 ---
 
 ## Documentation
@@ -47,7 +49,7 @@ Part of the **FlashAPI Ecosystem** — ensuring SDK client compatibility across
 
 ```bash
 # x-release-please-start-version
-pip install python-flashapi==0.2.0
+pip install python-flashapi==0.3.0
 # x-release-please-end
 
 # With framework extras:
@@ -189,8 +191,9 @@ FlashAPI(
         Model(Config, readonly=True, access="admin"),      # GET only, admin
         Model(Log, only=["list"]),                         # List only
         Model(Animal, plural="animaux"),                   # Custom plural
-        Model(Invoice, soft_delete=True, audit=True),      # Opt-in features
+        Model(Invoice, soft_delete=True, audit=True),      # Opt-in features (audit=True by default)
         Model(Eleve, access="staff", scope="tenant", tenant_field="ecole_id"),
+        Model(Post, current_user_field="author"),          # Auto-inject authenticated user on create
     ],
     base_path="/api",       # Configurable prefix (default: /api)
     auth_backend=MyAuth(),  # Your AuthBackend implementation
@@ -198,6 +201,14 @@ FlashAPI(
     rate_limit=100,         # 100 requests per window
     rate_window=60,         # 60 seconds window
 )
+
+# Enable idempotency (prevents duplicate operations from double-click/retry)
+# Client sends: Idempotency-Key: <uuid> header
+# Same key + same request → returns stored response (no duplicate created)
+
+# Enable cache layer (graceful fallback if Redis down)
+from flashapi.features.cache import CacheLayer, RedisCache, register_cache
+register_cache(CacheLayer(RedisCache(host='localhost')))
 ```
 
 See [Customization docs](docs/customization.md) for all options.

{python_flashapi-0.3.0 → python_flashapi-0.4.0}/docs/custom-logic.md

@@ -66,6 +66,7 @@ Just add `@api_doc()` on your views. FlashAPI auto-discovers them:
 # views.py
 from django.http import JsonResponse
 from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_POST
 from flashapi import api_doc
 import json
 
@@ -73,6 +74,7 @@ import json
          body={"client_id": "int", "table_id": "int", "plats": "array"},
          body_required=["client_id", "table_id", "plats"])
 @csrf_exempt
+@require_POST
 def checkout(request):
     body = json.loads(request.body)
     # your business logic...
@@ -106,12 +108,49 @@ custom_views = [
 urlpatterns = [
     path("api/", include(
         generate_urls(models=[Plat, Commande, Client], extra_views=custom_views)
-        + custom_views
     )),
+    # Register custom views for actual routing (extra_views only adds them to Swagger)
+    path("api/checkout/", views.checkout),
+    path("api/stats/chiffre-affaires/", views.chiffre_affaires),
+    path("api/reports/bestsellers/", views.bestsellers),
+]
+```
+
+That's it. `@api_doc` on the view + pass `extra_views` to `generate_urls()` for Swagger documentation, and register the same paths in `urlpatterns` for actual routing.
+
+#### Path parameters
+
+Django URL parameters (`<int:id>`, `<str:slug>`, etc.) are automatically converted to OpenAPI path parameters in Swagger:
+
+```python
+# views.py
+@api_doc(
+    tag="Ingestion",
+    summary="Ingest a book from its uploaded PDF",
+    methods=["post"],
+    params={"book_id": "int"},
+    body={"force": "bool"},
+    body_required=[],
+    response={"status": "string", "total_sentences": "int"},
+)
+@csrf_exempt
+@require_POST
+def ingest_view(request, book_id):
+    # book_id comes from the URL path
+    ...
+
+# urls.py
+extra_views = [
+    path("books/<int:book_id>/ingest/", views.ingest_view),
+]
+
+urlpatterns = [
+    path("api/", include(generate_urls(models=[Book], extra_views=extra_views))),
+    path("api/books/<int:book_id>/ingest/", views.ingest_view),
 ]
 ```
 
-That's it. `@api_doc` on the view + pass `extra_views` to `generate_urls()`. FlashAPI reads the decorator metadata and adds your endpoints to Swagger — no duplicate declarations.
+In Swagger, this renders as `/books/{book_id}/ingest/` with `book_id` as a required integer path parameter. The `params` dict in `@api_doc` controls the type shown in Swagger (`"int"` → integer, `"string"` → string, etc.).
 
 ### Custom routes (Flask)
 

{python_flashapi-0.3.0 → python_flashapi-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-flashapi"
-version = "0.3.0"
+version = "0.4.0"
 description = "Define your models. FlashAPI does the rest."
 readme = "README.md"
 license = "Apache-2.0"

{python_flashapi-0.3.0 → python_flashapi-0.4.0}/release-please-config.json

@@ -4,7 +4,7 @@
       "release-type": "python",
       "package-name": "python-flashapi",
       "bump-minor-pre-major": true,
-      "extra-files": ["pyproject.toml"]
+      "extra-files": ["pyproject.toml", "README.md"]
     }
   }
 }

{python_flashapi-0.3.0 → python_flashapi-0.4.0}/src/flashapi/adapters/django.py

@@ -9,7 +9,7 @@ from flashapi.core.custom_routes import (
 )
 from flashapi.core.response import create_error_response, create_item_response, create_list_response
 from flashapi.core.schema import Model, ModelSchema
-from flashapi.core.visibility import export_fields, filter_response, writable_fields
+from flashapi.core.visibility import export_fields, filter_response, select_fields, writable_fields
 from flashapi.docs.openapi import generate_openapi_schema, get_swagger_html
 from flashapi.features import apply_filters, apply_search, apply_sorting, paginate
 from flashapi.features.health import get_health_check
@@ -78,6 +78,7 @@ def generate_urls(
         schema.scope = wrapper.scope
         schema.tenant_field = wrapper.tenant_field
         schema.owner_field = wrapper.owner_field
+        schema.current_user_field = wrapper.current_user_field
 
         from flashapi.core.schema import validate_soft_delete
         validate_soft_delete(wrapper.model_class, wrapper.soft_delete)
@@ -266,6 +267,7 @@ def _create_django_views(
     model_scope = schema.scope
     model_tenant_field = schema.tenant_field
     model_owner_field = schema.owner_field
+    model_current_user_field = schema.current_user_field
     patterns = []
 
     def _check_auth(request, operation):
@@ -335,6 +337,7 @@ def _create_django_views(
                 sort = params.get("sort")
                 search = params.get("search")
                 deleted_param = params.get("deleted", "false").lower() == "true"
+                fields_param = params.get("fields")  # Field selection: ?fields=id,name,price
 
                 only_deleted = deleted_param and supports_soft_delete
                 items = storage.list_all(_table, only_deleted=only_deleted)
@@ -350,6 +353,12 @@ def _create_django_views(
                 items = apply_sorting(items, sort, _fields)
                 page_items, total = paginate(items, page, size)
                 page_items = [filter_response(item, _schema) for item in page_items]
+
+                # Apply field selection if ?fields parameter provided
+                if fields_param:
+                    field_list = [f.strip() for f in fields_param.split(",")]
+                    page_items = [select_fields(item, field_list, _schema) for item in page_items]
+
                 if metrics:
                     metrics.record("READ", entity_name)
                 return JsonResponse(
@@ -371,6 +380,24 @@ def _create_django_views(
                 if scope_filter:
                     data.update(scope_filter)
 
+                # Auto-inject current user if current_user_field specified
+                if model_current_user_field and user and auth_backend:
+                    user_id = auth_backend.get_owner_id(user)
+                    if user_id is not None:
+                        # For ForeignKey fields, Django expects field_id
+                        # For non-FK fields, use field directly
+                        # Try FK syntax first (most common case)
+                        try:
+                            storage._model._meta.get_field(model_current_user_field)
+                            field = storage._model._meta.get_field(model_current_user_field)
+                            if field.many_to_one:  # ForeignKey
+                                data[f"{model_current_user_field}_id"] = user_id
+                            else:
+                                data[model_current_user_field] = user_id
+                        except Exception:
+                            # Fallback: assume FK
+                            data[f"{model_current_user_field}_id"] = user_id
+
                 item = storage.create(_table, data)
                 if metrics:
                     metrics.record("CREATE", entity_name, str(item.get("id", "")))
@@ -661,6 +688,13 @@ def _create_django_views(
                     return JsonResponse(create_error_response("Not found", 404), status=404)
 
                 item = filter_response(item, _schema)
+
+                # Apply field selection if ?fields parameter provided
+                fields_param = request.GET.get("fields")
+                if fields_param:
+                    field_list = [f.strip() for f in fields_param.split(",")]
+                    item = select_fields(item, field_list, _schema)
+
                 return JsonResponse(create_item_response(item, formatter))
 
             if request.method == "PUT" and "update" in _schema.permissions:

{python_flashapi-0.3.0 → python_flashapi-0.4.0}/src/flashapi/adapters/fastapi.py

@@ -10,7 +10,7 @@ from pydantic import BaseModel, create_model
 from flashapi.core.relations import find_expandable_fields, resolve_relations
 from flashapi.core.response import create_error_response, create_item_response, create_list_response
 from flashapi.core.schema import FieldType, Model, ModelSchema
-from flashapi.core.visibility import export_fields, filter_response, writable_fields
+from flashapi.core.visibility import export_fields, filter_response, select_fields, writable_fields
 from flashapi.features import apply_filters, apply_search, apply_sorting, paginate
 from flashapi.features.dashboard import DASHBOARD_HTML, MetricsCollector
 from flashapi.features.export import CONTENT_TYPES, EXPORTERS
@@ -450,6 +450,13 @@ class FlashAPI:
 
             metrics.record("READ", tag)
             page_items = [filter_response(item, model_schema) for item in page_items]
+
+            # Apply field selection if ?fields parameter provided
+            fields_param = request.query_params.get("fields")
+            if fields_param:
+                field_list = [f.strip() for f in fields_param.split(",")]
+                page_items = [select_fields(item, field_list, model_schema) for item in page_items]
+
             return create_list_response(page_items, total, page, size, formatter)
 
     def _add_read_route(self, table, formatter, storage, tag, expandable, model_schema, lookup_field="id") -> None:
@@ -481,6 +488,13 @@ class FlashAPI:
                 item = self._expand_items([item], expand, expandable)[0]
 
             item = filter_response(item, model_schema)
+
+            # Apply field selection if ?fields parameter provided
+            fields_param = request.query_params.get("fields")
+            if fields_param:
+                field_list = [f.strip() for f in fields_param.split(",")]
+                item = select_fields(item, field_list, model_schema)
+
             return create_item_response(item, formatter)
 
     def _add_history_route(self, table, entity_name, lookup_field="id", model_schema=None) -> None:

{python_flashapi-0.3.0 → python_flashapi-0.4.0}/src/flashapi/adapters/flask.py

@@ -10,7 +10,7 @@ from flashapi.core.custom_routes import (
 from flashapi.core.relations import find_expandable_fields, resolve_relations
 from flashapi.core.response import create_error_response, create_item_response, create_list_response
 from flashapi.core.schema import Model, ModelSchema
-from flashapi.core.visibility import export_fields, filter_response, writable_fields
+from flashapi.core.visibility import export_fields, filter_response, select_fields, writable_fields
 from flashapi.docs.openapi import generate_openapi_schema, get_swagger_html
 from flashapi.features import apply_filters, apply_search, apply_sorting, paginate
 from flashapi.features.health import get_health_check
@@ -441,6 +441,13 @@ def _create_flask_routes(
             if _metrics:
                 _metrics.record("READ", entity_name)
             page_items = [filter_response(item, _schema) for item in page_items]
+
+            # Apply field selection if ?fields parameter provided
+            fields_param = request.args.get("fields")
+            if fields_param:
+                field_list = [f.strip() for f in fields_param.split(",")]
+                page_items = [select_fields(item, field_list, _schema) for item in page_items]
+
             return jsonify(create_list_response(page_items, total, page, size, formatter))
 
     if "read" in schema.permissions:
@@ -463,6 +470,13 @@ def _create_flask_routes(
                 item = _expand_items([item], expand, _exp, storage)[0]
 
             item = filter_response(item, _schema)
+
+            # Apply field selection if ?fields parameter provided
+            fields_param = request.args.get("fields")
+            if fields_param:
+                field_list = [f.strip() for f in fields_param.split(",")]
+                item = select_fields(item, field_list, _schema)
+
             return jsonify(create_item_response(item, formatter))
 
     if "read" in schema.permissions and entity_audit:

{python_flashapi-0.3.0 → python_flashapi-0.4.0}/src/flashapi/core/custom_routes.py

@@ -121,6 +121,8 @@ def discover_django_views(url_patterns, trailing_slash: bool = True) -> dict[str
     """Scan Django URL patterns for @api_doc-decorated views and build OpenAPI paths."""
     paths: dict[str, dict] = {}
 
+    import re
+
     for pattern in url_patterns:
         callback = getattr(pattern, "callback", None)
         if callback is None:
@@ -130,8 +132,9 @@ def discover_django_views(url_patterns, trailing_slash: bool = True) -> dict[str
         if doc is None:
             continue
 
-        # Build path from Django pattern
+        # Build path from Django pattern, converting <type:name> to {name}
         path_str = "/" + str(pattern.pattern)
+        path_str = re.sub(r"<(?:\w+:)?(\w+)>", r"{\1}", path_str)
         if trailing_slash and not path_str.endswith("/"):
             path_str += "/"
 
@@ -143,8 +146,27 @@ def discover_django_views(url_patterns, trailing_slash: bool = True) -> dict[str
         if path_str not in paths:
             paths[path_str] = {}
 
+        # Extract path parameters from URL pattern
+        path_params = re.findall(r"\{(\w+)\}", path_str)
+
         for method in methods:
-            paths[path_str][method] = _build_openapi_operation(doc, method)
+            operation = _build_openapi_operation(doc, method)
+            if path_params:
+                if "parameters" not in operation:
+                    operation["parameters"] = []
+                # Remove any query params that are actually path params
+                operation["parameters"] = [
+                    p for p in operation["parameters"] if p["name"] not in path_params
+                ]
+                for pname in path_params:
+                    ptype = doc.get("params", {}).get(pname, "string") if doc.get("params") else "string"
+                    operation["parameters"].append({
+                        "name": pname,
+                        "in": "path",
+                        "required": True,
+                        "schema": TYPE_MAP.get(ptype, {"type": "string"}),
+                    })
+            paths[path_str][method] = operation
 
     return paths
 

{python_flashapi-0.3.0 → python_flashapi-0.4.0}/src/flashapi/core/schema.py

@@ -59,6 +59,7 @@ class ModelSchema:
     scope: str | None = None  # "tenant", "owner", or "both"
     tenant_field: str | None = None
     owner_field: str | None = None
+    current_user_field: str | None = None  # Auto-inject authenticated user on CREATE
 
 
 ALL_OPERATIONS = ["list", "read", "create", "update", "delete"]
@@ -112,12 +113,13 @@ class Model:
         only: list[str] | None = None,
         plural: str | None = None,
         soft_delete: bool = False,
-        audit: bool = False,
+        audit: bool = True,  # Enabled by default for full traceability
         lookup_field: str = "id",
         access: str | dict | bool | None = None,
         scope: str | None = None,
         tenant_field: str | None = None,
         owner_field: str | None = None,
+        current_user_field: str | None = None,
     ) -> None:
         self.model_class = model_class
         self.plural = plural
@@ -128,6 +130,7 @@ class Model:
         self.scope = scope
         self.tenant_field = tenant_field
         self.owner_field = owner_field
+        self.current_user_field = current_user_field
         self.permissions = self._resolve_permissions(readonly, exclude, only)
 
     def _resolve_permissions(

{python_flashapi-0.3.0 → python_flashapi-0.4.0}/src/flashapi/core/visibility.py

@@ -44,3 +44,39 @@ def filter_input(data: dict, schema: ModelSchema) -> dict:
     """Remove readonly/hidden fields from input dict."""
     allowed = writable_fields(schema)
     return {k: v for k, v in data.items() if k in allowed}
+
+
+def select_fields(data: dict, fields: list[str] | None, schema: ModelSchema) -> dict:
+    """
+    Select only requested fields from response data.
+
+    Field selection (?fields=id,name,price) allows clients to request only specific fields,
+    reducing payload size and improving performance.
+
+    Args:
+        data: Response dict to filter
+        fields: List of field names to include (None = return all visible fields)
+        schema: Model schema for validation
+
+    Returns:
+        Dict containing only requested fields that exist and are visible (id always included)
+
+    Example:
+        >>> select_fields({"id": 1, "name": "Laptop", "price": 999, "stock": 10}, ["name"], schema)
+        {"id": 1, "name": "Laptop"}  # id always included
+    """
+    if not fields:
+        return data
+
+    # Get visible fields from schema
+    visible = response_fields(schema)
+
+    # Filter: requested fields + always include id
+    result = {}
+    for k, v in data.items():
+        if k == "id":
+            result[k] = v  # Always include id
+        elif k in fields and k in visible:
+            result[k] = v
+
+    return result