From cf6bb1a35ca294a857c6beab806695d67d2747fd Mon Sep 17 00:00:00 2001 From: idmn Date: Sun, 28 Apr 2024 11:51:50 +0000 Subject: [PATCH 1/8] may -> must in error messages --- R/cloud_local.R | 4 ++-- R/common.R | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/R/cloud_local.R b/R/cloud_local.R index ca3548c..87cf2e6 100644 --- a/R/cloud_local.R +++ b/R/cloud_local.R @@ -132,7 +132,7 @@ cloud_object_ls <- function(x, path, extension, prefix = "", suffix = "") { if (!grepl("^([A-Za-z]|[0-9]|-|_|\\.|/)+$", path)) { cli::cli_abort(c( - "Directory path {.path {path}} is not valid. A valid directory path may \\ + "Directory path {.path {path}} is not valid. A valid directory path must \\ consist of:", "*" = "uppercase/lowercase letters", "*" = "digits", @@ -144,7 +144,7 @@ cloud_object_ls <- function(x, path, extension, prefix = "", suffix = "") { if (!grepl("^([A-Za-z]|[0-9])+$", extension)) { cli::cli_abort(c( "{.arg extension} {.val {extension}} is not valid. A valid extension path \\ - may consist of:", + must consist of:", "*" = "uppercase/lowercase letters", "*" = "digits" )) diff --git a/R/common.R b/R/common.R index 3fc3613..56dd126 100644 --- a/R/common.R +++ b/R/common.R @@ -70,7 +70,7 @@ cloud_validate_file_path <- function(file, error = TRUE) { if (file == "") cli::cli_abort("A valid file name should not be empty.") if (!res) cli_abort(c( "File name '{file}' is not valid", - "A valid file name may consist of:", + "A valid file name must consist of:", "*" = "uppercase/lowercase letters", "*" = "digits", "*" = "spaces", From 904e827039200b496a6d4c574cfab1e0169b6c1f Mon Sep 17 00:00:00 2001 From: idmn Date: Sun, 28 Apr 2024 15:14:24 +0000 Subject: [PATCH 2/8] create check_path() and use throughout the package --- R/cli.R | 32 +++++++++++++++++++ R/cloud_local.R | 12 +------ R/common.R | 32 ------------------- R/doc.R | 9 ++++++ R/drive_transfer.R | 16 +++++----- R/drive_utils.R | 6 ++-- R/read_write.R | 8 ++--- R/s3_transfer.R | 16 +++++----- ...ud_validate_file_path.Rd => check_path.Rd} | 18 +++++------ man/doc_file.Rd | 17 ++++++++++ 10 files changed, 91 insertions(+), 75 deletions(-) create mode 100644 R/doc.R rename man/{cloud_validate_file_path.Rd => check_path.Rd} (65%) create mode 100644 man/doc_file.Rd diff --git a/R/cli.R b/R/cli.R index c894aa8..9ad69ba 100644 --- a/R/cli.R +++ b/R/cli.R @@ -310,3 +310,35 @@ check_bool <- function(x, alt_null = FALSE, add_msg = NULL) { )) } } + + +#' @title Validate a path +#' +#' @description Makes sure that a path passed to a cloud function is in the +#' right format. +#' +#' @param file Path to a file relative to project folder root. Can contain only +#' letters, digits, '-', '_', '.', spaces and '/' symbols. +#' @param error if `TRUE` (default), throws an error if `file` is not a valid +#' file path. +#' +#' @return Either `TRUE` or `FALSE` if `error` is `FALSE`. Either `TRUE` or +#' an error if `error` is `TRUE`. +#' +#' @keywords internal +check_path <- function(path, error = TRUE) { + res <- grepl("^([A-Za-z]|[0-9]|-|_|\\.| |/)+$", path) + if (error) { + if (path == "") cli::cli_abort("A valid path must not be empty.") + if (!res) cli_abort(c( + "Path '{path}' is not valid", + "A valid path must consist of:", + "*" = "uppercase/lowercase letters", + "*" = "digits", + "*" = "'/' symbols to separate directories in the path", + "*" = "'_', '-', '.' symbols or spaces" + )) + } + res +} + diff --git a/R/cloud_local.R b/R/cloud_local.R index 87cf2e6..2ebda4e 100644 --- a/R/cloud_local.R +++ b/R/cloud_local.R @@ -129,17 +129,7 @@ cloud_object_ls <- function(x, path, extension, prefix = "", suffix = "") { check_string(extension) check_string(prefix) check_string(suffix) - - if (!grepl("^([A-Za-z]|[0-9]|-|_|\\.|/)+$", path)) { - cli::cli_abort(c( - "Directory path {.path {path}} is not valid. A valid directory path must \\ - consist of:", - "*" = "uppercase/lowercase letters", - "*" = "digits", - "*" = "'/' symbols to describe its location inside project's folder", - "*" = "'_', '-', '.' symbols or spaces." - )) - } + check_path(path) if (!grepl("^([A-Za-z]|[0-9])+$", extension)) { cli::cli_abort(c( diff --git a/R/common.R b/R/common.R index 56dd126..299ce6b 100644 --- a/R/common.R +++ b/R/common.R @@ -49,38 +49,6 @@ proj_desc_get <- function(key, project = ".") { unname(value) } -#' @title Validate file path for cloud functions -#' -#' @description Makes sure that file path passed to a cloud function is in the -#' right format. -#' -#' @param file Path to a file relative to project folder root. Can contain only -#' letters, digits, '-', '_', '.', spaces and '/' symbols. -#' @param error if `TRUE` (default), throws an error if `file` is not a valid -#' file path. -#' -#' @return Either `TRUE` or `FALSE` if `error` is `FALSE`. Either `TRUE` or -#' an error if `error` is `TRUE`. -#' -#' @keywords internal -cloud_validate_file_path <- function(file, error = TRUE) { - check_string(file) - res <- grepl("^([A-Za-z]|[0-9]|-|_|\\.| |/)+$", file) - if (error) { - if (file == "") cli::cli_abort("A valid file name should not be empty.") - if (!res) cli_abort(c( - "File name '{file}' is not valid", - "A valid file name must consist of:", - "*" = "uppercase/lowercase letters", - "*" = "digits", - "*" = "spaces", - "*" = "'/' symbols to describe its location inside project's folder", - "*" = "'_', '-', '.' symbols" - )) - } - res -} - #' @title Validate file names #' #' @description Given a character vector of filenames checks that all names pass diff --git a/R/doc.R b/R/doc.R new file mode 100644 index 0000000..ccf8521 --- /dev/null +++ b/R/doc.R @@ -0,0 +1,9 @@ +#' @title Package-wide description of `file` parameter +#' @description A dummy function to be referred by `@inheritParams` for a +#' parameter documentation. +#' +#' @param file Path to a file relative to project folder root. Can contain only +#' letters, digits, '-', '_', '.', spaces and '/' symbols. +#' +#' @keywords internal +doc_file <- function(file) {} diff --git a/R/drive_transfer.R b/R/drive_transfer.R index 8243552..f64284a 100644 --- a/R/drive_transfer.R +++ b/R/drive_transfer.R @@ -3,7 +3,7 @@ #' @description Uploads a local file from the project's directory to its #' corresponding location within the project's Google Drive root folder. #' -#' @inheritParams cloud_validate_file_path +#' @inheritParams doc_file #' @inheritParams cloud_drive_ls #' #' @inherit cloud_drive_find_path details @@ -25,7 +25,7 @@ #' #' @export cloud_drive_upload <- function(file, root = NULL) { - cloud_validate_file_path(file) + check_path(file) if (!file.exists(file)) { cli::cli_abort("File {.path {file}} does not exist.") @@ -51,7 +51,7 @@ cloud_drive_upload <- function(file, root = NULL) { #' saves it to the local project folder, maintaining the original folder #' structure. #' -#' @inheritParams cloud_validate_file_path +#' @inheritParams doc_file #' @inheritParams cloud_drive_ls #' #' @inherit cloud_drive_find_path details @@ -68,7 +68,7 @@ cloud_drive_upload <- function(file, root = NULL) { #' #' @export cloud_drive_download <- function(file, root = NULL) { - cloud_validate_file_path(file) + check_path(file) check_string(root, alt_null = TRUE) if (is.null(root)) root <- cloud_drive_get_root() @@ -95,7 +95,7 @@ cloud_drive_download <- function(file, root = NULL) { #' function will infer the appropriate writing method based on the file's #' extension. #' -#' @inheritParams cloud_validate_file_path +#' @inheritParams doc_file #' @inheritParams cloud_drive_ls #' #' @param x An R object to be written to Google Drive. @@ -121,7 +121,7 @@ cloud_drive_download <- function(file, root = NULL) { #' @export cloud_drive_write <- function(x, file, fun = NULL, ..., local = FALSE, root = NULL) { - cloud_validate_file_path(file) + check_path(file) check_bool(local) if (is.null(fun)) { @@ -162,7 +162,7 @@ cloud_drive_write <- function(x, file, fun = NULL, ..., local = FALSE, #' reading function based on the file's extension. However, you can specify a #' custom reading function if necessary. #' -#' @inheritParams cloud_validate_file_path +#' @inheritParams doc_file #' @inheritParams cloud_drive_ls #' #' @param fun A custom reading function. If `NULL` (default), the appropriate @@ -185,7 +185,7 @@ cloud_drive_write <- function(x, file, fun = NULL, ..., local = FALSE, #' #' @export cloud_drive_read <- function(file, fun = NULL, ..., root = NULL) { - cloud_validate_file_path(file) + check_path(file) if (is.null(fun)) { fun <- cloud_guess_read_fun(file) } diff --git a/R/drive_utils.R b/R/drive_utils.R index 264e6ec..3a2508a 100644 --- a/R/drive_utils.R +++ b/R/drive_utils.R @@ -78,7 +78,7 @@ cloud_drive_download_by_id <- function(file, path, overwrite = FALSE) { #' #' @noRd cloud_drive_guess_type <- function(file) { - cloud_validate_file_path(file) + check_path(file) ext <- tolower(tools::file_ext(file)) switch ( ext, @@ -112,7 +112,7 @@ cloud_drive_put <- function(media, path) { #' @description Finds the spreadsheet by path relative to a project root. #' Applies [googlesheets4::range_autofit()] to each sheet. #' -#' @inheritParams cloud_validate_file_path +#' @inheritParams doc_file #' @inheritParams cloud_drive_ls #' #' @return The file ID of the resized Google spreadsheet as an invisible result. @@ -123,7 +123,7 @@ cloud_drive_put <- function(media, path) { #' #' @export cloud_drive_spreadsheet_autofit <- function(file, root = NULL) { - cloud_validate_file_path(file) + check_path(file) check_string(root, alt_null = TRUE) if (is.null(root)) root <- cloud_drive_get_root() diff --git a/R/read_write.R b/R/read_write.R index 726711f..07a7ed2 100644 --- a/R/read_write.R +++ b/R/read_write.R @@ -3,7 +3,7 @@ #' @description Take a look at the switch call. That's basically it. Returns an #' appropriate function or throws an error if wasn't able to find one. #' -#' @inheritParams cloud_validate_file_path +#' @inheritParams doc_file #' #' @section Default writing functions: #' @@ -21,7 +21,7 @@ #' #' @keywords internal cloud_guess_write_fun <- function(file) { - cloud_validate_file_path(file) + check_path(file) ext <- tolower(tools::file_ext(file)) if (ext == "") stop("Missing file extension, unable to guess writing function.") fun <- switch ( @@ -47,7 +47,7 @@ cloud_guess_write_fun <- function(file) { #' @description Take a look at the switch call. That's basically it. Returns an #' appropriate function or throws an error if wasn't able to find one. #' -#' @inheritParams cloud_validate_file_path +#' @inheritParams doc_file #' #' @section Default reading functions: #' @@ -64,7 +64,7 @@ cloud_guess_write_fun <- function(file) { #' #' @keywords internal cloud_guess_read_fun <- function(file) { - cloud_validate_file_path(file) + check_path(file) ext <- tolower(tools::file_ext(file)) if (ext == "") stop("Missing file extension, unable to guess reading function.") fun <- switch ( diff --git a/R/s3_transfer.R b/R/s3_transfer.R index 48f1475..827644e 100644 --- a/R/s3_transfer.R +++ b/R/s3_transfer.R @@ -3,7 +3,7 @@ #' @description Uploads a local file from the project's directory to its #' corresponding location within the project's S3 root folder. #' -#' @inheritParams cloud_validate_file_path +#' @inheritParams doc_file #' @inheritParams cloud_s3_ls #' #' @return Invisibly returns `NULL` after successfully uploading the file. @@ -21,7 +21,7 @@ #' #' @export cloud_s3_upload <- function(file, root = NULL) { - cloud_validate_file_path(file) + check_path(file) check_string(root, alt_null = TRUE) if (is.null(root)) root <- cloud_s3_get_root() @@ -51,7 +51,7 @@ cloud_s3_upload <- function(file, root = NULL) { #' @description Retrieves a file from the project's S3 root folder and saves it #' to the local project folder, maintaining the original folder structure. #' -#' @inheritParams cloud_validate_file_path +#' @inheritParams doc_file #' @inheritParams cloud_s3_ls #' #' @return Invisibly returns `NULL` after successfully downloading the file. @@ -66,7 +66,7 @@ cloud_s3_upload <- function(file, root = NULL) { #' #' @export cloud_s3_download <- function(file, root = NULL) { - cloud_validate_file_path(file) + check_path(file) check_string(root, alt_null = TRUE) if (is.null(root)) root <- cloud_s3_get_root() @@ -90,7 +90,7 @@ cloud_s3_download <- function(file, root = NULL) { #' S3 storage. If no custom writing function is specified, the function will #' infer the appropriate writing method based on the file's extension. #' -#' @inheritParams cloud_validate_file_path +#' @inheritParams doc_file #' @inheritParams cloud_s3_ls #' #' @param x An R object to be written to S3. @@ -115,7 +115,7 @@ cloud_s3_download <- function(file, root = NULL) { #' @export cloud_s3_write <- function(x, file, fun = NULL, ..., local = FALSE, root = NULL) { - cloud_validate_file_path(file) + check_path(file) check_bool(local) check_class(fun, "function", alt_null = TRUE) check_string(root, alt_null = TRUE) @@ -158,7 +158,7 @@ cloud_s3_write <- function(x, file, fun = NULL, ..., local = FALSE, #' function based on the file's extension. However, you can specify a custom #' reading function if necessary. #' -#' @inheritParams cloud_validate_file_path +#' @inheritParams doc_file #' @inheritParams cloud_s3_ls #' #' @param fun A custom reading function. If `NULL` (default), the appropriate @@ -179,7 +179,7 @@ cloud_s3_write <- function(x, file, fun = NULL, ..., local = FALSE, #' #' @export cloud_s3_read <- function(file, fun = NULL, ..., root = NULL) { - cloud_validate_file_path(file) + check_path(file) check_string(root, alt_null = TRUE) if (is.null(fun)) { diff --git a/man/cloud_validate_file_path.Rd b/man/check_path.Rd similarity index 65% rename from man/cloud_validate_file_path.Rd rename to man/check_path.Rd index 4090737..141f43d 100644 --- a/man/cloud_validate_file_path.Rd +++ b/man/check_path.Rd @@ -1,24 +1,24 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/common.R -\name{cloud_validate_file_path} -\alias{cloud_validate_file_path} -\title{Validate file path for cloud functions} +% Please edit documentation in R/cli.R +\name{check_path} +\alias{check_path} +\title{Validate a path} \usage{ -cloud_validate_file_path(file, error = TRUE) +check_path(path, error = TRUE) } \arguments{ -\item{file}{Path to a file relative to project folder root. Can contain only -letters, digits, '-', '_', '.', spaces and '/' symbols.} - \item{error}{if \code{TRUE} (default), throws an error if \code{file} is not a valid file path.} + +\item{file}{Path to a file relative to project folder root. Can contain only +letters, digits, '-', '_', '.', spaces and '/' symbols.} } \value{ Either \code{TRUE} or \code{FALSE} if \code{error} is \code{FALSE}. Either \code{TRUE} or an error if \code{error} is \code{TRUE}. } \description{ -Makes sure that file path passed to a cloud function is in the +Makes sure that a path passed to a cloud function is in the right format. } \keyword{internal} diff --git a/man/doc_file.Rd b/man/doc_file.Rd new file mode 100644 index 0000000..c141b35 --- /dev/null +++ b/man/doc_file.Rd @@ -0,0 +1,17 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/doc.R +\name{doc_file} +\alias{doc_file} +\title{Package-wide description of \code{file} parameter} +\usage{ +doc_file(file) +} +\arguments{ +\item{file}{Path to a file relative to project folder root. Can contain only +letters, digits, '-', '_', '.', spaces and '/' symbols.} +} +\description{ +A dummy function to be referred by \verb{@inheritParams} for a +parameter documentation. +} +\keyword{internal} From cc1490830f044c34f7c001f3d7ee8900dd3a9b2b Mon Sep 17 00:00:00 2001 From: idmn Date: Sun, 28 Apr 2024 15:44:37 +0000 Subject: [PATCH 3/8] better documentation for local parameter of writing functions --- R/doc.R | 19 +++++++++++++++++++ R/drive_transfer.R | 3 +-- R/s3_transfer.R | 3 +-- man/cloud_drive_write.Rd | 11 +++++++++-- man/cloud_drive_write_bulk.Rd | 11 +++++++++-- man/cloud_s3_write.Rd | 11 +++++++++-- man/cloud_s3_write_bulk.Rd | 11 +++++++++-- man/doc_local.Rd | 24 ++++++++++++++++++++++++ 8 files changed, 81 insertions(+), 12 deletions(-) create mode 100644 man/doc_local.Rd diff --git a/R/doc.R b/R/doc.R index ccf8521..0b77f85 100644 --- a/R/doc.R +++ b/R/doc.R @@ -7,3 +7,22 @@ #' #' @keywords internal doc_file <- function(file) {} + + + +#' @title Package-wide description of `local` parameter +#' @description A dummy function to be referred by `@inheritParams` for a +#' parameter documentation. +#' +#' @param local Logical, defaulting to `FALSE`. If `TRUE`, the function will +#' also create a local copy of the file at the specified path. Note that some +#' writing functions might not overwrite existing files unless explicitly +#' allowed. Typically, such functions have a parameter (often named +#' `overwrite`) to control this behavior. Check the documentation of the +#' writing function used to determine the exact parameter name and pass it +#' through the `...` argument if necessary. Alternatively, you can define an +#' anonymous function for `fun` that calls a writing function with the +#' overwriting option enabled. +#' +#' @keywords internal +doc_local <- function(local) {} diff --git a/R/drive_transfer.R b/R/drive_transfer.R index f64284a..a66394a 100644 --- a/R/drive_transfer.R +++ b/R/drive_transfer.R @@ -97,13 +97,12 @@ cloud_drive_download <- function(file, root = NULL) { #' #' @inheritParams doc_file #' @inheritParams cloud_drive_ls +#' @inheritParams doc_local #' #' @param x An R object to be written to Google Drive. #' @param fun A custom writing function. If `NULL` (default), the appropriate #' writing function will be inferred based on the file's extension. #' @param ... Additional arguments to pass to the writing function `fun`. -#' @param local Logical. If `TRUE`, a local copy of the file will also be -#' created at the specified path. Default is `FALSE`. #' #' @inheritSection cloud_guess_write_fun Default writing functions #' diff --git a/R/s3_transfer.R b/R/s3_transfer.R index 827644e..7617b68 100644 --- a/R/s3_transfer.R +++ b/R/s3_transfer.R @@ -92,13 +92,12 @@ cloud_s3_download <- function(file, root = NULL) { #' #' @inheritParams doc_file #' @inheritParams cloud_s3_ls +#' @inheritParams doc_local #' #' @param x An R object to be written to S3. #' @param fun A custom writing function. If `NULL` (default), the appropriate #' writing function will be inferred based on the file's extension. #' @param ... Additional arguments to pass to the writing function `fun`. -#' @param local Logical. If `TRUE`, a local copy of the file will also be -#' created at the specified path. Default is `FALSE`. #' #' @inheritSection cloud_guess_write_fun Default writing functions #' diff --git a/man/cloud_drive_write.Rd b/man/cloud_drive_write.Rd index 5ae39a5..6761abf 100644 --- a/man/cloud_drive_write.Rd +++ b/man/cloud_drive_write.Rd @@ -17,8 +17,15 @@ writing function will be inferred based on the file's extension.} \item{...}{Additional arguments to pass to the writing function \code{fun}.} -\item{local}{Logical. If \code{TRUE}, a local copy of the file will also be -created at the specified path. Default is \code{FALSE}.} +\item{local}{Logical, defaulting to \code{FALSE}. If \code{TRUE}, the function will +also create a local copy of the file at the specified path. Note that some +writing functions might not overwrite existing files unless explicitly +allowed. Typically, such functions have a parameter (often named +\code{overwrite}) to control this behavior. Check the documentation of the +writing function used to determine the exact parameter name and pass it +through the \code{...} argument if necessary. Alternatively, you can define an +anonymous function for \code{fun} that calls a writing function with the +overwriting option enabled.} \item{root}{Google Drive ID or URL of the project root. This serves as the reference point for all relative paths. When left as \code{NULL}, the root is diff --git a/man/cloud_drive_write_bulk.Rd b/man/cloud_drive_write_bulk.Rd index b4b0bf9..f9eb08b 100644 --- a/man/cloud_drive_write_bulk.Rd +++ b/man/cloud_drive_write_bulk.Rd @@ -21,8 +21,15 @@ writing function will be inferred based on the file's extension.} \item{...}{Additional arguments to pass to the writing function \code{fun}.} -\item{local}{Logical. If \code{TRUE}, a local copy of the file will also be -created at the specified path. Default is \code{FALSE}.} +\item{local}{Logical, defaulting to \code{FALSE}. If \code{TRUE}, the function will +also create a local copy of the file at the specified path. Note that some +writing functions might not overwrite existing files unless explicitly +allowed. Typically, such functions have a parameter (often named +\code{overwrite}) to control this behavior. Check the documentation of the +writing function used to determine the exact parameter name and pass it +through the \code{...} argument if necessary. Alternatively, you can define an +anonymous function for \code{fun} that calls a writing function with the +overwriting option enabled.} \item{quiet}{all caution messages may be turned off by setting this parameter to \code{TRUE}.} diff --git a/man/cloud_s3_write.Rd b/man/cloud_s3_write.Rd index d840cb9..0f8841d 100644 --- a/man/cloud_s3_write.Rd +++ b/man/cloud_s3_write.Rd @@ -17,8 +17,15 @@ writing function will be inferred based on the file's extension.} \item{...}{Additional arguments to pass to the writing function \code{fun}.} -\item{local}{Logical. If \code{TRUE}, a local copy of the file will also be -created at the specified path. Default is \code{FALSE}.} +\item{local}{Logical, defaulting to \code{FALSE}. If \code{TRUE}, the function will +also create a local copy of the file at the specified path. Note that some +writing functions might not overwrite existing files unless explicitly +allowed. Typically, such functions have a parameter (often named +\code{overwrite}) to control this behavior. Check the documentation of the +writing function used to determine the exact parameter name and pass it +through the \code{...} argument if necessary. Alternatively, you can define an +anonymous function for \code{fun} that calls a writing function with the +overwriting option enabled.} \item{root}{S3 path of the project root. This serves as the reference point for all relative paths. When left as \code{NULL}, the root is automatically diff --git a/man/cloud_s3_write_bulk.Rd b/man/cloud_s3_write_bulk.Rd index 5f94075..4a65737 100644 --- a/man/cloud_s3_write_bulk.Rd +++ b/man/cloud_s3_write_bulk.Rd @@ -21,8 +21,15 @@ writing function will be inferred based on the file's extension.} \item{...}{Additional arguments to pass to the writing function \code{fun}.} -\item{local}{Logical. If \code{TRUE}, a local copy of the file will also be -created at the specified path. Default is \code{FALSE}.} +\item{local}{Logical, defaulting to \code{FALSE}. If \code{TRUE}, the function will +also create a local copy of the file at the specified path. Note that some +writing functions might not overwrite existing files unless explicitly +allowed. Typically, such functions have a parameter (often named +\code{overwrite}) to control this behavior. Check the documentation of the +writing function used to determine the exact parameter name and pass it +through the \code{...} argument if necessary. Alternatively, you can define an +anonymous function for \code{fun} that calls a writing function with the +overwriting option enabled.} \item{quiet}{all caution messages may be turned off by setting this parameter to \code{TRUE}.} diff --git a/man/doc_local.Rd b/man/doc_local.Rd new file mode 100644 index 0000000..3e8fb8d --- /dev/null +++ b/man/doc_local.Rd @@ -0,0 +1,24 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/doc.R +\name{doc_local} +\alias{doc_local} +\title{Package-wide description of \code{local} parameter} +\usage{ +doc_local(local) +} +\arguments{ +\item{local}{Logical, defaulting to \code{FALSE}. If \code{TRUE}, the function will +also create a local copy of the file at the specified path. Note that some +writing functions might not overwrite existing files unless explicitly +allowed. Typically, such functions have a parameter (often named +\code{overwrite}) to control this behavior. Check the documentation of the +writing function used to determine the exact parameter name and pass it +through the \code{...} argument if necessary. Alternatively, you can define an +anonymous function for \code{fun} that calls a writing function with the +overwriting option enabled.} +} +\description{ +A dummy function to be referred by \verb{@inheritParams} for a +parameter documentation. +} +\keyword{internal} From 51e4dfe54a94066d7ca0ce9590d42054b259656c Mon Sep 17 00:00:00 2001 From: idmn Date: Sun, 28 Apr 2024 16:22:50 +0000 Subject: [PATCH 4/8] turn on multipart for S3 --- R/s3_transfer.R | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/R/s3_transfer.R b/R/s3_transfer.R index 7617b68..4e92b5e 100644 --- a/R/s3_transfer.R +++ b/R/s3_transfer.R @@ -35,7 +35,8 @@ cloud_s3_upload <- function(file, root = NULL) { aws.s3::put_object( bucket = bucket_prefix$bucket, file = file, - object = bucket_prefix$prefix + object = bucket_prefix$prefix, + multipart = TRUE ) cli::cli_alert_success( "File {.path {file}} uploaded to S3 root {.field {root}}." @@ -140,7 +141,8 @@ cloud_s3_write <- function(x, file, fun = NULL, ..., local = FALSE, aws.s3::put_object( file = local_file, bucket = bucket_prefix$bucket, - object = bucket_prefix$prefix + object = bucket_prefix$prefix, + multipart = TRUE ) if (!local) {unlink(local_file)} From 179d416d3002fc88f4f97eb03828acb79f7ddd03 Mon Sep 17 00:00:00 2001 From: idmn Date: Sun, 28 Apr 2024 16:27:35 +0000 Subject: [PATCH 5/8] updated NEWS --- NEWS.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/NEWS.md b/NEWS.md index b1a8fb8..5bc4e12 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,10 @@ # cloudfs (development version) +* Updated `cloud_object_ls()` to support paths containing spaces. +* Improved various sections of the documentation. +* Enabled multipart upload for S3 writing and uploading functions, with a +default part size set to 100 MB. + # cloudfs 0.1.2 * Initial version. From c28b03da00d2493184eb21004720f7db3b20c1ae Mon Sep 17 00:00:00 2001 From: idmn Date: Tue, 7 May 2024 15:03:07 +0000 Subject: [PATCH 6/8] bump version --- DESCRIPTION | 2 +- NEWS.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index a89b44c..289e227 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: cloudfs Title: Streamlined Interface to Interact with Cloud Storage Platforms -Version: 0.1.2.9000 +Version: 0.1.3 Authors@R: c( person("Iaroslav", "Domin", email = "iaroslav@gradientmetrics.com", role = c("aut", "cre")), person("Stefan", "Musch", email = "stefan@gradientmetrics.com", role = c("aut")), diff --git a/NEWS.md b/NEWS.md index 5bc4e12..ac828e3 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,9 +1,9 @@ -# cloudfs (development version) +# cloudfs 0.1.3 * Updated `cloud_object_ls()` to support paths containing spaces. * Improved various sections of the documentation. -* Enabled multipart upload for S3 writing and uploading functions, with a -default part size set to 100 MB. +* Enabled multipart upload for S3 writing and uploading functions, with the +default part size of 100 MB. # cloudfs 0.1.2 From 337ce3ef2780e2a5faf104b34caeb8accfedb865 Mon Sep 17 00:00:00 2001 From: idmn Date: Tue, 7 May 2024 15:25:30 +0000 Subject: [PATCH 7/8] udpate cran-comments --- cran-comments.md | 100 ++--------------------------------------------- 1 file changed, 4 insertions(+), 96 deletions(-) diff --git a/cran-comments.md b/cran-comments.md index 16c018c..c3a71d9 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,99 +1,7 @@ -## Resubmission -This is a resubmission. Below are my responses to the feedback received in the -previous review. - -### User options - -``` -Please always make sure to reset to user's options(), working directory or par() after you changed it in examples and vignettes and demos. --> inst/doc/cloudfs.R -e.g.: -old <- options(digits = 3) -... -options(old) -``` - -I've addressed this by removing the `options(width = 150)` command from the -beginning of the cloudfs.Rmd vignette. - -### User Space Integrity - -``` -Please ensure that your functions do not write by default or in your -examples/vignettes/tests in the user's home filespace (including the package -directory and getwd()). This is not allowed by CRAN policies. -Please omit any default path in writing functions. In your -examples/vignettes/tests you can write to tempdir(). -e.g.: man/cloud_drive_spreadsheet_autofit.Rd ; man/cloud_drive_upload.Rd ; ... -``` - -I understand the importance of adhering to CRAN policies and ensuring that there -are no unintended consequences for the users of the package. However, I have -chosen not to make the suggested modifications, and I'd like to explain the -rationale behind this decision and why in my opinion the package does not -violate the policies. - -One of the key features of the package is that it enables the use of concise -relative paths for both the current working directory and associated cloud -project folders. For instance, consider the task of uploading a local file, -"models/glm.rds", to a project's S3 folder. Using `aws.s3`, the code would be: - -```R -aws.s3::put_object( - file = "models/glm.rds", - bucket = "project-data", - object = "project-1/models/glm.rds" -) -``` - -With `cloudfs`, it can be achieved with a significantly simpler syntax: - -```R -cloud_s3_upload("models/glm.rds") -``` - -Applying `cloud_s3_upload()` to a file located in a temporary folder goes -against its design intent. Its main objective is to upload files while mirroring -the folder structure between the current directory and the project's S3. -Demonstrating this with a temp folder file would misrepresent the function's -typical application. - -That being said I've taken comprehensive measures to ensure no accidental or -default file writing occurs in the current working directory: - -- **Initial Setup**: Most functions, including all `*read*`, `*write*`, -`*upload*`, `*download*` require users to link their project directory with -cloud storage during the package's inaugural use. This entails obtaining -explicit user consent. - -- **dontshow**: Consequently, examples where this linkage would activate are -wrapped in `\dontshow` conditional on `interactive()`. - -- **Read Functions**: These initially pull files from the cloud to a temp folder -for reading, leaving the working directory untouched. In examples, the working -directory is also untouched. - -- **Write Functions**: Files are first created in a temp folder, then sent to -the cloud. The working directory remains untouched. - -- **Download Functions**: These do pull files into the working directory, but -this is their primary purpose and they cannot write anywhere outside of it. -Also, in examples (shielded with `\dontshow`), I've added code to remove the -donloaded files. - -- **Upload Functions**: In examples, files are generated files in the working -directory for uploading purposes. Still, cleanup code ensures their removal -afterward. - -- **Vignettes**: Chunks using `cloudfs` functions aren't executed; they're all -tagged with `eval=FALSE`. - -- **Tests**: These only operate when Google Drive or S3 tokens are available, -excluding execution on CRAN. When testing, I use temporary folders for project -creation and employ `withr::with_dir` to execute `cloudfs` code — a strategy -suitable for testing but not for example clarity. - ## R CMD check results -0 errors | 0 warnings | 1 note +0 errors | 0 warnings | 0 notes + +## revdepcheck results -* This is a new release. +This package does not have any reverse dependencies. From f6c2a1ec960552c2dca8fa2dae253198ae26fa9b Mon Sep 17 00:00:00 2001 From: idmn Date: Tue, 7 May 2024 15:30:47 +0000 Subject: [PATCH 8/8] fix doc of an internal check function --- DESCRIPTION | 2 +- R/cli.R | 2 +- man/check_path.Rd | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 289e227..b7bb2c0 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -15,7 +15,7 @@ Description: A unified interface for simplifying cloud storage interactions, License: MIT + file LICENSE Encoding: UTF-8 Roxygen: list(markdown = TRUE) -RoxygenNote: 7.2.3 +RoxygenNote: 7.3.1 Imports: aws.s3, googledrive, diff --git a/R/cli.R b/R/cli.R index 9ad69ba..be110f8 100644 --- a/R/cli.R +++ b/R/cli.R @@ -317,7 +317,7 @@ check_bool <- function(x, alt_null = FALSE, add_msg = NULL) { #' @description Makes sure that a path passed to a cloud function is in the #' right format. #' -#' @param file Path to a file relative to project folder root. Can contain only +#' @param path A path relative to the project folder root. Can contain only #' letters, digits, '-', '_', '.', spaces and '/' symbols. #' @param error if `TRUE` (default), throws an error if `file` is not a valid #' file path. diff --git a/man/check_path.Rd b/man/check_path.Rd index 141f43d..3ccddec 100644 --- a/man/check_path.Rd +++ b/man/check_path.Rd @@ -7,11 +7,11 @@ check_path(path, error = TRUE) } \arguments{ +\item{path}{A path relative to the project folder root. Can contain only +letters, digits, '-', '_', '.', spaces and '/' symbols.} + \item{error}{if \code{TRUE} (default), throws an error if \code{file} is not a valid file path.} - -\item{file}{Path to a file relative to project folder root. Can contain only -letters, digits, '-', '_', '.', spaces and '/' symbols.} } \value{ Either \code{TRUE} or \code{FALSE} if \code{error} is \code{FALSE}. Either \code{TRUE} or