orionis 0.431.0__py3-none-any.whl → 0.434.0__py3-none-any.whl

orionis/support/entities/base.py

@@ -5,11 +5,10 @@ class BaseEntity:
 
     def __post_init__(self):
         """
-        Post-initialization hook for dataclass instances.
+        Called automatically after the dataclass instance is initialized.
 
-        This method is automatically called after the dataclass `__init__` method.
-        It is intended to be overridden by subclasses to perform additional initialization
-        or validation logic after all fields have been set.
+        This method is intended to be overridden by subclasses to perform additional
+        initialization or validation after all fields have been set.
 
         Parameters
         ----------
@@ -18,60 +17,42 @@ class BaseEntity:
         Returns
         -------
         None
-            This method does not return any value.
-
-        Notes
-        -----
-        By default, this method does nothing. Subclasses can override it to implement
-        custom post-initialization behavior.
         """
-
         pass
 
     def toDict(self) -> dict:
         """
-        Converts the current dataclass instance into a dictionary.
-
-        Parameters
-        ----------
-        None
+        Convert the dataclass instance to a dictionary.
 
         Returns
         -------
         dict
-            A dictionary containing all fields of the instance, with field names as keys and their corresponding values.
-
-        Notes
-        -----
-        This method uses `dataclasses.asdict` to recursively convert the dataclass instance and any nested dataclasses into dictionaries.
-        Enum values are preserved as their actual values.
+            Dictionary representation of the dataclass instance, including nested dataclasses.
         """
-
-        # Use asdict to convert the dataclass instance to a dictionary, including nested dataclasses
         return asdict(self)
 
     def getFields(self):
         """
-        Retrieves detailed information about each field in the current dataclass instance.
-
-        Parameters
-        ----------
-        None
+        Get detailed information about each field in the dataclass instance.
 
         Returns
         -------
         list of dict
-            Each dictionary in the returned list contains:
-                - name (str): The name of the field.
-                - types (list of str): The type(s) of the field, represented as a list of type names.
-                - default: The default value of the field, resolved from the field definition, default factory, or metadata.
-                - metadata (dict): The metadata associated with the field.
+            A list where each element is a dictionary containing:
+            - name : str
+                The name of the field.
+            - types : list of str
+                The type(s) of the field as a list of type names.
+            - default : Any
+                The default value of the field, resolved from the field definition, default factory, or metadata.
+            - metadata : dict
+                The metadata associated with the field.
 
         Notes
         -----
-        - Handles complex field types, including unions and generics, by representing them as lists of type names.
-        - Resolves default values from direct assignment, default factories, or metadata, and normalizes dataclass and Enum values.
-        - Metadata defaults are normalized if present and callable or dataclass/Enum types.
+        Handles complex field types, including unions and generics, by representing them as lists of type names.
+        Resolves default values from direct assignment, default factories, or metadata, and normalizes dataclass and Enum values.
+        Metadata defaults are normalized if present and callable or dataclass/Enum types.
         """
 
         # List to hold field information dictionaries

orionis/support/facades/console.py

@@ -5,17 +5,11 @@ class Console(Facade):
     @classmethod
     def getFacadeAccessor(cls) -> str:
         """
-        Returns the service container binding key used to resolve the console component.
-
-        This method provides the unique string identifier that the service container uses
-        to locate and instantiate the console service. It is typically used internally
-        by the Facade base class to delegate calls to the underlying implementation.
+        Get the service container binding key for the console component.
 
         Returns
         -------
         str
-            The string key `"core.orionis.console"` that identifies the console service in the container.
+            The binding key used to resolve the console service from the container.
         """
-
-        # Return the binding key for the console service in the container
-        return "core.orionis.console"
+        return "core.orionis.console"

orionis/support/facades/dumper.py

@@ -5,17 +5,11 @@ class Dumper(Facade):
     @classmethod
     def getFacadeAccessor(cls) -> str:
         """
-        Returns the binding key used to retrieve the dumper component from the service container.
-
-        This method provides the unique string identifier that the service container uses to resolve
-        and return the dumper service instance. It is typically used internally by the Facade base class
-        to access the underlying implementation.
+        Returns the service container binding key for the dumper component.
 
         Returns
         -------
         str
-            The string "core.orionis.dumper", which is the service container binding key for the dumper component.
+            The binding key "core.orionis.dumper" used to resolve the dumper service from the container.
         """
