orionis 0.405.0__py3-none-any.whl → 0.407.0__py3-none-any.whl

orionis/foundation/providers/console_provider.py

@@ -3,15 +3,37 @@ from orionis.console.output.contracts.console import IConsole
 from orionis.container.providers.service_provider import ServiceProvider
 
 class ConsoleProvider(ServiceProvider):
+    """
+    ConsoleProvider
+    ===============
+
+    Registers the console output service in the application container.
+    Provides access to various console output features, including information, warnings, errors, debug messages, tables, confirmations, and password prompts.
+
+    Methods
+    -------
+    register()
+        Registers the console service in the application container.
+    boot()
+        Performs post-registration initialization if needed.
+    """
 
     def register(self) -> None:
         """
-        Register services into the application container.
+        Registers the console service in the application container.
+
+        Returns
+        -------
+        None
         """
         self.app.transient(IConsole, Console, alias="core.orionis.console")
 
     def boot(self) -> None:
         """
-        Perform any post-registration bootstrapping or initialization.
+        Performs post-registration initialization if needed.
+
+        Returns
+        -------
+        None
         """
         pass

orionis/foundation/providers/dumper_provider.py

@@ -3,15 +3,37 @@ from orionis.console.dumper.contracts.dump import IDebug
 from orionis.container.providers.service_provider import ServiceProvider
 
 class DumperProvider(ServiceProvider):
+    """
+    DumperProvider
+    ==============
+
+    Registers the debug message service in the application container.
+    Provides access to debug message printing, error reporting, and other console diagnostics.
+
+    Methods
+    -------
+    register()
+        Registers the debug service in the application container.
+    boot()
+        Performs post-registration initialization if needed.
+    """
 
     def register(self) -> None:
         """
-        Register services into the application container.
+        Registers the debug service in the application container.
+
+        Returns
+        -------
+        None
         """
         self.app.transient(IDebug, Debug, alias="core.orionis.dumper")
 
     def boot(self) -> None:
         """
-        Perform any post-registration bootstrapping or initialization.
+        Performs post-registration initialization if needed.
+
+        Returns
+        -------
+        None
         """
         pass

orionis/foundation/providers/logger_provider.py

@@ -3,15 +3,37 @@ from orionis.services.log.contracts.log_service import ILoggerService
 from orionis.services.log.log_service import LoggerService
 
 class LoggerProvider(ServiceProvider):
+    """
+    LoggerProvider
+    ==============
+
+    Registers the logging service in the application container.
+    Provides a `LoggerService` instance for application-wide logging.
+
+    Methods
+    -------
+    register()
+        Registers the logging service in the application container.
+    boot()
+        Performs post-registration initialization if needed.
+    """
 
     def register(self) -> None:
         """
-        Register services into the application container.
+        Registers the logging service in the application container.
+
+        Returns
+        -------
+        None
         """
         self.app.instance(ILoggerService, LoggerService(self.app.config('logging')), alias="core.orionis.logger")
 
     def boot(self) -> None:
         """
-        Perform any post-registration bootstrapping or initialization.
+        Performs post-registration initialization if needed.
+
+        Returns
+        -------
+        None
         """
         pass

orionis/foundation/providers/path_resolver_provider.py

@@ -3,15 +3,38 @@ from orionis.services.paths.contracts.resolver import IResolver
 from orionis.services.paths.resolver import Resolver
 
 class PathResolverProvider(ServiceProvider):
+    """
+    PathResolverProvider
+    ===================
+
+    Registers the path resolution service in the application container.
+    Provides compatibility with the file system for resolving paths.
+
+    Methods
+    -------
+    register()
+        Registers the path resolver service in the application container.
+    boot()
+        Performs post-registration initialization if needed.
+    """
+
 
     def register(self) -> None:
         """
-        Register services into the application container.
+        Registers the path resolver service in the application container.
+
+        Returns
+        -------
+        None
         """
         self.app.transient(IResolver, Resolver, alias="core.orionis.path_resolver")
 
     def boot(self) -> None:
         """
-        Perform any post-registration bootstrapping or initialization.
+        Performs post-registration initialization if needed.
+
+        Returns
+        -------
+        None
         """
         pass

orionis/foundation/providers/progress_bar_provider.py

@@ -3,15 +3,37 @@ from orionis.console.dynamic.progress_bar import ProgressBar
 from orionis.container.providers.service_provider import ServiceProvider
 
 class ProgressBarProvider(ServiceProvider):
