Merge pull request #16 from OldLipe/b-0.9.0

Update functions and add items functions

.Rbuildignore

@@ -7,3 +7,5 @@
 ^_pkgdown\.yml$
 ^docs$
 ^pkgdown$
+^README\.Rmd$
+^README-.*\.png$

DESCRIPTION

@@ -18,9 +18,10 @@ LazyData: true
 RoxygenNote: 7.1.1
 Depends:
     httr,
-    crayon
+    crayon,
+    utils,
+    magrittr
 Suggests:
     covr,
-    magrittr,
     testthat,
     vcr

NAMESPACE

@@ -1,26 +1,72 @@
 # Generated by roxygen2: do not edit by hand
 
-S3method(print,stac)
-S3method(print,stac_catalog)
-S3method(print,stac_collection)
-S3method(print,stac_collection_list)
-S3method(print,stac_item)
-S3method(print,stac_item_collection)
+S3method(after_response,RSTACQuery)
+S3method(after_response,collection_id)
+S3method(after_response,collections)
+S3method(after_response,ext_query)
+S3method(after_response,item_id)
+S3method(after_response,items)
+S3method(after_response,search)
+S3method(after_response,stac)
+S3method(before_request,RSTACQuery)
+S3method(before_request,collection_id)
+S3method(before_request,collections)
+S3method(before_request,ext_query)
+S3method(before_request,item_id)
+S3method(before_request,items)
+S3method(before_request,search)
+S3method(before_request,stac)
+S3method(check_subclass,RSTACDocument)
+S3method(check_subclass,RSTACQuery)
+S3method(endpoint,RSTACQuery)
+S3method(endpoint,collection_id)
+S3method(endpoint,collections)
+S3method(endpoint,ext_query)
+S3method(endpoint,item_id)
+S3method(endpoint,items)
+S3method(endpoint,search)
+S3method(endpoint,stac)
+S3method(print,RSTACQuery)
+S3method(print,STACCatalog)
+S3method(print,STACCollection)
+S3method(print,STACCollectionList)
+S3method(print,STACItem)
+S3method(print,STACItemCollection)
+S3method(stac_version,RSTACDocument)
+S3method(stac_version,RSTACQuery)
+S3method(stac_version,STACCollectionList)
+S3method(subclass,RSTACDocument)
+S3method(subclass,RSTACQuery)
+export(RSTACDocument)
+export(RSTACQuery)
+export(after_response)
 export(assets_download)
+export(assets_list)
+export(before_request)
+export(check_query_verb)
+export(check_subclass)
 export(collections)
-export(content_get_response)
-export(content_post_response)
-export(extension_query)
+export(content_response)
+export(doc_query)
+export(endpoint)
+export(ext_query)
 export(get_request)
 export(items)
+export(items_bands)
+export(items_bbox)
+export(items_datetime)
 export(items_fetch)
+export(items_fields)
+export(items_group)
 export(items_length)
 export(items_matched)
-export(params_get_request)
-export(params_post_request)
+export(items_reap)
+export(omit_query_params)
 export(post_request)
 export(stac)
 export(stac_search)
+export(stac_version)
+export(subclass)
 importFrom(crayon,bold)
 importFrom(httr,GET)
 importFrom(httr,POST)
@@ -29,3 +75,5 @@ importFrom(httr,content)
 importFrom(httr,http_type)
 importFrom(httr,status_code)
 importFrom(httr,write_disk)
+importFrom(magrittr,"%>%")
+importFrom(utils,modifyList)

NEWS.md

