orionis 0.253.0__py3-none-any.whl → 0.266.0__py3-none-any.whl

orionis/luminate/services/environment/dot_env.py

@@ -1,9 +1,10 @@
-import ast
 import os
+import ast
+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.luminate.patterns.singleton import Singleton
+from orionis.luminate.patterns.singleton.meta_class import Singleton
 
 class DotEnv(metaclass=Singleton):
     """
@@ -14,6 +15,8 @@ class DotEnv(metaclass=Singleton):
     environment variables and vice versa.
     """
 
+    _lock = threading.RLock()
+
     def __init__(self, path: str = None) -> None:
         """
         Initializes the environment service by resolving the path to the `.env` file, ensuring its existence,
@@ -25,268 +28,189 @@ class DotEnv(metaclass=Singleton):
             OSError: If the `.env` file cannot be created when it does not exist.
         """
 
-        # Path to the `.env` file - If no path is provided, use the default path
-        if path:
-            self._resolved_path = Path(path).expanduser().resolve()
-        else:
-            self._resolved_path = Path(os.getcwd()) / ".env"
+        with self._lock:
+            if path:
+                self._resolved_path = Path(path).expanduser().resolve()
+            else:
+                self._resolved_path = Path(os.getcwd()) / ".env"
 
-        # Ensure that the `.env` file exists
-        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
-        load_dotenv(self._resolved_path)
+            load_dotenv(self._resolved_path)
 
-    def destroy(self) -> bool:
-        """
-        Deletes the `.env` file at the resolved path.
-        Returns:
-            bool: True if the `.env` file was successfully deleted, False if the file did not exist.
+    def get(self, key: str, default: Optional[Any] = None) -> Any:
         """
+        Retrieve the value of an environment variable by key.
 
-        # Deletes the `.env` file and returns True if it was successfully deleted.
-        if self._resolved_path.exists():
-            os.remove(self._resolved_path)
-            return True
-        return False
+        This method first attempts to fetch the value from the dotenv file specified by
+        `self._resolved_path`. If the key is not found in the dotenv file, it falls back
+        to the system environment variables. If the key is not found in either location,
+        the provided `default` value is returned.
+
+        The returned value is parsed using the internal `__parseValue` method if found.
 
-    def get(self, key: str, default: Optional[Any] = None) -> Any:
-        """
-        Retrieve the value of an environment variable.
-        This method attempts to fetch the value of the specified environment variable `key`
-        from a `.env` file. If the variable is not found in the `.env` file, it falls back
-        to the system environment variables. If the variable is still not found, the provided
-        `default` value is returned.
         Args:
             key (str): The name of the environment variable to retrieve.
-            default (Optional[Any], optional): The value to return if the environment variable is not found. Defaults to None.
+            default (Optional[Any], optional): The value to return if the key is not found.
+                Defaults to None.
+
         Returns:
-            Any: The value of the environment variable, parsed if found; otherwise, the `default` value.
+            Any: The parsed value of the environment variable, or the default if not found.
         """
-
-        # Gets the value of an environment variable from the `.env` file or from system environment variables.
-        value = dotenv_values(self._resolved_path).get(key)
-        if value is None:
-            value = os.getenv(key)
-
-        # If the value is not found, return the default value
-        return self.__parseValue(value) if value is not None else default
+        with self._lock:
+            value = dotenv_values(self._resolved_path).get(key)
+            if value is None:
+                value = os.getenv(key)
+            return self.__parseValue(value) if value is not None else default
 
     def set(self, key: str, value: Union[str, int, float, bool, list, dict]) -> bool:
         """
-        Sets the value of an environment variable in both the `.env` file and the current system environment.
-        Args:
-            key (str): The name of the environment variable to set.
-            value (Union[str, int, float, bool, list, dict]): The value to assign to the environment variable.
-                The value will be serialized before being written to the `.env` file.
-        Notes:
-            - The value is serialized for storage in the `.env` file.
-            - The environment variable is also set in the current process's environment, making it immediately available.
-        """
-
-        # Serializes and sets the value of an environment variable in the `.env` file.
-        serialized_value = self.__serializeValue(value)
+        Sets an environment variable with the specified key and value.
 
