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

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

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])

orionis/support/standard/std.py

@@ -3,56 +3,59 @@ from orionis.support.standard.exceptions import OrionisStdValueException
 
 class StdClass(IStdClass):
     """
-    A dynamic class that allows setting arbitrary attributes,
-    similar to PHP's stdClass.
+    A dynamic class for storing arbitrary attributes, similar to PHP's stdClass.
+
+    Attributes
+    ----------
+    Any attribute can be dynamically set via keyword arguments or the `update` method.
     """
 
     def __init__(self, **kwargs):
         """
-        Initializes the StdClass with optional keyword arguments.
+        Initialize a StdClass instance with optional attributes.
 
         Parameters
         ----------
-        kwargs : dict
-            Key-value pairs to set as attributes.
+        **kwargs : dict, optional
+            Arbitrary keyword arguments to set as attributes.
         """
         self.update(**kwargs)
 
     def __repr__(self):
         """
-        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.
         """
         return f"{self.__class__.__name__}({self.__dict__})"
 
     def __str__(self):
         """
-        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.
+            String showing the object's attributes.
         """
         return str(self.__dict__)
 
     def __eq__(self, other):
         """
-        Compares two StdClass objects for equality based on their attributes.
+        Compare two StdClass objects for equality based on their attributes.
 
         Parameters
         ----------
         other : object
-            The object to compare with.
+            Object to compare with.
 
         Returns
         -------
         bool
-            True if both objects have the same attributes and values.
+            True if both objects have the same attributes and values, False otherwise.
         """
         if not isinstance(other, StdClass):
             return False
@@ -60,30 +63,29 @@ class StdClass(IStdClass):
 
     def toDict(self):
         """
-        Converts the object's attributes to a dictionary.
+        Convert the object's attributes to a dictionary.
 
         Returns
         -------
         dict
-            A dictionary representation of the object's attributes.
+            A shallow copy of the object's attributes.
         """
-
         # Return a copy to avoid external modifications
         return self.__dict__.copy()
 
     def update(self, **kwargs):
         """
-        Updates the object's attributes dynamically.
+        Update the object's attributes dynamically.
 
         Parameters
         ----------
-        kwargs : dict
-            Key-value pairs to update attributes.
+        **kwargs : dict
+            Key-value pairs to update or add as attributes.
 
         Raises
         ------
         OrionisStdValueException
-            If an attribute name is invalid or conflicts with existing methods.
+            If an attribute name is reserved or conflicts with a class method.
         """
         for key, value in kwargs.items():
             if key.startswith('__') and key.endswith('__'):
@@ -94,7 +96,7 @@ class StdClass(IStdClass):
 
     def remove(self, *attributes):
         """
-        Removes one or more attributes from the object.
+        Remove one or more attributes from the object.
 
         Parameters
         ----------
@@ -104,7 +106,7 @@ class StdClass(IStdClass):
         Raises
         ------
         AttributeError
-            If any of the attributes doesn't exist.
+            If any of the specified attributes do not exist.
         """
         for attr in attributes:
             if not hasattr(self, attr):
@@ -114,16 +116,16 @@ class StdClass(IStdClass):
     @classmethod
     def fromDict(cls, dictionary):
         """
-        Creates a StdClass instance from a dictionary.
+        Create a StdClass instance from a dictionary.
 
         Parameters
         ----------
         dictionary : dict
-            Dictionary to create the object from.
+            Dictionary containing attribute names and values.
 
         Returns
         -------
         StdClass
-            A new StdClass instance with the dictionary's key-value pairs as attributes.
+            A new StdClass instance with attributes set from the dictionary.
         """
         return cls(**dictionary)

orionis/support/wrapper/dot_dict.py

@@ -8,9 +8,6 @@ class DotDict(dict):
         """
         Retrieve the value associated with the given key as an attribute.
 
-        If the value is a dictionary (but not already a DotDict), it is converted
-        to a DotDict and updated in-place. If the key does not exist, returns None.
-
         Parameters
         ----------
         key : str
@@ -24,8 +21,8 @@ class DotDict(dict):
 
         Notes
         -----
-        This method allows attribute-style access to dictionary keys. If the value
-        is a plain dictionary, it is automatically wrapped as a DotDict for consistency.
+        Allows attribute-style access to dictionary keys. If the value is a plain
+        dictionary, it is automatically wrapped as a DotDict for consistency.
         """
         try:
             value = self[key]  # Attempt to retrieve the value by key
