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

orionis/services/environment/dynamic/caster.py

@@ -1,4 +1,3 @@
-
 from typing import Any
 from orionis.services.environment.contracts.caster import IEnvironmentCaster
 from orionis.services.environment.enums.value_type import EnvironmentValueType
@@ -12,12 +11,12 @@ class EnvironmentCaster(IEnvironmentCaster):
     @staticmethod
     def options() -> set:
         """
-        Returns the set of valid type hints that can be used with this Type class.
+        Get the set of valid type hints supported by this class.
 
         Returns
         -------
         set
-            A set containing the valid type hints.
+            Set of valid type hint strings that can be used for environment value casting.
         """
         return EnvironmentCaster.OPTIONS
 
@@ -26,15 +25,16 @@ class EnvironmentCaster(IEnvironmentCaster):
         raw: str | Any
     ) -> None:
         """
-        Initializes an EnvTypes instance by parsing a raw input into a type hint and value.
+        Parse the input `raw` to extract a type hint and value for environment variable casting.
 
         Parameters
         ----------
         raw : str or Any
-            The input to be parsed. If a string, it may contain a type hint and value separated by a colon
-            (e.g., "int: 42"). If a colon is present, the part before the colon is treated as the type hint
-            and the part after as the value. If no colon is present, the entire string is treated as the value
-            with no type hint. If not a string, the input is treated as the value with no type hint.
+            The input value to be parsed. If a string, it may contain a type hint and value
+            separated by a colon (e.g., "int: 42"). If a colon is present, the part before
+            the colon is treated as the type hint and the part after as the value. If no colon
+            is present, the entire string is treated as the value with no type hint. If not a
+            string, the input is treated as the value with no type hint.
 
         Attributes
         ----------
@@ -43,22 +43,25 @@ class EnvironmentCaster(IEnvironmentCaster):
         __value_raw : str or Any
             The extracted value string if input is a string, or the raw value otherwise.
 
-        Returns
-        -------
-        None
-            This constructor does not return a value. It initializes the instance attributes.
+        Notes
+        -----
+        This constructor does not return a value. It initializes the instance attributes
+        for type hint and raw value, which are used for subsequent type casting operations.
         """
+
         # Initialize type hint and value to default None
         self.__type_hint: str = None
         self.__value_raw: str | Any = None
 
         # If the input is a string, attempt to parse type hint and value
         if isinstance(raw, str):
+
             # Remove leading whitespace from the input
             self.__value_raw = raw.lstrip()
 
             # Check if the string contains a colon, indicating a type hint
             if ':' in self.__value_raw:
+
                 # Split at the first colon to separate type hint and value
                 type_hint, value_str = raw.split(':', 1)
 
@@ -68,30 +71,32 @@ class EnvironmentCaster(IEnvironmentCaster):
                     # Remove leading whitespace from the value part
                     self.__value_raw = value_str.lstrip() if value_str else None
         else:
+
             # If input is not a string, treat it as the value with no type hint
             self.__value_raw = raw
 
     def get(self):
         """
-        Retrieves the value processed according to the specified type hint.
+        Returns the processed value based on the specified type hint.
 
-        This method checks if a valid type hint is present and dispatches the call to the
-        corresponding internal parsing method for that type. Supported type hints include:
-        'path', 'str', 'int', 'float', 'bool', 'list', 'dict', 'tuple', and 'set'.
+        If a valid type hint is present, this method dispatches to the corresponding
+        internal parsing method for that type. Supported type hints include: 'path',
+        'str', 'int', 'float', 'bool', 'list', 'dict', 'tuple', 'set', and 'base64'.
         If no type hint is set, the raw value is returned as is.
 
         Returns
         -------
         Any
-            The value converted or processed according to the specified type hint. If no type hint
-            is set, returns the raw value.
+            The value converted or processed according to the specified type hint.
+            If no type hint is set, returns the raw value.
 
         Raises
         ------
         OrionisEnvironmentValueError
-            If the type hint is not one of the supported options.
+            If an error occurs during type conversion or processing.
         """
 
+        # Attempt to process the value based on the type hint
         try:
 
             # If a type hint is set, dispatch to the appropriate parsing method
@@ -138,6 +143,7 @@ class EnvironmentCaster(IEnvironmentCaster):
                     return self.__parseBase64()
 
             else:
+
                 # If no type hint is set, return the raw value
                 return self.__value_raw
 
