fastschema 0.1.3__py3-none-any.whl

fastschema/__init__.py

@@ -0,0 +1,19 @@
+"""
+framework - Class-based routing with dynamic Pydantic model generation for FastAPI.
+
+Routes defined inside the class with @route decorator.
+Typed input via UserRoute.schema() — request body auto-validated.
+SelfDerivedModel for bulk operations — derive schemas from own fields.
+"""
+
+from .core import (
+    FieldConfig, Chain, RouteField, FieldInfo, SelfDerivedModel,
+    RouteBase, ModelFactory, RouteMetaclass,
+    route, route_factory,
+)
+
+__all__ = [
+    'FieldConfig', 'Chain', 'RouteField', 'FieldInfo', 'SelfDerivedModel',
+    'RouteBase', 'ModelFactory', 'RouteMetaclass',
+    'route', 'route_factory',
+]

fastschema/core/__init__.py

@@ -0,0 +1,13 @@
+from .field_config import FieldConfig, Chain
+from .route_field import RouteField, FieldInfo
+from .self_derived import SelfDerivedModel
+from .route_base import RouteBase
+from .model_factory import ModelFactory
+from .metaclass import RouteMetaclass
+from .route_decorator import route, route_factory
+
+__all__ = [
+    'FieldConfig', 'Chain', 'RouteField', 'FieldInfo', 'SelfDerivedModel',
+    'RouteBase', 'ModelFactory', 'RouteMetaclass',
+    'route', 'route_factory',
+]

fastschema/core/field_config.py

@@ -0,0 +1,49 @@
+"""FieldConfig - Base class for schema type configurations."""
+
+from __future__ import annotations
+from typing import Any, Callable
+
+
+_UNSET = object()
+
+
+class Chain:
+    """Compose multiple functions to run sequentially on a field value."""
+
+    def __init__(self, *funcs: Callable):
+        self.funcs = funcs
+
+    def __call__(self, v: Any) -> Any:
+        result = v
+        for func in self.funcs:
+            result = func(result)
+        return result
+
+
+class FieldConfig:
+    """Extend to define schema types."""
+
+    required: bool = False
+    default: Any = _UNSET
+    default_factory: Callable | None = None
+    alias: str | None = None
+    description: str | None = None
+    type_override: type | None = None
+    exclude: bool = False
+    frozen: bool = False
+    apply_func: Callable | None = None
+    before: bool = True  # True = before validators, False = after validators
+    metadata: dict | None = None
+
+    def __init__(self, **overrides):
+        for key, value in overrides.items():
+            if hasattr(self, key) or key in self.__class__.__dict__:
+                setattr(self, key, value)
+
+    def __repr__(self):
+        attrs = {k: v for k, v in self.__dict__.items() if v is not _UNSET and v is not None and v is not False}
+        return f"{self.__name__}({attrs})"
+
+    @property
+    def __name__(self):
+        return self.__class__.__name__

fastschema/core/metaclass.py

