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.
Load and cache values from a resolved dotenv file.
| Static Method | __validate |
Reject a serialized value that cannot enter the process environment. |
| Method | __init__ |
Initialize the DotEnv service and prepare the .env file. |
| Method | __load |
Parse the file once and publish its validated process values. |
| Method | __parse |
Parse a value from the .env file into its corresponding Python type. |
| Method | __serialize |
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 |
Resolved backing file selected by the singleton's first caller. |
Reject a serialized value that cannot enter the process environment.
| Parameters | |
key:str | Environment variable name included in the Windows size limit. |
value:str | Serialized environment value to validate before any mutation. |
| Returns | |
None | No return value. |
| Raises | |
ValueError | If the value contains a null byte or exceeds Windows' native assignment length limit. |
Initialize the DotEnv service and prepare the .env file.
| Parameters | |
path:str or None, optional | Path to the .env file. Defaults to .env in the current working directory. |
| Returns | |
None | This method does not return a value. |
| Raises | |
OSError | If the .env file cannot be created or accessed. |
RuntimeError | If an unexpected error occurs during initialization. |
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 | |
OSError | If the selected file cannot be read. |
ValueError | If decoded entries cannot be assigned to the process environment. |
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:object | The value to parse, typically a string from the .env file or a Python object. |
| Returns | |
object | The 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. |
object, type_hint: str | EnvironmentValueType | None = None) -> str:
(source)
¶
Serialize a Python value for storage in a .env file.
| Parameters | |
value:object | The value to serialize. Supported types include None, str, int, float, bool, list, dict, tuple, and set. |
typestr | EnvironmentValueType | None, optional | An explicit type hint to guide serialization. |
| Returns | |
str | The serialized string representation of the input value, suitable for storage in a .env file. Returns "null" for None values. |
Return all environment variables from the resolved .env file.
| Returns | |
dict | Dictionary mapping environment variable names (str) to their parsed Python values. Only variables present in the .env file are included. |
Retrieve the value of an environment variable.
| Parameters | |
key:str | Name of the environment variable to retrieve. |
default:object | None, optional | Value to return if the key is not found. Defaults to None. |
| Returns | |
object | Parsed value of the environment variable if found, otherwise default. |
| Raises | |
TypeError | If key is not a string, or if the stored value is incompatible with its declared type. |
ValueError | If key is not a valid environment variable name, or if the stored value cannot be decoded for its declared type. |
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 | |
bool | True if environment variables were successfully reloaded. |
| Raises | |
RuntimeError | If an error occurs during the reload operation. |
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:str | Name of the environment variable to set. |
value:object | Value to serialize. Without a hint, strings, scalar values, None, and literal containers are supported; other objects use str. |
typestr | EnvironmentValueType | None, optional | Type hint to guide serialization of the value. |
onlybool, optional | If True, set only in the process environment, not in the .env file. |
| Returns | |
bool | True if the environment variable was set successfully. |
| Raises | |
TypeError | If key is not a string, an explicitly typed value is unsupported, or type_hint is neither a string nor an EnvironmentValueType. |
ValueError | If key is not a valid environment variable name, or if value cannot be serialized for the requested type. |
RuntimeError | If type_hint is a string that does not name a member of EnvironmentValueType. |
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:str | Name of the environment variable to remove. |
onlybool, optional | If True, remove only from the process environment, not from the .env file. |
| Returns | |
bool | True if the environment variable was removed or did not exist. |
| Raises | |
TypeError | If key is not a string. |
ValueError | If key is not a valid environment variable name. |