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

exonware/xwsystem/shared/defs.py

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

exonware/xwsystem/shared/errors.py

@@ -1,9 +1,10 @@
+#exonware/xwsystem/src/exonware/xwsystem/shared/errors.py
 #exonware/xwsystem/shared/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
 
 Shared exceptions (merged from the former core module).
@@ -74,4 +75,3 @@ class CoreOperationError(CoreError):
     """Raised when core operation fails."""
 
     pass
-

exonware/xwsystem/shared/xwobject.py

@@ -0,0 +1,316 @@
+#exonware/xwsystem/src/exonware/xwsystem/shared/xwobject.py
+#exonware/xwsystem/shared/xwobject.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.4
+Generation Date: September 04, 2025
+
+XWObject - Concrete base class for all objects in the eXonware ecosystem.
+"""
+
+from typing import Any, Optional
+from datetime import datetime
+import uuid
+
+from .base import AObject
+from .contracts import IObject
+
+
+class XWObject(AObject):
+    """
+    Concrete base class for all objects in the eXonware ecosystem.
+    
+    Provides common functionality shared by objects across xwauth, xwstorage,
+    xwentity, and other libraries:
+    - Identity management (id property, uid with UUID generation)
+    - Timestamp tracking (created_at, updated_at - abstract, must be set by subclasses)
+    - Metadata (title, description - optional)
+    - Serialization (to_dict, to_native)
+    - Storage operations (save, load - abstract, to be implemented by subclasses)
+    
+    Subclasses must implement:
+    - id property (returns object identifier)
+    - created_at property
+    - updated_at property
+    - to_dict() method (should include id, uid, created_at, updated_at, title, description)
+    - save() method (object-specific storage logic)
+    - load() method (object-specific loading logic)
+    
+    Example:
+        >>> class MyEntity(XWObject):
+        ...     def __init__(self):
+        ...         super().__init__()
+        ...         self._id = "my_id"
+        ...         self._created_at = datetime.now()
+        ...         self._updated_at = self._created_at
+        ...         self._title = "My Entity"
+        ...         self._description = "Description of my entity"
+        ...
+        ...     @property
+        ...     def id(self) -> str:
+        ...         return self._id
+        ...
+        ...     @property
+        ...     def created_at(self) -> datetime:
+        ...         return self._created_at
+        ...
+        ...     @property
+        ...     def updated_at(self) -> datetime:
+        ...         return self._updated_at
+    """
+    
+    def __init__(self, object_id: Optional[str] = None):
+        """
+        Initialize XWObject base class.
+        
+        Generates uid (GUID) on creation. Subclasses should call super().__init__() 
+        and then initialize:
+        - self._created_at
+        - self._updated_at
+        - self._title (optional)
+        - self._description (optional)
+        
+        Args:
+            object_id: Optional object identifier (subclasses define their own id property)
+        """
+        super().__init__(object_id)
+        # Generate uid (GUID) on creation
+        self._uid = str(uuid.uuid4())
+        # Timestamps are initialized by subclasses
+        # Set self._created_at and self._updated_at in __init__
+        # Title and description are optional
+        self._title: Optional[str] = None
+        self._description: Optional[str] = None
+    
+    @property
+    def uid(self) -> str:
+        """
+        Get the unique object GUID (universal identifier).
+        
+        This is automatically generated on object creation and provides
+        a globally unique identifier for the object.
+        """
+        return self._uid
+    
+    @property
+    def title(self) -> Optional[str]:
+        """
+        Get the object title.
+        
+        Returns:
+            Title string or None if not set
+        """
+        return self._title
+    
+    @property
+    def description(self) -> Optional[str]:
+        """
+        Get the object description.
+        
+        Returns:
+            Description string or None if not set
+        """
+        return self._description
+    
+    def _update_timestamp(self) -> None:
+        """
+        Update the updated_at timestamp.
+        
+        Subclasses should call this method when modifying the object.
+        This is a helper method that subclasses should implement by updating
+        self._updated_at. The default implementation does nothing.
+        """
+        # Subclasses implement this by updating self._updated_at
+        # This is a helper method that can be overridden
+        pass
+    
+    def to_native(self) -> Any:
+        """
+        Get object as native representation.
+        
+        Default implementation returns to_dict(). Subclasses can override
+        if they need a different native representation.
+        """
+        return self.to_dict()
+
+    def __str__(self) -> str:
+        """
+        String representation as JSON-like output (reusable by XWSchema, XWData, etc.).
+        Uses xwsystem JsonSerializer; to_native() so subclasses get their own content.
+        """
+        try:
+            from exonware.xwsystem.io.serialization import JsonSerializer
+            out = JsonSerializer().encode(
+                self.to_native(),
+                options={"indent": 2, "ensure_ascii": False, "default": str}
+            )
+            return out if isinstance(out, str) else out.decode("utf-8")
+        except Exception:
+            return super().__str__()
+
+    @classmethod
+    def from_string(cls, s: str) -> "IObject":
+        """
+        Create instance from JSON string (reusable by subclasses).
+        Uses xwsystem JsonSerializer. Default: decode, create instance, call from_native(data).
+        Subclasses (e.g. XWSchema) may override to construct from schema/data dict.
+        """
+        from exonware.xwsystem.io.serialization import JsonSerializer
+        data = JsonSerializer().decode(s)
+        obj = cls()
+        obj.from_native(data)
+        return obj
+
+    def from_native(self, data: dict[str, Any]) -> "IObject":
+        """
+        Populate object from native Python dictionary.
+        
+        This method takes a dictionary and populates the object's properties.
+        It handles:
+        - uid: Sets _uid if present in dict
+        - title: Sets _title if present in dict
+        - description: Sets _description if present in dict
+        - created_at: Sets _created_at if present (as datetime or ISO string)
+        - updated_at: Sets _updated_at if present (as datetime or ISO string)
+        - id: Sets _id if present (subclasses may use this)
+        - Any other attributes: Sets them directly on the object
+        
+        Args:
+            data: Dictionary containing object data
+            
+        Returns:
+            Self (for chaining) - returns IObject to match protocol
+            
+        Example:
+            >>> obj = XWObject()
+            >>> obj.from_native({
+            ...     "uid": "123e4567-e89b-12d3-a456-426614174000",
+            ...     "title": "My Object",
+            ...     "description": "Description",
+            ...     "created_at": "2025-01-25T10:00:00",
+            ...     "updated_at": "2025-01-25T11:00:00"
+            ... })
+        """
+        if not isinstance(data, dict):
+            raise TypeError(f"from_native expects a dict, got {type(data).__name__}")
+        
+        # Handle uid
+        if "uid" in data:
+            self._uid = str(data["uid"])
+        
+        # Handle title
+        if "title" in data:
+            self._title = data["title"] if data["title"] is not None else None
+        
+        # Handle description
+        if "description" in data:
+            self._description = data["description"] if data["description"] is not None else None
+        
+        # Handle created_at (if _created_at attribute exists)
+        if "created_at" in data and hasattr(self, "_created_at"):
+            created_at_value = data["created_at"]
+            if isinstance(created_at_value, str):
+                try:
+                    self._created_at = datetime.fromisoformat(created_at_value.replace("Z", "+00:00"))
+                except (ValueError, AttributeError):
+                    # If parsing fails, try to set as string (subclass may handle it)
+                    self._created_at = created_at_value
+            elif isinstance(created_at_value, datetime):
+                self._created_at = created_at_value
+        
+        # Handle updated_at (if _updated_at attribute exists)
+        if "updated_at" in data and hasattr(self, "_updated_at"):
+            updated_at_value = data["updated_at"]
+            if isinstance(updated_at_value, str):
+                try:
+                    self._updated_at = datetime.fromisoformat(updated_at_value.replace("Z", "+00:00"))
+                except (ValueError, AttributeError):
+                    # If parsing fails, try to set as string (subclass may handle it)
+                    self._updated_at = updated_at_value
+            elif isinstance(updated_at_value, datetime):
+                self._updated_at = updated_at_value
+        
+        # Handle id (if _id attribute exists - subclasses may use this)
+        if "id" in data and hasattr(self, "_id"):
+            self._id = str(data["id"])
+        
+        # Handle any other attributes in the dict
+        # Set them directly on the object (subclasses may use this)
+        for key, value in data.items():
+            if key not in ("uid", "title", "description", "created_at", "updated_at", "id"):
+                setattr(self, key, value)
+        
+        return self
+    
+    def __getitem__(self, key: str) -> Any:
+        """
+        Get object property using dictionary-style access.
+        
+        Supports accessing properties like:
+        - obj["uid"] -> returns uid property
+        - obj["title"] -> returns title property
+        - obj["description"] -> returns description property
+        - obj["id"] -> returns id property (if implemented)
+        - obj["created_at"] -> returns created_at property (if implemented)
+        - obj["updated_at"] -> returns updated_at property (if implemented)
+        - obj["property_name"] -> returns any other attribute
+        
+        Args:
+            key: Property name to access
+            
+        Returns:
+            Property value
+            
+        Raises:
+            KeyError: If property doesn't exist
+            
+        Example:
+            >>> obj = XWObject()
+            >>> obj._title = "My Title"
+            >>> print(obj["title"])  # "My Title"
+            >>> print(obj["uid"])    # UUID string
+        """
+        # Try to get via property methods first
+        if key == "uid":
+            return self.uid
+        elif key == "title":
+            return self.title
+        elif key == "description":
+            return self.description
+        elif key == "id":
+            # Try to get id property (may be abstract in some cases)
+            try:
+                return self.id
+            except (AttributeError, NotImplementedError):
+                # Fall back to _id attribute if it exists
+                if hasattr(self, "_id"):
+                    return self._id
+                raise KeyError(f"Property 'id' not available")
+        elif key == "created_at":
+            # Try to get created_at property (may be abstract)
+            try:
+                return self.created_at
+            except (AttributeError, NotImplementedError):
+                # Fall back to _created_at attribute if it exists
+                if hasattr(self, "_created_at"):
+                    return self._created_at
+                raise KeyError(f"Property 'created_at' not available")
+        elif key == "updated_at":
+            # Try to get updated_at property (may be abstract)
+            try:
+                return self.updated_at
+            except (AttributeError, NotImplementedError):
+                # Fall back to _updated_at attribute if it exists
+                if hasattr(self, "_updated_at"):
+                    return self._updated_at
+                raise KeyError(f"Property 'updated_at' not available")
+        else:
+            # Try to get as attribute
+            if hasattr(self, key):
+                return getattr(self, key)
+            # Try with underscore prefix (private attributes)
+            if hasattr(self, f"_{key}"):
+                return getattr(self, f"_{key}")
+            raise KeyError(f"Property '{key}' not found")

exonware/xwsystem/structures/__init__.py

@@ -1,3 +1,4 @@
+#exonware/xwsystem/src/exonware/xwsystem/structures/__init__.py
 """
 Data structure utilities for xwsystem.
 """

exonware/xwsystem/structures/base.py

@@ -1,16 +1,17 @@
+#exonware/xwsystem/src/exonware/xwsystem/structures/base.py
 #exonware/xwsystem/structures/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
 
 Structures module base classes - abstract classes for data structure functionality.
 """
 
 from abc import ABC, abstractmethod
