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

flashapi/features/websocket.py

@@ -0,0 +1,129 @@
+"""WebSocket real-time events — broadcasts CRUD events to connected clients.
+
+Protocol: raw WebSocket with JSON messages (compatible with the spec's event format).
+Clients subscribe to topics via a SUBSCRIBE message, server pushes events.
+
+Message format (server → client):
+{
+  "type": "ENTITY_CREATED" | "ENTITY_UPDATED" | "ENTITY_DELETED" | "ENTITY_RESTORED",
+  "entity": "Eleve",
+  "data": { ... },
+  "timestamp": "2026-07-14T15:30:00Z"
+}
+
+Subscribe message (client → server):
+{
+  "action": "subscribe",
+  "topic": "/topic/entities" | "/topic/{entity}"
+}
+
+Unsubscribe message (client → server):
+{
+  "action": "unsubscribe",
+  "topic": "/topic/entities" | "/topic/{entity}"
+}
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+
+class WebSocketHub:
+    """In-memory pub/sub hub for WebSocket connections.
+
+    Framework adapters register connections and call broadcast() on CRUD events.
+    """
+
+    def __init__(self) -> None:
+        self._subscribers: dict[str, set] = {}
+
+    def subscribe(self, topic: str, connection) -> None:
+        if topic not in self._subscribers:
+            self._subscribers[topic] = set()
+        self._subscribers[topic].add(connection)
+
+    def unsubscribe(self, topic: str, connection) -> None:
+        if topic in self._subscribers:
+            self._subscribers[topic].discard(connection)
+            if not self._subscribers[topic]:
+                del self._subscribers[topic]
+
+    def remove_connection(self, connection) -> None:
+        for topic in list(self._subscribers.keys()):
+            self._subscribers[topic].discard(connection)
+            if not self._subscribers[topic]:
+                del self._subscribers[topic]
+
+    def get_subscribers(self, entity: str) -> set:
+        global_subs = self._subscribers.get("/topic/entities", set())
+        entity_subs = self._subscribers.get(f"/topic/{entity.lower()}", set())
+        return global_subs | entity_subs
+
+    def build_message(self, event_type: str, entity: str, data: dict | None = None) -> str:
+        message = {
+            "type": event_type,
+            "entity": entity,
+            "data": data or {},
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+        return json.dumps(message)
+
+
+_hub = WebSocketHub()
+
+
+def get_hub() -> WebSocketHub:
+    return _hub
+
+
+def broadcast_event(entity: str, event_type: str, data: dict | None = None) -> None:
+    """Broadcast an event to all subscribers. Called by adapters after CRUD ops.
+
+    This is a no-op if no WebSocket connections are active (zero overhead).
+    """
+    hub = get_hub()
+    subscribers = hub.get_subscribers(entity)
+    if not subscribers:
+        return
+
+    message = hub.build_message(event_type, entity, data)
+
+    dead = set()
+    for conn in subscribers:
+        try:
+            conn.send_message(message)
+        except Exception:
+            dead.add(conn)
+
+    for conn in dead:
+        hub.remove_connection(conn)
+
+
+async def broadcast_event_async(entity: str, event_type: str, data: dict | None = None) -> None:
+    """Async version of broadcast_event for FastAPI/async frameworks."""
+    hub = get_hub()
+    subscribers = hub.get_subscribers(entity)
+    if not subscribers:
+        return
+
+    message = hub.build_message(event_type, entity, data)
+
+    dead = set()
+    for conn in subscribers:
+        try:
+            await conn.send_message(message)
+        except Exception:
+            dead.add(conn)
+
+    for conn in dead:
+        hub.remove_connection(conn)
+
+
+EVENT_MAP = {
+    "CREATE": "ENTITY_CREATED",
+    "UPDATE": "ENTITY_UPDATED",
+    "DELETE": "ENTITY_DELETED",
+    "RESTORE": "ENTITY_RESTORED",
+}

flashapi/flask.py

@@ -1,5 +1,5 @@
-"""FlashAPI Flask adapter — public entry point."""
-
-from flashapi.adapters.flask import register_models
-
-__all__ = ["register_models"]
+"""FlashAPI Flask adapter — public entry point."""
+
+from flashapi.adapters.flask import register_models
+
+__all__ = ["register_models"]

flashapi/inspectors/__init__.py

@@ -1,3 +1,3 @@
-from flashapi.inspectors.detect import inspect_model
-
-__all__ = ["inspect_model"]
+from flashapi.inspectors.detect import inspect_model
+
+__all__ = ["inspect_model"]

flashapi/inspectors/base.py

@@ -1,11 +1,13 @@
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-
-from flashapi.core.schema import ModelSchema
-
-
-class Inspector(ABC):
-    @abstractmethod
-    def inspect(self, model_class: type, plural: str | None = None) -> ModelSchema:
-        ...
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from flashapi.core.schema import ModelSchema
+
+
+class Inspector(ABC):
+    @abstractmethod
+    def inspect(self, model_class: type, plural: str | None = None) -> ModelSchema:
+        ...

flashapi/inspectors/dataclass.py

@@ -1,39 +1,50 @@
-from __future__ import annotations
-
-from dataclasses import fields as dc_fields, MISSING
-
-from flashapi.core.schema import FieldSchema, FieldType, ModelSchema
-from flashapi.core.pluralize import pluralize
-from flashapi.inspectors.base import Inspector
-
-TYPE_MAP: dict[type, FieldType] = {
-    str: FieldType.STRING,
-    int: FieldType.INTEGER,
-    float: FieldType.FLOAT,
-    bool: FieldType.BOOLEAN,
-}
-
-
-class DataclassInspector(Inspector):
-    def inspect(self, model_class: type, plural: str | None = None) -> ModelSchema:
-        schema_fields: list[FieldSchema] = []
-        schema_fields.append(
-            FieldSchema(name="id", type=FieldType.INTEGER, required=False, primary_key=True, auto_generated=True)
-        )
-
-        for f in dc_fields(model_class):
-            field_type = TYPE_MAP.get(f.type, FieldType.STRING)
-            required = f.default is MISSING and f.default_factory is MISSING
-            default = None if required else f.default
-
-            schema_fields.append(FieldSchema(
-                name=f.name,
-                type=field_type,
-                required=required,
-                default=default,
-            ))
-
-        model_name = model_class.__name__
-        plural_name = plural or pluralize(model_name)
-
-        return ModelSchema(name=model_name, plural=plural_name, fields=schema_fields)
+from __future__ import annotations
+
+from dataclasses import MISSING
+from dataclasses import fields as dc_fields
+
+from flashapi.core.pluralize import pluralize
+from flashapi.core.schema import FieldSchema, FieldType, ModelSchema
+from flashapi.inspectors.base import Inspector
+
+TYPE_MAP: dict[type, FieldType] = {
+    str: FieldType.STRING,
+    int: FieldType.INTEGER,
+    float: FieldType.FLOAT,
+    bool: FieldType.BOOLEAN,
+}
+
+
+class DataclassInspector(Inspector):
+    def _extract_visibility(self, f) -> dict:
+        visibility = {}
+        meta = f.metadata or {}
+        for key in ("readonly", "writeonly", "hidden", "export_exclude"):
+            if meta.get(key):
+                visibility[key] = True
+        return visibility
+
+    def inspect(self, model_class: type, plural: str | None = None) -> ModelSchema:
+        schema_fields: list[FieldSchema] = []
+        schema_fields.append(
+            FieldSchema(name="id", type=FieldType.INTEGER, required=False, primary_key=True, auto_generated=True),
+        )
+
+        for f in dc_fields(model_class):
+            field_type = TYPE_MAP.get(f.type, FieldType.STRING)
+            required = f.default is MISSING and f.default_factory is MISSING
+            default = None if required else f.default
+            visibility = self._extract_visibility(f)
+
+            schema_fields.append(FieldSchema(
+                name=f.name,
+                type=field_type,
+                required=required,
+                default=default,
+                **visibility,
+            ))
+
+        model_name = model_class.__name__
+        plural_name = plural or pluralize(model_name)
+
+        return ModelSchema(name=model_name, plural=plural_name, fields=schema_fields)

flashapi/inspectors/detect.py

@@ -1,48 +1,54 @@
-from __future__ import annotations
-
-from dataclasses import is_dataclass
-
-from flashapi.core.schema import ModelSchema
-
-
-def inspect_model(model_class: type, plural: str | None = None) -> ModelSchema:
-    if _is_django_model(model_class):
-        from flashapi.inspectors.django import DjangoInspector
-        return DjangoInspector().inspect(model_class, plural)
-
-    if _is_sqlalchemy_model(model_class):
-        from flashapi.inspectors.sqlalchemy import SQLAlchemyInspector
-        return SQLAlchemyInspector().inspect(model_class, plural)
-
-    if _is_pydantic_model(model_class):
-        from flashapi.inspectors.pydantic import PydanticInspector
-        return PydanticInspector().inspect(model_class, plural)
-
-    if is_dataclass(model_class):
-        from flashapi.inspectors.dataclass import DataclassInspector
-        return DataclassInspector().inspect(model_class, plural)
-
-    raise TypeError(
-        f"Unsupported model type: {model_class}. "
-        "FlashAPI supports Django models, SQLAlchemy models, Pydantic models, and dataclasses."
-    )
-
-
-def _is_django_model(cls: type) -> bool:
-    try:
-        from django.db import models
-        return issubclass(cls, models.Model)
-    except ImportError:
-        return False
-
-
-def _is_sqlalchemy_model(cls: type) -> bool:
-    return hasattr(cls, "__table__") and hasattr(cls, "__tablename__")
-
-
-def _is_pydantic_model(cls: type) -> bool:
-    try:
-        from pydantic import BaseModel
-        return issubclass(cls, BaseModel)
-    except ImportError:
-        return False
+from __future__ import annotations
+
+from dataclasses import is_dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from flashapi.core.schema import ModelSchema
+
+
+def inspect_model(model_class: type, plural: str | None = None) -> ModelSchema:
+    if _is_django_model(model_class):
+        from flashapi.inspectors.django import DjangoInspector
+        return DjangoInspector().inspect(model_class, plural)
+
+    if _is_sqlalchemy_model(model_class):
+        from flashapi.inspectors.sqlalchemy import SQLAlchemyInspector
+        return SQLAlchemyInspector().inspect(model_class, plural)
+
+    if _is_pydantic_model(model_class):
+        from flashapi.inspectors.pydantic import PydanticInspector
+        return PydanticInspector().inspect(model_class, plural)
+
+    if is_dataclass(model_class):
+        from flashapi.inspectors.dataclass import DataclassInspector
+        return DataclassInspector().inspect(model_class, plural)
+
+    msg = (
+        f"Unsupported model type: {model_class}. "
+        "FlashAPI supports Django models, SQLAlchemy models, Pydantic models, and dataclasses."
+    )
+    raise TypeError(
+        msg,
+    )
+
+
+def _is_django_model(cls: type) -> bool:
+    try:
+        from django.db import models
+        return isinstance(cls, type) and issubclass(cls, models.Model)
+    except ImportError:
+        return False
+
+
+def _is_sqlalchemy_model(cls: type) -> bool:
+    return isinstance(cls, type) and hasattr(cls, "__table__") and hasattr(cls, "__tablename__")
+
+
+def _is_pydantic_model(cls: type) -> bool:
+    try:
+        from pydantic import BaseModel
+        return isinstance(cls, type) and issubclass(cls, BaseModel)
+    except ImportError:
+        return False
+

flashapi/inspectors/django.py

@@ -1,83 +1,93 @@
-from __future__ import annotations
-
-from flashapi.core.schema import FieldSchema, FieldType, ModelSchema, RelationSchema
-from flashapi.core.pluralize import pluralize
-from flashapi.inspectors.base import Inspector
-
-DJANGO_TYPE_MAP = {
-    "AutoField": FieldType.INTEGER,
-    "BigAutoField": FieldType.INTEGER,
-    "SmallAutoField": FieldType.INTEGER,
-    "CharField": FieldType.STRING,
-    "TextField": FieldType.TEXT,
-    "IntegerField": FieldType.INTEGER,
-    "BigIntegerField": FieldType.INTEGER,
-    "SmallIntegerField": FieldType.INTEGER,
-    "PositiveIntegerField": FieldType.INTEGER,
-    "FloatField": FieldType.FLOAT,
-    "DecimalField": FieldType.FLOAT,
-    "BooleanField": FieldType.BOOLEAN,
-    "DateField": FieldType.DATE,
-    "DateTimeField": FieldType.DATETIME,
-    "TimeField": FieldType.TIME,
-    "UUIDField": FieldType.UUID,
-    "JSONField": FieldType.JSON,
-    "BinaryField": FieldType.BINARY,
-    "EmailField": FieldType.STRING,
-    "URLField": FieldType.STRING,
-    "SlugField": FieldType.STRING,
-    "FileField": FieldType.STRING,
-    "ImageField": FieldType.STRING,
-}
-
-
-class DjangoInspector(Inspector):
-    def inspect(self, model_class: type, plural: str | None = None) -> ModelSchema:
-        meta = model_class._meta
-        fields: list[FieldSchema] = []
-
-        for f in meta.get_fields():
-            if f.many_to_many or f.one_to_many:
-                continue
-
-            field_type_name = type(f).__name__
-            field_type = DJANGO_TYPE_MAP.get(field_type_name, FieldType.STRING)
-
-            constraints = {}
-            if hasattr(f, "max_length") and f.max_length:
-                constraints["max_length"] = f.max_length
-
-            relation = None
-            is_fk = hasattr(f, "related_model") and f.related_model
-            if is_fk:
-                relation = RelationSchema(
-                    type="one_to_one" if f.one_to_one else "many_to_one",
-                    target=f.related_model.__name__,
-                )
-                field_type = FieldType.INTEGER
-
-            is_pk = getattr(f, "primary_key", False)
-            auto_generated = field_type_name in ("AutoField", "BigAutoField", "SmallAutoField")
-            has_default = hasattr(f, "default") and f.default is not None
-            if is_pk and has_default and not auto_generated:
-                auto_generated = True
-            required = not getattr(f, "blank", False) and not getattr(f, "null", False) and not has_default
-            default = f.default if has_default else None
-
-            field_name = getattr(f, "attname", f.name) if is_fk else f.name
-
-            fields.append(FieldSchema(
-                name=field_name,
-                type=field_type,
-                required=required and not is_pk,
-                default=default,
-                constraints=constraints,
-                primary_key=is_pk,
-                auto_generated=auto_generated,
-                relation=relation,
-            ))
-
-        model_name = model_class.__name__
-        plural_name = plural or pluralize(model_name)
-
-        return ModelSchema(name=model_name, plural=plural_name, fields=fields)
+from __future__ import annotations
+
+from flashapi.core.pluralize import pluralize
+from flashapi.core.schema import FieldSchema, FieldType, ModelSchema, RelationSchema
+from flashapi.inspectors.base import Inspector
+
+DJANGO_TYPE_MAP = {
+    "AutoField": FieldType.INTEGER,
+    "BigAutoField": FieldType.INTEGER,
+    "SmallAutoField": FieldType.INTEGER,
+    "CharField": FieldType.STRING,
+    "TextField": FieldType.TEXT,
+    "IntegerField": FieldType.INTEGER,
+    "BigIntegerField": FieldType.INTEGER,
+    "SmallIntegerField": FieldType.INTEGER,
+    "PositiveIntegerField": FieldType.INTEGER,
+    "FloatField": FieldType.FLOAT,
+    "DecimalField": FieldType.FLOAT,
+    "BooleanField": FieldType.BOOLEAN,
+    "DateField": FieldType.DATE,
+    "DateTimeField": FieldType.DATETIME,
+    "TimeField": FieldType.TIME,
+    "UUIDField": FieldType.UUID,
+    "JSONField": FieldType.JSON,
+    "BinaryField": FieldType.BINARY,
+    "EmailField": FieldType.STRING,
+    "URLField": FieldType.STRING,
+    "SlugField": FieldType.STRING,
+    "FileField": FieldType.STRING,
+    "ImageField": FieldType.STRING,
+}
+
+
+class DjangoInspector(Inspector):
+    def inspect(self, model_class: type, plural: str | None = None) -> ModelSchema:
+        from django.db.models.fields import NOT_PROVIDED
+
+        meta = model_class._meta
+        fields: list[FieldSchema] = []
+
+        for f in meta.get_fields():
+            if f.many_to_many or f.one_to_many:
+                continue
+
+            field_type_name = type(f).__name__
+            field_type = DJANGO_TYPE_MAP.get(field_type_name, FieldType.STRING)
+
+            constraints = {}
+            if hasattr(f, "max_length") and f.max_length:
+                constraints["max_length"] = f.max_length
+
+            relation = None
+            is_fk = hasattr(f, "related_model") and f.related_model
+            if is_fk:
+                relation = RelationSchema(
+                    type="one_to_one" if f.one_to_one else "many_to_one",
+                    target=f.related_model.__name__,
+                )
+                target_pk = f.related_model._meta.pk
+                target_type_name = type(target_pk).__name__
+                field_type = DJANGO_TYPE_MAP.get(target_type_name, FieldType.INTEGER)
+
+            is_pk = getattr(f, "primary_key", False)
+            auto_generated = field_type_name in ("AutoField", "BigAutoField", "SmallAutoField")
+            raw_default = getattr(f, "default", NOT_PROVIDED)
+            has_real_default = raw_default is not NOT_PROVIDED and raw_default is not None
+            has_callable_default = has_real_default and callable(raw_default)
+            auto_now_add = getattr(f, "auto_now_add", False)
+            auto_now = getattr(f, "auto_now", False)
+            if is_pk and has_real_default and not auto_generated:
+                auto_generated = True
+            if has_callable_default or auto_now_add or auto_now:
+                auto_generated = True
+            required = not getattr(f, "blank", False) and not getattr(f, "null", False) and not has_real_default
+            default = raw_default if has_real_default else None
+
+            field_name = getattr(f, "attname", f.name) if is_fk else f.name
+
+            fields.append(FieldSchema(
+                name=field_name,
+                type=field_type,
+                required=required and not is_pk,
+                default=default,
+                constraints=constraints,
+                primary_key=is_pk,
+                auto_generated=auto_generated,
+                relation=relation,
+            ))
+
+        model_name = model_class.__name__
+        plural_name = plural or pluralize(model_name)
+
+        return ModelSchema(name=model_name, plural=plural_name, fields=fields)