graceful failure of API requests

DESCRIPTION

@@ -26,7 +26,8 @@ Imports:
     rlang (>= 0.4.11),
     stringr,
     tibble,
-    vctrs
+    vctrs,
+    webfakes
 Suggests: 
     covr,
     igraph,

NAMESPACE

@@ -62,6 +62,7 @@ export(get_xtools_page_info)
 export(get_xtools_page_links)
 export(get_xtools_page_prose)
 export(get_xtools_page_top_editors)
+export(gracefully)
 export(list_all_generators)
 export(list_all_list_modules)
 export(list_all_property_modules)

NEWS.md

@@ -1,5 +1,7 @@
 # wikkitidy (development version)
 
+* New `gracefully()` function added to allow graceful failure of http requests, as per CRAN policy. All API calls to Wikipedia query modules are now wrapped in `gracefully()` in the examples.
+
 # wikkitidy 0.1.12
 
 * `tidyr` moved from Imports to Suggests

R/generator-query-type.R

@@ -23,7 +23,7 @@
 #' @param ... <[`dynamic-dots`][rlang::dyn-dots]> Additional parameters to the
 #'   generator
 #'
-#' @return [query_generate_pages]: The modfied request, which can be passed to [next_batch] or
+#' @return [query_generate_pages]: The modified request, which can be passed to [next_batch] or
 #'   [retrieve_all] as appropriate.
 #'
 #'   [list_all_generators]: a [tibble][tibble::tbl_df] of all the available generator
@@ -34,11 +34,13 @@
 #'   pages' properties should be generated.
 #' @export
 #'
+#' @seealso [gracefully()]
+#'
 #' @examples
 #' # Search for articles about seagulls
 #' seagulls <- wiki_action_request() %>%
 #'   query_generate_pages("search", gsrsearch = "seagull") %>%
