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

exonware/xwsystem/utils/test_runner.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""
+#exonware/xwsystem/src/exonware/xwsystem/utils/test_runner.py
+
+Reusable pytest runner utilities for all eXonware libraries.
+
+Implements the hierarchical runner utilities described in:
+- docs/guides/GUIDE_DEV.md
+- docs/guides/GUIDE_TEST.md
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.4
+Generation Date: 28-Dec-2025
+"""
+
+from __future__ import annotations
+
+import sys
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Optional
+
+from exonware.xwsystem.console.cli import ensure_utf8_console
+
+
+def format_path(path: Path) -> str:
+    """Format a path as a full absolute path string."""
+    return str(path.resolve())
+
+
+class DualOutput:
+    """
+    Capture output for terminal and Markdown file simultaneously.
+    """
+
+    def __init__(self, output_file: Path):
+        self.output_file = output_file
+        self._markdown_lines: list[str] = []
+
+    def print(self, text: str, markdown_format: Optional[str] = None, *, emoji: Optional[str] = None) -> None:
+        prefix = f"{emoji} " if emoji else ""
+        line = f"{prefix}{text}"
+        print(line)
+        self._markdown_lines.append(markdown_format if markdown_format is not None else line)
+
+    def save(self, header_info: Optional[dict[str, Any]] = None) -> None:
+        header_info = header_info or {}
+        header = (
+            "# Test Runner Output\n\n"
+            f"**Library:** {header_info.get('library', '')}  \n"
+            f"**Layer:** {header_info.get('layer', '')}  \n"
+            f"**Generated:** {datetime.now().strftime('%d-%b-%Y %H:%M:%S')}  \n"
+            f"**Runner:** {header_info.get('runner', 'TestRunner')}  \n\n"
+            "---\n\n"
+        )
+        self.output_file.write_text(header + "\n".join(self._markdown_lines) + "\n", encoding="utf-8")
+
+
+def print_header(title: str, output: Optional[DualOutput] = None) -> None:
+    sep = "=" * 80
+    if output is None:
+        print(sep)
+        print(title)
+        print(sep)
+        return
+    output.print(sep)
+    output.print(title)
+    output.print(sep)
+
+
+def print_section(title: str, output: Optional[DualOutput] = None) -> None:
+    if output is None:
+        print(f"\n{'=' * 80}\n{title}\n{'=' * 80}\n")
+        return
+    output.print(f"\n{title}", f"\n## {title}\n")
+
+
+def print_status(success: bool, message: str, output: Optional[DualOutput] = None) -> None:
+    emoji = "✅" if success else "❌"
+    if output is None:
+        print(f"{emoji} {message}")
+        return
+    output.print(message, f"**Result:** {emoji} {message}", emoji=emoji)
+
+
+@dataclass(frozen=True)
+class PytestRunResult:
+    exit_code: int
+
+
+def run_pytest(
+    *,
+    test_dir: Path,
+    markers: Optional[list[str]] = None,
+    extra_args: Optional[list[str]] = None,
+    cwd: Optional[Path] = None,
+) -> PytestRunResult:
+    """
+    Run pytest as a subprocess with standard eXonware flags.
+    """
+    markers = markers or []
+    extra_args = extra_args or []
+    cwd = cwd or test_dir
+
+    args: list[str] = [
+        sys.executable,
+        "-m",
+        "pytest",
+        str(test_dir),
+        "-v",
+        "--tb=short",
+        "-x",
+        "--strict-markers",
+    ]
+    if markers:
+        args.extend(["-m", " and ".join(markers)])
+    args.extend(extra_args)
+
+    completed = subprocess.run(args, cwd=str(cwd))
+    return PytestRunResult(exit_code=int(completed.returncode))
+
+
+class TestRunner:
+    """
+    Simple reusable test runner for a single directory/layer.
+    """
+
+    def __init__(
+        self,
+        *,
+        library_name: str,
+        layer_name: str,
+        description: str,
+        test_dir: Path,
+        markers: Optional[list[str]] = None,
+        output_file: Optional[Path] = None,
+    ):
+        self.library_name = library_name
+        self.layer_name = layer_name
+        self.description = description
+        self.test_dir = test_dir
+        self.markers = markers or []
+
+        # Layer runners should pass output_file=None to not write files
+        # Only main runner writes to docs/logs/tests/
+        self.output_file = output_file
+        if self.output_file is None:
+            # Layer runner - create dummy output that won't save
+            # Use a temporary path that we'll ignore
+            import tempfile
+            dummy_file = Path(tempfile.gettempdir()) / "xwsystem_test_runner_dummy.md"
+            self.output = DualOutput(dummy_file)
+            self._is_layer_runner = True
+        else:
+            self.output = DualOutput(self.output_file)
+            self._is_layer_runner = False
+
+    def run(self) -> int:
+        ensure_utf8_console()
+
+        print_header(self.description, self.output)
+        self.output.print(
+            f"Directory: {format_path(self.test_dir)}",
+            f"**Directory:** `{format_path(self.test_dir)}`",
+            emoji="📂",
+        )
+
+        result = run_pytest(test_dir=self.test_dir, markers=self.markers)
+        ok = result.exit_code == 0
+        print_status(ok, "PASSED" if ok else "FAILED", self.output)
+
+        # Layer runners don't write files - only main runner writes to docs/logs/tests/
+        if not self._is_layer_runner:
+            self.output.save(
+                {
+                    "library": self.library_name,
+                    "layer": self.layer_name,
+                    "runner": "TestRunner",
+                }
+            )
+        return result.exit_code

exonware/xwsystem/utils/utils_contracts.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/utils/utils_contracts.py
 #exonware/xwsystem/utils/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
 
 Utils types and enums for XWSystem.

exonware/xwsystem/utils/web.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/utils/web.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.4
+Generation Date: January 2025
+
+Web utility functions for XSystem.
+"""
+
+from typing import Optional
+from urllib.parse import urlparse
+
+# Prevent BeautifulSoup from trying to import lxml (which has Python 2 syntax issues)
+# Block lxml import before BeautifulSoup tries to import it
+import sys
+if 'lxml' not in sys.modules:
+    # Create a dummy module to prevent lxml from being imported
+    class DummyModule:
+        pass
+    sys.modules['lxml'] = DummyModule()
+    sys.modules['lxml.etree'] = DummyModule()
+    sys.modules['lxml.html'] = DummyModule()
+
+
+def validate_url_accessible(url: str, timeout: int = 10) -> bool:
+    """
+    Validate that a URL is accessible.
+    
+    Args:
+        url: URL to validate
+        timeout: Request timeout in seconds
+    
+    Returns:
+        True if URL is accessible (status 200), False otherwise
+    
+    Examples:
+        >>> validate_url_accessible("https://www.example.com")
+        True
+        >>> validate_url_accessible("https://invalid-url-that-does-not-exist.com")
+        False
+    """
+    try:
+        parsed_url = urlparse(url)
+        if not all([parsed_url.scheme in ["http", "https"], parsed_url.netloc]):
+            return False
+        
+        # Optional dependency: requests
+        import importlib.util
+        _requests_spec = importlib.util.find_spec('requests')
+        if _requests_spec is None:
+            # If requests is not available, we can't validate
+            return False
+        import requests
+        
+        try:
+            # First try a HEAD request (more efficient)
+            response = requests.head(url, allow_redirects=True, timeout=timeout)
+        except requests.RequestException:
+            # If HEAD request fails, try a GET request
+            response = requests.get(url, allow_redirects=True, timeout=timeout)
+        
+        # Check if the status code indicates success
+        return response.status_code == 200
+        
+    except (requests.RequestException, Exception):
+        return False
+
+
+def extract_webpage_text(url: str) -> str:
+    """
+    Extract text content from a webpage.
+    
+    Args:
+        url: URL to extract text from
+    
+    Returns:
+        Extracted text content
+    
+    Examples:
+        >>> text = extract_webpage_text("https://www.example.com")
+        >>> len(text) > 0
+        True
+    """
+    from urllib.request import urlopen
+    from bs4 import BeautifulSoup
+    
+    html = urlopen(url).read()
+    soup = BeautifulSoup(html, features="html.parser")
+    
+    # Remove script and style elements
+    for script in soup(["script", "style"]):
+        script.extract()
+    
+    # Get text
+    text = soup.get_text()
+    
+    # Break into lines and remove leading/trailing space
+    lines = (line.strip() for line in text.splitlines())
+    chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
+    # Drop blank lines
+    return '\n'.join(chunk for chunk in chunks if chunk)
+
+
+__all__ = [
+    'validate_url_accessible',
+    'extract_webpage_text',
+]

