orionis 0.287.0__py3-none-any.whl → 0.288.0__py3-none-any.whl

orionis/metadata/framework.py

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

orionis/services/environment/contracts/types.py

@@ -0,0 +1,70 @@
+from abc import ABC, abstractmethod
+
+class IEnvTypes(ABC):
+
+    @abstractmethod
+    def to(self, type_hint: str):
+        """
+        Set the type hint for the Type instance.
+
+        Parameters
+        ----------
+        type_hint : str
+            The type hint to set, which must be one of the valid options defined in OPTIONS.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the provided type hint is not one of the valid options.
+        """
+        pass
+
+    @abstractmethod
+    def hasValidTypeHint(self) -> bool:
+        """
+        Check if the type hint is valid.
+
+        Returns
+        -------
+        bool
+            True if the type hint is valid (exists in the OPTIONS set), False otherwise.
+        """
+        pass
+
+    @abstractmethod
+    def explode(self) -> tuple:
+        """
+        Returns a tuple containing the type hint and value string.
+
+        Returns
+        -------
+        tuple
+            A tuple (type_hint, value_str) where:
+                type_hint : str or None
+                    The extracted type hint in lowercase, or None if not provided.
+                value_str : str or None
+                    The extracted value string, or None if not provided.
+        """
+        pass
+
+    @abstractmethod
+    def get(self):
+        """
+        Returns 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:'.
+
+        Returns
+        -------
+        Any
+            The value converted or processed according to the specified type hint.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the type hint is not one of the supported options.
+        """
+        pass

orionis/services/environment/dot_env.py

@@ -1,5 +1,6 @@
 import os
 import ast
+import re
 import threading
 from pathlib import Path
 from typing import Any, Optional, Union
@@ -7,7 +8,7 @@ from dotenv import dotenv_values, load_dotenv, set_key, unset_key
 from orionis.patterns.singleton.meta_class import Singleton
 from orionis.services.environment.exceptions.environment_value_exception import OrionisEnvironmentValueException
 from orionis.services.environment.exceptions.environment_value_error import OrionisEnvironmentValueError
-from orionis.services.environment.type_hint import EnvTypes
+from orionis.services.environment.types import EnvTypes
 
 class DotEnv(metaclass=Singleton):
 
@@ -114,7 +115,7 @@ class DotEnv(metaclass=Singleton):
             return None
 
         # Return immediately if already a basic type
-        if isinstance(value, (bool, int, float, dict, list, tuple)):
+        if isinstance(value, (bool, int, float, dict, list, tuple, set)):
             return value
 
         # Convert to string and clean
@@ -163,6 +164,11 @@ 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)):
@@ -170,17 +176,9 @@ class DotEnv(metaclass=Singleton):
                     f"Unsupported value type: {type(value).__name__}. Allowed types are str, int, float, bool, list, dict, tuple, set."
                 )
 
-            # Ensure the type is a string.
-            if not isinstance(type_hint, str):
-                raise OrionisEnvironmentValueError(
-                    f"Type hint must be a string, got {type(value).__name__}."
-                )
-
-            # Ensure the key is a string.
-            if not isinstance(key, str):
-                raise OrionisEnvironmentValueError(
-                    f"Key must be a string, got {type(key).__name__}."
-                )
+            # 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()

orionis/services/environment/{type_hint.py → types.py}

@@ -1,7 +1,8 @@
+from orionis.services.environment.contracts.types import IEnvTypes
 from orionis.services.environment.exceptions.environment_value_error import OrionisEnvironmentValueError
 from orionis.services.environment.exceptions.environment_value_exception import OrionisEnvironmentValueException
 
