Module: X::Resources::PostCounts

Included in:

Post

Defined in:

x-resources/lib/x/resources/post_counts.rb

Overview

Counts of the posts that match a query, which the API bills by the request rather than by the post

The counts endpoints refuse OAuth 1.0a, so a client that signs with it 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 count of recent posts takes, and the count of the full archive, which takes app-only authentication alone, refuses with 403 Forbidden, raising X::Forbidden.

Internal to x-resources: the methods it gives Post, such as X::Post.count, are public API, but the module is only how they are shared, and which classes extend or include it can change within 1.x.

Instance Method Summary

• #count(query, client:, max_pages: nil, **params) ⇒ Integer

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

• #count_all(query, client:, max_pages: nil, **params) ⇒ Integer

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

• #count_all_by_period(query, client:, max_pages: nil, **params) ⇒ Hash{Range<Time> => Integer}

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

• #count_by_period(query, client:, max_pages: nil, **params) ⇒ Hash{Range<Time> => Integer}

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

Instance Method Details

#count(query, client:, max_pages: nil, **params) ⇒ Integer

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

The recent posts are counted a page of periods at a time, as the full archive is, which max_pages limits.

Examples:

Count the recent posts about Ruby

X::Post.count("ruby", client: client)

Parameters:

• query (String) —

  the search query

• client (Object) —

  the client used to make the requests

• max_pages (Integer, nil) (defaults to: nil) —

  the most pages of counts to request, or nil for no limit

• params (Hash) —

  query parameters, such as start_time and end_time

Returns:

• (Integer) —

  the number of matching posts

Raises:

• (ArgumentError) —

  if max_pages is neither an Integer of at least 1 nor nil, before a request

• (InvalidAttribute) —

  if the response holds a total that is not a number

• (UnreadableResponse) —

  if a page names the token of a page before it as the next

• (PageLimitReached) —

  if the count requests max_pages pages, and the API names another

# File 'x-resources/lib/x/resources/post_counts.rb', line 50

def count(query, client:, max_pages: nil, **params) = total(pages(RECENT_ENDPOINT, query, client:, max_pages:, **params))

#count_all(query, client:, max_pages: nil, **params) ⇒ Integer

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

The archive is counted a page of periods at a time, and the API bills each page, so a count over many years can take many requests, which max_pages limits, raising PageLimitReached rather than read past them.

Examples:

Count every post about Ruby

X::Post.count_all("ruby", client: client)

Count the posts about Ruby in no more than three requests

X::Post.count_all("ruby", client: client, max_pages: 3)

Parameters:

• query (String) —

  the search query

• client (Object) —

  the client used to make the requests

• max_pages (Integer, nil) (defaults to: nil) —

  the most pages of counts to request, or nil for no limit

• params (Hash) —

  query parameters, such as start_time and end_time

Returns:

• (Integer) —

  the number of matching posts

Raises:

• (ArgumentError) —

  if max_pages is neither an Integer of at least 1 nor nil, before a request

• (InvalidAttribute) —

  if the response holds a total that is not a number

• (UnreadableResponse) —

  if a page names the token of a page before it as the next

• (PageLimitReached) —

  if the count requests max_pages pages, and the API names another

# File 'x-resources/lib/x/resources/post_counts.rb', line 71

def count_all(query, client:, max_pages: nil, **params) = total(pages(ALL_ENDPOINT, query, client:, max_pages:, **params))

#count_all_by_period(query, client:, max_pages: nil, **params) ⇒ Hash{Range<Time> => Integer}

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

The archive is counted a page of periods at a time, and the API bills each page, so a count over many years can take many requests, which max_pages limits, raising PageLimitReached rather than read past them.

Examples:

Count every post about Ruby by day

X::Post.count_all_by_period("ruby", client: client)

Parameters:

• query (String) —

  the search query

• client (Object) —

  the client used to make the requests

• max_pages (Integer, nil) (defaults to: nil) —

  the most pages of counts to request, or nil for no limit

• params (Hash) —

  query parameters, such as granularity, which is day by default

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

Raises:

• (ArgumentError) —

  if max_pages is neither an Integer of at least 1 nor nil, before a request

• (InvalidAttribute) —

  if the response holds a period without a start and an end in ISO 8601, or without a count

• (UnreadableResponse) —

  if a page names the token of a page before it as the next

• (PageLimitReached) —

  if the count requests max_pages pages, and the API names another

# File 'x-resources/lib/x/resources/post_counts.rb', line 112

def count_all_by_period(query, client:, max_pages: nil, **params) = periods(pages(ALL_ENDPOINT, query, client:, max_pages:, **params))

#count_by_period(query, client:, max_pages: nil, **params) ⇒ Hash{Range<Time> => Integer}

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

The recent posts are counted a page of periods at a time, as the full archive is, which max_pages limits.

Examples:

Count the recent posts about Ruby by hour

X::Post.count_by_period("ruby", client: client, granularity: "hour")

Parameters:

• query (String) —

  the search query

• client (Object) —

  the client used to make the requests

• max_pages (Integer, nil) (defaults to: nil) —

  the most pages of counts to request, or nil for no limit

• params (Hash) —

  query parameters, such as granularity, which is day by default

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

Raises:

• (ArgumentError) —

  if max_pages is neither an Integer of at least 1 nor nil, before a request

• (InvalidAttribute) —

  if the response holds a period without a start and an end in ISO 8601, or without a count

• (UnreadableResponse) —

  if a page names the token of a page before it as the next

• (PageLimitReached) —

  if the count requests max_pages pages, and the API names another

# File 'x-resources/lib/x/resources/post_counts.rb', line 91

def count_by_period(query, client:, max_pages: nil, **params) = periods(pages(RECENT_ENDPOINT, query, client:, max_pages:, **params))