exonware/xwsystem/validation/__init__.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/validation/__init__.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
 
 XSystem Validation Package
@@ -12,10 +13,33 @@ Declarative validation with type hints, automatic coercion, and Pydantic-style m
 
 from .declarative import XModel, Field, ValidationError
 from .type_safety import validate_untrusted_data
+from .contracts import ISchemaProvider
+from .schema_discovery import (
+    DEFAULT_SCHEMA_VALIDATOR_ENTRYPOINT_GROUP,
+    SchemaValidatorDiscoveryResult,
+    discover_schema_validators,
+    get_schema_validator,
+    set_schema_validator,
+    available_schema_validators,
+)
+
+# Unified Facade
+from .facade import XWValidator
 
 __all__ = [
+    # Unified Facade
+    "XWValidator",
+    # Core Classes
     "XModel",
     "Field", 
     "ValidationError",
     "validate_untrusted_data",
+    # Schema validation contracts + discovery (optional providers)
+    "ISchemaProvider",
+    "DEFAULT_SCHEMA_VALIDATOR_ENTRYPOINT_GROUP",
+    "SchemaValidatorDiscoveryResult",
+    "discover_schema_validators",
+    "get_schema_validator",
+    "set_schema_validator",
+    "available_schema_validators",
 ]

exonware/xwsystem/validation/base.py

