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

exonware/xwsystem/io/serialization/universal_options.py

@@ -0,0 +1,367 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/universal_options.py
+"""
+Universal Serialization Options
+
+This module provides universal option mapping across different serialization formats.
+Options like pretty, compact, sorted, canonical can be mapped to format-specific options.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.3
+"""
+
+from typing import Dict, List, Set, Any, Optional
+from enum import Enum
+
+
+class UniversalOption(Enum):
+    """Universal serialization options."""
+    PRETTY = "pretty"
+    COMPACT = "compact"
+    SORTED = "sorted"
+    CANONICAL = "canonical"
+    INDENT = "indent"
+    ENSURE_ASCII = "ensure_ascii"
+    ALLOW_NAN = "allow_nan"
+    STRIP_WHITESPACE = "strip_whitespace"
+    PRESERVE_QUOTES = "preserve_quotes"
+    LINE_SEPARATOR = "line_separator"
+    ITEM_SEPARATOR = "item_separator"
+
+
+# Format-specific option mappings
+_FORMAT_OPTION_MAPS: Dict[str, Dict[str, str]] = {
+    "json": {
+        "pretty": "indent",
+        "compact": "separators",
+        "sorted": "sort_keys",
+        "canonical": "sort_keys",
+        "indent": "indent",
+        "ensure_ascii": "ensure_ascii",
+        "allow_nan": "allow_nan",
+    },
+    "yaml": {
+        "pretty": "default_flow_style",
+        "compact": "default_flow_style",
+        "sorted": "sort_keys",
+        "canonical": "canonical",
+        "indent": "indent",
+        "strip_whitespace": "strip_whitespace",
+    },
+    "xml": {
+        "pretty": "pretty_print",
+        "compact": "pretty_print",
+        "sorted": "sort_attributes",
+        "canonical": "canonical",
+        "indent": "indent",
+        "preserve_quotes": "preserve_quotes",
+        "declaration": "full_document",  # xmltodict uses full_document to control XML declaration
+        "encoding": "encoding",
+    },
+    "toml": {
+        "pretty": "pretty",
+        "compact": "indent",
+        "sorted": "sort_keys",
+        "indent": "indent",
+    },
+    "csv": {
+        "pretty": "lineterminator",
+        "compact": "lineterminator",
+        "sorted": "sort_columns",
+        "line_separator": "lineterminator",
+        "item_separator": "delimiter",
+    },
+}
+
+
+# Supported options per format
+_FORMAT_SUPPORTED_OPTIONS: Dict[str, Set[str]] = {
+    "json": {
+        "pretty", "compact", "sorted", "canonical", "indent",
+        "ensure_ascii", "allow_nan"
+    },
+    "yaml": {
+        "pretty", "compact", "sorted", "canonical", "indent",
+        "strip_whitespace"
+    },
+    "xml": {
+        "pretty", "compact", "sorted", "canonical", "indent",
+        "preserve_quotes", "declaration", "encoding"
+    },
+    "toml": {
+        "pretty", "compact", "sorted", "indent"
+    },
+    "csv": {
+        "pretty", "compact", "sorted", "line_separator", "item_separator"
+    },
+    "msgpack": {
+        "compact"  # Always compact
+    },
+    "bson": {
+        "compact"  # Always compact
+    },
+    "cbor": {
+        "compact"  # Always compact
+    },
+}
+
+
+def map_universal_options(
+    format_name: str,
+    universal_options: Optional[Dict[str, Any]] = None,
+    **kwargs: Any
+) -> Dict[str, Any]:
+    """
+    Map universal options to format-specific options.
+    
+    Args:
+        format_name: Serialization format name (json, yaml, xml, etc.)
+        universal_options: Optional dictionary of universal options
+        **kwargs: Universal options as keyword arguments (pretty, compact, sorted, etc.)
+        
+    Returns:
+        Dictionary of format-specific options
+        
+    Example:
+        >>> # Using dict
+        >>> options = map_universal_options("json", {"pretty": True, "sorted": True})
+        >>> # Returns: {"indent": 2, "sort_keys": True}
+        >>> 
+        >>> # Using keyword arguments
+        >>> options = map_universal_options("json", pretty=True, sorted=True)
+        >>> # Returns: {"indent": 2, "sort_keys": True}
+    """
+    # Merge dict and kwargs
+    if universal_options is None:
+        universal_options = {}
+    
+    # Merge kwargs into universal_options (kwargs override dict values)
+    merged_options = {**universal_options, **kwargs}
+    
+    format_lower = format_name.lower()
+    option_map = _FORMAT_OPTION_MAPS.get(format_lower, {})
+    format_options = {}
+    
+    # Handle canonical first (it implies sorted)
+    if merged_options.get("canonical"):
+        merged_options["sorted"] = True
+    
+    # Handle compact overriding pretty
+    if merged_options.get("compact") and merged_options.get("pretty"):
+        # Compact wins
+        merged_options.pop("pretty", None)
+    
+    for universal_key, universal_value in merged_options.items():
+        if universal_key in option_map:
+            format_key = option_map[universal_key]
+            
+            # Handle special mappings
+            if universal_key == "pretty" and format_lower == "json":
+                format_options[format_key] = 2 if universal_value else None
+                format_options["use_orjson"] = False
+            elif universal_key == "compact" and format_lower == "json":
+                format_options["indent"] = None
+                format_options["separators"] = (",", ":") if universal_value else None
+                format_options["use_orjson"] = True
+            elif universal_key == "pretty" and format_lower == "yaml":
+                format_options[format_key] = False if universal_value else True
+                format_options["indent"] = 2 if universal_value else None
+            elif universal_key == "compact" and format_lower == "yaml":
+                format_options[format_key] = True if universal_value else False
+            elif universal_key == "pretty" and format_lower == "xml":
+                format_options[format_key] = universal_value
+            elif universal_key == "compact" and format_lower == "xml":
+                format_options[format_key] = False if universal_value else True
+            elif universal_key == "canonical" and format_lower == "json":
+                format_options["sort_keys"] = True
+                format_options["ensure_ascii"] = True
+                format_options["indent"] = None
+                format_options["canonical"] = True
+            else:
+                format_options[format_key] = universal_value
+    
+    return format_options
+
+
+def get_supported_universal_options(format_name: Optional[str] = None) -> Set[str] | Dict[str, Any]:
+    """
+    Get list of supported universal options for a format, or all universal options info.
+    
+    Args:
+        format_name: Optional serialization format name. If None, returns all universal options info.
+        
+    Returns:
+        If format_name provided: Set of supported universal option names for that format
+        If format_name is None: Dictionary with all universal options metadata
+        
+    Example:
+        >>> # Get options for a specific format
+        >>> options = get_supported_universal_options("json")
+        >>> # Returns: {"pretty", "compact", "sorted", "canonical", ...}
+        >>> 
+        >>> # Get all universal options info
+        >>> all_options = get_supported_universal_options()
+        >>> # Returns: {"pretty": {"type": bool, "default": False, "formats": [...]}, ...}
+    """
+    if format_name is None:
+        # Return all universal options with metadata
+        option_info = {}
+        type_map = {
+            "pretty": bool,
+            "compact": bool,
+            "sorted": bool,
+            "canonical": bool,
+            "indent": int,
+            "ensure_ascii": bool,
+            "allow_nan": bool,
+            "preserve_quotes": bool,
+            "strip_whitespace": bool,
+            "encoding": str,
+            "declaration": bool,
+            "line_separator": str,
+            "item_separator": str,
+        }
+        default_map = {
+            "pretty": False,
+            "compact": False,
+            "sorted": False,
+            "canonical": False,
+            "indent": None,
+            "ensure_ascii": True,
+            "allow_nan": True,
+            "preserve_quotes": False,
+            "strip_whitespace": False,
+            "encoding": "utf-8",
+            "declaration": True,
+            "line_separator": "\n",
+            "item_separator": None,
+        }
+        
+        # Collect all options across all formats
+        all_option_names = set()
+        for format_opts in _FORMAT_SUPPORTED_OPTIONS.values():
+            all_option_names.update(format_opts)
+        
+        # Build option info
+        for option_name in all_option_names:
+            # Find formats that support this option
+            supporting_formats = [
+                fmt.upper() for fmt, opts in _FORMAT_SUPPORTED_OPTIONS.items()
+                if option_name in opts
+            ]
+            
+            option_info[option_name] = {
+                "type": type_map.get(option_name, Any),
+                "default": default_map.get(option_name, None),
+                "formats": supporting_formats,
+            }
+        
+        return option_info
+    
+    format_lower = format_name.lower()
+    return _FORMAT_SUPPORTED_OPTIONS.get(format_lower, set())
+
+
+def validate_universal_options(
+    format_name: str,
+    universal_options: Optional[Dict[str, Any]] = None,
+    **kwargs: Any
+) -> tuple[bool, Optional[str]]:
+    """
+    Validate universal options for a format.
+    
+    Args:
+        format_name: Serialization format name
+        universal_options: Optional dictionary of universal options to validate
+        **kwargs: Universal options as keyword arguments
+        
+    Returns:
+        Tuple of (is_valid, error_message)
+        
+    Example:
+        >>> # Using dict
+        >>> is_valid, error = validate_universal_options(
+        ...     "json", {"pretty": True, "invalid_option": True}
+        ... )
+        >>> # Returns: (False, "Unsupported option: invalid_option")
+        >>> 
+        >>> # Using keyword arguments
+        >>> is_valid, error = validate_universal_options("json", pretty=True)
+        >>> # Returns: (True, None)
+    """
+    # Merge dict and kwargs
+    if universal_options is None:
+        universal_options = {}
+    
+    # Merge kwargs into universal_options (kwargs override dict values)
+    merged_options = {**universal_options, **kwargs}
+    
+    format_lower = format_name.lower()
+    supported = get_supported_universal_options(format_lower)
+    
+    # Check for unsupported options
+    unsupported = set(merged_options.keys()) - supported
+    if unsupported:
+        return False, f"Unsupported options for {format_name}: {', '.join(unsupported)}"
+    
+    # Validate option types
+    type_map = {
+        "pretty": bool,
+        "compact": bool,
+        "sorted": bool,
+        "canonical": bool,
+        "ensure_ascii": bool,
+        "allow_nan": bool,
+        "preserve_quotes": bool,
+        "strip_whitespace": bool,
+        "indent": int,
+        "encoding": str,
+        "declaration": bool,
+        "line_separator": str,
+        "item_separator": str,
+    }
+    
+    for key, value in merged_options.items():
+        expected_type = type_map.get(key)
+        if expected_type and not isinstance(value, expected_type):
+            return False, f"Option '{key}' expects type {expected_type.__name__}, got {type(value).__name__}"
+    
+    # Check for conflicting options
+    if merged_options.get("pretty") and merged_options.get("compact"):
+        if merged_options["pretty"] and merged_options["compact"]:
+            return False, "Cannot use both 'pretty' and 'compact' options together"
+    
+    return True, None
+
+
+def get_all_supported_formats() -> List[str]:
+    """
+    Get list of all formats that support universal options.
+    
+    Returns:
+        List of format names
+    """
+    return list(_FORMAT_SUPPORTED_OPTIONS.keys())
+
+
+def get_format_option_info(format_name: str) -> Dict[str, Any]:
+    """
+    Get detailed information about format option support.
+    
+    Args:
+        format_name: Serialization format name
+        
+    Returns:
+        Dictionary with option information
+    """
+    format_lower = format_name.lower()
+    supported = get_supported_universal_options(format_lower)
+    option_map = _FORMAT_OPTION_MAPS.get(format_lower, {})
+    
+    return {
+        "format": format_name,
+        "supported_options": list(supported),
+        "option_mappings": option_map,
+        "total_options": len(supported),
+    }

