Harmonise orderly_artefact() with orderly_dependency etc

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: orderly2
 Title: Orderly Next Generation
-Version: 1.99.22
+Version: 1.99.23
 Authors@R: c(person("Rich", "FitzJohn", role = c("aut", "cre"),
                     email = "[email protected]"),
              person("Robert", "Ashton", role = "aut"),

R/metadata.R

@@ -118,12 +118,8 @@ current_orderly_parameters <- function(src, envir) {
 ##' @return Undefined
 ##' @export
 orderly_description <- function(display = NULL, long = NULL, custom = NULL) {
-  if (!is.null(display)) {
-    assert_scalar_character(display, call = environment())
-  }
-  if (!is.null(long)) {
-    assert_scalar_character(long, call = environment())
-  }
+  assert_scalar_character(display, allow_null = TRUE, call = environment())
+  assert_scalar_character(long, allow_null = TRUE, call = environment())
   if (!is.null(custom)) {
     assert_named(custom, unique = TRUE, call = environment())
     assert_is(custom, "list", call = environment())
@@ -221,10 +217,30 @@ static_orderly_resource <- function(args) {
 ##' @return Undefined
 ##'
 ##' @export
-orderly_artefact <- function(description, files) {
-  assert_scalar_character(description, call = environment())
+orderly_artefact <- function(description = NULL, files) {
+  assert_scalar_character(description, allow_null = TRUE, call = environment())
   assert_character(files, call = environment()) # also check length >0 ?
 
+  call <- sys.call()
+  if (length(call) > 2 && !("description" %in% names(call))) {
+    description_str <- deparse1(call)
+    if (nchar(description_str) < 30) {
+      hint <- c(
+        i = "Use 'orderly_artefact(..., description = {description_str})'")
+    } else {
+      hint <- NULL
+    }
+    explanation <- paste(
+      "In future versions of orderly, we will change the order of the",
+      "arguments to 'orderly_artefact()' so that 'files' comes first.",
+      "If you name your calls to 'description' then you will be compatible",
+      "when we make this change.")
+    cli::cli_warn(c(
+      "Please use a named argument for the description in 'orderly_artefact()'",
+      hint,
+      explanation))
+  }
+
   p <- get_active_packet()
   if (!is.null(p)) {
     artefact <- list(description = description, files = files)
@@ -263,9 +279,7 @@ static_orderly_artefact <- function(args) {
 ##' @return Undefined
 ##' @export
 orderly_dependency <- function(name, query, files) {
-  if (!is.null(name)) {
-    assert_scalar_character(name, call = environment())
-  }
+  assert_scalar_character(name, allow_null = TRUE, call = environment())
 
   ctx <- orderly_context(rlang::caller_env())
   subquery <- NULL

R/outpack_config.R

@@ -224,9 +224,7 @@ config_set_path_archive <- function(value, root, call) {
 
 config_new <- function(path_archive, use_file_store, require_complete_tree,
                        call = NULL) {
-  if (!is.null(path_archive)) {
-    assert_scalar_character(path_archive, call = call)
-  }
+  assert_scalar_character(path_archive, allow_null = TRUE, call = call)
   assert_scalar_logical(use_file_store, call = call)
   if (is.null(path_archive) && !use_file_store) {
     stop("If 'path_archive' is NULL, then 'use_file_store' must be TRUE")

R/outpack_metadata.R

@@ -262,7 +262,8 @@ get_metadata_hash <- function(packet_id, root) {
 ## see run.R for the inverse of this
 custom_metadata_deserialise <- function(data) {
   data$artefacts <- data_frame(
-    description = vcapply(data$artefacts, "[[", "description"),
+    description = vcapply(data$artefacts,
+                          function(x) x$description %||% NA_character_),
     paths = I(lapply(data$artefacts, "[[", "paths")))
   data$role <- data_frame(
     path = vcapply(data$role, "[[", "path"),

R/util_assert.R

@@ -23,7 +23,11 @@ assert_logical <- function(x, name = deparse(substitute(x)), arg = name,
 }
 
 assert_scalar_character <- function(x, name = deparse(substitute(x)),
-                                    arg = name, call = NULL) {
+                                    arg = name, call = NULL,
+                                    allow_null = FALSE) {
+  if (is.null(x) && allow_null) {
+    return(invisible(x))
+  }
   assert_scalar(x, name, arg = arg, call = call)
   assert_character(x, name, arg = arg, call = call)
 }

inst/example/src/data/data.R

@@ -1,2 +1,2 @@
-orderly2::orderly_artefact("Final data", "data.rds")
+orderly2::orderly_artefact("data.rds", description = "Final data")
 saveRDS(mtcars, "data.rds")

inst/schema/orderly/orderly.json

@@ -11,7 +11,7 @@
                 "type": "object",
                 "properties": {
                     "description": {
-                        "type": "string"
+                        "type": ["null", "string"]
                     },
                     "paths": {
                         "comment": "Will match the set of paths in outpack",
@@ -20,7 +20,8 @@
                             "type": "string"
                         }
                     }
-                }
+                },
+                "required": ["description", "paths"]
             }
         },
         "shared": {

tests/testthat/examples/computed-resource/computed-resource.R

@@ -1,6 +1,6 @@
 files <- dir(pattern = "*.csv")
 orderly2::orderly_resource(files)
-orderly2::orderly_artefact("A graph of things", "mygraph.png")
+orderly2::orderly_artefact("mygraph.png", description = "A graph of things")
 
 data <- read.csv("data.csv", stringsAsFactors = FALSE)
 png("mygraph.png")

tests/testthat/examples/data/data.R

@@ -1,3 +1,3 @@
-orderly2::orderly_artefact("Some data", "data.rds")
+orderly2::orderly_artefact(files = "data.rds", description = "Some data")
 d <- data.frame(a = 1:10, x = runif(10), y = 1:10 + runif(10))
 saveRDS(d, "data.rds")

tests/testthat/examples/depends-params/depends-params.R

@@ -1,5 +1,5 @@
 orderly2::orderly_parameters(a = NULL)
 orderly2::orderly_dependency("parameters", "latest", c(input.rds = "data.rds"))
-orderly2::orderly_artefact("Processed data", "result.rds")
+orderly2::orderly_artefact("result.rds", description = "Processed data")
 d <- readRDS("input.rds")
 saveRDS(lapply(d, function(x) x * 2), "result.rds")

tests/testthat/examples/depends-query/depends-query.R

@@ -5,6 +5,6 @@ orderly2::orderly_dependency(
         "parameter:b == this:b &&",
         "parameter:c == this:c)"),
   c(input.rds = "data.rds"))
-orderly2::orderly_artefact("Processed data", "result.rds")
+orderly2::orderly_artefact("result.rds", description = "Processed data")
 d <- readRDS("input.rds")
 saveRDS(lapply(d, function(x) x * 2), "result.rds")

tests/testthat/examples/depends/depends.R

@@ -1,5 +1,5 @@
 orderly2::orderly_dependency("data", "latest", c(input.rds = "data.rds"))
-orderly2::orderly_artefact("Final plot", "graph.png")
+orderly2::orderly_artefact(description = "Final plot", files = "graph.png")
 d <- readRDS("input.rds")
 png("graph.png")
 plot(y ~ x, d)

tests/testthat/examples/deprecated-orderly-name/orderly.R

@@ -1,3 +1,3 @@
-orderly2::orderly_artefact("Some data", "data.rds")
+orderly2::orderly_artefact(description = "Some data", files = "data.rds")
 d <- data.frame(a = 1:10, x = runif(10), y = 1:10 + runif(10))
 saveRDS(d, "data.rds")

tests/testthat/examples/description/description.R

@@ -1,5 +1,5 @@
 orderly2::orderly_resource("data.csv")
-orderly2::orderly_artefact("A graph of things", "mygraph.png")
+orderly2::orderly_artefact("mygraph.png", description = "A graph of things")
 orderly2::orderly_description(
   "Packet with description",
   "A longer description. Perhaps multiple sentences",

tests/testthat/examples/directories/directories.R

@@ -1,6 +1,6 @@
 orderly2::orderly_strict_mode()
 orderly2::orderly_resource("data")
-orderly2::orderly_artefact("output files", "output")
+orderly2::orderly_artefact(files = "output", description = "output files")
 
 a <- read.csv("data/a.csv")
 b <- read.csv("data/b.csv")

tests/testthat/examples/explicit/explicit.R

@@ -1,5 +1,5 @@
 orderly2::orderly_resource("data.csv")
-orderly2::orderly_artefact("A graph of things", "mygraph.png")
+orderly2::orderly_artefact("mygraph.png", description = "A graph of things")
 
 data <- read.csv("data.csv", stringsAsFactors = FALSE)
 png("mygraph.png")

tests/testthat/examples/plugin/plugin.R

@@ -1,3 +1,3 @@
-orderly2::orderly_artefact("Generated data", "data.rds")
+orderly2::orderly_artefact("data.rds", description = "Generated data")
 example.random::numbers("dat", 10)
 saveRDS(dat, "data.rds")

tests/testthat/examples/programmatic-resource/programmatic-resource.R

@@ -4,7 +4,7 @@ if (use == "a") {
 } else {
   orderly2::orderly_resource("b.csv")
 }
-orderly2::orderly_artefact("final data", "data.rds")
+orderly2::orderly_artefact("data.rds", description = "final data")
 
 d <- read.csv(sprintf("%s.csv", use), stringsAsFactors = FALSE)
 saveRDS(d, "data.rds")

tests/testthat/examples/reexport/reexport.R

@@ -1,6 +1,6 @@
 orderly2::orderly_resource("data.csv")
-orderly2::orderly_artefact("A graph of things", "mygraph.png")
-orderly2::orderly_artefact("Original data", "data.csv")
+orderly2::orderly_artefact("mygraph.png", description = "A graph of things")
+orderly2::orderly_artefact("data.csv", description = "Original data")
 
 data <- read.csv("data.csv", stringsAsFactors = FALSE)
 png("mygraph.png")

tests/testthat/examples/resource-in-directory/resource-in-directory.R

@@ -1,4 +1,4 @@
-orderly2::orderly_artefact("data", "data.rds")
+orderly2::orderly_artefact(description = "data", files = "data.rds")
 a <- read.csv("data/a.csv")
 b <- read.csv("data/b.csv")
 saveRDS(list(a = a, b = b), "data.rds")

tests/testthat/examples/shared-dir/shared-dir.R

@@ -1,5 +1,5 @@
 orderly2::orderly_shared_resource(shared_data = "data")
-orderly2::orderly_artefact("combined data", "output.rds")
+orderly2::orderly_artefact("output.rds", description = "combined data")
 
 files <- dir("shared_data")
 dat <- lapply(file.path("shared_data", files), read.csv)

tests/testthat/examples/shared-shorthand/shared-shorthand.R

@@ -1,5 +1,5 @@
 orderly2::orderly_shared_resource("data.csv")
-orderly2::orderly_artefact("A graph of things", "mygraph.png")
+orderly2::orderly_artefact("mygraph.png", description = "A graph of things")
 
 data <- read.csv("data.csv", stringsAsFactors = FALSE)
 png("mygraph.png")

tests/testthat/examples/shared/shared.R

@@ -1,5 +1,5 @@
 orderly2::orderly_shared_resource(shared_data.csv = "data.csv")
-orderly2::orderly_artefact("A graph of things", "mygraph.png")
+orderly2::orderly_artefact("mygraph.png", description = "A graph of things")
 
 data <- read.csv("shared_data.csv", stringsAsFactors = FALSE)
 png("mygraph.png")

tests/testthat/examples/two-orderly-files/orderly.R

@@ -1,3 +1,3 @@
-orderly2::orderly_artefact("Some data", "data.rds")
+orderly2::orderly_artefact(description = "Some data", files = "data.rds")
 d <- data.frame(a = 1:10, x = runif(10), y = 1:10 + runif(10))
 saveRDS(d, "data.rds")

tests/testthat/examples/two-orderly-files/two-orderly-files.R

@@ -1,3 +1,3 @@
-orderly2::orderly_artefact("Some data", "data.rds")
+orderly2::orderly_artefact(description = "Some data", files = "data.rds")
 d <- data.frame(a = 1:10, x = runif(10), y = 1:10 + runif(10))
 saveRDS(d, "data.rds")

tests/testthat/test-run.R

@@ -72,7 +72,7 @@ test_that("error if declared artefacts are not produced", {
   path_src <- file.path(path, "src", "explicit", "explicit.R")
   code <- readLines(path_src)
   writeLines(c(
-    'orderly2::orderly_artefact("some data", "output.csv")',
+    'orderly2::orderly_artefact(files = "output.csv")',
     code),
     path_src)
   err <- expect_error(
@@ -863,7 +863,7 @@ test_that("can depend on a directory artefact", {
   fs::dir_create(path_src)
   writeLines(c(
     'orderly2::orderly_dependency("directories", "latest()", c(d = "output/"))',
-    'orderly2::orderly_artefact("data", "d.rds")',
+    'orderly2::orderly_artefact(files = "d.rds")',
     'd <- c(readRDS("d/a.rds", "d/b.rds"))',
     'saveRDS(d, "d.rds")'),
     file.path(path_src, "use.R"))
@@ -886,7 +886,7 @@ test_that("can depend on a directory artefact with trailing slash", {
   fs::dir_create(path_src)
   writeLines(c(
     'orderly2::orderly_dependency("directories", "latest()", "output/")',
-    'orderly2::orderly_artefact("data", "d.rds")',
+    'orderly2::orderly_artefact(files = "d.rds")',
     'd <- c(readRDS("output/a.rds", "output/b.rds"))',
     'saveRDS(d, "d.rds")'),
     file.path(path_src, "orderly.R"))
@@ -915,7 +915,7 @@ test_that("can compute dependencies", {
     '  "parameters",',
     '  "latest(parameter:a == environment:x)",',
     '  c(d.rds = "data.rds"))',
-    'orderly2::orderly_artefact("data", "d.rds")')
+    'orderly2::orderly_artefact(files = "d.rds")')
 
   writeLines(code, file.path(path_src, "use.R"))
   envir2 <- new.env()
@@ -1075,7 +1075,7 @@ test_that("can rename dependencies programmatically", {
   path_src <- file.path(path, "src", "use")
   fs::dir_create(path_src)
   writeLines(c(
-    'orderly2::orderly_artefact("data", "d.rds")',
+    'orderly2::orderly_artefact(files = "d.rds")',
     'p <- "x"',
     "orderly2::orderly_dependency(",
     '  "data", "latest()",',
@@ -1148,7 +1148,7 @@ test_that("can run example with artefacts and no resources", {
 
   envir <- new.env()
   ## previously this errored
-  prepend_lines(path_src, 'orderly2::orderly_artefact("plot", "mygraph.png")')
+  prepend_lines(path_src, 'orderly2::orderly_artefact(files = "mygraph.png")')
   id <- orderly_run_quietly("implicit", root = path, envir = envir)
   expect_true(file.exists(
     file.path(path, "archive", "implicit", id, "mygraph.png")))
@@ -1380,3 +1380,16 @@ test_that("can add a dependency on an id with no name", {
       query = sprintf('single(id == "%s")', id1),
       files = I(list(data_frame(here = "input.rds", there = "data.rds")))))
 })
+
+
+test_that("warn if description unnamed in artefact", {
+  path <- test_prepare_orderly_example("data")
+  path_src <- file.path(path, "src", "data", "data.R")
+  code <- readLines(path_src)
+  writeLines(sub("description = ", "", code), path_src)
+  envir <- new.env()
+  expect_warning(
+    suppressMessages(
+      orderly_run("data", root = path, envir = envir, echo = FALSE)),
+    "Please use a named argument")
+})