From 432c108ce8242ded09075079601140ce50f61439 Mon Sep 17 00:00:00 2001 From: Carson Sievert Date: Mon, 3 Jun 2024 17:17:34 -0500 Subject: [PATCH] Close #2175. Improve installation docs and warnings/errors surrounding save_image() (#2360) --- DESCRIPTION | 2 +- R/export.R | 4 ++-- R/kaleido.R | 49 +++++++++++++++++++++++++++++++++++------------ R/orca.R | 4 ++-- man/export.Rd | 2 +- man/orca.Rd | 2 +- man/save_image.Rd | 13 +++++++------ 7 files changed, 51 insertions(+), 25 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index f7c6718462..1471874803 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -42,7 +42,7 @@ Imports: vctrs, tibble, lazyeval (>= 0.2.0), - rlang (>= 0.4.10), + rlang (>= 1.0.0), crosstalk, purrr, data.table, diff --git a/R/export.R b/R/export.R index 91f18d0bbf..866a1b60ba 100644 --- a/R/export.R +++ b/R/export.R @@ -1,6 +1,6 @@ #' Export a plotly graph to a static file #' -#' This function is in the process of being deprecated (use [orca] instead). +#' This function is deprecated, use [save_image] instead. #' #' @details For SVG plots, a screenshot is taken via `webshot::webshot()`. #' Since `phantomjs` (and hence `webshot`) does not support WebGL, @@ -19,7 +19,7 @@ #' @author Carson Sievert #' export <- function(p = last_plot(), file = "plotly.png", selenium = NULL, ...) { - .Deprecated("orca") + .Deprecated("save_image") # infer the file type fileType <- tolower(tools::file_ext(file)) diff --git a/R/kaleido.R b/R/kaleido.R index 97aa75549b..2ed9cdb678 100644 --- a/R/kaleido.R +++ b/R/kaleido.R @@ -8,14 +8,15 @@ #' @section Installation: #' #' `kaleido()` requires [the kaleido python -#' package](https://github.com/plotly/Kaleido/) to be usable via the \pkg{reticulate} package. Here is a recommended way to do the installation: +#' package](https://github.com/plotly/Kaleido/) to be usable via the +#' \pkg{reticulate} package. If you're starting from scratch, you install +#' eveything you need with the following R code: #' #' ``` -#' install.packages('reticulate') -#' reticulate::install_miniconda() -#' reticulate::conda_install('r-reticulate', 'python-kaleido') -#' reticulate::conda_install('r-reticulate', 'plotly', channel = 'plotly') -#' reticulate::use_miniconda('r-reticulate') +#' install.packages("reticulate") +#' library(reticulate) +#' use_python(install_python()) +#' py_install(c("kaleido", "plotly")) #' ``` #' #' @param ... not currently used. @@ -65,16 +66,40 @@ save_image <- function(p, file, ..., width = NULL, height = NULL, scale = NULL) #' @rdname save_image #' @export kaleido <- function(...) { - if (!rlang::is_installed("reticulate")) { - stop("`kaleido()` requires the reticulate package.") - } - if (!reticulate::py_available(initialize = TRUE)) { - stop("`kaleido()` requires `reticulate::py_available()` to be `TRUE`. Do you need to install python?") + rlang::check_installed("reticulate") + + call_env <- rlang::caller_env() + + if (!reticulate::py_available()) { + rlang::abort(c("`{reticulate}` wasn't able to find a Python environment.", + i = "If you have an existing Python installation, use `reticulate::use_python()` to inform `{reticulate}` of it.", + i = "To have `{reticulate}` install Python for you, `reticulate::install_python()`." + ), call = call_env) } + tryCatch( + reticulate::import("plotly"), + error = function(e) { + rlang::abort(c( + "The `plotly` Python package is required for static image exporting.", + i = "Please install it via `reticulate::py_install('plotly')`." + ), call = call_env) + } + ) + + kaleido <- tryCatch( + reticulate::import("kaleido"), + error = function(e) { + rlang::abort(c( + "The `kaleido` Python package is required for static image exporting.", + i = "Please install it via `reticulate::py_install('kaleido')`." + ), call = call_env) + } + ) + py <- reticulate::py scope_name <- paste0("scope_", new_id()) - py[[scope_name]] <- reticulate::import("kaleido")$scopes$plotly$PlotlyScope( + py[[scope_name]] <- kaleido$scopes$plotly$PlotlyScope( plotlyjs = plotlyMainBundlePath() ) diff --git a/R/orca.R b/R/orca.R index dfa7d9716a..1f9f988742 100644 --- a/R/orca.R +++ b/R/orca.R @@ -1,6 +1,6 @@ #' Static image exporting via orca #' -#' Superseded by [kaleido()]. +#' This function is deprecated, use [save_image()] instead. #' #' @param p a plotly object. #' @param file output filename. @@ -60,7 +60,7 @@ orca <- function(p, file = "plot.png", format = tools::file_ext(file), parallel_limit = NULL, verbose = FALSE, debug = FALSE, safe = FALSE, more_args = NULL, ...) { - .Deprecated("kaleido") + .Deprecated("save_image") orca_available() diff --git a/man/export.Rd b/man/export.Rd index b8fb536213..fa9cf5c8ee 100644 --- a/man/export.Rd +++ b/man/export.Rd @@ -21,7 +21,7 @@ jpeg/png/pdf arguments are passed along to \code{webshot::webshot()}. Otherwise, they are ignored.} } \description{ -This function is in the process of being deprecated (use \link{orca} instead). +This function is deprecated, use \link{save_image} instead. } \details{ For SVG plots, a screenshot is taken via \code{webshot::webshot()}. diff --git a/man/orca.Rd b/man/orca.Rd index dc91c1f64c..efd96093d2 100644 --- a/man/orca.Rd +++ b/man/orca.Rd @@ -80,7 +80,7 @@ for specifying display and/or electron options, such as \code{--enable-webgl} or \item{quiet}{Suppress all logging info.} } \description{ -Superseded by \code{\link[=kaleido]{kaleido()}}. +This function is deprecated, use \code{\link[=save_image]{save_image()}} instead. } \section{Methods}{ diff --git a/man/save_image.Rd b/man/save_image.Rd index 0934d81f86..baebd94f09 100644 --- a/man/save_image.Rd +++ b/man/save_image.Rd @@ -45,13 +45,14 @@ method for converting R plots into static images. \code{save_image()} provides a \section{Installation}{ -\code{kaleido()} requires \href{https://github.com/plotly/Kaleido/}{the kaleido python package} to be usable via the \pkg{reticulate} package. Here is a recommended way to do the installation: +\code{kaleido()} requires \href{https://github.com/plotly/Kaleido/}{the kaleido python package} to be usable via the +\pkg{reticulate} package. If you're starting from scratch, you install +eveything you need with the following R code: -\if{html}{\out{
}}\preformatted{install.packages('reticulate') -reticulate::install_miniconda() -reticulate::conda_install('r-reticulate', 'python-kaleido') -reticulate::conda_install('r-reticulate', 'plotly', channel = 'plotly') -reticulate::use_miniconda('r-reticulate') +\if{html}{\out{
}}\preformatted{install.packages("reticulate") +library(reticulate) +use_python(install_python()) +py_install(c("kaleido", "plotly")) }\if{html}{\out{
}} }