-from typing import Any, Optional, Union, Iterator
+from typing import Any, Optional, Iterator
 from .contracts import StructureType, TraversalType, ValidationLevel
 
 

exonware/xwsystem/structures/circular_detector.py

@@ -1,3 +1,4 @@
+#exonware/xwsystem/src/exonware/xwsystem/structures/circular_detector.py
 """
 Circular reference detection and management utilities.
 """
@@ -5,7 +6,7 @@ Circular reference detection and management utilities.
 import logging
 import weakref
 from collections import defaultdict
-from typing import Any, Optional, Union
+from typing import Any, Optional
 
 logger = logging.getLogger(__name__)
 
@@ -56,6 +57,18 @@ class CircularReferenceDetector:
             return True
         finally:
             self.reset()
+    
+    def has_circular_references(self, obj: Any) -> bool:
+        """
+        Check if an object has circular references (alias for is_circular).
+
+        Args:
+            obj: Object to check
+
+        Returns:
+            True if circular references are detected
+        """
+        return self.is_circular(obj)
 
     def traverse(self, obj: Any, path: list[str]) -> None:
         """
@@ -139,7 +152,7 @@ class CircularReferenceDetector:
 
             self.traverse(value, new_path)
 
-    def _traverse_sequence(self, obj: Union[list, tuple, set], path: list[str]) -> None:
+    def _traverse_sequence(self, obj: list | tuple | set, path: list[str]) -> None:
         """Traverse sequence objects (list, tuple, set)."""
         for i, item in enumerate(obj):
             new_path = path + [f"[{i}]"]
@@ -298,18 +311,6 @@ def has_circular_references(obj: Any, max_depth: int = 100) -> bool:
     """
     detector = CircularReferenceDetector(max_depth=max_depth)
     return detector.is_circular(obj)