@@ -0,0 +1,96 @@
+"""RouteMetaclass - Collects fields and discovers schema types."""
+
+from __future__ import annotations
+import sys
+import typing
+from typing import get_type_hints, ClassVar, get_origin, get_args
+from .route_field import RouteField, FieldInfo
+
+try:
+    from sqlmodel.main import SQLModelMetaclass as _BaseMetaclass
+except ImportError:
+    from pydantic._internal._model_construction import ModelMetaclass as _BaseMetaclass
+
+
+def _resolve_annotations(cls: type) -> dict[str, type]:
+    try:
+        module = sys.modules.get(cls.__module__)
+        if not module:
+            return {}
+        return get_type_hints(cls, localns=vars(module))
+    except Exception:
+        return getattr(cls, '__annotations__', {})
+
+
+def _has_pydantic_base(bases: tuple) -> bool:
+    for base in bases:
+        if getattr(base, '__pydantic_complete__', False):
+            return True
+        if getattr(base, '__pydantic_validator__', None) is not None:
+            return True
+    return False
+
+
+def _is_classvar(annotation) -> bool:
+    origin = get_origin(annotation)
+    if origin is ClassVar:
+        return True
+    if isinstance(annotation, str):
+        return 'ClassVar' in annotation
+    return False
+
+
+def _unwrap_classvar(annotation):
+    if _is_classvar(annotation):
+        args = get_args(annotation)
+        if args:
+            return args[0]
+        return str
+    return annotation
+
+
+class RouteMetaclass(_BaseMetaclass):
+    def __new__(mcs, cls_name, bases, namespace, **kwargs):
+        if _has_pydantic_base(bases):
+            cls = super().__new__(mcs, cls_name, bases, namespace, **kwargs)
+        else:
+            cls = type.__new__(mcs, cls_name, bases, namespace)
+
+        fields = {}
+        for base in bases:
+            bf = getattr(base, '_fields', None)
+            if bf:
+                fields.update(bf)
+
+        resolved = _resolve_annotations(cls)
+
+        # Collect RouteField entries
+        for attr_name, annotation in resolved.items():
+            attr_value = namespace.get(attr_name)
+            if isinstance(attr_value, RouteField):
+                # Unwrap ClassVar[str] -> str for the schema
+                field_type = _unwrap_classvar(annotation) if _is_classvar(annotation) else annotation
+                fields[attr_name] = attr_value.to_field_info(attr_name, field_type)
+
+        # Collect ClassVar fields (not RouteField, but user wants them in schemas)
+        for attr_name, annotation in resolved.items():
+            if attr_name in fields:
+                continue
+            if _is_classvar(annotation) and attr_name in namespace:
+                inner_type = _unwrap_classvar(annotation)
+                field_info = FieldInfo(
+                    name=attr_name,
+                    annotation=inner_type,
+                    default=namespace.get(attr_name, None),
+                    configs={},
+                )
+                fields[attr_name] = field_info
+
+        cls._fields = fields
+
+        schema_types = set()
+        for info in fields.values():
+            schema_types.update(info.configs.keys())
+        cls._schema_types = schema_types
+
+        return cls

fastschema/core/model_factory.py

