setupBasiliskEnv: Set up 'basilisk'-managed environments

Description Usage Arguments Details Value See Also Examples

View source: R/setupBasiliskEnv.R

Description

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

Usage

1
setupBasiliskEnv(envpath, packages, channels = "conda-forge", pip = 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.

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 improved predictability makes debugging much easier when the R package is installed and executed on 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 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 the version numbers for the desired Conda packages are unknown, developers can set basilisk:::globals$set(no.version=TRUE) to allow setupBasiliskEnv to work without version numbers. This instructs Conda to create an environment with the latest version 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.

It is possible to specify a different version of Python in packages by supplying, e.g., "python=2.7.10". If no Python version is listed, the version in the base conda installation is used by default.

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

1
2
3
4
5
tmploc <- file.path(tempdir(), "my_package_A")
if (!file.exists(tmploc)) {
    setupBasiliskEnv(tmploc, c('pandas=0.25.3',
        "python-dateutil=2.8.1", "pytz=2019.3"))
}

basilisk documentation built on Dec. 18, 2020, 2 a.m.