grimoire-model 0.2.0__py3-none-any.whl

grimoire_model/__init__.py

@@ -0,0 +1,260 @@
+"""
+Grimoire Model Package
+
+A dict-like model system with schema validation, derived fields, and inheritance
+designed for integration with grimoire-context.
+
+Key Features:
+- Dict-like interface (MutableMapping)
+- Schema validation with Pydantic
+- Reactive derived fields with dependency tracking
+- Model inheritance support
+- Template-based field expressions using Jinja2
+- Immutable operations with pyrsistent
+- Dependency injection for extensibility
+
+Example Usage:
+    from grimoire_model import GrimoireModel, ModelDefinition, create_model
+
+    # Define model schema
+    character_def = ModelDefinition(
+        id="character",
+        name="Player Character",
+        attributes={
+            "name": {"type": "str", "required": True},
+            "level": {"type": "int", "default": 1},
+            "hp": {"type": "int", "default": 8},
+            "max_hp": {"type": "int", "derived": "{{ level * 8 }}"}
+        }
+    )
+
+    # Create model instance
+    character = create_model(character_def, {"name": "Aragorn", "level": 5})
+
+    # Use as dict
+    character['level'] = 6  # Automatically updates max_hp derived field
+    print(character['max_hp'])  # 48
+
+    # Works with grimoire-context
+    from grimoire_context import GrimoireContext
+    context = GrimoireContext({'character': character})
+    context.set_variable('character.level', 7)
+"""
+
+__version__ = "0.2.0"
+__author__ = "The Wyrd One"
+__email__ = "wyrdbound@proton.me"
+
+# Core exports
+from .core.exceptions import (
+    ConfigurationError,
+    DependencyError,
+    GrimoireModelError,
+    InheritanceError,
+    ModelValidationError,
+    TemplateResolutionError,
+)
+from .core.model import (
+    GrimoireModel,
+    create_model,
+)
+from .core.registry import (
+    ModelRegistry,
+    clear_registry,
+    get_default_registry,
+    get_model,
+    get_model_registry,  # Kept for backward compatibility
+    register_model,
+)
+from .core.schema import (
+    AttributeDefinition,
+    ModelDefinition,
+    ValidationRule,
+)
+
+# Logging configuration
+from .logging import clear_logger_injection, get_logger, inject_logger, logger
+from .resolvers.derived import (
+    BatchedDerivedFieldResolver,
+    DependencyInfo,
+    DerivedFieldResolver,
+    ObservableValue,
+    create_derived_field_resolver,
+)
+
+# Resolver exports
+from .resolvers.template import (
+    CachingTemplateResolver,
+    Jinja2TemplateResolver,
+    ModelContextTemplateResolver,
+    TemplateResolver,
+    create_template_resolver,
+)
+
+# Utility exports
+from .utils.inheritance import resolve_model_inheritance
+from .utils.paths import (
+    delete_nested_value,
+    flatten_dict,
+    get_nested_value,
+    has_nested_value,
+    set_nested_value,
+    unflatten_dict,
+)
+
+# Validation exports
+from .validation.validators import (
+    EnumValidator,
+    LengthValidator,
+    PatternValidator,
+    RangeValidator,
+    RequiredValidator,
+    TypeValidator,
+    ValidationEngine,
+    get_validation_engine,
+    validate_field_value,
+    validate_model_data,
+)
+
+__all__ = [
+    # Core classes
+    "GrimoireModel",
+    "ModelDefinition",
+    "AttributeDefinition",
+    "ValidationRule",
+    # Factory functions
+    "create_model",
+    "create_template_resolver",
+    "create_derived_field_resolver",
+    # Registry
+    "ModelRegistry",
+    "get_default_registry",
+    "get_model_registry",  # Backward compatibility
+    "clear_registry",
+    "register_model",
+    "get_model",
+    # Logging
+    "logger",
+    "get_logger",
+    "inject_logger",
+    "clear_logger_injection",
+    # Exceptions
+    "GrimoireModelError",
+    "ModelValidationError",
+    "TemplateResolutionError",
+    "InheritanceError",
+    "DependencyError",
+    "ConfigurationError",
+    # Resolvers
+    "TemplateResolver",
+    "Jinja2TemplateResolver",
+    "ModelContextTemplateResolver",
+    "CachingTemplateResolver",
+    "DerivedFieldResolver",
+    "BatchedDerivedFieldResolver",
+    "ObservableValue",
+    "DependencyInfo",
+    # Utilities
+    "resolve_model_inheritance",
+    "get_nested_value",
+    "set_nested_value",
+    "has_nested_value",
+    "delete_nested_value",
+    "flatten_dict",
+    "unflatten_dict",
+    # Validators
+    "TypeValidator",
+    "RangeValidator",
+    "EnumValidator",
+    "RequiredValidator",
+    "PatternValidator",
+    "LengthValidator",
+    "ValidationEngine",
+    "validate_field_value",
+    "validate_model_data",
+    "get_validation_engine",
+]
+
+# Package metadata
+__meta__ = {
+    "name": "grimoire-model",
+    "version": __version__,
+    "description": (
+        "Dict-like model system with validation and derived fields for Grimoire"
+    ),
+    "long_description": __doc__,
+    "author": __author__,
+    "author_email": __email__,
+    "license": "MIT",
+    "url": "https://github.com/wyrdbound/grimoire-model",
+    "classifiers": [
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Topic :: Games/Entertainment :: Role-Playing",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+    ],
+    "keywords": "gaming rpg tabletop model validation schema",
+    "python_requires": ">=3.8",
+    "install_requires": [
+        "pydantic>=2.0.0",
+        "pyrsistent>=0.19.0",
+        "jinja2>=3.1.0",
+        "pyyaml>=6.0",
+    ],
+    "extras_require": {
+        "dev": [
+            "pytest>=7.0.0",
+            "pytest-cov>=4.0.0",
+            "ruff>=0.1.0",
+            "mypy>=1.0.0",
+            "black>=22.0.0",
+        ],
+        "docs": [
+            "sphinx>=4.0.0",
+            "sphinx-rtd-theme>=1.0.0",
+            "sphinxcontrib-napoleon>=0.7",
+        ],
+        "test": [
+            "pytest>=7.0.0",
+            "pytest-cov>=4.0.0",
+            "pytest-mock>=3.0.0",
+            "hypothesis>=6.0.0",
+        ],
+    },
+}
+
+
+# Integration helpers for grimoire-context
+def register_with_grimoire_context():
+    """Register GrimoireModel as a compatible value type with grimoire-context.
+
+    This function should be called if you want seamless integration between
+    grimoire-model and grimoire-context packages.
+    """
+    try:
+        from grimoire_context import GrimoireContext  # type: ignore[import-not-found]
+
+        # Register our model as a compatible dict-like type
+        if hasattr(GrimoireContext, "register_dict_like_type"):
+            GrimoireContext.register_dict_like_type(GrimoireModel)  # type: ignore
+
+        return True
+    except ImportError:
+        # grimoire-context not available
+        return False
+
+
+# Optional auto-registration
+try:
+    # Try to register automatically if grimoire-context is available
+    register_with_grimoire_context()
+except Exception:
+    # Silently ignore registration failures
+    pass

grimoire_model/core/__init__.py

@@ -0,0 +1 @@
+"""Core components of grimoire-model package."""

grimoire_model/core/exceptions.py

@@ -0,0 +1,287 @@
+"""
+Core exceptions for grimoire-model package.
+
+Provides a hierarchy of exceptions for different error conditions that can occur
+during model operations, validation, template resolution, and inheritance processing.
+"""
+
+from typing import Any, Dict, List, Optional
+
+
+class GrimoireModelError(Exception):
+    """Base exception for grimoire-model package.
+
+    All other exceptions in this package inherit from this base class.
+    """
+
+    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None):
+        """Initialize with message and optional context information.
+
+        Args:
+            message: Human-readable error description
+            context: Additional context information for debugging
+        """
+        super().__init__(message)
+        self.message = message
+        self.context = context or {}
+
+    def __str__(self) -> str:
+        """Return string representation with context if available."""
+        if self.context:
+            context_str = ", ".join(f"{k}={v}" for k, v in self.context.items())
+            return f"{self.message} (context: {context_str})"
+        return self.message
+
+
+class ModelValidationError(GrimoireModelError):
+    """Raised when model validation fails.
+
+    This exception is raised when:
+    - Required fields are missing
+    - Field values don't match their defined types
+    - Value constraints are violated (range, enum, etc.)
+    - Cross-field validation rules fail
+    """
+
+    def __init__(
+        self,
+        message: str,
+        field_name: Optional[str] = None,
+        field_value: Any = None,
+        validation_errors: Optional[List[str]] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        """Initialize validation error with field-specific information.
+
+        Args:
+            message: Primary error message
+            field_name: Name of the field that failed validation
+            field_value: Value that caused the validation failure
+            validation_errors: List of specific validation error messages
+            context: Additional context information
+        """
+        super().__init__(message, context)
+        self.field_name = field_name
+        self.field_value = field_value
+        self.validation_errors = validation_errors or []
+
+    def __str__(self) -> str:
+        """Return detailed string representation including field information."""
+        parts = [self.message]
+
+        if self.field_name:
+            parts.append(f"field: {self.field_name}")
+
+        if self.field_value is not None:
+            parts.append(f"value: {self.field_value}")
+
+        if self.validation_errors:
+            error_list = ", ".join(self.validation_errors)
+            parts.append(f"errors: [{error_list}]")
+
+        if self.context:
+            context_str = ", ".join(f"{k}={v}" for k, v in self.context.items())
+            parts.append(f"context: {context_str}")
+
+        return " | ".join(parts)
+
+
+class TemplateResolutionError(GrimoireModelError):
+    """Raised when template resolution fails.
+
+    This exception is raised when:
+    - Template syntax is invalid
+    - Referenced variables are undefined
+    - Template evaluation produces an error
+    - Circular template dependencies are detected
+    """
+
+    def __init__(
+        self,
+        message: str,
+        template_str: Optional[str] = None,
+        template_variables: Optional[List[str]] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        """Initialize template resolution error.
+
+        Args:
+            message: Primary error message
+            template_str: The template string that failed to resolve
+            template_variables: Variables referenced in the template
+            context: Additional context information
+        """
+        super().__init__(message, context)
+        self.template_str = template_str
+        self.template_variables = template_variables or []
+
+    def __str__(self) -> str:
+        """Return detailed string representation including template information."""
+        parts = [self.message]
+
+        if self.template_str:
+            parts.append(f"template: {self.template_str}")
+
+        if self.template_variables:
+            vars_str = ", ".join(self.template_variables)
+            parts.append(f"variables: [{vars_str}]")
+
+        if self.context:
+            context_str = ", ".join(f"{k}={v}" for k, v in self.context.items())
+            parts.append(f"context: {context_str}")
+
+        return " | ".join(parts)
+
+
+class InheritanceError(GrimoireModelError):
+    """Raised when model inheritance resolution fails.
+
+    This exception is raised when:
+    - Parent model definitions are not found
+    - Circular inheritance dependencies are detected
+    - Inheritance conflicts cannot be resolved
+    - Model registry is incomplete or corrupted
+    """
+
+    def __init__(
+        self,
+        message: str,
+        model_id: Optional[str] = None,
+        parent_ids: Optional[List[str]] = None,
+        inheritance_chain: Optional[List[str]] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        """Initialize inheritance error.
+
+        Args:
+            message: Primary error message
+            model_id: ID of the model that failed inheritance resolution
+            parent_ids: List of parent model IDs
+            inheritance_chain: The inheritance chain being resolved
+            context: Additional context information
+        """
+        super().__init__(message, context)
+        self.model_id = model_id
+        self.parent_ids = parent_ids or []
+        self.inheritance_chain = inheritance_chain or []
+
+    def __str__(self) -> str:
+        """Return detailed string representation including inheritance information."""
+        parts = [self.message]
+
+        if self.model_id:
+            parts.append(f"model: {self.model_id}")
+
+        if self.parent_ids:
+            parents_str = ", ".join(self.parent_ids)
+            parts.append(f"parents: [{parents_str}]")
+
+        if self.inheritance_chain:
+            chain_str = " -> ".join(self.inheritance_chain)
+            parts.append(f"chain: {chain_str}")
+
+        if self.context:
+            context_str = ", ".join(f"{k}={v}" for k, v in self.context.items())
+            parts.append(f"context: {context_str}")
+
+        return " | ".join(parts)
+
+
+class DependencyError(GrimoireModelError):
+    """Raised when derived field dependencies cannot be resolved.
+
+    This exception is raised when:
+    - Circular dependencies are detected between derived fields
+    - Required dependencies are missing or undefined
+    - Dependency graph cannot be topologically sorted
+    - Dependency computation fails
+    """
+
+    def __init__(
+        self,
+        message: str,
+        field_name: Optional[str] = None,
+        dependencies: Optional[List[str]] = None,
+        dependency_chain: Optional[List[str]] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        """Initialize dependency error.
+
+        Args:
+            message: Primary error message
+            field_name: Name of the field with dependency issues
+            dependencies: List of field dependencies
+            dependency_chain: The dependency chain that failed
+            context: Additional context information
+        """
+        super().__init__(message, context)
+        self.field_name = field_name
+        self.dependencies = dependencies or []
+        self.dependency_chain = dependency_chain or []
+
+    def __str__(self) -> str:
+        """Return detailed string representation including dependency information."""
+        parts = [self.message]
+
+        if self.field_name:
+            parts.append(f"field: {self.field_name}")
+
+        if self.dependencies:
+            deps_str = ", ".join(self.dependencies)
+            parts.append(f"deps: [{deps_str}]")
+
+        if self.dependency_chain:
+            chain_str = " -> ".join(self.dependency_chain)
+            parts.append(f"chain: {chain_str}")
+
+        if self.context:
+            context_str = ", ".join(f"{k}={v}" for k, v in self.context.items())
+            parts.append(f"context: {context_str}")
+
+        return " | ".join(parts)
+
+
+class ConfigurationError(GrimoireModelError):
+    """Raised when configuration is invalid or incomplete.
+
+    This exception is raised when:
+    - Required configuration parameters are missing
+    - Configuration values are invalid
+    - Dependency injection setup fails
+    - Resolver configuration is incomplete
+    """
+
+    def __init__(
+        self,
+        message: str,
+        config_key: Optional[str] = None,
+        config_value: Any = None,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        """Initialize configuration error.
+
+        Args:
+            message: Primary error message
+            config_key: Configuration key that caused the error
+            config_value: Invalid configuration value
+            context: Additional context information
+        """
+        super().__init__(message, context)
+        self.config_key = config_key
+        self.config_value = config_value
+
+    def __str__(self) -> str:
+        """Return detailed string representation including configuration information."""
+        parts = [self.message]
+
+        if self.config_key:
+            parts.append(f"key: {self.config_key}")
+
+        if self.config_value is not None:
+            parts.append(f"value: {self.config_value}")
+
+        if self.context:
+            context_str = ", ".join(f"{k}={v}" for k, v in self.context.items())
+            parts.append(f"context: {context_str}")
+
+        return " | ".join(parts)