@@ -0,0 +1,189 @@
+"""ModelFactory - Generates Pydantic models from FieldInfo + schema type."""
+
+from __future__ import annotations
+from types import NoneType
+from typing import Literal
+from pydantic import BaseModel, Field, create_model, ConfigDict
+from pydantic import field_validator as pv_field_validator
+from pydantic import model_validator as pv_model_validator
+from .route_field import FieldInfo
+from .self_derived import SelfDerivedModel
+from .field_config import _UNSET
+
+
+class ModelFactory:
+
+    @staticmethod
+    def create(fields, schema_type, model_name="GeneratedModel",
+               forbid_extra=True, include_fields=None, exclude_fields=None,
+               as_literal=False, route_cls=None) -> type[BaseModel]:
+        skip = set(exclude_fields or [])
+        only = set(include_fields) if include_fields else None
+
+        if as_literal:
+            names = [n for n, info in fields.items()
+                     if n not in skip and (only is None or n in only)
+                     and info.has_config(schema_type)
+                     and not info.get_config(schema_type).exclude]
+            return Literal[tuple(names)]
+
+        model_fields = {}
+        apply_funcs = {}
+        for name, info in fields.items():
+            if name in skip or (only is not None and name not in only):
+                continue
+            config = info.get_config(schema_type)
+            if config is None or config.exclude:
+                continue
+
+            ftype = config.type_override or info.annotation
+
+            if isinstance(ftype, str):
+                import typing
+                ftype = typing._eval_type(typing.ForwardRef(ftype), globals(), None)
+
+            fdefault = ModelFactory._resolve_default(config, info)
+
+            # Resolve SelfDerivedModel
+            if isinstance(fdefault, SelfDerivedModel) and route_cls:
+                ftype, fdefault = ModelFactory._resolve_self_derived(fdefault, route_cls)
+
+            if fdefault is not None and fdefault is not ...:
+                if NoneType not in (getattr(ftype, '__args__', ()) or ()):
+                    ftype = ftype | None
+
+            # Start with RouteField's Pydantic Field kwargs
+            fk = dict(info.field_info_kwargs) if info.field_info_kwargs else {}
+
+            # Remove 'default' from kwargs — we pass it as positional arg
+            fk.pop('default', None)
+            fk.pop('default_factory', None)
+
+            # Config-level overrides take precedence
+            if info.alias and 'alias' not in fk:
+                fk['alias'] = info.alias
+            desc = config.description or info.description
+            if desc and 'description' not in fk:
+                fk['description'] = desc
+            if config.frozen and 'frozen' not in fk:
+                fk['frozen'] = True
+            if config.metadata:
+                fk.update(config.metadata)
+
+            # Pass constraint kwargs (max_length, min_length, gt, etc.) from RouteField
+            field_metadata = info.metadata if hasattr(info, 'metadata') and info.metadata else None
+            if field_metadata and isinstance(field_metadata, dict):
+                fk.update(field_metadata)
+
+            model_fields[name] = (ftype, Field(fdefault, **fk))
+
+            if config.apply_func is not None:
+                func = config.apply_func
+                if hasattr(func, '__func__'):
+                    func = func.__func__
+                apply_funcs[name] = (func, 'before' if config.before else 'after')
+
+        validator_base = ModelFactory._create_validator_base(route_cls, fields, schema_type, apply_funcs)
+        model_module = route_cls.__module__ if route_cls else __name__
+
+        if validator_base:
+            model = create_model(
+                model_name,
+                __base__=validator_base,
+                __config__=ConfigDict(extra='forbid' if forbid_extra else 'ignore'),
+                __module__=model_module,
+                **model_fields,
+            )
+        else:
+            model = create_model(
+                model_name,
+                __config__=ConfigDict(extra='forbid' if forbid_extra else 'ignore'),
+                __module__=model_module,
+                **model_fields,
+            )
+
+        try:
+            model.model_rebuild(force=True)
+        except Exception:
+            pass
+
+        return model
+
+    @staticmethod
+    def _create_validator_base(route_cls, fields, schema_type, apply_funcs=None):
+        """Create a base class with validators from route_cls and apply_func."""
+        apply_funcs = apply_funcs or {}
+        namespace = {}
+
+        # Collect validators from route_cls
+        if route_cls and getattr(route_cls, '__pydantic_complete__', False):
+            decorators = getattr(route_cls, '__pydantic_decorators__', None)
+            if decorators:
+                for name, dec in decorators.field_validators.items():
+                    func = getattr(route_cls, name, None)
+                    if func is None:
+                        continue
+                    raw_func = getattr(func, '__func__', func)
+                    mode = dec.info.mode or 'before'
+                    for field_name in dec.info.fields:
+                        validator_name = f'_validator_{field_name}_{mode}'
+                        namespace[validator_name] = pv_field_validator(field_name, mode=mode, check_fields=False)(raw_func)
+
+                for name, dec in decorators.model_validators.items():
+                    if name == 'fill_back_refs':
+                        continue
+                    func = getattr(route_cls, name, None)
+                    if func is None:
+                        continue
+                    raw_func = getattr(func, '__func__', func)
+                    namespace[f'_model_validator_{name}'] = pv_model_validator(mode=dec.info.mode)(raw_func)
+
+        # Create validators from apply_func
+        for field_name, (func, mode) in apply_funcs.items():
+            validator_name = f'_apply_func_{field_name}_{mode}'
+            def _make_validator(f):
+                def validator(cls, v):
+                    return f(v)
+                return validator
+            v = _make_validator(func)
+            v.__qualname__ = validator_name
+            namespace[validator_name] = pv_field_validator(field_name, mode=mode, check_fields=False)(v)
+
+        if namespace:
+            base_name = f'{route_cls.__name__}Validators' if route_cls else 'Validators'
+            return type(base_name, (BaseModel,), namespace)
+        return None
+
+    @staticmethod
+    def _resolve_default(config, info):
+        if config.default is not _UNSET:
+            return config.default
+        if config.default_factory is not None:
+            return config.default_factory
+        if info.default is not _UNSET:
+            return info.default
+        if info.default_factory is not None:
+            return info.default_factory
+        if config.required:
+            return ...
+        return ...
+
+    @staticmethod
+    def _resolve_self_derived(sdm, route_cls):
+        derived = route_cls.schema(
+            sdm.schema,
+            include_fields=sdm.include_fields,
+            exclude_fields=sdm.exclude_fields,
+        )
+        field_type = list[derived]
+        default = [] if not sdm.is_optional else None
+        return field_type, default
+
+    @staticmethod
+    def field_names(fields, schema_type, include=None, exclude=None):
+        skip = set(exclude or [])
+        only = set(include) if include else None
+        return [n for n, info in fields.items()
+                if n not in skip and (only is None or n in only)
+                and info.has_config(schema_type)
+                and not info.get_config(schema_type).exclude]

