orionis 0.406.0__tar.gz → 0.407.0__tar.gz

{orionis-0.406.0/orionis.egg-info → orionis-0.407.0}/PKG-INFO

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

{orionis-0.406.0 → orionis-0.407.0}/orionis/metadata/framework.py

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

orionis-0.407.0/orionis/services/asynchrony/contracts/coroutines.py

@@ -0,0 +1,32 @@
+from abc import ABC, abstractmethod
+import asyncio
+from typing import TypeVar, Union
+
+T = TypeVar("T")
+
+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
+
+        Returns
+        -------
+        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
+        -----
+        - 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-0.407.0/orionis/services/asynchrony/coroutines.py

@@ -0,0 +1,83 @@
+import asyncio
+from typing import Any, Coroutine as TypingCoroutine, TypeVar, Union
+from orionis.services.asynchrony.contracts.coroutines import ICoroutine
+from orionis.services.asynchrony.exceptions import OrionisCoroutineException
+from orionis.services.introspection.objects.types import Type
+
+T = TypeVar("T")
+
+class Coroutine(ICoroutine):
+
+    def __init__(self, func: TypingCoroutine[Any, Any, T]) -> None:
+        """
+        Initialize the Coroutine wrapper.
+
+        Parameters
+        ----------
+        func : Coroutine
+            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 object for later execution
+        self.__func = func
+
+    def run(self) -> Union[T, asyncio.Future]:
+        """
+        Executes the wrapped coroutine, either synchronously or asynchronously depending on the context.
+
+        Parameters
+        ----------
+        None
+
+        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.
+
+        Raises
+        ------
+        RuntimeError
+            If the coroutine cannot be executed due to event loop issues.
+
+        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.
+        """
+        # Attempt to get the currently running event loop
+        try:
+            loop = asyncio.get_running_loop()
+
+        # No running event loop; execute the coroutine synchronously and return its result
+        except RuntimeError:
+            return asyncio.run(self.__func)
+
+        # If inside an active event loop, schedule the coroutine and return a Future
+        if loop.is_running():
+            return asyncio.ensure_future(self.__func)
+
+        # If no event loop is running, execute the coroutine synchronously using the loop
+        else:
+            return loop.run_until_complete(self.__func)

orionis-0.407.0/orionis/services/asynchrony/exceptions/exception.py

@@ -0,0 +1,27 @@
+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
+            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-0.406.0 → orionis-0.407.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-0.407.0/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-0.407.0/orionis/services/environment/serializer/values.py

@@ -0,0 +1,21 @@
+from orionis.services.environment.enums.cast_type import EnvCastType
+
+class SerializerValue:
+
+    def __init__(self, value):
+        pass
+
+    def to(self, type_hint: str | EnvCastType = None):
+        pass
+
+    def get(self):
+        pass
+
+
+class SerializerFrom:
+
+    def __init__(self, key: str):
+        pass
+
+    def get(self):
+        pass

orionis-0.407.0/orionis/services/environment/validators/key_name.py

@@ -0,0 +1,46 @@
+import re
+from orionis.services.environment.exceptions.value import OrionisEnvironmentValueError
+
+class __ValidateKeyName:
+
+    # Regular expression pattern to match valid environment variable names
+    _pattern = re.compile(r'^[A-Z][A-Z0-9_]*$')
+
+    def __call__(self, key: object) -> str:
+        """
+        Validates that the provided environment variable name meets the required format.
+
+        Parameters
+        ----------
+        key : object
+            The environment variable name to validate.
+
+        Returns
+        -------
+        str
+            The validated environment variable name if it meets the format requirements.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the provided key is not a string or does not match the required format.
+        """
+
+        # Check if the key is a string
+        if not isinstance(key, str):
+            raise OrionisEnvironmentValueError(
+                f"Environment variable name must be a string, got {type(key).__name__}."
+            )
+
+        # Validate the key against the pattern
+        if not self._pattern.fullmatch(key):
+            raise OrionisEnvironmentValueError(
+                f"Invalid environment variable name '{key}'. It must start with an uppercase letter, "
+                "contain only uppercase letters, numbers, or underscores. Example: 'MY_ENV_VAR'."
+            )
+
+        # Return the validated key
+        return key
+
+# Instance to be used for key name validation
+ValidateKeyName = __ValidateKeyName()

orionis-0.407.0/orionis/services/environment/validators/types.py

@@ -0,0 +1,45 @@
+import re
+from typing import Any, Union
+from orionis.services.environment.enums.cast_type import EnvCastType
+from orionis.services.environment.exceptions.value import OrionisEnvironmentValueError
+
+class __ValidateTypes:
+
+    def __call__(self, value: Union[str, int, float, bool, list, dict, tuple, set], type_hint: str | EnvCastType = None) -> str:
+
+        # 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."
+            )
+
+        # If a type hint is provided, ensure it is valid.
+        if type_hint and not isinstance(type_hint, (str, EnvCastType)):
+            raise OrionisEnvironmentValueError(
+                f"Type hint must be a string or EnvCastType, got {type(type_hint).__name__}."
+            )
+
+        # If type_hint is provided, convert it to a string if it's an EnvCastType.
+        if type_hint:
+
+            # If type_hint is a string, convert it to EnvCastType if valid.
+            if isinstance(type_hint, str):
+                try:
+                    type_hint = EnvCastType[type_hint.upper()].value
+                except KeyError:
+                    raise OrionisEnvironmentValueError(
+                        f"Invalid type hint: {type_hint}. Allowed types are {[e.value for e in EnvCastType]}"
+                    )
+            elif isinstance(type_hint, EnvCastType):
+                type_hint = type_hint.value
+
+        # If no type hint is provided, use the type of the value.
+        else:
+            type_hint = type(value).__name__.lower()
+
+        # Return the type hint as a string.
+        return type_hint
+
+
+# Instance to be used for key name validation
+ValidateTypes = __ValidateTypes()

orionis-0.407.0/orionis/services/system/contracts/imports.py

@@ -0,0 +1,71 @@
+from abc import ABC, abstractmethod
+
+class IImports(ABC):
+
+    @abstractmethod
+    def collect(self):
+        """
+        Collects information about user-defined Python modules currently loaded in `sys.modules`.
+
+        This method should scan the current Python runtime environment and gather details about
+        all user-defined modules that have been imported and are present in `sys.modules`. The
+        collected information may include module names, file paths, and other relevant metadata,
+        depending on the implementation.
+
+        Returns
+        -------
+        IImports
+            Returns the current instance (`self`) with its internal imports information updated
+            to reflect the latest state of loaded modules.
+
+        Notes
+        -----
+        This method does not modify the actual modules loaded in memory; it only updates the
+        internal collection maintained by the implementation. Subclasses should implement the
+        logic for identifying and storing relevant module information.
+        """
+
+        # Subclasses should implement logic to scan sys.modules and update internal imports collection.
+        pass
+
+    @abstractmethod
+    def display(self) -> None:
+        """
+        Displays a formatted table summarizing the collected import statements.
+
+        This method should present the information about the currently collected Python module imports
+        in a human-readable tabular format. The display may include details such as module names,
+        file paths, and other relevant metadata, depending on the implementation.
+
+        Returns
+        -------
+        None
+            This method does not return any value. Its sole purpose is to output the collected import
+            information for inspection or debugging.
+
+        Notes
+        -----
+        The actual formatting and output destination (e.g., console, log, GUI) are determined by the
+        implementing subclass.
+        """
+
+        # Subclasses should implement logic to format and output the collected imports.
+        pass
+
+    @abstractmethod
+    def clear(self) -> None:
+        """
+        Removes all entries from the collected imports list, resetting the internal state.
+
+        This method should be called when you want to discard all previously collected import
+        information and start fresh. It does not affect the actual Python modules loaded in memory,
+        only the internal collection maintained by the implementation.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+        """
+
+        # Subclasses should implement logic to clear their internal imports collection.
+        pass

orionis-0.407.0/orionis/services/system/contracts/workers.py

@@ -0,0 +1,52 @@
+from abc import ABC, abstractmethod
+
+class IWorkers(ABC):
+
+    @abstractmethod
+    def setRamPerWorker(self, ram_per_worker: float) -> None:
+        """
+        Set the amount of RAM to allocate for each worker process.
+
+        Parameters
+        ----------
+        ram_per_worker : float
+            The amount of RAM, in gigabytes (GB), to allocate for each worker process.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method should be implemented by subclasses to configure the memory usage
+        per worker, which may affect the total number of workers that can be spawned
+        based on system resources.
+        """
+
+        # Implementation should assign the specified RAM per worker.
+        pass
+
+    @abstractmethod
+    def calculate(self) -> int:
+        """
+        Compute the recommended maximum number of worker processes for the current machine.
+
+        This method should consider both CPU and memory constraints to determine the optimal
+        number of worker processes that can be safely spawned without overloading system resources.
+
+        Returns
+        -------
+        int
+            The maximum number of worker processes that can be supported by the current machine,
+            based on available CPU cores and memory limits.
+
+        Notes
+        -----
+        Subclasses should implement this method to analyze system resources and return an integer
+        representing the recommended number of workers. The calculation should ensure that each
+        worker receives sufficient resources as configured (e.g., RAM per worker).
+        """
+
+        # Implementation should analyze system resources and return the recommended worker count.
+        pass