From 18ac0777174a80be06913d8c61996d32cf73bae8 Mon Sep 17 00:00:00 2001
From: Scott Chamberlain <sachamber@fredhutch.org>
Date: Tue, 19 Mar 2024 13:45:48 -0700
Subject: [PATCH] fix #44 aws_bucket_delete return NULL invisibly; other fixes
 for examples for bucket files

---
 R/bucket.R                        | 72 ++++++++++++++++++++++---------
 R/files.R                         |  2 +
 man/aws_bucket_delete.Rd          | 17 +++++---
 man/aws_bucket_download.Rd        |  4 +-
 man/aws_bucket_list_objects.Rd    | 13 ++++--
 man/aws_bucket_tree.Rd            | 26 +++++++++--
 man/aws_bucket_upload.Rd          | 18 +++++---
 man/aws_file_upload.Rd            |  2 +
 man/aws_policy_document_create.Rd |  6 +--
 9 files changed, 115 insertions(+), 45 deletions(-)

diff --git a/R/bucket.R b/R/bucket.R
index 692c040..0ab7d68 100644
--- a/R/bucket.R
+++ b/R/bucket.R
@@ -70,12 +70,14 @@ bucket_create_if_not <- function(bucket, force = FALSE) {
 #' @note Requires the env var `AWS_REGION`. This function prompts you to make
 #' sure that you want to delete the bucket.
 #' @family buckets
-#' @return an empty list
-#' @examples \dontrun{
-#' aws_bucket_create(bucket = "bucket-to-delete-111")
-#' aws_buckets()
-#' aws_bucket_delete(bucket = "bucket-to-delete-111")
-#' aws_buckets()
+#' @return `NULL`, invisibly
+#' @examplesIf interactive()
+#' bucket_name <- "bucket-to-delete-113"
+#' if (!aws_bucket_exists(bucket_name)) {
+#'  aws_bucket_create(bucket = bucket_name)
+#'  aws_buckets()
+#'  aws_bucket_delete(bucket = bucket_name)
+#'  aws_buckets()
 #' }
 aws_bucket_delete <- function(bucket, force = FALSE, ...) {
   # TODO: add a package level option to override the prompt for adv. users
@@ -85,6 +87,7 @@ aws_bucket_delete <- function(bucket, force = FALSE, ...) {
     }
   }
   env64$s3$delete_bucket(Bucket = bucket, ...)
+  return(invisible())
 }
 
 #' Download an S3 bucket
