rm attachment code (deprecated), other cran fixes

NAMESPACE

@@ -3,14 +3,11 @@
 S3method(bulk_delete,cosmos_container)
 S3method(bulk_import,cosmos_container)
 S3method(cosmos_mongo_connection,cosmos_mongo_endpoint)
-S3method(create_attachment,cosmos_document)
 S3method(create_cosmos_container,cosmos_database)
 S3method(create_cosmos_database,cosmos_endpoint)
 S3method(create_document,cosmos_container)
 S3method(create_stored_procedure,cosmos_container)
 S3method(create_udf,cosmos_container)
-S3method(delete_attachment,cosmos_attachment)
-S3method(delete_attachment,cosmos_document)
 S3method(delete_cosmos_container,cosmos_container)
 S3method(delete_cosmos_container,cosmos_database)
 S3method(delete_cosmos_database,cosmos_database)
@@ -25,7 +22,6 @@ S3method(do_cosmos_op,cosmos_container)
 S3method(do_cosmos_op,cosmos_database)
 S3method(do_cosmos_op,cosmos_document)
 S3method(do_cosmos_op,cosmos_endpoint)
-S3method(download_attachment,cosmos_attachment)
 S3method(exec_stored_procedure,cosmos_container)
 S3method(exec_stored_procedure,cosmos_stored_procedure)
 S3method(get_cosmos_container,cosmos_database)
@@ -34,13 +30,11 @@ S3method(get_cosmos_database,cosmos_endpoint)
 S3method(get_document,cosmos_container)
 S3method(get_stored_procedure,cosmos_container)
 S3method(get_udf,cosmos_container)
-S3method(list_attachments,cosmos_document)
 S3method(list_cosmos_containers,cosmos_database)
 S3method(list_cosmos_databases,cosmos_endpoint)
 S3method(list_documents,cosmos_container)
 S3method(list_stored_procedures,cosmos_container)
 S3method(list_udfs,cosmos_container)
-S3method(print,cosmos_attachment)
 S3method(print,cosmos_container)
 S3method(print,cosmos_database)
 S3method(print,cosmos_document)
@@ -62,20 +56,17 @@ export(call_cosmos_endpoint)
 export(cosmos_endpoint)
 export(cosmos_mongo_connection)
 export(cosmos_mongo_endpoint)
-export(create_attachment)
 export(create_cosmos_container)
 export(create_cosmos_database)
 export(create_document)
 export(create_stored_procedure)
 export(create_udf)
-export(delete_attachment)
 export(delete_cosmos_container)
 export(delete_cosmos_database)
 export(delete_document)
 export(delete_stored_procedure)
 export(delete_udf)
 export(do_cosmos_op)
-export(download_attachment)
 export(exec_stored_procedure)
 export(get_cosmos_container)
 export(get_cosmos_database)
@@ -83,7 +74,6 @@ export(get_document)
 export(get_partition_key)
 export(get_stored_procedure)
 export(get_udf)
-export(list_attachments)
 export(list_cosmos_containers)
 export(list_cosmos_databases)
 export(list_documents)

R/attachment.R