@@ -155,30 +161,31 @@ class EnvironmentCaster(IEnvironmentCaster):
 
     def to(self, type_hint: str | EnvironmentValueType) -> Any:
         """
-        Converts the internal value to the specified type and returns its string representation with the type hint prefix.
-
-        This method sets the type hint for the instance and attempts to convert the internal value to the specified type.
-        The type hint must be one of the valid options defined in `OPTIONS`. If the conversion is successful, a string
-        representation of the value prefixed with the type hint is returned. If the type hint is invalid or the conversion
-        fails, an exception is raised.
+        Convert the internal value to the specified type and return its string representation
+        with the type hint prefix.
 
         Parameters
         ----------
         type_hint : str or EnvironmentValueType
-            The type hint to set. Can be a string or an `EnvironmentValueType` enum member. Must be one of the valid options.
+            The type to which the internal value should be converted. Can be a string or an
+            EnvironmentValueType enum member. Must be one of the valid options in `OPTIONS`.
 
         Returns
         -------
         Any
-            The string representation of the value with the type hint prefix, according to the specified type.
-            For example, "int:42", "list:[1, 2, 3]", etc.
+            The string representation of the value with the type hint prefix, according to the
+            specified type. For example, "int:42", "list:[1, 2, 3]", etc.
 
         Raises
         ------
         OrionisEnvironmentValueError
-            If the provided type hint is not valid or if the value cannot be converted to the specified type.
+            If the provided type hint is not valid or if the value cannot be converted to the
+            specified type.
         """
+
+        # Validate the type hint and ensure it is one of the defined options
         try:
+
             # If type_hint is an enum, convert it to its value string
             if isinstance(type_hint, EnvironmentValueType):
                 type_hint = type_hint.value
@@ -195,30 +202,50 @@ class EnvironmentCaster(IEnvironmentCaster):
             # Dispatch to the appropriate conversion method based on the type hint
             if self.__type_hint == EnvironmentValueType.PATH.value:
                 return self.__toPath()
+
+            # If the type hint is 'str', convert to string
             if self.__type_hint == EnvironmentValueType.STR.value:
                 return self.__toStr()
+
+            # If the type hint is 'int', convert to integer
             if self.__type_hint == EnvironmentValueType.INT.value:
                 return self.__toInt()
+
+            # If the type hint is 'float', convert to float
             if self.__type_hint == EnvironmentValueType.FLOAT.value:
                 return self.__toFloat()
+
+            # If the type hint is 'bool', convert to boolean
             if self.__type_hint == EnvironmentValueType.BOOL.value:
                 return self.__toBool()
+
+            # If the type hint is 'list', convert to list
             if self.__type_hint == EnvironmentValueType.LIST.value:
                 return self.__toList()
+
+            # If the type hint is 'dict', convert to dictionary
             if self.__type_hint == EnvironmentValueType.DICT.value:
                 return self.__toDict()
+
+            # If the type hint is 'tuple', convert to tuple
             if self.__type_hint == EnvironmentValueType.TUPLE.value:
                 return self.__toTuple()
+
+            # If the type hint is 'set', convert to set
             if self.__type_hint == EnvironmentValueType.SET.value:
                 return self.__toSet()
+
+            # If the type hint is 'base64', convert to Base64 encoded string
             if self.__type_hint == EnvironmentValueType.BASE64.value:
                 return self.__toBase64()
 
         except OrionisEnvironmentValueError:
+
             # Propagate specific type conversion errors
             raise
 
         except Exception as e:
