krons 0.1.0__py3-none-any.whl

kronos/specs/adapters/dataclass_field.py

@@ -0,0 +1,246 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""DataClass SpecAdapter: Spec <-> dataclass fields/Params/DataClass.
+
+Supports bidirectional transformation for Python dataclasses:
+    - Frozen (Params): Immutable, slots=True, init=False
+    - Mutable (DataClass): Standard dataclass with slots=True
+    - Field validators via __field_validators__ mechanism
+"""
+
+from __future__ import annotations
+
+from dataclasses import MISSING as DATACLASS_MISSING
+from dataclasses import dataclass
+from dataclasses import field as dc_field
+from dataclasses import fields
+from typing import TYPE_CHECKING, Any
+
+from kronos.types._sentinel import Unset, UnsetType, is_sentinel
+
+from ..protocol import SpecAdapter
+from ..spec import Spec
+from ._utils import resolve_annotation_to_base_types
+
+if TYPE_CHECKING:
+    from kronos.types.base import DataClass, ModelConfig, Params
+
+    from ..operable import Operable
+
+
+__all__ = ("DataClassSpecAdapter",)
+
+
+def _field_to_spec(field_name: str, field_obj: Any, annotation: Any) -> Spec:
+    """Convert dataclass field to Spec, preserving defaults and type modifiers."""
+
+    base_metas = resolve_annotation_to_base_types(annotation)
+    spec = Spec(name=field_name, **base_metas)
+
+    # Handle defaults
+    if field_obj.default is not DATACLASS_MISSING:
+        spec = spec.with_default(field_obj.default)
+    elif field_obj.default_factory is not DATACLASS_MISSING:
+        spec = spec.with_default(field_obj.default_factory)
+
+    return spec
+
+
+def _make_validator_method(validators: dict[str, list[Any]], is_frozen: bool) -> Any:
+    """Create _validate method that runs field validators. Uses object.__setattr__ for frozen classes."""
+
+    def _validate_with_field_validators(self) -> None:
+        """Validate instance including field validators."""
+        super(type(self), self)._validate()
+
+        field_validators = getattr(type(self), "__field_validators__", {})
+        errors: list[Exception] = []
+
+        for fname, validator_list in field_validators.items():
+            value = getattr(self, fname, None)
+            for validator in validator_list:
+                try:
+                    result = validator(value)
+                    if result is not None and result is not value:
+                        if is_frozen:
+                            object.__setattr__(self, fname, result)
+                        else:
+                            setattr(self, fname, result)
+                except Exception as e:
+                    errors.append(ValueError(f"Validation failed for '{fname}': {e}"))
+
+        if errors:
+            raise ExceptionGroup(f"Field validation failed for {type(self).__name__}", errors)
+
+    return _validate_with_field_validators
+
+
+class DataClassSpecAdapter(SpecAdapter[dict[str, Any]]):
+    """DataClass/Params adapter: Spec → dataclass fields, Operable → DataClass/Params.
+
+    Supports both frozen (Params) and mutable (DataClass) targets with
+    optional field validators.
+
+    Usage:
+        op = Operable([
+            Spec(str, name="name", validator=validate_name),
+            Spec(int, name="age", default=0),
+        ])
+        Person = DataClassSpecAdapter.compose_structure(op, "Person", frozen=True)
+        p = Person(name="Alice", age=30)
+    """
+
+    @classmethod
+    def create_field(cls, spec: Spec) -> dict[str, Any]:
+        """Convert Spec to dataclass field kwargs (default or default_factory)."""
+        field_kwargs: dict[str, Any] = {}
+
+        default_val = spec.get("default")
+        default_factory = spec.get("default_factory")
+
+        if not is_sentinel(default_factory, {"none"}):
+            field_kwargs["default_factory"] = default_factory
+        elif not is_sentinel(default_val, {"none"}):
+            field_kwargs["default"] = default_val
+        elif spec.is_nullable:
+            field_kwargs["default"] = None
+
+        return field_kwargs
+
+    @classmethod
+    def create_field_validator(cls, spec: Spec) -> dict[str, list[Any]] | None:
+        """Extract validators from Spec. Returns {field_name: [validators]} or None."""
+        validator = spec.get("validator")
+        if is_sentinel(validator):
+            return None
+
+        field_name = spec.name or "field"
+        validators = validator if isinstance(validator, list) else [validator]
+
+        return {field_name: validators}
+
+    @classmethod
+    def compose_structure(
+        cls,
+        op: Operable,
+        name: str,
+        /,
+        *,
+        include: set[str] | UnsetType = Unset,
+        exclude: set[str] | UnsetType = Unset,
+        frozen: bool = True,
+        base_type: type | None = None,
+        doc: str | None = None,
+        model_config: ModelConfig | None = None,
+        **kwargs: Any,
+    ) -> type[Params] | type[DataClass]:
+        """Generate DataClass/Params subclass from Operable.
+
+        Args:
+            op: Operable containing Specs
+            name: Class name
+            include/exclude: Field name filters
+            frozen: True=Params (immutable), False=DataClass (mutable)
+            base_type: Custom base class (Params/DataClass subclass)
+            doc: Optional docstring
+            model_config: ModelConfig instance for sentinel/validation behavior
+
+        Returns:
+            Dynamically created dataclass with validators wired in
+        """
+        from kronos.types.base import DataClass, Params
+
+        use_specs = op.get_specs(include=include, exclude=exclude)
+
+        base = base_type if base_type is not None else (Params if frozen else DataClass)
+
+        annotations: dict[str, type] = {}
+        class_attrs: dict[str, Any] = {}
+        validators: dict[str, list[Any]] = {}
+
+        required_specs = []
+        optional_specs = []
+
+        for spec in use_specs:
+            if not spec.name:
+                continue
+            field_kwargs = cls.create_field(spec)
+            if "default" in field_kwargs or "default_factory" in field_kwargs:
+                optional_specs.append((spec, field_kwargs))
+            else:
+                required_specs.append((spec, field_kwargs))
+
+        for spec, field_kwargs in required_specs + optional_specs:
+            field_name = spec.name
+            annotations[field_name] = spec.annotation
+
+            if "default_factory" in field_kwargs:
+                class_attrs[field_name] = dc_field(default_factory=field_kwargs["default_factory"])
+            elif "default" in field_kwargs:
+                class_attrs[field_name] = field_kwargs["default"]
+
+            if v := cls.create_field_validator(spec):
+                validators.update(v)
+
+        class_dict: dict[str, Any] = {
+            "__annotations__": annotations,
+            "__module__": op.name or "__dynamic__",
+            **class_attrs,
+        }
+
+        if doc:
+            class_dict["__doc__"] = doc
+
+        if model_config is not None:
+            class_dict["_config"] = model_config
+
+        if validators:
+            class_dict["__field_validators__"] = validators
+            class_dict["_validate"] = _make_validator_method(validators, frozen)
+
+        new_cls = type(name, (base,), class_dict)
+
+        if frozen:
+            new_cls = dataclass(frozen=True, slots=True, init=False)(new_cls)
+        else:
+            new_cls = dataclass(slots=True)(new_cls)
+
+        return new_cls
+
+    @classmethod
+    def validate_instance(
+        cls, structure: type[Params] | type[DataClass], data: dict, /
+    ) -> Params | DataClass:
+        """Create DataClass/Params instance from dict data."""
+        return structure(**data)
+
+    @classmethod
+    def dump_instance(cls, instance: Params | DataClass) -> dict[str, Any]:
+        """Dump DataClass/Params instance to dict via to_dict()."""
+        return instance.to_dict()
+
+    @classmethod
+    def extract_specs(cls, structure: type[Params] | type[DataClass]) -> tuple[Spec, ...]:
+        """Extract Specs from DataClass/Params, preserving defaults and type modifiers.
+
+        Raises:
+            TypeError: If structure is not a DataClass or Params subclass
+        """
+        from kronos.types.base import DataClass, Params
+
+        if not isinstance(structure, type) or not issubclass(structure, (DataClass, Params)):
+            raise TypeError(
+                f"structure must be a DataClass or Params subclass, got {type(structure)}"
+            )
+
+        specs: list[Spec] = []
+        for f in fields(structure):
+            if f.name.startswith("_"):
+                continue
+
+            annotation = structure.__annotations__.get(f.name, Any)
+            spec = _field_to_spec(f.name, f, annotation)
+            specs.append(spec)
+
+        return tuple(specs)

kronos/specs/adapters/factory.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import functools
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from ..protocol import SpecAdapter
+
+# Supported adapter types
+AdapterType = Literal["pydantic", "sql", "dataclass"]
+
+__all__ = (
+    "get_adapter",
+    "AdapterType",
+)
+
+
+@functools.cache
+def get_adapter(adapter_name: str) -> type[SpecAdapter]:
+    """Get adapter class by name (cached).
+
+    Factory method for adapter classes. Caches to avoid repeated imports.
+
+    Args:
+        adapter_name: Adapter identifier ("pydantic", "sql", "dataclass", future: "rust")
+
+    Returns:
+        Adapter class (not instance)
+
+    Raises:
+        ValueError: If adapter not supported
+        ImportError: If adapter dependencies not installed
+    """
+    match adapter_name:
+        case "pydantic":
+            try:
+                from .pydantic_adapter import PydanticSpecAdapter
+
+                return PydanticSpecAdapter
+            except ImportError as e:
+                raise ImportError(
+                    "PydanticSpecAdapter requires Pydantic. Install with: pip install pydantic"
+                ) from e
+        case "sql":
+            from .sql_ddl import SQLSpecAdapter
+
+            return SQLSpecAdapter
+        case "dataclass":
+            from .dataclass_field import DataClassSpecAdapter
+
+            return DataClassSpecAdapter
+        # case "rust":
+        #     from .spec_adapters.rust_field import RustSpecAdapter
+        #     return RustSpecAdapter
+        case _:
+            raise ValueError(f"Unsupported adapter: {adapter_name}")

kronos/specs/adapters/pydantic_adapter.py

@@ -0,0 +1,309 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Pydantic SpecAdapter: Spec <-> Pydantic FieldInfo/BaseModel.
+
+Supports bidirectional transformation with:
+    - Field validators (field_validator decorator)
+    - Constraints (gt, ge, lt, le, min_length, max_length, pattern, etc.)
+    - Rich metadata (aliases, descriptions, examples, json_schema_extra)
+    - Type modifiers (nullable, listable)
+"""
+
+from __future__ import annotations
+
+import functools
+from typing import TYPE_CHECKING, Annotated, Any
+
+from pydantic import BaseModel, create_model, field_validator
+from pydantic.fields import FieldInfo
+from pydantic_core import PydanticUndefined
+from pydantic_core._pydantic_core import PydanticUndefinedType
+
+from kronos.specs.protocol import SpecAdapter
+from kronos.specs.spec import Spec
+from kronos.types._sentinel import Unset, UnsetType, is_sentinel, is_unset, not_sentinel
+from kronos.types.db_types import FKMeta, VectorMeta
+
+from ._utils import resolve_annotation_to_base_types
+
+if TYPE_CHECKING:
+    from kronos.specs.operable import Operable
+
+__all__ = ("PydanticSpecAdapter",)
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_FIELD_INFO_ATTRS = frozenset(
+    {
+        "alias",
+        "validation_alias",
+        "serialization_alias",
+        "title",
+        "description",
+        "examples",
+        "deprecated",
+        "frozen",
+        "json_schema_extra",
+        "discriminator",
+        "exclude",
+        "repr",
+        "init",
+        "init_var",
+        "kw_only",
+        "validate_default",
+    }
+)
+
+_CONSTRAINT_MAPPING = {
+    "Gt": "gt",
+    "Ge": "ge",
+    "Lt": "lt",
+    "Le": "le",
+    "MultipleOf": "multiple_of",
+    "MinLen": "min_length",
+    "MaxLen": "max_length",
+}
+
+
+@functools.lru_cache(maxsize=1)
+def _get_pydantic_field_params() -> set[str]:
+    """Get valid Pydantic Field() parameter names (cached)."""
+    import inspect
+
+    from pydantic import Field as PydanticField
+
+    params = set(inspect.signature(PydanticField).parameters.keys())
+    params.discard("kwargs")
+    return params
+
+
+# ---------------------------------------------------------------------------
+# FieldInfo -> Spec resolution (extract_specs direction)
+# ---------------------------------------------------------------------------
+
+
+def _is_valid_meta(v) -> bool:
+    return not_sentinel(v) and not isinstance(v, PydanticUndefinedType)
+
+
+def _ensure_annotation_from_field_info(fi: FieldInfo) -> Annotated | Any:
+    annotation = fi.annotation
+    if hasattr(fi, "metadata") and fi.metadata:
+        for meta in fi.metadata:
+            if isinstance(meta, (FKMeta, VectorMeta)):
+                annotation = Annotated[annotation, meta]
+                break
+    return annotation
+
+
+def _resolve_defaults_from_field_info(
+    fi: FieldInfo,
+) -> dict[str, Any]:
+    if getattr(fi, "default", PydanticUndefined) is not PydanticUndefined:
+        return {"default": fi.default}
+    if (
+        _df := getattr(fi, "default_factory", PydanticUndefined)
+    ) is not PydanticUndefined and not_sentinel(_df, {"none", "empty"}):
+        return {"default_factory": _df}
+    return {}
+
+
+def _resolve_constraint_metas(metadata: Any) -> dict[str, Any]:
+    all_wanted = set(_CONSTRAINT_MAPPING.keys()) | {
+        "Strict",
+        "_PydanticGeneralMetadata",
+    }
+    out = {}
+
+    for constraint in metadata:
+        con_type = type(constraint).__name__
+        if con_type not in all_wanted:
+            continue
+
+        _k, _v = Unset, Unset
+        match con_type:
+            case "Gt" | "Ge" | "Lt" | "Le" | "MultipleOf" | "MinLen" | "MaxLen":
+                _k = _CONSTRAINT_MAPPING[con_type]
+                _v = getattr(constraint, _k, Unset)
+            case "Strict":
+                _k, _v = "strict", getattr(constraint, "strict", True)
+            case "_PydanticGeneralMetadata":
+                pattern = getattr(constraint, "pattern", Unset)
+                if is_sentinel(pattern, {"none", "empty"}):
+                    _k, _v = "pattern", pattern
+                strict = getattr(constraint, "strict", Unset)
+                if is_sentinel(strict, {"none", "empty"}):
+                    _k, _v = "strict", strict
+
+        if not is_unset(_k) and _is_valid_meta(_v):
+            out[_k] = _v
+
+    return out
+
+
+def _create_spec_metas_from_field_info(field_name: str, field_info: FieldInfo) -> dict:
+    annotation = _ensure_annotation_from_field_info(field_info)
+    base_metas = resolve_annotation_to_base_types(annotation)
+    defaults = _resolve_defaults_from_field_info(field_info)
+    updates = {
+        attr: v
+        for attr in _FIELD_INFO_ATTRS
+        if _is_valid_meta(v := getattr(field_info, attr, Unset))
+    }
+    if not_sentinel(
+        (meta := getattr(field_info, "metadata", Unset)),
+        {"none", "empty"},
+    ):
+        updates.update(_resolve_constraint_metas(meta))
+
+    return {"name": field_name, **defaults, **updates, **base_metas}
+
+
+# ---------------------------------------------------------------------------
+# PydanticSpecAdapter
+# ---------------------------------------------------------------------------
+
+
+class PydanticSpecAdapter(SpecAdapter[FieldInfo]):
+    @classmethod
+    def create_field(cls, spec: Spec) -> FieldInfo:
+        """Convert Spec to Pydantic FieldInfo with annotation set."""
+        from pydantic import Field as PydanticField
+
+        pydantic_field_params = _get_pydantic_field_params()
+        field_kwargs: dict[str, Any] = {}
+
+        if not is_sentinel(spec.metadata, {"none"}):
+            for meta in spec.metadata:
+                if meta.key == "default":
+                    if callable(meta.value):
+                        field_kwargs["default_factory"] = meta.value
+                    else:
+                        field_kwargs["default"] = meta.value
+                elif meta.key == "validator":
+                    continue
+                elif meta.key in pydantic_field_params:
+                    if not_sentinel(meta.value):
+                        field_kwargs[meta.key] = meta.value
+                elif meta.key in {"nullable", "listable"}:
+                    pass
+                else:
+                    if isinstance(meta.value, type):
+                        continue
+                    if "json_schema_extra" not in field_kwargs:
+                        field_kwargs["json_schema_extra"] = {}
+                    field_kwargs["json_schema_extra"][meta.key] = meta.value
+
+        # Nullable fields default to None unless explicitly required
+        is_required = any(m.key == "required" and m.value for m in spec.metadata)
+        if (
+            spec.is_nullable
+            and "default" not in field_kwargs
+            and "default_factory" not in field_kwargs
+            and not is_required
+        ):
+            field_kwargs["default"] = None
+
+        field_info = PydanticField(**field_kwargs)
+        field_info.annotation = spec.annotation
+
+        return field_info
+
+    @classmethod
+    def create_field_validator(cls, spec: Spec) -> dict[str, Any] | None:
+        """Create Pydantic field_validator from Spec metadata. Returns None if no validator."""
+        v = spec.get("validator")
+        if is_sentinel(v):
+            return None
+        _func = field_validator(spec.name, check_fields=False)(v)
+        return {f"_{spec.name}_validator": _func}
+
+    @classmethod
+    def compose_structure(
+        cls,
+        op: Operable,
+        name: str,
+        /,
+        *,
+        include: set[str] | UnsetType = Unset,
+        exclude: set[str] | UnsetType = Unset,
+        base_type: type[BaseModel] | UnsetType = Unset,
+        doc: str | UnsetType = Unset,
+    ) -> type[BaseModel]:
+        """Generate Pydantic BaseModel subclass from Operable.
+
+        Args:
+            op: Operable containing Specs
+            name: Model class name
+            include/exclude: Field name filters
+            base_type: Base class for the model
+            doc: Docstring for the model
+
+        Returns:
+            Dynamically created BaseModel subclass with validators
+        """
+        use_specs = op.get_specs(include=include, exclude=exclude)
+        use_fields = {i.name: cls.create_field(i) for i in use_specs if i.name}
+
+        field_definitions = {
+            field_name: (field_info.annotation, field_info)
+            for field_name, field_info in use_fields.items()
+        }
+
+        validators = {}
+        for spec in use_specs:
+            if spec.name and (validator := cls.create_field_validator(spec)):
+                validators.update(validator)
+
+        if validators:
+            base_with_validators = type(
+                f"{name}Base",
+                (base_type or BaseModel,),
+                validators,
+            )
+            actual_base = base_with_validators
+        else:
+            actual_base = base_type or BaseModel
+
+        model_cls: type[BaseModel] = create_model(
+            name,
+            __base__=actual_base,
+            __doc__=doc,
+            **field_definitions,
+        )
+
+        model_cls.model_rebuild()
+        return model_cls
+
+    @classmethod
+    def validate_instance(cls, structure: type[BaseModel], data: dict, /) -> BaseModel:
+        """Validate dict into BaseModel instance via model_validate."""
+        return structure.model_validate(data)
+
+    @classmethod
+    def dump_instance(cls, instance: BaseModel) -> dict[str, Any]:
+        """Dump BaseModel instance to dict via model_dump."""
+        return instance.model_dump()
+
+    @classmethod
+    def extract_specs(cls, structure: type[BaseModel]) -> tuple[Spec, ...]:
+        """Extract Specs from Pydantic model, preserving constraints and metadata.
+
+        Raises:
+            TypeError: If structure is not a BaseModel subclass
+        """
+        if not isinstance(structure, type) or not issubclass(structure, BaseModel):
+            raise TypeError(
+                f"structure must be a Pydantic BaseModel subclass, got {type(structure)}"
+            )
+
+        specs: list[Spec] = []
+        for field_name, field_info in structure.model_fields.items():
+            metas = _create_spec_metas_from_field_info(field_name, field_info)
+            specs.append(Spec(**metas))
+
+        return tuple(specs)