@@ -0,0 +1,22 @@
+# rstac (development version)
+
+* Fix issue from CRAN.
+
+# rstac 0.9.0 (Released 2020-09-18)
+
+* Preparing package to send to CRAN.
+* Update documentation.
+* Add function for extensions creating.
+* Add new tests.
+* Support for STAC version 0.9.0 and 0.8.1.
+
+# rstac 0.8.1 (Released 2020-08-24)
+
+* Support for STAC version 0.8.0 and 0.8.1.
+* Add functions to download and support analysis from items objects.
+* Add new tests.
+* License: `MIT <https://raw.githubusercontent.com/brazil-data-cube/rstac/b-0.9.0/LICENSE>`_ .
+* Update documentation.
+* Add CI support.
+* Add tests for CI.
+* Unit-tests with code coverage.

R/assets_download.R

@@ -1,9 +1,9 @@
-#' @title assets download
+#' @title Downloads assets via STAC API
 #'
 #' @description The \code{assets_download} function downloads the assets
 #' provided by the STAC API.
 #'
-#' @param items       a \code{stac_item_collection} or \code{stac_item} object
+#' @param items       a \code{STACItem} or \code{STACItemCollection} object
 #'  representing the result of \code{/stac/search},
 #'  \code{/collections/{collectionId}/items} or
 #'  \code{/collections/{collectionId}/items/{itemId}} endpoints.
@@ -13,76 +13,89 @@
 #' @param output_dir  a \code{character} directory in which the assets will be
 #'  saved.
 #'
+#' @param overwrite  a \code{logical} if TRUE will replaced the existing file,
+#'  if FALSE a warning message is shown.
+#'
+#' @param items_max a \code{numeric} corresponding how many items will be
+#'  downloaded.
+#'
 #' @param progress    a \code{logical} indicating if a progress bar must be
 #'  shown or not. Defaults to \code{TRUE}.
 #'
-#' @param ...        other params to be passed to \link[httr]{GET} method.
-#'
-#' @param headers    a \code{character} of named arguments to be passed as
-#' HTTP request headers.
+#' @param ...       config parameters to be passed to \link[httr]{GET} or
+#' \link[httr]{POST} methods, such as \link[httr]{add_headers} or
+#' \link[httr]{set_cookies}.
 #'
 #' @seealso
 #' \code{\link{stac_search}}, \code{\link{items}}, \code{\link{get_request}}
 #'
 #' @examples
 #' \dontrun{
 #'
-#' stac("http://brazildatacube.dpi.inpe.br/bdc-stac/0.8.1",
-#'      force_version = "0.8.1") %>%
-#'  stac_search(collections = "MOD13Q1",
-#'             bbox = c(-55.16335, -4.26325, -49.31739, -1.18355),
-#'             limit = 2) %>%
-#'  get_request() %>%
-#'  assets_download(assets_name = c("thumbnail"), output_dir = ".")
+#' stac("http://brazildatacube.dpi.inpe.br/stac/") %>%
+#'   stac_search(collections = "CB4_64_16D_STK-1") %>%
+#'   stac_search(limit = 2) %>%
+#'   get_request() %>%
+#'   assets_download(assets_name = "thumbnail", output_dir = ".",
+#'   overwrite = FALSE)
 #' }
 #'
