exonware-xwsystem 0.1.0.1__py3-none-any.whl → 0.1.0.4__py3-none-any.whl

exonware/xwsystem/validation/defs.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/validation/defs.py
 #exonware/xwsystem/validation/types.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: 07-Sep-2025
 
 Validation types and enums for XWSystem.

exonware/xwsystem/validation/errors.py

@@ -1,9 +1,10 @@
+#exonware/xwsystem/src/exonware/xwsystem/validation/errors.py
 #exonware/xwsystem/validation/errors.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 Validation module errors - exception classes for validation functionality.

exonware/xwsystem/validation/facade.py

@@ -0,0 +1,198 @@
+#exonware/xwsystem/src/exonware/xwsystem/validation/facade.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.4
+Generation Date: January 2026
+
+XWValidator - Unified Validation Facade
+
+Simplified API for validation operations:
+- Quick validation
+- Declarative models
+- Path validation
+- Data validation (depth, size)
+"""
+
+from typing import Any, Optional, Dict, Type
+from pathlib import Path
+
+from .declarative import XModel, Field, ValidationError
+from .data_validator import DataValidator, validate_path_input, check_data_depth, estimate_memory_usage
+from .type_safety import validate_untrusted_data, SafeTypeValidator
+from ..security.path_validator import PathValidator
+from ..config.logging_setup import get_logger
+
+logger = get_logger(__name__)
+
+
+class XWValidator:
+    """
+    Unified validation facade - simple API for validation operations.
+    
+    Examples:
+        >>> # Quick validation
+        >>> XWValidator.validate(data, rules={"age": "int", "name": "required"})
+        
+        >>> # Declarative models
+        >>> class User(XWValidator.Model):
+        ...     name: str = XWValidator.Field(required=True, min_length=3)
+        ...     age: int = XWValidator.Field(min=0, max=150)
+        
+        >>> user = User(name="John", age=30)  # Validates automatically
+        
+        >>> # Path validation
+        >>> XWValidator.validate_path("/safe/dir/file.txt", base_path="/safe")
+        
+        >>> # Data validation
+        >>> XWValidator.validate_depth(data, max_depth=100)
+        >>> XWValidator.validate_size(data, max_size_mb=10)
+    """
+    
+    # Re-export XModel and Field for convenience
+    Model = XModel
+    Field = Field
+    
+    @staticmethod
+    def validate(data: Any, rules: Dict[str, Any]) -> bool:
+        """
+        Quick validation with rules dictionary.
+        
+        Args:
+            data: Data to validate
+            rules: Validation rules (e.g., {"age": "int", "name": "required"})
+            
+        Returns:
+            True if valid
+            
+        Raises:
+            ValidationError: If validation fails
+        """
+        # Simple rule-based validation
+        if not isinstance(data, dict):
+            raise ValidationError("Data must be a dictionary")
+        
+        for key, rule in rules.items():
+            if rule == "required" and key not in data:
+                raise ValidationError(f"Required field missing: {key}")
+            elif key in data:
+                value = data[key]
+                if rule == "int" and not isinstance(value, int):
+                    raise ValidationError(f"Field {key} must be int, got {type(value).__name__}")
+                elif rule == "str" and not isinstance(value, str):
+                    raise ValidationError(f"Field {key} must be str, got {type(value).__name__}")
+        
+        return True
+    
+    @staticmethod
+    def validate_path(path: str, base_path: Optional[str] = None, must_exist: bool = False) -> str:
+        """
+        Validate and sanitize file path.
+        
+        Args:
+            path: Path to validate
+            base_path: Base directory (prevents directory traversal)
+            must_exist: Whether path must exist (default: False)
+            
+        Returns:
+            Validated path
+            
+        Raises:
+            ValidationError: If path is invalid
+        """
+        try:
+            validator = PathValidator(base_path) if base_path else PathValidator()
+            validated = validator.validate_path(path)
+            
+            # Check existence if required
+            if must_exist and not Path(validated).exists():
+                raise ValidationError(f"Path does not exist: {validated}")
+            
+            return validated
+        except ValidationError:
+            raise
+        except Exception as e:
+            raise ValidationError(f"Path validation failed: {e}") from e
+    
+    @staticmethod
+    def validate_depth(data: Any, max_depth: int = 100) -> bool:
+        """
+        Validate data depth.
+        
+        Args:
+            data: Data to validate
+            max_depth: Maximum allowed depth
+            
+        Returns:
+            True if depth is within limits
+            
+        Raises:
+            ValidationError: If depth exceeds limit
+        """
+        # check_data_depth raises exception if depth exceeds, returns None otherwise
+        try:
+            check_data_depth(data, max_depth=max_depth)
+            return True
+        except Exception as e:
+            raise ValidationError(f"Data depth validation failed: {e}") from e
+    
+    @staticmethod
+    def validate_size(data: Any, max_size_mb: int = 10) -> bool:
+        """
+        Validate data size.
+        
+        Args:
+            data: Data to validate
+            max_size_mb: Maximum size in MB
+            
+        Returns:
+            True if size is within limits
+            
+        Raises:
+            ValidationError: If size exceeds limit
+        """
+        size_mb = estimate_memory_usage(data) / (1024 * 1024)
+        if size_mb > max_size_mb:
+            raise ValidationError(f"Data size {size_mb:.2f}MB exceeds maximum {max_size_mb}MB")
+        return True
+    
+    @staticmethod
+    def validate_untrusted(data: Any, max_depth: int = 100) -> bool:
+        """
+        Validate untrusted data with security checks.
+        
+        Args:
+            data: Untrusted data to validate
+            max_depth: Maximum allowed depth
+            
+        Returns:
+            True if valid
+            
+        Raises:
+            ValidationError: If validation fails
+        """
+        return validate_untrusted_data(data, max_depth=max_depth)
+    
+    @classmethod
+    def create_model(cls, **fields) -> Type[XModel]:
+        """
+        Create a model class dynamically.
+        
+        Args:
+            **fields: Field definitions
+            
+        Returns:
+            Model class
+        """
+        # Create a dynamic model class
+        class DynamicModel(XModel):
+            pass
+        
+        for name, field_def in fields.items():
+            if isinstance(field_def, Field):
+                setattr(DynamicModel, name, field_def)
+            else:
+                setattr(DynamicModel, name, Field(default=field_def))
+        
+        return DynamicModel

exonware/xwsystem/validation/fluent_validator.py

@@ -1,15 +1,18 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/validation/fluent_validator.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: October 26, 2025
 
 Fluent validator with chainable API for data validation.
 """
 
