Improve entity_list: add parameter deleted

ropensci · Apr 1, 2024 · c8c0d34 · c8c0d34
1 parent cbce233
commit c8c0d34
Show file tree

Hide file tree

Showing 7 changed files with 58 additions and 53 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,12 +1,12 @@
 Type: Package
 Package: ruODK
 Title: An R Client for the ODK Central API
-Version: 1.4.9.9004
+Version: 1.4.9.9005
 Authors@R: 
     c(person(given = c("Florian", "W."),
              family = "Mayer",
              role = c("aut", "cre"),
-             email = "Florian.Mayer@dbca.wa.gov.au",
+             email = "Florian.Mayer@dpc.wa.gov.au",
              comment = c(ORCID = "0000-0003-4269-4242")),
       person(given = "Maëlle",
              family = "Salmon",
@@ -33,9 +33,12 @@ Authors@R:
       person(given = "NWSFTCP",
              role = "fnd"))
 Description: Access and tidy up data from the 'ODK Central' API.  
-    'ODK Central' is a clearinghouse for digitally captured data 
+    'ODK Central' is a clearinghouse for digitally captured data using ODK 
     <https://docs.getodk.org/central-intro/>.
-    'ODK Central' and its API are documented at <https://docs.getodk.org/>.
+    It manages user accounts and permissions, stores form definitions, and 
+    allows data collection clients like 'ODK Collect' to connect to it for form 
+    download and submission upload. The 'ODK Central' API is documented at 
+    <https://docs.getodk.org/central-api/>.
 License: GPL-3
 URL: https://docs.ropensci.org/ruODK,
     https://github.com/ropensci/ruODK

diff --git a/R/entity_list.R b/R/entity_list.R
@@ -5,18 +5,17 @@
 #' This function returns a list of the Entities of a kind (belonging to an
 #' Entity List or Dataset).
 #' Please note that this endpoint only returns metadata of the entities, not the
-#' data. If you want to get the data of all entities then please refer to OData
-#' Dataset Service
+#' data. If you want to get the data of all entities then please refer to the
+#' OData Dataset Service.
 #'
-#' You can provide ?deleted=true to get only deleted entities.
-#'
-#' `entity_list()` will fail with incorrect or missing authentication.
-#'
-#' This function is supported from ODK Central v2022.3 and will warn if the
-#' given odkc_version is lower.
+#' You can get only deleted entities with `deleted=TRUE`.
 #'
+#' @template tpl-auth-missing
+#' @template tpl-compat-2022-3
 #' @template param-pid
 #' @template param-did
+#' @param deleted (bool) Whether to get only deleted entities (`TRUE`) or not
+#'   (`FALSE`). Default: `FALSE`.
 #' @template param-url
 #' @template param-auth
 #' @template param-retries
@@ -36,36 +35,37 @@
 #' # See vignette("setup") for setup and authentication options
 #' # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")
 #'
-#'  el <- entitylist_list()
+#' el <- entitylist_list()
 #'
-#'  # Entity List name (dataset ID)
-#'  did <- el$name[1]
+#' # Entity List name (dataset ID)
+#' did <- el$name[1]
 #'
-#'  # All Entities of Entity List
-#'  en <- entity_list(did = el$name[1])
+#' # All Entities of Entity List
+#' en <- entity_list(did = el$name[1])
 #'
-#'  # The UUID of the first Entity
-#'  eid <- en$uuid[1]
+#' # The UUID of the first Entity
+#' eid <- en$uuid[1]
 #'
-#'  # The current version of the first Entity
-#'  ev <- en$current_version_version[1]
+#' # The current version of the first Entity
+#' ev <- en$current_version_version[1]
 #' }
 entity_list <- function(pid = get_default_pid(),
-                            did = NULL,
-                            url = get_default_url(),
-                            un = get_default_un(),
-                            pw = get_default_pw(),
-                            retries = get_retries(),
-                            odkc_version = get_default_odkc_version(),
-                            orders = c(
-                              "YmdHMS",
-                              "YmdHMSz",
-                              "Ymd HMS",
-                              "Ymd HMSz",
-                              "Ymd",
-                              "ymd"
-                            ),
-                            tz = get_default_tz()) {
+                        did = NULL,
+                        deleted = FALSE,
+                        url = get_default_url(),
+                        un = get_default_un(),
+                        pw = get_default_pw(),
+                        retries = get_retries(),
+                        odkc_version = get_default_odkc_version(),
+                        orders = c(
+                          "YmdHMS",
+                          "YmdHMSz",
+                          "Ymd HMS",
+                          "Ymd HMSz",
+                          "Ymd",
+                          "ymd"
+                        ),
+                        tz = get_default_tz()) {
   yell_if_missing(url, un, pw, pid = pid)
 
   if (is.null(did)) {
@@ -80,6 +80,10 @@ entity_list <- function(pid = get_default_pid(),
     "v1/projects/{pid}/datasets/{URLencode(did, reserved = TRUE)}/entities"
   )
 
+  if (deleted == TRUE) {
+    pth <- glue::glue("{pth}?deleted=true")
+  }
+
   httr::RETRY(
     "GET",
     httr::modify_url(url, path = pth),
@@ -101,4 +105,4 @@ entity_list <- function(pid = get_default_pid(),
     )
 }
 
-# usethis::use_test("entity_list")  # nolint
+# usethis::use_test("entity_list")  # nolint
diff --git a/R/isodt_to_local.R b/R/isodt_to_local.R
@@ -22,9 +22,8 @@
 isodt_to_local <- function(datetime_string,
                            orders = c("YmdHMS", "YmdHMSz"),
                            tz = get_default_tz(),
-                           quiet=TRUE
-                           ) {
+                           quiet = TRUE) {
   datetime_string %>%
-    lubridate::parse_date_time(orders = orders, quiet=quiet) %>%
+    lubridate::parse_date_time(orders = orders, quiet = quiet) %>%
     lubridate::with_tz(., tzone = tz)
 }
diff --git a/man/entity_list.Rd b/man/entity_list.Rd
diff --git a/man/ruODK-package.Rd b/man/ruODK-package.Rd
diff --git a/tests/testthat/test-entity_detail.R b/tests/testthat/test-entity_detail.R
@@ -55,7 +55,7 @@ test_that("entitylist_detail errors if did is missing", {
 
 test_that("entitylist_detail warns if odkc_version too low", {
   skip_if(Sys.getenv("ODKC_TEST_URL") == "",
-          message = "Test server not configured"
+    message = "Test server not configured"
   )
 
   ru_setup(
@@ -77,4 +77,4 @@ test_that("entitylist_detail warns if odkc_version too low", {
 })
 
 
-# usethis::use_e("entity_detail")  # nolint
+# usethis::use_e("entity_detail")  # nolint
diff --git a/tests/testthat/test-entity_list.R b/tests/testthat/test-entity_list.R
@@ -1,6 +1,6 @@
 test_that("entity_list works", {
   skip_if(Sys.getenv("ODKC_TEST_URL") == "",
-          message = "Test server not configured"
+    message = "Test server not configured"
   )
 
   ru_setup(
@@ -18,7 +18,7 @@ test_that("entity_list works", {
 
   testthat::expect_s3_class(en, "tbl_df")
 
-  cn <-  c(
+  cn <- c(
     "uuid",
     "created_at",
     "creator_id",