@@ -1,156 +0,0 @@
-#' Methods for working with Azure Cosmos DB attachments
-#'
-#' @param document A Cosmos DB document object, as obtained by `get_document`, `create_document`, `list_documents` or `query_documents`.
-#' @param file For `create_attachment`, the file to turn into an attachment. This can be a filename, a raw connection, or a URL connection pointing to a location on the Internet.
-#' @param content_type For `create_attachment`, the content type of the attachment. Defaults to "application/octet-stream".
-#' @param id For `create_attachment` and `delete_attachment`, the ID for the attachment. This is optional for `create_attachment`.
-#' @param attachment For `download_attachment`, the attachment object, as obtained by `list_attachments` or `create_attachment`.
-#' @param destfile For `download_attachment`, the destination filename.
-#' @param overwrite For `download_attachment`, whether to overwrite an existing destination file.
-#' @param confirm For `delete_attachment`, whether to ask for confirmation before deleting.
-#' @param options,headers,... Optional arguments passed to lower-level functions.
-#' @details
-#' These are methods for working with document attachments in Cosmos DB using the core (SQL) API. Note that the attachments API is deprecated; going forward, you should explore other options for hosting external files, such as Azure blob storage.
-#'
-#' @aliases cosmos_attachment
-#' @rdname cosmos_attachment
-#' @export
-list_attachments <- function(document, ...)
-{
-    UseMethod("list_attachments")
-}
-
-#' @rdname cosmos_attachment
-#' @export
-list_attachments.cosmos_document <- function(document, ...)
-{
-    res <- do_cosmos_op(document, "attachments", "attachments", "", ...)
-    atts <- if(inherits(res, "response"))
-        process_cosmos_response(res, ...)$Attachments
-    else unlist(lapply(process_cosmos_response(res, ...), `[[`, "Attachments"), recursive=FALSE)
-    lapply(atts, as_attachment, document=document)
-}
-
-
-#' @rdname cosmos_attachment
-#' @export
-create_attachment <- function(document, ...)
-{
-    UseMethod("create_attachment")
-}
-
-#' @rdname cosmos_attachment
-#' @export
-create_attachment.cosmos_document <- function(document, file, content_type="application/octet-stream",
-    id=NULL, headers=list(), ...)
-{
-    # read the data if a (non-URL) connection or filename
-    if((inherits(file, "connection") && !inherits(file, "url")) ||
-       (is.character(file) && length(file) == 1 && file.exists(file)))
-    {
-        if(is.character(file))
-            file <- file(file, open="rb")
-
-        on.exit(close(file))
-        body <- raw(0)
-        repeat
-        {
-            chunk <- readBin(file, "raw", 1e6)
-            if(length(chunk) == 0)
-                break
-            body <- c(body, chunk)
-        }
-        headers$`Content-Type` <- content_type
-    }
-    else
-    {
-        if(inherits(file, "url"))
-            file <- summary(file)$description
-        if(is.null(id))
-            id <- uuid::UUIDgenerate()
-        body <- jsonlite::toJSON(list(
-            id=id,
-            contentType=content_type,
-            media=file
-        ), auto_unbox=TRUE)
-    }
-    res <- do_cosmos_op(document, "attachments", "attachments", "", headers=headers, body=body, http_verb="POST", ...)
-    att <- process_cosmos_response(res, ...)
-    invisible(as_attachment(att, document))
-}
-
-
-#' @rdname cosmos_attachment
-#' @export
-download_attachment <- function(attachment, ...)
-{
-    UseMethod("download_attachment")
-}
-
-#' @rdname cosmos_attachment
-#' @export
-download_attachment.cosmos_attachment <- function(attachment, destfile, options=list(), headers=list(),
-    overwrite=FALSE, ...)
-{
-    url <- httr::parse_url(attachment$media)
-    if(is.null(url$scheme))  # attachment is hosted in Cosmos DB
-    {
-        key <- attachment$document$container$database$endpoint$key
-        reslink <- tolower(attachment$`_rid`)
-        now <- httr::http_date(Sys.time())
-        sig <- sign_cosmos_request(key, "GET", "media", reslink, now)
-        headers <- utils::modifyList(headers, list(
-            Authorization=sig,
-            `x-ms-date`=now,
-            `x-ms-version`=attachment$document$container$database$endpoint$api_version
-        ))
-        url <- attachment$document$container$database$endpoint$host
-        url$path <- attachment$media
-    }
-    else url$query <- options
-
-    httr::GET(url, do.call(httr::add_headers, headers),
-              config=httr::write_disk(destfile, overwrite=overwrite), httr::progress())
-}
-
-
-#' @rdname cosmos_attachment
-#' @export
-delete_attachment <- function(document, ...)
-{
-    UseMethod("delete_attachment")
-}
-
-#' @rdname cosmos_attachment
-#' @export
-delete_attachment.cosmos_document <- function(document, id, confirm=TRUE, ...)
-{
-    if(!delete_confirmed(confirm, id, "attachment"))
-        return(invisible(NULL))
-
-    path <- file.path("attachments", id)
-    res <- do_cosmos_op(document, path, "attachments", path, http_verb="DELETE", ...)
-    invisible(process_cosmos_response(res, ...))
-}
-
-#' @rdname cosmos_attachment
-#' @export
-delete_attachment.cosmos_attachment <- function(document, ...)
-{
-    delete_attachment(document$document, document$id, ...)
-}
-
-
-#' @export
-print.cosmos_attachment <- function(x, ...)
-{
-    cat("Cosmos DB document attachment '", x$id, "'\n", sep="")
-    invisible(x)
-}
-
-
-as_attachment <- function(attachment, document)
-{
-    attachment$document <- document
-    structure(attachment, class="cosmos_attachment")
-}

