orionis.environment.dynamic.caster.EnvironmentCaster

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class EnvironmentCaster(IEnvironmentCaster): (source)

Constructor: EnvironmentCaster(raw)

View In Hierarchy

Undocumented

Static Method	`parseTyped`	Parse a typed string (e.g. 'int:42') without full object construction.
Static Method	`supportedTypes`	Return the set of valid type hints supported by this class.
Method	`__init__`	Initialize the caster by parsing input to extract type hint and value.
Method	`__parseBase64`	Decode the internal raw value from Base64 encoding.
Method	`__parseBool`	Convert the internal raw value to a boolean.
Method	`__parseDict`	Parse the internal raw value and convert it to a Python dictionary.
Method	`__parseFloat`	Convert the internal raw value to a float.
Method	`__parseInt`	Convert the internal raw value to an integer.
Method	`__parseList`	Parse the internal raw value and convert it to a Python list.
Method	`__parsePath`	Convert the internal raw value to a normalized POSIX path string.
Method	`__parseSet`	Parse the internal raw value and convert it to a Python set.
Method	`__parseStr`	Return the internal raw value as a string with leading whitespace removed.
Method	`__parseTuple`	Parse the internal raw value and convert it to a Python tuple.
Method	`__toBase64`	Convert internal value to Base64 encoded string with type hint prefix.
Method	`__toBool`	Convert the internal value to a boolean string with type hint prefix.
Method	`__toDict`	Convert the internal value to a string with dictionary type hint prefix.
Method	`__toFloat`	Convert the internal value to a string with the float type hint prefix.
Method	`__toInt`	Convert the internal value to a string with the integer type hint prefix.
Method	`__toList`	Convert the internal value to a string representation with list type hint.
Method	`__toPath`	Convert internal value to absolute POSIX path string with type hint prefix.
Method	`__toSet`	Convert the internal value to a string with the set type hint prefix.
Method	`__toStr`	Return the internal value as a string prefixed by the type hint.
Method	`__toTuple`	Convert the internal value to a string with the tuple type hint prefix.
Method	`get`	Return the processed value according to the type hint.
Method	`to`	Convert the internal value to the specified type and return as a string.
Constant	`OPTIONS`	Undocumented
Class Variable	`__slots__`	Undocumented
Instance Variable	`__type_hint`	Undocumented
Instance Variable	`__value_raw`	Undocumented

@staticmethod

def parseTyped(value_str: str) -> object: (source) ¶

Parse a typed string (e.g. 'int:42') without full object construction.

Provides a fast path for the common case where a string with a known type prefix must be parsed. Primitive types (int, float, bool, str) are handled inline without allocating an EnvironmentCaster instance. Complex types (list, dict, tuple, set, path, base64) fall back to full instantiation only when necessary.

Parameters
value_str:`str`	A string in the format `<type_hint>:<value>`, e.g. `int:42`.

Returns
`object`	The parsed Python value according to the embedded type hint.

Raises
`ValueError`	If the value cannot be converted to the indicated type.
`TypeError`	If the value is incompatible with the indicated type.

@staticmethod

def supportedTypes() -> frozenset[str]: (source) ¶

Return the set of valid type hints supported by this class.

Returns
`set[str]`	Set of valid type hint strings that can be used for environment value casting.

def __init__(self, raw: str | object): (source) ¶

Initialize the caster by parsing input to extract type hint and value.

Parameters
raw:`str \| object`	Input value to be parsed. If string containing a colon, the part before the colon is treated as type hint and after as value. If no colon is present, entire string is treated as value with no type hint. Non-string inputs are treated as values with no type hint.

Returns
`None`	Does not return a value; initializes instance attributes.

def __parseBase64(self) -> str | bytes: (source) ¶

Decode the internal raw value from Base64 encoding.

Returns
`str \| bytes`	The decoded value. Returns a UTF-8 string if the decoded bytes represent valid UTF-8 text, otherwise returns the raw bytes.

Raises
`ValueError`	If the internal value cannot be decoded from Base64.

def __parseBool(self) -> bool: (source) ¶

Convert the internal raw value to a boolean.

Strips leading and trailing whitespace, converts to lowercase, and checks for common boolean representations. Returns True for 'true', '1', 'yes', 'on', 'enabled'. Returns False for 'false', '0', 'no', 'off', 'disabled'. Raises ValueError if the value does not match any valid representation.