-#'   next_batch()
+#'   gracefully(next_batch)
 #'
 #' seagulls
 query_generate_pages <- function(.req, generator, ...) {

R/get-diff.R

@@ -37,10 +37,16 @@
 #'     "revisions",
 #'     rvlimit = 2, rvprop = "ids", rvdir = "older"
 #'   ) %>%
-#'   next_result() %>%
-#'   tidyr::unnest(cols = c(revisions)) %>%
-#'   dplyr::mutate(diffs = get_diff(from = parentid, to = revid))
-#' revisions
+#'   gracefully(next_result)
+#'
+#' if (tibble::is_tibble(revisions)) {
+#'   revisions <- revisions %>%
+#'     tidyr::unnest(cols = c(revisions)) %>%
+#'     dplyr::mutate(diffs = get_diff(from = parentid, to = revid))
+#'
+#'   print(revisions)
+#' }
+#'
 get_diff <- function(from, to, language = "en", simplify = TRUE) {
   if (!rlang::is_scalar_logical(simplify)) {
     rlang::abort("`simplify` must be either TRUE or FALSE")

R/get-query-results.R

@@ -34,15 +34,19 @@
 #' preview <- wiki_action_request() %>%
 #'   query_by_title("Steve Wozniak") %>%
 #'   query_page_properties("categories", cllimit = 40) %>%
-#'   next_result()
+#'   gracefully(next_result)
 #' preview
 #'
-#' all_results <- retrieve_all(preview)
+#' all_results <- preview %>%
+#'   gracefully(retrieve_all)
 #' all_results
 #'
 #' # tidyr is useful for list-columns.
-#' all_results %>%
-#'   tidyr::unnest(cols=c(categories), names_sep = "_")
+#' if (tibble::is_tibble(all_results)) {
+#'   all_results %>%
+#'     tidyr::unnest(cols=c(categories), names_sep = "_")
+#' }
+#'
 NULL
 
 #' @rdname get_query_results

R/list-query-type.R

@@ -24,14 +24,16 @@
 #' @return An HTTP response: an S3 list with class httr2_request
 #' @export
 #'
+#' @seealso [gracefully()]
+#'
 #' @examples
 #' # Get the ten most recently added pages in Category:Physics
 #' physics_pages <- wiki_action_request() %>%
 #'   query_list_pages("categorymembers",
 #'     cmsort = "timestamp",
 #'     cmdir = "desc", cmtitle = "Category:Physics"
 #'   ) %>%
-#'   next_batch()
+#'   gracefully(next_batch)
 #'
 #' physics_pages
 query_list_pages <- function(.req, list, ...) {

R/prop-query-type.R

@@ -22,12 +22,14 @@
 #' @return A request object of type `pages/query/action_api/httr2_request`. To
 #'   perform the query, pass the object to [next_batch] or [retrieve_all]
 #'
+#' @seealso [gracefully()]
+#'
 #' @examples
 #' # Retrieve the categories for Charles Harpur's Wikipedia page
 #'  resp <- wiki_action_request() %>%
 #'   query_by_title("Charles Harpur") %>%
 #'   query_page_properties("categories") %>%
-#'   next_batch()
+#'   gracefully(next_batch)
 NULL
 
 #' @rdname query_by_

R/query-category-members.R

@@ -46,10 +46,13 @@
 #'   be passed to [igraph::graph_from_data_frame] for network analysis.
 #' @export
 #'
+#' @seealso [gracefully()]
+#'
 #' @examples
 #' # Get the first 10 pages in 'Category:Physics' on English Wikipedia
 #' physics_members <- wiki_action_request() %>%
-#'   query_category_members("Physics") %>% next_batch()
+#'   query_category_members("Physics") %>%
+#'   gracefully(next_batch)
 #' physics_members
 #'
 #'

R/query-page-properties.R

@@ -20,14 +20,16 @@
 #' @return An HTTP response: an S3 list with class httr2_request
 #' @export
 #'
+#' @seealso [gracefully()]
+#'
 #' @examples
 #' # Search for articles about seagulls and retrieve their number of
 #' # watchers
 #'
 #' resp <- wiki_action_request() %>%
 #'   query_generate_pages("search", gsrsearch = "seagull") %>%
 #'   query_page_properties("info", inprop = "watchers") %>%
-#'   next_batch() %>%
+#'   gracefully(next_batch) %>%
 #'   dplyr::select(pageid, ns, title, watchers)
 #' resp
 query_page_properties <- function(.req, property, ...) {

R/request-gracefully.R

@@ -0,0 +1,45 @@
+#' Gracefully request a resource from Wikipedia
+#'
+#' The main purpose of this function is to enable examples using live resources
+#' in the documentation. Examples must not throw errors, according to CRAN
+#' policy. If you wrap a requesting method in `gracefully`, then any
+#' errors of type `httr2_http` will be caught and no error will be thrown.
+#'
+#'
+#' @param request_object A `httr2_request` object describing a query to a
+#'   Wikimedia Action API
+#' @param request_method The desired function for performing the request,
+#'   typically one of those in [get_query_results]
+#'
+#' @return The output of `request_method` called on `request_object`, if the
+#'   request was successful. Otherwise a `httr2_response` object with details
+#'   of the failed request.
+#' @export
+#'
+#' @examplesIf rlang::is_installed("webfakes")
+#' # This fails without throwing an error
+#' req <- httr2::request(httr2::example_url()) |>
+#'   httr2::req_url_path("/status/404")
+#'
+#' resp <- gracefully(req, httr2::req_perform)
+#'
+#' print(resp)
+#'
+#' # This request succeeds
+#' req <- httr2::request(httr2::example_url())
+#'
+#' resp <- gracefully(req, httr2::req_perform)
+#'
+#' print(resp)
+gracefully <- function(request_object, request_method) {
+  tryCatch(
+    request_method(request_object),
+    httr2_http = function(cnd) show_bad_response(cnd)
+  )
+}
+
+show_bad_response <- function(cnd) {
+  cli::cli_alert("The query you tried was unsuccessful. See the response below.")
+  print(cnd$resp)
+  return(cnd$resp)
+}

R/wiki-action-request.R

@@ -10,7 +10,7 @@
 #'
 #' [wikkitidy] provides an ergonomic API for the Action API's [Query
 #' modules](https://www.mediawiki.org/wiki/API:Query). These modules are most
-#' useful for researchers, because they allow you to explore the stucture of
+#' useful for researchers, because they allow you to explore the structure of
 #' Wikipedia and its back pages. You can obtain a list of available modules in
 #' your R console using [list_all_property_modules()], [list_all_list_modules()]
 #' and [list_all_generators()],
@@ -41,6 +41,8 @@
 #'   combined with a [query_by_] query.
 #' @export
 #'
+#' @seealso [gracefully()]
+#'
 #' @examples
 #' # List the first 10 pages in the category 'Australian historians'
 #' historians <- wiki_action_request() %>%
@@ -49,7 +51,7 @@
 #'     cmtitle = "Category:Australian_historians",
 #'     cmlimit = 10
 #'   ) %>%
-#'   next_batch()
+#'   gracefully(next_batch)
 #' historians
 wiki_action_request <- function(..., action = "query", language = "en") {
   base_url <- glue::glue("https://{language}.wikipedia.org/w/api.php")