-from typing import Any, Callable, Optional, Union
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
 from .errors import ValidationError
 from ..config.logging_setup import get_logger
 
@@ -40,7 +43,7 @@ class FluentValidator:
         self.errors: list[str] = []
         self.rules: list[dict[str, Any]] = []
     
-    def require(self, field_name: str, message: Optional[str] = None) -> 'FluentValidator':
+    def require(self, field_name: str, message: Optional[str] = None) -> FluentValidator:
         """
         Require a field to be present and not None.
         
@@ -65,7 +68,7 @@ class FluentValidator:
         
         return self
     
-    def type_check(self, expected_type: type, message: Optional[str] = None) -> 'FluentValidator':
+    def type_check(self, expected_type: type, message: Optional[str] = None) -> FluentValidator:
         """
         Check if data is of expected type.
         
@@ -88,10 +91,10 @@ class FluentValidator:
     
     def range_check(
         self,
-        min_value: Optional[Union[int, float]] = None,
-        max_value: Optional[Union[int, float]] = None,
+        min_value: Optional[int | float] = None,
+        max_value: Optional[int | float] = None,
         message: Optional[str] = None
-    ) -> 'FluentValidator':
+    ) -> FluentValidator:
         """
         Check if numeric data is within range.
         
@@ -128,7 +131,7 @@ class FluentValidator:
         min_length: Optional[int] = None,
         max_length: Optional[int] = None,
         message: Optional[str] = None
-    ) -> 'FluentValidator':
+    ) -> FluentValidator:
         """
         Check if data length is within range.
         
