orionis 0.287.0__py3-none-any.whl → 0.289.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.289.0"
 
 # Full name of the author or maintainer of the project
 AUTHOR = "Raul Mauricio Uñate Castro"

orionis/metadata/package.py

@@ -7,38 +7,9 @@ class PypiPackageApi:
     This class initializes by retrieving package information from the PyPI JSON API for the 'orionis' package.
     It exposes various methods to access metadata such as the package name, version, author, description, license,
     classifiers, required Python version, keywords, and project URLs.
-    Attributes:
-        _baseUrl (str): The URL to the PyPI JSON API for the Orionis package.
-        _info (dict): A dictionary containing the package metadata fetched from PyPI.
-    Methods:
-        getAllData():
-            Fetches and updates the internal information dictionary with the latest data from PyPI.
-        getName():
-            Returns the CLI name by appending '-cli' to the package name.
-        getVersion():
-            Returns the version string of the framework.
-        getAuthor():
-            Returns the author's name.
-        getAuthorEmail():
-            Returns the author's email address.
-        getDescription():
-            Returns the summary description of the framework.
-        getUrl():
-            Returns the homepage URL of the project.
-        getLongDescription():
-        getDescriptionContentType():
-            Returns the content type of the long description.
-        getLicense():
-            Returns the license type, defaulting to "MIT" if not specified.
-        getClassifiers():
-            Returns a list of PyPI classifiers for the package.
-        getPythonVersion():
-            Returns the required Python version specification.
-        getKeywords():
-            Returns a list of keywords associated with the package.
     """
 
-    def __init__(self):
+    def __init__(self) -> None:
         """
         Initializes the class by setting the base URL for the Orionis PyPI package,
         initializing the information dictionary, and retrieving all package data.
@@ -47,7 +18,7 @@ class PypiPackageApi:
         self._info = {}
         self.getAllData()
 
-    def getAllData(self):
+    def getAllData(self) -> dict:
         """
         Fetches all data from the base URL and updates the internal info attribute.
 
@@ -76,16 +47,16 @@ class PypiPackageApi:
                 f"Invalid response structure from PyPI: {ve}"
             )
 
-    def getName(self):
+    def getName(self) -> str:
         """
-        Returns the CLI name by appending '-cli' to the value of the 'name' key in the _info dictionary.
+        Returns the package name from the value of the 'name' key in the _info dictionary.
 
         Returns:
-            str: The CLI name in the format '<name>-cli'.
+            str: The package name.
         """
-        return f"{self._info['name']}-cli"
+        return self._info['name']
 
-    def getVersion(self):
+    def getVersion(self) -> str:
         """
         Returns the version information of the framework.
 
@@ -94,7 +65,7 @@ class PypiPackageApi:
         """
         return self._info['version']
 
-    def getAuthor(self):
+    def getAuthor(self) -> str:
         """
         Returns the author of the framework.
 
@@ -103,7 +74,7 @@ class PypiPackageApi:
         """
         return self._info['author']
 
-    def getAuthorEmail(self):
+    def getAuthorEmail(self) -> str:
         """
         Retrieve the author's email address from the internal information dictionary.
 
@@ -112,7 +83,7 @@ class PypiPackageApi:
         """
         return self._info['author_email']
 
-    def getDescription(self):
+    def getDescription(self) -> str:
         """
         Returns the summary description from the internal information dictionary.
 
@@ -121,7 +92,7 @@ class PypiPackageApi:
         """
         return self._info['summary']
 
-    def getUrl(self):
+    def getUrl(self) -> str:
         """
         Retrieves the homepage URL from the project's information.
 
@@ -130,7 +101,7 @@ class PypiPackageApi:
         """
         return self._info['project_urls']['Homepage']
 
-    def getLongDescription(self):
+    def getLongDescription(self) -> str:
         """
         Returns the long description of the framework.
 
@@ -139,7 +110,7 @@ class PypiPackageApi:
         """
         return self._info['description']
 
-    def getDescriptionContentType(self):
+    def getDescriptionContentType(self) -> str:
         """
         Returns the content type of the description from the internal information dictionary.
 
@@ -148,7 +119,7 @@ class PypiPackageApi:
         """
         return self._info['description_content_type']
 
-    def getLicense(self):
+    def getLicense(self) -> str:
         """
         Returns the license type specified in the framework information.
 
@@ -159,7 +130,7 @@ class PypiPackageApi:
         """
         return self._info['license'] or "MIT"
 
-    def getClassifiers(self):
+    def getClassifiers(self) -> list:
         """
         Returns the list of classifiers from the internal _info dictionary.
 
@@ -168,7 +139,7 @@ class PypiPackageApi:
         """
         return self._info['classifiers']
 
-    def getPythonVersion(self):
+    def getPythonVersion(self) -> str:
         """
         Retrieves the required Python version for the framework.
 
@@ -177,7 +148,7 @@ class PypiPackageApi:
         """
         return self._info['requires_python']
 
-    def getKeywords(self):
+    def getKeywords(self) -> list:
         """
         Retrieve the list of keywords associated with the current object.
 

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]}"