@@ -1,16 +1,17 @@
+#exonware/xwsystem/src/exonware/xwsystem/validation/base.py
 #exonware/xwsystem/validation/base.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 base classes - abstract classes for validation functionality.
 """
 
 from abc import ABC, abstractmethod
-from typing import Any, Optional, Union, Callable
+from typing import Any, Optional, Callable
 # Root cause: Migrating to Python 3.12 built-in generic syntax for consistency
 # Priority #3: Maintainability - Modern type annotations improve code clarity
 from .contracts import ValidationType, ValidationLevel, ConstraintType, SchemaType
@@ -102,13 +103,13 @@ class ADataValidatorBase(ABC):
         pass
     
     @abstractmethod
-    def validate_range(self, data: Union[int, float], min_value: Optional[Union[int, float]] = None, 
-                      max_value: Optional[Union[int, float]] = None) -> bool:
+    def validate_range(self, data: int | float, min_value: Optional[int | float] = None, 
+                      max_value: Optional[int | float] = None) -> bool:
         """Validate data range."""
         pass
     
     @abstractmethod
-    def validate_length(self, data: Union[str, list, dict], min_length: Optional[int] = None, 
+    def validate_length(self, data: str | list | dict, min_length: Optional[int] = None, 
                        max_length: Optional[int] = None) -> bool:
         """Validate data length."""
         pass

exonware/xwsystem/validation/contracts.py

@@ -1,17 +1,16 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/validation/contracts.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 protocol interfaces for XWSystem.
 """
 
