env

optimus_dl.core.env

get_device_from_env(env, name)

Return the value of an environment variable as :class:torch.device.

Parameters:

Name	Type	Description	Default
env	Mapping[str, str]	The environment mapping.	required
name	str	The name of the environment variable.	required

Returns:

Type	Description
device | None	The torch.device, or None if the variable is not present.

Raises:

Type	Description
InvalidEnvironmentVariableError	If the value is not a valid device string.

Source code in optimus_dl/core/env.py

def get_device_from_env(env: Mapping[str, str], name: str) -> torch.device | None:
    """Return the value of an environment variable as :class:`torch.device`.

    Args:
        env: The environment mapping.
        name: The name of the environment variable.

    Returns:
        The torch.device, or None if the variable is not present.

    Raises:
        InvalidEnvironmentVariableError: If the value is not a valid device string.
    """
    device_str = env.get(name)
    if device_str is None:
        return None

    try:
        return torch.device(device_str)
    except (RuntimeError, ValueError):
        raise InvalidEnvironmentVariableError(
            name, f"The value of the `{name}` environment variable is expected to specify a PyTorch device, but is '{device_str}' instead."  # fmt: skip
        ) from None

get_int_from_env(env, name, allow_zero=False)

Return the value of an environment variable as int.

Parameters:

Name	Type	Description	Default
env	Mapping[str, str]	The environment mapping (e.g. os.environ).	required
name	str	The name of the environment variable.	required
allow_zero	bool	If True, returns the value if it equals to zero; otherwise, raises a :class:InvalidEnvironmentVariableError.	False

Returns:

Type	Description
int | None	The integer value, or None if the variable is not present.

Raises:

Type	Description
InvalidEnvironmentVariableError	If the value is not a valid integer or violates constraints (e.g. negative when allow_zero is False).

Source code in optimus_dl/core/env.py

def get_int_from_env(
    env: Mapping[str, str], name: str, allow_zero: bool = False
) -> int | None:
    """Return the value of an environment variable as ``int``.

    Args:
        env: The environment mapping (e.g. os.environ).
        name: The name of the environment variable.
        allow_zero: If ``True``, returns the value if it equals to zero;
            otherwise, raises a :class:`InvalidEnvironmentVariableError`.

    Returns:
        The integer value, or None if the variable is not present.

    Raises:
        InvalidEnvironmentVariableError: If the value is not a valid integer
            or violates constraints (e.g. negative when allow_zero is False).
    """
    s = env.get(name)
    if s is None:
        return None

    try:
        value = int(s)
    except ValueError:
        raise InvalidEnvironmentVariableError(
            name, f"The value of the `{name}` environment variable is expected to be an integer, but is '{s}' instead."  # fmt: skip
        ) from None

    if not allow_zero:
        if not value >= 1:
            raise InvalidEnvironmentVariableError(
                name, f"The value of the `{name}` environment variable is expected to be a positive integer, but is {value} instead."  # fmt: skip
            )
    else:
        if not value >= 0:
            raise InvalidEnvironmentVariableError(
                name, f"The value of the `{name}` environment variable is expected to be greater than or equal to 0, but is {value} instead."  # fmt: skip
            )

    return value

get_path_from_env(env, name)

Return the value of an environment variable as :class:~pathlib.Path.

Parameters:

Name	Type	Description	Default
env	Mapping[str, str]	The environment mapping.	required
name	str	The name of the environment variable.	required

Returns:

Type	Description
Path | None	The path, or None if the variable is not present.

Raises:

Type	Description
InvalidEnvironmentVariableError	If the value cannot be converted to a Path.

Source code in optimus_dl/core/env.py

def get_path_from_env(env: Mapping[str, str], name: str) -> Path | None:
    """Return the value of an environment variable as :class:`~pathlib.Path`.

    Args:
        env: The environment mapping.
        name: The name of the environment variable.

    Returns:
        The path, or None if the variable is not present.

    Raises:
        InvalidEnvironmentVariableError: If the value cannot be converted to a Path.
    """
    pathname = env.get(name)
    if not pathname:
        return None

    try:
        return Path(pathname)
    except ValueError:
        raise InvalidEnvironmentVariableError(
            name, f"The value of the `{name}` environment variable is expected to be a pathname, but is '{pathname}' instead."  # fmt: skip
        ) from None