fastschema/core/route_base.py

@@ -0,0 +1,70 @@
+"""RouteBase - Base class with schema generation."""
+
+from __future__ import annotations
+from typing import ClassVar
+from .metaclass import RouteMetaclass
+from .route_field import FieldInfo, RouteField
+from .field_config import FieldConfig
+from .model_factory import ModelFactory
+from .self_derived import SelfDerivedModel
+from pydantic import BaseModel
+
+
+class RouteBase(BaseModel,metaclass=RouteMetaclass):
+    """Base class. Routes defined inside with @route decorator.
+
+        class UserRoute(RouteBase):
+            name: str = RouteField(add=Add(), edit=Edit())
+
+            @route(path="/users", method="POST")
+            async def create_user(cls, request, data: UserRoute.schema("add")):
+                ...
+    """
+
+    _fields: ClassVar[dict[str, FieldInfo]] = {}
+    _schema_types: ClassVar[set[str]] = set()
+    _route_group: ClassVar[str] = ""
+
+    @classmethod
+    def schema(cls, schema_type: str, *, name: str | None = None,
+               include_fields: list[str] | None = None,
+               exclude_fields: list[str] | None = None,
+               forbid_extra: bool = True, as_literal: bool = False) -> type[BaseModel]:
+        """Generate a Pydantic model for the given schema type."""
+        if schema_type not in cls._schema_types:
+            raise ValueError(
+                f"Unknown schema type '{schema_type}'. Available: {sorted(cls._schema_types)}"
+            )
+        model_name = name or f"{cls.__name__}_{schema_type.title()}"
+        return ModelFactory.create(
+            fields=cls._fields, schema_type=schema_type,
+            model_name=model_name, forbid_extra=forbid_extra,
+            include_fields=include_fields, exclude_fields=exclude_fields,
+            as_literal=as_literal, route_cls=cls,
+        )
+
+    @classmethod
+    def schema_fields(cls, schema_type: str) -> list[str]:
+        return ModelFactory.field_names(cls._fields, schema_type)
+
+    @classmethod
+    def all_fields(cls) -> dict[str, FieldInfo]:
+        return dict(cls._fields)
+
+    @classmethod
+    def field_names(cls) -> list[str]:
+        return list(cls._fields.keys())
+
+    @classmethod
+    def schema_types(cls) -> list[str]:
+        return sorted(cls._schema_types)
+
+    @classmethod
+    def from_schema(cls, data):
+        """Create an instance from a schema model without re-validating nested models."""
+        return cls.model_validate(data, from_attributes=True)
+
+    @classmethod
+    def field_config_for(cls, field_name: str, schema_type: str) -> FieldConfig | None:
+        info = cls._fields.get(field_name)
+        return info.get_config(schema_type) if info else None

fastschema/core/route_decorator.py

