orionis 0.435.0__py3-none-any.whl → 0.437.0__py3-none-any.whl

orionis/services/environment/enums/__init__.py

@@ -0,0 +1,5 @@
+from .value_type import EnvironmentValueType
+
+__all__ = [
+    'EnvironmentValueType'
+]

orionis/services/environment/enums/value_type.py

@@ -2,33 +2,30 @@ from enum import Enum
 
 class EnvironmentValueType(Enum):
     """
-    Enum representing supported environment variable cast types.
+    Enum representing the supported types for casting environment variable values.
 
     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.
+    BASE64 : str
+        Represents a base64 encoded value.
+    PATH : str
+        Represents a file system path.
+    STR : str
+        Represents a string value.
+    INT : str
+        Represents an integer value.
+    FLOAT : str
+        Represents a floating-point value.
+    BOOL : str
+        Represents a boolean value.
+    LIST : str
+        Represents a list value.
+    DICT : str
+        Represents a dictionary value.
+    TUPLE : str
+        Represents a tuple value.
+    SET : str
+        Represents a set value.
     """
 
     BASE64 = 'base64' # Represents a base64 encoded type
@@ -40,4 +37,4 @@ class EnvironmentValueType(Enum):
     LIST = 'list'     # Represents a list type
     DICT = 'dict'     # Represents a dictionary type
     TUPLE = 'tuple'   # Represents a tuple type
-    SET = 'set'       # Represents a set type
+    SET = 'set'       # Represents a set type

orionis/services/environment/env.py

@@ -7,72 +7,88 @@ class Env(IEnv):
     @staticmethod
     def get(key: str, default: Any = None) -> Any:
         """
-        Retrieve the value of an environment variable by key.
+        Retrieve the value of an environment variable by its key.
 
         Parameters
         ----------
         key : str
-            The name of the environment variable to retrieve.
+            The environment variable name to look up.
         default : Any, optional
-            The value to return if the key is not found. Default is None.
+            Value to return if the key is not found. Defaults to None.
 
         Returns
         -------
         Any
-            The value of the environment variable if found, otherwise the default value.
+            The value of the environment variable if present, otherwise `default`.
         """
+
+        # Create a new DotEnv instance to access environment variables
         dotenv = DotEnv()
+
+        # Retrieve the value for the given key, or return default if not found
         return dotenv.get(key, default)
 
     @staticmethod
     def set(key: str, value: str, type_hint: str = None) -> bool:
         """
-        Set an environment variable in the .env file.
+        Set or update an environment variable in the .env file.
 
         Parameters
         ----------
         key : str
-            The name of the environment variable to set.
+            The environment variable name to set.
         value : str
             The value to assign to the environment variable.
         type_hint : str, optional
-            The type of the environment variable (e.g., 'str', 'int'). Default is None.
+            Optional type hint for the variable (e.g., 'str', 'int'). Defaults to None.
 
         Returns
         -------
         bool
             True if the variable was set successfully, False otherwise.
         """
+
+        # Create a new DotEnv instance to modify environment variables
         dotenv = DotEnv()
+
+        # Set the environment variable with the specified key, value, and optional type hint
         return dotenv.set(key, value, type_hint)
 
     @staticmethod
     def unset(key: str) -> bool:
         """
-        Remove the specified environment variable from the .env file.
+        Remove an environment variable from the .env file.
 
         Parameters
         ----------
         key : str
-            The name of the environment variable to remove.
+            The environment variable name to remove.
 
         Returns
         -------
         bool
-            True if the variable was successfully removed, False otherwise.
+            True if the variable was removed successfully, False otherwise.
         """
+
+        # Create a new DotEnv instance to remove environment variables
         dotenv = DotEnv()
+
+        # Remove the environment variable with the specified key
         return dotenv.unset(key)
 
     @staticmethod
     def all() -> Dict[str, Any]:
         """
-        Retrieve all environment variables as a dictionary.
+        Get all environment variables as a dictionary.
 
         Returns
         -------
         dict of str to Any
-            A dictionary containing all environment variables loaded by DotEnv.
+            Dictionary containing all environment variables loaded by DotEnv.
         """
+
+        # Create a new DotEnv instance to access all environment variables
         dotenv = DotEnv()
+
+        # Return all environment variables as a dictionary
         return dotenv.all()

orionis/services/environment/exceptions/exception.py

@@ -2,18 +2,22 @@ class OrionisEnvironmentValueException(Exception):
 
     def __init__(self, msg: str):
         """
+        Initialize the OrionisEnvironmentValueException.
+
         Parameters
         ----------
         msg : str
-            Descriptive error message explaining the cause of the exception.
+            A descriptive error message that explains the cause of the exception.
         """
         super().__init__(msg)
 
     def __str__(self) -> str:
         """
+        Return the string representation of the exception.
+
         Returns
         -------
         str
-            Formatted string describing the exception.
+            The error message associated with the exception.
         """
         return str(self.args[0])

orionis/services/environment/exceptions/value.py

@@ -2,18 +2,22 @@ class OrionisEnvironmentValueError(Exception):
 
     def __init__(self, msg: str):
         """
+        Initialize the OrionisEnvironmentValueError exception.
+
         Parameters
         ----------
         msg : str
-            Descriptive error message explaining the cause of the exception.
+            A descriptive error message explaining the cause of the exception.
         """
         super().__init__(msg)
 
     def __str__(self) -> str:
         """
+        Return a formatted string describing the exception.
+
         Returns
         -------
         str
-            Formatted string describing the exception.
+            The error message associated with the exception.
         """
         return str(self.args[0])