-
-        # Return the service container binding key for the dumper component
-        return "core.orionis.dumper"
+        return "core.orionis.dumper"

orionis/support/facades/logger.py

@@ -5,18 +5,12 @@ class Log(Facade):
     @classmethod
     def getFacadeAccessor(cls) -> str:
         """
-        Returns the binding key used to resolve the logger service from the service container.
-
-        This method provides the unique identifier required by the service container to retrieve
-        the logger component. It is used internally by the Facade base class to delegate calls
-        to the appropriate service implementation.
+        Returns the binding key for the logger service in the service container.
 
         Returns
         -------
         str
-            The binding key for the logger service in the service container, specifically
+            The unique identifier used to resolve the logger service, specifically
             "core.orionis.logger".
         """
-
-        # Return the service container binding key for the logger component
-        return "core.orionis.logger"
+        return "core.orionis.logger"

orionis/support/facades/path_resolver.py

@@ -5,18 +5,11 @@ class PathResolver(Facade):
     @classmethod
     def getFacadeAccessor(cls):
         """
-        Returns the service container binding key used to resolve the path resolver component.
-
-        This method provides the unique string identifier that the service container uses
-        to locate and retrieve the path resolver service. It is typically used internally
-        by the facade mechanism to delegate calls to the appropriate underlying implementation.
+        Returns the binding key for the path resolver service in the container.
 
         Returns
         -------
         str
-            The string key "core.orionis.path_resolver" that identifies the path resolver
-            service in the container.
+            The unique string identifier for the path resolver service, used by the service container.
         """
-
-        # Return the binding key for the path resolver service in the container
-        return "core.orionis.path_resolver"
+        return "core.orionis.path_resolver"

orionis/support/facades/progress_bar.py

@@ -5,18 +5,11 @@ class ProgressBar(Facade):
     @classmethod
     def getFacadeAccessor(cls):
         """
-        Returns the binding key used to retrieve the progress bar service from the service container.
-
-        This method provides the unique string identifier that the service container uses to resolve
-        the progress bar component. It is typically used internally by the Facade system to access
-        the underlying implementation.
+        Returns the binding key for the progress bar service.
 
         Returns
         -------
         str
-            The binding key for the progress bar service in the service container, specifically
-            "core.orionis.progress_bar".
+            The unique identifier used to retrieve the progress bar service from the service container.
         """
-
-        # Return the service container binding key for the progress bar component
-        return "core.orionis.progress_bar"
+        return "core.orionis.progress_bar"

orionis/support/facades/testing.py

@@ -5,18 +5,12 @@ class Test(Facade):
     @classmethod
     def getFacadeAccessor(cls) -> str:
         """
-        Returns the service container binding key for the testing component.
-
-        This method provides the unique string identifier used by the service container
-        to resolve the testing component. It is typically used internally by the Facade
-        system to retrieve the correct implementation from the container.
+        Returns the binding key for the testing component in the service container.
 
         Returns
         -------
         str
-            The string key "core.orionis.testing" that identifies the testing component
-            in the service container.
+            The unique string identifier for the testing component, used by the service
+            container to resolve the appropriate implementation.
         """
-
-        # Return the binding key for the testing component in the service container
-        return "core.orionis.testing"
+        return "core.orionis.testing"

orionis/support/facades/workers.py

@@ -5,18 +5,13 @@ class Workers(Facade):
     @classmethod
     def getFacadeAccessor(cls):
         """
-        Returns the service container binding key for the workers component.
-
-        This method provides the unique string identifier used by the service container
-        to resolve the workers service. It is typically used internally by the Facade
-        mechanism to access the underlying implementation.
+        Returns the binding key for the workers service in the service container.
 
         Returns
         -------
         str
-            The string key "core.orionis.workers" that identifies the workers service
-            in the service container.
+            The identifier string for the workers service, used by the service container
+            to resolve the corresponding implementation.
         """
 
-        # Return the binding key for the workers service in the container
-        return "core.orionis.workers"
+        return "core.orionis.workers"

orionis/support/formatter/exceptions/contracts/parser.py

