pycharter 0.0.22__py3-none-any.whl → 0.0.24__py3-none-any.whl

pycharter/shared/__init__.py

@@ -2,6 +2,7 @@
 Shared utilities used across all services.
 
 Includes:
+- Protocols (interface definitions for extensible components)
 - Coercions (pre-validation transformations)
 - Validations (post-validation checks)
 - JSON Schema support utilities
@@ -20,6 +21,19 @@ from pycharter.shared.json_schema_validator import (
     is_valid_json_schema,
     validate_json_schema,
 )
+from pycharter.shared.protocols import (
+    MetadataStore,
+    CoercionFunc,
+    CoercionRegistry,
+    ValidatorFunc,
+    ValidationFactory,
+    ValidationRegistry,
+    ContractParser,
+    ContractMetadataProtocol,
+    ModelGenerator,
+    DataValidator,
+    ValidationResultProtocol,
+)
 from pycharter.shared.schema_parser import (
     get_schema_type,
     is_required,
@@ -33,8 +47,35 @@ from pycharter.shared.name_validator import (
     validate_name,
 )
 from pycharter.shared.validations import get_validation, register_validation
+from pycharter.shared.errors import (
+    PyCharterError,
+    ConfigError,
+    ConfigValidationError,
+    ConfigLoadError,
+    ExpressionError,
+    ErrorMode,
+    ErrorContext,
+    get_error_context,
+    set_error_mode,
+    handle_error,
+    handle_warning,
+    StrictMode,
+    LenientMode,
+)
 
 __all__ = [
+    # Protocols
+    "MetadataStore",
+    "CoercionFunc",
+    "CoercionRegistry",
+    "ValidatorFunc",
+    "ValidationFactory",
+    "ValidationRegistry",
+    "ContractParser",
+    "ContractMetadataProtocol",
+    "ModelGenerator",
+    "DataValidator",
+    "ValidationResultProtocol",
     # Coercions
     "get_coercion",
     "register_coercion",
@@ -62,4 +103,19 @@ __all__ = [
     "validate_name",
     "is_valid_name",
     "normalize_name",
+    # Exception hierarchy
+    "PyCharterError",
+    "ConfigError",
+    "ConfigValidationError",
+    "ConfigLoadError",
+    "ExpressionError",
+    # Error handling
+    "ErrorMode",
+    "ErrorContext",
+    "get_error_context",
+    "set_error_mode",
+    "handle_error",
+    "handle_warning",
+    "StrictMode",
+    "LenientMode",
 ]

pycharter/shared/errors.py

@@ -0,0 +1,296 @@
+"""
+Standardized error handling for pycharter.
+
+Exception hierarchy:
+- PyCharterError: Base for all pycharter exceptions (catch this for any pycharter error)
+- ConfigError: Config loading/parsing failures (e.g. missing file, invalid YAML)
+- ConfigValidationError: Schema validation failures (e.g. missing required 'type' field)
+- ExpressionError: Expression evaluation failures (e.g. invalid syntax in add field)
+
+Error handling modes:
+- STRICT: Raise exceptions immediately on errors
+- LENIENT: Log warnings and continue (best effort)
+- COLLECT: Collect errors and return them with results
+"""
+
+import logging
+import warnings
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# EXCEPTION HIERARCHY
+# =============================================================================
+
+
+class PyCharterError(Exception):
+    """
+    Base exception for all pycharter errors.
+    
+    Catch this to handle any pycharter-related failure without depending on
+    specific exception types. Subclasses provide more specific handling.
+    
+    Example:
+        try:
+            pipeline = Pipeline.from_config_files(extract="e.yaml", load="l.yaml")
+        except PyCharterError as e:
+            logger.error("Pipeline config failed: %s", e)
+    """
+    pass
+
+
+class ConfigError(PyCharterError):
+    """
+    Raised when configuration cannot be loaded or parsed.
+    
+    Use for: missing files, invalid YAML/JSON, I/O errors during config load.
+    """
+    def __init__(self, message: str, path: Optional[str] = None):
+        self.path = path
+        super().__init__(message + (f" (path: {path})" if path else ""))
+
+
+class ConfigValidationError(PyCharterError):
+    """
+    Raised when configuration fails schema validation.
+    
+    Use for: missing required fields (e.g. 'type'), invalid structure,
+    schema constraint violations. May include a list of validation errors.
+    """
+    def __init__(
+        self,
+        message: str,
+        errors: Optional[List[dict]] = None,
+        config_type: Optional[str] = None,
+        config_path: Optional[str] = None,
+    ):
+        self.message = message
+        self.errors = errors or []
+        self.config_type = config_type
+        self.config_path = config_path
+        super().__init__(self._format_message())
+    
+    def _format_message(self) -> str:
+        parts = [self.message]
+        if self.config_path:
+            parts.append(f"  File: {self.config_path}")
+        if self.errors:
+            parts.append("\nValidation errors:")
+            for i, error in enumerate(self.errors[:10], 1):
+                path = error.get("path", "")
+                msg = error.get("message", "Unknown error")
+                parts.append(f"  {i}. {path}: {msg}" if path else f"  {i}. {msg}")
+            if len(self.errors) > 10:
+                parts.append(f"  ... and {len(self.errors) - 10} more errors")
+        return "\n".join(parts)
+
+
+class ConfigLoadError(ConfigError):
+    """
+    Raised when pipeline config cannot be loaded (missing file, invalid YAML, I/O).
+    
+    Subclass of ConfigError for backward compatibility and ETL-specific usage.
+    """
+    pass
+
+
+class ExpressionError(PyCharterError):
+    """
+    Raised when an expression cannot be evaluated (e.g. in add field, defaults).
+    
+    Use for: invalid expression syntax, missing variables, type errors in evaluation.
+    """
+    pass
+
+
+class ErrorMode(Enum):
+    """Error handling mode for pycharter operations."""
+    
+    STRICT = "strict"
+    """Raise exceptions immediately on any error."""
+    
+    LENIENT = "lenient"
+    """Log warnings and continue with best effort."""
+    
+    COLLECT = "collect"
+    """Collect errors and return them with results."""
+
+
+@dataclass
+class ErrorContext:
+    """
+    Context for tracking errors during operations.
+    
+    Use with ErrorMode.COLLECT to gather errors without stopping.
+    """
+    
+    mode: ErrorMode = ErrorMode.LENIENT
+    errors: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+    
+    def handle_error(
+        self,
+        message: str,
+        exception: Optional[Exception] = None,
+        category: str = "error",
+    ) -> None:
+        """
+        Handle an error according to the current mode.
+        
+        Args:
+            message: Error message
+            exception: Optional exception that caused the error
+            category: Error category for logging
+        """
+        full_message = f"{category}: {message}"
+        if exception:
+            full_message += f" ({type(exception).__name__}: {exception})"
+        
+        if self.mode == ErrorMode.STRICT:
+            if exception:
+                raise type(exception)(full_message) from exception
+            raise ValueError(full_message)
+        
+        elif self.mode == ErrorMode.LENIENT:
+            warnings.warn(full_message)
+            logger.warning(full_message)
+            self.warnings.append(full_message)
+        
+        elif self.mode == ErrorMode.COLLECT:
+            self.errors.append(full_message)
+            logger.warning(full_message)
+    
+    def handle_warning(self, message: str, category: str = "warning") -> None:
+        """
+        Handle a warning (non-fatal issue).
+        
+        Args:
+            message: Warning message
+            category: Warning category
+        """
+        full_message = f"{category}: {message}"
+        warnings.warn(full_message)
+        logger.warning(full_message)
+        self.warnings.append(full_message)
+    
+    @property
+    def has_errors(self) -> bool:
+        """Whether any errors were collected."""
+        return len(self.errors) > 0
+    
+    def raise_if_errors(self) -> None:
+        """Raise ValueError if any errors were collected."""
+        if self.errors:
+            raise ValueError(f"Errors occurred: {'; '.join(self.errors)}")
+    
+    def clear(self) -> None:
+        """Clear all errors and warnings."""
+        self.errors.clear()
+        self.warnings.clear()
+
+
+# Default error context (lenient by default)
+_default_context = ErrorContext(mode=ErrorMode.LENIENT)
+
+
+def get_error_context() -> ErrorContext:
+    """Get the default error context."""
+    return _default_context
+
+
+def set_error_mode(mode: ErrorMode) -> None:
+    """
+    Set the default error handling mode.
+    
+    Args:
+        mode: Error mode to use
+    """
+    _default_context.mode = mode
+
+
+def handle_error(
+    message: str,
+    exception: Optional[Exception] = None,
+    category: str = "error",
+    context: Optional[ErrorContext] = None,
+) -> None:
+    """
+    Handle an error using the specified or default context.
+    
+    Args:
+        message: Error message
+        exception: Optional exception that caused the error
+        category: Error category
+        context: Optional error context (uses default if not provided)
+    """
+    ctx = context or _default_context
+    ctx.handle_error(message, exception, category)
+
+
+def handle_warning(
+    message: str,
+    category: str = "warning",
+    context: Optional[ErrorContext] = None,
+) -> None:
+    """
+    Handle a warning using the specified or default context.
+    
+    Args:
+        message: Warning message
+        category: Warning category
+        context: Optional error context (uses default if not provided)
+    """
+    ctx = context or _default_context
+    ctx.handle_warning(message, category)
+
+
+class StrictMode:
+    """
+    Context manager for temporarily enabling strict mode.
+    
+    Example:
+        >>> with StrictMode():
+        ...     # Errors will raise exceptions
+        ...     validator.validate(data)
+    """
+    
+    def __init__(self):
+        self._previous_mode: Optional[ErrorMode] = None
+    
+    def __enter__(self):
+        self._previous_mode = _default_context.mode
+        _default_context.mode = ErrorMode.STRICT
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self._previous_mode is not None:
+            _default_context.mode = self._previous_mode
+        return False
+
+
+class LenientMode:
+    """
+    Context manager for temporarily enabling lenient mode.
+    
+    Example:
+        >>> with LenientMode():
+        ...     # Errors will be logged as warnings
+        ...     validator.validate(data)
+    """
+    
+    def __init__(self):
+        self._previous_mode: Optional[ErrorMode] = None
+    
+    def __enter__(self):
+        self._previous_mode = _default_context.mode
+        _default_context.mode = ErrorMode.LENIENT
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self._previous_mode is not None:
+            _default_context.mode = self._previous_mode
+        return False

pycharter/shared/protocols.py

@@ -0,0 +1,234 @@
+"""
+Protocol definitions for pycharter interfaces.
+
+These protocols define the expected interfaces for extensible components,
+enabling type checking and clear contracts for custom implementations.
+"""
+
+from typing import Any, Callable, Dict, List, Optional, Protocol, Type, runtime_checkable
+
+from pydantic import BaseModel, ValidationInfo
+
+
+# =============================================================================
+# Metadata Store Protocols
+# =============================================================================
+
+@runtime_checkable
+class MetadataStore(Protocol):
+    """
+    Protocol for metadata store implementations.
+    
+    All metadata stores (SQLite, Postgres, MongoDB, Redis, InMemory) must
+    implement this interface for storing and retrieving data contracts.
+    
+    Example implementation:
+        >>> class MyCustomStore:
+        ...     def get_schema(self, schema_id: str, version: str = None) -> dict | None:
+        ...         # Custom implementation
+        ...         return {"type": "object", "properties": {...}}
+    """
+    
+    def get_schema(
+        self, schema_id: str, version: Optional[str] = None
+    ) -> Optional[Dict[str, Any]]:
+        """Get a schema by ID and optional version."""
+        ...
+    
+    def get_complete_schema(
+        self, schema_id: str, version: Optional[str] = None
+    ) -> Optional[Dict[str, Any]]:
+        """Get a complete schema with coercion and validation rules merged."""
+        ...
+    
+    def store_schema(
+        self,
+        schema_id: str,
+        schema: Dict[str, Any],
+        version: Optional[str] = None,
+    ) -> str:
+        """Store a schema and return its ID."""
+        ...
+    
+    def list_schemas(self) -> List[Dict[str, Any]]:
+        """List all available schemas."""
+        ...
+
+
+# =============================================================================
+# Coercion Protocols
+# =============================================================================
+
+# Type alias for coercion functions
+CoercionFunc = Callable[[Any], Any]
+
+
+@runtime_checkable
+class CoercionRegistry(Protocol):
+    """
+    Protocol for coercion function registries.
+    
+    Coercions are pre-validation transformations applied to data
+    before Pydantic validation (mode='before').
+    """
+    
+    def get(self, name: str) -> CoercionFunc:
+        """Get a coercion function by name."""
+        ...
+    
+    def register(self, name: str, func: CoercionFunc) -> None:
+        """Register a custom coercion function."""
+        ...
+    
+    def list_available(self) -> List[str]:
+        """List all available coercion names."""
+        ...
+
+
+# =============================================================================
+# Validation Protocols
+# =============================================================================
+
+# Type alias for validation functions (factory pattern)
+# A validation factory returns a validator function that takes (value, info) -> value
+ValidatorFunc = Callable[[Any, ValidationInfo], Any]
+ValidationFactory = Callable[..., ValidatorFunc]
+
+
+@runtime_checkable
+class ValidationRegistry(Protocol):
+    """
+    Protocol for validation function registries.
+    
+    Validations are post-validation checks applied to data
+    after Pydantic validation (mode='after').
+    """
+    
+    def get(self, name: str) -> ValidationFactory:
+        """Get a validation factory by name."""
+        ...
+    
+    def register(self, name: str, factory: ValidationFactory) -> None:
+        """Register a custom validation factory."""
+        ...
+    
+    def list_available(self) -> List[str]:
+        """List all available validation names."""
+        ...
+
+
+# =============================================================================
+# Contract Parser Protocols
+# =============================================================================
+
+@runtime_checkable
+class ContractParser(Protocol):
+    """
+    Protocol for contract parsers.
+    
+    Contract parsers decompose data contract files/dicts into
+    their constituent components (schema, coercion_rules, validation_rules, metadata).
+    """
+    
+    def parse(self, contract_data: Dict[str, Any]) -> "ContractMetadataProtocol":
+        """Parse contract data into metadata components."""
+        ...
+    
+    def parse_file(self, file_path: str) -> "ContractMetadataProtocol":
+        """Parse contract from file."""
+        ...
+
+
+@runtime_checkable
+class ContractMetadataProtocol(Protocol):
+    """Protocol for contract metadata containers."""
+    
+    @property
+    def schema(self) -> Dict[str, Any]:
+        """Get the JSON Schema definition."""
+        ...
+    
+    @property
+    def coercion_rules(self) -> Dict[str, Any]:
+        """Get coercion rules."""
+        ...
+    
+    @property
+    def validation_rules(self) -> Dict[str, Any]:
+        """Get validation rules."""
+        ...
+    
+    @property
+    def metadata(self) -> Dict[str, Any]:
+        """Get additional metadata."""
+        ...
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        ...
+
+
+# =============================================================================
+# Model Generator Protocols
+# =============================================================================
+
+@runtime_checkable
+class ModelGenerator(Protocol):
+    """
+    Protocol for Pydantic model generators.
+    
+    Model generators take JSON Schemas and produce Pydantic model classes.
+    """
+    
+    def generate(
+        self, schema: Dict[str, Any], model_name: str = "DynamicModel"
+    ) -> Type[BaseModel]:
+        """Generate a Pydantic model from JSON Schema."""
+        ...
+
+
+# =============================================================================
+# Validator Protocols
+# =============================================================================
+
+@runtime_checkable
+class DataValidator(Protocol):
+    """
+    Protocol for data validators.
+    
+    Validators validate data against contracts/schemas and return results.
+    """
+    
+    def validate(self, data: Dict[str, Any]) -> "ValidationResultProtocol":
+        """Validate a single data record."""
+        ...
+    
+    def validate_batch(
+        self, data_list: List[Dict[str, Any]]
+    ) -> List["ValidationResultProtocol"]:
+        """Validate a batch of data records."""
+        ...
+    
+    def get_model(self) -> Type[BaseModel]:
+        """Get the underlying Pydantic model."""
+        ...
+
+
+@runtime_checkable
+class ValidationResultProtocol(Protocol):
+    """Protocol for validation results."""
+    
+    @property
+    def is_valid(self) -> bool:
+        """Whether validation passed."""
+        ...
+    
+    @property
+    def data(self) -> Optional[Any]:
+        """Validated/coerced data (if valid)."""
+        ...
+    
+    @property
+    def errors(self) -> List[Dict[str, Any]]:
+        """Validation errors (if any)."""
+        ...