-        # Sets the value in the `.env` file
-        set_key(str(self._resolved_path), key, serialized_value)
+        This method serializes the given value and updates both the .env file and the current process's environment variables.
 
-        # Also sets the value in the system environment variables
-        # so that it is available in the current environment.
-        # This is useful if you need to access the environment variable immediately
-        os.environ[key] = str(value)
+        Args:
+            key (str): The name of the environment variable to set.
+            value (Union[str, int, float, bool, list, dict]): The value to assign to the environment variable. Supported types include string, integer, float, boolean, list, and dictionary.
 
-        # Return True to indicate that the operation was successful
-        return True
+        Returns:
+            bool: True if the environment variable was successfully set.
+        """
+        with self._lock:
+            serialized_value = self.__serializeValue(value)
+            set_key(str(self._resolved_path), key, serialized_value)
+            os.environ[key] = str(value)
+            return True
 
     def unset(self, key: str) -> bool:
         """
-        Removes an environment variable from both the `.env` file and the current system environment.
-        Args:
-            key (str): The name of the environment variable to remove.
-        This method updates the `.env` file by removing the specified key and also ensures
-        that the variable is no longer present in the current process's environment variables.
-        """
-
-        # Removes an environment variable from the `.env` file and from the system environment.
-        unset_key(str(self._resolved_path), key)
+        Removes the specified environment variable from both the .env file and the current process environment.
 
-        # Also removes the environment variable from the system
-        # so that it is not available in the current environment.
-        os.environ.pop(key, None)
+        Args:
+            key (str): The name of the environment variable to unset.
 
-        # Return True to indicate that the operation was successful
-        return True
+        Returns:
+            bool: True if the operation was successful.
+        """
+        with self._lock:
+            unset_key(str(self._resolved_path), key)
+            os.environ.pop(key, None)
+            return True
 
     def all(self) -> dict:
         """
-        Returns all environment variables from the `.env` file as a dictionary.
-
-        Reads the environment variables from the resolved `.env` file path, parses each value
-        using the `__parseValue` method, and returns a dictionary mapping variable names to their
-        parsed values.
+        Retrieves all environment variables from the resolved .env file.
 
         Returns:
-            dict: A dictionary containing all environment variables and their parsed values.
+            dict: A dictionary containing all environment variable key-value pairs,
+                  with values parsed using the internal __parseValue method.
         """
-
-        # Returns all environment variables from the `.env` file as a dictionary,
-        # parsing the values using __parseValue.
-        raw_values = dotenv_values(self._resolved_path)
-        return {k: self.__parseValue(v) for k, v in raw_values.items()}
+        with self._lock:
+            raw_values = dotenv_values(self._resolved_path)
+            return {k: self.__parseValue(v) for k, v in raw_values.items()}
 
     def toJson(self) -> str:
         """
-        Converts the environment variables from the `.env` file into a JSON string.
-
-        This method retrieves all environment variables, parses their values using the
-        `__parseValue` method, and returns a JSON string representation of the resulting dictionary.
+        Serializes all environment variables managed by this instance to a JSON-formatted string.
 
         Returns:
-            str: A JSON string representing all environment variables and their parsed values.
+            str: A JSON string representation of all environment variables, formatted with indentation for readability.
         """
-
-        # Converts the environment variables to a JSON string.
         import json
-        return json.dumps(self.all(), indent=4)
+        with self._lock:
+            return json.dumps(self.all(), indent=4)
 
     def toBase64(self) -> str:
         """
-        Converts the environment variables from the `.env` file into a Base64 encoded string.
-
-        This method retrieves all environment variables, parses their values using the
-        `__parseValue` method, and returns a Base64 encoded string representation of the resulting dictionary.
+        Serializes all environment variables to a JSON string and encodes it in Base64.
 
         Returns:
-            str: A Base64 encoded string representing all environment variables and their parsed values.
+            str: A Base64-encoded string representation of all environment variables.
         """