R/bulk.R

@@ -10,6 +10,8 @@
 #' This is a convenience function to import a dataset into a container. It works by creating a stored procedure and then calling it in a loop, passing the to-be-imported data in chunks. The dataset must include a column for the container's partition key or an error will result.
 #'
 #' Note that this function is not meant for production use. In particular, if the import fails midway through, it will not clean up after itself: you should call `bulk_delete` to remove the remnants of a failed import.
+#' @return
+#' A list containing the number of rows imported, for each value of the partition key.
 #' @seealso
 #' [bulk_delete], [cosmos_container]
 #' @examples
@@ -24,7 +26,7 @@
 #' bulk_import(cont, dplyr::starwars)
 #'
 #' # importing from a JSON file
-#' writeLines(jsonlite::toJSON(dplyr::starwars), "starwars.json"
+#' writeLines(jsonlite::toJSON(dplyr::starwars), "starwars.json")
 #' bulk_import(cont, "starwars.json")
 #'
 #' }
@@ -101,6 +103,8 @@ import_by_key <- function(container, key, data, procname, init_chunksize, header
 #' @param headers,... Optional arguments passed to lower-level functions.
 #' @details
 #' This is a convenience function to delete multiple documents from a container. It works by creating a stored procedure and then calling it with the supplied query as a parameter. This function is not meant for production use.
+#' @return
+#' The number of rows deleted.
 #' @seealso
 #' [bulk_import], [cosmos_container]
 #' @examples

R/query.R

@@ -17,6 +17,8 @@
 #' The `by_pkrange` argument allows running the query separately across all _partition key ranges_. Each partition key range corresponds to a separate physical partition, and contains the documents for one or more key values. You can set this to TRUE to run a query that fails when run across partitions; the returned object will be a list containing the individual query results from each pkrange.
 #'
 #' As an alternative to AzureCosmosR, you can also use the ODBC protocol to interface with the SQL API. By installing a suitable ODBC driver, you can then talk to Cosmos DB in a manner similar to other SQL databases. An advantage of the ODBC interface is that it fully supports cross-partition queries, unlike the REST API. A disadvantage is that it does not support nested document fields; functions like `array_contains()` cannot be used, and attempts to reference arrays and objects may return incorrect results.
+#' @return
+#' `query_documents` returns the results of the query. Most of the time this will be a data frame, or list of data frames if `by_pkrange=TRUE`.
 #' @seealso
 #' [cosmos_container], [cosmos_document], [list_partition_key_values], [list_partition_key_ranges]
 #' @examples

R/sproc.R

@@ -9,6 +9,8 @@
 #' @details
 #' These are methods for working with stored procedures in Azure Cosmos DB using the core (SQL) API. In the Cosmos DB model, stored procedures are written in JavaScript and associated with a container.
 #'
+#' @return
+#' For `get_stored_procedure` and `create_stored_procedure`, an object of class `cosmos_stored_procedure`. For `list_stored_procedures`, a list of such objects.
 #' @seealso
 #' [cosmos_container], [get_udf]
 #' @examples

R/udf.R

@@ -8,6 +8,8 @@
 #' @details
 #' These are methods for working with user-defined functions (UDFs) in Azure Cosmos DB using the core (SQL) API. In the Cosmos DB model, UDFs are written in JavaScript and associated with a container.
 #'
+#' @return
+#' For `get_udf` and `create_udf`, an object of class `cosmos_udf`. For `list_udfs`, a list of such objects.
 #' @seealso
 #' [cosmos_container], [get_stored_procedure]
 #' @examples

man/bulk_delete.Rd

@@ -27,6 +27,9 @@ bulk_delete(container, ...)
 
 \item{headers, ...}{Optional arguments passed to lower-level functions.}
 }
+\value{
+The number of rows deleted.
+}
 \description{
 Delete a set of documents from an Azure Cosmos DB container
 }

man/bulk_import.Rd

@@ -29,6 +29,9 @@ bulk_import(container, ...)
 
 \item{procname}{The stored procedure name to use for the server-side import code. Change this if, for some reason, the default name is taken.}
 }
+\value{
+A list containing the number of rows imported, for each value of the partition key.
+}
 \description{
 Import a set of documents to an Azure Cosmos DB container
 }
@@ -49,7 +52,7 @@ cont <- create_cosmos_container(db, "mycontainer", partition_key="sex")
 bulk_import(cont, dplyr::starwars)
 
 # importing from a JSON file