orionis/services/environment/helpers/functions.py

@@ -3,18 +3,20 @@ from orionis.services.environment.core.dot_env import DotEnv
 
 def env(key: str, default: Any = None) -> Any:
     """
-    Retrieve the value of an environment variable.
+    Retrieves the value of an environment variable.
 
     Parameters
     ----------
     key : str
         The name of the environment variable to retrieve.
     default : Any, optional
-        The value to return if the environment variable is not found. Default is None.
+        The value to return if the environment variable is not found. Defaults to None.
 
     Returns
     -------
     Any
-        The value of the environment variable if it exists, otherwise the default value.
+        The value of the environment variable if it exists, otherwise the specified default value.
     """
+
+    # Instantiate DotEnv and retrieve the environment variable by key
     return DotEnv().get(key, default)

orionis/services/environment/key/key_generator.py

@@ -2,28 +2,25 @@ import os
 
 class SecureKeyGenerator:
     """
-    Provides static methods for generating secure random keys in base64 format.
+    Static utility class for generating cryptographically secure random keys.
 
-    Methods
-    -------
-    generate_key() : str
-        Generates a secure random key encoded in base64.
+    This class provides a static method to generate a secure random key,
+    encoded as a hexadecimal string, suitable for use in security-sensitive
+    applications such as cryptographic secrets or tokens.
     """
 
     @staticmethod
     def generate() -> str:
         """
-        Generates a cryptographically secure random key and encodes it in hexadecimal format.
-
-        This method uses the operating system's cryptographic random number generator to
-        produce a 32-byte random value, which is then encoded as a hexadecimal string.
+        Generate a cryptographically secure random key encoded in hexadecimal.
 
         Returns
         -------
         str
-            A 64-character hexadecimal string representing a 32-byte secure random key.
+            A 64-character hexadecimal string representing a 32-byte
+            cryptographically secure random key.
         """
 
         # Generate 32 random bytes using a cryptographically secure RNG
         # Encode the bytes as a hexadecimal string and return
-        return os.urandom(32).hex()
+        return os.urandom(32).hex()

orionis/services/environment/validators/__init__.py

@@ -0,0 +1,7 @@
+from .key_name import ValidateKeyName
+from .types import ValidateTypes
+
+__all__ = [
+    'ValidateKeyName',
+    'ValidateTypes',
+]

orionis/services/environment/validators/key_name.py

@@ -8,7 +8,7 @@ class __ValidateKeyName:
 
     def __call__(self, key: object) -> str:
         """
-        Validates that the provided environment variable name meets the required format.
+        Validates that the provided environment variable name is a string and matches the required format.
 
         Parameters
         ----------
@@ -26,21 +26,21 @@ class __ValidateKeyName:
             If the provided key is not a string or does not match the required format.
         """
 
-        # Check if the key is a string
+        # Ensure the key is of type 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
+        # Check if the key matches the required pattern for environment variable names
         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 the validated key if all checks pass
         return key
 
 # Instance to be used for key name validation
-ValidateKeyName = __ValidateKeyName()
+ValidateKeyName = __ValidateKeyName()

orionis/services/environment/validators/types.py

@@ -1,4 +1,3 @@
-import re
 from typing import Union
 from orionis.services.environment.enums.value_type import EnvironmentValueType
 from orionis.services.environment.exceptions.value import OrionisEnvironmentValueError
@@ -6,7 +5,26 @@ from orionis.services.environment.exceptions.value import OrionisEnvironmentValu
 class __ValidateTypes:
 
     def __call__(self, value: Union[str, int, float, bool, list, dict, tuple, set], type_hint: str | EnvironmentValueType = None) -> str:
+        """
+        Validates and determines the type of a given value, optionally using a provided type hint.
 
+        Parameters
+        ----------
+        value : str, int, float, bool, list, dict, tuple, or set
+            The value whose type is to be validated and determined.
+        type_hint : str or EnvironmentValueType, optional
+            An optional type hint specifying the expected type. Can be a string or an EnvironmentValueType.
+
+        Returns
+        -------
+        str
+            The determined type as a string, either from the type hint or inferred from the value.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the value is not of a supported type or if the type hint is invalid.
+        """
         # Ensure the value is a valid type.
         if not isinstance(value, (str, int, float, bool, list, dict, tuple, set)):
             raise OrionisEnvironmentValueError(
@@ -23,15 +41,17 @@ class __ValidateTypes:
         if type_hint:
 
             # If type_hint is a string, convert it to EnvironmentValueType if valid.
-            if isinstance(type_hint, str):
-                try:
+            try:
+                if isinstance(type_hint, str):
                     type_hint = EnvironmentValueType[type_hint.upper()].value
-                except KeyError:
-                    raise OrionisEnvironmentValueError(
-                        f"Invalid type hint: {type_hint}. Allowed types are: {[e.value for e in EnvironmentValueType]}"
-                    )
-            elif isinstance(type_hint, EnvironmentValueType):
-                type_hint = type_hint.value
+                elif isinstance(type_hint, EnvironmentValueType):
+                    type_hint = type_hint.value
+
+            # If type_hint is not a valid EnvironmentValueType, raise an error.
+            except KeyError:
+                raise OrionisEnvironmentValueError(
+                    f"Invalid type hint: {type_hint}. Allowed types are: {[e.value for e in EnvironmentValueType]}"
+                )
 
         # If no type hint is provided, use the type of the value.
         else: