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

orionis/metadata/framework.py

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

orionis/services/asynchrony/contracts/coroutines.py

@@ -9,24 +9,19 @@ class ICoroutine(ABC):
     @abstractmethod
     def run(self) -> Union[T, asyncio.Future]:
         """
-        Executes the wrapped coroutine, either synchronously or asynchronously depending on the context.
-
-        Parameters
-        ----------
-        None
+        Execute the wrapped coroutine either synchronously or asynchronously, depending on the execution context.
 
         Returns
         -------
         T or asyncio.Future
-            If called outside an event loop, returns the result of the coroutine execution (type T).
+            If called outside of an event loop, returns the result of the coroutine execution (type T).
             If called within an event loop, returns an asyncio.Future representing the scheduled coroutine.
 
         Notes
         -----
-        - When invoked outside of an event loop, the coroutine is executed synchronously and its result is returned.
-        - When invoked inside an event loop, the coroutine is scheduled for asynchronous execution and a Future is returned.
+        - Executes the coroutine synchronously and returns its result when called outside an event loop.
+        - Schedules the coroutine for asynchronous execution and returns a Future when called inside an event loop.
         - The caller is responsible for awaiting the Future if asynchronous execution is used.
         """
-
         # This method should be implemented by subclasses to handle coroutine execution.
-        pass
+        pass

orionis/services/asynchrony/coroutines.py

@@ -10,27 +10,17 @@ class Coroutine(ICoroutine):
 
     def __init__(self, func: TypingCoroutine[Any, Any, T]) -> None:
         """
-        Initialize the Coroutine wrapper.
+        Wraps a coroutine object and validates its type.
 
         Parameters
         ----------
         func : Coroutine
-            The coroutine object to be wrapped. Must be an awaitable coroutine.
+            The coroutine object to be wrapped and managed.
 
         Raises
         ------
         OrionisCoroutineException
             If the provided object is not a coroutine.
-
-        Returns
-        -------
-        None
-            This method does not return a value.
-
-        Notes
-        -----
-        This constructor validates that the provided object is a coroutine using the framework's type introspection.
-        If the validation fails, an exception is raised to prevent improper usage.
         """
         # Validate that the provided object is a coroutine
         if not Type(func).isCoroutine():
@@ -43,17 +33,12 @@ class Coroutine(ICoroutine):
 
     def run(self) -> Union[T, asyncio.Future]:
         """
-        Executes the wrapped coroutine, either synchronously or asynchronously depending on the context.
-
-        Parameters
-        ----------
-        None
+        Executes the wrapped coroutine, adapting to the current event loop context.
 
         Returns
         -------
         T or asyncio.Future
-            If called outside an event loop, returns the result of the coroutine after synchronous execution.
-            If called within an event loop, returns an asyncio.Future representing the scheduled coroutine.
+            The result of the coroutine if executed synchronously, or an asyncio.Future if scheduled asynchronously.
 
         Raises
         ------
@@ -62,9 +47,9 @@ class Coroutine(ICoroutine):
 
         Notes
         -----
-        - When invoked outside an active event loop, the coroutine is executed synchronously and its result is returned.
-        - When invoked inside an active event loop, the coroutine is scheduled for asynchronous execution and a Future is returned.
-        - This method automatically detects the execution context and chooses the appropriate execution strategy.
+        - If called outside an active event loop, the coroutine is executed synchronously and its result is returned.
+        - If called within an active event loop, the coroutine is scheduled for asynchronous execution and a Future is returned.
+        - The method automatically detects the execution context and chooses the appropriate execution strategy.
         """
         # Attempt to get the currently running event loop
         try:
@@ -80,4 +65,4 @@ class Coroutine(ICoroutine):
 
         # If no event loop is running, execute the coroutine synchronously using the loop
         else:
-            return loop.run_until_complete(self.__func)
+            return loop.run_until_complete(self.__func)

orionis/services/asynchrony/exceptions/exception.py

@@ -2,26 +2,24 @@ class OrionisCoroutineException(Exception):
 
     def __init__(self, msg: str):
         """
-        Initializes an OrionisCoroutineException with a descriptive error message.
+        Initialize the OrionisCoroutineException.
 
         Parameters
         ----------
         msg : str
-            Descriptive error message explaining the cause of the exception.
+            A descriptive error message explaining the cause of the exception.
         """
