Update pin_upload() args (#809)

* Update `pin_upload()` args

* Update NEWS, docs

* Add test for new `...` message

* Update NEWS

NEWS.md

@@ -1,4 +1,10 @@
-# pins (development version)
+# pins (development version, to be released as 1.4.0)
+
+## Lifecycle changes
+
+* Changed the function signature of `pin_upload()` to be consistent with `pin_write()` i.e. arguments like `tags` must be passed by name and not position (#809).
+
+## Other improvements
 
 * Added example Python code to pin previews for Posit Connect (#806).
 

R/pin-upload-download.R

@@ -28,8 +28,21 @@ pin_download <- function(board, name, version = NULL, hash = NULL, ...) {
 #' @export
 #' @rdname pin_download
 #' @param paths A character vector of file paths to upload to `board`.
-pin_upload <- function(board, paths, name = NULL, title = NULL, description = NULL, metadata = NULL, ...) {
+pin_upload <- function(board,
+                       paths,
+                       name = NULL,
+                       ...,
+                       title = NULL,
+                       description = NULL,
+                       metadata = NULL,
+                       tags = NULL,
+                       urls = NULL) {
   check_board(board, "pin_upload", "pin")
+  dots <- list2(...)
+  if (!missing(...) && (is.null(names(dots)) || names(dots)[[1]] == "")) {
+    cli::cli_abort('Arguments after the dots `...` must be named, like {.code tags = "my-great-tag"}.')
+  }
+
 
   if (!is.character(paths)) {
     abort("`path` must be a character vector")
@@ -48,6 +61,10 @@ pin_upload <- function(board, paths, name = NULL, title = NULL, description = NU
     check_pin_name(name)
   }
 
+  check_metadata(metadata)
+  check_character(tags, allow_null = TRUE)
+  check_character(urls, allow_null = TRUE)
+
   # Expand any directories
   is_dir <- fs::is_dir(paths)
   if (any(is_dir)) {
@@ -60,10 +77,11 @@ pin_upload <- function(board, paths, name = NULL, title = NULL, description = NU
     paths = paths,
     type = "file",
     title = title %||% default_title(name, path = paths),
-    description = description
+    description = description,
+    tags = tags,
+    urls = urls
   )
   meta$user <- metadata
 
   invisible(pin_store(board, name, paths, meta, ...))
 }
-

tests/testthat/_snaps/pin-upload-download.md

@@ -16,6 +16,11 @@
     Message
       Guessing `name = 'test.txt'`
       Creating new version '20120304T050607Z-xxxxx'
+    Code
+      pin_upload(board, path, "test", c("blue", "green"))
+    Condition
+      Error in `pin_upload()`:
+      ! Arguments after the dots `...` must be named, like `tags = "my-great-tag"`.
 
 # can pin file called data.txt
 

tests/testthat/test-pin-upload-download.R

@@ -20,6 +20,7 @@ test_that("pin_upload generated useful messages", {
 
     path <- fs::file_touch(fs::path_temp("test.txt"))
     pin_upload(board, path)
+    pin_upload(board, path, "test", c("blue", "green"))
   })
 })
 
@@ -51,10 +52,11 @@ test_that("user can supply metadata", {
   writeLines("Hi!", path1)
 
   board <- board_temp()
-  pin_upload(board, path1, "x", metadata = list(name = "Susan"), desc = "A vector")
+  pin_upload(board, path1, "x", metadata = list(name = "Susan"), description = "A vector", tags = c("blue", "green"))
   meta <- pin_meta(board, "x")
   expect_equal(meta$user, list(name = "Susan"))
   expect_equal(meta$description, "A vector")
+  expect_equal(meta$tags, c("blue", "green"))
 })
 
 test_that("informative error for legacy boards", {