Merge pull request #18 from ropensci/dev

`eia_data()` refactor: dynamic error handling, forced input format requirements, and additional unit testing

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: eia
 Title: API Wrapper for 'US Energy Information Administration' Open Data
-Version: 0.4.0
+Version: 0.4.1
 Authors@R: 
  c(person(
  given = "Matthew",

NEWS.md

@@ -1,8 +1,14 @@
 # eia 0.4.1
 
-* Added dynamic error handling to `eia_data()` via metadata layer conditioned on
-new function argument `check_metadata`.
-
+* Re-factor of `eia_data()`:
+ * Added dynamic error handling via metadata layer conditioned on new function argument `check_metadata`.
+ * Forced `start` and `end` input values to character.
+ * Forced `length` and `offset` input values to numeric.
+ * Augmented `sort` functionality to now handle multiple, varying "asc"/"desc" inputs 
+ to `order` as a list, rather than just one value of "asc" or "desc" applied to all
+ specified columns.
+ * Improved error messaging with `check_metadata = TRUE` to more closely resemble
+ those provided by the API (i.e. with `check_metadata = FALSE`).
 
 # eia 0.4.0
 

R/data.R

@@ -6,6 +6,14 @@
 #' input values for each of these arguments, use the specific ID labels
 #' as provided by `eia_metadata()`.
 #'
+#' The use of `start` and `end` require some input to `freq`.
+#' By default (`check_metadata = FALSE`), the resulting data will match the
+#' temporal resolution provided to `freq`, however, `check_metadata = TRUE` applies
+#' further restrictions such that the format of values provided to `start`/`end` must match
+#' that of `freq`. Furthermore, regardless of the input format provided to `start`/`end`,
+#' the resulting data will always match the specification of `freq`. And lastly,
+#' regardless of chosen format, `end` must be strictly greater than `start` to return data.
+#'
 #' By default, additional processing is done to return a list containing tibble data frames.
 #' Set `tidy = FALSE` to return only the initial list result of `jsonlite::fromJSON`.
 #' Set `tidy = NA` to return the original JSON as a character string.
@@ -20,8 +28,7 @@
 #' @param data character or `NULL`, see details.
 #' @param facets character list or `NULL`, see details.
 #' @param freq character or `NULL`, see details.
-#' @param start,end character, integer or `NULL`, must match format of default or supplied
-#' `freq`; e.g. if `freq = "yearly"`, then format must be `YYYY`.
+#' @param start,end character or `NULL`, see details.
 #' @param sort named list of two.
 #' * `cols`: list column names on which to sort.
 #' * `order`: `"asc"` or `"desc"` for ascending or descending, respectively.
@@ -71,7 +78,7 @@ eia_data <- function(dir,
  warning(wrngs, "\nTotal available rows: ", r$response$total, call. = FALSE)
  } else {
  if (r$response$total == 0)
- stop("No data available - check inputs.", call. = FALSE)
+ stop("No data available - check temporal inputs.", call. = FALSE)
  if (nrow(r$response$data) != r$response$total)
  warning("Rows returned: ", nrow(r$response$data), "\nRows available: ", r$response$total, call. = FALSE)
  }
@@ -153,6 +160,8 @@ eia_data <- function(dir,
 # Start input formatting and validation
 .start_specs <- function(start, freq){
  if(!is.null(start)){
+ if(!is.character(start))
+ stop("'start' must be a character string of length 1.", call. = FALSE)
  if(is.null(freq))
  stop("'start' requires 'freq' be non-NULL.", call. = FALSE)
  paste0("&start=", start)
@@ -161,11 +170,13 @@ eia_data <- function(dir,
 
 .start_check <- function(start, freq, md_frq_tbl, mds, mde){
  if(!is.null(start)){
+ if(!is.character(start))
+ stop("'start' must be a character string of length 1.", call. = FALSE)
  if (is.null(freq))
  stop("'start' requires 'freq' be non-NULL.", call. = FALSE)
  fmt <- md_frq_tbl[md_frq_tbl$id == freq, ]$format
  if (nchar(start) != nchar(fmt))
- stop("'start' must be a string of format: ", fmt, call. = FALSE)
+ stop("'start' must be a character string of format: ", fmt, call. = FALSE)
  if (start > mde)
  stop("'start' is beyond the end of available data.", call. = FALSE)
  if (start < mds)
@@ -176,6 +187,8 @@ eia_data <- function(dir,
 # End input formatting and validation
 .end_specs <- function(end, freq){
  if (!is.null(end)){
+ if(!is.character(end))
+ stop("'end' must be a character string of length 1.", call. = FALSE)
  if(is.null(freq))
  stop("'end' requires 'freq' be non-NULL.", call. = FALSE)
  paste0("&end=", end)
@@ -184,11 +197,13 @@ eia_data <- function(dir,
 
 .end_check <- function(end, freq, md_frq_tbl, mde, mds){
  if (!is.null(end)){
+ if(!is.character(end))
+ stop("'end' must be a character string of length 1.", call. = FALSE)
  if (is.null(freq))
  stop("'end' requires 'freq' be non-NULL.", call. = FALSE)
  fmt <- md_frq_tbl[md_frq_tbl$id == freq, ]$format
  if (nchar(end) != nchar(fmt))
- stop("'end' must be a string of format: ", fmt, call. = FALSE)
+ stop("'end' must be a character string of format: ", fmt, call. = FALSE)
  if (end < mds)
  stop("'end' is before the start of available data.", call. = FALSE)
  if (end > mde)
@@ -224,17 +239,17 @@ eia_data <- function(dir,
 # Length input formatting and validation
 .lng_specs <- function(length){
  if (!is.null(length)){
- if (length > 5000 | length < 0)
- stop("'length' must be a single value between 0 and 5000.", call. = FALSE)
+ if (!is.numeric(length) | length > 5000 | length < 0)
+ stop("'length' must be a numeric value between 0 and 5000.", call. = FALSE)
  paste0("&length=", length)
  }
 }
 
 # Offset input formatting and validation
 .ofs_specs <- function(offset){
  if (!is.null(offset)){
- if (offset < 0)
- stop("'offset' must be a single value greater than 0.", call. = FALSE)
+ if (!is.numeric(offset) | offset < 0)
+ stop("'offset' must be a numeric value greater than 0.", call. = FALSE)
  paste0("&offset=", offset)
  }
 }

codemeta.json

@@ -8,7 +8,7 @@
  "codeRepository": "https://github.com/ropensci/eia",
  "issueTracker": "https://github.com/ropensci/eia/issues",
  "license": "https://spdx.org/licenses/MIT",
- "version": "0.4.0",
+ "version": "0.4.1",
  "programmingLanguage": {
  "@type": "ComputerLanguage",
  "name": "R",
@@ -229,5 +229,5 @@
  },
  "SystemRequirements": null
  },
- "fileSize": "191.382KB"
+ "fileSize": "202.642KB"
 }

cran-comments.md

@@ -8,8 +8,7 @@
 
 ## Update release
 
-* This update includes a maintainer change/email address update.
-* Refactored package to work with newer version 2 of the US Energy Information Administration API.
+* Code updates and additional unit testing.
 
 ## R CMD check results
 

revdep/README.md

@@ -10,31 +10,30 @@
 |collate |English_United States.utf8 |
 |ctype |English_United States.utf8 |
 |tz |America/Denver |
-|date |2023-10-31 |
+|date |2023-11-17 |
 |rstudio |2023.06.1+524 Mountain Hydrangea (desktop) |
 |pandoc |3.1.1 @ C:/Program Files/RStudio/resources/app/bin/quarto/bin/tools/ (via rmarkdown) |
 
 # Dependencies
 
 |package |old |new |Δ |
 |:-----------|:-----|:-----|:--|
-|eia |0.3.7 |0.4.0 |* |
+|eia |0.4.0 |0.4.1 |* |
 |askpass |1.2.0 |1.2.0 | |
 |cachem |1.0.8 |1.0.8 | |
 |cellranger |1.1.0 |1.1.0 | |
 |cli |3.6.1 |3.6.1 | |
 |cpp11 |0.4.6 |0.4.6 | |
 |crayon |1.5.2 |1.5.2 | |
 |curl |5.1.0 |5.1.0 | |
-|dplyr |1.1.3 |NA |* |
 |fansi |1.0.5 |1.0.5 | |
 |fastmap |1.1.1 |1.1.1 | |
 |generics |0.1.3 |0.1.3 | |
 |glue |1.6.2 |1.6.2 | |
 |hms |1.1.3 |1.1.3 | |
 |httr |1.4.7 |1.4.7 | |
 |jsonlite |1.8.7 |1.8.7 | |
-|lifecycle |1.0.3 |1.0.3 | |
+|lifecycle |1.0.4 |1.0.4 | |
 |lubridate |1.9.3 |1.9.3 | |
 |magrittr |2.0.3 |2.0.3 | |
 |memoise |2.0.1 |2.0.1 | |
@@ -48,14 +47,12 @@
 |R6 |2.5.1 |2.5.1 | |
 |readxl |1.4.3 |1.4.3 | |
 |rematch |2.0.0 |2.0.0 | |
-|rlang |1.1.1 |1.1.1 | |
+|rlang |1.1.2 |1.1.2 | |
 |sys |3.4.2 |3.4.2 | |
 |tibble |3.2.1 |3.2.1 | |
-|tidyselect |1.2.0 |NA |* |
 |timechange |0.2.0 |0.2.0 | |
 |utf8 |1.2.4 |1.2.4 | |
 |vctrs |0.6.4 |0.6.4 | |
-|withr |2.5.2 |NA |* |
 
 # Revdeps