-
-        # Converts the environment variables to a Base64 encoded string.
         import base64
         import json
-        return base64.b64encode(json.dumps(self.all()).encode()).decode()
+        with self._lock:
+            return base64.b64encode(json.dumps(self.all()).encode()).decode()
 
     def __parseValue(self, value: Any) -> Any:
         """
-        Parses a given value and attempts to convert it into an appropriate Python data type.
-        The function handles the following conversions:
-            - Returns None for None, empty strings, or string representations of null values ('none', 'null', 'nan').
-            - Returns the value unchanged if it is already a primitive type (bool, int, float).
-            - Converts string representations of booleans ('true', 'false') to their respective boolean values.
-            - Converts string representations of integers and floats to their respective numeric types.
-            - Attempts to evaluate the string as a Python literal (e.g., lists, dicts, tuples).
-            - Returns the original string if no conversion is possible.
+        Parses and converts the input value to an appropriate Python data type.
+
         Args:
-            value (Any): The value to parse.
+            value (Any): The value to parse and convert.
+
         Returns:
-            Any: The parsed value in its appropriate Python data type, or the original string if no conversion is possible.
+            Any: The parsed value, which may be of type None, bool, int, float, or the original string.
+                - Returns None for None, empty strings, or strings like 'none', 'null', 'nan' (case-insensitive).
+                - Returns a boolean for 'true'/'false' strings (case-insensitive).
+                - Returns an int if the string represents an integer.
+                - Returns a float if the string represents a float.
+                - Attempts to evaluate the string as a Python literal (e.g., list, dict, tuple).
+                - Returns the original string if no conversion is possible.
         """
-
-        # Parses a string value into a Python data type.
         if value is None:
             return None
-
-        # If it is already a primitive type, return it
         if isinstance(value, (bool, int, float)):
             return value
-
         value_str = str(value).strip()
-
-        # Special cases: empty or representations of None
         if not value_str or value_str.lower() in {'none', 'null', 'nan'}:
             return None
-
-        # Booleans
         if value_str.lower() == 'true':
             return True
         if value_str.lower() == 'false':
             return False
-
-        # Try to convert to int
         try:
             if value_str.isdigit() or (value_str.startswith('-') and value_str[1:].isdigit()):
                 return int(value_str)
         except Exception:
             pass
-
-        # Try to convert to float
         try:
             float_val = float(value_str)
-            # Avoid converting strings like '1e10' to float if it is not really a number
             if '.' in value_str or 'e' in value_str.lower():
                 return float_val
         except Exception:
             pass
-
-        # Try to evaluate as Python literal (lists, dicts, etc.)
         try:
             return ast.literal_eval(value_str)
         except Exception:
             pass
-
-        # If all else fails, return the original string
         return value_str
 
     def __serializeValue(self, value: Any) -> str:
         """
-        Serializes a Python value into a string suitable for storing in a `.env` file.
-        Supported types:
-            - None: serialized as the string "None"
-            - str: returned as-is
-            - bool: converted to "true" or "false"
-            - int, float: converted to their string representation
-            - list, dict: converted to their string representation using repr()
-        Raises:
-            TypeError: If the value is an instance of a custom class or an unsupported type (e.g., set, tuple).
-        Args:
-            value (Any): The value to serialize.
+        Serializes a given value to a string suitable for storage in a .env file.
+
+        Parameters:
+            value (Any): The value to serialize. Supported types are None, str, bool, int, float, list, and dict.
+
         Returns:
             str: The serialized string representation of the value.
-        """
 