+
             # Catch any other unexpected errors and wrap them in an environment value error
             raise OrionisEnvironmentValueError(
                 f"Error converting value '{self.__value_raw}' to type '{type_hint}': {str(e)}"
@@ -226,24 +253,24 @@ class EnvironmentCaster(IEnvironmentCaster):
 
     def __toBase64(self) -> str:
         """
-        Converts the internal value to a Base64 encoded string with the type hint prefix.
-
-        This method checks if the internal value is a string or bytes. If so, it encodes the value in Base64
-        and returns a string in the format "<type_hint>:<base64_value>". If the internal value is not a string
-        or bytes, an exception is raised.
+        Convert the internal value to a Base64 encoded string with the type hint prefix.
 
         Returns
         -------
         str
-            A Base64 encoded string combining the type hint and the internal value, separated by a colon.
+            A string in the format "<type_hint>:<base64_value>", where <base64_value> is the Base64
+            encoded representation of the internal value.
 
         Raises
         ------
         OrionisEnvironmentValueError
             If the internal value is not a string or bytes.
         """
+
+        # Import the base64 module for encoding
         import base64
 
+        # Ensure the internal value is a string or bytes before encoding
         if not isinstance(self.__value_raw, (str, bytes)):
             raise OrionisEnvironmentValueError(
                 f"Value must be a string or bytes to convert to Base64, got {type(self.__value_raw).__name__} instead."
@@ -257,141 +284,147 @@ class EnvironmentCaster(IEnvironmentCaster):
 
     def __parseBase64(self) -> str:
         """
-        Decodes the Base64 encoded value, assuming the type hint is 'base64:'.
+        Decode the internal raw value from Base64 encoding.
 
-        This method decodes the internal raw value from Base64 and returns it as a string.
-        If the value cannot be decoded, an `OrionisEnvironmentValueException` is raised.
+        Decodes the Base64-encoded string stored in the internal raw value and returns the decoded result as a string.
+        If decoding fails, raises an OrionisEnvironmentValueException.
 
         Returns
         -------
         str
-            The decoded Base64 value as a string.
+            The decoded string from the Base64-encoded internal value.
 
         Raises
         ------
         OrionisEnvironmentValueException
-            If the value cannot be decoded from Base64.
+            If the internal value cannot be decoded from Base64.
         """
+
+        # Import the base64 module for decoding
         import base64
 
         try:
-            # Decode the Base64 encoded value
+
+            # Decode the Base64 encoded value and return as string
             decoded_value = base64.b64decode(self.__value_raw).decode()
             return decoded_value
+
         except Exception as e:
+
+            # Raise a custom exception if decoding fails
             raise OrionisEnvironmentValueException(f"Cannot decode Base64 value '{self.__value_raw}': {str(e)}")
 
     def __parsePath(self):
         """
-        Converts the internal raw value to a `Path` object, assuming the type hint is 'path:'.
-
-        This method processes the internal value as a file system path. It replaces backslashes
-        with forward slashes for normalization and returns a `Path` object representing the path.
+        Convert the internal raw value to a normalized POSIX path string.
 
-        Parameters
-        ----------
-        self : EnvironmentCaster
-            The instance of the EnvironmentCaster class.
+        This method processes the internal value as a file system path. If the value is already
+        a `Path` object, it returns its POSIX representation. If the value is a string, it replaces
+        backslashes with forward slashes for normalization and returns the POSIX path string.
 
         Returns
         -------
-        pathlib.Path
-            A `Path` object representing the normalized file system path.
+        str
+            The normalized POSIX path string representing the file system path.
 
         Raises
         ------
         OrionisEnvironmentValueException
             If the value cannot be processed as a valid path.
         """
+
+        # Import the Path class from pathlib for path manipulation
         from pathlib import Path
 
-        # If the value is already a Path object, return it directly
+        # If the value is already a Path object, return its POSIX representation
         if isinstance(self.__value_raw, Path):
             return self.__value_raw.as_posix()
 
         # Normalize the path by replacing backslashes with forward slashes
         normalized_path = str(self.__value_raw).replace('\\', '/')
 
-        # Avoid redundant wrapping: if normalized_path is already absolute, just return Path(normalized_path)
+        # Convert the normalized string to a Path object and return its POSIX representation
         return Path(normalized_path).as_posix()
 
     def __toPath(self) -> str:
         """
-        Converts the internal value to an absolute path string.
+        Convert the internal value to an absolute POSIX path string with type hint prefix.
 
         Returns
         -------
         str
-            A string representing the type hint and the absolute path value.
+            A string in the format "<type_hint>:<absolute_path>", where <absolute_path> is the
+            normalized, absolute POSIX path representation of the internal value.
 
         Raises
         ------
         OrionisEnvironmentValueError
-            If the internal value is not a string or Path.
+            If the internal value is not a string or a pathlib.Path object.
         """
+
+        # Import the Path class from pathlib for path manipulation
         from pathlib import Path
-        import os
 
+        # Ensure the internal value is a string or Path object
         if not isinstance(self.__value_raw, (str, Path)):
             raise OrionisEnvironmentValueError(
-            f"Value must be a string or Path to convert to path, got {type(self.__value_raw).__name__} instead."
+                f"Value must be a string or Path to convert to path, got {type(self.__value_raw).__name__} instead."
             )
 
-        # Normalize slashes and strip whitespace
+        # Normalize slashes and strip whitespace from the path string
         raw_path = str(self.__value_raw).replace('\\', '/').strip()
 
-        # If the path is relative, resolve it from the current working directory
+        # Create a Path object from the normalized path string
         path_obj = Path(raw_path)
 
-        # If the path is not absolute, make it absolute by combining with the current working directory
+        # If the path is not absolute, resolve it relative to the current working directory
         if not path_obj.is_absolute():
 
-            # Remove leading slash if present to avoid absolute path when joining
+            # Remove any leading slash to avoid creating an absolute path when joining
             raw_path_no_leading = raw_path.lstrip('/\\')
+
+            # Combine with the current working directory to form an absolute path
             path_obj = Path(Path.cwd()) / raw_path_no_leading
 
-        # Resolve the path to get the absolute path
+        # Expand user home and convert to POSIX format for consistency
         abs_path = path_obj.expanduser().as_posix()
 
-        # Return the absolute path as a string with the type hint
+        # Return the absolute path as a string with the type hint prefix
         return f"{self.__type_hint}:{str(abs_path)}"
 
     def __parseStr(self):
         """
-        Returns the value as a string, assuming the type hint is 'str:'.
+        Returns the internal raw value as a string, removing leading whitespace.
 
-        This method processes the internal raw value and returns it as a string,
-        provided the type hint is 'str:'. Leading whitespace is removed from the value
-        before returning. No type conversion is performed; the value is returned as-is
-        after stripping leading whitespace.
+        Parameters
+        ----------
+        self : EnvironmentCaster
+            Instance of the EnvironmentCaster class.
 
         Returns
         -------
         str
             The internal value as a string with leading whitespace removed.
 
-        Raises
-        ------
-        None
-            This method does not raise any exceptions.
+        Notes
+        -----
+        No type conversion is performed; the value is returned as a string after
+        stripping leading whitespace. This method assumes the type hint is 'str:'.
+        No exceptions are raised by this method.
         """
 
-        # Return the internal value as a string, removing leading whitespace
+        # Remove leading whitespace from the internal value
+        # This ensures that any accidental spaces before the value are ignored
         return self.__value_raw.lstrip()
 
     def __toStr(self):
         """
-        Converts the internal value to a string representation with the type hint prefix.
-
-        This method checks if the internal value is a string. If so, it returns a string
-        in the format "<type_hint>:<value>", where <type_hint> is the current type hint
-        and <value> is the internal string value. If the internal value is not a string,
-        an exception is raised.
+        Returns the internal value as a string representation with the type hint prefix.
 
         Returns
         -------
         str
-            A string combining the type hint and the internal value, separated by a colon.
+            The string representation of the internal value, prefixed by the type hint and separated by a colon.
 
         Raises
         ------
@@ -401,25 +434,21 @@ class EnvironmentCaster(IEnvironmentCaster):
 
         # Ensure the internal value is a string before conversion
         if not isinstance(self.__value_raw, str):
+
+            # Raise an error if the value is not a string
             raise OrionisEnvironmentValueError(
                 f"Value must be a string to convert to str, got {type(self.__value_raw).__name__} instead."
             )
 
         # Return the formatted string with type hint and value
-        return f"{self.__value_raw}"
+        return f"{self.__type_hint}:{self.__value_raw}"
 
     def __parseInt(self):
         """
-        Converts the internal raw value to an integer, assuming the type hint is 'int:'.
-
-        This method attempts to strip leading and trailing whitespace from the internal
-        raw value and convert it to an integer. If the conversion fails due to an invalid
-        format or non-integer input, an `OrionisEnvironmentValueException` is raised.
+        Convert the internal raw value to an integer.
 
-        Parameters
-        ----------
-        self : EnvironmentCaster
-            The instance of the EnvironmentCaster class.
+        Strips leading and trailing whitespace from the internal raw value and attempts to convert it to an integer.
+        Raises an OrionisEnvironmentValueException if the conversion fails due to invalid format or type.
 
         Returns
         -------
@@ -431,13 +460,13 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueException
             If the value cannot be converted to an integer due to invalid format or type.
         """
+
         # Remove leading and trailing whitespace from the raw value
         value = self.__value_raw.strip()
 
         # Attempt to convert the value to an integer
         try:
             return int(value)
-
         # Raise a custom exception if conversion fails
         except ValueError as e:
             raise OrionisEnvironmentValueException(f"Cannot convert '{value}' to int: {str(e)}")
@@ -446,14 +475,11 @@ class EnvironmentCaster(IEnvironmentCaster):
         """
         Converts the internal value to a string representation with the integer type hint prefix.
 
-        This method checks if the internal value is an integer. If so, it returns a string
-        in the format "<type_hint>:<value>", where <type_hint> is the current type hint
-        and <value> is the integer value. If the internal value is not an integer, an exception is raised.
-
         Returns
         -------
         str
-            A string combining the type hint and the internal integer value, separated by a colon.
+            String in the format "<type_hint>:<value>", where <type_hint> is the current type hint
+            and <value> is the integer value.
 
         Raises
         ------
@@ -461,8 +487,10 @@ class EnvironmentCaster(IEnvironmentCaster):
             If the internal value is not an integer.
         """
 
-        # Ensure the internal value is an integer before conversion
+        # Check if the internal value is an integer before conversion
         if not isinstance(self.__value_raw, int):
+
+            # Raise an error if the value is not an integer
             raise OrionisEnvironmentValueError(
                 f"Value must be an integer to convert to int, got {type(self.__value_raw).__name__} instead."
             )
@@ -472,16 +500,10 @@ class EnvironmentCaster(IEnvironmentCaster):
 
     def __parseFloat(self):
         """
-        Converts the internal raw value to a float, assuming the type hint is 'float:'.
+        Convert the internal raw value to a float.
 
-        This method attempts to strip leading and trailing whitespace from the internal
-        raw value and convert it to a float. If the conversion fails due to an invalid
-        format or non-numeric input, an `OrionisEnvironmentValueException` is raised.
-
-        Parameters
-        ----------
-        self : EnvironmentCaster
-            The instance of the EnvironmentCaster class.
+        Strips leading and trailing whitespace from the internal raw value and attempts to convert it to a float.
+        Raises an OrionisEnvironmentValueException if the conversion fails due to invalid format or type.
 
         Returns
         -------
@@ -493,7 +515,8 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueException
             If the value cannot be converted to a float due to invalid format or type.
         """
-        # Remove leading and trailing whitespace from the raw value
+
+        # Remove leading and trailing whitespace from the raw value to ensure clean input
         value = self.__value_raw.strip()
 
         # Attempt to convert the value to a float
@@ -508,15 +531,11 @@ class EnvironmentCaster(IEnvironmentCaster):
         """
         Converts the internal value to a string representation with the float type hint prefix.
 
-        This method checks if the internal value is a float. If so, it returns a string
-        in the format "<type_hint>:<value>", where <type_hint> is the current type hint
-        and <value> is the float value. If the internal value is not a float, an exception is raised.
-
         Returns
         -------
         str
-            A string combining the type hint and the internal float value, separated by a colon.
-            For example, "float:3.14".
+            A string in the format "<type_hint>:<value>", where <type_hint> is the current type hint
+            and <value> is the float value.
 
         Raises
         ------
@@ -526,6 +545,8 @@ class EnvironmentCaster(IEnvironmentCaster):
 
         # Ensure the internal value is a float before conversion
         if not isinstance(self.__value_raw, float):
+
+            # Raise an error if the value is not a float
             raise OrionisEnvironmentValueError(
                 f"Value must be a float to convert to float, got {type(self.__value_raw).__name__} instead."
             )
@@ -535,23 +556,17 @@ class EnvironmentCaster(IEnvironmentCaster):
 
     def __parseBool(self):
         """
-        Converts the internal raw value to a boolean, assuming the type hint is 'bool:'.
-
-        This method processes the internal raw value by stripping leading and trailing whitespace,
-        converting it to lowercase, and then checking if it matches the string 'true' or 'false'.
-        If the value is 'true', it returns the boolean value True. If the value is 'false', it returns
-        the boolean value False. If the value does not match either, an `OrionisEnvironmentValueException`
-        is raised.
+        Convert the internal raw value to a boolean.
 
-        Parameters
-        ----------
-        self : EnvironmentCaster
-            The instance of the EnvironmentCaster class.
+        This method strips leading and trailing whitespace from the internal raw value,
+        converts it to lowercase, and checks if it matches 'true' or 'false'. If the value
+        is 'true', it returns True. If the value is 'false', it returns False. If the value
+        does not match either, an OrionisEnvironmentValueException is raised.
 
         Returns
         -------
         bool
-            Returns True if the value is 'true' (case-insensitive), False if the value is 'false' (case-insensitive).
+            True if the value is 'true' (case-insensitive), False if the value is 'false' (case-insensitive).
 
         Raises
         ------
@@ -559,35 +574,30 @@ class EnvironmentCaster(IEnvironmentCaster):
             If the value cannot be converted to a boolean because it does not match 'true' or 'false'.
         """
 
-        # Strip whitespace and convert the value to lowercase for comparison
+        # Remove leading and trailing whitespace, then convert to lowercase for comparison
         value = self.__value_raw.strip().lower()
 
-        # Check for 'true' and return True
+        # If the value is 'true', return True
         if value == 'true':
             return True
 
-        # Check for 'false' and return False
+        # If the value is 'false', return False
         elif value == 'false':
             return False
 
-        # Raise an exception if the value cannot be interpreted as a boolean
+        # If the value is neither 'true' nor 'false', raise an exception
         else:
             raise OrionisEnvironmentValueException(f"Cannot convert '{value}' to bool.")
 
     def __toBool(self):
         """
-        Converts the internal value to a string representation with the boolean type hint prefix.
-
-        This method checks if the internal value is a boolean. If so, it returns a string
-        in the format "<type_hint>:<value>", where <type_hint> is the current type hint
-        and <value> is the lowercase string representation of the boolean value.
-        If the internal value is not a boolean, an exception is raised.
+        Convert the internal value to a string representation with the boolean type hint prefix.
 
         Returns
         -------
         str
-            A string combining the type hint and the internal boolean value, separated by a colon.
-            The boolean value is represented as 'true' or 'false' in lowercase.
+            A string in the format "<type_hint>:<value>", where <type_hint> is the current type hint
+            and <value> is the lowercase string representation of the boolean value ('true' or 'false').
 
         Raises
         ------
@@ -597,6 +607,8 @@ class EnvironmentCaster(IEnvironmentCaster):
 
         # Ensure the internal value is a boolean before conversion
         if not isinstance(self.__value_raw, bool):
+
+            # Raise an error if the value is not a boolean
             raise OrionisEnvironmentValueError(
                 f"Value must be a boolean to convert to bool, got {type(self.__value_raw).__name__} instead."
             )
@@ -606,43 +618,41 @@ class EnvironmentCaster(IEnvironmentCaster):
 
     def __parseList(self):
         """
-        Converts the internal raw value to a list, assuming the type hint is 'list:'.
+        Parses the internal raw value and converts it to a Python list.
 
-        This method attempts to strip leading and trailing whitespace from the internal
-        raw value and convert it to a Python list using `ast.literal_eval`. If the conversion
-        fails due to an invalid format or if the evaluated value is not a list, an
+        The method strips leading and trailing whitespace from the internal raw value,
+        then attempts to safely evaluate the string as a Python list using `ast.literal_eval`.
+        If the conversion is successful and the result is a list, it is returned.
+        If the conversion fails or the evaluated value is not a list, an
         `OrionisEnvironmentValueException` is raised.
 
-        Parameters
-        ----------
-        self : EnvironmentCaster
-            The instance of the EnvironmentCaster class.
-
         Returns
         -------
         list
-            The internal value converted to a list if the type hint is 'list:'.
+            The internal value converted to a list.
 
         Raises
         ------
         OrionisEnvironmentValueException
             If the value cannot be converted to a list due to invalid format or type.
         """
+
+        # Import the ast module for safe evaluation of string literals
         import ast
 
-        # Remove leading and trailing whitespace from the raw value
+        # Remove leading and trailing whitespace from the raw value to ensure clean input
         value = self.__value_raw.strip()
 
         try:
 
-            # Safely evaluate the string to a Python object
+            # Safely evaluate the string to a Python object using ast.literal_eval
             parsed = ast.literal_eval(value)
 
             # Ensure the evaluated object is a list
             if not isinstance(parsed, list):
                 raise ValueError("Value is not a list")
 
-            # Return the parsed list
+            # Return the parsed list if successful
             return parsed
 
         except (ValueError, SyntaxError) as e:
@@ -652,18 +662,18 @@ class EnvironmentCaster(IEnvironmentCaster):
 
     def __toList(self):
         """
-        Converts the internal value to a string representation with the list type hint prefix.
+        Converts the internal value to its string representation with the list type hint prefix.
 
-        This method checks if the internal value is a list. If so, it returns a string
-        in the format "<type_hint>:<value>", where <type_hint> is the current type hint
-        and <value> is the string representation of the list. If the internal value is not a list,
-        an exception is raised.
+        Parameters
+        ----------
+        self : EnvironmentCaster
+            Instance of the EnvironmentCaster class.
 
         Returns
         -------
         str
-            A string combining the type hint and the internal list value, separated by a colon.
-            For example, "list:[1, 2, 3]".
+            A string in the format "<type_hint>:<value>", where <type_hint> is the current type hint
+            and <value> is the string representation of the list.
 
         Raises
         ------
@@ -673,6 +683,8 @@ class EnvironmentCaster(IEnvironmentCaster):
 
         # Ensure the internal value is a list before conversion
         if not isinstance(self.__value_raw, list):
+
+            # Raise an error if the value is not a list
             raise OrionisEnvironmentValueError(
                 f"Value must be a list to convert to list, got {type(self.__value_raw).__name__} instead."
             )
@@ -682,43 +694,42 @@ class EnvironmentCaster(IEnvironmentCaster):
 
     def __parseDict(self):
         """
-        Converts the internal raw value to a dictionary, assuming the type hint is 'dict:'.
-
-        This method attempts to strip leading and trailing whitespace from the internal
-        raw value and safely evaluate it as a Python dictionary using `ast.literal_eval`.
-        If the conversion fails due to an invalid format or if the evaluated value is not
-        a dictionary, an `OrionisEnvironmentValueException` is raised.
+        Parses the internal raw value and converts it to a Python dictionary.
 
-        Parameters
-        ----------
-        self : EnvironmentCaster
-            The instance of the EnvironmentCaster class.
+        The method strips leading and trailing whitespace from the internal raw value,
+        then attempts to safely evaluate the string as a Python dictionary using
+        `ast.literal_eval`. If the conversion is successful and the result is a dictionary,
+        it is returned. If the conversion fails or the evaluated value is not a dictionary,
+        an OrionisEnvironmentValueException is raised.
 
         Returns
         -------
         dict
-            The internal value converted to a dictionary if the type hint is 'dict:'.
+            The internal value converted to a dictionary.
 
         Raises
         ------
         OrionisEnvironmentValueException
             If the value cannot be converted to a dictionary due to invalid format or type.
         """
+
+        # Import the ast module for safe evaluation of string literals
         import ast
 
-        # Remove leading and trailing whitespace from the raw value
+        # Remove leading and trailing whitespace from the raw value to ensure clean input
         value = self.__value_raw.strip()
 
+        # Attempt to parse the string as a dictionary
         try:
 
-            # Safely evaluate the string to a Python object
+            # Safely evaluate the string to a Python object using ast.literal_eval
             parsed = ast.literal_eval(value)
 
             # Ensure the evaluated object is a dictionary
             if not isinstance(parsed, dict):
                 raise ValueError("Value is not a dict")
 
-            # Return the parsed dictionary
+            # Return the parsed dictionary if successful
             return parsed
 
         except (ValueError, SyntaxError) as e:
@@ -730,16 +741,11 @@ class EnvironmentCaster(IEnvironmentCaster):
         """
         Converts the internal value to a string representation with the dictionary type hint prefix.
 
-        This method checks if the internal value is a dictionary. If so, it returns a string
-        in the format "<type_hint>:<value>", where <type_hint> is the current type hint
-        and <value> is the string representation of the dictionary. If the internal value is not a dictionary,
-        an exception is raised.
-
         Returns
         -------
         str
-            A string combining the type hint and the internal dictionary value, separated by a colon.
-            For example, "dict:{'key': 'value'}".
+            A string in the format "<type_hint>:<value>", where <type_hint> is the current type hint
+            and <value> is the string representation of the dictionary.
 
         Raises
         ------
@@ -749,6 +755,8 @@ class EnvironmentCaster(IEnvironmentCaster):
 
         # Ensure the internal value is a dictionary before conversion
         if not isinstance(self.__value_raw, dict):
+
+            # Raise an error if the value is not a dictionary
             raise OrionisEnvironmentValueError(
                 f"Value must be a dict to convert to dict, got {type(self.__value_raw).__name__} instead."
             )
@@ -758,44 +766,41 @@ class EnvironmentCaster(IEnvironmentCaster):
 
     def __parseTuple(self):
         """
-        Converts the internal raw value to a tuple, assuming the type hint is 'tuple:'.
+        Parse the internal raw value and convert it to a Python tuple.
 
-        This method strips leading and trailing whitespace from the internal raw value,
+        The method removes leading and trailing whitespace from the internal raw value,
         then attempts to safely evaluate the string as a Python tuple using `ast.literal_eval`.
         If the conversion is successful and the result is a tuple, it is returned.
         If the conversion fails or the evaluated value is not a tuple, an
-        `OrionisEnvironmentValueException` is raised.
-
-        Parameters
-        ----------
-        self : EnvironmentCaster
-            The instance of the EnvironmentCaster class.
+        OrionisEnvironmentValueException is raised.
 
         Returns
         -------
         tuple
-            The internal value converted to a tuple if the type hint is 'tuple:'.
+            The internal value converted to a tuple.
 
         Raises
         ------
         OrionisEnvironmentValueException
             If the value cannot be converted to a tuple due to invalid format or type.
         """
+
+        # Import the ast module for safe evaluation of string literals
         import ast
 
-        # Remove leading and trailing whitespace from the raw value
+        # Remove leading and trailing whitespace from the raw value to ensure clean input
         value = self.__value_raw.strip()
 
         try:
 
-            # Safely evaluate the string to a Python object
+            # Safely evaluate the string to a Python object using ast.literal_eval
             parsed = ast.literal_eval(value)
 
             # Ensure the evaluated object is a tuple
             if not isinstance(parsed, tuple):
                 raise ValueError("Value is not a tuple")
 
-            # Return the parsed tuple
+            # Return the parsed tuple if successful
             return parsed
 
         except (ValueError, SyntaxError) as e:
@@ -805,18 +810,13 @@ class EnvironmentCaster(IEnvironmentCaster):
 
     def __toTuple(self):
         """
-        Converts the internal value to a string representation with the tuple type hint prefix.
-
-        This method checks if the internal value is a tuple. If so, it returns a string
-        in the format "<type_hint>:<value>", where <type_hint> is the current type hint
-        and <value> is the string representation of the tuple. If the internal value is not a tuple,
-        an exception is raised.
+        Convert the internal value to a string representation with the tuple type hint prefix.
 
         Returns
         -------
         str
-            A string combining the type hint and the internal tuple value, separated by a colon.
-            For example, "tuple:(1, 2, 3)".
+            A string in the format "<type_hint>:<value>", where <type_hint> is the current type hint
+            and <value> is the string representation of the tuple.
 
         Raises
         ------
@@ -826,6 +826,8 @@ class EnvironmentCaster(IEnvironmentCaster):
 
         # Ensure the internal value is a tuple before conversion
         if not isinstance(self.__value_raw, tuple):
+
+            # Raise an error if the value is not a tuple
             raise OrionisEnvironmentValueError(
                 f"Value must be a tuple to convert to tuple, got {type(self.__value_raw).__name__} instead."
             )
@@ -835,39 +837,41 @@ class EnvironmentCaster(IEnvironmentCaster):
 
     def __parseSet(self):
         """
-        Converts the internal raw value to a set, assuming the type hint is 'set:'.
+        Parse the internal raw value and convert it to a Python set.
 
-        This method strips leading and trailing whitespace from the internal raw value,
+        This method removes leading and trailing whitespace from the internal raw value,
         then attempts to safely evaluate the string as a Python set using `ast.literal_eval`.
         If the conversion is successful and the result is a set, it is returned.
         If the conversion fails or the evaluated value is not a set, an
-        `OrionisEnvironmentValueException` is raised.
+        OrionisEnvironmentValueException is raised.
 
         Returns
         -------
         set
-            The internal value converted to a set if the type hint is 'set:'.
+            The internal value converted to a set.
 
         Raises
         ------
         OrionisEnvironmentValueException
             If the value cannot be converted to a set due to invalid format or type.
         """
+
+        # Import the ast module for safe evaluation of string literals
         import ast
 
-        # Remove leading and trailing whitespace from the raw value
+        # Remove leading and trailing whitespace from the raw value to ensure clean input
         value = self.__value_raw.strip()
 
         try:
 
-            # Safely evaluate the string to a Python object
+            # Safely evaluate the string to a Python object using ast.literal_eval
             parsed = ast.literal_eval(value)
 
             # Ensure the evaluated object is a set
             if not isinstance(parsed, set):
                 raise ValueError("Value is not a set")
 
-            # Return the parsed set
+            # Return the parsed set if successful
             return parsed
 
         except (ValueError, SyntaxError) as e:
@@ -877,18 +881,13 @@ class EnvironmentCaster(IEnvironmentCaster):
 
     def __toSet(self):
         """
-        Converts the internal value to a string representation with the set type hint prefix.
-
-        This method checks if the internal value is a set. If so, it returns a string
-        in the format "<type_hint>:<value>", where <type_hint> is the current type hint
-        and <value> is the string representation of the set. If the internal value is not a set,
-        an exception is raised.
+        Convert the internal value to a string representation with the set type hint prefix.
 
         Returns
         -------
         str
-            A string combining the type hint and the internal set value, separated by a colon.
-            For example, "set:{1, 2, 3}".
+            A string in the format "<type_hint>:<value>", where <type_hint> is the current type hint
+            and <value> is the string representation of the set.
 
         Raises
         ------
@@ -898,8 +897,9 @@ class EnvironmentCaster(IEnvironmentCaster):
 
         # Ensure the internal value is a set before conversion
         if not isinstance(self.__value_raw, set):
+            # Raise an error if the value is not a set
             raise OrionisEnvironmentValueError(
-                f"Value must be a set to convert to set, got {type(self.__value_raw).__name__} instead."
+            f"Value must be a set to convert to set, got {type(self.__value_raw).__name__} instead."
             )
 
         # Return the formatted string with type hint and set value