Returns
`bool`	True or False based on the value's representation.

Raises
`ValueError`	If the value cannot be converted to a boolean.

def __parseDict(self) -> dict: (source) ¶

Parse the internal raw value and convert it to a Python dictionary.

Strips leading and trailing whitespace from the internal raw value, then safely evaluates the string as a Python dictionary using ast.literal_eval. Raises an error if the conversion fails or the result is not a dictionary.

Returns
`dict`	The internal value converted to a dictionary.

Raises
`ValueError`	If the value cannot be converted to a dictionary due to invalid format or type.

def __parseFloat(self) -> float: (source) ¶

Convert the internal raw value to a float.

Strips leading and trailing whitespace from the internal raw value and attempts to convert it to a float.

Parameters
self:`EnvironmentCaster`	Instance of the EnvironmentCaster class.

Returns
`float`	The internal value converted to a float.

Raises
`ValueError`	If the value cannot be converted to a float due to invalid format or type.

def __parseInt(self) -> int: (source) ¶

Convert the internal raw value to an integer.

Strip leading and trailing whitespace from the internal raw value and attempt to convert it to an integer.

Returns
`int`	The internal value converted to an integer.

Raises
`ValueError`	If the value cannot be converted to an integer due to invalid format or type.

def __parseList(self) -> list: (source) ¶

Parse the internal raw value and convert it to a Python list.

Strips leading and trailing whitespace from the internal raw value, then safely evaluates the string as a Python list using ast.literal_eval. Raises an exception if the conversion fails or the result is not a list.

Returns
`list`	The internal value converted to a list.

Raises
`ValueError`	If the value cannot be converted to a list due to invalid format.
`SyntaxError`	If the value contains invalid Python syntax.
`TypeError`	If the evaluated value is not a list.

def __parsePath(self) -> str: (source) ¶

Convert the internal raw value to a normalized POSIX path string.

Process the internal value as a file system path. If the value is already a Path object, return its POSIX representation. If the value is a string, replace backslashes with forward slashes for normalization and return the POSIX path string.

Returns
`str`	The normalized POSIX path string representing the file system path.

Raises
`ValueError`	If the value cannot be processed as a valid path.

def __parseSet(self) -> set: (source) ¶

Parse the internal raw value and convert it to a Python set.

Remove leading and trailing whitespace from the internal raw value, then safely evaluate the string as a Python set using ast.literal_eval. Raise a TypeError if the result is not a set, or a ValueError if the conversion fails.

Returns
`set`	The internal value converted to a set.

Raises
`TypeError`	If the evaluated value is not a set.
`ValueError`	If the value cannot be converted to a set due to invalid format or type.

def __parseStr(self) -> str: (source) ¶

Return the internal raw value as a string with leading whitespace removed.

Returns
`str`	The internal value as a string with leading whitespace stripped.

def __parseTuple(self) -> tuple: (source) ¶

Parse the internal raw value and convert it to a Python tuple.

Remove leading and trailing whitespace from the internal raw value, then safely evaluate the string as a Python tuple using ast.literal_eval. Raise a ValueError if conversion fails or the result is not a tuple.

Returns
`tuple`	The internal value converted to a tuple.

Raises
`ValueError`	If the value cannot be converted to a tuple due to invalid format or type.
`TypeError`	If the evaluated value is not a tuple.

def __toBase64(self) -> str: (source) ¶

Convert internal value to Base64 encoded string with type hint prefix.

If the value is already valid Base64, it is preserved as-is. Otherwise, the value is encoded to Base64 format.

Returns
`str`	String in format "<type_hint>:<base64_value>" where base64_value is the Base64 encoded representation.

Raises
`TypeError`	If the internal value is not a string or bytes type.
`ValueError`	If there's an error during Base64 encoding/decoding operations.

def __toBool(self) -> str: (source) ¶

Convert the internal value to a boolean string with type hint prefix.

Converts the internal value to a string representation of a boolean, prefixed by the type hint. Accepts common boolean representations for string inputs.

Parameters
self:`EnvironmentCaster`	Instance of the EnvironmentCaster class.

Returns
`str`	String in the format "<type_hint>:<value>", where <value> is 'true' or 'false' in lowercase.

