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

orionis/services/environment/key/key_generator.py

@@ -0,0 +1,37 @@
+import os
+import base64
+
+class SecureKeyGenerator:
+    """
+    Provides static methods for generating secure random keys in base64 format.
+
+    Methods
+    -------
+    generate_key() : str
+        Generates a secure random key encoded in base64.
+    """
+
+    @staticmethod
+    def generate() -> str:
+        """
+        Generates a secure random key and encodes it in base64 format.
+
+        This method creates a cryptographically secure random key of 32 bytes,
+        encodes it using base64 encoding, and returns the result as a string
+        prefixed with 'base64:'.
+
+        Returns
+        -------
+        str
+            A string in the format 'base64:<key>', where <key> is a base64-encoded
+            representation of a securely generated 32-byte random key.
+        """
+
+        # Generate 32 bytes of cryptographically secure random data
+        key = os.urandom(32)
+
+        # Encode the random bytes using base64 and decode to a UTF-8 string
+        encoded = base64.b64encode(key).decode('utf-8')
+
+        # Return the key in the required format
+        return f"base64:{encoded}"

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/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/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/services/system/contracts/imports.py

@@ -1,51 +1,71 @@
 from abc import ABC, abstractmethod
 
 class IImports(ABC):
-    """
-    Interface for a utility to collect and display information about currently loaded Python modules.
-
-    Methods
-    -------
-    collect()
-        Collects information about user-defined Python modules currently loaded in sys.modules.
-
-    display()
-        Displays a formatted table of collected import statements.
-
-    clear()
-        Clears the collected imports list.
-    """
 
     @abstractmethod
     def collect(self):
         """
-        Collect information about user-defined Python modules currently loaded in sys.modules.
+        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
-            The current instance with updated imports information.
+            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:
         """
-        Display a formatted table of collected import statements.
+        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:
         """
-        Clear the collected imports list.
+        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/services/system/contracts/workers.py

@@ -1,35 +1,52 @@
 from abc import ABC, abstractmethod
 
 class IWorkers(ABC):
-    """
-    Interface for calculating the optimal number of workers a machine can handle based on CPU and memory resources.
-
-    Notes
-    -----
-    Implementations should provide logic to determine the recommended number of worker processes
-    according to the available CPU and memory resources of the current machine.
-    """
 
     @abstractmethod
     def setRamPerWorker(self, ram_per_worker: float) -> None:
         """
-        Set the amount of RAM allocated per worker.
+        Set the amount of RAM to allocate for each worker process.
 
         Parameters
         ----------
         ram_per_worker : float
-            Amount of RAM (in GB) allocated per worker.
+            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 maximum number of workers supported by the current machine.
+        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
-            Recommended number of worker processes based on CPU and memory limits.
+            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

orionis/services/system/imports.py

@@ -2,58 +2,68 @@ from typing import List, Dict, Any
 from orionis.services.system.contracts.imports import IImports
 
 class Imports(IImports):
-    """
-    Utility class to collect and display information about currently loaded Python modules.
-
-    This class provides methods to gather details about user-defined Python modules
-    currently loaded in `sys.modules`, excluding standard library and virtual environment modules.
-    It can display the collected information in a formatted table using the Rich library.
-    """
 
     def __init__(self):
         """
-        Initialize the Imports object.
+        Initialize the Imports instance.
+
+        This constructor sets up the Imports object by initializing an empty list
+        to store information about user-defined Python modules. The list will
+        contain dictionaries, each representing a module with its name, file path,
+        and defined symbols.
 
-        Initializes an empty list to store module information.
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
+
+        # List to hold information about imported modules
         self.imports: List[Dict[str, Any]] = []
 
     def collect(self) -> 'Imports':
         """
         Collect information about user-defined Python modules currently loaded.
 
-        For each qualifying module, gathers:
-            - The module's name.
-            - The relative file path to the module from the current working directory.
-            - A list of symbols (functions, classes, or submodules) defined in the module.
+        Iterates through all modules in `sys.modules` and gathers details for each qualifying module:
+            - Module name.
+            - Relative file path from the current working directory.
+            - List of symbols (functions, classes, or submodules) defined in the module.
 
-        Excludes:
-            - Modules from the standard library.
-            - Modules from the active virtual environment (if any).
-            - Binary extension modules (.pyd, .dll, .so).
-            - Special modules like "__main__", "__mp_main__", and modules starting with "_distutils".
+        Excludes modules that:
+            - Are part of the standard library.
+            - Reside in the active virtual environment (if any).
+            - Are binary extension modules (e.g., `.pyd`, `.dll`, `.so`).
+            - Are special modules such as `"__main__"`, `"__mp_main__"`, or those starting with `"_distutils"`.
 
-        The collected information is stored in `self.imports` as a list of dictionaries.
+        The collected information is stored in `self.imports` as a list of dictionaries, each containing the module's name, file path, and symbols.
 
         Returns
         -------
         Imports