-
         # Call the base Exception constructor with the provided message
         super().__init__(msg)
 
     def __str__(self) -> str:
         """
-        Returns a formatted string representation of the exception message.
+        Return the string representation of the exception.
 
         Returns
         -------
         str
             The error message provided during exception initialization.
         """
-
         # Return the first argument passed to the Exception, which is the error message
         return str(self.args[0])

orionis/services/environment/contracts/caster.py

@@ -10,24 +10,23 @@ class IEnvironmentCaster(ABC):
         Parameters
         ----------
         type_hint : str
-            The type hint to set, which must be one of the valid options defined in OPTIONS.
+            The type hint to assign. Must be one of the valid options defined in OPTIONS.
 
         Raises
         ------
         OrionisEnvironmentValueError
-            If the provided type hint is not one of the valid options.
+            If the provided type hint is not among the valid options.
         """
         pass
 
     @abstractmethod
     def get(self):
         """
-        Returns the value corresponding to the specified type hint.
+        Retrieve the value corresponding to the specified type hint.
 
-        Checks if the provided type hint is valid and then dispatches the call to the appropriate
-        method for handling the type.
-
-        Supported type hints include: 'path:', 'str:', 'int:', 'float:', 'bool:', 'list:', 'dict:', 'tuple:', and 'set:'.
+        Checks the validity of the provided type hint and dispatches the call to the appropriate
+        handler for the type. Supported type hints include: 'path:', 'str:', 'int:', 'float:',
+        'bool:', 'list:', 'dict:', 'tuple:', and 'set:'.
 
         Returns
         -------
@@ -37,6 +36,6 @@ class IEnvironmentCaster(ABC):
         Raises
         ------
         OrionisEnvironmentValueError
-            If the type hint is not one of the supported options.
+            If the type hint is not supported.
         """
-        pass
+        pass

orionis/services/environment/contracts/env.py

@@ -7,19 +7,19 @@ class IEnv(ABC):
     @abstractmethod
     def get(key: str, default: Any = None) -> Any:
         """
-        Retrieve the value of an environment variable by key.
+        Retrieves the value of the specified environment variable.
 
         Parameters
         ----------
         key : str
             The name of the environment variable to retrieve.
         default : Any, optional
-            The value to return if the key is not found. Default is None.
+            The value to return if the environment variable is not found. Defaults to None.
 
         Returns
         -------
         Any
-            The value of the environment variable if found, otherwise the default value.
+            The value of the environment variable if it exists, otherwise the default value.
         """
         pass
 
@@ -27,7 +27,7 @@ class IEnv(ABC):
     @abstractmethod
     def set(key: str, value: str, type: str = None) -> bool:
         """
-        Set an environment variable in the .env file.
+        Sets the value of an environment variable in the .env file.
 
         Parameters
         ----------
@@ -36,12 +36,12 @@ class IEnv(ABC):
         value : str
             The value to assign to the environment variable.
         type : str, optional
-            The type of the environment variable (e.g., 'str', 'int'). Default is None.
+            The type of the environment variable (e.g., 'str', 'int'). Defaults to None.
 
         Returns
         -------
         bool
-            True if the variable was set successfully, False otherwise.
+            True if the environment variable was set successfully, False otherwise.
         """
         pass
 
@@ -49,7 +49,7 @@ class IEnv(ABC):
     @abstractmethod
     def unset(key: str) -> bool:
         """
-        Remove the specified environment variable from the .env file.
+        Removes the specified environment variable from the .env file.
 
         Parameters
         ----------
@@ -59,7 +59,7 @@ class IEnv(ABC):
         Returns
         -------
         bool
-            True if the variable was successfully removed, False otherwise.
+            True if the environment variable was removed successfully, False otherwise.
         """
         pass
 
@@ -67,7 +67,7 @@ class IEnv(ABC):
     @abstractmethod
     def all() -> Dict[str, Any]:
         """
-        Retrieve all environment variables as a dictionary.
+        Retrieves all environment variables as a dictionary.
 
         Returns
         -------

orionis/services/environment/core/dot_env.py

@@ -4,9 +4,8 @@ import threading
 from pathlib import Path
 from typing import Any, Optional, Union
 from dotenv import dotenv_values, load_dotenv, set_key, unset_key
-from orionis.services.environment.enums.value_type import EnvironmentValueType
-from orionis.services.environment.validators.key_name import ValidateKeyName
-from orionis.services.environment.validators.types import ValidateTypes
+from orionis.services.environment.enums import EnvironmentValueType
+from orionis.services.environment.validators import ValidateKeyName, ValidateTypes
 from orionis.support.patterns.singleton import Singleton
 from orionis.services.environment.dynamic.caster import EnvironmentCaster
 