Raises
`ValueError`	If the internal value cannot be converted to a boolean.
`TypeError`	If the value type is not convertible to boolean.

def __toDict(self) -> str: (source) ¶

Convert the internal value to a string with dictionary type hint prefix.

Parameters
self:`EnvironmentCaster`	Instance of the EnvironmentCaster class.

Returns
`str`	String in the format "<type_hint>:<value>", where <type_hint> is the current type hint and <value> is the string representation of the dict.

Raises
`TypeError`	If the internal value is not a dictionary.

def __toFloat(self) -> str: (source) ¶

Convert the internal value to a string with the float type hint prefix.

Parameters
self:`EnvironmentCaster`	Instance of the EnvironmentCaster class.

Returns
`str`	String in the format "<type_hint>:<value>", where <type_hint> is the current type hint and <value> is the float value.

Raises
`TypeError`	If the internal value cannot be converted to a float.
`ValueError`	If the internal value cannot be converted to a float due to invalid format.

def __toInt(self) -> str: (source) ¶

Convert the internal value to a string with the integer type hint prefix.

Supports conversion from string values to integers for usability.

Returns
`str`	String in the format "<type_hint>:<value>", where <type_hint> is the current type hint and <value> is the integer value.

Raises
`ValueError`	If the internal value cannot be converted to an integer.

def __toList(self) -> str: (source) ¶

Convert the internal value to a string representation with list type hint.

Returns
`str`	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
`TypeError`	If the internal value is not a list.

def __toPath(self) -> str: (source) ¶

Convert internal value to absolute POSIX path string with type hint prefix.

Parameters
self:`EnvironmentCaster`	Instance of the EnvironmentCaster class.

Returns
`str`	String in format "<type_hint>:<absolute_path>" where absolute_path is the normalized, absolute POSIX path representation.

Raises
`TypeError`	If the internal value is not a string or pathlib.Path object.

def __toSet(self) -> str: (source) ¶

Convert the internal value to a string with the set type hint prefix.

Parameters
self:`EnvironmentCaster`	Instance of the EnvironmentCaster class.

Returns
`str`	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
`TypeError`	If the internal value is not a set.

def __toStr(self) -> str: (source) ¶

Return the internal value as a string prefixed by the type hint.

Parameters
self:`EnvironmentCaster`	Instance of the EnvironmentCaster class.

Returns
`str`	String in the format "<type_hint>:<value>", where <type_hint> is the current type hint and <value> is the string value.

Raises
`TypeError`	If the internal value is not a string.

def __toTuple(self) -> str: (source) ¶

Convert the internal value to a string with the tuple type hint prefix.

Parameters
self:`EnvironmentCaster`	Instance of the EnvironmentCaster class.

Returns
`str`	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
`TypeError`	If the internal value is not a tuple.

def get(self) -> object: (source) ¶

overrides orionis.environment.contracts.caster.IEnvironmentCaster.get

Return the processed value according to the type hint.

If a valid type hint is present, dispatch 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, return the raw value.

Parameters
self:`EnvironmentCaster`	Instance of the EnvironmentCaster class.

Returns
`object`	The value converted or processed according to the specified type hint. If no type hint is set, returns the raw value.

Raises
`ValueError`	If an error occurs during type conversion or processing.
`TypeError`	If an error occurs during type conversion or processing.

def to(self, type_hint: str | EnvironmentValueType) -> str: (source) ¶

overrides orionis.environment.contracts.caster.IEnvironmentCaster.to

Convert the internal value to the specified type and return as a string.

Parameters
type_hint:`str or EnvironmentValueType`	The type to which the internal value should be converted. Must be a valid option in `OPTIONS`.

Returns
`str`	String representation of the value with the type hint prefix, e.g., int:42, list:[1, 2, 3], etc.

Raises
`ValueError`	If the provided type hint is invalid or conversion fails.

OPTIONS: ClassVar[frozenset[str]] = (source) ¶

Undocumented

Value

frozenset((e.value for e in EnvironmentValueType))

__slots__: tuple[str, ...] = (source) ¶

overrides orionis.environment.contracts.caster.IEnvironmentCaster.__slots__

Undocumented

__type_hint: str | None = (source) ¶

Undocumented

__value_raw: str | Any = (source) ¶

Undocumented