Add support for setting up Python through renv

DESCRIPTION

@@ -94,7 +94,8 @@ Suggests:
     jsonlite,
     sessioninfo,
     mockr,
-    varnish (>= 0.3.0)
+    varnish (>= 0.3.0),
+    reticulate
 Additional_repositories: https://carpentries.r-universe.dev/
 Remotes:
   carpentries/pegboard,
@@ -107,7 +108,7 @@ Config/testthat/parallel: false
 Config/Needs/check: rstudio/renv
 Config/potools/style: explicit
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.1
 URL: https://carpentries.github.io/sandpaper/, https://github.com/carpentries/sandpaper/, https://carpentries.github.io/workbench/
 BugReports: https://github.com/carpentries/sandpaper/issues/
 VignetteBuilder: knitr

NAMESPACE

@@ -25,6 +25,7 @@ export(move_episode)
 export(no_package_cache)
 export(package_cache_trigger)
 export(pin_version)
+export(py_install)
 export(renv_diagnostics)
 export(reset_episodes)
 export(reset_site)
@@ -37,6 +38,7 @@ export(set_instructors)
 export(set_learners)
 export(set_profiles)
 export(strip_prefix)
+export(template_citation)
 export(template_conduct)
 export(template_config)
 export(template_contributing)
@@ -55,6 +57,7 @@ export(update_cache)
 export(update_github_workflows)
 export(update_varnish)
 export(use_package_cache)
+export(use_python)
 export(validate_lesson)
 export(work_with_cache)
 importFrom(assertthat,validate_that)

R/create_lesson.R

@@ -11,6 +11,16 @@
 #'   file extension in the lesson.
 #' @param rstudio create an RStudio project (defaults to if RStudio exits)
 #' @param open if interactive, the lesson will open in a new editor window.
+#' @param add_python if set to `TRUE`, will add Python as a dependency for the
+#'   lesson. See [use_python()] for details. Defaults to `FALSE`.
+#' @param python the path to the version of Python to be used. The default,
+#'   `NULL`, will prompt the user to select an appropriate version of Python in
+#'   interactive sessions. In non-interactive sessions, \pkg{renv} will attempt
+#'   to automatically select an appropriate version. See [renv::use_python()]
+#'   for more details.
+#' @param type the type of Python environment to use. When `"auto"`, the
+#'   default, virtual environments will be used. See [renv::use_python()] for
+#'   more details.
 #'
 #' @export
 #' @return the path to the new lesson
@@ -19,7 +29,8 @@
 #' on.exit(unlink(tmp))
 #' lsn <- create_lesson(tmp, name = "This Lesson", open = FALSE)
 #' lsn