@@ -22,20 +21,10 @@ class DotEnv(metaclass=Singleton):
         """
         Initialize the DotEnv service and prepare the `.env` file for environment variable management.
 
-        This constructor determines the location of the `.env` file, ensures its existence,
-        and loads its contents into the current process environment. If a custom path is provided,
-        it is resolved and used; otherwise, a `.env` file in the current working directory is used.
-
         Parameters
         ----------
         path : str, optional
-            The path to the `.env` file. If not specified, defaults to a `.env` file
-            in the current working directory.
-
-        Returns
-        -------
-        None
-            This method does not return any value.
+            Path to the `.env` file. If not provided, defaults to `.env` in the current working directory.
 
         Raises
         ------
@@ -44,16 +33,16 @@ class DotEnv(metaclass=Singleton):
 
         Notes
         -----
-        - Ensures thread safety during initialization.
-        - If the specified `.env` file does not exist, it is created automatically.
-        - Loads environment variables from the `.env` file into the process environment.
+        Ensures thread safety during initialization. If the specified `.env` file does not exist, it is created.
+        Loads environment variables from the `.env` file into the process environment.
         """
+
         try:
 
-            # Ensure thread-safe initialization
+            # Ensure thread-safe initialization to avoid race conditions
             with self._lock:
 
-                # Set default .env file path to current working directory
+                # Set the default .env file path to the current working directory
                 self.__resolved_path = Path(os.getcwd()) / ".env"
 
                 # If a custom path is provided, resolve and use it
@@ -81,41 +70,47 @@ class DotEnv(metaclass=Singleton):
         """
         Set an environment variable in both the `.env` file and the current process environment.
 
-        This method serializes the provided value (optionally using a type hint), validates the key,
-        and updates the corresponding entry in the `.env` file as well as the process's environment
-        variables. Thread safety is ensured during the operation.
-
         Parameters
         ----------
         key : str
             The name of the environment variable to set. Must be a valid environment variable name.
-        value : Union[str, int, float, bool, list, dict, tuple, set]
-            The value to assign to the environment variable. Supported types include string, integer,
-            float, boolean, list, dictionary, tuple, and set.
+        value : str, int, float, bool, list, dict, tuple, or set
+            The value to assign to the environment variable.
         type_hint : str or EnvironmentValueType, optional
-            An explicit type hint to guide serialization. If provided, the value is serialized
-            according to the specified type.
+            An explicit type hint to guide the serialization of the value.
 
         Returns
         -------
         bool
-            Returns True if the environment variable was successfully set in both the `.env` file
-            and the current process environment.
+            True if the environment variable was successfully set.
 
         Raises
         ------
         OrionisEnvironmentValueError
             If the provided key is not a valid environment variable name.
+
+        Notes
+        -----
+        This method ensures thread safety during the set operation. It validates the key name,
+        serializes the value (optionally using a type hint), writes the variable to the `.env` file,
+        and updates the variable in the current process environment.
         """
         with self._lock:
+
             # Validate the environment variable key name.
             __key = ValidateKeyName(key)
 
             # If a type hint is provided, validate and serialize the value accordingly.
             if type_hint is not None:
+
+                # Validate the value against the provided type hint.
                 __type = ValidateTypes(value, type_hint)
+
+                # Serialize the value using the validated type.
                 __value = self.__serializeValue(value, __type)
+
             else:
+
                 # Serialize the value without a type hint.
                 __value = self.__serializeValue(value)
 
@@ -134,7 +129,7 @@ class DotEnv(metaclass=Singleton):
         default: Optional[Any] = None
     ) -> Any:
         """
-        Get the value of an environment variable.
+        Retrieve the value of an environment variable.
 
         Parameters
         ----------
@@ -172,20 +167,15 @@ class DotEnv(metaclass=Singleton):
         """
         Remove an environment variable from both the `.env` file and the current process environment.
 
-        This method deletes the specified environment variable from the resolved `.env` file
-        and removes it from the current process's environment variables. The operation is
-        performed in a thread-safe manner. The key is validated before removal.
-
         Parameters
         ----------
         key : str
-            The name of the environment variable to remove. Must be a valid environment variable name.
+            Name of the environment variable to remove.
 
         Returns
         -------
         bool
