Merge pull request #1852 from rstudio/requirements-doc-improvements

Add `reg.finalizer(py_write_requirements)` example

Author: t-kalinowski

R/install.R

@@ -271,15 +271,39 @@ py_list_packages <- function(envname = NULL,
 #' ephemeral, it writes a fully resolved manifest via `pip freeze`.
 #'
 #' - `py_read_requirements()` reads `requirements.txt` and `.python-version`, and
-#' applies them with [py_require()]. By default, entries are added (`action =
-#' "add"`).
+#' applies them with [py_require()]. By default, entries are added (`action
+#' = "add"`).
 #'
-#' These are primarily an alternative interface to `py_require()`, but can also
-#' work with non-ephemeral virtual environments.
+#' These are primarily an alternative interface to `py_require()`, but can
+#' also work with non-ephemeral virtual environments.
 #'
 #' @note
-#' You can create a local virtual environment from `requirements.txt` and
-#' `.python-version` using [virtualenv_create()]:
+#'
+#' To continue using `py_require()` locally while keeping a
+#' `requirements.txt` up-to-date for deployments, you can register
+#' an exit handler in `.Rprofile` like this:
+#'
+#' ```r
+#' reg.finalizer(
+#'   asNamespace("reticulate"),
+#'   function(ns) {
+#'     if (
+#'       reticulate::py_available() &&
+#'         isTRUE(reticulate::py_config()$ephemeral)
+#'     ) {
+#'       reticulate::py_write_requirements(quiet = TRUE)
+#'     }
+#'   },
+#'   onexit = TRUE
+#' )
+#' ```
+#'
+#' This approach is only recommended if you are using `git`.
+#'
+#' Alternatively, you can transition away from using ephemeral python
+#' environemnts via `py_require()` to using a persistent local virtual
+#' environment you manage. You can create a local virtual environment from
+#' `requirements.txt` and `.python-version` using [virtualenv_create()]:
 #'
 #' ```r
 #' # Note: '.venv' in the current directory is auto-discovered by reticulate.
@@ -291,31 +315,37 @@ py_list_packages <- function(envname = NULL,
 #' )
 #' ```
 #'
+#' If you run into issues, be aware that `requirements.txt` and
+#' `.python-version` may not contain all the information necessary to
+#' reproduce the Python environment if the R code sets environment variables
+#' like `UV_INDEX` or `UV_CONSTRAINT`.
+#'
 #' @name py_requirements_files
 #'
 #' @param packages Path to the package requirements file. Defaults to
 #'   `"requirements.txt"`. Use `NULL` to skip.
 #' @param python_version Path to the Python version file. Defaults to
 #'   `".python-version"`. Use `NULL` to skip.
-#' @param freeze Logical. If `TRUE`, writes a fully resolved list of installed
-#'   packages using `pip freeze`. If `FALSE`, writes only the requirements
-#'   tracked by [py_require()].
+#' @param freeze Logical. If `TRUE`, writes a fully resolved list of
+#'   installed packages using `pip freeze`. If `FALSE`, writes only the
+#'   requirements tracked by [py_require()].
 #' @param python Path to the Python executable to use.
 #' @param action How to apply requirements read by `py_read_requirements()`:
 #'   `"add"` (default) adds to existing requirements, `"set"` replaces them,
-#'   `"remove"` removes matching entries, or `"none"` skips applying them and
-#'   returns the read values.
+#'   `"remove"` removes matching entries, or `"none"` skips applying them
+#'   and returns the read values.
 #' @param ... Unused; must be empty.
-#' @param quiet Logical; if `TRUE`, suppresses the informational messages that
-#'   print `wrote '<path>'` for each file written.
+#' @param quiet Logical; if `TRUE`, suppresses the informational messages
+#'   that print `wrote '<path>'` for each file written.
 #'
 #' @return Invisibly, a list with two named elements:
 #' \describe{
 #'   \item{`packages`}{Character vector of package requirements.}
 #'   \item{`python_version`}{String specifying the Python version.}
 #' }
 #'
-#' To get just the return value without writing any files, you can pass `NULL` for file paths, like this:
+#'   To get just the return value without writing any files, you can pass
+#'   `NULL` for file paths, like this:
 #'
 #' ```r
 #' py_write_requirements(NULL, NULL)