Manage/install

Manage brmspy runtimes and R environments.

This module defines the surface returned by brmspy.brms.manage().

The file is safe to import in the main Python process (no top-level rpy2.robjects imports). In normal use these methods are invoked through the manage() context, and the actual work executes in the worker process that hosts the embedded R session.

Example:

env = "mrp"
if not brms.environment_exists(env):
    with brms.manage(environment_name=env) as ctx:
        ctx.install_brms(use_prebuilt=True)
        ctx.install_rpackage("MCMCglmm")
else:
    brms.environment_activate(env)

Notes

• Use the context manager to ensure the worker (and its embedded R session) is started with the desired environment configuration.
• Calling these methods directly in the main process is unsupported and may reintroduce the same stability issues that the worker isolation is designed to avoid.

Classes

ManageModule

Management surface returned by brmspy.brms.manage().

The returned object is a proxy that executes these methods inside the worker process. Use it to install brms/toolchains, manage R packages in the active environment, and query basic runtime state.

Notes

The worker process must be able to run R and (depending on the installation mode) may require an OS toolchain for compiling packages / CmdStan.

Functions

install_runtime(*, install_rtools=False) staticmethod

Install the prebuilt brmspy runtime bundle.

This is a convenience wrapper around install_brms(use_prebuilt=True). It downloads (if necessary) a precompiled runtime and optionally activates it.

Parameters:

Name	Type	Description	Default
install_rtools	bool	If True, install Rtools on Windows if missing.	False

Returns:

Type	Description
Path or None	Path to the installed runtime directory (prebuilt mode). Returns None if no runtime was installed (unexpected for prebuilt mode).

Raises:

Type	Description
RuntimeError	If no compatible prebuilt runtime exists for the current platform.

Examples:

>>> from brmspy import brms
>>> with brms.manage(environment_name="default") as ctx:
...     runtime = ctx.install_runtime()

install_brms(*, use_prebuilt=False, install_rtools=False, brms_version=None, cmdstanr_version=None, install_rstan=True, install_cmdstanr=True, rstan_version=None, activate=True) staticmethod

Install brms and its toolchain dependencies.

In traditional mode (use_prebuilt=False), this installs into the active R library (typically the active brmspy environment) and may build CmdStan from source.

In prebuilt mode (use_prebuilt=True), this downloads a brmspy runtime bundle (R packages + CmdStan) and can activate it.

Parameters:

Name	Type	Description	Default
use_prebuilt	bool	If True, use a prebuilt runtime bundle instead of installing via R.	False
install_rtools	bool	If True, install Rtools on Windows if missing.	False
brms_version	str or None	Version spec for the brms R package (traditional mode only). None means "latest".	None
cmdstanr_version	str or None	Version spec for cmdstanr (traditional mode only). None means "latest".	None
install_rstan	bool	If True, install rstan (traditional mode).	True
install_cmdstanr	bool	If True, install cmdstanr and CmdStan (traditional mode).	True
rstan_version	str or None	Version spec for rstan (traditional mode only). None means "latest".	None
activate	bool	If True and use_prebuilt=True, activate the downloaded runtime in the worker's embedded R session.	True

Returns:

Type	Description
Path or None	If use_prebuilt=True, returns the installed runtime directory. If use_prebuilt=False, returns None.

Raises:

Type	Description
RuntimeError	If installation fails (for example missing toolchain, or no compatible prebuilt runtime exists).

Examples:

Prebuilt (fast) install:

>>> from brmspy import brms
>>> with brms.manage(environment_name="default") as ctx:
...     ctx.install_brms(use_prebuilt=True)

Traditional (R installs + builds CmdStan):

>>> from brmspy import brms
>>> with brms.manage(environment_name="default") as ctx:
...     ctx.install_brms(use_prebuilt=False, install_cmdstanr=True, install_rstan=False)

install_rpackage(name, version=None, repos_extra=None) staticmethod

Install an R package into the active environment library.

Parameters:

Name	Type	Description	Default
name	str	R package name (e.g. "MCMCglmm").	required
version	str or None	Optional version spec. None means "latest".	None
repos_extra	list[str] or None	Extra repositories to add (for example R-universe URLs).	None

Returns:

Type	Description
None

Notes

This installs into the active R library path (usually the brmspy environment library), not into the system R library tree.

Examples:

>>> from brmspy import brms
>>> with brms.manage(environment_name="mrp") as ctx:
...     ctx.install_rpackage("MCMCglmm")

uninstall_rpackage(name) staticmethod

Uninstall an R package from the active library paths.

Parameters:

Name	Type	Description	Default
name	str	R package name.	required

Returns:

Type	Description
bool	True if the package appears removed, otherwise False.

Notes

Package unloading/removal can be OS-dependent (especially on Windows where DLLs may be locked). This function makes a best effort.

Examples:

>>> from brmspy import brms
>>> with brms.manage(environment_name="mrp") as ctx:
...     ok = ctx.uninstall_rpackage("MCMCglmm")

import_rpackages(*names) staticmethod

Import (load) one or more R packages into the worker's embedded R session.

This does not install packages. Use install_rpackage() first if needed.

Parameters:

Name	Type	Description	Default
*names	str	One or more package names.	()

Returns:

Type	Description
None

Examples:

>>> from brmspy import brms
>>> with brms.manage(environment_name="default") as ctx:
...     ctx.import_rpackages("brms", "cmdstanr")

is_rpackage_loaded(name) staticmethod

Check whether an R package is loaded in the current R session.

Parameters:

Name	Type	Description	Default
name	str	R package name.	required

Returns:

Type	Description
bool	True if the package is loaded (namespace loaded or attached).

get_rpackage_version(name) staticmethod

Get installed version of an R package.

Parameters:

Name	Type	Description	Default
name	str	R package name.	required

Returns:

Type	Description
str or None	Installed version string, or None if not installed / not found.

is_rpackage_installed(name) staticmethod

Check whether an R package is installed in the active library paths.

Parameters:

Name	Type	Description	Default
name	str	R package name.	required

Returns:

Type	Description
bool	True if installed, otherwise False.

get_lib_paths() staticmethod

Get the current R .libPaths() search paths.

Returns:

Type	Description
list[str]	R library search paths (highest priority first).

get_cmdstan_path() staticmethod

Get the current CmdStan path configured in cmdstanr.

Returns:

Type	Description
str or None	CmdStan directory path, or None if not configured / cmdstanr unavailable.