@@ -3,36 +3,39 @@ from typing import Any, Dict
 
 class IExceptionParser(ABC):
     """
-    Abstract base interface for classes that parse exceptions
-    into a structured dictionary format.
+    Interface for parsing exceptions into structured dictionary representations.
+
+    This abstract base class defines the contract for classes that convert
+    exception objects into a standardized dictionary format, which may include
+    details such as error type, message, code, stack trace, and cause.
     """
 
     @property
     @abstractmethod
     def raw_exception(self) -> Exception:
         """
-        Get the original exception object.
+        Returns the original exception instance.
 
         Returns
         -------
         Exception
-            The raw exception instance.
+            The exception object to be parsed.
         """
         pass
 
     @abstractmethod
     def toDict(self) -> Dict[str, Any]:
         """
-        Serialize the exception into a dictionary.
+        Converts the exception into a structured dictionary.
 
         Returns
         -------
         dict
-            A structured representation of the exception including details such as:
+            A dictionary containing details about the exception, such as:
             - error_type
             - error_message
             - error_code
             - stack_trace
-            - cause (if any)
+            - cause (if present)
         """
         pass

orionis/support/formatter/exceptions/parser.py

@@ -4,24 +4,21 @@ from orionis.support.formatter.exceptions.contracts.parser import IExceptionPars
 
 class ExceptionParser(IExceptionParser):
     """
-    A utility class to parse an exception and convert it into a structured dictionary.
+    Parses an exception and converts it into a structured dictionary representation.
+
+    Parameters
+    ----------
+    exception : Exception
+        The exception instance to be parsed.
     """
 
     def __init__(self, exception: Exception) -> None:
-        """
-        Initialize the ExceptionParser with the given exception.
-
-        Parameters
-        ----------
-        exception : Exception
-            The exception to be parsed.
-        """
         self.__exception = exception
 
     @property
     def raw_exception(self) -> Exception:
         """
-        Get the original exception object.
+        Returns the original exception object.
 
         Returns
         -------
@@ -32,21 +29,21 @@ class ExceptionParser(IExceptionParser):
 
     def toDict(self) -> Dict[str, Any]:
         """
-        Serialize the exception into a dictionary format.
+        Serializes the exception into a dictionary containing detailed error information.
 
         Returns
         -------
         dict
-            A dictionary containing:
-            - 'error_type': The type of exception.
-            - 'error_message': The complete traceback string.
-            - 'error_code': Custom error code, if available.
-            - 'stack_trace': A list of frames in the stack trace, each with:
-                - 'filename': File where the error occurred.
-                - 'lineno': Line number.
-                - 'name': Function or method name.
-                - 'line': The source line of code.
-            - 'cause': A nested dictionary representing the original cause (if any).
+            Dictionary with the following keys:
+            - 'error_type': str, the type of the exception.
+            - 'error_message': str, the formatted traceback string.
+            - 'error_code': Any, custom error code if present on the exception.
+            - 'stack_trace': list of dict, each dict contains frame details:
+                - 'filename': str, file where the error occurred.
+                - 'lineno': int, line number in the file.
+                - 'name': str, function or method name.
+                - 'line': str or None, source line of code.
+            - 'cause': dict or None, nested dictionary for the original cause if present.
         """
         tb = traceback.TracebackException.from_exception(self.__exception, capture_locals=False)
 
@@ -60,17 +57,21 @@ class ExceptionParser(IExceptionParser):
 
     def __parse_stack(self, stack: traceback.StackSummary) -> List[Dict[str, Union[str, int, None]]]:
         """
-        Helper method to parse the stack trace.
+        Parses the stack trace summary into a list of frame dictionaries.
 
         Parameters
         ----------
         stack : traceback.StackSummary
-            The summary of the stack.
+            The summary of the stack trace.
 
         Returns
         -------
         list of dict
-            A list of dictionaries with detailed frame information.
+            Each dictionary contains:
+            - 'filename': str, file where the frame is located.
+            - 'lineno': int, line number in the file.
+            - 'name': str, function or method name.
+            - 'line': str or None, source line of code.
         """
         return [
             {
@@ -84,7 +85,7 @@ class ExceptionParser(IExceptionParser):
 
     def __parse_cause(self, cause: Optional[BaseException]) -> Optional[Dict[str, Any]]:
         """
