Merge pull request #217 from cmu-delphi/ds/api-keys

refactor+docs: set_api_key

Author: dshemetov

DESCRIPTION

@@ -3,7 +3,7 @@ Type: Package
 Title: Client for Delphi's 'Epidata' API
 Version: 1.1.0.9000
 Date: 2023-09-11
-Authors@R: 
+Authors@R:
   c(
     person("Logan", "Brooks", email = "lcbrooks@andrew.cmu.edu", role = c("aut")),
     person("Dmitry", "Shemetov", email = "dshemeto@andrew.cmu.edu", role = c("aut")),
@@ -37,6 +37,7 @@ Imports:
     openssl,
     readr,
     tibble,
+    usethis,
     xml2
 RoxygenNote: 7.2.3
 Suggests:
@@ -50,7 +51,7 @@ Suggests:
 VignetteBuilder: knitr
 Language: en-US
 Config/testthat/edition: 3
-Collate: 
+Collate:
     'auth.R'
     'avail_endpoints.R'
     'cache.R'

NAMESPACE

@@ -44,7 +44,7 @@ export(pvt_norostat)
 export(pvt_quidel)
 export(pvt_sensors)
 export(pvt_twitter)
-export(set_api_key)
+export(save_api_key)
 export(set_cache)
 import(cachem)
 import(glue)

NEWS.md

@@ -1,6 +1,7 @@
 # epidatr 1.1.0
+
 - renamed the mostly internal `get_auth_key` to `get_api_key`
-- added `set_api_key` to more easily set the option
+- added `save_api_key` to more easily set the option
 - various CRAN submission related doc-fixes
 - fixed some errors from passing "" as a key
 

R/auth.R

@@ -10,43 +10,28 @@
 #' please consider [registering for an API
 #' key](https://api.delphi.cmu.edu/epidata/admin/registration_form).
 #'
-#' API keys are strings and can be set in two ways. If the environment variable
-#' `DELPHI_EPIDATA_KEY` is set, it will be used automatically. Environment
-#' variables can be set either in the shell or by editing your `.Renviron` file,
-#' which will ensure the setting applies to all R sessions. See `?Startup` for a
-#' description of `Renviron` files and where they can be placed.
-#'
-#' Alternately, the API key can be set from within a session by using
-#' `set_api_key()`, which sets the R option `delphi.epidata.key` using
-#' `options()`. If this option is set, it is used in preference to the
-#' environment variable, so you may change keys within an R session. R options
-#' are not preserved between sessions, so `set_api_key()` must be run every time
-#' you open R. Alternately, you can have R set the option at startup by adding
-#' it to your `.Rprofile`; see `?Startup` for a description of `Rprofile` files
-#' and where they can be placed.
+#' API keys are strings read from the environment variable `DELPHI_EPIDATA_KEY`.
+#' We recommend setting your key with `save_api_key()`, which will modify an
+#' applicable `.Renviron` file, which will be read in automatically when you
+#' start future R sessions (see [`?Startup`][base::Startup] for details on
+#' `.Renviron` files). Alternatively, you can modify the environment variable at
+#' the command line before/while launching R, or inside an R session with
+#' [`Sys.setenv()`], but these will not persist across sessions.
 #'
 #' Once an API key is set, it is automatically used for all requests made by
 #' functions in this package.
 #'
 #' @return For `get_api_key()`, returns the current API key as a string, or
 #'   `""` if none is set.
 #'
-#' @seealso [usethis::edit_r_environ()] to automatically edit the `.Renviron`
-#'   file; [usethis::edit_r_profile()] to automatically edit the `.Rprofile`
-#'   file
-#'
-#' @references Delphi Epidata API Keys documentation.
-#'   <https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html>
+#' @references
+#' - [Delphi Epidata API Keys
+#'   documentation](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html).
+#' - [Delphi Epidata API Registration
+#'   Form](https://api.delphi.cmu.edu/epidata/admin/registration_form).
 #'
-#' Delphi Epidata API Registration Form.
-#' <https://api.delphi.cmu.edu/epidata/admin/registration_form>
 #' @export
 get_api_key <- function() {
-  key <- getOption("delphi.epidata.key", default = "")
-  if (key != "") {
-    return(key)
-  }
-
   key <- Sys.getenv("DELPHI_EPIDATA_KEY", unset = "")
   if (key != "") {
     return(key)
@@ -55,7 +40,7 @@ get_api_key <- function() {
   cli::cli_warn(
     c(
       "No API key found. You will be limited to non-complex queries and encounter rate limits if you proceed.",
-      "i" = "See {.help set_api_key} for details on obtaining and setting API keys."
+      "i" = "See {.help save_api_key} for details on obtaining and setting API keys."
     ),
     .frequency = "regularly",
     .frequency_id = "delphi.epidata.key"
@@ -64,8 +49,29 @@ get_api_key <- function() {
 }
 
 #' @rdname get_api_key
-#' @param key API key to use for future requests
 #' @export
-set_api_key <- function(key) {
-  options(delphi.epidata.key = key)
+save_api_key <- function() {
+  cli::cli_inform(
+    c(
+      "i" = "This function will open your {.code .Renviron} file in a text editor. You will need to
+      write {.code DELPHI_EPIDATA_KEY=yourkeyhere} (without quotes) in the file and save it. If the editor
+      does not open, you will need to edit the file manually.",
+      "i" = "Press enter to continue."
+    )
+  )
+  readline()
+
+  if (file.exists(usethis::proj_path(".Renviron"))) {
+    usethis::edit_r_environ(scope = "project")
+
+    cat("\n\n")
+    cli::cli_inform(
+      c(
+        "i" = "Your project {.code .Renviron} file has been updated. Make sure not to share this
+        file (add it to .gitignore or equivalents)."
+      )
+    )
+  } else {
+    usethis::edit_r_environ(scope = "user")
+  }
 }

README.Rmd

@@ -28,7 +28,7 @@ API](https://cmu-delphi.github.io/delphi-epidata/). It provides a simple R inter
 
 ## Usage
 
-You can find detailed docs here: 
+You can find detailed docs here:
 
 ```{r}
 library(epidatr)
@@ -86,7 +86,7 @@ your key, register for a pseudo-anonymous account
 [here](https://api.delphi.cmu.edu/epidata/admin/registration_form) and see more
 discussion on the [general API
 website](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html). See the
-`set_api_key()` function documentation for details on how to use your API key.
+`save_api_key()` function documentation for details on how to use your API key.
 
 Note that the private endpoints (i.e. those prefixed with `pvt_`) require a
 separate key that needs to be passed as an argument. These endpoints require

README.md

@@ -115,8 +115,8 @@ generate your key, register for a pseudo-anonymous account
 [here](https://api.delphi.cmu.edu/epidata/admin/registration_form) and
 see more discussion on the [general API
 website](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html).
-See the `set_api_key()` function documentation for details on how to use
-your API key.
+See the `save_api_key()` function documentation for details on how to
+use your API key.
 
 Note that the private endpoints (i.e. those prefixed with `pvt_`)
 require a separate key that needs to be passed as an argument. These

man/get_api_key.Rd

@@ -1,14 +1,5 @@
 test_that("get_api_key", {
   withr::with_envvar(c(DELPHI_EPIDATA_KEY = "epidata_key_from_envvar"), {
-    withr::with_options(list(delphi.epidata.key = "epidata_key_from_options"), {
-      # option takes precedence over environment variable
-      expect_identical(get_api_key(), "epidata_key_from_options")
-    })
-  })
-  withr::with_envvar(c(DELPHI_EPIDATA_KEY = NA_character_), {
-    withr::with_options(list(delphi.epidata.key = "epidata_key_from_options"), {
-      # option by itself works:
-      expect_identical(get_api_key(), "epidata_key_from_options")
-    })
+    expect_identical(get_api_key(), "epidata_key_from_envvar")
   })
 })

tests/testthat/test-auth.R

@@ -23,7 +23,7 @@ regions.
 We recommend you register for an API key. While most endpoints are available
 without one, there are [limits on API usage for anonymous
 users](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html), including
-a rate limit. See `set_api_key()` for details on how to obtain an API key and
+a rate limit. See `save_api_key()` for details on how to obtain an API key and
 set this package to use it.
 
 ## Basic Usage