@@ -0,0 +1,70 @@
+"""route decorator and route_factory."""
+
+from __future__ import annotations
+from typing import Callable, Literal
+from fastapi import APIRouter, status
+
+
+class _RouteInfo:
+    __slots__ = ('path', 'method', 'name', 'description', 'status_code', 'tags')
+
+    def __init__(self, path, method, name, description, status_code, tags):
+        self.path = path
+        self.method = method
+        self.name = name
+        self.description = description
+        self.status_code = status_code
+        self.tags = tags
+
+
+def route(
+    path: str,
+    method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'] = 'GET',
+    name: str | None = None,
+    description: str | None = None,
+    status_code: int = status.HTTP_200_OK,
+    tags: list[str] | None = None,
+) -> Callable:
+    """Decorator to mark a method as a route endpoint."""
+    def decorator(func: Callable) -> Callable:
+        func._route_info = _RouteInfo(
+            path=path, method=method,
+            name=name or func.__name__,
+            description=description,
+            status_code=status_code,
+            tags=tags or [],
+        )
+        return func
+    return decorator
+
+
+def route_factory(*route_classes: type) -> APIRouter:
+    """Collect all @route methods from Route classes into a FastAPI APIRouter."""
+    router = APIRouter()
+
+    for cls in route_classes:
+        default_tags = [getattr(cls, '_route_group', None) or cls.__name__]
+
+        for attr_name in dir(cls):
+            attr = getattr(cls, attr_name, None)
+            if attr is None:
+                continue
+
+            func = getattr(attr, '__func__', attr)
+            info = getattr(func, '_route_info', None)
+            if info is None:
+                continue
+
+            tags = info.tags if info.tags else default_tags
+
+            router.add_api_route(
+                path=info.path,
+                endpoint=attr,
+                methods=[info.method],
+                name=info.name,
+                description=info.description,
+                status_code=info.status_code,
+                tags=tags,
+            )
+
+    return router

fastschema/core/route_field.py