+    """
+    ProgressBarProvider
+    ===================
+
+    Registers the dynamic progress bar service in the application container.
+    Provides a console progress bar for visual feedback during operations.
+
+    Methods
+    -------
+    register()
+        Registers the progress bar service in the application container.
+    boot()
+        Performs post-registration initialization if needed.
+    """
 
     def register(self) -> None:
         """
-        Register services into the application container.
+        Registers the progress bar service in the application container.
+
+        Returns
+        -------
+        None
         """
         self.app.transient(IProgressBar, ProgressBar, alias="core.orionis.progress_bar")
 
     def boot(self) -> None:
         """
-        Perform any post-registration bootstrapping or initialization.
+        Performs post-registration initialization if needed.
+
+        Returns
+        -------
+        None
         """
         pass

orionis/foundation/providers/testing_provider.py

@@ -0,0 +1,39 @@
+from orionis.container.providers.service_provider import ServiceProvider
+from orionis.test.contracts.unit_test import IUnitTest
+from orionis.test.core.unit_test import UnitTest
+
+class TestingProvider(ServiceProvider):
+    """
+    TestingProvider
+    ===============
+
+    Registers the unit testing environment service in the application container.
+    Provides a native unit testing framework for Orionis with features beyond common frameworks.
+
+    Methods
+    -------
+    register()
+        Registers the unit testing service in the application container.
+    boot()
+        Performs post-registration initialization if needed.
+    """
+
+    def register(self) -> None:
+        """
+        Registers the unit testing service in the application container.
+
+        Returns
+        -------
+        None
+        """
+        self.app.singleton(IUnitTest, UnitTest, alias="core.orionis.testing")
+
+    def boot(self) -> None:
+        """
+        Performs post-registration initialization if needed.
+
+        Returns
+        -------
+        None
+        """
+        pass

orionis/foundation/providers/workers_provider.py

@@ -3,15 +3,37 @@ from orionis.services.system.contracts.workers import IWorkers
 from orionis.services.system.workers import Workers
 
 class WorkersProvider(ServiceProvider):
+    """
+    WorkersProvider
+    ===============
+
+    Registers the worker management service in the application container.
+    Determines the optimal number of workers to start based on system analysis.
+
+    Methods
+    -------
+    register()
+        Registers the worker service in the application container.
+    boot()
+        Performs post-registration initialization if needed.
+    """
 
     def register(self) -> None:
         """
-        Register services into the application container.
+        Registers the worker service in the application container.
+
+        Returns
+        -------
+        None
         """
         self.app.transient(IWorkers, Workers, alias="core.orionis.workers")
 
     def boot(self) -> None:
         """
-        Perform any post-registration bootstrapping or initialization.
+        Performs post-registration initialization if needed.
+
+        Returns
+        -------
+        None
         """
         pass

orionis/metadata/framework.py

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

orionis/services/asynchrony/contracts/coroutines.py

@@ -9,16 +9,24 @@ class ICoroutine(ABC):
     @abstractmethod
     def run(self) -> Union[T, asyncio.Future]:
         """
-        Execute the wrapped coroutine.
+        Executes the wrapped coroutine, either synchronously or asynchronously depending on the context.
+
+        Parameters
+        ----------
+        None
 
         Returns
         -------
-        result : T or asyncio.Future
-            The result of the coroutine if run synchronously, or a Future if run in an event loop.
+        T or asyncio.Future
+            If called outside 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
         -----
-        - If called from outside an event loop, this method will run the coroutine synchronously.
-        - If called from within an event loop, it will schedule the coroutine and return a Future.
+        - 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.
+        - 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

orionis/services/asynchrony/coroutines.py

@@ -7,20 +7,6 @@ from orionis.services.introspection.objects.types import Type
 T = TypeVar("T")
 
 class Coroutine(ICoroutine):
-    """
-    Wrapper class for coroutine objects to facilitate execution in both synchronous
-    and asynchronous contexts.
-
-    Parameters
-    ----------
-    func : Coroutine
-        The coroutine object to be wrapped.
-
-    Raises
-    ------
-    OrionisCoroutineException
-        If the provided object is not a coroutine.
-    """
 
     def __init__(self, func: TypingCoroutine[Any, Any, T]) -> None:
         """
@@ -29,51 +15,69 @@ class Coroutine(ICoroutine):
         Parameters
         ----------
         func : Coroutine
-            The coroutine object to be wrapped.
+            The coroutine object to be wrapped. Must be an awaitable coroutine.
 
         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():
             raise OrionisCoroutineException(
                 f"Expected a coroutine object, but got {type(func).__name__}."
             )
 