-from abc import ABC, abstractmethod
-from typing import Any, Optional, Union, Iterator, Callable, Protocol
-from typing_extensions import runtime_checkable
+from typing import Any, Optional, Iterator, Callable, Protocol, runtime_checkable
 
 # Import enums from types module
 from .defs import (
@@ -25,14 +24,14 @@ from .defs import (
 # VALIDATION INTERFACES
 # ============================================================================
 
-class IValidatable(ABC):
+@runtime_checkable
+class IValidatable(Protocol):
     """
     Interface for objects that can be validated.
     
     Enforces consistent validation behavior across XWSystem.
     """
     
-    @abstractmethod
     def validate(self) -> bool:
         """
         Validate this object.
@@ -40,9 +39,8 @@ class IValidatable(ABC):
         Returns:
             True if valid
         """
-        pass
+        ...
     
-    @abstractmethod
     def is_valid(self) -> bool:
         """
         Check if object is valid.
@@ -50,9 +48,8 @@ class IValidatable(ABC):
         Returns:
             True if valid
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_errors(self) -> list[str]:
         """
         Get validation errors.
@@ -60,16 +57,14 @@ class IValidatable(ABC):
         Returns:
             List of error messages
         """
-        pass
+        ...
     
-    @abstractmethod
     def clear_errors(self) -> None:
         """
         Clear validation errors.
         """
-        pass
+        ...
     
-    @abstractmethod
     def has_errors(self) -> bool:
         """
         Check if object has validation errors.
@@ -77,9 +72,8 @@ class IValidatable(ABC):
         Returns:
             True if has errors
         """
-        pass
+        ...
     
-    @abstractmethod
     def add_error(self, error: str) -> None:
         """
         Add validation error.
@@ -87,21 +81,21 @@ class IValidatable(ABC):
         Args:
             error: Error message
         """
-        pass
+        ...
 
 
 # ============================================================================
 # VALIDATION MANAGER INTERFACES
 # ============================================================================
 
-class IValidationManager(ABC):
+@runtime_checkable
+class IValidationManager(Protocol):
     """
     Interface for validation management.
     
     Enforces consistent validation management across XWSystem.
     """
     
-    @abstractmethod
     def add_validator(self, name: str, validator: Callable[[Any], bool]) -> None:
         """
         Add validator function.
@@ -110,9 +104,8 @@ class IValidationManager(ABC):
             name: Validator name
             validator: Validator function
         """
-        pass
+        ...
     
-    @abstractmethod
     def remove_validator(self, name: str) -> bool:
         """
         Remove validator.
@@ -123,9 +116,8 @@ class IValidationManager(ABC):
         Returns:
             True if removed
         """
-        pass
+        ...
     
-    @abstractmethod
     def validate_object(self, obj: Any, validators: list[str]) -> tuple[bool, list[str]]:
         """
         Validate object with specified validators.
@@ -137,9 +129,8 @@ class IValidationManager(ABC):
         Returns:
             Tuple of (is_valid, error_messages)
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_validators(self) -> list[str]:
         """
         Get list of available validators.
@@ -147,21 +138,22 @@ class IValidationManager(ABC):
         Returns:
             List of validator names
         """
-        pass
+        ...
 
 
 # ============================================================================
-# SCHEMA VALIDATION INTERFACES
+# SCHEMA VALIDATION INTERFACES (Schema Provider)
 # ============================================================================
 
-class ISchemaValidator(ABC):
+@runtime_checkable
+class ISchemaProvider(Protocol):
     """
-    Interface for schema validation.
+    Interface for schema validation (schema provider).
     
     Enforces consistent schema validation across XWSystem.
+    Implementations are discovered via entry point xwsystem.schema_validators.
     """
     
-    @abstractmethod
     def validate_schema(self, data: Any, schema: dict[str, Any]) -> tuple[bool, list[str]]:
         """
         Validate data against schema.
@@ -173,9 +165,8 @@ class ISchemaValidator(ABC):
         Returns:
             Tuple of (is_valid, error_messages)
         """
-        pass
+        ...
     
-    @abstractmethod
     def create_schema(self, data: Any) -> dict[str, Any]:
         """
         Create schema from data.
@@ -186,9 +177,8 @@ class ISchemaValidator(ABC):
         Returns:
             Schema definition
         """
-        pass
+        ...
     
-    @abstractmethod
     def validate_type(self, data: Any, expected_type: str) -> bool:
         """
         Validate data type.
@@ -200,9 +190,8 @@ class ISchemaValidator(ABC):
         Returns:
             True if type matches
         """
-        pass
+        ...
     
-    @abstractmethod
     def validate_range(self, data: Any, min_value: Any, max_value: Any) -> bool:
         """
         Validate data range.
@@ -215,9 +204,8 @@ class ISchemaValidator(ABC):
         Returns:
             True if in range
         """
-        pass
+        ...
     
-    @abstractmethod
     def validate_pattern(self, data: str, pattern: str) -> bool:
         """
         Validate string pattern.
@@ -229,7 +217,7 @@ class ISchemaValidator(ABC):
         Returns:
             True if pattern matches
         """
-        pass
+        ...
 
 
 # ============================================================================
@@ -237,8 +225,8 @@ class ISchemaValidator(ABC):
 # ============================================================================
 
 @runtime_checkable
-class Validatable(Protocol):
-    """Protocol for objects that support data validation."""
+class IValidatableSimple(Protocol):
+    """Protocol for objects that support data validation (simpler interface than IValidatable)."""
     
     def validate(self, data: Any, **kwargs: Any) -> bool:
         """Validate data against rules."""

exonware/xwsystem/validation/data_validator.py

@@ -1,3 +1,4 @@
+#exonware/xwsystem/src/exonware/xwsystem/validation/data_validator.py
 """
 Data Validation Utilities for XSystem
 

exonware/xwsystem/validation/declarative.py

@@ -1,13 +1,16 @@
+#exonware/xwsystem/src/exonware/xwsystem/validation/declarative.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
 
 Pydantic-style declarative validation with type hints and automatic coercion.
 """
 
+from __future__ import annotations
+
 import inspect
 import json
 from dataclasses import dataclass, field
@@ -58,10 +61,10 @@ class Field:
     description: Optional[str] = None
     
     # Validation constraints
-    gt: Optional[Union[int, float]] = None  # Greater than
-    ge: Optional[Union[int, float]] = None  # Greater than or equal
-    lt: Optional[Union[int, float]] = None  # Less than
-    le: Optional[Union[int, float]] = None  # Less than or equal
+    gt: Optional[int | float] = None  # Greater than
+    ge: Optional[int | float] = None  # Greater than or equal
+    lt: Optional[int | float] = None  # Less than
+    le: Optional[int | float] = None  # Less than or equal
     min_length: Optional[int] = None
     max_length: Optional[int] = None
     pattern: Optional[str] = None
@@ -73,7 +76,7 @@ class Field:
     to_upper: bool = False
     
     # Advanced constraints
-    multiple_of: Optional[Union[int, float]] = None
+    multiple_of: Optional[int | float] = None
     allow_inf_nan: bool = True
     
     # Metadata
@@ -442,12 +445,12 @@ class XModel(metaclass=ModelMeta):
             raise ValidationError(f"Value must be one of: {field_config.enum}")
     
     @classmethod
-    def model_validate(cls, data: dict[str, Any]) -> 'XModel':
+    def model_validate(cls, data: dict[str, Any]) -> XModel:
         """Create and validate model from dictionary data."""
         return cls(**data)
     
     @classmethod
-    def model_validate_json(cls, json_data: str) -> 'XModel':
+    def model_validate_json(cls, json_data: str) -> XModel:
         """Create and validate model from JSON string."""
         data = json.loads(json_data)
         return cls.model_validate(data)