@@ -0,0 +1,135 @@
+"""RouteField and FieldInfo."""
+
+from __future__ import annotations
+from typing import Any, Callable
+from pydantic.fields import FieldInfo as PydanticFieldInfo
+from .field_config import FieldConfig, _UNSET
+
+
+# Pydantic FieldInfo attribute names (to separate from schema_configs)
+_PYDANTIC_FIELD_ATTRS = frozenset(PydanticFieldInfo.__slots__)
+
+
+class FieldInfo:
+    __slots__ = ('name', 'annotation', 'default', 'default_factory', 'configs',
+                 'db_field', 'alias', 'description', 'field_info_kwargs', 'metadata')
+
+    def __init__(self, name, annotation, default=_UNSET, default_factory=None,
+                 configs=None, db_field=None, alias=None, description=None,
+                 field_info_kwargs=None, metadata=None):
+        self.name = name
+        self.annotation = annotation
+        self.default = default
+        self.default_factory = default_factory
+        self.configs = configs or {}
+        self.db_field = db_field or alias or name
+        self.alias = alias
+        self.description = description
+        self.field_info_kwargs = field_info_kwargs or {}
+        self.metadata = metadata
+
+    def get_config(self, schema_type: str) -> FieldConfig | None:
+        return self.configs.get(schema_type)
+
+    def has_config(self, schema_type: str) -> bool:
+        return schema_type in self.configs
+
+
+class RouteField(PydanticFieldInfo):
+    """Declarative field with per-schema configs.
+
+    Inherits from Pydantic's FieldInfo, so it works in both RouteBase and BaseModel:
+
+        # In RouteBase — schema configs work
+        class UserRoute(RouteBase):
+            title: str = RouteField(add=Add(), edit=Edit())
+
+        # In BaseModel — Pydantic Field params work
+        class MyModel(BaseModel):
+            title: str = RouteField(alias="x", description="test")
+    """
+
+    def __init__(self, default: Any = _UNSET, *, default_factory: Callable | None = None,
+                 alias: str | None = None, validation_alias: str | None = None,
+                 serialization_alias: str | None = None,
+                 description: str | None = None, title: str | None = None,
+                 exclude: bool = False, frozen: bool = False,
+                 deprecated: str | None = None,
+                 json_schema_extra: dict | None = None,
+                 validate_default: bool = False,
+                 repr: bool = True,
+                 **kwargs: Any):
+        # Extract schema_configs (FieldConfig instances) from all kwargs
+        self.schema_configs = {k: v for k, v in kwargs.items() if isinstance(v, FieldConfig)}
+
+        # Build kwargs for Pydantic FieldInfo
+        # These are the params Pydantic FieldInfo stores as direct attributes
+        pydantic_kwargs = {}
+        if default is not _UNSET:
+            pydantic_kwargs['default'] = default
+        if default_factory is not None:
+            pydantic_kwargs['default_factory'] = default_factory
+        if alias is not None:
+            pydantic_kwargs['alias'] = alias
+        if validation_alias is not None:
+            pydantic_kwargs['validation_alias'] = validation_alias
+        if serialization_alias is not None:
+            pydantic_kwargs['serialization_alias'] = serialization_alias
+        if description is not None:
+            pydantic_kwargs['description'] = description
+        if title is not None:
+            pydantic_kwargs['title'] = title
+        if exclude:
+            pydantic_kwargs['exclude'] = exclude
+        if frozen:
+            pydantic_kwargs['frozen'] = frozen
+        if deprecated is not None:
+            pydantic_kwargs['deprecated'] = deprecated
+        if json_schema_extra is not None:
+            pydantic_kwargs['json_schema_extra'] = json_schema_extra
+        if validate_default:
+            pydantic_kwargs['validate_default'] = validate_default
+        if not repr:
+            pydantic_kwargs['repr'] = repr
+
+        # Pass constraint kwargs (min_length, max_length, gt, ge, lt, le, pattern, etc.)
+        # These are stored in metadata by Pydantic
+        for k, v in kwargs.items():
+            if k not in self.schema_configs and k not in pydantic_kwargs:
+                pydantic_kwargs[k] = v
+
+        super().__init__(**pydantic_kwargs)
+
+    def to_field_info(self, name: str, annotation: type) -> FieldInfo:
+        return FieldInfo(
+            name=name, annotation=annotation,
+            default=self.default, default_factory=self.default_factory,
+            configs=self.schema_configs,
+            alias=getattr(self, 'alias', None),
+            description=getattr(self, 'description', None),
+            field_info_kwargs=self._field_info_kwargs(),
+            metadata=self._constraint_kwargs(),
+        )
+
+    def _field_info_kwargs(self) -> dict:
+        kwargs = {}
+        # Only include public FieldInfo attributes, skip internal ones
+        _skip = {'_original_assignment', '_attributes_set', '_original_annotation',
+                 '_qualifiers', '_complete', '_final', 'metadata'}
+        for attr in _PYDANTIC_FIELD_ATTRS:
+            if attr in _skip:
+                continue
+            val = getattr(self, attr, None)
+            if val is not None and val is not False and val != []:
+                kwargs[attr] = val
+        return kwargs
+
+    def _constraint_kwargs(self) -> dict:
+        """Return constraint kwargs (max_length, min_length, gt, ge, lt, le, etc.) for Field()."""
+        constraints = {}
+        for item in (self.metadata or []):
+            for attr in ('max_length', 'min_length', 'gt', 'ge', 'lt', 'le',
+                         'multiple_of', 'pattern'):
+                if hasattr(item, attr):
+                    constraints[attr] = getattr(item, attr)
+        return constraints

fastschema/core/self_derived.py

@@ -0,0 +1,27 @@
+"""SelfDerivedModel - Derive a field's schema from the route's own fields."""
+
+from __future__ import annotations
+
+
+class SelfDerivedModel:
+    """Metadata for a field whose schema is derived from the route's own fields.
+
+        class UserRoute(RouteBase):
+            name: str = RouteField(add=Add(), edit=Edit())
+            items: list = RouteField(
+                bulk_add=BulkAddConfig(
+                    default=SelfDerivedModel(schema='add', exclude_fields=['email'])
+                )
+            )
+    """
+
+    def __init__(self, schema: str, is_optional: bool = True, format: str = 'model',
+                 include_fields: list[str] | None = None, exclude_fields: list[str] | None = None):
+        self.schema = schema
+        self.is_optional = is_optional
+        self.format = format
+        self.include_fields = include_fields
+        self.exclude_fields = exclude_fields
+
+    def __repr__(self):
+        return f"SelfDerivedModel(schema={self.schema!r}, include={self.include_fields}, exclude={self.exclude_fields})"