check_algorithm_deprecation(): implement toggle to bypass warning *

This is used internally to avoid producing the same warning multiple times in one user call.

Following code was used in testing interactively (from
#193 (comment)):

library(qgisprocess)

download.file("https://github.com/inbo/coding-club/raw/main/data/20231214/20231214_land_use_nara_2016_100m.tif", "20231214_land_use_nara_2016_100m.tif")
download.file("https://github.com/inbo/coding-club/raw/main/data/20231214/20231214_natura2000_protected_areas.gpkg", "20231214_natura2000_protected_areas.gpkg")

zonal_st <- qgis_run_algorithm("native:zonalstatistics",
                               INPUT_RASTER = "20231214_land_use_nara_2016_100m.tif",
                               COLUMN_PREFIX = "landuse_",
                               INPUT_VECTOR = "20231214_natura2000_protected_areas.gpkg",
                               STATISTICS = c("Majority", "Minority"))
qgis_show_help("native:zonalstatistics")
qgis_get_description("native:zonalstatistics")
qgis_get_argument_specs("native:zonalstatistics")
qgis_get_output_specs("native:zonalstatistics")
qgis_function("native:zonalstatistics")

Author: florisvdh

R/qgis-algorithms.R

@@ -83,7 +83,7 @@ qgis_providers <- function(
 }
 
 #' @keywords internal
-assert_qgis_algorithm <- function(algorithm) {
+assert_qgis_algorithm <- function(algorithm, check_deprecation = TRUE) {
   if (!is.character(algorithm) || length(algorithm) != 1) {
     abort("`algorithm` must be a character vector of length 1")
   } else if (!qgis_has_algorithm(algorithm)) {
@@ -94,14 +94,15 @@ assert_qgis_algorithm <- function(algorithm) {
     )
   }
 
-  check_algorithm_deprecation(algorithm)
+  check_algorithm_deprecation(algorithm, skip = !check_deprecation)
 
   invisible(algorithm)
 }
 
 
 #' @keywords internal
-check_algorithm_deprecation <- function(algorithm) {
+check_algorithm_deprecation <- function(algorithm, skip = FALSE) {
+  if (skip) return(invisible(NULL))
   algs <- qgis_algorithms()
   if ("deprecated" %in% colnames(algs)) {
     deprecated_algs <- algs$algorithm[algs$deprecated]

R/qgis-arguments.R

@@ -79,8 +79,11 @@ as_qgis_argument <- function(x, spec = qgis_argument_spec(), use_json_input = FA
 # serialized as JSON instead of serialized as a command-line argument.
 # @param .algorithm_arguments The result of [qgis_get_argument_specs()]
 #' @keywords internal
-qgis_sanitize_arguments <- function(algorithm, ..., .algorithm_arguments = qgis_get_argument_specs(algorithm),
-                                    .use_json_input = FALSE) {
+qgis_sanitize_arguments <- function(
+    algorithm,
+    ...,
+    .algorithm_arguments = qgis_get_argument_specs(algorithm, check_deprecation = FALSE),
+    .use_json_input = FALSE) {
   dots <- rlang::list2(...)
   if (length(dots) > 0 && !rlang::is_named(dots)) {
     abort("All ... arguments to `qgis_sanitize_arguments()` must be named.")
@@ -501,7 +504,7 @@ qgis_argument_spec <- function(algorithm = NA_character_, name = NA_character_,
 
 #' @keywords internal
 qgis_argument_spec_by_name <- function(algorithm, name,
-                                       .algorithm_arguments = qgis_get_argument_specs(algorithm)) {
+                                       .algorithm_arguments = qgis_get_argument_specs(algorithm, check_deprecation = FALSE)) {
   # These are special-cased at the command-line level, so they don't have
   # types defined in the help file. Here, we create two special types
   # ELLIPSOID and PROJECT_PATH.

R/qgis-function.R

@@ -30,7 +30,7 @@ qgis_function <- function(algorithm, ...) {
   assert_qgis()
   assert_qgis_algorithm(algorithm)
 
-  args <- qgis_get_argument_specs(algorithm)
+  args <- qgis_get_argument_specs(algorithm, check_deprecation = FALSE)
   arg_names <- c(args$name, "PROJECT_PATH", "ELLIPSOID", ".quiet")
 
   # The dots are the default values and are not exposed as

R/qgis-help.R

@@ -4,6 +4,7 @@
 #'
 #' @param algorithm A qualified algorithm name
 #' (e.g., `"native:buffer"`).
+#' @param ... For internal use only.
 #'
 #' @returns
 #' - `qgis_get_description()`: a string.
@@ -47,9 +48,9 @@ extract_type_component <- function(param_element, component) {
 
 #' @rdname qgis_show_help
 #' @export
-qgis_get_argument_specs <- function(algorithm) {
+qgis_get_argument_specs <- function(algorithm, ...) {
   if (qgis_using_json_output()) {
-    help <- qgis_help_json(algorithm)
+    help <- qgis_help_json(algorithm, ...)
     out <- tibble::tibble(
       name = names(help$parameters),
       description = vapply(help$parameters, "[[", character(1), "description"),
@@ -64,19 +65,20 @@ qgis_get_argument_specs <- function(algorithm) {
     # The order of the parameters is alphabetized in JSON but has a
     # natural ordering in the parsed help text (which we need for backward
     # compatibility)
-    out_legacy <- qgis_parse_help(algorithm)$arguments
+    # Setting 'check_deprecation = FALSE' to avoid repetition of same warning
+    out_legacy <- qgis_parse_help(algorithm, check_deprecation = FALSE)$arguments
 
     out[match(out_legacy$name, out$name), ]
   } else {
-    qgis_parse_help(algorithm)$arguments
+    qgis_parse_help(algorithm, ...)$arguments
   }
 }
 
 #' @rdname qgis_show_help
 #' @export
-qgis_get_output_specs <- function(algorithm) {
+qgis_get_output_specs <- function(algorithm, ...) {
   if (qgis_using_json_output()) {
-    help <- qgis_help_json(algorithm)
+    help <- qgis_help_json(algorithm, ...)
     out <- tibble::tibble(
       name = names(help$outputs),
       description = vapply(help$outputs, "[[", character(1), "description"),
@@ -86,20 +88,20 @@ qgis_get_output_specs <- function(algorithm) {
     out[] <- lapply(out, unname)
     out
   } else {
-    qgis_parse_help(algorithm)$outputs
+    qgis_parse_help(algorithm, ...)$outputs
   }
 }
 
 #' @keywords internal
-qgis_help_json <- function(algorithm) {
+qgis_help_json <- function(algorithm, check_deprecation = TRUE) {
   cached <- help_cache_file(algorithm, json = TRUE)
   if (qgis_using_cached_help() && file.exists(cached)) {
-    check_algorithm_deprecation(algorithm)
+    check_algorithm_deprecation(algorithm, skip = !check_deprecation)
     try(return(jsonlite::fromJSON(readRDS(cached))))
   }
 
   assert_qgis()
-  assert_qgis_algorithm(algorithm)
+  assert_qgis_algorithm(algorithm, check_deprecation = check_deprecation)
 
   result <- qgis_run(
     args = c("--json", "help", algorithm),
@@ -114,15 +116,15 @@ qgis_help_json <- function(algorithm) {
   jsonlite::fromJSON(result$stdout)
 }
 
-qgis_help_text <- function(algorithm) {
+qgis_help_text <- function(algorithm, check_deprecation = TRUE) {
   cached <- help_cache_file(algorithm, json = FALSE)
   if (qgis_using_cached_help() && file.exists(cached)) {
-    check_algorithm_deprecation(algorithm)
+    check_algorithm_deprecation(algorithm, skip = !check_deprecation)
     try(return(readRDS(cached)))
   }
 
   assert_qgis()
-  assert_qgis_algorithm(algorithm)
+  assert_qgis_algorithm(algorithm, check_deprecation = check_deprecation)
 
   result <- qgis_run(
     args = c("help", algorithm)
@@ -136,8 +138,8 @@ qgis_help_text <- function(algorithm) {
   result$stdout
 }
 
-qgis_parse_help <- function(algorithm) {
-  help_text <- trimws(qgis_help_text(algorithm))
+qgis_parse_help <- function(algorithm, check_deprecation = TRUE) {
+  help_text <- trimws(qgis_help_text(algorithm, check_deprecation = check_deprecation))
 
   sec_description <- stringr::str_match(
     help_text,

R/qgis-output.R

@@ -4,7 +4,7 @@ qgis_parse_results <- function(algorithm, output) {
     outputs_list <- output_parsed$results
     output_names <- names(outputs_list)
 
-    algorithm_outputs <- qgis_get_output_specs(algorithm)
+    algorithm_outputs <- qgis_get_output_specs(algorithm, check_deprecation = FALSE)
 
     Map(
       qgis_result_output,
@@ -25,7 +25,7 @@ qgis_parse_results <- function(algorithm, output) {
     outputs_list <- lapply(outputs, "[", 2)
     output_names <- vapply(outputs, "[", 1, FUN.VALUE = character(1))
 
-    algorithm_outputs <- qgis_get_output_specs(algorithm)
+    algorithm_outputs <- qgis_get_output_specs(algorithm, check_deprecation = FALSE)
 
     outputs_list <- Map(
       qgis_parse_result_output,