From 05361676816ded28004a7e490d9e2b18db34aab9 Mon Sep 17 00:00:00 2001 From: Tomasz Kalinowski Date: Wed, 26 Feb 2025 07:43:18 -0500 Subject: [PATCH 1/2] add `exclude_newer` arg to `uv_run_tool()` --- R/py_require.R | 42 ++++++++++++++++++++++++++++-------------- man/py_require.Rd | 16 ++++++++-------- man/uv_run_tool.Rd | 19 ++++++++++++++----- 3 files changed, 50 insertions(+), 27 deletions(-) diff --git a/R/py_require.R b/R/py_require.R index cbf999e94..5241648ef 100644 --- a/R/py_require.R +++ b/R/py_require.R @@ -80,8 +80,8 @@ #' ## Clearing the Cache #' #' If `uv` is already installed on your machine, `reticulate` will use the -#' existing `uv` installation as-is, including its default `cache dir` location. To -#' clear the caches of a self-managed `uv` installation, send the following +#' existing `uv` installation as-is, including its default `cache dir` location. +#' To clear the caches of a self-managed `uv` installation, send the following #' system commands to `uv`: #' #' ``` @@ -90,10 +90,10 @@ #' rm -r "$(uv tool dir)" #' ``` #' -#' If `uv` is not installed, `reticulate` will automatically download -#' `uv` and store it along with ephemeral environments and all downloaded -#' artifacts in the `tools::R_user_dir("reticulate", "cache")` directory. To -#' clear this cache, simply delete the directory: +#' If `uv` is not installed, `reticulate` will automatically download `uv` and +#' store it along with ephemeral environments and all downloaded artifacts in +#' the `tools::R_user_dir("reticulate", "cache")` directory. To clear this +#' cache, simply delete the directory: #' #' ```r #' unlink(tools::R_user_dir("reticulate", "cache"), recursive = TRUE) @@ -122,8 +122,8 @@ #' specified date. This offers a lightweight alternative to freezing package #' versions, helping guard against Python package updates that break a #' workflow. Accepts strings formatted as RFC 3339 timestamps (e.g., -#' "2006-12-02T02:07:43Z") and local dates in the same format (e.g., -#' "2006-12-02") in your system's configured time zone. Once `exclude_newer` +#' `"2006-12-02T02:07:43Z"`) and local dates in the same format (e.g., +#' `"2006-12-02"`) in your system's configured time zone. Once `exclude_newer` #' is set, only the `set` action can override it. #' #' @returns `py_require()` is primarily called for its side effect of modifying @@ -684,20 +684,27 @@ uv_get_or_create_env <- function(packages = py_reqs_get("packages"), #' uv run tool #' -#' Run a Command Line Tool distributed as a Python package. Packages are automatically -#' download and installed into a cached, ephemeral, and isolated environment on the first run. +#' Run a Command Line Tool distributed as a Python package. Packages are +#' automatically download and installed into a cached, ephemeral, and isolated +#' environment on the first run. #' #' @param tool,args A character vector of command and arguments. Arguments are #' not quoted for the shell, so you may need to use [`shQuote()`]. -#' @param from Use the given python package to provide the command. +#' @param from Use the given Python package to provide the command. #' @param with Run with the given Python packages installed. You can also #' specify version constraints like `"ruff>=0.3.0"`. -#' @param python_version A python version string, or character vector of python +#' @param python_version A Python version string, or character vector of Python #' version constraints. -#' +#' @param exclude_newer String. Limit package versions to those published before +#' a specified date. This offers a lightweight alternative to freezing package +#' versions, helping guard against Python package updates that break a +#' workflow. Accepts strings formatted as RFC 3339 timestamps (e.g., +#' `"2006-12-02T02:07:43Z"`) and local dates in the same format (e.g., +#' `"2006-12-02"`) in your system's configured time zone. #' @inheritDotParams base::system2 -command #' #' @details +#' #' ## Examples #' ```r #' uv_run_tool("pycowsay", shQuote("hello from reticulate")) @@ -713,7 +720,13 @@ uv_get_or_create_env <- function(packages = py_reqs_get("packages"), #' @returns Return value of [`system2()`] #' @export #' @md -uv_run_tool <- function(tool, args = character(), ..., from = NULL, with = NULL, python_version = NULL) { +uv_run_tool <- function(tool, + args = character(), + ..., + from = NULL, + with = NULL, + python_version = NULL, + exclude_newer = NULL) { uv <- uv_binary() withr::local_envvar(c( VIRTUAL_ENV = NA, @@ -731,6 +744,7 @@ uv_run_tool <- function(tool, args = character(), ..., from = NULL, with = NULL, "--isolated", "--python-preference=only-managed", "--python", resolve_python_version(constraints = python_version), + if (length(exclude_newer)) c("--exclude-newer", exclude_newer), if (length(from)) c("--from", maybe_shQuote(from)), if (length(with)) c(rbind("--with", maybe_shQuote(with))), "--", diff --git a/man/py_require.Rd b/man/py_require.Rd index c4a2f926f..446998ca3 100644 --- a/man/py_require.Rd +++ b/man/py_require.Rd @@ -27,8 +27,8 @@ from local files or a git repository is also supported (see details).} specified date. This offers a lightweight alternative to freezing package versions, helping guard against Python package updates that break a workflow. Accepts strings formatted as RFC 3339 timestamps (e.g., -"2006-12-02T02:07:43Z") and local dates in the same format (e.g., -"2006-12-02") in your system's configured time zone. Once \code{exclude_newer} +\code{"2006-12-02T02:07:43Z"}) and local dates in the same format (e.g., +\code{"2006-12-02"}) in your system's configured time zone. Once \code{exclude_newer} is set, only the \code{set} action can override it.} \item{action}{Determines how \code{py_require()} processes the provided @@ -132,8 +132,8 @@ See more examples \subsection{Clearing the Cache}{ If \code{uv} is already installed on your machine, \code{reticulate} will use the -existing \code{uv} installation as-is, including its default \verb{cache dir} location. To -clear the caches of a self-managed \code{uv} installation, send the following +existing \code{uv} installation as-is, including its default \verb{cache dir} location. +To clear the caches of a self-managed \code{uv} installation, send the following system commands to \code{uv}: \if{html}{\out{
}}\preformatted{uv cache clean @@ -141,10 +141,10 @@ rm -r "$(uv python dir)" rm -r "$(uv tool dir)" }\if{html}{\out{
}} -If \code{uv} is not installed, \code{reticulate} will automatically download -\code{uv} and store it along with ephemeral environments and all downloaded -artifacts in the \code{tools::R_user_dir("reticulate", "cache")} directory. To -clear this cache, simply delete the directory: +If \code{uv} is not installed, \code{reticulate} will automatically download \code{uv} and +store it along with ephemeral environments and all downloaded artifacts in +the \code{tools::R_user_dir("reticulate", "cache")} directory. To clear this +cache, simply delete the directory: \if{html}{\out{
}}\preformatted{unlink(tools::R_user_dir("reticulate", "cache"), recursive = TRUE) }\if{html}{\out{
}} diff --git a/man/uv_run_tool.Rd b/man/uv_run_tool.Rd index eb48661e9..a0b6e5113 100644 --- a/man/uv_run_tool.Rd +++ b/man/uv_run_tool.Rd @@ -10,7 +10,8 @@ uv_run_tool( ..., from = NULL, with = NULL, - python_version = NULL + python_version = NULL, + exclude_newer = NULL ) } \arguments{ @@ -51,20 +52,28 @@ not quoted for the shell, so you may need to use \code{\link[=shQuote]{shQuote() ignored on this platform, with a warning.} }} -\item{from}{Use the given python package to provide the command.} +\item{from}{Use the given Python package to provide the command.} \item{with}{Run with the given Python packages installed. You can also specify version constraints like \code{"ruff>=0.3.0"}.} -\item{python_version}{A python version string, or character vector of python +\item{python_version}{A Python version string, or character vector of Python version constraints.} + +\item{exclude_newer}{String. Limit package versions to those published before +a specified date. This offers a lightweight alternative to freezing package +versions, helping guard against Python package updates that break a +workflow. Accepts strings formatted as RFC 3339 timestamps (e.g., +\code{"2006-12-02T02:07:43Z"}) and local dates in the same format (e.g., +\code{"2006-12-02"}) in your system's configured time zone.} } \value{ Return value of \code{\link[=system2]{system2()}} } \description{ -Run a Command Line Tool distributed as a Python package. Packages are automatically -download and installed into a cached, ephemeral, and isolated environment on the first run. +Run a Command Line Tool distributed as a Python package. Packages are +automatically download and installed into a cached, ephemeral, and isolated +environment on the first run. } \details{ \subsection{Examples}{ From 0ae6aa92e36f7ca215664abd6594870400727b67 Mon Sep 17 00:00:00 2001 From: Tomasz Kalinowski Date: Wed, 26 Feb 2025 08:13:00 -0500 Subject: [PATCH 2/2] Add NEWS --- NEWS.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/NEWS.md b/NEWS.md index 0debc5da9..73d93ceee 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,6 +1,10 @@ # reticulate (development version) -- Internal fixes to prevent reticulate-managed `uv` from writing outside +- `uv_run_tool()` gains an `exclude_newer` argument (#1748). + +- Internal changes to support R-devel (4.5) (#1747). + +- Internal fixes to prevent reticulate-managed `uv` from writing outside reticulates cache directory (#1745). # reticulate 1.41.0