-class EnvTypes:
+class EnvTypes(IEnvTypes):
 
     # Type class to handle different types of environment variables
     OPTIONS = {
@@ -28,7 +29,7 @@ class EnvTypes:
         """
         return EnvTypes.OPTIONS
 
-    def __init__(self, raw: str = None):
+    def __init__(self, raw):
         """
         Parse a raw string input into a type hint and value string.
 
@@ -46,13 +47,31 @@ class EnvTypes:
         __value_str : str or None
             The extracted value string, or None if not provided.
         """
-        type_hint, value_str = raw.split(':', 1)
-        if type_hint.strip().lower() in self.OPTIONS:
-            self.__type_hint = type_hint.strip().lower()
-            self.__value_str = value_str.strip() if value_str else None
+
+        # Default values for type hint and value string
+        self.__type_hint = None
+        self.__value_raw = None
+
+        # If raw is a string, parse it to extract type hint and value
+        if isinstance(raw, str):
+
+            # Strip whitespace and check for a colon to separate type hint and value
+            self.__value_raw = raw.strip()
+
+            # If a colon is present, split the string into type hint and value
+            if ':' in self.__value_raw:
+
+                # Split the string at the first colon
+                type_hint, value_str = raw.split(':', 1)
+
+                # If the type hint is valid, set it and the value
+                if type_hint.strip().lower() in self.OPTIONS:
+                    self.__type_hint = type_hint.strip().lower()
+                    self.__value_raw = value_str.strip() if value_str else None
         else:
-            self.__type_hint = None
-            self.__value_str = raw.strip() if raw else None
+
+            # If raw is not a string, treat it as a value with no type hint
+            self.__value_raw = raw
 
     def to(self, type_hint: str):
         """
@@ -127,7 +146,7 @@ class EnvTypes:
                 value_str : str or None
                     The extracted value string, or None if not provided.
         """
-        return self.__type_hint, self.__value_str
+        return self.__type_hint, self.__value_raw
 
     def __parsePath(self):
         """
@@ -147,7 +166,7 @@ class EnvTypes:
         OrionisEnvironmentValueException
             If the value cannot be processed as a path.
         """
-        return self.__value_str.replace('\\', '/').strip()
+        return self.__value_raw.replace('\\', '/').strip()
 
     def __toPath(self):
         """
@@ -163,9 +182,9 @@ class EnvTypes:
         OrionisEnvironmentValueError
             If the internal value is not a string.
         """
-        if not isinstance(self.__value_str, str):
-            raise OrionisEnvironmentValueError(f"Value must be a string to convert to path, got {type(self.__value_str).__name__} instead.")
-        value = self.__value_str.replace('\\', '/').strip()
+        if not isinstance(self.__value_raw, str):
+            raise OrionisEnvironmentValueError(f"Value must be a string to convert to path, got {type(self.__value_raw).__name__} instead.")
+        value = self.__value_raw.replace('\\', '/').strip()
         return f"{self.__type_hint}:{value}"
 
     def __parseStr(self):
@@ -177,7 +196,7 @@ class EnvTypes:
         str
             The value string if the type hint is 'str:', otherwise raises an error.
         """
-        return self.__value_str.strip()
+        return self.__value_raw.strip()
 
     def __toStr(self):
         """
@@ -193,9 +212,9 @@ class EnvTypes:
         OrionisEnvironmentValueError
             If the internal value is not a string.
         """
-        if not isinstance(self.__value_str, str):
-            raise OrionisEnvironmentValueError(f"Value must be a string to convert to str, got {type(self.__value_str).__name__} instead.")
-        return f"{self.__type_hint}:{self.__value_str}"
+        if not isinstance(self.__value_raw, str):
+            raise OrionisEnvironmentValueError(f"Value must be a string to convert to str, got {type(self.__value_raw).__name__} instead.")
+        return f"{self.__type_hint}:{self.__value_raw}"
 
     def __parseInt(self):
         """
@@ -215,7 +234,7 @@ class EnvTypes:
         OrionisEnvironmentValueException
             If the value cannot be converted to an integer.
         """
-        value = self.__value_str.strip()
+        value = self.__value_raw.strip()
         try:
             return int(value)
         except ValueError as e:
@@ -235,9 +254,9 @@ class EnvTypes:
         OrionisEnvironmentValueError
             If the internal value is not a string or cannot be converted to an integer.
         """
-        if not isinstance(self.__value_str, int):
-            raise OrionisEnvironmentValueError(f"Value must be an integer to convert to int, got {type(self.__value_str).__name__} instead.")
-        return f"{self.__type_hint}:{str(self.__value_str)}"
+        if not isinstance(self.__value_raw, int):
+            raise OrionisEnvironmentValueError(f"Value must be an integer to convert to int, got {type(self.__value_raw).__name__} instead.")
+        return f"{self.__type_hint}:{str(self.__value_raw)}"
 
     def __parseFloat(self):
         """
@@ -257,7 +276,7 @@ class EnvTypes:
         OrionisEnvironmentValueException
             If the value cannot be converted to a float.
         """
-        value = self.__value_str.strip()
+        value = self.__value_raw.strip()
         try:
             return float(value)
         except ValueError as e:
@@ -277,9 +296,9 @@ class EnvTypes:
         OrionisEnvironmentValueError
             If the internal value is not a string or cannot be converted to a float.
         """
-        if not isinstance(self.__value_str, float):
-            raise OrionisEnvironmentValueError(f"Value must be a float to convert to float, got {type(self.__value_str).__name__} instead.")
-        return f"{self.__type_hint}:{str(self.__value_str)}"
+        if not isinstance(self.__value_raw, float):
+            raise OrionisEnvironmentValueError(f"Value must be a float to convert to float, got {type(self.__value_raw).__name__} instead.")
+        return f"{self.__type_hint}:{str(self.__value_raw)}"
 
     def __parseBool(self):
         """
@@ -299,7 +318,7 @@ class EnvTypes:
         OrionisEnvironmentValueException
             If the value cannot be converted to a boolean.
         """
-        value = self.__value_str.strip().lower()
+        value = self.__value_raw.strip().lower()
         if value in {'true', '1', 'yes', 'on'}:
             return True
         elif value in {'false', '0', 'no', 'off'}:
@@ -321,9 +340,9 @@ class EnvTypes:
         OrionisEnvironmentValueError
             If the internal value is not a boolean.
         """
-        if not isinstance(self.__value_str, bool):
-            raise OrionisEnvironmentValueError(f"Value must be a boolean to convert to bool, got {type(self.__value_str).__name__} instead.")
-        return f"{self.__type_hint}:{str(self.__value_str).lower()}"
+        if not isinstance(self.__value_raw, bool):
+            raise OrionisEnvironmentValueError(f"Value must be a boolean to convert to bool, got {type(self.__value_raw).__name__} instead.")
+        return f"{self.__type_hint}:{str(self.__value_raw).lower()}"
 
     def __parseList(self):
         """
@@ -341,7 +360,7 @@ class EnvTypes:
         """
         import ast
 
-        value = self.__value_str.strip()
+        value = self.__value_raw.strip()
         try:
             parsed = ast.literal_eval(value)
             if not isinstance(parsed, list):
@@ -364,9 +383,9 @@ class EnvTypes:
         OrionisEnvironmentValueError
             If the internal value is not a list.
         """
-        if not isinstance(self.__value_str, list):
-            raise OrionisEnvironmentValueError(f"Value must be a list to convert to list, got {type(self.__value_str).__name__} instead.")
-        return f"{self.__type_hint}:{repr(self.__value_str)}"
+        if not isinstance(self.__value_raw, list):
+            raise OrionisEnvironmentValueError(f"Value must be a list to convert to list, got {type(self.__value_raw).__name__} instead.")
+        return f"{self.__type_hint}:{repr(self.__value_raw)}"
 
     def __parseDict(self):
         """
@@ -388,7 +407,7 @@ class EnvTypes:
         """
         import ast
 
-        value = self.__value_str.strip()
+        value = self.__value_raw.strip()
         try:
             parsed = ast.literal_eval(value)
             if not isinstance(parsed, dict):
@@ -411,9 +430,9 @@ class EnvTypes:
         OrionisEnvironmentValueError
             If the internal value is not a dict.
         """
-        if not isinstance(self.__value_str, dict):
-            raise OrionisEnvironmentValueError(f"Value must be a dict to convert to dict, got {type(self.__value_str).__name__} instead.")
-        return f"{self.__type_hint}:{repr(self.__value_str)}"
+        if not isinstance(self.__value_raw, dict):
+            raise OrionisEnvironmentValueError(f"Value must be a dict to convert to dict, got {type(self.__value_raw).__name__} instead.")
+        return f"{self.__type_hint}:{repr(self.__value_raw)}"
 
     def __parseTuple(self):
         """
@@ -435,7 +454,7 @@ class EnvTypes:
         """
         import ast
 
-        value = self.__value_str.strip()
+        value = self.__value_raw.strip()
         try:
             parsed = ast.literal_eval(value)
             if not isinstance(parsed, tuple):
@@ -458,9 +477,9 @@ class EnvTypes:
         OrionisEnvironmentValueError
             If the internal value is not a tuple.
         """
-        if not isinstance(self.__value_str, tuple):
-            raise OrionisEnvironmentValueError(f"Value must be a tuple to convert to tuple, got {type(self.__value_str).__name__} instead.")
-        return f"{self.__type_hint}:{repr(self.__value_str)}"
+        if not isinstance(self.__value_raw, tuple):
+            raise OrionisEnvironmentValueError(f"Value must be a tuple to convert to tuple, got {type(self.__value_raw).__name__} instead.")
+        return f"{self.__type_hint}:{repr(self.__value_raw)}"
 
     def __parseSet(self):
         """
@@ -482,7 +501,7 @@ class EnvTypes:
         """
         import ast
 
-        value = self.__value_str.strip()
+        value = self.__value_raw.strip()
         try:
             parsed = ast.literal_eval(value)
             if not isinstance(parsed, set):
@@ -505,9 +524,9 @@ class EnvTypes:
         OrionisEnvironmentValueError
             If the internal value is not a set.
         """
-        if not isinstance(self.__value_str, set):
-            raise OrionisEnvironmentValueError(f"Value must be a set to convert to set, got {type(self.__value_str).__name__} instead.")
-        return f"{self.__type_hint}:{repr(self.__value_str)}"
+        if not isinstance(self.__value_raw, set):
+            raise OrionisEnvironmentValueError(f"Value must be a set to convert to set, got {type(self.__value_raw).__name__} instead.")
+        return f"{self.__type_hint}:{repr(self.__value_raw)}"
 
     def get(self):
         """

orionis/services/paths/exceptions/not_found_exceptions.py

@@ -1,28 +1,31 @@
 class OrionisFileNotFoundException(Exception):
     """
-    Exception raised when a file is not found in the Orionis framework.
+    Exception raised when a specified file is not found.
 
-    Args:
-        msg (str): A detailed message describing the missing file.
-
-    Example:
-        raise OrionisFileNotFoundException("File 'config.yaml' not found.")
+    Parameters
+    ----------
+    msg : str
+        The error message describing the exception.
     """
 
     def __init__(self, msg: str):
         """
-        Initializes the exception with a custom error message.
+        Initialize the exception with a custom error message.
 
-        Args:
-            msg (str): The error message describing the exception.
+        Parameters
+        ----------
+        msg : str
+            The error message describing the exception.
         """
         super().__init__(msg)
 
     def __str__(self) -> str:
         """
-        Return a string representation of the exception, including the class name and the first argument.
+        Return a string representation of the exception.
 
-        Returns:
-            str: A formatted string with the exception class name and the first argument.
+        Returns
+        -------
+        str
+            A formatted string with the exception class name and the first argument.
         """
         return f"{self.__class__.__name__}: {self.args[0]}"

orionis/services/paths/exceptions/path_value_exceptions.py

@@ -2,19 +2,20 @@ class OrionisPathValueException(Exception):
     """
     Exception raised when a file is not found in the Orionis framework.
 
-    Args:
-        msg (str): A detailed message describing the missing file.
-
-    Example:
-        raise OrionisFileNotFoundException("File 'config.yaml' not found.")
+    Parameters
+    ----------
+    msg : str
+        A detailed message describing the missing file.
     """
 
     def __init__(self, msg: str):
         """
-        Initializes the exception with a custom error message.
+        Initialize the exception with a custom error message.
 
-        Args:
-            msg (str): The error message describing the exception.
+        Parameters
+        ----------
+        msg : str
+            The error message describing the exception.
         """
         super().__init__(msg)
 
@@ -22,7 +23,9 @@ class OrionisPathValueException(Exception):
         """
         Return a string representation of the exception, including the class name and the first argument.
 
-        Returns:
-            str: A formatted string with the exception class name and the first argument.
+        Returns
+        -------
+        str
+            A formatted string with the exception class name and the first argument.
         """
         return f"{self.__class__.__name__}: {self.args[0]}"

orionis/services/standard/contracts/std.py

@@ -110,7 +110,7 @@ class IStdClass(ABC):
 
     @classmethod
     @abstractmethod
-    def from_dict(cls, dictionary: Dict[str, Any]) -> 'IStdClass':
+    def fromDict(cls, dictionary: Dict[str, Any]) -> 'IStdClass':
         """
         Creates an instance from a dictionary.
 

orionis/services/standard/exceptions/std_value_exception.py

@@ -0,0 +1,23 @@
+class OrionisStdValueException(Exception):
+
+    def __init__(self, msg: str):
+        """
+        Initialize the exception with a custom error message.
+
+        Parameters
+        ----------
+        msg : str
+            The error message describing the exception.
+        """
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        """
+        Return a string representation of the exception, including the class name and the first argument.
+
+        Returns
+        -------
+        str
+            A formatted string with the exception class name and the first argument.
+        """
+        return f"{self.__class__.__name__}: {self.args[0]}"

orionis/services/standard/std.py

@@ -1,5 +1,5 @@
 from orionis.services.standard.contracts.std import IStdClass
-from orionis.services.standard.exceptions.path_value_exceptions import OrionisStdValueException
+from orionis.services.standard.exceptions.std_value_exception import OrionisStdValueException
 
 class StdClass(IStdClass):
     """
@@ -112,7 +112,7 @@ class StdClass(IStdClass):
             delattr(self, attr)
 
     @classmethod
-    def from_dict(cls, dictionary):
+    def fromDict(cls, dictionary):
         """
         Creates a StdClass instance from a dictionary.
 

orionis/services/system/contracts/imports.py

@@ -3,29 +3,49 @@ 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):
         """
-        Collects information about user-defined Python modules currently loaded in sys.modules.
-        Returns:
-            IImports: The current instance with updated imports information.
+        Collect information about user-defined Python modules currently loaded in sys.modules.
+
+        Returns
+        -------
+        IImports
+            The current instance with updated imports information.
         """
         pass
 
     @abstractmethod
     def display(self) -> None:
         """
-        Displays a formatted table of collected import statements.
-        Returns:
-            None
+        Display a formatted table of collected import statements.
+
+        Returns
+        -------
+        None
         """
         pass
 
     @abstractmethod
     def clear(self) -> None:
         """
-        Clears the collected imports list.
+        Clear the collected imports list.
+
+        Returns
+        -------
+        None
         """
         pass

orionis/services/system/contracts/workers.py

@@ -2,17 +2,22 @@ from abc import ABC, abstractmethod
 
 class IWorkers(ABC):
     """
-    Interface - Calculates the optimal number of workers a machine can handle based on CPU and memory resources.
+    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 calculate(self) -> int:
         """
-        Computes the maximum number of workers supported by the current machine.
+        Compute the maximum number of workers supported by the current machine.
 
         Returns
         -------
         int
-            The recommended number of worker processes based on CPU and memory limits.
+            Recommended number of worker processes based on CPU and memory limits.
         """
         pass