-        # if it is None, return "None"
-        # This is useful to avoid problems when saving None in the .env file
+        Raises:
+            ValueError: If a float value is in scientific notation.
+            TypeError: If the value's type is not serializable for .env files.
+        """
         if value is None:
             return "None"
-
-        # If it is a string, return it as is
         if isinstance(value, str):
             return value
-
-        # If it is a boolean, convert it to string
         if isinstance(value, bool):
             return str(value).lower()
-
-        # If it is a number, convert it to string
         if isinstance(value, int):
             return str(value)
-
-        # If is a float, convert it to string
         if isinstance(value, float):
             value = str(value)
             if 'e' in value or 'E' in value:
                 raise ValueError('scientific notation is not supported, use a string instead')
             return value
-
-        # If it is a list or dictionary, convert them to string
         if isinstance(value, (list, dict)):
             return repr(value)
-
-        # If it is an object of a custom class, raise an error
-        # This is useful to avoid problems when saving class instances in the .env file
         if hasattr(value, '__dict__'):
             raise TypeError(f"Type {type(value).__name__} is not serializable for .env")
-
-        # If it is an unsupported data type, raise an error
-        # This is useful to avoid problems when saving unsupported data types in the .env file
-        # such as sets, tuples, etc.
         if not isinstance(value, (list, dict, bool, int, float, str)):
             raise TypeError(f"Type {type(value).__name__} is not serializable for .env")
-
-        # Serializes a Python data type into a string for storing in the `.env` file.
-        # Only allows simple serializable types and not class instances.
         if isinstance(value, (list, dict, bool, int, float, str)):
-            # Prevent serializing instances of custom classes
             if type(value).__module__ != "builtins" and not isinstance(value, str):
                 raise TypeError(f"Type {type(value).__name__} is not serializable for .env")
             return repr(value) if not isinstance(value, str) else value

orionis/luminate/services/environment/env.py

@@ -51,17 +51,6 @@ class Env(IEnv):
         """
         return Env._dotenv().all()
 
-    @staticmethod
-    def destroy() -> bool:
-        """
-        Destroys the current environment by resetting the DotEnv instance.
-        """
-        if Env._dotenv_instance is not None:
-            result = Env._dotenv_instance.destroy()
-            Env._dotenv_instance = None
-            return result
-        return False
-
     @staticmethod
     def toJson() -> str:
         """

orionis/luminate/services/introspection/abstracts/entities/abstract_class_attributes.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict
+
+@dataclass(frozen=True, kw_only=True)
+class AbstractClassAttributes:
+    """
+    A class to represent the attributes of an entity.
+    """
+    public: Dict[str, Any] = field()
+    private: Dict[str, Any] = field()
+    protected: Dict[str, Any] = field()
+
+    def __post_init__(self):
+        """
+        Post-initialization method to validate attribute types.
+
+        Ensures that the 'public', 'private', and 'protected' attributes of the instance
+        are all dictionaries. Raises a TypeError if any of these attributes are not of type dict.
+
+        Raises:
+            TypeError: If 'public', 'private', or 'protected' is not a dict.
+        """
+        if not isinstance(self.public, dict):
+            raise TypeError(
+                f"Invalid type for 'public' attribute in {self.__class__.__name__}: "
+                f"expected 'dict', got '{type(self.public).__name__}'."
+            )
+        if not isinstance(self.private, dict):
+            raise TypeError(
+                f"Invalid type for 'private' attribute in {self.__class__.__name__}: "
+                f"expected 'dict', got '{type(self.private).__name__}'."
+            )
+        if not isinstance(self.protected, dict):
+            raise TypeError(
+                f"Invalid type for 'protected' attribute in {self.__class__.__name__}: "
+                f"expected 'dict', got '{type(self.protected).__name__}'."
+            )

orionis/luminate/{support → services}/introspection/abstracts/reflect_abstract.py

@@ -3,7 +3,7 @@ import ast
 import inspect
 import types
 from typing import Any, Callable, Dict, List, Optional, Set, Tuple, Type, TypeVar
-from orionis.luminate.support.introspection.abstracts.entities.abstract_class_attributes import AbstractClassAttributes
+from orionis.luminate.services.introspection.abstracts.entities.abstract_class_attributes import AbstractClassAttributes
 
 ABC = TypeVar('ABC', bound=abc.ABC)
 

orionis/luminate/{support → services}/introspection/dependencies/contracts/reflect_dependencies.py

@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
-from orionis.luminate.support.introspection.dependencies.entities.class_dependencies import ClassDependency
-from orionis.luminate.support.introspection.dependencies.entities.method_dependencies import MethodDependency
+from orionis.luminate.services.introspection.dependencies.entities.class_dependencies import ClassDependency
+from orionis.luminate.services.introspection.dependencies.entities.method_dependencies import MethodDependency
 
 class IReflectDependencies(ABC):
     """