-#' @return The same \code{stac_item_collection} or \code{stac_item} object, with the
+#' @return The same \code{STACItemCollection} or \code{STACItem} object, with the
 #' link of the item pointing to the directory where the assets were saved.
 #'
 #' @export
 assets_download <- function(items, assets_name, output_dir = ".",
-                            progress = TRUE, ..., headers = character()) {
+                            overwrite = FALSE, items_max = Inf, progress = TRUE, ...) {
 
-  # TODO: add parameter to cut out the assets if provided - keep_assets
-  # TODO: warning if the value of item_length is different of item_matched
-
-  #check the object class
-  .check_obj(items, expected = c("stac_item_collection", "stac_item"))
+  #check the object subclass
+  check_subclass(items, subclasses = c("STACItemCollection", "STACItem"))
 
   # check output dir
   if (!dir.exists(output_dir))
     .error(paste("The directory provided does not exist.",
                  "Please specify a valid directory."))
 
-  if (inherits(items, "stac_item")) {
+  # if the object is a STACItem
+  if (subclass(items) == "STACItem") {
     items <- .item_download(stac_item   = items,
                             assets_name = assets_name,
                             output_dir  = output_dir,
-                            ..., headers = headers)
-
+                            overwrite   = overwrite, ...)
     return(items)
   }
 
-  items_len <- items_length(items)
-  # Queries that return without features
-  if (items_len == 0)
-    .error(paste("Query provided returned 0 items.",
-                 "Please verify your query"))
+  # check if items length corresponds with items matched
+  if (!missing(items_max)) {
+    if (items_max > items_length(items)) {
+      .warning(paste("The number of specified items is greater than the number",
+                     "of items length on your object. By default, items_max = %d"),
+               items_length(items))
+
+      items_max <- .parse_items_size(items)
+    }
+  } else {
+    # Queries that return without features
+    if (items_length(items) == 0)
+      .error(paste("Query provided returned 0 items.",
+                   "Please verify your query."))
+
+    items_max <- .parse_items_size(items)
+  }
 
   # verify if progress bar can be shown
-  progress <- progress & (!is.null(items_len))
+  progress <- progress & (!is.null(items_max))
   if (progress)
-    pb <- utils::txtProgressBar(min = 0, max = items_len, style = 3, width = 50)
+    pb <- utils::txtProgressBar(min = 0, max = items_max, style = 3, width = 50)
 
-  for (i in seq_len(items_len)) {
+  for (i in seq_len(items_max)) {
 
     # toggle bar
     if (progress)
       utils::setTxtProgressBar(pb, i)
 
     items$features[[i]] <- .item_download(items$features[[i]],
                                           assets_name, output_dir,
-                                          ..., headers = headers)
+                                          overwrite,...)
   }
   # close progress bar
   if (progress)
@@ -106,18 +119,18 @@ assets_download <- function(items, assets_name, output_dir = ".",
 #' @param output_dir  a \code{character} directory in which the images will be
 #'  saved.
 #'
-#' @param ...        other params to be passed to \link[httr]{GET} or
-#' \link[httr]{POST} methods
+#' @param overwrite  a \code{logical} if TRUE will replaced the existing file,
+#'  if FALSE a warning message is shown.
 #'
-#' @param headers    a \code{character} of named arguments to be passed as
-#' HTTP request headers.
+#' @param ...       config parameters to be passed to \link[httr]{GET} or
+#' \link[httr]{POST} methods, such as \link[httr]{add_headers} or
+#' \link[httr]{set_cookies}.
 #'
 #' @return The same \code{stac_item} object, but with the link of the item
 #'  pointing to the directory where the assets were saved.
 #'
 #' @noRd
-.item_download <- function(stac_item, assets_name, output_dir, ...,
-                           headers = character()) {
+.item_download <- function(stac_item, assets_name, output_dir, overwrite, ...) {
 
   feat_id <- stac_item[["id"]]
   assets  <- .select_assets(stac_item[["assets"]], assets_name)
@@ -134,11 +147,10 @@ assets_download <- function(items, assets_name, output_dir = ".",
 
     tryCatch({
       httr::GET(url = asset_href,
-                httr::write_disk(path = dest_file),
-                httr::add_headers(headers), ...)
+                httr::write_disk(path = dest_file, overwrite = overwrite), ...)
 
     }, error = function(error){
-      warning(paste("\n", error, "in ", asset_href))
+      .warning(paste("\n", error, "in ", asset_href))
     })
 
     if (file.exists(dest_file)) {
@@ -187,8 +199,8 @@ assets_download <- function(items, assets_name, output_dir = ".",
   }
 
   if (!all(assets_names %in% names(assets))) {
-    .error(paste("The provided assets names do not match with the API",
-                 "assets names. By default, all assets will be used"))
+    .error(paste("The provided assets names do not match with the",
+                 "assets names in the document."))
   }
   assets <- assets[names(assets) %in% assets_names]