Module: X::Objects::Lookups::Posts

Included in:

API

Defined in:

x-objects/lib/x/objects/lookups/posts.rb

Overview

Look up, search, and count posts, and report how many posts the app has read, mixed into a client through API

Internal to x-objects: X::Objects::API includes it, and its methods are public API of the client that includes API, but the module is only how they are grouped, and some of them need the methods of another, so include API rather than this module alone.

Instance Method Summary

• #count_all_posts(query, **params) ⇒ Integer (also: #count_all_tweets)

  Count the posts from the full archive that match a query, without reading them.

• #count_all_posts_by_period(query, **params) ⇒ Hash{Range<Time> => Integer} (also: #count_all_tweets_by_period)

  Count the posts from the full archive that match a query, by period.

• #count_posts(query, **params) ⇒ Integer (also: #count_tweets)

  Count the recent posts that match a query, without reading them.

• #count_posts_by_period(query, **params) ⇒ Hash{Range<Time> => Integer} (also: #count_tweets_by_period)

  Count the posts from the last seven days that match a query, by period.

• #find_all_posts(ids, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Post> (also: #find_all_tweets)

  Look up many posts by identifier, in parallel batches.

• #find_post(id, **params) {|problem| ... } ⇒ Post^? (also: #find_tweet)

  Look up a post by identifier.

• #find_post!(id, **params) ⇒ Post (also: #find_tweet!)

  Look up a post by identifier, which must exist.

• #post_usage(**params) {|problem| ... } ⇒ PostUsage^?

  Look up how many posts the app's project has read.

• #post_usage!(**params) ⇒ PostUsage

  Look up how many posts the app's project has read, which must be returned.

• #reposts_of_me(**params) ⇒ Cursor (also: #retweets_of_me)

  The posts of the authenticated user that other users have reposted.

• #search_all_posts(query, **params) ⇒ Cursor (also: #search_all_tweets)

  Search the full archive of posts.

• #search_posts(query, **params) ⇒ Cursor (also: #search_tweets)

  Search recent posts.

Instance Method Details

#count_all_posts(query, **params) ⇒ Integer Also known as: count_all_tweets

Count the posts from the full archive that match a query, without reading them

The API bills a count by the request, not by the post, and refuses OAuth 1.0a for it, so a client that signs with OAuth 1.0a counts with a copy that authenticates as the app. A client signed in with OAuth 2.0 as a user that holds no credentials of the app counts as the user, which the full archive refuses with X::Forbidden.

Examples:

Count every post about Ruby from 2024

client.count_all_posts("ruby", start_time: "2024-01-01T00:00:00Z", end_time: "2025-01-01T00:00:00Z")

Parameters:

• query (String) —

  the search query

• params (Hash) —

  query parameters, such as start_time and end_time, and the max_pages of X::Post.count_all, which limits the pages of counts requested

Returns:

• (Integer) —

  the number of matching posts

# File 'x-objects/lib/x/objects/lookups/posts.rb', line 123

def count_all_posts(query, **params) = Post.count_all(query, client: self, **params) # steep:ignore DifferentMethodParameterKind

#count_all_posts_by_period(query, **params) ⇒ Hash{Range<Time> => Integer} Also known as: count_all_tweets_by_period

Count the posts from the full archive that match a query, by period

The API bills a count by the request, not by the post, and refuses OAuth 1.0a for it, so a client that signs with OAuth 1.0a counts with a copy that authenticates as the app. A client signed in with OAuth 2.0 as a user that holds no credentials of the app counts as the user, which the full archive refuses with X::Forbidden.

Examples:

Count the posts about Ruby by day in 2024

client.count_all_posts_by_period("ruby", start_time: "2024-01-01T00:00:00Z", end_time: "2025-01-01T00:00:00Z")

Parameters:

• query (String) —

  the search query

• params (Hash) —

  query parameters, such as granularity, which is day by default, and the max_pages of X::Post.count_all_by_period, which limits the pages of counts requested

Returns:

• (Hash{Range<Time> => Integer}) —

  the number of matching posts, keyed by the time each period spans, from its start up to, but not including, its end, oldest first

# File 'x-objects/lib/x/objects/lookups/posts.rb', line 154

def count_all_posts_by_period(query, **params) = Post.count_all_by_period(query, client: self, **params) # steep:ignore DifferentMethodParameterKind

#count_posts(query, **params) ⇒ Integer Also known as: count_tweets

Count the recent posts that match a query, without reading them

The API bills a count by the request, not by the post, and refuses OAuth 1.0a for it, so a client that signs with OAuth 1.0a counts with a copy that authenticates as the app.

Examples:

Count the recent posts about Ruby with an app-only client

client.count_posts("ruby")

Parameters:

• query (String) —

  the search query

• params (Hash) —

  query parameters, such as start_time and end_time, and max_pages, the most pages of counts to request

Returns:

• (Integer) —

  the number of matching posts

# File 'x-objects/lib/x/objects/lookups/posts.rb', line 108

def count_posts(query, **params) = Post.count(query, client: self, **params) # steep:ignore DifferentMethodParameterKind

#count_posts_by_period(query, **params) ⇒ Hash{Range<Time> => Integer} Also known as: count_tweets_by_period

Count the posts from the last seven days that match a query, by period

The API bills a count by the request, not by the post, and refuses OAuth 1.0a for it, so a client that signs with OAuth 1.0a counts with a copy that authenticates as the app.

Examples:

Count the recent posts about Ruby by hour

client.count_posts_by_period("ruby", granularity: "hour")

Parameters:

• query (String) —

  the search query

• params (Hash) —

  query parameters, such as granularity, which is day by default, and max_pages, the most pages of counts to request

Returns:

