Use TWIT_paginate_cursor in more places

NAMESPACE

@@ -7,12 +7,6 @@ S3method(next_cursor,default)
 S3method(next_cursor,list)
 S3method(next_cursor,numeric)
 S3method(next_cursor,response)
-S3method(previous_cursor,character)
-S3method(previous_cursor,data.frame)
-S3method(previous_cursor,default)
-S3method(previous_cursor,list)
-S3method(previous_cursor,numeric)
-S3method(previous_cursor,response)
 S3method(print,rtweet_bearer)
 S3method(print,rtweet_screen_name)
 S3method(round_time,Date)

NEWS.md

@@ -1,5 +1,12 @@
 # rtweet (development version)
 
+- `lookup_collections()` and `get_collections()` has been hard deprecated 
+  because the underlying Twitter API has been deprecated.
+
+- `previous_cursor()` has been hard deprecated. It could only be used with 
+  `lists_memberships()` and it has been dropped in favour of making regular
+  pagination better.
+
 - The `home` argument to `get_timeline()` has been deprecated. You can only
   retrieve the home timeline for the logged in user, and that's the job of
   `get_my_timeline()` (#550).

R/collections.R

@@ -1,108 +1,29 @@
-#' Get collections by user or status id.
-#'
-#' Return data for specified collection (themed grouping of Twitter statuses).
-#' Response data varies significantly compared to most other users and tweets
-#' data objects returned in this package.
-#'
-#' @param id required. The identifier of the Collection to return results for
-#'   e.g., "custom-539487832448843776"
-#' @param n Specifies the maximum number of results to include in
-#'   the response. Specify count between 1 and 200.
-#' @inheritParams lookup_users
-#' @param ... Other arguments passed along to composed request query.
-#' @return Return object converted to nested list if parsed otherwise
-#'   an HTTP response object is returned.
-#' @examples
-#'
-#' \dontrun{
-#'
-#' ## lookup a specific collection
-#' cc <- lookup_collections("custom-539487832448843776")
-#'
-#' ## inspect data
-#' str(cc)
-#'
-#' }
-#'
+#' Collections API 
+#' 
+#' @description 
+#' `r lifecycle::badge("deprecated")`
+#' 
+#' `get_collections()` and `lookup_collections()` have been deprecated
+#' since the underlying Twitter API has been deprecated:
+#' <https://developer.twitter.com/en/docs/twitter-for-websites/timelines/guides/collection>.
+#'
+#' @keywords internal
 #' @export
 lookup_collections <- function(id, n = 200,
                                parse = TRUE,
                                token = NULL,
                                ...) {
-  stopifnot(is.character(id), is_n(n))
-
-  params <- list(
-    id = id,
-    count = n,
-    ...
-  )
-  TWIT_get(token, "/1.1/collections/entries", params, parse = parse)
+  lifecycle::deprecate_stop("1.0.0", "lookup_collections()")
 }
 
-
-#' Get collections by user or status id.
-#'
-#' Find collections (themed grouping of statuses) created by specific user
-#' or status id. Results include user, status, and collection features.
-#'
-#' @param user Screen name or user id of target user. Requests must
-#'   provide a value for one of user or status_id.
-#' @param status_id Optional, the identifier of the tweet for which to
-#'   return results. Requests must provide a value for one of user or
-#'   status_id.
-#' @param n Maximum number of results to return. Defaults to 200.
-#' @param cursor Page identifier of results to retrieve. If parse = TRUE,
-#'   the next cursor value for any given request--if available--is stored
-#'   as an attribute, accessible via [next_cursor()]
-#' @inheritParams lookup_users
-#' @return Return object converted to nested list if parsed otherwise
-#'   an HTTP response object is returned.
-#' @examples
-#'
-#' \dontrun{
-#'
-#' ## lookup a specific collection
-#' cnnc <- get_collections("cnn")
-#'
-#' ## inspect data
-#' str(cnnc)
-#'
-#' ## by status id
-#' wwe <- get_collections(status_id = "925172982313570306")
-#'
-#' ## inspect data
-#' str(wwe)
-#'
-#' }
-#'
 #' @export
-get_collections <- function(user,
+#' @rdname lookup_collections
+get_collections <- function(user = NULL,
                             status_id = NULL,
                             n = 200,
                             cursor = NULL,
                             parse = TRUE,
                             token = NULL) {
-  stopifnot(is_n(n))
-
-  params <- list(
-    count = n,
-    cursor = cursor
-  )
-
-  if (missing(user) && !is.null(status_id) ||
-      is.null(user) && !is.null(status_id)) {
-    stopifnot(is.atomic(status_id))
-
-    params$tweet_id <- status_id
-  } else {
-    stopifnot(is.atomic(user))
-
-    params[[user_type(user)]] <- user
-  }
 
-  r <- TWIT_get(token, "/1.1/collections/list", params, parse = parse)
-  if (parse) {
-    attr(r, "next_cursor") <- r[["response"]][["cursors"]][["next_cursor"]]
-  }
-  r
+  lifecycle::deprecate_stop("1.0.0", "get_collections()")
 }

R/direct_messages.R

@@ -2,15 +2,13 @@
 #' past 30 days
 #'
 #' Returns all Direct Message events (both sent and received) within the last 30
-#' days. Sorted in reverse-chronological order.
+#' days. Sorted in reverse-chronological order. Includes detailed information 
+#' about the sender and recipient. 
 #'
-#' @param n optional Specifies the number of direct messages to try
-#'   and retrieve, up to a maximum of 50.
-#' @param next_cursor If there are more than 200 DMs in the last 30 days,
-#'   responses will include a next_cursor value, which can be supplied in
-#'   additional requests to scroll through pages of results.
+#' @inheritParams TWIT_paginate_cursor
 #' @inheritParams lookup_users
-#' @return Return parsed or non-parsed response object.
+#' @param next_cursor `r lifecycle::badge("deprecated")` Use `cursor` instead.
+#' @return A list with one element for each page of results.
 #' @examples
 #'
 #' \dontrun{
@@ -22,24 +20,30 @@
 #' str(dms)
 #'
 #' }
-#'
-#' @details Includes detailed information about the sender and
-#'   recipient user. You can request up to 50 direct messages per
-#'   call, and only direct messages from the last 30 days will be
-#'   available using this endpoint.
 #' @export
+#' @references <https://developer.twitter.com/en/docs/twitter-api/v1/direct-messages/sending-and-receiving/api-reference/list-events>
 direct_messages <- function(n = 50,
+                            cursor = NULL,
                             next_cursor = NULL,
                             parse = TRUE,
                             token = NULL) {
-  params <- list(
-    count = n, 
-    next_cursor = next_cursor
+
+  if (!is.null(next_cursor)) {
+    lifecycle::deprecate_warn("1.0.0", 
+      "direct_messages(next_cursor)", 
+      "direct_messages(cursor)"
+    )
+    cursor <- next_cursor
+  }
+
+  TWIT_paginate_cursor(token, "/1.1/direct_messages/events/list", list(), 
+    cursor = cursor,
+    n = n,
+    page_size = 50,
+    get_id = function(x) x$events$id
   )
-  TWIT_get(token, "/1.1/direct_messages/events/list", params, parse = parse)
 }
 
-
 #' (DEPRECATED) Get the most recent direct messages sent to the authenticating user.
 #'
 #' Retrieves up to 200 of the most recently received direct messages

R/favorites.R

@@ -69,7 +69,6 @@ get_favorites_user <- function(user,
   params[[user_type(user)]] <- user
 
   results <- TWIT_paginate_max_id(token, "/1.1/favorites/list", params,
-    get_max_id = function(x) x$id_str,
     page_size = 200,
     n = n,
     parse = parse

R/http.R

@@ -62,9 +62,11 @@ TWIT_method <- function(method, token, api,
 #' Pagination
 #' 
 #' @keywords internal
-#' @param get_max_id A single argument function that returns a vector of 
-#'   string ids. This is needed because different endpoints store that 
-#'   information in different places.
+#' @param n Maximum number of results to return.
+#' @param get_id A single argument function that returns a vector of ids given 
+#'   the JSON response. The defaults are chosen to cover the most common cases,
+#'   but you'll need to double check whenever implementing pagination for
+#'   a new endpoint.
 #' @param max_id String giving id of most recent tweet to return. 
 #'   Can be used for manual pagination.
 #' @param retryonratelimit If `TRUE`, and a rate limit is exhausted, will wait
@@ -79,7 +81,7 @@ TWIT_method <- function(method, token, api,
 #' @param verbose Show progress bars and other messages indicating current 
 #'   progress?
 TWIT_paginate_max_id <- function(token, api, params, 
-                                 get_max_id, 
+                                 get_id = function(x) x$id_str, 
                                  n = 1000, 
                                  page_size = 200, 
                                  parse = TRUE,
@@ -128,7 +130,7 @@ TWIT_paginate_max_id <- function(token, api, params,
       break
     }
 
-    max_id <- id_minus_one(last(get_max_id(json)))
+    max_id <- id_minus_one(last(get_id(json)))
     results[[i]] <- if (parse) json else resp
 
     if (verbose) {
@@ -148,6 +150,7 @@ TWIT_paginate_cursor <- function(token, api, params,
                                  n = 5000, 
                                  page_size = 5000, 
                                  cursor = "-1", 
+                                 get_id = function(x) x$ids,
                                  retryonratelimit = FALSE,
                                  verbose = TRUE) {
   params$count <- page_size
@@ -183,7 +186,7 @@ TWIT_paginate_cursor <- function(token, api, params,
 
     results[[i]] <- json
     cursor <- json$next_cursor_str
-    n_seen <- n_seen + length(json$ids)
+    n_seen <- n_seen + length(get_id(json))
     i <- i + 1
 
     if (identical(cursor, "0") || n_seen >= n) {

R/lists_members.R

@@ -6,17 +6,7 @@
 #'   have to specify the list owner using the owner_id or
 #'   owner_user parameters.
 #' @param owner_user optional The screen name or user ID of the user
-#'   who owns the list being requested by a slug.
-#' @param n Specifies the number of results to return
-#'   per page (see cursor below). For `list_memberships()`, the default and
-#'   max is 200 per page. Twitter technically allows up to 1,000 per page,
-#'   but above 200 frequently results in an over capacity error.
-#'   For `lists_members()`, the default, and max number
-#'   of users per list, is 5,000.
-#' @param cursor optional Breaks the results into pages. Provide a
-#'   value of -1 to begin paging. Provide values as returned in the
-#'   response body's next_cursor and previous_cursor attributes to
-#'   page back and forth in the list.
+#' @inheritParams TWIT_paginate_cursor
 #' @inheritParams lookup_users
 #' @param ... Other arguments used as parameters in query composition.
 #' @return Either a nested list (if parsed) or an HTTP response object.
@@ -38,8 +28,8 @@
 #' }
 #'
 #' @family lists
-#' @rdname lists_members
 #' @export
+#' @references <https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-members>
 lists_members <- function(list_id = NULL,
                           slug = NULL,
                           owner_user = NULL,
@@ -48,24 +38,20 @@ lists_members <- function(list_id = NULL,
                           token = NULL,
                           parse = TRUE,
                           ...) {
-  stopifnot(is.numeric(n))
-  if (n > 5000) {
-    warning("maximum number of list users it 5,000")
-    n <- 5000
-  }
-
   params <- lists_params(
     list_id = list_id,
     slug = slug,
-    owner_user = owner_user,
-    count = n,
-    cursor = cursor
+    owner_user = owner_user
+  )
+  r <- TWIT_paginate_cursor(token, "/1.1/lists/members", params,
+    n = n,
+    page_size = 5000,
+    cursor = cursor,
+    get_id = function(x) x$users$id_str
   )
-  r <- TWIT_get(token, "/1.1/lists/members", params, parse = parse)
 
   if (parse) {
-    r <- as_lists_members(r)
-    r <- as.data.frame(r)
+    r <- parse_lists_users(r)
   }
   r
 }