Handle deprecated algorithms explicitly

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: qgisprocess
 Title: Use 'QGIS' Processing Algorithms
-Version: 0.2.0.9002
+Version: 0.2.0.9003
 Authors@R: c(
     person("Dewey", "Dunnington", , "[email protected]", role = "aut",
            comment = c(ORCID = "0000-0002-9415-4582", affiliation = "Voltron Data")),

NAMESPACE

@@ -122,6 +122,7 @@ importFrom(assertthat,assert_that)
 importFrom(assertthat,is.flag)
 importFrom(assertthat,is.number)
 importFrom(assertthat,is.string)
+importFrom(assertthat,noNA)
 importFrom(glue,glue)
 importFrom(rlang,"%||%")
 importFrom(rlang,abort)

NEWS.md

@@ -2,6 +2,11 @@
 
 - More consistent and intuitive handling of JSON input / output user settings (#195, #196; see `?qgis_using_json_output`).
 - Fix bug in support for environment variable `R_QGISPROCESS_DETECT_NEWER_QGIS` (#197).
+- QGIS or third-party providers can expose deprecated algorithms that may be removed from future versions.
+`{qgisprocess}` now handles these algorithms explicitly (#198):
+  - `qgis_run_algorithm()` and other functions (such as `qgis_show_help()` and `qgis_get_description()`) will warn if a deprecated algorithm is passed (feature request #194; original issue #193).
+  - `qgis_search_algorithms()` now **excludes** deprecated algorithms by default; they can still be included by setting the `include_deprecated` argument to `TRUE`.
+  - `qgis_algorithms()` can _optionally_ restrict its results to non-deprecated algorithms (set the `include_deprecated` argument to `FALSE`). By default they are included, just as before.
 
 # qgisprocess 0.2.0
 

R/qgis-algorithms.R

@@ -7,6 +7,10 @@
 #' for a detailed description of the algorithms provided
 #' 'out of the box' on QGIS.
 #'
+#' The `include_deprecated` argument in `qgis_algorithms()` does not affect the
+#' cached value. The latter always includes deprecated algorithms if these are
+#' returned by 'qgis_process' (this requires the JSON output method).
+#'
 #' @family topics about information on algorithms & processing providers
 #' @family topics about reporting the QGIS state
 #' @concept functions to manage and explore QGIS and qgisprocess
@@ -16,6 +20,7 @@
 #' status in QGIS (enabled or disabled).
 #' Must be one of: `"all"`, `"enabled"`, `"disabled"`.
 #' @param ... Only used by other functions calling this function.
+#' @param include_deprecated Logical. Should deprecated algorithms be included?
 #' @inheritParams qgis_path
 #'
 #' @returns
@@ -25,11 +30,18 @@
 #'
 #' @examplesIf has_qgis()
 #' qgis_algorithms()
+#' qgis_algorithms(include_deprecated = FALSE)
 #' qgis_providers()
 #' qgis_plugins(quiet = FALSE)
 #' qgis_plugins(which = "disabled")
 #'
-qgis_algorithms <- function(query = FALSE, quiet = TRUE) {
+qgis_algorithms <- function(
+    query = FALSE,
+    quiet = TRUE,
+    include_deprecated = TRUE) {
+  assert_that(is.flag(query), noNA(query))
+  assert_that(is.flag(quiet), noNA(quiet))
+  assert_that(is.flag(include_deprecated), noNA(include_deprecated))
   if (query) {
     qgisprocess_cache$algorithms <- qgis_query_algorithms(quiet = quiet)
   }
@@ -38,13 +50,25 @@ qgis_algorithms <- function(query = FALSE, quiet = TRUE) {
     "access to { nrow(qgisprocess_cache$algorithms) } algorithms ",
     "from { nrow(qgis_providers()) } QGIS processing providers."
   ))
-  qgisprocess_cache$algorithms
+  algs <- qgisprocess_cache$algorithms
+  if (!include_deprecated && "deprecated" %in% colnames(algs)) {
+    algs[!algs$deprecated, ]
+  } else {
+    algs
+  }
 }
 
 #' @rdname qgis_algorithms
 #' @export
-qgis_providers <- function(query = FALSE, quiet = TRUE) {
-  algs <- qgis_algorithms(query = query, quiet = quiet)
+qgis_providers <- function(
+    query = FALSE,
+    quiet = TRUE,
+    include_deprecated = TRUE) {
+  algs <- qgis_algorithms(
+    query = query,
+    quiet = quiet,
+    include_deprecated = include_deprecated
+  )
   counted <- stats::aggregate(
     algs[[1]],
     by = list(algs$provider, algs$provider_title),
@@ -70,10 +94,29 @@ assert_qgis_algorithm <- function(algorithm) {
     )
   }
 
+  check_algorithm_deprecation(algorithm)
+
   invisible(algorithm)
 }
 
 
+#' @keywords internal
+check_algorithm_deprecation <- function(algorithm) {
+  algs <- qgis_algorithms()
+  if ("deprecated" %in% colnames(algs)) {
+    deprecated_algs <- algs$algorithm[algs$deprecated]
+    if (algorithm %in% deprecated_algs) {
+      warning(
+        glue(
+          "Algorithm '{ algorithm }' is deprecated and may be removed in a later ",
+          "QGIS version!\nCurrently using QGIS { qgis_version() }."
+        ),
+        call. = FALSE
+      )
+    }
+  }
+}
+
 
 #' @keywords internal
 qgis_query_algorithms <- function(quiet = FALSE) {
@@ -228,6 +271,7 @@ qgis_query_algorithms <- function(quiet = FALSE) {
 #' `provider_title` value from the output of [qgis_algorithms()].
 #' @param group Regular expression to match the `group` value
 #' from the output of [qgis_algorithms()].
+#' @inheritParams qgis_algorithms
 #'
 #' @returns A tibble.
 #'
@@ -241,12 +285,17 @@ qgis_query_algorithms <- function(quiet = FALSE) {
 qgis_search_algorithms <- function(
     algorithm = NULL,
     provider = NULL,
-    group = NULL) {
+    group = NULL,
+    include_deprecated = FALSE) {
   assert_that(
     !is.null(algorithm) || !is.null(provider) || !is.null(group),
     msg = "You must provide at least one of the arguments."
   )
-  result <- qgis_algorithms(query = FALSE, quiet = TRUE)
+  result <- qgis_algorithms(
+    query = FALSE,
+    quiet = TRUE,
+    include_deprecated = include_deprecated
+  )
   assert_that(inherits(result, "data.frame"))
   assert_that(
     nrow(result) > 0L,

R/qgis-help.R

@@ -94,6 +94,7 @@ qgis_get_output_specs <- function(algorithm) {
 qgis_help_json <- function(algorithm) {
   cached <- help_cache_file(algorithm, json = TRUE)
   if (qgis_using_cached_help() && file.exists(cached)) {
+    check_algorithm_deprecation(algorithm)
     try(return(jsonlite::fromJSON(readRDS(cached))))
   }
 
@@ -116,6 +117,7 @@ qgis_help_json <- function(algorithm) {
 qgis_help_text <- function(algorithm) {
   cached <- help_cache_file(algorithm, json = FALSE)
   if (qgis_using_cached_help() && file.exists(cached)) {
+    check_algorithm_deprecation(algorithm)
     try(return(readRDS(cached)))
   }
 

R/qgisprocess-package.R

@@ -13,6 +13,7 @@
 #' @importFrom assertthat
 #' assert_that
 #' is.flag
+#' noNA
 #' is.string
 #' is.number
 ## usethis namespace: end

tests/testthat/test-qgis-algorithms.R

@@ -4,6 +4,7 @@ test_that("qgis_algorithms() works", {
   expect_true(tibble::is_tibble(algs))
   expect_gt(nrow(algs), 200)
   expect_gt(ncol(algs), 20)
+  expect_gte(nrow(algs), nrow(qgis_algorithms(include_deprecated = FALSE)))
   old_names <- c(
     "provider", "provider_title", "algorithm",
     "algorithm_id", "algorithm_title"
@@ -23,12 +24,28 @@ test_that("qgis_providers() works", {
   )
 })
 
-test_that("assert_qgis_algorithm() works", {
+test_that("Internal function assert_qgis_algorithm() works", {
   skip_if_not(has_qgis())
   expect_error(assert_qgis_algorithm("notanalgorithm"))
   expect_identical(assert_qgis_algorithm("native:filedownloader"), "native:filedownloader")
 })
 
+test_that("Internal function check_algorithm_deprecation() works", {
+  skip_if_not(has_qgis())
+  algs <- qgis_algorithms()
+  skip_if_not(
+    "deprecated" %in% colnames(algs) && sum(algs$deprecated) > 0,
+    paste(
+      "There are no deprecated algorithms available.",
+      "Unless using no-JSON output, rewrite this test to simulate deprecated algorithms."
+    )
+  )
+  alg_deprecated <- sample(algs$algorithm[algs$deprecated], 1)
+  alg_non_deprecated <- sample(algs$algorithm[!algs$deprecated], 1)
+  expect_warning(check_algorithm_deprecation(alg_deprecated))
+  expect_no_warning(check_algorithm_deprecation(alg_non_deprecated))
+})
+
 test_that("qgis_search_algorithms() works", {
   skip_if_not(has_qgis())
   expect_error(qgis_search_algorithms(), "at least one of the arguments")
@@ -46,4 +63,7 @@ test_that("qgis_search_algorithms() works", {
   expect_gt(nrow(res1), 0L)
   res2 <- qgis_search_algorithms(algorithm = "point.*line")
   expect_gt(nrow(res2), nrow(res1))
+  res3 <- qgis_search_algorithms(algorithm = "raster")
+  res4 <- qgis_search_algorithms(algorithm = "raster", include_deprecated = TRUE)
+  expect_gte(nrow(res4), nrow(res3))
 })