-        Recursively parse the cause of an exception, if available.
+        Recursively parses the cause of an exception, if present.
 
         Parameters
         ----------
@@ -94,7 +95,8 @@ class ExceptionParser(IExceptionParser):
         Returns
         -------
         dict or None
-            A dictionary with the cause information or None if no cause exists.
+            Dictionary with the cause's error type, message, and stack trace,
+            or None if no cause exists.
         """
         if not isinstance(cause, BaseException):
             return None

orionis/support/formatter/serializer.py

@@ -5,11 +5,18 @@ class Parser:
     @staticmethod
     def exception(exception: Exception) -> ExceptionParser:
         """
-        Creates and returns an ExceptionParser instance for the given exception.
-        Args:
-            exception (Exception): The exception to be parsed.
-        Returns:
-            ExceptionParser: An instance of ExceptionParser initialized with the provided exception.
+        Create and return an ExceptionParser instance for the given exception.
+
+        Parameters
+        ----------
+        exception : Exception
+            The exception object to be parsed.
+
+        Returns
+        -------
+        ExceptionParser
+            An ExceptionParser instance initialized with the provided exception.
         """
 
+        # Instantiate and return an ExceptionParser for the given exception
         return ExceptionParser(exception)

orionis/support/patterns/singleton/meta.py

@@ -6,25 +6,21 @@ T = TypeVar('T')
 
 class Singleton(type):
     """
-    Thread-safe and async-safe singleton metaclass.
+    Metaclass for implementing thread-safe and async-safe singleton pattern.
 
-    Ensures that only one instance of a class exists, regardless of whether the code is running in a synchronous or asynchronous context. This metaclass provides both a synchronous (`__call__`) and asynchronous (`__acall__`) method for instance creation, using appropriate locking mechanisms to prevent race conditions in multi-threaded or async environments.
+    This metaclass ensures that only one instance of a class exists, regardless of
+    whether the code is running in a synchronous or asynchronous context. It provides
+    both synchronous and asynchronous mechanisms for instance creation, using appropriate
+    locking to prevent race conditions in multi-threaded or async environments.
 
     Attributes
     ----------
     _instances : Dict[Type[T], T]
-        Stores singleton instances for each class using this metaclass.
+        Dictionary storing singleton instances for each class using this metaclass.
     _lock : threading.Lock
         Thread lock for synchronizing instance creation in synchronous contexts.
     _async_lock : asyncio.Lock
         Async lock for synchronizing instance creation in asynchronous contexts.
-
-    Methods
-    -------
-    __call__(cls, *args, **kwargs)
-        Synchronously creates or retrieves the singleton instance.
-    __acall__(cls, *args, **kwargs)
-        Asynchronously creates or retrieves the singleton instance.
     """
 
     _instances: Dict[Type[T], T] = {}
@@ -33,12 +29,12 @@ class Singleton(type):
 
     def __call__(cls: Type[T], *args: Any, **kwargs: Any) -> T:
         """
-        Synchronously creates or retrieves a singleton instance of the class.
+        Synchronously create or retrieve the singleton instance.
 
-        This method ensures that only one instance of the class is created, even in multi-threaded environments.
-        If the instance does not exist, it acquires a thread lock to prevent race conditions, creates the instance,
-        and stores it in the class-level `_instances` dictionary. If the instance already exists, it simply returns
-        the existing instance.
+        Ensures that only one instance of the class is created in a thread-safe manner.
+        If the instance does not exist, acquires a thread lock to prevent race conditions,
+        creates the instance, and stores it in the class-level `_instances` dictionary.
+        If the instance already exists, returns the existing instance.
 
         Parameters
         ----------
@@ -70,12 +66,12 @@ class Singleton(type):
 
     async def __acall__(cls: Type[T], *args: Any, **kwargs: Any) -> T:
         """
-        Asynchronously creates or retrieves a singleton instance of the class.
+        Asynchronously create or retrieve the singleton instance.
 
-        This method ensures that only one instance of the class is created, even in asynchronous contexts.
-        If the instance does not exist, it acquires an asynchronous lock to prevent race conditions,
-        creates the instance, and stores it in the class-level `_instances` dictionary. If the instance
-        already exists, it simply returns the existing instance.
+        Ensures that only one instance of the class is created in an async-safe manner.
+        If the instance does not exist, acquires an asynchronous lock to prevent race
+        conditions, creates the instance, and stores it in the class-level `_instances`
+        dictionary. If the instance already exists, returns the existing instance.
 
         Parameters
         ----------
@@ -103,4 +99,4 @@ class Singleton(type):
                     cls._instances[cls] = super().__call__(*args, **kwargs)
 
         # Return the singleton instance
-        return cls._instances[cls]
+        return cls._instances[cls]

orionis/support/standard/contracts/std.py

@@ -3,86 +3,87 @@ from typing import Any, Dict
 
 class IStdClass(ABC):
     """