-            Returns True if the environment variable was successfully removed from both the `.env` file
-            and the process environment. Returns True even if the variable does not exist.
+            True if the environment variable was successfully removed.
 
         Raises
         ------
@@ -194,9 +184,10 @@ class DotEnv(metaclass=Singleton):
 
         Notes
         -----
-        - The method is thread-safe.
-        - If the environment variable does not exist, the method has no effect and returns True.
+        If the environment variable does not exist, the method has no effect and returns True.
         """
+
+        # Ensure thread-safe operation during the unset process.
         with self._lock:
 
             # Validate the environment variable key name.
@@ -215,24 +206,19 @@ class DotEnv(metaclass=Singleton):
         """
         Retrieve all environment variables from the resolved `.env` file as a dictionary.
 
-        This method reads all key-value pairs from the currently resolved `.env` file and
-        parses each value into its appropriate Python type using the internal `__parseValue`
-        method. The returned dictionary contains environment variable names as keys and their
-        parsed values as values.
-
         Returns
         -------
         dict
-            A dictionary where each key is an environment variable name (str) and each value
-            is the parsed Python representation of the variable as determined by `__parseValue`.
-            If the `.env` file is empty, an empty dictionary is returned.
+            Dictionary where each key is an environment variable name (str) and each value
+            is the parsed Python representation of the variable.
 
         Notes
         -----
-        - Thread safety is ensured during the read operation.
-        - Only variables present in the `.env` file are returned; variables set only in the
-          process environment are not included.
+        Only variables present in the `.env` file are returned; variables set only in the
+        process environment are not included.
         """
+
+        # Ensure thread-safe operation while reading and parsing environment variables.
         with self._lock:
 
             # Read all raw key-value pairs from the .env file
@@ -249,24 +235,18 @@ class DotEnv(metaclass=Singleton):
         """
         Serialize a Python value into a string suitable for storage in a .env file.
 
-        This method converts the provided value into a string representation that can be
-        safely written to a .env file. If a type hint is provided, the value is serialized
-        according to the specified type using the EnvTypes utility. Otherwise, the method
-        infers the serialization strategy based on the value's type.
-
         Parameters
         ----------
         value : Any
-            The value to serialize. Supported types include None, str, int, float, bool,
+            Value to serialize. Supported types include None, str, int, float, bool,
             list, dict, tuple, and set.
         type_hint : str or EnvironmentValueType, optional
-            An explicit type hint to guide serialization. If provided, the value is
-            serialized using EnvTypes.
+            Explicit type hint to guide serialization.
 
         Returns
         -------
         str
-            The serialized string representation of the input value, suitable for storage
+            Serialized string representation of the input value, suitable for storage
             in a .env file. Returns "null" for None values.
         """
 
@@ -308,28 +288,24 @@ class DotEnv(metaclass=Singleton):
         """
         Parse a string or raw value from the .env file into its appropriate Python type.
 
-        This method attempts to convert the input value, which may be a string or already a Python object,
-        into its most suitable Python type. It handles common representations of null, booleans, and
-        attempts to parse collections and literals. If parsing fails, the original string is returned.
-
         Parameters
         ----------
         value : Any
-            The value to parse, typically a string read from the .env file, but may also be a Python object.
+            Value to parse, typically a string read from the .env file, but may also be a Python object.
 
         Returns
         -------
         Any
-            The parsed Python value. Returns `None` for recognized null representations, a boolean for
+            Parsed Python value. Returns `None` for recognized null representations, a boolean for
             "true"/"false" strings, a Python literal (list, dict, int, etc.) if possible, or the original
             string if no conversion is possible.
 
         Notes
         -----
-        - Recognizes 'none', 'null', 'nan', 'nil' (case-insensitive) as null values.
-        - Attempts to use `EnvironmentCaster` for advanced type parsing.
-        - Falls back to `ast.literal_eval` for literal evaluation.
-        - Returns the original string if all parsing attempts fail.
+        Recognizes 'none', 'null', 'nan', 'nil' (case-insensitive) as null values.
+        Attempts to use `EnvironmentCaster` for advanced type parsing.
+        Falls back to `ast.literal_eval` for literal evaluation.
+        Returns the original string if all parsing attempts fail.
         """
 
         # Early return for None values
@@ -365,4 +341,4 @@ class DotEnv(metaclass=Singleton):
 
         # Return the original string if parsing fails
         except (ValueError, SyntaxError):
-            return value_str
+            return value_str