orionis 0.432.0__tar.gz → 0.434.0__tar.gz

{orionis-0.432.0/orionis.egg-info → orionis-0.434.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orionis
-Version: 0.432.0
+Version: 0.434.0
 Summary: Orionis Framework – Elegant, Fast, and Powerful.
 Home-page: https://github.com/orionis-framework/framework
 Author: Raul Mauricio Uñate Castro

orionis-0.434.0/orionis/app.py

@@ -0,0 +1,17 @@
+from orionis.foundation.application import Application, IApplication
+
+def Orionis() -> IApplication:
+    """
+    Initialize and return the main Orionis application instance.
+
+    Initializes the core application object that implements the `IApplication` interface.
+    This function acts as the entry point for creating and accessing the main application instance.
+
+    Returns
+    -------
+    IApplication
+        The initialized application instance implementing the `IApplication` interface.
+    """
+
+    # Instantiate and return the main application object
+    return Application()

{orionis-0.432.0 → orionis-0.434.0}/orionis/metadata/framework.py

@@ -5,7 +5,7 @@
 NAME = "orionis"
 
 # Current version of the framework
-VERSION = "0.432.0"
+VERSION = "0.434.0"
 
 # Full name of the author or maintainer of the project
 AUTHOR = "Raul Mauricio Uñate Castro"

{orionis-0.432.0 → orionis-0.434.0}/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-0.434.0/orionis/support/facades/console.py

@@ -0,0 +1,15 @@
+from orionis.container.facades.facade import Facade
+
+class Console(Facade):
+
+    @classmethod
+    def getFacadeAccessor(cls) -> str:
+        """
+        Get the service container binding key for the console component.
+
+        Returns
+        -------
+        str
+            The binding key used to resolve the console service from the container.
+        """
+        return "core.orionis.console"

orionis-0.434.0/orionis/support/facades/dumper.py

@@ -0,0 +1,15 @@
+from orionis.container.facades.facade import Facade
+
+class Dumper(Facade):
+
+    @classmethod
+    def getFacadeAccessor(cls) -> str:
+        """
+        Returns the service container binding key for the dumper component.
+
+        Returns
+        -------
+        str
+            The binding key "core.orionis.dumper" used to resolve the dumper service from the container.
+        """
+        return "core.orionis.dumper"

orionis-0.434.0/orionis/support/facades/logger.py

@@ -0,0 +1,16 @@
+from orionis.container.facades.facade import Facade
+
+class Log(Facade):
+
+    @classmethod
+    def getFacadeAccessor(cls) -> str:
+        """
+        Returns the binding key for the logger service in the service container.
+
+        Returns
+        -------
+        str
+            The unique identifier used to resolve the logger service, specifically
+            "core.orionis.logger".
+        """
+        return "core.orionis.logger"

orionis-0.434.0/orionis/support/facades/path_resolver.py

@@ -0,0 +1,15 @@
+from orionis.container.facades.facade import Facade
+
+class PathResolver(Facade):
+
+    @classmethod
+    def getFacadeAccessor(cls):
+        """
+        Returns the binding key for the path resolver service in the container.
+
+        Returns
+        -------
+        str
+            The unique string identifier for the path resolver service, used by the service container.
+        """
+        return "core.orionis.path_resolver"

orionis-0.434.0/orionis/support/facades/progress_bar.py

@@ -0,0 +1,15 @@
+from orionis.container.facades.facade import Facade
+
+class ProgressBar(Facade):
+
+    @classmethod
+    def getFacadeAccessor(cls):
+        """
+        Returns the binding key for the progress bar service.
+
+        Returns
+        -------
+        str
+            The unique identifier used to retrieve the progress bar service from the service container.
+        """
+        return "core.orionis.progress_bar"

orionis-0.434.0/orionis/support/facades/testing.py

@@ -0,0 +1,16 @@
+from orionis.container.facades.facade import Facade
+
+class Test(Facade):
+
+    @classmethod
+    def getFacadeAccessor(cls) -> str:
+        """
+        Returns the binding key for the testing component in the service container.
+
+        Returns
+        -------
+        str
+            The unique string identifier for the testing component, used by the service
+            container to resolve the appropriate implementation.
+        """
+        return "core.orionis.testing"

orionis-0.434.0/orionis/support/facades/workers.py

@@ -0,0 +1,17 @@
+from orionis.container.facades.facade import Facade
+
+class Workers(Facade):
+
+    @classmethod
+    def getFacadeAccessor(cls):
+        """
+        Returns the binding key for the workers service in the service container.
+
+        Returns
+        -------
+        str
+            The identifier string for the workers service, used by the service container
+            to resolve the corresponding implementation.
+        """
+
+        return "core.orionis.workers"

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

@@ -0,0 +1,41 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+class IExceptionParser(ABC):
+    """
+    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:
+        """
+        Returns the original exception instance.
+
+        Returns
+        -------
+        Exception
+            The exception object to be parsed.
+        """
+        pass
+
+    @abstractmethod
+    def toDict(self) -> Dict[str, Any]:
+        """
+        Converts the exception into a structured dictionary.
+
+        Returns
+        -------
+        dict
+            A dictionary containing details about the exception, such as:
+            - error_type
+            - error_message
+            - error_code
+            - stack_trace
+            - cause (if present)
+        """
+        pass

{orionis-0.432.0 → orionis-0.434.0}/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-0.434.0/orionis/support/formatter/serializer.py

@@ -0,0 +1,22 @@
+from orionis.support.formatter.exceptions.parser import ExceptionParser
+
+class Parser:
+
+    @staticmethod
+    def exception(exception: Exception) -> ExceptionParser:
+        """
+        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-0.432.0 → orionis-0.434.0}/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-0.434.0/orionis/support/standard/contracts/std.py