-        # Store the coroutine function
+        # Store the coroutine object for later execution
         self.__func = func
 
     def run(self) -> Union[T, asyncio.Future]:
         """
-        Execute the wrapped coroutine.
+        Executes the wrapped coroutine, either synchronously or asynchronously depending on the context.
+
+        Parameters
+        ----------
+        None
 
         Returns
         -------
-        result : T or asyncio.Future
-            The result of the coroutine if run synchronously, or a Future if run in an event loop.
+        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.
+
+        Raises
+        ------
+        RuntimeError
+            If the coroutine cannot be executed due to event loop issues.
 
         Notes
         -----
-        - If called from outside an event loop, this method will run the coroutine synchronously.
-        - If called from within an event loop, it will schedule the coroutine and return a Future.
+        - 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.
         """
+        # Attempt to get the currently running event loop
         try:
-
-            # Get the current event loop
             loop = asyncio.get_running_loop()
 
+        # No running event loop; execute the coroutine synchronously and return its result
         except RuntimeError:
-
-            # No running event loop, run synchronously
             return asyncio.run(self.__func)
 
+        # If inside an active event loop, schedule the coroutine and return a Future
         if loop.is_running():
-
-            # Inside an event loop, schedule as a Future
             return asyncio.ensure_future(self.__func)
 
+        # If no event loop is running, execute the coroutine synchronously using the loop
         else:
-
-            # No running loop, run synchronously
             return loop.run_until_complete(self.__func)

orionis/services/asynchrony/exceptions/exception.py

@@ -2,18 +2,26 @@ class OrionisCoroutineException(Exception):
 
     def __init__(self, msg: str):
         """
+        Initializes an OrionisCoroutineException with a descriptive error message.
+
         Parameters
         ----------
         msg : str
             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.
+
         Returns
         -------
         str
-            Formatted string describing the exception.
+            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/core/dot_env.py

@@ -5,6 +5,9 @@ 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.cast_type import EnvCastType
+from orionis.services.environment.validators.key_name import ValidateKeyName
+from orionis.services.environment.validators.types import ValidateTypes
 from orionis.support.patterns.singleton import Singleton
 from orionis.services.environment.exceptions import OrionisEnvironmentValueException, OrionisEnvironmentValueError
 from orionis.services.environment.dynamic.types import EnvTypes
@@ -16,33 +19,56 @@ class DotEnv(metaclass=Singleton):
 
     def __init__(self, path: str = None) -> None:
         """
-        Initialize the environment service by resolving the path to the `.env` file, ensuring its existence,
-        and loading environment variables from it.
+        Initialize the DotEnv service by resolving and preparing the `.env` file.
+
+        This method determines the path to the `.env` file, ensures its existence,
+        and loads environment variables from it into the current process environment.
 
         Parameters
         ----------
         path : str, optional
-            Path to the `.env` file. If not provided, defaults to a `.env` file
+            The path to the `.env` file. If not provided, defaults to a `.env` file
             in the current working directory.
 
+        Returns
+        -------
+        None
+            This method does not return any value.
+
         Raises
         ------
         OSError
-            If the `.env` file cannot be created when it does not exist.
+            If the `.env` file cannot be created or accessed.
+
+        Notes
+        -----
+        - If the specified `.env` file does not exist, it will be created.
+        - Environment variables from the `.env` file are loaded into the process environment.
         """
+
         try:
+
+            # Use a thread-safe lock to ensure only one thread can execute this block at a time
             with self._lock:
+
+                # Defualt Environment file path
+                self.__resolved_path = Path(os.getcwd()) / ".env"
+
+                # If a path is provided, resolve it
                 if path:
-                    self._resolved_path = Path(path).expanduser().resolve()
-                else:
-                    self._resolved_path = Path(os.getcwd()) / ".env"
+                    self.__resolved_path = Path(path).expanduser().resolve()
+
+                # Create the .env file if it does not exist
+                if not self.__resolved_path.exists():
+                    self.__resolved_path.touch()
 
-                if not self._resolved_path.exists():
-                    self._resolved_path.touch()
+                # Load environment variables from the .env file into the process environment
+                load_dotenv(self.__resolved_path)
 
-                load_dotenv(self._resolved_path)
         except OSError as e:
-            raise OSError(f"Failed to create or access the .env file at {self._resolved_path}: {e}")
+
+            # Raise an error if the .env file cannot be created or accessed
+            raise OSError(f"Failed to create or access the .env file at {self.__resolved_path}: {e}")
 
     def __parseValue(self, value: Any) -> Any:
         """
@@ -172,7 +198,7 @@ class DotEnv(metaclass=Singleton):
                 )
 
             # Get the value from the .env file or the current environment.
-            value = dotenv_values(self._resolved_path).get(key)
+            value = dotenv_values(self.__resolved_path).get(key)
 
             # If the value is not found in the .env file, check the current environment variables.
             if value is None:
