storage_file_exists generic + methods

NAMESPACE

@@ -79,6 +79,9 @@ S3method(storage_container,file_endpoint)
 S3method(storage_download,adls_filesystem)
 S3method(storage_download,blob_container)
 S3method(storage_download,file_share)
+S3method(storage_file_exists,adls_filesystem)
+S3method(storage_file_exists,blob_container)
+S3method(storage_file_exists,file_share)
 S3method(storage_multidownload,adls_filesystem)
 S3method(storage_multidownload,blob_container)
 S3method(storage_multidownload,file_share)
@@ -90,16 +93,18 @@ S3method(storage_upload,blob_container)
 S3method(storage_upload,file_share)
 export(acquire_lease)
 export(adls_endpoint)
+export(adls_file_exists)
 export(adls_filesystem)
 export(az_storage)
 export(azcopy_login)
+export(azure_file_exists)
 export(blob_container)
 export(blob_endpoint)
+export(blob_exists)
 export(break_lease)
 export(call_azcopy)
 export(call_storage_endpoint)
 export(change_lease)
-export(check_blob)
 export(copy_url_to_blob)
 export(copy_url_to_storage)
 export(create_adls_dir)
@@ -153,6 +158,7 @@ export(set_storage_metadata)
 export(storage_container)
 export(storage_download)
 export(storage_endpoint)
+export(storage_file_exists)
 export(storage_multidownload)
 export(storage_multiupload)
 export(storage_upload)

NEWS.md

@@ -1,3 +1,7 @@
+# AzureStor 3.0.1.9000
+
+- New `storage_file_exists` generic to check for file existence, which dispatches to `blob_exists`, `azure_file_exists` and `adls_file_exists` for the individual storage types.
+
 # AzureStor 3.0.1
 
 - Uploading with ADLS now sets the Content-Type property correctly.

R/adls_client_funcs.R