@@ -0,0 +1,128 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+class IStdClass(ABC):
+    """
+    Abstract base class for a dynamic object that allows arbitrary attribute assignment,
+    similar to PHP's stdClass.
+
+    Implementations must support dynamic attribute management and provide methods for
+    representation, comparison, serialization, and attribute manipulation.
+    """
+
+    @abstractmethod
+    def __init__(self, **kwargs: Any) -> None:
+        """
+        Initialize the object with optional attributes.
+
+        Parameters
+        ----------
+        **kwargs : Any
+            Arbitrary keyword arguments to set as initial attributes.
+        """
+        pass
+
+    @abstractmethod
+    def __repr__(self) -> str:
+        """
+        Return an unambiguous string representation of the object.
+
+        Returns
+        -------
+        str
+            String representation suitable for debugging and object recreation.
+        """
+        pass
+
+    @abstractmethod
+    def __str__(self) -> str:
+        """
+        Return a readable string representation of the object.
+
+        Returns
+        -------
+        str
+            Human-readable string displaying the object's attributes.
+        """
+        pass
+
+    @abstractmethod
+    def __eq__(self, other: Any) -> bool:
+        """
+        Compare this object with another for equality based on attributes.
+
+        Parameters
+        ----------
+        other : Any
+            Object to compare against.
+
+        Returns
+        -------
+        bool
+            True if both objects have identical attributes and values, False otherwise.
+        """
+        pass
+
+    @abstractmethod
+    def toDict(self) -> Dict[str, Any]:
+        """
+        Convert the object's attributes to a dictionary.
+
+        Returns
+        -------
+        dict of str to Any
+            Dictionary containing the object's attribute names and values.
+        """
+        pass
+
+    @abstractmethod
+    def update(self, **kwargs: Any) -> None:
+        """
+        Update the object's attributes with the provided key-value pairs.
+
+        Parameters
+        ----------
+        **kwargs : Any
+            Arbitrary keyword arguments to update or add as attributes.
+
+        Raises
+        ------
+        ValueError
+            If an attribute name is invalid or conflicts with existing methods.
+        """
+        pass
+
+    @abstractmethod
+    def remove(self, *attributes: str) -> None:
+        """
+        Remove one or more attributes from the object.
+
+        Parameters
+        ----------
+        *attributes : str
+            Names of the attributes to remove.
+
+        Raises
+        ------
+        AttributeError
+            If any specified attribute does not exist.
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def fromDict(cls, dictionary: Dict[str, Any]) -> 'IStdClass':
+        """
+        Create an instance from a dictionary of attributes.
+
+        Parameters
+        ----------
+        dictionary : dict of str to Any
+            Dictionary containing attribute names and values.
+
+        Returns
+        -------
+        IStdClass
+            New instance with attributes set from the dictionary.
+        """
+        pass

{orionis-0.432.0 → orionis-0.434.0}/orionis/support/standard/exceptions/value.py

@@ -5,7 +5,7 @@ class OrionisStdValueException(Exception):
         Parameters
         ----------
         msg : str
-            Descriptive error message explaining the cause of the exception.
+            The error message that describes the reason for the exception.
         """
         super().__init__(msg)
 
@@ -14,6 +14,6 @@ class OrionisStdValueException(Exception):
         Returns
         -------
         str
-            Formatted string describing the exception.
+            The error message associated with this exception.
         """
         return str(self.args[0])