orionis/luminate/services/introspection/dependencies/entities/class_dependencies.py

@@ -0,0 +1,41 @@
+from dataclasses import dataclass
+from typing import Any, Dict, List
+from orionis.luminate.services.introspection.dependencies.entities.resolved_dependencies import ResolvedDependency
+
+@dataclass(frozen=True, kw_only=True)
+class ClassDependency:
+    """
+    Represents the dependencies of a class, separating resolved and unresolved dependencies.
+
+    Attributes:
+        resolved (Dict[ResolvedDependency, Any]):
+            A dictionary mapping resolved dependency descriptors to their corresponding resolved instances or values.
+            All keys must be ResolvedDependency instances.
+        unresolved (List[str]):
+            A list of dependency names or identifiers that could not be resolved.
+            Must contain only strings.
+    """
+    resolved: Dict[ResolvedDependency, Any]
+    unresolved: List[str]
+
+    def __post_init__(self):
+        """
+        Validates types of attributes during initialization.
+
+        Raises:
+            TypeError: If types don't match the expected:
+                - resolved: Dict[ResolvedDependency, Any]
+                - unresolved: List[str]
+            ValueError: If resolved contains None keys or unresolved contains empty strings
+        """
+        # Validate 'resolved' is a dict with ResolvedDependency keys
+        if not isinstance(self.resolved, dict):
+            raise TypeError(
+                f"'resolved' must be a dict, got {type(self.resolved).__name__}"
+            )
+
+        # Validate 'unresolved' is a list of non-empty strings
+        if not isinstance(self.unresolved, list):
+            raise TypeError(
+                f"'unresolved' must be a list, got {type(self.unresolved).__name__}"
+            )

orionis/luminate/services/introspection/dependencies/entities/method_dependencies.py

@@ -0,0 +1,42 @@
+from dataclasses import dataclass
+from typing import Any, Dict, List
+from orionis.luminate.services.introspection.dependencies.entities.resolved_dependencies import ResolvedDependency
+
+@dataclass(frozen=True, kw_only=True)
+class MethodDependency:
+    """
+    Represents the dependencies of a method, separating resolved and unresolved dependencies.
+
+    Attributes:
+        resolved (Dict[ResolvedDependency, Any]):
+            A dictionary mapping resolved dependency descriptors to their corresponding
+            resolved instances or values for the method.
+            All keys must be ResolvedDependency instances.
+        unresolved (List[str]):
+            A list of method parameter names or dependency identifiers that could not be resolved.
+            Must contain only non-empty strings.
+    """
+    resolved: Dict[ResolvedDependency, Any]
+    unresolved: List[str]
+
+    def __post_init__(self):
+        """
+        Validates types and values of attributes during initialization.
+
+        Raises:
+            TypeError: If types don't match the expected:
+                - resolved: Dict[ResolvedDependency, Any]
+                - unresolved: List[str]
+            ValueError: If resolved contains None keys or unresolved contains empty strings
+        """
+        # Validate 'resolved' is a dict with proper key types
+        if not isinstance(self.resolved, dict):
+            raise TypeError(
+                f"'resolved' must be a dict, got {type(self.resolved).__name__}"
+            )
+
+        # Validate 'unresolved' is a list of valid parameter names
+        if not isinstance(self.unresolved, list):
+            raise TypeError(
+                f"'unresolved' must be a list, got {type(self.unresolved).__name__}"
+            )