-    Interface for a dynamic class that allows setting arbitrary attributes,
+    Abstract base class for a dynamic object that allows arbitrary attribute assignment,
     similar to PHP's stdClass.
 
-    Implementations should provide dynamic attribute access and management.
+    Implementations must support dynamic attribute management and provide methods for
+    representation, comparison, serialization, and attribute manipulation.
     """
 
     @abstractmethod
     def __init__(self, **kwargs: Any) -> None:
         """
-        Initializes the object with optional attributes.
+        Initialize the object with optional attributes.
 
         Parameters
         ----------
-        kwargs : Any
-            Key-value pairs to set as initial attributes.
+        **kwargs : Any
+            Arbitrary keyword arguments to set as initial attributes.
         """
         pass
 
     @abstractmethod
     def __repr__(self) -> str:
         """
-        Returns an unambiguous string representation of the object.
+        Return an unambiguous string representation of the object.
 
         Returns
         -------
         str
-            A string that could be used to recreate the object.
+            String representation suitable for debugging and object recreation.
         """
         pass
 
     @abstractmethod
     def __str__(self) -> str:
         """
-        Returns a readable string representation of the object.
+        Return a readable string representation of the object.
 
         Returns
         -------
         str
-            A user-friendly string showing the object's attributes.
+            Human-readable string displaying the object's attributes.
         """
         pass
 
     @abstractmethod
     def __eq__(self, other: Any) -> bool:
         """
-        Compares two objects for equality based on their attributes.
+        Compare this object with another for equality based on attributes.
 
         Parameters
         ----------
         other : Any
-            The object to compare with.
+            Object to compare against.
 
         Returns
         -------
         bool
-            True if both objects have the same attributes and values.
+            True if both objects have identical attributes and values, False otherwise.
         """
         pass
 
     @abstractmethod
     def toDict(self) -> Dict[str, Any]:
         """
-        Converts the object's attributes to a dictionary.
+        Convert the object's attributes to a dictionary.
 
         Returns
         -------
-        Dict[str, Any]
-            A dictionary representation of the object's attributes.
+        dict of str to Any
+            Dictionary containing the object's attribute names and values.
         """
         pass
 
     @abstractmethod
     def update(self, **kwargs: Any) -> None:
         """
-        Updates the object's attributes dynamically.
+        Update the object's attributes with the provided key-value pairs.
 
         Parameters
         ----------
-        kwargs : Any
-            Key-value pairs to update attributes.
+        **kwargs : Any
+            Arbitrary keyword arguments to update or add as attributes.
 
         Raises
         ------
@@ -94,7 +95,7 @@ class IStdClass(ABC):
     @abstractmethod
     def remove(self, *attributes: str) -> None:
         """
-        Removes one or more attributes from the object.
+        Remove one or more attributes from the object.
 
         Parameters
         ----------
@@ -104,7 +105,7 @@ class IStdClass(ABC):
         Raises
         ------
         AttributeError
-            If any of the attributes doesn't exist.
+            If any specified attribute does not exist.
         """
         pass
 
@@ -112,16 +113,16 @@ class IStdClass(ABC):
     @abstractmethod
     def fromDict(cls, dictionary: Dict[str, Any]) -> 'IStdClass':
         """
-        Creates an instance from a dictionary.
+        Create an instance from a dictionary of attributes.
 
         Parameters
         ----------
-        dictionary : Dict[str, Any]
-            Dictionary to create the object from.
+        dictionary : dict of str to Any
+            Dictionary containing attribute names and values.
 
         Returns
         -------
         IStdClass
-            A new instance with the dictionary's key-value pairs as attributes.
+            New instance with attributes set from the dictionary.
         """
         pass