-            The current instance with updated imports information.
+            The current instance of `Imports` with the `imports` attribute updated to include information about the collected modules.
         """
 
         import sys
         import os
         import types
 
+        # Clear any previously collected imports
         self.imports.clear()
+
+        # Get standard library paths to exclude standard modules
         stdlib_paths = [os.path.dirname(os.__file__)]
+
+        # Get virtual environment path if active
         venv_path = os.environ.get("VIRTUAL_ENV")
         if venv_path:
             venv_path = os.path.abspath(venv_path)
 
+        # Iterate over all loaded modules
         for name, module in list(sys.modules.items()):
-            file:str = getattr(module, '__file__', None)
+            file: str = getattr(module, '__file__', None)
 
+            # Filter out unwanted modules based on path, type, and name
             if (
                 file
                 and not any(file.startswith(stdlib_path) for stdlib_path in stdlib_paths)
@@ -62,18 +72,25 @@ class Imports(IImports):
                 and name not in ("__main__", "__mp_main__")
                 and not name.startswith("_distutils")
             ):
+
+                # Get relative file path from current working directory
                 rel_file = os.path.relpath(file, os.getcwd())
                 symbols = []
 
+                # Collect symbols defined in the module (functions, classes, submodules)
                 try:
                     for attr in dir(module):
                         value = getattr(module, attr)
                         if isinstance(value, (types.FunctionType, type, types.ModuleType)):
+
+                            # Ensure symbol is defined in this module
                             if getattr(value, '__module__', None) == name:
                                 symbols.append(attr)
                 except Exception:
+                    # Ignore errors during symbol collection
                     pass
 
+                # Only add modules that are not __init__.py and have symbols
                 if not rel_file.endswith('__init__.py') and symbols:
                     self.imports.append({
                         "name": name,
@@ -81,32 +98,45 @@ class Imports(IImports):
                         "symbols": symbols,
                     })
 
+        # Return the current instance with updated imports
         return self
 
     def display(self) -> None:
         """
         Display a formatted table of collected import statements using the Rich library.
 
-        If the imports have not been collected yet, it calls `self.collect()` to gather them.
-        The table includes columns for the import name, file, and imported symbols, and is
-        rendered inside a styled panel in the console.
+        This method presents a visual summary of all collected user-defined Python modules.
+        If the imports have not been collected yet, it automatically calls `self.collect()` to gather them.
+        The output is rendered as a table inside a styled panel in the console, showing each module's name,
+        relative file path, and its defined symbols.
+
+        Parameters
+        ----------
+        None
 
         Returns
         -------
         None
+            This method does not return any value. It outputs the formatted table to the console.
         """
 
+        # Collect imports if not already done
         if not self.imports:
             self.collect()
 
+        # Import Rich components for console output
         from rich.console import Console
         from rich.table import Table
         from rich.box import MINIMAL
         from rich.panel import Panel
 
+        # Create a console instance for output
         console = Console()
+
+        # Set table width to 75% of console width
         width = int(console.size.width * 0.75)
 
+        # Create a table with minimal box style and custom formatting
         table = Table(
             box=MINIMAL,
             show_header=True,
@@ -117,14 +147,17 @@ class Imports(IImports):
             collapse_padding=True,
         )
 
+        # Add columns for module name, file path, and symbols
         table.add_column("Name", style="cyan", no_wrap=True)
         table.add_column("File", style="white")
         table.add_column("Symbols", style="magenta")
 
+        # Populate the table with sorted import data
         for imp in sorted(self.imports, key=lambda x: x["name"].lower()):
             symbols_str = ", ".join(imp["symbols"])
             table.add_row(imp["name"], imp["file"], symbols_str)
 
+        # Render the table inside a styled panel in the console
         console.print(Panel(
             table,
             title="[bold blue]🔎 Loaded Python Modules (Orionis Imports Trace)[/bold blue]",
@@ -134,10 +167,17 @@ class Imports(IImports):
 
     def clear(self) -> None:
         """
-        Clear the collected imports list.
+        Remove all entries from the collected imports list.
+
+        This method resets the `imports` attribute by removing all currently stored
+        module information. It is useful for discarding previously collected data
+        before performing a new collection or when a fresh state is required.
 
         Returns
         -------
         None
+            This method does not return any value. The `imports` list is emptied in place.
         """
+
+        # Remove all items from the imports list to reset its state
         self.imports.clear()

orionis/services/system/runtime/imports.py

@@ -25,6 +25,7 @@ Notes
 - Thread safety is provided via a threading.Lock.
 
 """
+
 import builtins
 from collections import defaultdict
 from threading import Lock
@@ -40,40 +41,48 @@ _import_lock = Lock()
 
 def custom_import(name, globals=None, locals=None, fromlist=(), level=0):
     """
-    Custom import function that tracks imports of 'orionis' modules.
+    Tracks and logs imports of modules whose names start with 'orionis'.
+
+    This function overrides Python's built-in import mechanism to monitor
+    how many times modules from the 'orionis' package are imported. It
+    increments an internal counter for each such import and prints a log
+    message with the module name, import count, and fromlist. Thread safety
+    is ensured using a lock.
 
     Parameters
     ----------
     name : str
         The name of the module to import.
     globals : dict, optional
-        The global namespace.
+        The global namespace in which the import is performed.
     locals : dict, optional
-        The local namespace.
+        The local namespace in which the import is performed.
     fromlist : tuple, optional
         Names to import from the module.
     level : int, optional
-        Relative import level.
+        Relative import level (0 for absolute, >0 for relative).
 
     Returns
     -------
-    module
-        The imported module.
+    module : ModuleType
+        The imported module object as returned by the original import function.
     """
-    # Check if the module name starts with 'orionis'
+    # Only track imports for modules starting with 'orionis'
     if str(name).startswith("orionis"):
         with _import_lock:
+
+            # Increment the import count for this module
             _import_count[name] += 1
             count = _import_count[name]
 
-            # Print the import details
+            # Print import details to the console
             print(
                 f"\033[1;37mModule\033[0m: \033[90m{name}\033[0m | "
                 f"\033[1;37mImported\033[0m: \033[90m{count}\033[0m | "
                 f"\033[1;37mFromList\033[0m: \033[90m{fromlist}\033[0m"
             )
 
-    # Call the original import function
+    # Delegate the actual import to the original __import__ function
     return _original_import(name, globals, locals, fromlist, level)
 
 # Override the built-in __import__ function