-
-
-class CircularDetector(CircularReferenceDetector):
-    """Alias for CircularReferenceDetector for backward compatibility."""
-    
-    def __init__(self, max_depth: int = 100):
-        """Initialize circular detector."""
-        super().__init__(max_depth)
-    
-    def detect(self, obj: Any) -> bool:
-        """Detect circular references (alias for is_circular)."""
-        return self.is_circular(obj)
     
     def check(self, obj: Any) -> bool:
         """Check for circular references (alias for is_circular)."""

exonware/xwsystem/structures/contracts.py

@@ -1,15 +1,17 @@
+#exonware/xwsystem/src/exonware/xwsystem/structures/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
 
 Structures module contracts - interfaces and enums for data structure functionality.
 """
 
-from abc import ABC, abstractmethod
-from typing import Any, Optional, Union, Iterator, Callable
+from __future__ import annotations
+
+from typing import Any, Optional, Iterator, Callable, Protocol, runtime_checkable
 
 # Import enums from types module
 from .defs import (
@@ -22,177 +24,152 @@ from .defs import (
 )
 
 
-class ITreeNode(ABC):
+@runtime_checkable
+class ITreeNode(Protocol):
     """Interface for tree node operations."""
     
     @property
-    @abstractmethod
     def value(self) -> Any:
         """Node value."""
-        pass
+        ...
     
     @property
-    @abstractmethod
-    def children(self) -> list['ITreeNode']:
+    def children(self) -> list[ITreeNode]:
         """Node children."""
-        pass
+        ...
     
     @property
-    @abstractmethod
-    def parent(self) -> Optional['ITreeNode']:
+    def parent(self) -> Optional[ITreeNode]:
         """Node parent."""
-        pass
+        ...
     
-    @abstractmethod
-    def add_child(self, child: 'ITreeNode') -> None:
+    def add_child(self, child: ITreeNode) -> None:
         """Add child node."""
-        pass
+        ...
     
-    @abstractmethod
-    def remove_child(self, child: 'ITreeNode') -> None:
+    def remove_child(self, child: ITreeNode) -> None:
         """Remove child node."""
-        pass
+        ...
     
-    @abstractmethod
     def is_leaf(self) -> bool:
         """Check if node is leaf."""
-        pass
+        ...
     
-    @abstractmethod
     def get_depth(self) -> int:
         """Get node depth."""
-        pass
+        ...
 
 
-class ITreeWalker(ABC):
+@runtime_checkable
+class ITreeWalker(Protocol):
     """Interface for tree walking operations."""
     
-    @abstractmethod
     def walk_preorder(self, root: ITreeNode) -> Iterator[ITreeNode]:
         """Walk tree in preorder."""
-        pass
+        ...
     
-    @abstractmethod
     def walk_inorder(self, root: ITreeNode) -> Iterator[ITreeNode]:
         """Walk tree in inorder."""
-        pass
+        ...
     
-    @abstractmethod
     def walk_postorder(self, root: ITreeNode) -> Iterator[ITreeNode]:
         """Walk tree in postorder."""
-        pass
+        ...
     
-    @abstractmethod
     def walk_level_order(self, root: ITreeNode) -> Iterator[ITreeNode]:
         """Walk tree in level order."""
-        pass
+        ...
     
-    @abstractmethod
     def find_nodes(self, root: ITreeNode, predicate: Callable[[ITreeNode], bool]) -> list[ITreeNode]:
         """Find nodes matching predicate."""
-        pass
+        ...
 
 
-class ICircularDetector(ABC):
+@runtime_checkable
+class ICircularDetector(Protocol):
     """Interface for circular reference detection."""
     
-    @abstractmethod
     def detect_circular_reference(self, obj: Any) -> bool:
         """Detect circular reference in object."""
-        pass
+        ...
     
-    @abstractmethod
     def find_circular_paths(self, obj: Any) -> list[list[Any]]:
         """Find all circular paths."""
-        pass
+        ...
     
-    @abstractmethod
     def get_circular_objects(self, obj: Any) -> list[Any]:
         """Get objects involved in circular references."""
-        pass
+        ...
     
-    @abstractmethod
     def break_circular_references(self, obj: Any) -> Any:
         """Break circular references."""
-        pass
+        ...
 
 
-class IGraphNode(ABC):
+@runtime_checkable
+class IGraphNode(Protocol):
     """Interface for graph node operations."""
     
     @property
-    @abstractmethod
     def id(self) -> str:
         """Node ID."""
-        pass
+        ...
     
     @property
-    @abstractmethod
     def data(self) -> Any:
         """Node data."""
-        pass
+        ...
     
     @property
-    @abstractmethod
-    def neighbors(self) -> list['IGraphNode']:
+    def neighbors(self) -> list[IGraphNode]:
         """Node neighbors."""
-        pass
+        ...
     
-    @abstractmethod
-    def add_neighbor(self, neighbor: 'IGraphNode', weight: Optional[float] = None) -> None:
+    def add_neighbor(self, neighbor: IGraphNode, weight: Optional[float] = None) -> None:
         """Add neighbor node."""
-        pass
+        ...
     
-    @abstractmethod
-    def remove_neighbor(self, neighbor: 'IGraphNode') -> None:
+    def remove_neighbor(self, neighbor: IGraphNode) -> None:
         """Remove neighbor node."""
-        pass
+        ...
     
-    @abstractmethod
-    def get_edge_weight(self, neighbor: 'IGraphNode') -> Optional[float]:
+    def get_edge_weight(self, neighbor: IGraphNode) -> Optional[float]:
         """Get edge weight to neighbor."""
-        pass
+        ...
 
 
-class IGraph(ABC):
+@runtime_checkable
+class IGraph(Protocol):
     """Interface for graph operations."""
     
-    @abstractmethod
     def add_node(self, node: IGraphNode) -> None:
         """Add node to graph."""
-        pass
+        ...
     
-    @abstractmethod
     def remove_node(self, node_id: str) -> None:
         """Remove node from graph."""
-        pass
+        ...
     
-    @abstractmethod
     def get_node(self, node_id: str) -> Optional[IGraphNode]:
         """Get node by ID."""
-        pass
+        ...
     
-    @abstractmethod
     def add_edge(self, from_node: str, to_node: str, weight: Optional[float] = None) -> None:
         """Add edge between nodes."""
-        pass
+        ...
     
-    @abstractmethod
     def remove_edge(self, from_node: str, to_node: str) -> None:
         """Remove edge between nodes."""
-        pass
+        ...
     
-    @abstractmethod
     def get_all_nodes(self) -> list[IGraphNode]:
         """Get all nodes."""
-        pass
+        ...
     
-    @abstractmethod
     def get_all_edges(self) -> list[tuple]:
         """Get all edges."""
-        pass
+        ...
     
-    @abstractmethod
     def is_connected(self, from_node: str, to_node: str) -> bool:
         """Check if nodes are connected."""
-        pass
+        ...