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 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 basilisk 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.

For channels, we recommend using open-source repositories like conda-forge and bioconda. This avoids problems with non-open-source licensing of the main Anaconda repositories (i.e., the "defaults" channel). If a client package relies on non-free channels, its users may inadvertently violate the Anaconda license, e.g., when used in a commercial environment.

After all conda packages are installed, additional packages can be installed from PyPi using the pip argument. 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.

After conda and PyPi, more Python packages can be installed from local directories via the paths argument. This is useful for basilisk clients vendoring Python packages that are not available in standard repositories. While paths expects absolute paths for general usage, this will be auto-generated in a package development context - 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

if (.Platform$OS.type != "windows") {
 

 tmploc <- file.path(tempdir(), "my_package_A")
 if (!file.exists(tmploc)) {
     setupBasiliskEnv(tmploc, c('pandas=1.4.3'))
 }
}

LTLA/basilisk documentation built on Nov. 3, 2024, 3:05 p.m.