Merge branch 'main' into vignettes/workflow

.lintr

@@ -1,3 +1,4 @@
 linters: linters_with_defaults(
-    line_length_linter = line_length_linter(100L)
+    line_length_linter = line_length_linter(100L),
+    cyclocomp_linter = cyclocomp_linter(25L)
   )

DESCRIPTION

@@ -1,30 +1,34 @@
 Package: eesyapi
 Title: EES-y API
 Version: 0.3.0
-Authors@R: 
-    c(
+Authors@R: c(
     person("Rich", "Bielby", , "[email protected]", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0001-9070-9969")),
     person("Cam", "Race", , "[email protected]", role = "aut"),
-    person("Laura", "Selby", , "[email protected]", role = "ctb"))
-Description: An R package with useful utility functions for connecting to, and
-    processing data from, the DfE's explore education statistics API.
+    person("Laura", "Selby", , "[email protected]", role = "ctb")
+  )
+Description: An R package with useful utility functions for connecting to,
+    and processing data from, the DfE's explore education statistics API.
 License: MIT + file LICENSE
-Encoding: UTF-8
-Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.2
 URL: https://dfe-analytical-services.github.io/eesyapi
-Suggests: 
-    knitr,
-    rmarkdown,
-    testthat (>= 3.0.0)
-Config/testthat/edition: 3
+Depends: 
+    R (>= 3.5.0)
 Imports: 
+    data.table,
+    dplyr,
     httr,
     jsonlite,
-    dplyr,
-    stringr,
-    data.table,
     magrittr,
     rlang
+    rlang,
+    stringr
+Suggests: 
+    knitr,
+    rmarkdown,
+    readr,
+    testthat (>= 3.0.0)
 VignetteBuilder: knitr
+Config/testthat/edition: 3
+Encoding: UTF-8
+Roxygen: list(markdown = TRUE)
+RoxygenNote: 7.3.2

NAMESPACE

@@ -4,6 +4,7 @@ export(api_url)
 export(api_url_pages)
 export(api_url_query)
 export(convert_api_filter_type)
+export(download_dataset)
 export(example_data_raw)
 export(example_geography_query)
 export(example_id)

R/api_url.R

@@ -9,15 +9,15 @@
 #' \strong{Endpoints} \tab \strong{id required} \cr
 #' get-publications \tab Neither  \cr
 #' get-data-catalogue \tab publication_id  \cr
-#' get-summary, get-meta, get-data, post-data \tab dataset_id  \cr
+#' get-summary, get-meta, get-csv, get-data, post-data \tab dataset_id  \cr
 #' }
 #'
 #' @param endpoint Name of endpoint, can be "get-publications", "get-data-catalogue",
-#' "get-summary", "get-meta", "get-data" or "post-data"
+#' "get-summary", "get-meta", "get-csv", "get-data" or "post-data"
 #' @param publication_id ID of the publication to be connected to. This is required if the
 #' endpoint is "get-data-catalogue"
 #' @param dataset_id ID of data set to be connected to. This is required if the endpoint is one
-#' of "get-summary", "get-meta", "get-data" or "post-data"
+#' of "get-summary", "get-meta", "get-csv", "get-data" or "post-data"
 #' @inheritParams api_url_query
 #' @param dataset_version Version of data set to be connected to
 #' @param page_size Number of results to return in a single query
@@ -34,6 +34,7 @@
 #' api_url("get-data-catalogue", publication_id = eesyapi::example_id("publication"))
 #' api_url("get-summary", dataset_id = eesyapi::example_id("dataset"))
 #' api_url("get-meta", dataset_id = eesyapi::example_id("dataset"))
+#' api_url("get-csv", dataset_id = eesyapi::example_id("dataset"))
 #' api_url(
 #'   "get-data",
 #'   dataset_id = eesyapi::example_id("dataset"),
@@ -83,7 +84,7 @@ api_url <- function(
     endpoint %in% c(
       "get-publications", "get-data-catalogue",
       "get-summary", "get-meta",
-      "get-data", "post-data"
+      "get-csv", "get-data", "post-data"
     )
   }
 
@@ -92,7 +93,8 @@ api_url <- function(
       stop(
         paste(
           "You have entered an invalid endpoint, this should one of:",
-          "get-summary, get-meta, get-data or post-data"
+          "get-publications, get-data-catalogue, get-summary, get-meta,",
+          "get-csv, get-data or post-data"
         )
       )
     }
@@ -103,7 +105,7 @@ api_url <- function(
   }
 
   # Check that if endpoint requires a data set then dataset_id is not null
-  if (endpoint %in% c("get-summary", "get-meta", "get-data", "post-data")) {
+  if (endpoint %in% c("get-summary", "get-meta", "get-csv", "get-data", "post-data")) {
     eesyapi::validate_ees_id(dataset_id, level = "dataset")
     if (is_valid_dataset_info(dataset_id, dataset_version) == FALSE) {
       stop(
@@ -209,8 +211,18 @@ api_url <- function(
           )
         )
     }
+    if (endpoint == "get-csv") {
+      url <- paste0(
+        endpoint_base_version,
+        "data-sets/",
+        dataset_id,
+        "/csv"
+      )
+    }
   }
-  if (endpoint %in% c("get-publications", "get-data-catalogue", "get-summary", "get-meta")) {
+  if (endpoint %in% c(
+    "get-publications", "get-data-catalogue", "get-summary", "get-meta", "get-csv"
+  )) {
     if (
       any(!is.null(c(time_periods, geographic_levels, locations, filter_items, indicators)))
     ) {

R/download_dataset.R

@@ -0,0 +1,82 @@
+#' Download the raw CSV for an API data set
+#'
+#' This gives a super quick way to just fetch the whole file in a human
+#' readable format.
+#'
+#' @description
+#' This function is mostly designed for exploring the API, and is unlikely to
+#' be suitable for long term production use.
+#'
+#' There is no filtering down of the file so you will always get the whole file
+#' and in some instances this may be very large.
+#'
+#' As there are no IDs involved, this is brittle and code relying on this
+#' function will likely break whenever there is renaming of variables or items
+#' in the data.
+#'
+#' It is recommended to take the time to set up custom queries using the
+#' `query_dataset()` function instead. If you are using this function for more
+#' than exploratory purposes, make sure you subscribe to the data set you're
+#' downloading and then keep track of any updates to the data.
+#'
+#' @param dataset_id ID of data set
+#' @param dataset_version Version number of data set
+#' @param api_version EES API version
+#' @param verbose Run with additional contextual messaging, logical, default = FALSE
+#'
+#' @return data.frame
+#' @export
+#'
+#' @examples
+#' download_dataset(example_id("dataset"))
+download_dataset <- function(
+    dataset_id,
+    dataset_version = NULL,
+    api_version = NULL,
+    verbose = FALSE) {
+  # Validation ----------------------------------------------------------------
+  if (!is.null(dataset_version)) {
+    warning(
+      paste(
+        "Support for dataset_version is not yet available for downloading",
+        "full data sets. Returning latest available version of data set."
+      )
+    )
+  }
+
+  if (!is.logical(verbose)) {
+    stop("verbose must be a logical value, either TRUE or FALSE")
+  }
+
+  eesyapi::validate_ees_id(dataset_id, level = "dataset")
+
+  # Generate query ------------------------------------------------------------
+  query_url <- eesyapi::api_url(
+    endpoint = "get-csv",
+    dataset_id = dataset_id,
+    verbose = verbose
+  )
+
+  toggle_message("Requesting data...", verbose = verbose)
+
+  response <- httr::GET(query_url)
+
+  eesyapi::http_request_error(response, verbose = verbose)
+
+  toggle_message("Parsing response...", verbose = verbose)
+
+  # Parse into data.frame -----------------------------------------------------
+  output <- httr::content(
+    response,
+
+    # All EES CSVs should be UTF-8 and are validated on import
+    encoding = "UTF-8",
+
+    # httr uses read_csv() underneath, controlling read_csv() verbosity
+    show_col_types = verbose,
+    progress = verbose
+  ) |>
+    as.data.frame()
+
+  return(output)
+}

R/utils.R

@@ -0,0 +1,18 @@
+#' Controllable console messages
+#'
+#' Quick expansion to the `message()` function aimed for use in functions for
+#' an easy addition of a global verbose TRUE / FALSE argument to toggle the
+#' messages on or off
+#'
+#' @param ... any message you would normally pass into `message()`. See
+#' \code{\link{message}} for more details
+#'
+#' @param verbose logical, usually a variable passed from the function you are
+#' using this within
+#'
+#' @keywords internal
+toggle_message <- function(..., verbose) {
+  if (verbose) {
+    message(...)
+  }
+}

_pkgdown.yml

@@ -12,6 +12,7 @@ reference:
   - get_publications
   - get_data_catalogue
   - get_meta
+  - download_dataset
   - query_dataset
 
 - title: Support for generating API URLs and interpreting responses