• (Hash{Range<Time> => Integer}) —

  the number of matching posts, keyed by the time each period spans, from its start up to, but not including, its end, oldest first

# File 'x-objects/lib/x/objects/lookups/posts.rb', line 138

def count_posts_by_period(query, **params) = Post.count_by_period(query, client: self, **params) # steep:ignore DifferentMethodParameterKind

#find_all_posts(ids, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Post> Also known as: find_all_tweets

Look up many posts by identifier, in parallel batches

Examples:

Look up many posts

client.find_all_posts([1234567890, 1234567891])

Look up many posts one batch at a time

client.find_all_posts(ids, concurrency: 1)

Parameters:

• ids (Array<String, Integer, Post>) —

  the identifiers

• concurrency (Integer) (defaults to: BatchFinders::DEFAULT_CONCURRENCY) —

  the number of batches looked up at once, which must be at least one; each is a request of up to 100 posts, so a lower number spends a rate limit more slowly

• params (Hash) —

  query parameters merged over the default parameters

Yield Parameters:

• problem (Problem) —

  each problem the API reported, such as a resource that was not found

Returns:

• (Array<Post>) —

  the posts that were found

Raises:

• (ArgumentError) —

  if the concurrency is less than one

# File 'x-objects/lib/x/objects/lookups/posts.rb', line 57

def find_all_posts(ids, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params, &)
  Post.find_all(ids, client: self, concurrency:, **params, &)
end

#find_post(id, **params) {|problem| ... } ⇒ Post^? Also known as: find_tweet

Look up a post by identifier

Examples:

Look up a post

client.find_post(1234567890).text

Parameters:

• id (String, Integer, Post) —

  the identifier

• params (Hash) —

  query parameters merged over the default parameters

Yield Parameters:

• problem (Problem) —

  each problem the API reported, such as a resource that was not found

Returns:

• (Post, nil) —

  the post or nil if the post was not found

# File 'x-objects/lib/x/objects/lookups/posts.rb', line 26

def find_post(id, **params, &)
  Post.find(id, client: self, **params, &)
end

#find_post!(id, **params) ⇒ Post Also known as: find_tweet!

Look up a post by identifier, which must exist

Examples:

Look up a post

client.find_post!(1234567890).text

Parameters:

• id (String, Integer, Post) —

  the identifier

• params (Hash) —

  query parameters merged over the default parameters

Returns:

• (Post) —

  the post

Raises:

• (MissingResource) —

  if the post was not found

# File 'x-objects/lib/x/objects/lookups/posts.rb', line 39

def find_post!(id, **params)
  Post.find!(id, client: self, **params)
end

#post_usage(**params) {|problem| ... } ⇒ PostUsage^?

Look up how many posts the app's project has read

The usage endpoint takes app-only authentication alone, so a client that signs with OAuth 1.0a looks it up with a copy that authenticates as the app, and one signed in with OAuth 2.0 as a user that holds no credentials of the app is refused with X::Forbidden.

A response that holds no usage returns nil, as current_user does for a users/me that holds no user, and passes the problems it reported to the block, if there is one.

Examples:

Check how much of the monthly cap remains

usage = client.post_usage
usage.project_cap - usage.project_usage if usage

Parameters:

• params (Hash) —

  query parameters, such as days, the number of days to report, which is 7 by default

Yield Parameters:

• problem (Problem) —

  each problem the API reported

Returns:

• (PostUsage, nil) —

  the usage, or nil if the response holds none

# File 'x-objects/lib/x/objects/lookups/posts.rb', line 172

def post_usage(**params, &) = PostUsage.current(client: self, **params, &)

#post_usage!(**params) ⇒ PostUsage

Look up how many posts the app's project has read, which must be returned

Examples:

Check how much of the monthly cap remains

usage = client.post_usage!
usage.project_cap - usage.project_usage

Parameters:

• params (Hash) —

  query parameters, such as days, the number of days to report, which is 7 by default

Returns:

• (PostUsage) —

  the usage

Raises:

• (MissingResource) —

  if the API returns no usage

# File 'x-objects/lib/x/objects/lookups/posts.rb', line 183

def post_usage!(**params) = PostUsage.current!(client: self, **params)

#reposts_of_me(**params) ⇒ Cursor Also known as: retweets_of_me

The posts of the authenticated user that other users have reposted

Examples:

Print the reposted posts

client.reposts_of_me.each { |post| puts post.text }

Parameters:

• params (Hash) —

  query parameters merged over the default parameters

Returns:

• (Cursor) —

  a cursor over the reposted posts

# File 'x-objects/lib/x/objects/lookups/posts.rb', line 80

def reposts_of_me(**params)
  Post.reposts_of_me(client: self, **params)
end

#search_all_posts(query, **params) ⇒ Cursor Also known as: search_all_tweets

Search the full archive of posts

Examples:

Print every post about Ruby

client.search_all_posts("ruby -is:retweet").each { |post| puts post.text }

Parameters:

• query (String) —

  the search query

• params (Hash) —

  query parameters merged over the default parameters

Returns:

• (Cursor) —

  a cursor over the matching posts

# File 'x-objects/lib/x/objects/lookups/posts.rb', line 92

def search_all_posts(query, **params)
  Post.search_all(query, client: self, **params)
end

#search_posts(query, **params) ⇒ Cursor Also known as: search_tweets

Search recent posts

Examples:

Print posts about Ruby

client.search_posts("ruby -is:retweet").each { |post| puts post.text }

Parameters:

• query (String) —

  the search query

• params (Hash) —

  query parameters merged over the default parameters

Returns:

• (Cursor) —

  a cursor over the matching posts

# File 'x-objects/lib/x/objects/lookups/posts.rb', line 69

def search_posts(query, **params)
  Post.search(query, client: self, **params)
end