@@ -162,7 +165,7 @@ class FluentValidator:
         
         return self
     
-    def pattern_check(self, pattern: str, message: Optional[str] = None) -> 'FluentValidator':
+    def pattern_check(self, pattern: str, message: Optional[str] = None) -> FluentValidator:
         """
         Check if string data matches pattern (regex).
         
@@ -191,7 +194,7 @@ class FluentValidator:
         
         return self
     
-    def add_rule(self, validator_func: Callable[[Any], bool], message: Optional[str] = None) -> 'FluentValidator':
+    def add_rule(self, validator_func: Callable[[Any], bool], message: Optional[str] = None) -> FluentValidator:
         """
         Add custom validation rule.
         
@@ -216,7 +219,7 @@ class FluentValidator:
         """Check if data is valid (no errors)."""
         return len(self.errors) == 0
     
-    def validate(self) -> 'FluentValidator':
+    def validate(self) -> FluentValidator:
         """
         Validate data and raise ValidationError if invalid.
         
@@ -234,12 +237,12 @@ class FluentValidator:
         """Get list of validation errors."""
         return self.errors.copy()
     
-    def clear_errors(self) -> 'FluentValidator':
+    def clear_errors(self) -> FluentValidator:
         """Clear all validation errors."""
         self.errors.clear()
         return self
     
-    def set_data(self, data: Any) -> 'FluentValidator':
+    def set_data(self, data: Any) -> FluentValidator:
         """Set data to validate."""
         self.data = data
         return self
@@ -248,8 +251,8 @@ class FluentValidator:
         self,
         field_name: str,
         field_data: Any,
-        rules: list[Callable[['FluentValidator'], 'FluentValidator']]
-    ) -> 'FluentValidator':
+        rules: list[Callable[[FluentValidator], FluentValidator]]
+    ) -> FluentValidator:
         """
         Validate a specific field with rules.
         
@@ -280,8 +283,8 @@ class FluentValidator:
     
     def validate_dict_fields(
         self,
-        field_rules: dict[str, list[Callable[['FluentValidator'], 'FluentValidator']]]
-    ) -> 'FluentValidator':
+        field_rules: dict[str, list[Callable[[FluentValidator], FluentValidator]]]
+    ) -> FluentValidator:
         """
         Validate multiple fields in a dictionary.
         
@@ -342,7 +345,7 @@ def validate_string(data: str) -> FluentValidator:
     return FluentValidator(data)
 
 
-def validate_numeric(data: Union[int, float]) -> FluentValidator:
+def validate_numeric(data: int | float) -> FluentValidator:
     """
     Create a fluent validator for numeric data.
     
@@ -366,7 +369,7 @@ def is_type(expected_type: type) -> Callable[[FluentValidator], FluentValidator]
     return lambda v: v.type_check(expected_type)
 
 
-def is_in_range(min_val: Optional[Union[int, float]] = None, max_val: Optional[Union[int, float]] = None) -> Callable[[FluentValidator], FluentValidator]:
+def is_in_range(min_val: Optional[int | float] = None, max_val: Optional[int | float] = None) -> Callable[[FluentValidator], FluentValidator]:
     """Create a range check rule."""
     return lambda v: v.range_check(min_val, max_val)
 