@@ -96,7 +99,7 @@ aws_bucket_delete <- function(bucket, force = FALSE, ...) {
 #' @note Requires the env var `AWS_REGION`. This function prompts you to make
 #' sure that you want to delete the bucket.
 #' @family buckets
-#' @examples \dontrun{
+#' @examplesIf interactive()
 #' aws_bucket_create(bucket = "tmp-bucket-369")
 #' desc_file <- file.path(system.file(), "DESCRIPTION")
 #' aws_file_upload(bucket = "tmp-bucket-369", path = desc_file)
@@ -106,7 +109,6 @@ aws_bucket_delete <- function(bucket, force = FALSE, ...) {
 #'
 #' # cleanup
 #' aws_bucket_delete("tmp-bucket-369")
-#' }
 aws_bucket_download <- function(bucket, dest_path, ...) {
   s3fs::s3_dir_download(path = bucket, new_path = dest_path, ...)
 }
@@ -123,21 +125,24 @@ aws_bucket_download <- function(bucket, dest_path, ...) {
 #' @note Requires the env var `AWS_REGION`. This function prompts you to make
 #' sure that you want to delete the bucket.
 #' @family buckets
-#' @examples \dontrun{
+#' @details To upload individual files see [aws_file_upload()]
+#' @examplesIf interactive()
 #' library(fs)
 #' tdir <- path(tempdir(), "apples")
 #' dir.create(tdir)
 #' tfiles <- replicate(n = 10, file_temp(tmp_dir = tdir, ext = ".txt"))
 #' invisible(lapply(tfiles, function(x) write.csv(mtcars, x)))
 #'
-#' aws_bucket_upload(path = tdir, bucket = "a-new-bucket-345")
-#' aws_bucket_list_objects("a-new-bucket-345")
+#' bucket_name <- "a-new-bucket-345"
+#' if (!aws_bucket_exists(bucket_name)) aws_bucket_create(bucket_name)
+#' aws_bucket_upload(path = tdir, bucket = bucket_name)
+#' aws_bucket_list_objects(bucket_name)
 #'
 #' # cleanup
-#' objs <- aws_bucket_list_objects("a-new-bucket-345")
+#' objs <- aws_bucket_list_objects(bucket_name)
 #' aws_file_delete(objs$uri)
-#' aws_bucket_delete("a-new-bucket-345")
-#' }
+#' aws_bucket_delete(bucket_name, force=TRUE)
+#' aws_bucket_exists(bucket_name)
 aws_bucket_upload <- function(
     path, bucket, max_batch = fs::fs_bytes("100MB"),
     ...) {
@@ -171,9 +176,15 @@ aws_bucket_upload <- function(
 #' * owner (character)
 #' * etag (character)
 #' * last_modified (dttm)
-#' @examples \dontrun{
-#' aws_bucket_list_objects(bucket = "s64-test-2")
-#' }
+#' @examplesIf interactive()
+#' bucket_name <- "s64-test-67"
+#' if (!aws_bucket_exists(bucket_name)) aws_bucket_create(bucket_name)
+#' links_file <- file.path(system.file(), "Meta/links.rds")
+#' aws_file_upload(
+#'   links_file,
+#'   s3_path(bucket_name, basename(links_file))
+#' )
+#' aws_bucket_list_objects(bucket = bucket_name)
 aws_bucket_list_objects <- function(bucket, ...) {
   out <- s3fs::s3_dir_info(bucket, ...)
   if (is.data.frame(out) && NROW(out) > 0) {
@@ -214,9 +225,28 @@ aws_buckets <- function(...) {
 #' @family buckets
 #' @return character vector of objects/files within the bucket,
 #' printed as a tree
-#' @examples \dontrun{
-#' aws_bucket_tree("s3://s64-test-2")
-#' }
+#' @examplesIf interactive()
+#' bucket_name <- "s64-test-69"
+#' if (!aws_bucket_exists(bucket_name)) aws_bucket_create(bucket_name)
+#' links_file <- file.path(system.file(), "Meta/links.rds")
+#' pkgs_file <- file.path(system.file(), "Meta/package.rds")
+#' demo_file <- file.path(system.file(), "Meta/demo.rds")
+#' aws_file_upload(
+#'   c(links_file, pkgs_file, demo_file),
+#'   s3_path(bucket_name,
+#'     c(basename(links_file),
+#'       basename(pkgs_file),
+#'       basename(demo_file)
+#'     )
+#'   )
+#' )
+#' aws_bucket_tree(bucket_name)
+#'
+#' # cleanup
+#' objs <- aws_bucket_list_objects(bucket_name)
+#' aws_file_delete(objs$uri)
+#' aws_bucket_delete(bucket_name, force=TRUE)
+#' aws_bucket_exists(bucket_name)
 aws_bucket_tree <- function(bucket, recurse = TRUE, ...) {
-  s3fs::s3_dir_tree(bucket, recurse = recurse, ...)
+  s3fs::s3_dir_tree(s3_path(bucket), recurse = recurse, ...)
 }
diff --git a/R/files.R b/R/files.R
index 3f1a468..5870106 100644
--- a/R/files.R
+++ b/R/files.R
@@ -22,6 +22,8 @@ equal_lengths <- function(x, y) {
 #' @details
 #' - For upload: if it does exist it will be created
 #' - For download: if it does not exist, function will return an error
+#'
+#' To upload a folder of files see [aws_bucket_upload()]
 #' @family files
 #' @examples \dontrun{
 #' demo_rds_file <- file.path(system.file(), "Meta/demo.rds")
diff --git a/man/aws_bucket_delete.Rd b/man/aws_bucket_delete.Rd
index e5b48dc..9385635 100644
--- a/man/aws_bucket_delete.Rd
+++ b/man/aws_bucket_delete.Rd
@@ -17,7 +17,7 @@ non-interactive use.}
 \href{https://www.paws-r-sdk.com/docs/s3_delete_bucket/}{delete_bucket}}
 }
 \value{
-an empty list
+\code{NULL}, invisibly
 }
 \description{
 Delete an S3 bucket
@@ -27,12 +27,15 @@ Requires the env var \code{AWS_REGION}. This function prompts you to make
 sure that you want to delete the bucket.
 }
 \examples{
-\dontrun{
-aws_bucket_create(bucket = "bucket-to-delete-111")
-aws_buckets()
-aws_bucket_delete(bucket = "bucket-to-delete-111")
-aws_buckets()
-}
+\dontshow{if (interactive()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
+bucket_name <- "bucket-to-delete-113"
+if (!aws_bucket_exists(bucket_name)) {
+ aws_bucket_create(bucket = bucket_name)
+ aws_buckets()
+ aws_bucket_delete(bucket = bucket_name)
+ aws_buckets()
+}
+\dontshow{\}) # examplesIf}
 }
 \seealso{
 Other buckets: 
diff --git a/man/aws_bucket_download.Rd b/man/aws_bucket_download.Rd
index 665bf5d..df77faf 100644
--- a/man/aws_bucket_download.Rd
+++ b/man/aws_bucket_download.Rd
@@ -21,7 +21,7 @@ Requires the env var \code{AWS_REGION}. This function prompts you to make
 sure that you want to delete the bucket.
 }
 \examples{
-\dontrun{
+\dontshow{if (interactive()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
 aws_bucket_create(bucket = "tmp-bucket-369")
 desc_file <- file.path(system.file(), "DESCRIPTION")
 aws_file_upload(bucket = "tmp-bucket-369", path = desc_file)
@@ -31,7 +31,7 @@ aws_bucket_download(bucket = "tmp-bucket-369", dest_path = temp_dir)
 
 # cleanup
 aws_bucket_delete("tmp-bucket-369")
-}
+\dontshow{\}) # examplesIf}
 }
 \seealso{
 Other buckets: 
diff --git a/man/aws_bucket_list_objects.Rd b/man/aws_bucket_list_objects.Rd
index f066d13..cbe25f7 100644
--- a/man/aws_bucket_list_objects.Rd
+++ b/man/aws_bucket_list_objects.Rd
@@ -29,9 +29,16 @@ is an S3 bucket, with 8 columns:
 List objects in an S3 bucket
 }
 \examples{
-\dontrun{
-aws_bucket_list_objects(bucket = "s64-test-2")
-}
+\dontshow{if (interactive()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
+bucket_name <- "s64-test-67"
+if (!aws_bucket_exists(bucket_name)) aws_bucket_create(bucket_name)
+links_file <- file.path(system.file(), "Meta/links.rds")
+aws_file_upload(
+  links_file,
+  s3_path(bucket_name, basename(links_file))
+)
+aws_bucket_list_objects(bucket = bucket_name)
+\dontshow{\}) # examplesIf}
 }
 \seealso{
 Other buckets: 
diff --git a/man/aws_bucket_tree.Rd b/man/aws_bucket_tree.Rd
index 9b38e8e..a29b295 100644
--- a/man/aws_bucket_tree.Rd
+++ b/man/aws_bucket_tree.Rd
@@ -22,9 +22,29 @@ printed as a tree
 Print a tree of the objects in a bucket
 }
 \examples{
-\dontrun{
-aws_bucket_tree("s3://s64-test-2")
-}
+\dontshow{if (interactive()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
+bucket_name <- "s64-test-69"
+if (!aws_bucket_exists(bucket_name)) aws_bucket_create(bucket_name)
+links_file <- file.path(system.file(), "Meta/links.rds")
+pkgs_file <- file.path(system.file(), "Meta/package.rds")
+demo_file <- file.path(system.file(), "Meta/demo.rds")
+aws_file_upload(
+  c(links_file, pkgs_file, demo_file),
+  s3_path(bucket_name,
+    c(basename(links_file),
+      basename(pkgs_file),
+      basename(demo_file)
+    )
+  )
+)
+aws_bucket_tree(bucket_name)
+
+# cleanup
+objs <- aws_bucket_list_objects(bucket_name)
+aws_file_delete(objs$uri)
+aws_bucket_delete(bucket_name, force=TRUE)
+aws_bucket_exists(bucket_name)
+\dontshow{\}) # examplesIf}
 }
 \seealso{
 Other buckets: 
diff --git a/man/aws_bucket_upload.Rd b/man/aws_bucket_upload.Rd
index e0153f9..969d3fa 100644
--- a/man/aws_bucket_upload.Rd
+++ b/man/aws_bucket_upload.Rd
@@ -19,26 +19,32 @@ multipart}
 \description{
 Upload a folder of files to create an S3 bucket
 }
+\details{
+To upload individual files see \code{\link[=aws_file_upload]{aws_file_upload()}}
+}
 \note{
 Requires the env var \code{AWS_REGION}. This function prompts you to make
 sure that you want to delete the bucket.
 }
 \examples{
-\dontrun{
+\dontshow{if (interactive()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
 library(fs)
 tdir <- path(tempdir(), "apples")
 dir.create(tdir)
 tfiles <- replicate(n = 10, file_temp(tmp_dir = tdir, ext = ".txt"))
 invisible(lapply(tfiles, function(x) write.csv(mtcars, x)))
 
-aws_bucket_upload(path = tdir, bucket = "a-new-bucket-345")
-aws_bucket_list_objects("a-new-bucket-345")
+bucket_name <- "a-new-bucket-345"
+if (!aws_bucket_exists(bucket_name)) aws_bucket_create(bucket_name)
+aws_bucket_upload(path = tdir, bucket = bucket_name)
+aws_bucket_list_objects(bucket_name)
 
 # cleanup
-objs <- aws_bucket_list_objects("a-new-bucket-345")
+objs <- aws_bucket_list_objects(bucket_name)
 aws_file_delete(objs$uri)
-aws_bucket_delete("a-new-bucket-345")
-}
+aws_bucket_delete(bucket_name, force=TRUE)
+aws_bucket_exists(bucket_name)
+\dontshow{\}) # examplesIf}
 }
 \seealso{
 Other buckets: 
diff --git a/man/aws_file_upload.Rd b/man/aws_file_upload.Rd
index 35ce9a4..258d02c 100644
--- a/man/aws_file_upload.Rd
+++ b/man/aws_file_upload.Rd
@@ -29,6 +29,8 @@ Upload a file
 \item For upload: if it does exist it will be created
 \item For download: if it does not exist, function will return an error
 }
+
+To upload a folder of files see \code{\link[=aws_bucket_upload]{aws_bucket_upload()}}
 }
 \examples{
 \dontrun{
diff --git a/man/aws_policy_document_create.Rd b/man/aws_policy_document_create.Rd
index d0b85d1..1342491 100644
--- a/man/aws_policy_document_create.Rd
+++ b/man/aws_policy_document_create.Rd
@@ -78,7 +78,7 @@ aws_policy_document_create(
 \dontshow{\}) # examplesIf}
 }
 \references{
-#no lint start
-\url{https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html}
-#no lint end
+nolint start
+
+\url{https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html}nolint end
 }