@@ -197,7 +197,7 @@ delete_adls_filesystem.adls_endpoint <- function(endpoint, name, confirm=TRUE, .
 
 #' Operations on an Azure Data Lake Storage Gen2 filesystem
 #'
-#' Upload, download, or delete a file; list files in a directory; create or delete directories.
+#' Upload, download, or delete a file; list files in a directory; create or delete directories; check file existence.
 #'
 #' @param filesystem An ADLSgen2 filesystem object.
 #' @param dir,file A string naming a directory or file respectively.
@@ -225,6 +225,8 @@ delete_adls_filesystem.adls_endpoint <- function(endpoint, name, confirm=TRUE, .
 #'
 #' For `download_adls_file`, if `dest=NULL`, the contents of the downloaded file as a raw vector.
 #'
+#' For `adls_file_exists`, either TRUE or FALSE.
+#'
 #' @seealso
 #' [adls_filesystem], [az_storage], [storage_download], [call_azcopy]
 #'
@@ -418,3 +420,14 @@ delete_adls_dir <- function(filesystem, dir, recursive=FALSE, confirm=TRUE)
     invisible(do_container_op(filesystem, dir, options=opts, http_verb="DELETE"))
 }
 
+#' @rdname adls
+#' @export
+adls_file_exists <- function(filesystem, file)
+{
+    res <- do_container_op(filesystem, file, headers = list(), http_verb = "HEAD", http_status_handler = "pass")
+    if (httr::status_code(res) == 404L)
+        return(FALSE)
+
+    httr::stop_for_status(res, storage_error_message(res))
+    return(TRUE)
+}

R/blob_client_funcs.R

@@ -242,7 +242,7 @@ delete_blob_container.blob_endpoint <- function(endpoint, name, confirm=TRUE, le
 #' `upload_blob` and `download_blob` can display a progress bar to track the file transfer. You can control whether to display this with `options(azure_storage_progress_bar=TRUE|FALSE)`; the default is TRUE.
 #'
 #' @return
-#' For `list_blobs`, details on the blobs in the container. For `download_blob`, if `dest=NULL`, the contents of the downloaded blob as a raw vector. For `check_blob` a flag whether the blob exists.
+#' For `list_blobs`, details on the blobs in the container. For `download_blob`, if `dest=NULL`, the contents of the downloaded blob as a raw vector. For `blob_exists` a flag whether the blob exists.
 #'
 #' @seealso
 #' [blob_container], [az_storage], [storage_download], [call_azcopy]
@@ -421,12 +421,12 @@ delete_blob <- function(container, blob, confirm=TRUE)
 
 #' @rdname blob
 #' @export
-check_blob <- function(container, blob)
+blob_exists <- function(container, blob)
 {
     res <- do_container_op(container, blob, headers = list(), http_verb = "HEAD", http_status_handler = "pass")
-    if (httr::status_code(res) == 404L) {
+    if (httr::status_code(res) == 404L)
         return(FALSE)
-    }
+
     httr::stop_for_status(res, storage_error_message(res))
     return(TRUE)
 }

R/client_generics.R

@@ -281,3 +281,25 @@ delete_azure_file(container, file, ...)
 delete_storage_file.adls_filesystem <- function(container, file, confirm=TRUE, ...)
 delete_adls_file(container, file, confirm=confirm, ...)
 
+
+# check existence
+
+#' @rdname generics
+#' @export
+storage_file_exists <- function(container, file, ...)
+UseMethod("storage_file_exists")
+
+#' @rdname generics
+#' @export
+storage_file_exists.blob_container <- function(container, file, ...)
+blob_exists(container, file, ...)
+
+#' @rdname generics
+#' @export
+storage_file_exists.file_share <- function(container, file, ...)
+azure_file_exists(container, file, ...)
+
+#' @rdname generics
+#' @export
+storage_file_exists.adls_filesystem <- function(container, file, ...)
+adls_file_exists(container, file, ...)

R/file_client_funcs.R

@@ -196,7 +196,7 @@ delete_file_share.file_endpoint <- function(endpoint, name, confirm=TRUE, ...)
 
 #' Operations on a file share
 #'
-#' Upload, download, or delete a file; list files in a directory; create or delete directories.
+#' Upload, download, or delete a file; list files in a directory; create or delete directories; check file existence.
 #'
 #' @param share A file share object.
 #' @param dir,file A string naming a directory or file respectively.
@@ -225,6 +225,8 @@ delete_file_share.file_endpoint <- function(endpoint, name, confirm=TRUE, ...)
 #'
 #' For `download_azure_file`, if `dest=NULL`, the contents of the downloaded file as a raw vector.
 #'
+#' For `azure_file_exists`, either TRUE or FALSE.
+#'
 #' @seealso
 #' [file_share], [az_storage], [storage_download], [call_azcopy]
 #'
@@ -399,3 +401,14 @@ delete_azure_dir <- function(share, dir, recursive=FALSE, confirm=TRUE)
     invisible(do_container_op(share, dir, options=list(restype="directory"), http_verb="DELETE"))
 }
 
+#' @rdname file
+#' @export
+azure_file_exists <- function(share, file)
+{
+    res <- do_container_op(share, file, headers = list(), http_verb = "HEAD", http_status_handler = "pass")
+    if (httr::status_code(res) == 404L)
+        return(FALSE)
+
+    httr::stop_for_status(res, storage_error_message(res))
+    return(TRUE)
+}

man/adls.Rd

@@ -9,6 +9,7 @@
 \alias{delete_adls_file}
 \alias{create_adls_dir}
 \alias{delete_adls_dir}
+\alias{adls_file_exists}
 \title{Operations on an Azure Data Lake Storage Gen2 filesystem}
 \usage{
 list_adls_files(filesystem, dir = "/", info = c("all", "name"),
@@ -33,6 +34,8 @@ delete_adls_file(filesystem, file, confirm = TRUE)
 create_adls_dir(filesystem, dir)
 
 delete_adls_dir(filesystem, dir, recursive = FALSE, confirm = TRUE)
+
+adls_file_exists(filesystem, file)
 }
 \arguments{
 \item{filesystem}{An ADLSgen2 filesystem object.}
@@ -61,9 +64,11 @@ delete_adls_dir(filesystem, dir, recursive = FALSE, confirm = TRUE)
 For \code{list_adls_files}, if \code{info="name"}, a vector of file/directory names. If \code{info="all"}, a data frame giving the file size and whether each object is a file or directory.
 
 For \code{download_adls_file}, if \code{dest=NULL}, the contents of the downloaded file as a raw vector.
+
+For \code{adls_file_exists}, either TRUE or FALSE.
 }
 \description{
-Upload, download, or delete a file; list files in a directory; create or delete directories.
+Upload, download, or delete a file; list files in a directory; create or delete directories; check file existence.
 }
 \details{
 \code{upload_adls_file} and \code{download_adls_file} are the workhorse file transfer functions for ADLSgen2 storage. They each take as inputs a \emph{single} filename as the source for uploading/downloading, and a single filename as the destination. Alternatively, for uploading, \code{src} can be a \link{textConnection} or \link{rawConnection} object; and for downloading, \code{dest} can be NULL or a \code{rawConnection} object. If \code{dest} is NULL, the downloaded data is returned as a raw vector, and if a raw connection, it will be placed into the connection. See the examples below.

man/blob.Rd

@@ -5,9 +5,9 @@
 \alias{upload_blob}
 \alias{multiupload_blob}
 \alias{download_blob}
-\alias{check_blob}
 \alias{multidownload_blob}
 \alias{delete_blob}
+\alias{blob_exists}
 \alias{copy_url_to_blob}
 \alias{multicopy_url_to_blob}
 \title{Operations on a blob container or blob}
@@ -31,7 +31,7 @@ multidownload_blob(container, src, dest, recursive = FALSE,
 
 delete_blob(container, blob, confirm = TRUE)
 
-check_blob(container, blob)
+blob_exists(container, blob)
 
 copy_url_to_blob(container, src, dest, lease = NULL, async = FALSE)
 
@@ -70,7 +70,7 @@ multicopy_url_to_blob(container, src, dest, lease = NULL,
 \item{async}{For \code{copy_url_to_blob} and \code{multicopy_url_to_blob}, whether the copy operation should be asynchronous (proceed in the background).}
 }
 \value{
-For \code{list_blobs}, details on the blobs in the container. For \code{download_blob}, if \code{dest=NULL}, the contents of the downloaded blob as a raw vector. For \code{check_blob} a flag whether the blob exists.
+For \code{list_blobs}, details on the blobs in the container. For \code{download_blob}, if \code{dest=NULL}, the contents of the downloaded blob as a raw vector. For \code{blob_exists} a flag whether the blob exists.
 }
 \description{
 Upload, download, or delete a blob; list blobs in a container; check blob availability.

man/file.Rd

@@ -9,6 +9,7 @@
 \alias{delete_azure_file}
 \alias{create_azure_dir}
 \alias{delete_azure_dir}
+\alias{azure_file_exists}
 \title{Operations on a file share}
 \usage{
 list_azure_files(share, dir = "/", info = c("all", "name"),
@@ -33,6 +34,8 @@ delete_azure_file(share, file, confirm = TRUE)
 create_azure_dir(share, dir, recursive = FALSE)
 
 delete_azure_dir(share, dir, recursive = FALSE, confirm = TRUE)
+
+azure_file_exists(share, file)
 }
 \arguments{
 \item{share}{A file share object.}
@@ -63,9 +66,11 @@ delete_azure_dir(share, dir, recursive = FALSE, confirm = TRUE)
 For \code{list_azure_files}, if \code{info="name"}, a vector of file/directory names. If \code{info="all"}, a data frame giving the file size and whether each object is a file or directory.
 
 For \code{download_azure_file}, if \code{dest=NULL}, the contents of the downloaded file as a raw vector.
+
+For \code{azure_file_exists}, either TRUE or FALSE.
 }
 \description{
-Upload, download, or delete a file; list files in a directory; create or delete directories.
+Upload, download, or delete a file; list files in a directory; create or delete directories; check file existence.
 }
 \details{
 \code{upload_azure_file} and \code{download_azure_file} are the workhorse file transfer functions for file storage. They each take as inputs a \emph{single} filename as the source for uploading/downloading, and a single filename as the destination. Alternatively, for uploading, \code{src} can be a \link{textConnection} or \link{rawConnection} object; and for downloading, \code{dest} can be NULL or a \code{rawConnection} object. If \code{dest} is NULL, the downloaded data is returned as a raw vector, and if a raw connection, it will be placed into the connection. See the examples below.

man/generics.Rd

@@ -40,6 +40,10 @@
 \alias{delete_storage_file.blob_container}
 \alias{delete_storage_file.file_share}
 \alias{delete_storage_file.adls_filesystem}
+\alias{storage_file_exists}
+\alias{storage_file_exists.blob_container}
+\alias{storage_file_exists.file_share}
+\alias{storage_file_exists.adls_filesystem}
 \title{Storage client generics}
 \usage{
 storage_container(endpoint, ...)
@@ -123,6 +127,14 @@ delete_storage_file(container, ...)
 
 \method{delete_storage_file}{adls_filesystem}(container, file,
   confirm = TRUE, ...)
+
+storage_file_exists(container, file, ...)
+
+\method{storage_file_exists}{blob_container}(container, file, ...)
+
+\method{storage_file_exists}{file_share}(container, file, ...)
+
+\method{storage_file_exists}{adls_filesystem}(container, file, ...)
 }
 \arguments{
 \item{endpoint}{A storage endpoint object, or for the character methods, a string giving the full URL to the container.}

tests/testthat/test02_blob.R

@@ -135,8 +135,8 @@ test_that("Blob client interface works",
     expect_identical(iris, iris3)
 
     # check blob
-    expect_false(check_blob(cont, "nonexisting.blob"))
-    expect_true(check_blob(cont, "iris.json"))
+    expect_false(blob_exists(cont, "nonexistent"))
+    expect_true(blob_exists(cont, "iris.json"))
 
     # ways of deleting a container
     delete_blob_container(cont, confirm=FALSE)

tests/testthat/test03_file.R

@@ -139,6 +139,10 @@ test_that("File client interface works",
     iris3 <- as.data.frame(jsonlite::fromJSON(con))
     expect_identical(iris, iris3)
 
+    # check existence
+    expect_false(azure_file_exists(share, "nonexistent"))
+    expect_true(azure_file_exists(share, "iris.json"))
+
     # ways of deleting a share
     delete_file_share(share, confirm=FALSE)
     delete_file_share(fl, "newshare2", confirm=FALSE)

tests/testthat/test04_adls.R

@@ -127,6 +127,10 @@ test_that("ADLSgen2 client interface works",
     iris3 <- as.data.frame(jsonlite::fromJSON(con))
     expect_identical(iris, iris3)
 
+    # check existence
+    expect_false(adls_file_exists(fs, "nonexistent"))
+    expect_true(adls_file_exists(fs, "iris.json"))
+
     # ways of deleting a filesystem
     delete_adls_filesystem(fs, confirm=FALSE)
     delete_adls_filesystem(ad, "newfs2", confirm=FALSE)

tests/testthat/test05_generics.R

@@ -45,6 +45,10 @@ test_that("Blob dispatch works",
     expect_silent(storage_upload(cont, file.path("../resources", filename), filename))
     expect_silent(storage_download(cont, filename, tempfile()))
 
+    # file existence
+    expect_false(storage_file_exists(cont, "nonexistent"))
+    expect_true(storage_file_exists(cont, filename))
+
     # delete the objects
     expect_silent(delete_storage_file(cont, filename, confirm=FALSE))
     expect_error(delete_storage_dir(cont, dirname, confirm=FALSE))
@@ -75,6 +79,10 @@ test_that("File dispatch works",
     expect_silent(storage_upload(cont, file.path("../resources", filename), file.path(dirname, filename)))
     expect_silent(storage_download(cont, file.path(dirname, filename), tempfile()))
 
+    # file existence
+    expect_false(storage_file_exists(cont, "nonexistent"))
+    expect_true(storage_file_exists(cont, file.path(dirname, filename)))
+
     # delete the objects
     expect_silent(delete_storage_file(cont, file.path(dirname, filename), confirm=FALSE))
     expect_silent(delete_storage_dir(cont, dirname, confirm=FALSE))
@@ -105,6 +113,10 @@ test_that("ADLSgen2 dispatch works",
     expect_silent(storage_upload(cont, file.path("../resources", filename), file.path(dirname, filename)))
     expect_silent(storage_download(cont, file.path(dirname, filename), tempfile()))
 
+    # file existence
+    expect_false(storage_file_exists(cont, "nonexistent"))
+    expect_true(storage_file_exists(cont, file.path(dirname, filename)))
+
     # delete the objects
     expect_silent(delete_storage_file(cont, file.path(dirname, filename), confirm=FALSE))
     expect_silent(delete_storage_dir(cont, dirname, confirm=FALSE))