exonware/xwsystem/validation/schema_discovery.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/validation/schema_discovery.py
+"""
+Schema validator discovery (plugin entry points).
+
+This module provides a lightweight "plugin" mechanism (via Python packaging
+entry points) to discover an implementation of
+`xwsystem.validation.contracts.ISchemaProvider`.
+
+Why this exists:
+- Avoids hard dependency cycles (e.g., xwdata <-> xwschema)
+- Keeps xwsystem as the stable contract owner
+- Enables optional providers to be installed and discovered at runtime
+
+Entry point group:
+  - xwsystem.schema_validators
+
+Providers should register an entry point that resolves to either:
+- an ISchemaProvider instance
+- a class (constructible with no args) returning an ISchemaProvider instance
+- a callable (factory) returning an ISchemaProvider instance
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import threading
+from typing import Any, Optional
+
+from ..config.logging_setup import get_logger
+from .contracts import ISchemaProvider
+
+logger = get_logger("xwsystem.validation.schema_discovery")
+
+
+DEFAULT_SCHEMA_VALIDATOR_ENTRYPOINT_GROUP = "xwsystem.schema_validators"
+
+
+@dataclass(frozen=True)
+class SchemaValidatorDiscoveryResult:
+    """Structured discovery information for observability/debugging."""
+
+    group: str
+    loaded: dict[str, str]  # name -> provider repr
+    errors: dict[str, str]  # name -> error string
+
+
+_lock = threading.RLock()
+_attempted_groups: set[str] = set()
+_providers_by_group: dict[str, dict[str, ISchemaProvider]] = {}
+_default_provider_by_group: dict[str, str] = {}
+
+
+def _as_schema_provider(obj: Any) -> Optional[ISchemaProvider]:
+    """Coerce an entry-point loaded object into an ISchemaProvider instance."""
+    if obj is None:
+        return None
+
+    # 1) Direct instance
+    try:
+        if isinstance(obj, ISchemaProvider):
+            return obj
+    except Exception:
+        # Protocol runtime checks can raise if obj is weird; treat as not valid.
+        return None
+
+    # 2) Class -> instantiate
+    if isinstance(obj, type):
+        try:
+            inst = obj()
+        except Exception:
+            return None
+        try:
+            return inst if isinstance(inst, ISchemaProvider) else None
+        except Exception:
+            return None
+
+    # 3) Factory callable -> call
+    if callable(obj):
+        try:
+            inst = obj()
+        except Exception:
+            return None
+        try:
+            return inst if isinstance(inst, ISchemaProvider) else None
+        except Exception:
+            return None
+
+    return None
+
+
+def discover_schema_validators(
+    *,
+    group: str = DEFAULT_SCHEMA_VALIDATOR_ENTRYPOINT_GROUP,
+    force: bool = False,
+) -> tuple[dict[str, ISchemaProvider], SchemaValidatorDiscoveryResult]:
+    """
+    Discover schema validator providers from entry points.
+
+    Args:
+        group: Entry-point group to search.
+        force: If True, re-run discovery even if already attempted.
+
+    Returns:
+        (providers, discovery_result)
+    """
+    with _lock:
+        already_attempted = group in _attempted_groups
+        if already_attempted and not force:
+            providers = dict(_providers_by_group.get(group, {}))
+            loaded_repr = {k: repr(v) for k, v in providers.items()}
+            return providers, SchemaValidatorDiscoveryResult(group=group, loaded=loaded_repr, errors={})
+
+    loaded: dict[str, ISchemaProvider] = {}
+    loaded_repr: dict[str, str] = {}
+    errors: dict[str, str] = {}
+
+    try:
+        from importlib.metadata import entry_points
+        eps = entry_points(group=group)
+    except Exception as e:
+        # Cache attempted to avoid repeated expensive failures.
+        with _lock:
+            _attempted_groups.add(group)
+            _providers_by_group.setdefault(group, {})
+        logger.debug(f"Schema validator discovery failed for group '{group}': {e}")
+        return {}, SchemaValidatorDiscoveryResult(group=group, loaded={}, errors={"__discovery__": str(e)})
+
+    for ep in eps:
+        name = getattr(ep, "name", "<unknown>")
+        try:
+            obj = ep.load()
+            inst = _as_schema_provider(obj)
+            if inst is None:
+                errors[name] = "Entry point did not resolve to an ISchemaProvider (instance/class/factory)."
+                continue
+            loaded[name] = inst
+            loaded_repr[name] = repr(inst)
+        except Exception as e:
+            errors[name] = str(e)
+
+    with _lock:
+        _attempted_groups.add(group)
+        _providers_by_group[group] = dict(loaded)
+        # Preserve existing default selection if still valid; else choose first.
+        if group not in _default_provider_by_group or _default_provider_by_group[group] not in loaded:
+            if loaded:
+                _default_provider_by_group[group] = sorted(loaded.keys())[0]
+
+    if errors:
+        logger.debug(f"Schema validator discovery had errors for group '{group}': {errors}")
+
+    return dict(loaded), SchemaValidatorDiscoveryResult(group=group, loaded=loaded_repr, errors=errors)
+
+
+def set_schema_validator(
+    validator: ISchemaProvider,
+    *,
+    name: str = "manual",
+    group: str = DEFAULT_SCHEMA_VALIDATOR_ENTRYPOINT_GROUP,
+    make_default: bool = True,
+) -> None:
+    """Manually register a schema provider (useful for tests / custom wiring)."""
+    with _lock:
+        _attempted_groups.add(group)
+        _providers_by_group.setdefault(group, {})
+        _providers_by_group[group][name] = validator
+        if make_default:
+            _default_provider_by_group[group] = name
+
+
+def get_schema_validator(
+    *,
+    name: Optional[str] = None,
+    group: str = DEFAULT_SCHEMA_VALIDATOR_ENTRYPOINT_GROUP,
+) -> Optional[ISchemaProvider]:
+    """
+    Get a schema provider (validator).
+
+    Args:
+        name: Optional provider name; if omitted, returns the group's default provider.
+        group: Entry-point group.
+
+    Returns:
+        ISchemaProvider instance or None if no providers available.
+    """
+    providers, _ = discover_schema_validators(group=group, force=False)
+    if not providers:
+        return None
+
+    if name:
+        return providers.get(name)
+
+    with _lock:
+        default_name = _default_provider_by_group.get(group)
+
+    if default_name and default_name in providers:
+        return providers[default_name]
+
+    # Fall back to deterministic choice
+    return providers[sorted(providers.keys())[0]]
+
+
+def available_schema_validators(
+    *,
+    group: str = DEFAULT_SCHEMA_VALIDATOR_ENTRYPOINT_GROUP,
+) -> list[str]:
+    """List discovered provider names."""
+    providers, _ = discover_schema_validators(group=group, force=False)
+    return sorted(providers.keys())

exonware/xwsystem/validation/type_safety.py

@@ -1,3 +1,4 @@
+#exonware/xwsystem/src/exonware/xwsystem/validation/type_safety.py
 """
 Generic type safety validation.
 
@@ -20,7 +21,7 @@ class SafeTypeValidator:
     # Allowed types for untrusted data
     SAFE_TYPES = (str, int, float, bool, list, dict, type(None))
 
-    # Types that are always safe to cache
+    # Types that are safe to cache
     IMMUTABLE_TYPES = (str, int, float, bool, tuple, frozenset, type(None))
 
     @classmethod

exonware/xwsystem/version.py

@@ -14,13 +14,13 @@ All version references should import from this module to ensure consistency.
 # =============================================================================
 
 # Main version - update this to change version across entire project
-__version__ = "0.1.0.1"
+__version__ = "0.1.0.4"
 
 # Version components for programmatic access
 VERSION_MAJOR = 0
 VERSION_MINOR = 1
 VERSION_PATCH = 0
-VERSION_BUILD = 1  # Set to None for releases, or build number for dev builds
+VERSION_BUILD = 4  # Set to None for releases, or build number for dev builds
 
 # Version metadata
 VERSION_SUFFIX = ""  # e.g., "dev", "alpha", "beta", "rc1"