orionis/luminate/services/introspection/dependencies/entities/resolved_dependencies.py

@@ -0,0 +1,49 @@
+from dataclasses import dataclass
+from typing import Type, Any
+
+@dataclass(frozen=True, kw_only=True)
+class ResolvedDependency:
+    """
+    Represents a fully resolved dependency with complete type information.
+
+    Attributes:
+        module_name (str):
+            The name of the module where the dependency is defined.
+            Must be a non-empty string without spaces.
+        class_name (str):
+            The name of the class/type being resolved.
+            Must be a valid Python identifier.
+        type (Type):
+            The actual Python type object of the resolved dependency.
+        full_class_path (str):
+            The full import path to the class (e.g., 'package.module.ClassName').
+            Must match 'module_name.class_name' pattern.
+    """
+    module_name: str
+    class_name: str
+    type: Type[Any]
+    full_class_path: str
+
+    def __post_init__(self):
+        """
+        Validates all fields during initialization.
+
+        Raises:
+            TypeError: If any field has incorrect type.
+            ValueError: If string fields are empty or don't meet format requirements.
+        """
+        # Validate module_name
+        if not isinstance(self.module_name, str):
+            raise TypeError(f"module_name must be str, got {type(self.module_name).__name__}")
+
+        # Validate class_name
+        if not isinstance(self.class_name, str):
+            raise TypeError(f"class_name must be str, got {type(self.class_name).__name__}")
+
+        # Validate type
+        if self.type is None:
+            raise ValueError("The 'type' field must not be None. Please provide a valid Python type object for the dependency.")
+
+        # Validate full_class_path
+        if not isinstance(self.full_class_path, str):
+            raise TypeError(f"full_class_path must be str, got {type(self.full_class_path).__name__}")

orionis/luminate/{support → services}/introspection/dependencies/reflect_dependencies.py

@@ -1,9 +1,9 @@
 import inspect
 from typing import Any, Dict, List
-from orionis.luminate.support.introspection.dependencies.contracts.reflect_dependencies import IReflectDependencies
-from orionis.luminate.support.introspection.dependencies.entities.class_dependencies import ClassDependency
-from orionis.luminate.support.introspection.dependencies.entities.method_dependencies import MethodDependency
-from orionis.luminate.support.introspection.dependencies.entities.resolved_dependencies import ResolvedDependency
+from orionis.luminate.services.introspection.dependencies.contracts.reflect_dependencies import IReflectDependencies
+from orionis.luminate.services.introspection.dependencies.entities.class_dependencies import ClassDependency
+from orionis.luminate.services.introspection.dependencies.entities.method_dependencies import MethodDependency
+from orionis.luminate.services.introspection.dependencies.entities.resolved_dependencies import ResolvedDependency
 
 class ReflectDependencies(IReflectDependencies):
     """

orionis/luminate/{support/parsers/exception_parser.py → services/parsers/exception.py}

@@ -1,6 +1,6 @@
 import traceback
 from typing import Any, Dict, List, Optional, Union
-from orionis.luminate.support.parsers.contracts.exception_parser import IExceptionParser
+from orionis.luminate.services.parsers.contracts.exception_parser import IExceptionParser
 
 class ExceptionParser(IExceptionParser):
     """

orionis/luminate/services/parsers/serializer.py

@@ -0,0 +1,15 @@
+from orionis.luminate.services.parsers.exception import ExceptionParser
+
+class Parser:
+
+    @staticmethod
+    def exception(exception: Exception) -> ExceptionParser:
+        """
+        Creates and returns an ExceptionParser instance for the given exception.
+        Args:
+            exception (Exception): The exception to be parsed.
+        Returns:
+            ExceptionParser: An instance of ExceptionParser initialized with the provided exception.
+        """
+
+        return ExceptionParser(exception)