Soft deprecate req_url_path_*()

Since `req_url_relative()` is a more general interface. And improve `req_url()` docs, links, and examples.

Part of #625

NEWS.md

@@ -1,5 +1,6 @@
 # httr2 (development version)
 
+* `req_url_path()` and `req_url_path_append()` are (soft) deprecated in favour of `req_url_relative()`.
 * `curl_transform()` will now use `req_body_json_modify()` for JSON data (#258).
 * `resp_stream_is_complete()` tells you if there is still data remaining to be streamed (#559).
 * New `url_modify()`, `url_modify_query()`, and `url_modify_relative()` make it easier to modify an existing url (#464).

R/iterate-helpers.R

@@ -26,7 +26,7 @@
 #' @export
 #' @examples
 #' req <- request(example_url()) |>
-#'   req_url_path("/iris") |>
+#'   req_url_relative("/iris") |>
 #'   req_throttle(10) |>
 #'   req_url_query(limit = 50)
 #'

R/iterate-responses.R

@@ -18,8 +18,8 @@
 #'   returns the data found inside that response as a vector or data frame.
 #' @examples
 #' reqs <- list(
-#'   request(example_url()) |> req_url_path("/ip"),
-#'   request(example_url()) |> req_url_path("/user-agent"),
+#'   request(example_url()) |> req_url_relative("/ip"),
+#'   request(example_url()) |> req_url_relative("/user-agent"),
 #'   request(example_url()) |> req_template("/status/:status", status = 404),
 #'   request("INVALID")
 #' )
@@ -29,10 +29,14 @@
 #' resps |> resps_successes()
 #'
 #' # collect all their data
-#' resps |> resps_successes() |> resps_data(\(resp) resp_body_json(resp))
+#' resps |>
+#'   resps_successes() |>
+#'   resps_data(\(resp) resp_body_json(resp))
 #'
 #' # find requests corresponding to failure responses
-#' resps |> resps_failures() |> resps_requests()
+#' resps |>
+#'   resps_failures() |>
+#'   resps_requests()
 resps_successes <- function(resps) {
   resps[resps_ok(resps)]
 }

R/iterate.R

@@ -88,7 +88,7 @@
 #' @export
 #' @examples
 #' req <- request(example_url()) |>
-#'   req_url_path("/iris") |>
+#'   req_url_relative("/iris") |>
 #'   req_throttle(10) |>
 #'   req_url_query(limit = 5)
 #'

R/multi-req.R

@@ -26,18 +26,18 @@
 #' # Requesting these 4 pages one at a time would take 2 seconds:
 #' request_base <- request(example_url())
 #' reqs <- list(
-#'   request_base |> req_url_path("/delay/0.5"),
-#'   request_base |> req_url_path("/delay/0.5"),
-#'   request_base |> req_url_path("/delay/0.5"),
-#'   request_base |> req_url_path("/delay/0.5")
+#'   request_base |> req_url_relative("/delay/0.5"),
+#'   request_base |> req_url_relative("/delay/0.5"),
+#'   request_base |> req_url_relative("/delay/0.5"),
+#'   request_base |> req_url_relative("/delay/0.5")
 #' )
 #' # But it's much faster if you request in parallel
 #' system.time(resps <- req_perform_parallel(reqs))
 #'
 #' # req_perform_parallel() will fail on error
 #' reqs <- list(
-#'   request_base |> req_url_path("/status/200"),
-#'   request_base |> req_url_path("/status/400"),
+#'   request_base |> req_url_relative("/status/200"),
+#'   request_base |> req_url_relative("/status/400"),
 #'   request("FAILURE")
 #' )
 #' try(resps <- req_perform_parallel(reqs))
@@ -49,7 +49,9 @@
 #' resps |> resps_successes()
 #'
 #' # And the failed responses
-#' resps |> resps_failures() |> resps_requests()
+#' resps |>
+#'   resps_failures() |>
+#'   resps_requests()
 req_perform_parallel <- function(reqs,
                                  paths = NULL,
                                  pool = NULL,
@@ -125,9 +127,9 @@ pool_run <- function(pool, perfs, on_error = "continue") {
   # signal (not error) that wraps the error. Here we catch that error and
   # handle it based on the value of `on_error`
   httr2_fail <- switch(on_error,
-    stop =     function(cnd) cnd_signal(cnd$error),
+    stop = function(cnd) cnd_signal(cnd$error),
     continue = function(cnd) zap(),
-    return =   function(cnd) NULL
+    return = function(cnd) NULL
   )
 
   try_fetch(
@@ -149,13 +151,11 @@ Performance <- R6Class("Performance", public = list(
   req = NULL,
   req_prep = NULL,
   path = NULL,
-
   handle = NULL,
   resp = NULL,
   pool = NULL,
   error_call = NULL,
   progress = NULL,
-
   initialize = function(req, path = NULL, progress = NULL, error_call = NULL) {
     self$req <- req
     self$path <- path
@@ -172,7 +172,6 @@ Performance <- R6Class("Performance", public = list(
       curl::handle_setopt(self$handle, url = req$url)
     }
   },
-
   submit = function(pool = NULL) {
     if (!is.null(self$resp)) {
       # cached
@@ -189,7 +188,6 @@ Performance <- R6Class("Performance", public = list(
     )
     invisible(self)
   },
-
   succeed = function(res) {
     self$progress$update()
     req_completed(self$req_prep)
@@ -220,7 +218,6 @@ Performance <- R6Class("Performance", public = list(
       signal("", error = self$resp, class = "httr2_fail")
     }
   },
-
   fail = function(msg) {
     self$progress$update()
     req_completed(self$req_prep)
@@ -233,7 +230,6 @@ Performance <- R6Class("Performance", public = list(
     )
     signal("", error = self$resp, class = "httr2_fail")
   },
-
   cancel = function() {
     # No handle if response was cached
     if (!is.null(self$handle)) {

R/req-auth-aws.R

@@ -14,7 +14,7 @@
 #' model_id <- "anthropic.claude-3-5-sonnet-20240620-v1:0"
 #' req <- request("https://bedrock-runtime.us-east-1.amazonaws.com")
 #' # https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html
-#' req <- req_url_path_append(req, "model", model_id, "converse")
+#' req <- req_template(req, "model/:model_id/converse")
 #' req <- req_body_json(req, list(
 #'   messages = list(list(
 #'     role = "user",

R/req-body.R

@@ -16,7 +16,7 @@
 #' @returns A modified HTTP [request].
 #' @examples
 #' req <- request(example_url()) |>
-#'   req_url_path("/post")
+#'   req_url_relative("/post")
 #'
 #' # Most APIs expect small amounts of data in either form or json encoded:
 #' req |>

R/req-cookies.R

@@ -37,7 +37,7 @@
 #'
 #' # Add a client side cookie
 #' request(example_url()) |>
-#'   req_url_path("/cookies/set") |>
+#'   req_url_relative("/cookies/set") |>
 #'   req_cookie_preserve(path) |>
 #'   req_cookies_set(snicker = "doodle") |>
 #'   req_perform() |>

R/req-error.R

@@ -60,7 +60,7 @@
 #' # Performing this request usually generates an error because httr2
 #' # converts HTTP errors into R errors:
 #' req <- request(example_url()) |>
-#'   req_url_path("/status/404")
+#'   req_url_relative("/status/404")
 #' try(req |> req_perform())
 #' # You can still retrieve it with last_response()
 #' last_response()

R/req-perform-connection.R

@@ -23,7 +23,7 @@
 #' @export
 #' @examples
 #' req <- request(example_url()) |>
-#'   req_url_path("/stream-bytes/32768")
+#'   req_url_relative("/stream-bytes/32768")
 #' resp <- req_perform_connection(req)
 #'
 #' length(resp_stream_raw(resp, kb = 16))

R/req-perform-stream.R

@@ -29,7 +29,7 @@
 #'   TRUE
 #' }
 #' resp <- request(example_url()) |>
-#'   req_url_path("/stream-bytes/100000") |>
+#'   req_url_relative("/stream-bytes/100000") |>
 #'   req_perform_stream(show_bytes, buffer_kb = 32)
 #' resp
 req_perform_stream <- function(req,

R/req-promise.R

@@ -37,9 +37,11 @@
 #' @examples
 #' \dontrun{
 #' library(promises)
-#' request_base <- request(example_url()) |> req_url_path_append("delay")
+#' req <- request(example_url())
 #'
-#' p <- request_base |> req_url_path_append(2) |> req_perform_promise()
+#' p <- req |>
+#'   req_url_relative("delay/1") |>
+#'   req_perform_promise()
 #'
 #' # A promise object, not particularly useful on its own
 #' p
@@ -51,8 +53,12 @@
 #'
 #'
 #' # Can run two requests at the same time
-#' p1 <- request_base |> req_url_path_append(2) |> req_perform_promise()
-#' p2 <- request_base |> req_url_path_append(1) |> req_perform_promise()
+#' p1 <- req |>
+#'   req_url_relative("delay/1") |>
+#'   req_perform_promise()
+#' p2 <- req |>
+#'   req_url_relative("delay/1") |>
+#'   req_perform_promise()
 #'
 #' p1 %...>%
 #'   resp_url_path %...>%
@@ -97,19 +103,18 @@ req_perform_promise <- function(req,
   )
 }
 
-PerformancePromise <- R6Class("PerformancePromise", inherit = Performance,
+PerformancePromise <- R6Class("PerformancePromise",
+  inherit = Performance,
   public = list(
     resolve = NULL,
     reject = NULL,
-
     initialize = function(req, resolve, reject, path = NULL, error_call = NULL) {
       progress <- create_progress_bar(config = FALSE)
 
       super$initialize(req = req, path = path, progress = progress, error_call = error_call)
       self$resolve <- resolve
       self$reject <- reject
     },
-
     submit = function(pool = NULL) {
       if (!is.null(self$resp)) {
         # cached
@@ -119,7 +124,6 @@ PerformancePromise <- R6Class("PerformancePromise", inherit = Performance,
       super$submit(pool)
       ensure_pool_poller(pool, self$reject)
     },
-
     succeed = function(res) {
       tryCatch(
         {
@@ -130,19 +134,21 @@ PerformancePromise <- R6Class("PerformancePromise", inherit = Performance,
         error = function(cnd) self$reject(cnd)
       )
     },
-
     fail = function(msg) {
       tryCatch(
         super$fail(msg),
         httr2_fail = function(cnd) self$reject(cnd$error),
         error = function(cnd) self$reject(cnd)
       )
     }
-  ))
+  )
+)
 
 ensure_pool_poller <- function(pool, reject) {
   monitor <- pool_poller_monitor(pool)
-  if (monitor$already_going()) return()
+  if (monitor$already_going()) {
+    return()
+  }
 
   poll_pool <- function(ready) {
     tryCatch(
@@ -160,7 +166,8 @@ ensure_pool_poller <- function(pool, reject) {
         } else {
           monitor$ending()
         }
-      }, error = function(cnd) {
+      },
+      error = function(cnd) {
         monitor$ending()
         reject(cnd)
       }

R/req-template.R

@@ -29,7 +29,7 @@
 #' httpbin |> req_template("GET /bytes/{n}")
 #'
 #' # Existing path is preserved:
-#' httpbin_test <- request(example_url()) |> req_url_path("/test")
+#' httpbin_test <- request(example_url()) |> req_url_relative("/test")
 #' name <- "id"
 #' value <- "a3fWa"
 #' httpbin_test |> req_template("GET /set/{name}/{value}")
@@ -56,7 +56,7 @@ req_template <- function(req, template, ..., .env = parent.frame()) {
   }
 
   path <- template_process(template, dots, .env)
-  req_url_path_append(req, path)
+  req_url_relative(req, path)
 }
 
 template_process <- function(template,
@@ -99,7 +99,9 @@ template_val <- function(name, dots, env, error_call = caller_env()) {
 }
 
 template_vars <- function(x, type) {
-  if (type == "none") return(character())
+  if (type == "none") {
+    return(character())
+  }
 
   pattern <- switch(type,
     colon = ":([a-zA-Z0-9_]+)",

R/req-url-path.R

@@ -0,0 +1,54 @@
+#' Modify URL path
+#'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' * `req_url_path()` modifies the path.
+#' * `req_url_path_append()` adds to the path.
+#'
+#' Please use [req_url_relative()] instead.
+#'
+#' @inheritParams req_perform
+#' @param ... For `req_url_path()` and `req_url_path_append()`: A sequence of
+#'   path components that will be combined with `/`.
+#' @returns A modified HTTP [request].
+#' @export
+#' @examples
+#' req <- request("http://example.com/a/b/c")
+#'
+#' # OLD
+#' req |> req_url_path("/d/e/f")
+#' req |> req_url_path_append("d/e/f")
+#'
+#' # NEW
+#' req |> req_url_relative("/d/e/f")
+#' req |> req_url_relative("d/e/f")
+req_url_path <- function(req, ...) {
+  lifecycle::deprecate_soft("1.1.0", "req_url_path()", "req_url_relative()")
+
+  check_request(req)
+  path <- dots_to_path(...)
+
+  req_url(req, url_modify(req$url, path = path))
+}
+
+#' @export
+#' @rdname req_url_path
+req_url_path_append <- function(req, ...) {
+  lifecycle::deprecate_soft("1.1.0", "req_url_path_append()", "req_url_relative()")
+
+  check_request(req)
+  path <- dots_to_path(...)
+
+  url <- url_parse(req$url)
+  url$path <- paste0(sub("/$", "", url$path), path)
+
+  req_url(req, url_build(url))
+}
+
+dots_to_path <- function(...) {
+  path <- paste(c(...), collapse = "/")
+  # Ensure we don't add duplicate /s
+  # NB: also keeps "" unchanged.
+  sub("^([^/])", "/\\1", path)
+}