Description Usage Arguments Details Value Choice of process type Constraints on user-defined functions Use of lazy installation Persistence of environment variables Author(s) See Also Examples
View source: R/basiliskStart.R
Creates a basilisk process in which Python operations (via reticulate) can be safely performed with the correct versions of Python packages.
1 2 3 4 5 6 7 8 9 10 11 12 | basiliskStart(env, fork = getBasiliskFork(), shared = getBasiliskShared())
basiliskStop(proc)
basiliskRun(
proc = NULL,
fun,
...,
env,
fork = getBasiliskFork(),
shared = getBasiliskShared()
)
|
env |
A BasiliskEnvironment object specifying the basilisk environment to use. Alternatively, a string specifying the path to an environment, though this should only be used for testing purposes. Alternatively, |
fork |
Logical scalar indicating whether forking should be performed on non-Windows systems,
see |
shared |
Logical scalar indicating whether |
proc |
A process object generated by |
fun |
A function to be executed in the basilisk process. This should return a “pure R” object, see details. |
... |
Further arguments to be passed to |
These functions ensure that any Python operations in fun
will use the environment specified by envname
.
This avoids version conflicts in the presence of other Python instances or environments loaded by other packages or by the user.
Thus, basilisk clients are not affected by (and if shared=FALSE
, do not affect) the activity of other R packages.
If necessary, objects created in fun
can persist across calls to basiliskRun
, e.g., for file handles.
This requires the use of assign
with envir
set to findPersistentEnv
to persist a variable,
and a corresponding get
to retrieve that object in later calls.
See Examples for more details.
It is good practice to call basiliskStop
once computation is finished to terminate the process.
Any Python-related operations between basiliskStart
and basiliskStop
should only occur via basiliskRun
.
Calling reticulate functions directly will have unpredictable consequences,
Similarly, it would be unwise to interact with proc
via any function other than the ones listed here.
If proc=NULL
in basiliskRun
, a process will be created and closed automatically.
This may be convenient in functions where persistence is not required.
Note that doing so requires specification of pkgname
and envname
.
If the base Conda installation provided with basilisk satisfies the requirements of the client package, developers can set env=NULL
in this function to use that base installation rather than constructing a separate environment.
basiliskStart
returns a process object, the exact nature of which depends on fork
and shared
.
This object should only be used in basiliskRun
and basiliskStop
.
basiliskRun
returns the output of fun(...)
, possibly executed inside the separate process.
basiliskStop
stops the process in proc
.
If shared=TRUE
and no Python version has already been loaded,
basiliskStart
will load Python directly into the R session from the specified environment.
Similarly, if the existing environment is the same as the requested environment, basiliskStart
will use that directly.
This mode is most efficient as it avoids creating any new processes,
but the use of a shared Python configuration may prevent non-basilisk packages from working correctly in the same session.
If fork=TRUE
, no Python version has already been loaded and we are not on Windows,
basiliskStart
will create a new process by forking.
In the forked process, basiliskStart
will load the specified environment for operations in Python.
This is less efficient as it needs to create a new process
but it avoids forcing a Python configuration on other packages in the same R session.
Otherwise, basiliskStart
will create a parallel socket process containing a separate R session.
In the new process, basiliskStart
will load the specified environment for Python operations.
This is the least efficient as it needs to transfer data over sockets but is guaranteed to work.
Developers can control these choices directly by explicitly specifying shared
and fork
,
while users can control them indirectly with setBasiliskFork
and related functions.
In basiliskRun
, there is no guarantee that fun
has access to basiliskRun
's calling environment.
This has a number of consequences for the type of code that can be written inside fun
:
Functions or variables from non-base R packages used inside fun
should be prefixed with the package namespace,
or the package itself should be reloaded inside fun
.
Any other variables used inside fun
should be explicitly passed as an argument.
Developers should not rely on closures to capture variables in the calling environment of basiliskRun
.
Relevant global variables from the calling environment should be explicitly reset inside fun
.
Developers should not attempt to pass complex objects to memory in or out of fun
.
This mostly refers to objects that contain custom pointers to memory, e.g., file handles, pointers to reticulate objects.
Both the arguments and return values of fun
should be pure R objects.
If the specified basilisk environment is not present and env
is a BasiliskEnvironment object, the environment will be created upon first use of basiliskStart
.
If the base Conda installation is not present, it will also be installed upon first use of basiliskStart
.
We do not provide Conda with the basilisk package binaries to avoid portability problems with hard-coded paths (as well as potential licensing issues from redistribution).
By default, both the base conda installation and the environments will be placed in an external user-writable directory defined by rappdirs via getExternalDir
.
The location of this directory can be changed by setting the BASILISK_EXTERNAL_DIR
environment variable to the desired path.
This may occasionally be necessary if the file path to the default location is too long for Windows, or if the default path has spaces that break the Miniconda/Anaconda installer.
Advanced users may consider setting the environment variable BASILISK_USE_SYSTEM_DIR
to 1 when installing basilisk and its client packages from source.
This will place both the base installation and the environments in the R system directory, which simplifies permission management and avoids duplication in enterprise settings.
When shared=TRUE
and if no Python instance has already been loaded into the current R session,
a side-effect of basiliskStart
is that it will modify a number of environment variables.
This is done to mimic activation of the Conda environment located at env
.
Importantly, old values for these variables will not be restored upon basiliskStop
.
This behavior is intentional as (i) the correct use of the Conda-derived Python depends on activation and (ii) the loaded Python persists for the entire R session.
It may not be safe to reset the environment variables and “deactivate” the environment while the Conda-derived Python instance is effectively still in use.
(In practice, lack of activation is most problematic on Windows due to its dependence on correct PATH
specification for dynamic linking.)
If persistence is not desirable, users should set shared=FALSE
via setBasiliskShared
.
This will limit any modifications to the environment variables to a separate R process.
Aaron Lun
setupBasiliskEnv
, to set up the conda environments.
getBasiliskFork
and getBasiliskShared
, to control various global options.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 | # Creating an environment (note, this is not necessary
# when supplying a BasiliskEnvironment to basiliskStart):
tmploc <- file.path(tempdir(), "my_package_B")
if (!file.exists(tmploc)) {
setupBasiliskEnv(tmploc, c('pandas=0.25.1',
"python-dateutil=2.8.0", "pytz=2019.3"))
}
# Pulling out the pandas version, as a demonstration:
cl <- basiliskStart(tmploc)
basiliskRun(proc=cl, function() {
X <- reticulate::import("pandas"); X$`__version__`
})
basiliskStop(cl)
# This happily co-exists with our other environment:
tmploc2 <- file.path(tempdir(), "my_package_C")
if (!file.exists(tmploc2)) {
setupBasiliskEnv(tmploc2, c('pandas=0.24.1',
"python-dateutil=2.7.1", "pytz=2018.7"))
}
cl2 <- basiliskStart(tmploc2)
basiliskRun(proc=cl2, function() {
X <- reticulate::import("pandas"); X$`__version__`
})
basiliskStop(cl2)
# Persistence of variables is possible within a Start/Stop pair.
cl <- basiliskStart(tmploc)
basiliskRun(proc=cl, function() {
assign(x="snake.in.my.shoes", 1, envir=basilisk::findPersistentEnv())
})
basiliskRun(proc=cl, function() {
get("snake.in.my.shoes", envir=basilisk::findPersistentEnv())
})
basiliskStop(cl)
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.