environment

Environment store helpers (internal).

This module provides small filesystem helpers for brmspy "environments", which are named directories under ~/.brmspy/environment/<name>/ containing:

• config.json (serialized EnvironmentConfig)
• Rlib/ (user-managed R library for that environment)

The session layer uses these helpers when entering/leaving context-managed tools (e.g. manage()), and for convenience methods like environment existence checks.

Classes

EnvironmentConfig dataclass

Worker environment configuration.

This configuration is applied in the worker before importing/using brms.

Parameters:

Name	Type	Description	Default
r_home	str or None	Override for R_HOME. If None, the worker will rely on system detection.	None
startup_scripts	list[str]	R code snippets executed in the worker after initialization.	list()
environment_name	str	brmspy environment name (used to determine ~/.brmspy/environment/<name>/Rlib).	'default'
runtime_path	str or None	Path to a brmspy runtime bundle to activate in the worker.	None
env	dict[str, str]	Extra environment variables applied when spawning the worker.	dict()

Source code in brmspy/types/session.py

@dataclass
class EnvironmentConfig:
    """
    Worker environment configuration.

    This configuration is applied in the worker before importing/using brms.

    Parameters
    ----------
    r_home : str or None
        Override for `R_HOME`. If None, the worker will rely on system detection.
    startup_scripts : list[str]
        R code snippets executed in the worker after initialization.
    environment_name : str
        brmspy environment name (used to determine `~/.brmspy/environment/<name>/Rlib`).
    runtime_path : str or None
        Path to a brmspy runtime bundle to activate in the worker.
    env : dict[str, str]
        Extra environment variables applied when spawning the worker.
    """

    r_home: None | str = None
    startup_scripts: list[str] = field(default_factory=list)
    environment_name: str = "default"
    runtime_path: None | str = None
    env: dict[str, str] = field(default_factory=dict)

    def to_dict(self) -> dict[str, Any]:
        """Serialize configuration for persistence to JSON."""
        return {
            "environment_name": self.environment_name,
            "r_home": self.r_home,
            "startup_scripts": self.startup_scripts or [],
            "runtime_path": self.runtime_path,
            "env": self.env,
        }

    @classmethod
    def from_dict(cls, obj: dict[str, Any]) -> EnvironmentConfig:
        """Deserialize configuration from a JSON object."""
        return cls(
            r_home=obj["r_home"],
            startup_scripts=obj["startup_scripts"],
            environment_name=obj["environment_name"],
            runtime_path=obj["runtime_path"],
            env=obj["env"],
        )

    @classmethod
    def from_obj(
        cls, obj: None | dict[str, Any] | EnvironmentConfig
    ) -> EnvironmentConfig:
        """Normalize `None | dict | EnvironmentConfig` into an `EnvironmentConfig`."""
        if obj is None:
            return cls()
        if isinstance(obj, dict):
            return cls.from_dict(obj)
        return obj

Attributes

r_home = None class-attribute instance-attribute

startup_scripts = field(default_factory=list) class-attribute instance-attribute

environment_name = 'default' class-attribute instance-attribute

runtime_path = None class-attribute instance-attribute

env = field(default_factory=dict) class-attribute instance-attribute

Functions

to_dict()

Serialize configuration for persistence to JSON.

Source code in brmspy/types/session.py

def to_dict(self) -> dict[str, Any]:
    """Serialize configuration for persistence to JSON."""
    return {
        "environment_name": self.environment_name,
        "r_home": self.r_home,
        "startup_scripts": self.startup_scripts or [],
        "runtime_path": self.runtime_path,
        "env": self.env,
    }

from_dict(obj) classmethod

Deserialize configuration from a JSON object.

Source code in brmspy/types/session.py

@classmethod
def from_dict(cls, obj: dict[str, Any]) -> EnvironmentConfig:
    """Deserialize configuration from a JSON object."""
    return cls(
        r_home=obj["r_home"],
        startup_scripts=obj["startup_scripts"],
        environment_name=obj["environment_name"],
        runtime_path=obj["runtime_path"],
        env=obj["env"],
    )

from_obj(obj) classmethod

Normalize None | dict | EnvironmentConfig into an EnvironmentConfig.

Source code in brmspy/types/session.py

@classmethod
def from_obj(
    cls, obj: None | dict[str, Any] | EnvironmentConfig
) -> EnvironmentConfig:
    """Normalize `None | dict | EnvironmentConfig` into an `EnvironmentConfig`."""
    if obj is None:
        return cls()
    if isinstance(obj, dict):
        return cls.from_dict(obj)
    return obj

__init__(r_home=None, startup_scripts=list(), environment_name='default', runtime_path=None, env=dict())

Functions

get_environment_base_dir()

Return the base directory for brmspy environments, creating it if needed.

Returns:

Type	Description
Path	~/.brmspy/environment/

Source code in brmspy/_session/environment.py

def get_environment_base_dir() -> Path:
    """
    Return the base directory for brmspy environments, creating it if needed.

    Returns
    -------
    pathlib.Path
        `~/.brmspy/environment/`
    """
    base_dir = Path.home() / ".brmspy" / "environment"
    base_dir.mkdir(parents=True, exist_ok=True)
    return base_dir

get_environment_dir(name)

Return the directory for a named environment (may or may not exist).

Source code in brmspy/_session/environment.py

def get_environment_dir(name: str) -> Path:
    """Return the directory for a named environment (may or may not exist)."""
    base_dir = get_environment_base_dir()
    env_dir = base_dir / name
    return env_dir

get_environments_state_path()

Return the path to environment_state.json (stores last active environment name).

Source code in brmspy/_session/environment.py

def get_environments_state_path() -> Path:
    """Return the path to `environment_state.json` (stores last active environment name)."""
    return Path.home() / ".brmspy" / "environment_state.json"

get_environment_userlibs_dir(name)

Return the per-environment user library directory: .../<name>/Rlib.

Source code in brmspy/_session/environment.py

def get_environment_userlibs_dir(name: str) -> Path:
    """Return the per-environment user library directory: `.../<name>/Rlib`."""
    return get_environment_dir(name=name) / "Rlib"

get_environment_exists(name)

Return True if an environment exists (determined by presence of config.json).

Source code in brmspy/_session/environment.py

def get_environment_exists(name: str) -> bool:
    """
    Return True if an environment exists (determined by presence of `config.json`).
    """
    base_dir = get_environment_base_dir()
    env_dir = base_dir / name
    config_dir = env_dir / "config.json"

    return config_dir.exists()

get_environment_config(name)

Load an environment configuration from disk.

Parameters:

Name	Type	Description	Default
name	str	Environment name.	required

Returns:

Type	Description
EnvironmentConfig	Loaded configuration. If no config file exists, returns a default config with environment_name=name.

Source code in brmspy/_session/environment.py

def get_environment_config(name: str) -> EnvironmentConfig:
    """
    Load an environment configuration from disk.

    Parameters
    ----------
    name : str
        Environment name.

    Returns
    -------
    brmspy.types.session.EnvironmentConfig
        Loaded configuration. If no config file exists, returns a default config
        with `environment_name=name`.
    """
    base_dir = get_environment_base_dir()
    env_dir = base_dir / name
    config_dir = env_dir / "config.json"

    if not config_dir.exists():
        return EnvironmentConfig(environment_name=name)

    with open(config_dir) as f:
        data = json.load(f)
        return EnvironmentConfig.from_dict(data)