setupBasiliskEnv: Set up 'basilisk'-managed environments

In LTLA/basilisk: Freezing Python Dependencies Inside Bioconductor Packages

Set up basilisk-managed environments

Description

Set up a conda environment for isolated execution of Python code with appropriate versions of all Python packages.

Usage

setupBasiliskEnv(
  envpath,
  packages,
  channels = "conda-forge",
  pip = NULL,
  paths = NULL
)

Arguments

envpath	String containing the path to the environment to use.
packages	Character vector containing the names of conda packages to install into the environment. Version numbers must be included.
channels	Character vector containing the names of additional conda channels to search. Defaults to the conda-forge repository.
pip	Character vector containing the names of additional packages to install from PyPi using pip. Version numbers must be included.
paths	Character vector containing absolute paths to Python package directories, to be installed by pip.

Details

Developers of client packages should never need to call this function directly. For typical usage, setupBasiliskEnv is automatically called by basiliskStart to perform lazy installation. Developers should also create configure(.win) files to call configureBasiliskEnv, which will call setupBasiliskEnv during R package installation when BASILISK_USE_SYSTEM_DIR=1.

Pinned version numbers must be present for all desired conda packages in packages. This improves predictability and simplifies debugging across different systems. Note that the version notation for conda packages uses a single =, while the notation for Python packages uses ==; any instances of the latter will be coerced to the former automatically.

It is possible to use the pip argument to install additional packages from PyPi after all the conda packages are installed. All packages listed here are also expected to have pinned versions, this time using the == notation. However, some caution is required when mixing packages from conda and pip, see https://www.anaconda.com/using-pip-in-a-conda-environment for more details.

It is further possible to install Python packages from directories. In the package development context, this typically assumes that the Python directories are included in the inst subdirectory of the R package. basiliskStart will then convert the relative path to an absolute path before calling this function - see BasiliskEnvironment for details.

It is also good practice to explicitly list the versions of the dependencies of all desired packages. This protects against future changes in the behavior of your code if conda's solver decides to use a different version of a dependency. To identify appropriate versions of dependencies, we suggest:

1. Creating a fresh conda environment with the desired packages, using packages= in setupBasiliskEnv.

2. Calling listPackages on the environment to identify any relevant dependencies and their versions.

3. Including those dependencies in the packages= argument for future use. (It is helpful to mark dependencies in some manner, e.g., with comments, to distinguish them from the actual desired packages.)

The only reason that pinned dependencies are not mandatory is because some dependencies are OS-specific, requiring some manual pruning of the output of listPackages.

If versions for the desired conda packages are not known beforehand, developers may use setBasiliskCheckVersions(FALSE) before running setupBasiliskEnv. This instructs conda to create an environment with appropriate versions of all unpinned packages, which can then be read out via listPackages for insertion in the packages= argument as described above. We stress that this option should not be used in any release of the R package, it is a development-phase-only utility.

If no Python version is listed, the version in the base conda installation is used by default - check listPythonVersion for the version number. However, it is often prudent to explicitly list the desired version of Python in packages, even if this is already version-compatible with the default (e.g., "python=3.8"). This protects against changes to the Python version in the base installation, e.g., if administrators override the choice of conda installation with certain environment variables. Of course, it is possible to specify an entirely different version of Python in packages by supplying, e.g., "python=2.7.10".

Value

A conda environment is created at envpath containing the specified packages. A NULL is invisibly returned.

See Also

listPackages, to list the packages in the conda environment.

Examples

tmploc <- file.path(tempdir(), "my_package_A")
if (!file.exists(tmploc)) {
    setupBasiliskEnv(tmploc, c(pandas_spec()))
}

LTLA/basilisk documentation built on Feb. 6, 2024, 2:29 p.m.