ORIONIS API REFERENCE

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.

class documentation

class DotEnv: (source)

Constructor: DotEnv(path)

View In Hierarchy

Load and cache values from a resolved dotenv file.

Static Method __validateProcessValue Reject a serialized value that cannot enter the process environment.
Method __init__ Initialize the DotEnv service and prepare the .env file.
Method __loadValues Parse the file once and publish its validated process values.
Method __parseValue Parse a value from the .env file into its corresponding Python type.
Method __serializeValue Serialize a Python value for storage in a .env file.
Method all Return all environment variables from the resolved .env file.
Method get Retrieve the value of an environment variable.
Method reload Reload environment variables from the .env file.
Method set Set an environment variable in the .env file and process environment.
Method unset Remove an environment variable from the .env file and process environment.
Class Variable __slots__ Declare the instance attribute slots reserved by this class.
Class Variable _lock Lock to ensure thread safety during initialization and operations that modify the .env file.
Instance Variable __cache Single parsed snapshot used for file-backed values.
Instance Variable __resolved_path Resolved backing file selected by the singleton's first caller.
def __validateProcessValue(key: str, value: str): (source)

Reject a serialized value that cannot enter the process environment.

Parameters
key:strEnvironment variable name included in the Windows size limit.
value:strSerialized environment value to validate before any mutation.
Returns
NoneNo return value.
Raises
ValueErrorIf the value contains a null byte or exceeds Windows' native assignment length limit.
def __init__(self, path: str | None = None): (source)

Initialize the DotEnv service and prepare the .env file.

Parameters
path:str or None, optionalPath to the .env file. Defaults to .env in the current working directory.
Returns
NoneThis method does not return a value.
Raises
OSErrorIf the .env file cannot be created or accessed.
RuntimeErrorIf an unexpected error occurs during initialization.
def __loadValues(self) -> dict[str, str | None]: (source)

Parse the file once and publish its validated process values.

Returns
dict[str, str | None]The same resolved values used for the process and file snapshot. Entries without an assignment retain None in the snapshot.
Raises
OSErrorIf the selected file cannot be read.
ValueErrorIf decoded entries cannot be assigned to the process environment.
def __parseValue(self, value: object) -> object: (source)

Parse a value from the .env file into its corresponding Python type.

Notes

Recognizes 'none', 'null', 'nan', 'nil' (case-insensitive) as null values. Attempts to use EnvironmentCaster for advanced type parsing. Falls back to ast.literal_eval for literal evaluation. Returns the original string if all parsing attempts fail.

Parameters
value:objectThe value to parse, typically a string from the .env file or a Python object.
Returns
objectThe parsed Python value. Returns None for recognized null representations, a boolean for "true"/"false" strings, a Python literal (list, dict, int, etc.) if possible, or the original string if no conversion is possible.
def __serializeValue(self, value: object, type_hint: str | EnvironmentValueType | None = None) -> str: (source)

Serialize a Python value for storage in a .env file.

Parameters
value:objectThe value to serialize. Supported types include None, str, int, float, bool, list, dict, tuple, and set.
type_hint:str | EnvironmentValueType | None, optionalAn explicit type hint to guide serialization.
Returns
strThe serialized string representation of the input value, suitable for storage in a .env file. Returns "null" for None values.
def all(self) -> dict: (source)

Return all environment variables from the resolved .env file.

Returns
dictDictionary mapping environment variable names (str) to their parsed Python values. Only variables present in the .env file are included.
def get(self, key: str, default: object | None = None) -> object: (source)

Retrieve the value of an environment variable.

Parameters
key:strName of the environment variable to retrieve.
default:object | None, optionalValue to return if the key is not found. Defaults to None.
Returns
objectParsed value of the environment variable if found, otherwise default.
Raises
TypeErrorIf key is not a string, or if the stored value is incompatible with its declared type.
ValueErrorIf key is not a valid environment variable name, or if the stored value cannot be decoded for its declared type.
def reload(self) -> bool: (source)

Reload environment variables from the .env file.

Reload all environment variables from the .env file into the current process environment, overriding any existing values.

Returns
boolTrue if environment variables were successfully reloaded.
Raises
RuntimeErrorIf an error occurs during the reload operation.
def set(self, key: str, value: object, type_hint: str | EnvironmentValueType | None = None, *, only_os: bool = False) -> bool: (source)

Set an environment variable in the .env file and process environment.

Notes

Ensures thread safety, validates the key, serializes the value, writes to the .env file, and updates the process environment.

Parameters
key:strName of the environment variable to set.
value:objectValue to serialize. Without a hint, strings, scalar values, None, and literal containers are supported; other objects use str.
type_hint:str | EnvironmentValueType | None, optionalType hint to guide serialization of the value.
only_os:bool, optionalIf True, set only in the process environment, not in the .env file.
Returns
boolTrue if the environment variable was set successfully.
Raises
TypeErrorIf key is not a string, an explicitly typed value is unsupported, or type_hint is neither a string nor an EnvironmentValueType.
ValueErrorIf key is not a valid environment variable name, or if value cannot be serialized for the requested type.
RuntimeErrorIf type_hint is a string that does not name a member of EnvironmentValueType.
def unset(self, key: str, *, only_os: bool = False) -> bool: (source)

Remove an environment variable from the .env file and process environment.

Notes

This method is thread-safe. If the variable does not exist, returns True.

Parameters
key:strName of the environment variable to remove.
only_os:bool, optionalIf True, remove only from the process environment, not from the .env file.
Returns
boolTrue if the environment variable was removed or did not exist.
Raises
TypeErrorIf key is not a string.
ValueErrorIf key is not a valid environment variable name.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

Lock to ensure thread safety during initialization and operations that modify the .env file.

Single parsed snapshot used for file-backed values.

__resolved_path = (source)

Resolved backing file selected by the singleton's first caller.