exonware/xwsystem/io/serialization/utils/__init__.py

@@ -4,7 +4,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: November 9, 2025
 
 Serialization utilities module.
@@ -29,4 +29,3 @@ __all__ = [
     "validate_path_security",
     "normalize_path",
 ]
-

exonware/xwsystem/io/serialization/utils/path_ops.py

@@ -4,7 +4,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: November 9, 2025
 
 Path operations utilities for serialization formats.
@@ -13,7 +13,7 @@ Provides JSONPointer path parsing and manipulation utilities that serializers
 can use for path-based operations. Includes path validation for security.
 """
 
-from typing import Any, Union
+from typing import Any
 from pathlib import Path
 
 from ...errors import SerializationError
@@ -42,7 +42,7 @@ def validate_json_pointer(path: str) -> bool:
     Example:
         >>> validate_json_pointer("/users/0/name")  # Valid
         True
-        >>> validate_json_pointer("invalid")  # Invalid - must start with /
+        >>> validate_json_pointer("invalid")  # Invalid - starts with /
         ValueError
     """
     if not isinstance(path, str):
@@ -51,7 +51,7 @@ def validate_json_pointer(path: str) -> bool:
     if not path:
         raise ValueError("Path cannot be empty")
     
-    # JSONPointer must start with / for non-empty paths
+    # JSONPointer starts with / for non-empty paths
     if path != "/" and not path.startswith("/"):
         raise ValueError(f"JSONPointer path must start with '/', got: {path}")
     