@@ -42,10 +39,6 @@ class DotDict(dict):
         """
         Assign a value to an attribute of the DotDict instance.
 
-        This method enables attribute-style assignment for dictionary keys. If the
-        assigned value is a plain dictionary (not a DotDict), it is automatically
-        converted to a DotDict for consistency and recursive attribute access.
-
         Parameters
         ----------
         key : str
@@ -57,14 +50,13 @@ class DotDict(dict):
         Returns
         -------
         None
-            This method does not return a value.
 
         Notes
         -----
-        The attribute is stored as a key-value pair in the underlying dictionary.
-        This allows seamless attribute-style access and assignment for dictionary keys.
+        Enables attribute-style assignment for dictionary keys. If the assigned value
+        is a plain dictionary (not a DotDict), it is automatically converted to a
+        DotDict for consistency and recursive attribute access.
         """
-
         # Convert plain dicts to DotDict for recursive attribute access
         if isinstance(value, dict) and not isinstance(value, DotDict):
             value = DotDict(value)
@@ -76,9 +68,6 @@ class DotDict(dict):
         """
         Remove an attribute from the DotDict instance.
 
-        This method deletes the key-value pair corresponding to the given attribute name
-        from the underlying dictionary. If the key does not exist, an AttributeError is raised.
-
         Parameters
         ----------
         key : str
@@ -87,7 +76,6 @@ class DotDict(dict):
         Returns
         -------
         None
-            This method does not return a value.
 
         Raises
         ------
@@ -96,7 +84,7 @@ class DotDict(dict):
 
         Notes
         -----
-        This method enables attribute-style deletion for dictionary keys, allowing
+        Enables attribute-style deletion for dictionary keys, allowing
         seamless removal of items using dot notation.
         """
         try:
@@ -110,10 +98,6 @@ class DotDict(dict):
         """
         Retrieve the value associated with the given key, returning a default value if the key is not found.
 
-        If the retrieved value is a plain dictionary (not a DotDict), it is converted to a DotDict,
-        stored back in the dictionary, and then returned. This ensures consistent attribute-style access
-        for nested dictionaries.
-
         Parameters
         ----------
         key : str
@@ -129,7 +113,7 @@ class DotDict(dict):
 
         Notes
         -----
-        This method overrides the standard dict.get() to provide automatic conversion of nested
+        Overrides the standard dict.get() to provide automatic conversion of nested
         dictionaries to DotDict instances, enabling recursive attribute-style access.
         """
         # Retrieve the value using the base dict's get method
@@ -144,27 +128,17 @@ class DotDict(dict):
         """
         Recursively export the contents of the DotDict as a standard Python dictionary.
 
-        This method traverses the DotDict and converts all nested DotDict instances
-        into regular dictionaries by recursively calling their `export` method.
-        Non-DotDict values are included as-is. This ensures that the returned object
-        is composed entirely of built-in Python types, making it suitable for serialization
-        or interoperability with code expecting standard dictionaries.
-
-        Parameters
-        ----------
-        None
-
         Returns
         -------
-        result : dict
+        dict
             A dictionary representation of the DotDict, where all nested DotDict instances
             are recursively converted to dictionaries. Non-DotDict values are returned unchanged.
 
         Notes
         -----
-        This method is useful for converting a DotDict (which supports attribute-style access)
-        into a plain dictionary for use with APIs, serialization, or other libraries that
-        require standard dict objects.
+        Converts all nested DotDict instances into regular dictionaries by recursively
+        calling their `export` method. Useful for serialization or interoperability
+        with code expecting standard dictionaries.
         """
         result = {}
         # Iterate through all key-value pairs in the DotDict
@@ -181,10 +155,6 @@ class DotDict(dict):
         """
         Create a deep copy of the DotDict instance, recursively copying all nested DotDict and dict objects.
 
-        This method traverses the DotDict and ensures that all nested DotDict and dict instances are
-        copied recursively, so that the returned DotDict is fully independent of the original. Non-dict
-        values are copied by reference.
-
         Returns
         -------
         DotDict
@@ -193,8 +163,8 @@ class DotDict(dict):
 
         Notes
         -----
-        This method is useful when you need a completely independent copy of a DotDict, including all
-        nested structures, to avoid unintended side effects from shared references.
+        Ensures that all nested DotDict and dict instances are copied recursively,
+        so that the returned DotDict is fully independent of the original.
         """
         copied = {}
         # Iterate through all key-value pairs in the DotDict
@@ -215,11 +185,6 @@ class DotDict(dict):
         """
         Return a string representation of the DotDict instance.
 
-        This method overrides the default `__repr__` implementation to provide a concise
-        and informative string that displays the class name (`DotDict`) and the contents
-        of the underlying dictionary. This is useful for debugging and logging, as it
-        clearly distinguishes DotDict objects from regular dictionaries.
-
         Returns
         -------
         str
@@ -228,8 +193,8 @@ class DotDict(dict):
 
         Notes
         -----
-        The returned string uses the base dictionary's representation, but is prefixed
-        with the DotDict class name for clarity.
+        Uses the base dict's __repr__ for the contents, but keeps the DotDict class name
+        for clarity and distinction from regular dictionaries.
         """
         # Use the base dict's __repr__ for the contents, but keep DotDict class name