@@ -181,7 +207,7 @@ class DotEnv(metaclass=Singleton):
             # Parse the value using the internal __parseValue method and return it
             return self.__parseValue(value) if value is not None else default
 
-    def set(self, key: str, value: Union[str, int, float, bool, list, dict, tuple, set], type_hint: str = None) -> bool:
+    def set(self, key: str, value: Union[str, int, float, bool, list, dict, tuple, set], type_hint: str | EnvCastType = None) -> bool:
         """
         Set an environment variable with the specified key and value.
 
@@ -203,32 +229,18 @@ class DotEnv(metaclass=Singleton):
         """
         with self._lock:
 
-            # Ensure the key is a string.
-            if not isinstance(key, str) or not re.match(r'^[A-Z][A-Z0-9_]*$', key):
-                raise OrionisEnvironmentValueError(
-                    f"The environment variable name '{key}' is not valid. It must be an uppercase string, may contain numbers and underscores, and must always start with a letter. Example of a valid name: 'MY_ENV_VAR'."
-                )
-
-            # Ensure the value is a valid type.
-            if not isinstance(value, (str, int, float, bool, list, dict, tuple, set)):
-                raise OrionisEnvironmentValueError(
-                    f"Unsupported value type: {type(value).__name__}. Allowed types are str, int, float, bool, list, dict, tuple, set."
-                )
+            # Ensure name key is valid.
+            key = ValidateKeyName(key)
+            type = ValidateTypes(value, type_hint)
 
-            # Dinamically determine the type hint if not provided.
-            if isinstance(value, (int, float, bool, list, dict, tuple, set)) and not type_hint:
-                type_hint = type(value).__name__.lower()
 
-            # Validate the type hint if provided.
-            options = EnvTypes.options()
-            if type_hint and type_hint not in options:
-                raise OrionisEnvironmentValueException(f"Invalid type hint: {type_hint}. Allowed types are {str(options)}.")
 
+            
             # Serialize the value based on its type.
             serialized_value = self.__serializeValue(value, type_hint)
 
             # Set the environment variable in the .env file and the current process environment.
-            set_key(str(self._resolved_path), key, serialized_value)
+            set_key(str(self.__resolved_path), key, serialized_value)
             os.environ[key] = str(value)
 
             # Return True to indicate success.
@@ -249,7 +261,7 @@ class DotEnv(metaclass=Singleton):
             True if the operation was successful.
         """
         with self._lock:
-            unset_key(str(self._resolved_path), key)
+            unset_key(str(self.__resolved_path), key)
             os.environ.pop(key, None)
             return True
 
@@ -264,5 +276,5 @@ class DotEnv(metaclass=Singleton):
             with values parsed using the internal __parseValue method.
         """
         with self._lock:
-            raw_values = dotenv_values(self._resolved_path)
+            raw_values = dotenv_values(self.__resolved_path)
             return {k: self.__parseValue(v) for k, v in raw_values.items()}

orionis/services/environment/enums/cast_type.py

@@ -0,0 +1,42 @@
+from enum import Enum
+
+class EnvCastType(Enum):
+    """
+    Enum representing supported environment variable cast types.
+
+    Attributes
+    ----------
+    PATH : EnvCastType
+        Cast to a file system path.
+    STR : EnvCastType
+        Cast to a string.
+    INT : EnvCastType
+        Cast to an integer.
+    FLOAT : EnvCastType
+        Cast to a floating-point number.
+    BOOL : EnvCastType
+        Cast to a boolean value.
+    LIST : EnvCastType
+        Cast to a list.
+    DICT : EnvCastType
+        Cast to a dictionary.
+    TUPLE : EnvCastType
+        Cast to a tuple.
+    SET : EnvCastType
+        Cast to a set.
+
+    Returns
+    -------
+    EnvCastType
+        An enumeration member representing the desired cast type.
+    """
+
+    PATH = 'path'   # Represents a file system path
+    STR = 'str'     # Represents a string type
+    INT = 'int'     # Represents an integer type
+    FLOAT = 'float' # Represents a floating-point type
+    BOOL = 'bool'   # Represents a boolean type
+    LIST = 'list'   # Represents a list type
+    DICT = 'dict'   # Represents a dictionary type
+    TUPLE = 'tuple' # Represents a tuple type
+    SET = 'set'     # Represents a set type

orionis/services/environment/helpers/functions.py

@@ -17,5 +17,4 @@ def env(key: str, default: Any = None) -> Any:
     Any
         The value of the environment variable if it exists, otherwise the default value.
     """
-    dotenv = DotEnv()
-    return dotenv.get(key, default)
+    return DotEnv().get(key, default)