-create_lesson <- function(path, name = fs::path_file(path), rmd = TRUE, rstudio = rstudioapi::isAvailable(), open = rlang::is_interactive()) {
+create_lesson <- function(path, name = fs::path_file(path), rmd = TRUE, rstudio = rstudioapi::isAvailable(), open = rlang::is_interactive(),
+                          add_python = FALSE, python = NULL, type = c("auto", "virtualenv", "conda", "system")) {
 
   path <- fs::path_abs(path)
   id <- cli::cli_status("{cli::symbol$arrow_right} Creating Lesson in {.file {path}}...")
@@ -93,6 +104,11 @@ create_lesson <- function(path, name = fs::path_file(path), rmd = TRUE, rstudio
   if (has_consent) {
     cli::cli_status_update("{cli::symbol$arrow_right} Managing Dependencies ...")
     manage_deps(path, snapshot = TRUE)
+
+    if (add_python) {
+      cli::cli_status_update("{cli::symbol$arrow_right} Setting up Python ...")
+      use_python(path = path, python = python, type = type, open = FALSE)
+    }
   }
 
   cli::cli_status_update("{cli::symbol$arrow_right} Committing ...")

R/manage_deps.R

@@ -104,18 +104,31 @@ manage_deps <- function(path = ".", profile = "lesson-requirements", snapshot =
 #'   if it's running in an interactive session.
 #' @rdname dependency_management
 #' @export
-update_cache <- function(path = ".", profile = "lesson-requirements", prompt = interactive(), quiet = !prompt, snapshot = TRUE) {
-  path <- root_path(path)
+update_cache <- function(path = ".", profile = "lesson-requirements", prompt = interactive(),
+                         quiet = !prompt, snapshot = TRUE) {
+
   prof <- Sys.getenv("RENV_PROFILE")
   on.exit({
-    invisible(utils::capture.output(renv::deactivate(path), type = "message"))
     Sys.setenv("RENV_PROFILE" = prof)
   }, add = TRUE)
   Sys.setenv("RENV_PROFILE" = profile)
-  renv::load(project = path)
+  path <- root_path(path)
+
+  # Make sure the current requirements are installed, this also avoids removing any uninstalled
+  # Python dependencies in requirements.txt
+  manage_deps(path = path, profile = profile, snapshot = snapshot, quiet = quiet)
+
   lib <- renv::paths$library(project = path)
+  updates <- callr::r(
+    func = function(f, lib) f(lib),
+    args = list(
+      f = with_renv_factory(check_for_updates, renv_path = path, renv_profile = profile),
+      lib = lib
+    ),
+    show = !quiet
+  )
+
   if (prompt) {
-    updates <- renv::update(library = lib, check = TRUE, prompt = TRUE)
     if (isTRUE(updates)) {
       return(invisible())
     }
@@ -135,6 +148,33 @@ update_cache <- function(path = ".", profile = "lesson-requirements", prompt = i
       return(invisible())
     }
   }
+
+  sho <- !(quiet || identical(Sys.getenv("TESTTHAT"), "true"))
+  out <- callr::r(
+    func = function(f, path, lib, snapshot) f(path, lib, snapshot),
+    args = list(
+      f = with_renv_factory(callr_update_cache, renv_path = path, renv_profile = profile),
+      path = path,
+      lib = lib,
+      snapshot = snapshot
+    ),
+    show = !quiet,
+    spinner = sho,
+    user_profile = FALSE,
+    env = c(callr::rcmd_safe_env(),
+      "R_PROFILE_USER" = fs::path(tempfile(), "nada"),
+      "RENV_CONFIG_CACHE_SYMLINKS" = renv_cache_available()
+    )
+  )
+  invisible(out)
+}
+
+check_for_updates <- function(lib) {
+  cli::cli_alert("Checking for updates")
+  renv::update(library = lib, check = TRUE, prompt = TRUE)
+}
+
+callr_update_cache <- function(path, lib, snapshot) {
   updates <- renv::update(library = lib, prompt = FALSE)
   if (snapshot) {
     renv::snapshot(lockfile = renv::paths$lockfile(project = path), prompt = FALSE)

R/use_python.R

@@ -0,0 +1,151 @@
+#' Add Python as a lesson dependency
+#'
+#' Associate a version of Python with your lesson. This is essentially a wrapper
+#' around [renv::use_python()].
+#'
+#' @param path path to the current project
+#' @inheritParams renv::use_python
+#' @param open if interactive, the lesson will open in a new editor window.
+#' @param quiet if `TRUE`, suppresses output.
+#' @param ... Further arguments to be passed on to [renv::use_python()]
+#'
+#' @details
+#' This helper function adds Python as a dependency to the \pkg{renv} lockfile
+#' and installs a Python environment of the specified `type`. This ensures any
+#' Python packages used for this lesson are installed separately from the user's
+#' main library, much like the R packages (see [manage_deps()]).
+#'
+#' Note that \pkg{renv} is not (yet) able to automatically detect Python package
+#' dependencies (e.g. from `import` statements). So any required Python packages
+#' still need to be installed manually. To facilitate this, the [py_install()]
+#' helper is provided. This will install Python packages in the correct
+#' environment and record them in a `requirements.txt` file, which will be
+#' tracked by \pkg{renv}. Subsequent calls of [manage_deps()] will then
+#' correctly restore the required Python packages if needed.
+#'
+#' @export
+#' @rdname use_python
+#' @seealso [renv::use_python()], [py_install()]
+#' @return The path to the Python executable. Note that this function is mainly
+#'   called for its side effects.
+#' @examples
+#' \dontrun{
+#' tmp <- tempfile()
+#' on.exit(unlink(tmp))
+#'
+#' ## Create lesson with Python support
+#' lsn <- create_lesson(tmp, name = "This Lesson", open = FALSE, add_python = TRUE)
+#' lsn
+#'
+#' ## Add Python as a dependency to an existing lesson
+#' setwd(lsn)
+#' use_python()
+#'
+#' ## Install Python packages and record them as dependencies
+#' py_install("numpy")
+#' }
+use_python <- function(path = ".", python = NULL,
+                       type = c("auto", "virtualenv", "conda", "system"),
+                       open = rlang::is_interactive(), ..., quiet = FALSE) {
+
+  ## Make sure reticulate is installed
+  install_reticulate(path = path, quiet = quiet)
+
+  ## Generate function to run in separate R process
+  use_python_with_renv <- function(path, python, type, ...) {
+    prof <- Sys.getenv("RENV_PROFILE")
+    renv::use_python(project = path, python = python, type = type, ...)
+
+    ## NOTE: use_python() deactivates the default profile,
+    ## see https://github.com/rstudio/renv/issues/1217
+    ## Workaround: re-activate the profile
+    renv::activate(project = path, profile = prof)
+  }
+  callr_use_python <- with_renv_factory(use_python_with_renv,
+    renv_path = path, renv_profile = "lesson-requirements"
+  )
+
+  ## Run in separate R process
+  callr::r(
+    func = function(f, path, python, type,  ...) f(path = path, python = python , type = type, ...),
+    args = list(f = callr_use_python, path = path, python = python, type = type, ...),
+    show = !quiet
+  )
+
+  if (open) {
+    if (usethis::proj_activate(path)) {
+      on.exit()
+    }
+  }
+  invisible(path)
+}
+
+
+#' Install Python packages and add them to the cache
+#'
+#' To add Python packages, `py_install()` is provided, which installs Python
+#' packages with [reticulate::py_install()] and then records them in the renv
+#' environment. This ensures [manage_deps()] keeps track of the Python packages
+#' as well.
+#'
+#' @param packages Python packages to be installed as a character vecto.
+#' @param path path to your lesson. Defaults to the current working directory.
+#' @param ... Further arguments to be passed to [reticulate::py_install()]
+#'
+#' @export
+#' @rdname use_python
+py_install <- function(packages, path = ".",  ...) {
+
+  ## Ensure reticulate is installed
+  install_reticulate(path = path)
+
+  py_install_with_renv <- function(packages, ...) {
+    reticulate::py_install(packages = packages, ...)
+    cli::cli_alert("Updating the package cache")
+    renv::snapshot(prompt = FALSE)
+  }
+  callr_py_install <- with_renv_factory(py_install_with_renv,
+    renv_path = path, renv_profile = "lesson-requirements"
+  )
+
+  ## Run in separate R process
+  callr::r(
+    func = function(f, packages) f(packages = packages),
+    args = list(f = callr_py_install, packages = packages),
+    show = TRUE
+  )
+
+  invisible(TRUE)
+}
+
+
+## Helper to install reticulate in the lesson's renv environment and record it as a dependency
+install_reticulate <- function(path, quiet = FALSE) {
+
+  if (!check_reticulate_installable()) {
+    cli::cli_alert("`reticulate` can not be installed on this system. Skipping installation.")
+    return(invisible(FALSE))
+  }
+
+  ## Record reticulate as a dependency for renv
+  dep_file <- fs::path(path, "dependencies.R")
+  write("library(reticulate)", file = dep_file, append = TRUE)
+
+  ## Install reticulate through manage_deps()
+  manage_deps(path = path, quiet = quiet)
+
+  invisible(TRUE)
+}
+
+check_reticulate_installable <- function() {
+  minimal_major <- 4
+  r_compatible <- is_r_version_greater_than(minimal_major = minimal_major)
+  if (!r_compatible) {
+    cli::cli_warn("R version {minimal_major}.0 or higher is required for reticulate")
+  }
+  r_compatible
+}
+
+is_r_version_greater_than <- function(minimal_major = 4) {
+  R.version$major >= minimal_major
+}

R/utils-renv.R

@@ -291,8 +291,12 @@ callr_manage_deps <- function(path, repos, snapshot, lockfile_exists) {
   #    recorded.
   if (lockfile_exists) {
     cli::cli_alert("Restoring any dependency versions")
-    res <- renv::restore(project = path, library = renv_lib,
-      lockfile = renv_lock, prompt = FALSE)
+    # Load profile, this ensures Python dependencies also get restored
+    renv::load(project = path)
+    on.exit({
+      invisible(utils::capture.output(renv::deactivate(project = path), type = "message"))
+    }, add = TRUE)
+    res <- renv::restore(project = path, prompt = FALSE)
   }
   if (snapshot) {
     # 3. Load the current profile, unloading it when we exit
@@ -309,3 +313,38 @@ callr_manage_deps <- function(path, repos, snapshot, lockfile_exists) {
   }
   return(NULL)
 }
+
+
+#' Generate a function to run in a renv profile
+#'
+#' This is a [Function operator](https://adv-r.hadley.nz/function-operators.html) which will
+#' generate a function that will run in a renv profile. This is useful for running code in a
+#' separate R subprocess with [`callr::r()`], to avoid *renv* side effects related to interactive
+#' sessions.
+#'
+#' @param func The function to be evaluated after loading the renv environment.
+#' @param renv_path The path to the renv environment to load. Usually a directory created by
+#'   [`create_lesson()`]
+#' @param renv_profile Optional profile to load. Defaults to "lesson-requirements".
+#' @param ... Additional arguments to be passed to `func`.
+#'
+#' @return The result of evaluating `func(...)` after loading the renv environment.
+#'
+#' @keywords internal
+with_renv_factory <- function(func, renv_path, renv_profile = "lesson-requirements") {
+  force(func); force(renv_path); force(renv_profile)
+
+  function(...) {
+    on.exit({
+      invisible(utils::capture.output(renv::deactivate(project = renv_path), type = "message"))
+    }, add = TRUE)
+    renv_path <- normalizePath(renv_path)
+    withr::local_dir(renv_path)
+    withr::local_envvar(c("RENV_PROFILE" = renv_profile))
+    renv::load(renv_path)
+
+    func(...)
+  }
+}
+
+

_pkgdown.yml

@@ -61,6 +61,7 @@ reference:
  - contents:
    - use_package_cache
    - manage_deps
+   - use_python
  - title: "Updating Lesson Tools"
    desc: >
      Lesson updates will happen automatically on a regular schedule on GitHub.
@@ -151,4 +152,3 @@ articles:
  - title: "In Progress"
    contents:
    - articles/internationalisation
-