Merge pull request #194 from mrc-ide/gh-146

Rename "pull" functions
mrc-ide · Oct 24, 2024 · 478e76e · 478e76e
2 parents 00dd499 + b609505
commit 478e76e
Show file tree

Hide file tree

Showing 47 changed files with 362 additions and 243 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: orderly2
 Title: Orderly Next Generation
-Version: 1.99.52
+Version: 1.99.53
 Authors@R: c(person("Rich", "FitzJohn", role = c("aut", "cre"),
                     email = "[email protected]"),
              person("Robert", "Ashton", role = "aut"),

diff --git a/NAMESPACE b/NAMESPACE
@@ -26,7 +26,9 @@ export(orderly_location_add)
 export(orderly_location_add_http)
 export(orderly_location_add_packit)
 export(orderly_location_add_path)
+export(orderly_location_fetch_metadata)
 export(orderly_location_list)
+export(orderly_location_pull)
 export(orderly_location_pull_metadata)
 export(orderly_location_pull_packet)
 export(orderly_location_push)

diff --git a/R/compare.R b/R/compare.R
@@ -31,7 +31,7 @@ compare_filesets <- function(target, current) {
 ##'
 ##' @param target The id of the packet to use in the comparison.
 ##' @param current The id of the other packet against which to compare.
-##' @inheritParams orderly_search_options
+##' @inheritParams orderly_search
 ##' @inheritParams orderly_metadata
 ##' @return An object of class orderly_comparison. The object can be printed to
 ##'  get a summary description of the differences, or passed to
@@ -41,18 +41,18 @@ compare_filesets <- function(target, current) {
 orderly_compare_packets <- function(target, current,
                                     location = NULL,
                                     allow_remote = NULL,
-                                    pull_metadata = FALSE,
+                                    fetch_metadata = FALSE,
                                     root = NULL) {
   root <- root_open(root, require_orderly = FALSE)
   validate_outpack_id(target, call = environment())
   validate_outpack_id(current, call = environment())
 
   options <- build_search_options(location = location,
                                   allow_remote = allow_remote,
-                                  pull_metadata = pull_metadata)
+                                  fetch_metadata = fetch_metadata)
 
-  if (options$pull_metadata) {
-    orderly_location_pull_metadata(options$location, root = root)
+  if (options$fetch_metadata) {
+    orderly_location_fetch_metadata(options$location, root = root)
   }
 
   target_metadata <- orderly_metadata(target, root = root)
@@ -115,7 +115,7 @@ compare_file_contents <- function(cmp, files) {
   # very straightforward, and covers the case where the file only exists
   # remotely transparent.
   #
-  # pull_metadata is intentionally hardcoded to FALSE, regardless of what the
+  # fetch_metadata is intentionally hardcoded to FALSE, regardless of what the
   # user may have specified as an argument to orderly_compare_packets: the
   # latter would have already pulled the files once, and we don't need to do it
   # again.
@@ -124,15 +124,15 @@ compare_file_contents <- function(cmp, files) {
                      files = files,
                      location = cmp$search_options$location,
                      allow_remote = cmp$search_options$allow_remote,
-                     pull_metadata = FALSE,
+                     fetch_metadata = FALSE,
                      root = cmp$root)
 
   orderly_copy_files(cmp$current$id,
                      dest = path_current,
                      files = files,
                      location = cmp$search_options$location,
                      allow_remote = cmp$search_options$allow_remote,
-                     pull_metadata = FALSE,
+                     fetch_metadata = FALSE,
                      root = cmp$root)
 
 

diff --git a/R/deprecated.R b/R/deprecated.R
@@ -0,0 +1,22 @@
+##' Deprecated functions in orderly2. These functions still work (*for
+##' now*) but will be removed shortly.  Please update your code.
+##'
+##' * `orderly_location_pull_packet`; please use [orderly_location_pull()]
+##' * `orderly_location_pull_metadata`; please use
+##'   [orderly_location_fetch_metadata()]
+##'
+##' @param ... Arguments forwarded to the new version
+##' @return See the linked pages above for the current return type.
+##' @rdname orderly2-deprecated
+##' @name orderly2-deprecated
+NULL
+
+
+deprecate_warn <- function(old, new, body = NULL) {
+  cli::cli_warn(
+    c(paste("'{old}()' is deprecated and will be removed soon, please",
+            "use '{new}()' instead"),
+      body),
+    .frequency = "regularly",
+    .frequency_id = paste0("orderly_deprecate:", old))
+}
diff --git a/R/interactive.R b/R/interactive.R
@@ -75,16 +75,16 @@ detect_orderly_interactive_path <- function(
 ##'
 ##' @title Set search options for interactive use
 ##'
-##' @inheritParams orderly_search_options
+##' @inheritParams orderly_search
 ##'
 ##' @return Nothing, called for its side effects
 ##' @export
 orderly_interactive_set_search_options <- function(location = NULL,
                                                    allow_remote = NULL,
-                                                   pull_metadata = FALSE) {
+                                                   fetch_metadata = FALSE) {
   options <- build_search_options(location = location,
                                   allow_remote = allow_remote,
-                                  pull_metadata = pull_metadata)
+                                  fetch_metadata = fetch_metadata)
   .interactive$search_options <- options
 }
 

diff --git a/R/location.R b/R/location.R
@@ -3,7 +3,7 @@
 ##' based locations are supported, with limited support for custom
 ##' locations. Note that adding a location does *not* pull metadata
 ##' from it, you need to call
-##' [orderly2::orderly_location_pull_metadata] first.  The function
+##' [orderly2::orderly_location_fetch_metadata] first.  The function
 ##' `orderly_location_add` can add any sort of location, but the other
 ##' functions documented here (`orderly_location_add_path`, etc) will
 ##' typically be much easier to use in practice.
@@ -290,7 +290,7 @@ orderly_location_remove <- function(name, root = NULL) {
 ##'   `args`.  The `args` column is a list column, with each element
 ##'   being the key-value pair arguments to the location.
 ##'
-##' @seealso [orderly2::orderly_location_pull_metadata], which can
+##' @seealso [orderly2::orderly_location_fetch_metadata], which can
 ##'   update your outpack index with metadata from any of the
 ##'   locations listed here.
 ##'
@@ -305,11 +305,11 @@ orderly_location_list <- function(verbose = FALSE, root = NULL) {
 }
 
 
-##' Pull metadata from a location, updating the index.  This should
+##' Fetch metadata from a location, updating the index.  This should
 ##' always be relatively quick as it updates only small files that
 ##' contain information about what can be found in remote packets.
 ##'
-##' @title Pull metadata from a location
+##' @title Fetch metadata from a location
 ##'
 ##' @param location The name of a location to pull from (see
 ##'   [orderly2::orderly_location_list] for possible values).  If not
@@ -322,7 +322,7 @@ orderly_location_list <- function(verbose = FALSE, root = NULL) {
 ##' @return Nothing
 ##'
 ##' @export
-orderly_location_pull_metadata <- function(location = NULL, root = NULL) {
+orderly_location_fetch_metadata <- function(location = NULL, root = NULL) {
   root <- root_open(root, require_orderly = FALSE)
   location_name <- location_resolve_valid(location, root,
                                           include_local = FALSE,
@@ -333,7 +333,7 @@ orderly_location_pull_metadata <- function(location = NULL, root = NULL) {
     "Fetching metadata from {length(location_name)} location{?s}:",
     "{squote({location_name})}"))
   for (name in location_name) {
-    res <- location_pull_metadata(name, root)
+    res <- location_fetch_metadata(name, root)
     if (res$total > 0) {
       cli_alert_success(paste(
         "Found {res$total} packet{?s} at '{name}', of which",
@@ -357,6 +357,17 @@ orderly_location_pull_metadata <- function(location = NULL, root = NULL) {
 }
 
 
+##' @rdname orderly2-deprecated
+##' @keywords internal
+##' @export
+orderly_location_pull_metadata <- function(...) {
+  deprecate_warn(
+    "orderly_location_pull_metadata",
+    "orderly_location_fetch_metadata")
+  orderly_location_fetch_metadata(...)
+}
+
+
 ##' Pull one or more packets (including all their files) into this
 ##' archive from one or more of your locations. This will make files
 ##' available for use as dependencies (e.g., with
@@ -382,15 +393,15 @@ orderly_location_pull_metadata <- function(location = NULL, root = NULL) {
 ##'
 ##' @return Invisibly, the ids of packets that were pulled
 ##' @export
-orderly_location_pull_packet <- function(expr,
-                                         name = NULL,
-                                         location = NULL,
-                                         pull_metadata = FALSE,
-                                         recursive = NULL,
-                                         options = NULL,
-                                         root = NULL) {
+orderly_location_pull <- function(expr,
+                                  name = NULL,
+                                  location = NULL,
+                                  fetch_metadata = FALSE,
+                                  recursive = NULL,
+                                  options = NULL,
+                                  root = NULL) {
   root <- root_open(root, require_orderly = FALSE)
-  compatibility_fix_options(options, "orderly_location_pull_packet")
+  compatibility_fix_options(options, "orderly_location_pull")
 
   if (expr_is_literal_id(expr, name)) {
     ids <- expr
@@ -399,16 +410,16 @@ orderly_location_pull_packet <- function(expr,
                           name = name,
                           location = location,
                           allow_remote = TRUE,
-                          pull_metadata = pull_metadata,
+                          fetch_metadata = fetch_metadata,
                           root = root)
   }
 
   if (length(ids) == 0 || (length(ids) == 1 && is.na(ids))) {
-    if (!pull_metadata) {
+    if (!fetch_metadata) {
       hint <- c(i = paste("Did you forget to pull metadata? You can do this",
-                          "by using the argument {.code pull_metadata = TRUE}",
-                          "in the call to 'orderly_location_pull_packet()', or",
-                          "by running 'orderly_location_pull_metadata()'"))
+                          "by using the argument {.code fetch_metadata = TRUE}",
+                          "in the call to 'orderly_location_pull()', or",
+                          "by running 'orderly_location_fetch_metadata()'"))
     } else {
       hint <- NULL
     }
@@ -462,6 +473,19 @@ orderly_location_pull_packet <- function(expr,
 }
 
 
+##' @rdname orderly2-deprecated
+##' @keywords internal
+##' @export
+orderly_location_pull_packet <- function(...) {
+  deprecate_warn(
+    "orderly_location_pull_packet",
+    "orderly_location_pull",
+    c(i = paste("We like 'orderly_location_pull' as the inverse of",
+                "'orderly_location_push'")))
+  orderly_location_pull(...)
+}
+
+
 ##' Push tree to location. This function works out what packets are
 ##' not known at the location and then what files are required to
 ##' create them. It then pushes all the files required to build all
@@ -525,7 +549,7 @@ orderly_location_push <- function(expr, location, name = NULL, dry_run = FALSE,
       driver <- location_driver(location_name, root)
       location_push_files(plan$files, driver, root)
       location_push_metadata(plan$packet_id, driver, root)
-      orderly_location_pull_metadata(location_name, root)
+      orderly_location_fetch_metadata(location_name, root)
     }
   }
 
@@ -614,7 +638,8 @@ orderly_location_custom <- function(driver, ...) {
 }
 
 
-location_pull_metadata <- function(location_name, root, call = parent.frame()) {
+location_fetch_metadata <- function(location_name, root,
+                                    call = parent.frame()) {
   index <- root$index$data()
   driver <- location_driver(location_name, root)
 
@@ -825,7 +850,8 @@ location_build_pull_plan_location <- function(packets, location, root, call) {
     } else {
       ## In the case where the above is used, we probably have
       ## up-to-date metadata so we don't display this.
-      hint <- "Do you need to run 'orderly2::orderly_location_pull_metadata()'?"
+      hint <- paste("Do you need to run",
+                    "{.run orderly2::orderly_location_fetch_metadata()}?")
     }
     cli::cli_abort(c("Failed to find packet{?s} {squote(missing)}",
                      i = "Looked in location{?s} {squote(location_name)}",

diff --git a/R/metadata.R b/R/metadata.R
@@ -305,7 +305,7 @@ orderly_dependency <- function(name, query, files) {
       parameters = ctx$parameters,
       location = search_options$location,
       allow_remote = search_options$allow_remote,
-      pull_metadata = search_options$pull_metadata,
+      fetch_metadata = search_options$fetch_metadata,
       envir = ctx$envir,
       root = ctx$root)
   }

diff --git a/R/outpack_config.R b/R/outpack_config.R
@@ -126,7 +126,7 @@ config_set_require_complete_tree <- function(value, root, call) {
   if (value) {
     id <- root$index$unpacked()
     if (length(id) > 0) {
-      orderly_location_pull_packet(id, recursive = TRUE, root = root)
+      orderly_location_pull(id, recursive = TRUE, root = root)
     }
   }
 

diff --git a/R/outpack_helpers.R b/R/outpack_helpers.R
@@ -22,7 +22,7 @@
 ##'   it's not unpacked but also not known to be present in some other
 ##'   remote) then this will fail because it's impossible to resolve
 ##'   the files. Consider refreshing the metadata with
-##'   [orderly2::orderly_location_pull_metadata] to refresh this.
+##'   [orderly2::orderly_location_fetch_metadata] to refresh this.
 ##' * if the `id` is not unpacked *and* no local copy of the files
 ##'   referred to can be found, we error by default (but see the next
 ##'   option). However, sometimes the file you refer to might also be
@@ -32,7 +32,7 @@
 ##' * if the `id` is not unpacked, there is no local copy of the file
 ##'   and if `allow_remote` is `TRUE` we will try and request the file
 ##'   from whatever remote would be selected by
-##'   [orderly2::orderly_location_pull_packet] for this packet.
+##'   [orderly2::orderly_location_pull] for this packet.
 ##'
 ##' Note that empty directories might be created on failure.
 ##'
@@ -82,7 +82,7 @@
 ##' @export
 orderly_copy_files <- function(expr, files, dest, overwrite = TRUE,
                                name = NULL, location = NULL,
-                               allow_remote = NULL, pull_metadata = FALSE,
+                               allow_remote = NULL, fetch_metadata = FALSE,
                                parameters = NULL, options = NULL,
                                envir = parent.frame(),
                                root = NULL) {
@@ -92,7 +92,7 @@ orderly_copy_files <- function(expr, files, dest, overwrite = TRUE,
   ## allow_remote later in error messages.
   options <- build_search_options(location = location,
                                   allow_remote = allow_remote,
-                                  pull_metadata = pull_metadata)
+                                  fetch_metadata = fetch_metadata)
 
   ## Validate files and dest early; it gives a better error where this
   ## was not provided with names.
@@ -112,7 +112,7 @@ orderly_copy_files <- function(expr, files, dest, overwrite = TRUE,
                          parameters = parameters,
                          location = options$location,
                          allow_remote = options$allow_remote,
-                         pull_metadata = options$pull_metadata,
+                         fetch_metadata = options$fetch_metadata,
                          root = root)
     if (length(id) > 1) {
       cli::cli_abort(

diff --git a/R/outpack_packet.R b/R/outpack_packet.R
@@ -177,7 +177,7 @@ outpack_packet_use_dependency <- function(packet, query, files,
                        envir = envir,
                        location = search_options$location,
                        allow_remote = search_options$allow_remote,
-                       pull_metadata = search_options$pull_metadata,
+                       fetch_metadata = search_options$fetch_metadata,
                        root = packet$root)
   if (is.na(id)) {
     explanation <- orderly_query_explain(
@@ -195,13 +195,13 @@ outpack_packet_use_dependency <- function(packet, query, files,
     packet$root$config$core$require_complete_tree &&
     !(id %in% packet$root$index$unpacked())
   if (needs_pull) {
-    orderly_location_pull_packet(id, root = packet$root)
+    orderly_location_pull(id, root = packet$root)
   }
 
   result <- orderly_copy_files(id, files = files, dest = packet$path,
                                location = search_options$location,
                                allow_remote = search_options$allow_remote,
-                               pull_metadata = search_options$pull_metadata,
+                               fetch_metadata = search_options$fetch_metadata,
                                overwrite = overwrite,
                                envir = envir,
                                root = packet$root)

diff --git a/R/outpack_tools.R b/R/outpack_tools.R
@@ -198,7 +198,8 @@
 ##'
 ##' @export
 orderly_metadata_extract <- function(expr = NULL, name = NULL, location = NULL,
-                                     allow_remote = NULL, pull_metadata = FALSE,
+                                     allow_remote = NULL,
+                                     fetch_metadata = FALSE,
                                      extract = NULL, options = NULL,
                                      root = NULL) {
   root <- root_open(root, require_orderly = FALSE)
@@ -211,7 +212,7 @@ orderly_metadata_extract <- function(expr = NULL, name = NULL, location = NULL,
                           name = name,
                           location = location,
                           allow_remote = allow_remote,
-                          pull_metadata = pull_metadata,
+                          fetch_metadata = fetch_metadata,
                           root = root)
   }
   extract <- parse_extract(extract, environment())