From 222080c3570b610e686a68b0a9df8a02e97542cf Mon Sep 17 00:00:00 2001 From: chainsawriot Date: Wed, 13 Mar 2024 14:08:00 +0100 Subject: [PATCH] Update docs ref #154 --- DESCRIPTION | 4 ++-- NEWS.md | 4 ++++ R/accounts.R | 14 ++++++++++++-- R/timelines_statuses.R | 12 +++++++++--- man/get_account_blocks.Rd | 4 ++-- man/get_account_bookmarks.Rd | 4 ++-- man/get_account_favourites.Rd | 2 +- man/get_account_followers.Rd | 4 ++-- man/get_account_following.Rd | 4 ++-- man/get_account_mutes.Rd | 4 ++-- man/get_account_statuses.Rd | 6 +++--- man/get_timeline_hashtag.Rd | 12 +++++++++--- man/get_timeline_home.Rd | 9 ++++++--- man/get_timeline_public.Rd | 9 ++++++--- man/rtoot-package.Rd | 2 +- 15 files changed, 63 insertions(+), 31 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index c92c91e..07151ad 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: rtoot Title: Collecting and Analyzing Mastodon Data -Version: 0.3.4 +Version: 0.3.4.9000 Authors@R: c(person("David", "Schoch", , "david@schochastics.net", role = c("aut", "cre"), comment = c(ORCID = "0000-0003-2952-4812")), person("Chung-hong", "Chan", ,"chainsawtiney@gmail.com", role = c("aut"), comment = c(ORCID = "0000-0002-6232-7530")), @@ -12,7 +12,7 @@ URL: https://gesistsa.github.io/rtoot/, https://github.com/gesistsa/rtoot/ BugReports: https://github.com/gesistsa/rtoot/issues Encoding: UTF-8 Roxygen: list(markdown = TRUE) -RoxygenNote: 7.2.3 +RoxygenNote: 7.3.1 Depends: R (>= 3.6) Imports: diff --git a/NEWS.md b/NEWS.md index cd9451d..60d79d4 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,7 @@ +# rtoot 0.3.4.9000 + +* fixed #153 by allowing POSIXct as `max_id`, `min_id` and `since_id` (#154) by @Kudusch + # rtoot 0.3.4 * added progress bar for long running queries (#141) by @chainsawriot diff --git a/R/accounts.R b/R/accounts.R index f1765c1..28d8a5b 100644 --- a/R/accounts.R +++ b/R/accounts.R @@ -44,6 +44,8 @@ search_accounts <- function(query, limit = 40, token = NULL, anonymous = FALSE, #' @inheritParams get_status #' @inheritParams post_toot #' @inheritParams get_timeline_home +#' @inheritParams get_timeline_public +#' @inherit get_timeline_public details #' @param exclude_reblogs logical, Whether to filter out boosts from the response. #' @param hashtag character, filter for statuses using a specific hashtag. #' @param retryonratelimit If TRUE, and a rate limit is exhausted, will wait until it refreshes. Most Mastodon rate limits refresh every 5 minutes. If FALSE, and the rate limit is exceeded, the function will terminate early with a warning; you'll still get back all results received up to that point. @@ -78,8 +80,8 @@ get_account_statuses <- function(id, max_id, since_id, min_id, limit = 20L, #' Get followers of a user #' @inheritParams get_account_statuses -#' @param max_id character, Return results older than this id -#' @param since_id character, Return results newer than this id +#' @inheritParams get_timeline_public +#' @inherit get_timeline_public details #' @param limit integer, maximum number of results to return. Defaults to 40. #' @param retryonratelimit If TRUE, and a rate limit is exhausted, will wait until it refreshes. Most Mastodon rate limits refresh every 5 minutes. If FALSE, and the rate limit is exceeded, the function will terminate early with a warning; you'll still get back all results received up to that point. #' @inheritParams auth_setup @@ -109,6 +111,8 @@ get_account_followers <- function(id, max_id, since_id, #' @inheritParams get_account_statuses #' @inheritParams get_account_followers #' @inheritParams auth_setup +#' @inheritParams get_timeline_public +#' @inherit get_timeline_public details #' @inherit get_account_followers details #' @return tibble or list of accounts a user follows #' @examples @@ -212,6 +216,8 @@ get_account_bookmarks <- function(max_id, since_id, min_id, limit = 40L, #' @inheritParams get_account_statuses #' @inheritParams get_account_followers #' @inheritParams auth_setup +#' @inheritParams get_timeline_public +#' @inherit get_timeline_public details #' @param min_id character, Return results younger than this id #' @inherit get_account_followers details #' @return tibble or list of favourited statuses @@ -238,6 +244,8 @@ get_account_favourites <- function(max_id, min_id, limit = 40L, #' @inheritParams get_account_statuses #' @inheritParams get_account_followers #' @inheritParams auth_setup +#' @inheritParams get_timeline_public +#' @inherit get_timeline_public details #' @inherit get_account_followers details #' @return tibble or list of blocked users #' @examples @@ -263,6 +271,8 @@ get_account_blocks <- function(max_id, since_id, limit = 40L, #' @inheritParams get_account_statuses #' @inheritParams get_account_followers #' @inheritParams auth_setup +#' @inheritParams get_timeline_public +#' @inherit get_timeline_public details #' @inherit get_account_followers details #' @return tibble or list of muted users #' @examples diff --git a/R/timelines_statuses.R b/R/timelines_statuses.R index f4ae341..52d17fe 100644 --- a/R/timelines_statuses.R +++ b/R/timelines_statuses.R @@ -83,14 +83,15 @@ get_poll <- function(id, instance = NULL, token = NULL, anonymous = FALSE, parse #' @param local logical, Show only local statuses? #' @param remote logical, Show only remote statuses? #' @param only_media logical, Show only statuses with media attached? -#' @param max_id character, Return results older than this id -#' @param since_id character, Return results newer than this id -#' @param min_id character, Return results immediately newer than this id +#' @param max_id character or `POSIXct` (date time), Return results older than this id +#' @param since_id character or `POSIXct` (date time), Return results newer than this id +#' @param min_id character or `POSIXct` (date time), Return results immediately newer than this id #' @param limit integer, Maximum number of results to return #' @param retryonratelimit If TRUE, and a rate limit is exhausted, will wait until it refreshes. Most Mastodon rate limits refresh every 5 minutes. If FALSE, and the rate limit is exceeded, the function will terminate early with a warning; you'll still get back all results received up to that point. #' @param verbose logical whether to display messages #' @inheritParams post_toot #' @inheritParams get_status +#' @details `max_id`, `since_id`, and `min_id` can either be character or `POSIXct` (date time). If it is `POSXIct`, it will be converted to the so-called snowflake ID. #' @return statuses #' @export #' @examples @@ -126,12 +127,16 @@ get_timeline_public <- function(local = FALSE, remote = FALSE, only_media = FALS #' Query the instance for the timeline of a specific hashtag #' @param hashtag character, Content of a #hashtag. The hash is optional #' @inherit get_timeline_public +#' @inherit get_timeline_public details #' @export #' @examples #' \dontrun{ #' get_timeline_hashtag(hashtag = "#ichbinhanna") #' ## anonymously #' get_timeline_hashtag(hashtag = "ichbinhanna", instance = "mastodon.social", anonymous = TRUE) +#' ## Search for toots by date +#' get_timeline_hashtag(hashtag = "ichbinhanna", instance = "mastodon.social", anonymous = TRUE, +#' max_id = as.POSIXct("2024-03-01")) #' } get_timeline_hashtag <- function(hashtag = "rstats", local = FALSE, only_media = FALSE, max_id, since_id, min_id, limit = 20L, instance = NULL, @@ -152,6 +157,7 @@ get_timeline_hashtag <- function(hashtag = "rstats", local = FALSE, only_media = #' Query the instance for the timeline from either followed users or a specific list. These functions can only be called with a user token from [create_token()]. #' @param list_id character, Local ID of the list in the database. #' @inherit get_timeline_public +#' @inherit get_timeline_public details #' @export #' @examples #' \dontrun{ diff --git a/man/get_account_blocks.Rd b/man/get_account_blocks.Rd index 1d9497d..86adf84 100644 --- a/man/get_account_blocks.Rd +++ b/man/get_account_blocks.Rd @@ -15,9 +15,9 @@ get_account_blocks( ) } \arguments{ -\item{max_id}{character, Return results older than this id} +\item{max_id}{character or \code{POSIXct} (date time), Return results older than this id} -\item{since_id}{character, Return results newer than this id} +\item{since_id}{character or \code{POSIXct} (date time), Return results newer than this id} \item{limit}{integer, Maximum number of results to return} diff --git a/man/get_account_bookmarks.Rd b/man/get_account_bookmarks.Rd index a144dcd..935be54 100644 --- a/man/get_account_bookmarks.Rd +++ b/man/get_account_bookmarks.Rd @@ -16,9 +16,9 @@ get_account_bookmarks( ) } \arguments{ -\item{max_id}{character, Return results older than this id} +\item{max_id}{character or \code{POSIXct} (date time), Return results older than this id} -\item{since_id}{character, Return results newer than this id} +\item{since_id}{character or \code{POSIXct} (date time), Return results newer than this id} \item{min_id}{character, Return results younger than this id} diff --git a/man/get_account_favourites.Rd b/man/get_account_favourites.Rd index 8c63c6f..515f5ef 100644 --- a/man/get_account_favourites.Rd +++ b/man/get_account_favourites.Rd @@ -15,7 +15,7 @@ get_account_favourites( ) } \arguments{ -\item{max_id}{character, Return results older than this id} +\item{max_id}{character or \code{POSIXct} (date time), Return results older than this id} \item{min_id}{character, Return results younger than this id} diff --git a/man/get_account_followers.Rd b/man/get_account_followers.Rd index cd0c665..727974d 100644 --- a/man/get_account_followers.Rd +++ b/man/get_account_followers.Rd @@ -18,9 +18,9 @@ get_account_followers( \arguments{ \item{id}{character, local ID of a user (this is not the username)} -\item{max_id}{character, Return results older than this id} +\item{max_id}{character or \code{POSIXct} (date time), Return results older than this id} -\item{since_id}{character, Return results newer than this id} +\item{since_id}{character or \code{POSIXct} (date time), Return results newer than this id} \item{limit}{integer, maximum number of results to return. Defaults to 40.} diff --git a/man/get_account_following.Rd b/man/get_account_following.Rd index 46b96d2..8eb31a2 100644 --- a/man/get_account_following.Rd +++ b/man/get_account_following.Rd @@ -18,9 +18,9 @@ get_account_following( \arguments{ \item{id}{character, local ID of a user (this is not the username)} -\item{max_id}{character, Return results older than this id} +\item{max_id}{character or \code{POSIXct} (date time), Return results older than this id} -\item{since_id}{character, Return results newer than this id} +\item{since_id}{character or \code{POSIXct} (date time), Return results newer than this id} \item{limit}{integer, Maximum number of results to return} diff --git a/man/get_account_mutes.Rd b/man/get_account_mutes.Rd index 00813d1..5ce0877 100644 --- a/man/get_account_mutes.Rd +++ b/man/get_account_mutes.Rd @@ -15,9 +15,9 @@ get_account_mutes( ) } \arguments{ -\item{max_id}{character, Return results older than this id} +\item{max_id}{character or \code{POSIXct} (date time), Return results older than this id} -\item{since_id}{character, Return results newer than this id} +\item{since_id}{character or \code{POSIXct} (date time), Return results newer than this id} \item{limit}{integer, Maximum number of results to return} diff --git a/man/get_account_statuses.Rd b/man/get_account_statuses.Rd index e7726ee..2913fbe 100644 --- a/man/get_account_statuses.Rd +++ b/man/get_account_statuses.Rd @@ -23,11 +23,11 @@ get_account_statuses( \arguments{ \item{id}{character, local ID of a user (this is not the username)} -\item{max_id}{character, Return results older than this id} +\item{max_id}{character or \code{POSIXct} (date time), Return results older than this id} -\item{since_id}{character, Return results newer than this id} +\item{since_id}{character or \code{POSIXct} (date time), Return results newer than this id} -\item{min_id}{character, Return results immediately newer than this id} +\item{min_id}{character or \code{POSIXct} (date time), Return results immediately newer than this id} \item{limit}{integer, Maximum number of results to return} diff --git a/man/get_timeline_hashtag.Rd b/man/get_timeline_hashtag.Rd index 7348fff..38b21d9 100644 --- a/man/get_timeline_hashtag.Rd +++ b/man/get_timeline_hashtag.Rd @@ -27,11 +27,11 @@ get_timeline_hashtag( \item{only_media}{logical, Show only statuses with media attached?} -\item{max_id}{character, Return results older than this id} +\item{max_id}{character or \code{POSIXct} (date time), Return results older than this id} -\item{since_id}{character, Return results newer than this id} +\item{since_id}{character or \code{POSIXct} (date time), Return results newer than this id} -\item{min_id}{character, Return results immediately newer than this id} +\item{min_id}{character or \code{POSIXct} (date time), Return results immediately newer than this id} \item{limit}{integer, Maximum number of results to return} @@ -53,11 +53,17 @@ statuses \description{ Query the instance for the timeline of a specific hashtag } +\details{ +\code{max_id}, \code{since_id}, and \code{min_id} can either be character or \code{POSIXct} (date time). If it is \code{POSXIct}, it will be converted to the so-called snowflake ID. +} \examples{ \dontrun{ get_timeline_hashtag(hashtag = "#ichbinhanna") ## anonymously get_timeline_hashtag(hashtag = "ichbinhanna", instance = "mastodon.social", anonymous = TRUE) +## Search for toots by date +get_timeline_hashtag(hashtag = "ichbinhanna", instance = "mastodon.social", anonymous = TRUE, +max_id = as.POSIXct("2024-03-01")) } } \references{ diff --git a/man/get_timeline_home.Rd b/man/get_timeline_home.Rd index ce26011..a2848f0 100644 --- a/man/get_timeline_home.Rd +++ b/man/get_timeline_home.Rd @@ -32,11 +32,11 @@ get_timeline_list( \arguments{ \item{local}{logical, Show only local statuses?} -\item{max_id}{character, Return results older than this id} +\item{max_id}{character or \code{POSIXct} (date time), Return results older than this id} -\item{since_id}{character, Return results newer than this id} +\item{since_id}{character or \code{POSIXct} (date time), Return results newer than this id} -\item{min_id}{character, Return results immediately newer than this id} +\item{min_id}{character or \code{POSIXct} (date time), Return results immediately newer than this id} \item{limit}{integer, Maximum number of results to return} @@ -56,6 +56,9 @@ statuses \description{ Query the instance for the timeline from either followed users or a specific list. These functions can only be called with a user token from \code{\link[=create_token]{create_token()}}. } +\details{ +\code{max_id}, \code{since_id}, and \code{min_id} can either be character or \code{POSIXct} (date time). If it is \code{POSXIct}, it will be converted to the so-called snowflake ID. +} \examples{ \dontrun{ get_timeline_home() diff --git a/man/get_timeline_public.Rd b/man/get_timeline_public.Rd index 8eb9d7e..44fa875 100644 --- a/man/get_timeline_public.Rd +++ b/man/get_timeline_public.Rd @@ -27,11 +27,11 @@ get_timeline_public( \item{only_media}{logical, Show only statuses with media attached?} -\item{max_id}{character, Return results older than this id} +\item{max_id}{character or \code{POSIXct} (date time), Return results older than this id} -\item{since_id}{character, Return results newer than this id} +\item{since_id}{character or \code{POSIXct} (date time), Return results newer than this id} -\item{min_id}{character, Return results immediately newer than this id} +\item{min_id}{character or \code{POSIXct} (date time), Return results immediately newer than this id} \item{limit}{integer, Maximum number of results to return} @@ -53,6 +53,9 @@ statuses \description{ Query the instance for the public timeline } +\details{ +\code{max_id}, \code{since_id}, and \code{min_id} can either be character or \code{POSIXct} (date time). If it is \code{POSXIct}, it will be converted to the so-called snowflake ID. +} \examples{ \dontrun{ ## as tibble diff --git a/man/rtoot-package.Rd b/man/rtoot-package.Rd index 64db6fd..e1aa997 100644 --- a/man/rtoot-package.Rd +++ b/man/rtoot-package.Rd @@ -3,7 +3,6 @@ \docType{package} \name{rtoot-package} \alias{rtoot-package} -\alias{_PACKAGE} \title{rtoot: Collect Mastodon data from R} \description{ rtoots provides a range of functions to interact with the Mastodon API. @@ -40,6 +39,7 @@ Authors: Other contributors: \itemize{ \item Johannes Gruber \email{JohannesB.Gruber@gmail.com} (\href{https://orcid.org/0000-0001-9177-1772}{ORCID}) [contributor] + \item Tim Schatto-Eckrodt \email{kudusch@posteo.de} (\href{https://orcid.org/0000-0003-1658-4373}{ORCID}) [contributor] } }