-        return super().__repr__()
+        return super().__repr__()

orionis/test/cases/asynchronous.py

@@ -3,132 +3,68 @@ from orionis.test.output.dumper import TestDumper
 
 class AsyncTestCase(unittest.IsolatedAsyncioTestCase, TestDumper):
     """
-    Base test case class for asynchronous unit testing.
+    Base class for asynchronous unit tests in the Orionis framework.
 
-    This class provides a foundation for writing asynchronous unit tests within
-    the Orionis framework. It extends unittest.IsolatedAsyncioTestCase and includes
-    TestDumper functionality for enhanced test output and debugging capabilities.
-
-    The class provides hooks for custom async setup and teardown logic through the
-    onAsyncSetup() and onAsyncTeardown() methods, which can be overridden by subclasses
-    to implement test-specific asynchronous initialization and cleanup procedures.
-
-    Each test method runs in its own isolated asyncio event loop, ensuring proper
-    isolation and preventing side effects between tests.
+    Inherits from `unittest.IsolatedAsyncioTestCase` and `TestDumper`, providing
+    a structure for writing asynchronous tests with isolated event loops and
+    enhanced output capabilities. Subclasses can override `onAsyncSetup` and
+    `onAsyncTeardown` for custom asynchronous setup and teardown logic.
 
     Attributes
     ----------
     None
-
-    Methods
-    -------
-    asyncSetUp()
-        Initialize test environment before each async test method execution.
-    asyncTearDown()
-        Clean up test environment after each async test method execution.
-    onAsyncSetup()
-        Hook method for subclass-specific async setup logic.
-    onAsyncTeardown()
-        Hook method for subclass-specific async teardown logic.
     """
 
     async def asyncSetUp(self):
         """
-        Initialize the test environment before each async test method.
-
-        This method is automatically called by the unittest framework before
-        each async test method execution. It performs the standard unittest
-        async setup and then calls the onAsyncSetup() hook for custom
-        asynchronous initialization.
+        Asynchronous setup executed before each test method.
 
-        Parameters
-        ----------
-        None
+        Calls the parent class's asyncSetUp and then invokes the
+        `onAsyncSetup` hook for additional subclass-specific setup.
 
         Returns
         -------
         None
-
-        Notes
-        -----
-        This method should not be overridden directly. Use onAsyncSetup() instead
-        for custom async setup logic. The method runs in the isolated event loop
-        created for each test.
         """
         await super().asyncSetUp()
         await self.onAsyncSetup()
 
     async def asyncTearDown(self):
         """
-        Clean up the test environment after each async test method.
+        Asynchronous teardown executed after each test method.
 
-        This method is automatically called by the unittest framework after
-        each async test method execution. It calls the onAsyncTeardown() hook
-        for custom cleanup and then performs the standard unittest async teardown.
-
-        Parameters
-        ----------
-        None
+        Invokes the `onAsyncTeardown` hook for subclass-specific cleanup,
+        then calls the parent class's asyncTearDown.
 
         Returns
         -------
         None
-
-        Notes
-        -----
-        This method should not be overridden directly. Use onAsyncTeardown() instead
-        for custom async teardown logic. The method runs in the same isolated event
-        loop as the test.
         """
         await self.onAsyncTeardown()
         await super().asyncTearDown()
 
     async def onAsyncSetup(self):
         """
-        Hook method for subclass-specific async setup logic.
-
-        This method is called during the asyncSetUp() phase and is intended to be
-        overridden by subclasses that need to perform custom asynchronous
-        initialization before each test method execution.
+        Hook for subclass-specific asynchronous setup logic.
 
-        Parameters
-        ----------
-        None
+        Intended to be overridden by subclasses to perform custom
+        asynchronous initialization before each test.
 
         Returns
         -------
         None
-
-        Examples
-        --------
-        >>> async def onAsyncSetup(self):
-        ...     self.db_connection = await create_async_connection()
-        ...     self.mock_service = AsyncMockService()
-        ...     await self.mock_service.initialize()
         """
         pass
 
     async def onAsyncTeardown(self):
         """
-        Hook method for subclass-specific async teardown logic.
+        Hook for subclass-specific asynchronous teardown logic.
 
-        This method is called during the asyncTearDown() phase and is intended to be
-        overridden by subclasses that need to perform custom asynchronous cleanup
-        after each test method execution.
-
-        Parameters
-        ----------
-        None
+        Intended to be overridden by subclasses to perform custom
+        asynchronous cleanup after each test.
 
         Returns
         -------
         None
-
-        Examples
-        --------
-        >>> async def onAsyncTeardown(self):
-        ...     await self.db_connection.close()
-        ...     await self.mock_service.cleanup()
-        ...     del self.test_data
         """
         pass