-writeLines(jsonlite::toJSON(dplyr::starwars), "starwars.json"
+writeLines(jsonlite::toJSON(dplyr::starwars), "starwars.json")
 bulk_import(cont, "starwars.json")
 
 }

man/cosmos_attachment.Rd

@@ -1,72 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/attachment.R
-\name{list_attachments}
-\alias{list_attachments}
-\alias{cosmos_attachment}
-\alias{list_attachments.cosmos_document}
-\alias{create_attachment}
-\alias{create_attachment.cosmos_document}
-\alias{download_attachment}
-\alias{download_attachment.cosmos_attachment}
-\alias{delete_attachment}
-\alias{delete_attachment.cosmos_document}
-\alias{delete_attachment.cosmos_attachment}
-\title{Methods for working with Azure Cosmos DB attachments}
-\usage{
-list_attachments(document, ...)
-
-\method{list_attachments}{cosmos_document}(document, ...)
-
-create_attachment(document, ...)
-
-\method{create_attachment}{cosmos_document}(
-  document,
-  file,
-  content_type = "application/octet-stream",
-  id = NULL,
-  headers = list(),
-  ...
-)
-
-download_attachment(attachment, ...)
-
-\method{download_attachment}{cosmos_attachment}(
-  attachment,
-  destfile,
-  options = list(),
-  headers = list(),
-  overwrite = FALSE,
-  ...
-)
-
-delete_attachment(document, ...)
-
-\method{delete_attachment}{cosmos_document}(document, id, confirm = TRUE, ...)
-
-\method{delete_attachment}{cosmos_attachment}(document, ...)
-}
-\arguments{
-\item{document}{A Cosmos DB document object, as obtained by \code{get_document}, \code{create_document}, \code{list_documents} or \code{query_documents}.}
-
-\item{file}{For \code{create_attachment}, the file to turn into an attachment. This can be a filename, a raw connection, or a URL connection pointing to a location on the Internet.}
-
-\item{content_type}{For \code{create_attachment}, the content type of the attachment. Defaults to "application/octet-stream".}
-
-\item{id}{For \code{create_attachment} and \code{delete_attachment}, the ID for the attachment. This is optional for \code{create_attachment}.}
-
-\item{attachment}{For \code{download_attachment}, the attachment object, as obtained by \code{list_attachments} or \code{create_attachment}.}
-
-\item{destfile}{For \code{download_attachment}, the destination filename.}
-
-\item{options, headers, ...}{Optional arguments passed to lower-level functions.}
-
-\item{overwrite}{For \code{download_attachment}, whether to overwrite an existing destination file.}
-
-\item{confirm}{For \code{delete_attachment}, whether to ask for confirmation before deleting.}
-}
-\description{
-Methods for working with Azure Cosmos DB attachments
-}
-\details{
-These are methods for working with document attachments in Cosmos DB using the core (SQL) API. Note that the attachments API is deprecated; going forward, you should explore other options for hosting external files, such as Azure blob storage.
-}

man/cosmos_stored_procedure.Rd

@@ -59,6 +59,9 @@ delete_stored_procedure(object, ...)
 
 \item{confirm}{For \code{delete_stored_procedure}, whether to ask for confirmation before deleting.}
 }
+\value{
+For \code{get_stored_procedure} and \code{create_stored_procedure}, an object of class \code{cosmos_stored_procedure}. For \code{list_stored_procedures}, a list of such objects.
+}
 \description{
 Methods for working with Azure Cosmos DB stored procedures
 }

man/cosmos_udf.Rd

@@ -47,6 +47,9 @@ delete_udf(object, ...)
 
 \item{confirm}{For \code{delete_udf}, whether to ask for confirmation before deleting.}
 }
+\value{
+For \code{get_udf} and \code{create_udf}, an object of class \code{cosmos_udf}. For \code{list_udfs}, a list of such objects.
+}
 \description{
 Methods for working with Azure Cosmos DB user-defined functions
 }

man/query_documents.Rd

@@ -35,6 +35,9 @@ query_documents(container, ...)
 
 \item{headers, ...}{Optional arguments passed to lower-level functions.}
 }
+\value{
+\code{query_documents} returns the results of the query. Most of the time this will be a data frame, or list of data frames if \code{by_pkrange=TRUE}.
+}
 \description{
 Query an Azure Cosmos DB container
 }