@@ -65,7 +65,7 @@ def validate_json_pointer(path: str) -> bool:
     return True
 
 
-def parse_json_pointer(path: str) -> list[Union[str, int]]:
+def parse_json_pointer(path: str) -> list[str | int]:
     """
     Parse a JSONPointer path into a list of keys/indices.
     
@@ -301,4 +301,3 @@ def normalize_path(path: str) -> str:
         return "/"
     
     return path
-

exonware/xwsystem/io/source_reader.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""
+Source reader: load text content from a URI or local path.
+
+All logic for "read from path or URI" lives in xwsystem. Supports multiple
+schemes (file, http, https, ftp, etc.) with configurable security:
+- allowed_schemes: which protocols are allowed
+- allow_external: whether non-file (remote) sources are allowed
+- timeout_sec, max_size_mb: limits
+
+Callers (e.g. xwdata) pass SourceLoadConfig from their own config; xwsystem
+enforces it. No scheme or fetch logic in xwdata—single entry point here and
+via XWFile.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import urllib.parse
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from .common.atomic import FileOperationError
+from .stream.async_operations import async_safe_read_text
+
+
+# -----------------------------------------------------------------------------
+# Configuration (consumed by xwdata / xwschema; defined here for single source)
+# -----------------------------------------------------------------------------
+
+@dataclass
+class SourceLoadConfig:
+    """
+    Configuration for loading from a URI or path. Enforced by xwsystem.
+
+    Callers (xwdata) set this from their SecurityConfig/ReferenceConfig;
+    xwsystem validates scheme and size against these values.
+    """
+    allowed_schemes: tuple[str, ...] = ('file', 'http', 'https', 'ftp')
+    allow_external: bool = True
+    timeout_sec: float = 30.0
+    max_size_mb: float = 100.0
+    encoding: str = 'utf-8'
+
+    @classmethod
+    def strict(cls) -> SourceLoadConfig:
+        """Local files only, no external URIs."""
+        return cls(
+            allowed_schemes=('file',),
+            allow_external=False,
+            timeout_sec=10.0,
+            max_size_mb=10.0,
+        )
+
+    @classmethod
+    def relaxed(cls) -> SourceLoadConfig:
+        """Allow common external schemes."""
+        return cls(
+            allowed_schemes=('file', 'http', 'https', 'ftp'),
+            allow_external=True,
+            timeout_sec=60.0,
+            max_size_mb=500.0,
+        )
+
+
+# -----------------------------------------------------------------------------
+# Scheme detection and validation
+# -----------------------------------------------------------------------------
+
+def get_scheme(uri_or_path: str) -> str:
+    """
+    Return the URI scheme, or 'file' for a bare path.
+
+    Args:
+        uri_or_path: URI (http://..., file://...) or local path
+
+    Returns:
+        Lowercase scheme (e.g. 'file', 'http', 'https', 'ftp') or 'file' for paths.
+    """
+    if not uri_or_path or not isinstance(uri_or_path, str):
+        return 'file'
+    parsed = urllib.parse.urlparse(uri_or_path)
+    scheme = (parsed.scheme or '').lower()
+    if scheme and parsed.netloc:
+        return scheme
+    return 'file'
+
+
+def is_external_scheme(scheme: str) -> bool:
+    """Return True if scheme is not local file."""
+    return scheme not in ('file', '')
+
+
+def is_http_url(path_or_url: str) -> bool:
+    """Return True if the string is an http(s) URL (convenience)."""
+    return get_scheme(path_or_url) in ('http', 'https')
+
+
+def _validate_config(uri_or_path: str, config: SourceLoadConfig) -> None:
+    """Raise FileOperationError if URI/path is not allowed by config."""
+    scheme = get_scheme(uri_or_path)
+    if scheme not in config.allowed_schemes:
+        raise FileOperationError(
+            f"Scheme '{scheme}' not allowed. Allowed: {config.allowed_schemes}"
+        )
+    if is_external_scheme(scheme) and not config.allow_external:
+        raise FileOperationError(
+            "External sources are disabled (allow_external=False)"
+        )
+
+
+# -----------------------------------------------------------------------------
+# Async read: single entry point for xwsystem (and XWFile / xwdata)
+# -----------------------------------------------------------------------------
+
+async def read_source_text(
+    uri_or_path: str,
+    config: Optional[SourceLoadConfig] = None,
+    timeout_sec: Optional[float] = None,
+    max_size_mb: Optional[float] = None,
+    encoding: Optional[str] = None,
+) -> tuple[str, dict]:
+    """
+    Read text from a URI or local path (async). All scheme and fetch logic here.
+
+    Security and behavior are driven by config (from xwdata). Supported schemes:
+    - file: local path (existing async_safe_read_text)
+    - http, https: aiohttp or urllib
+    - ftp: urllib (ftp://)
+
+    Args:
+        uri_or_path: File path or URI (file://, http://, https://, ftp://)
+        config: SourceLoadConfig (allowed_schemes, allow_external, limits). If None, relaxed defaults.
+        timeout_sec: Override config timeout (optional)
+        max_size_mb: Override config max size (optional)
+        encoding: Override config encoding for file reads (optional)
+
+    Returns:
+        (content_str, metadata) with at least 'source' and 'content_type'.
+    """
+    cfg = config or SourceLoadConfig.relaxed()
+    timeout = timeout_sec if timeout_sec is not None else cfg.timeout_sec
+    max_mb = max_size_mb if max_size_mb is not None else cfg.max_size_mb
+    enc = encoding or cfg.encoding
+
+    _validate_config(uri_or_path, cfg)
+    scheme = get_scheme(uri_or_path)
+
+    if scheme == 'file':
+        path = uri_or_path
+        if path.startswith('file://'):
+            path = urllib.parse.unquote(urllib.parse.urlparse(path).path)
+        content = await async_safe_read_text(
+            Path(path), encoding=enc, max_size_mb=max_mb
+        )
+        return content, {'source': uri_or_path, 'content_type': None}
+
+    if scheme in ('http', 'https'):
+        return await _read_http_text(uri_or_path, timeout, max_mb)
+
+    if scheme == 'ftp':
+        return await _read_ftp_text(uri_or_path, timeout, max_mb)
+
+    raise FileOperationError(f"Unsupported scheme for reading: {scheme}")
+
+
+async def _read_http_text(
+    url: str, timeout_sec: float, max_size_mb: float
+) -> tuple[str, dict]:
+    """Fetch http(s) URL; return (text, metadata)."""
+    content_type: Optional[str] = None
+    try:
+        try:
+            import aiohttp
+            timeout = aiohttp.ClientTimeout(total=timeout_sec)
+            async with aiohttp.ClientSession(timeout=timeout) as session:
+                async with session.get(url) as response:
+                    response.raise_for_status()
+                    raw = await response.read()
+                    content_type = response.headers.get('Content-Type') or None
+        except ImportError:
+            def _fetch() -> tuple[bytes, Optional[str]]:
+                req = urllib.request.Request(url)
+                with urllib.request.urlopen(req, timeout=timeout_sec) as resp:
+                    ct = resp.headers.get('Content-Type')
+                    return resp.read(), ct if ct else None
+
+            loop = asyncio.get_event_loop()
+            raw, content_type = await loop.run_in_executor(None, _fetch)
+    except Exception as e:
+        raise FileOperationError(f"Failed to load from URL: {e}") from e
+
+    size_mb = len(raw) / (1024 * 1024)
+    if size_mb > max_size_mb:
+        raise FileOperationError(
+            f"URL response size ({size_mb:.1f}MB) exceeds max ({max_size_mb}MB)"
+        )
+    text = raw.decode('utf-8', errors='replace')
+    return text, {'source': url, 'content_type': content_type}
+
+
+async def _read_ftp_text(
+    url: str, timeout_sec: float, max_size_mb: float
+) -> tuple[str, dict]:
+    """Fetch ftp URL via urllib in executor; return (text, metadata)."""
+    def _fetch() -> bytes:
+        with urllib.request.urlopen(url, timeout=timeout_sec) as resp:
+            return resp.read()
+
+    loop = asyncio.get_event_loop()
+    try:
+        raw = await loop.run_in_executor(None, _fetch)
+    except Exception as e:
+        raise FileOperationError(f"Failed to load from FTP: {e}") from e
+
+    size_mb = len(raw) / (1024 * 1024)
+    if size_mb > max_size_mb:
+        raise FileOperationError(
+            f"FTP response size ({size_mb:.1f}MB) exceeds max ({max_size_mb}MB)"
+        )
+    text = raw.decode('utf-8', errors='replace')
+    return text, {'source': url, 'content_type': None}

exonware/xwsystem/io/stream/__init__.py

@@ -4,7 +4,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: 30-Oct-2025
 
 Stream operations and codec-integrated I/O.