Class: X::User

Inherits:

Resource

Object
Resource
X::User

show all

Extended by:: UserFinders, Resources::UserFinders

Includes:: Relationships, UserCollections, Resources::Relationships, Resources::UserCollections

Defined in:: x-resources/lib/x/resources/user.rb

Overview

A user account

Constant Summary collapse

FIELDS = The user fields the object layer requests: every one that does not depend on who is authenticated, since a field that does, such as connection_status, would make every request fail for a client that cannot read it; the identifiers of referenced posts, and the affiliation, come with their expansions A minor release may add to it the fields the API adds, so that a lookup asks for them too; see Resource#hydrated? for what that means for a resource looked up with a list of fields of its own.

%w[created_at description entities id is_identity_verified location name parody profile_banner_url
profile_image_url protected public_metrics subscriber_count subscription_type url username verified
verified_followers_count verified_type withheld].freeze

EXPANSIONS = Every expansion available on user endpoints The API gives a user its affiliation when a request asks for the affiliation expansion, which it takes only at the endpoints whose data is users, so the users a post, a list, a space, or a direct message includes hold none, and hydrate looks them up with it. A minor release may add to it the expansions the API adds, so that a lookup asks for them too; see Resource#hydrated? for what that means for a resource looked up with a list of expansions of its own.

%w[affiliation most_recent_post_id pinned_post_id].freeze

Instance Attribute Summary collapse

#affiliated_with_ids ⇒ Array<Integer> readonly
The identifiers of the accounts this account is affiliated with.
#affiliation ⇒ Hash^? readonly
The organization the account is affiliated with, with its badge.
#connection_status ⇒ Array<String>^? readonly
How the authenticated user and this user are connected.
#created_at ⇒ Time^? readonly
The time when the account was created.
#description ⇒ String^? readonly
The profile description.
#entities ⇒ Hash^? readonly
The entities found in the description and URL.
#followers_count ⇒ Integer^? readonly
The number of followers.
#following_count ⇒ Integer^? readonly
The number of followed users.
#identity_verified ⇒ Boolean^? readonly
Whether the account's identity is verified, the is_identity_verified field.
#like_count ⇒ Integer^? readonly
The number of posts the user has liked.
#listed_count ⇒ Integer^? readonly
The number of lists the user is a member of.
#location ⇒ String^? readonly
The profile location.
#media_count ⇒ Integer^? readonly
The number of photos and videos the user has posted.
#most_recent_post_id ⇒ Integer^? (also: #most_recent_tweet_id) readonly
The identifier of the most recent post.
#name ⇒ String^? readonly
The display name.
#parody ⇒ Boolean^? readonly
Whether the account labels itself a parody.
#pinned_post_id ⇒ Integer^? (also: #pinned_tweet_id) readonly
The identifier of the pinned post.
#post_count ⇒ Integer^? (also: #tweet_count) readonly
The number of posts.
#profile_banner_url ⇒ String^? readonly
The profile banner URL.
#profile_image_url ⇒ String^? readonly
The profile image URL.
#protected ⇒ Boolean^? readonly
Whether the account's posts are protected.
#public_metrics ⇒ Hash^? readonly
The public metrics.
#receives_your_dm ⇒ Boolean^? readonly
Whether the authenticated user can send this user a direct message.
#subscriber_count ⇒ Integer^? readonly
The number of users who subscribe to the user.
#subscribes_to_you ⇒ Boolean^? readonly
Whether this user subscribes to the authenticated user.
#subscription ⇒ Hash^? readonly
The subscription between this user and the authenticated user.
#subscription_type ⇒ String^? readonly
The subscription the account pays for: Basic, Premium, PremiumPlus, or None.
#url ⇒ String^? readonly
The URL of the website the profile links to.
#username ⇒ String^? readonly
The handle, without the leading at sign.
#verified ⇒ Boolean^? readonly
Whether the account is verified.
#verified_followers_count ⇒ Integer^? readonly
The number of verified followers.
#verified_type ⇒ String^? readonly
The verification type: blue, business, government, or none.
#withheld ⇒ Hash^? readonly
The withholding details.

Class Method Summary collapse

.current(client:, **params) {|problem| ... } ⇒ User^? extended from Resources::UserFinders
Look up the authenticated user.
.current!(client:, **params) ⇒ User extended from Resources::UserFinders
Look up the authenticated user, who must be found.
.default_params ⇒ Hash{String => Array<String>}
The default query parameters requesting every user field and expansion.
.find(id_or_username, client:, **params) {|problem| ... } ⇒ User^? extended from Resources::UserFinders
Look up a user by identifier or username.
.find!(id_or_username, client:, **params) ⇒ User extended from Resources::UserFinders
Look up a user by identifier or username, which must exist.
.find_all(ids_or_usernames, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<User> extended from Resources::UserFinders
Look up many users by identifier or username, in parallel batches.
.find_all_by_id(ids, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<User> extended from Resources::UserFinders
Look up many users by identifier, in parallel batches.
.find_all_by_username(usernames, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<User> extended from Resources::UserFinders
Look up many users by username, in parallel batches.
.find_by_id(id, client:, **params) {|problem| ... } ⇒ User^? extended from Resources::UserFinders
Look up a user by identifier.
.find_by_id!(id, client:, **params) ⇒ User extended from Resources::UserFinders
Look up a user by identifier, which must exist.
.find_by_username(username, client:, **params) {|problem| ... } ⇒ User^? extended from Resources::UserFinders
Look up a user by username.
.find_by_username!(username, client:, **params) ⇒ User extended from Resources::UserFinders
Look up a user by username, which must exist.
.hydrate_all(resources, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Resource> extended from Resources::BatchFinders
Replace the resources that are not hydrated with the full resources.
.search(query, client:, **params) ⇒ Cursor
Search users.

Instance Method Summary collapse

#affiliated_with ⇒ Array<User>
The accounts this account is affiliated with, such as its organization.
#affiliates(**params) ⇒ Cursor included from Resources::UserCollections
The users affiliated with this user, such as the people of an organization.
#blocking(**params) ⇒ Cursor included from Resources::UserCollections
The users this user blocks, which must be the authenticated user.
#bookmark_folders(**params) ⇒ Cursor included from Resources::UserCollections
The bookmark folders of the authenticated user.
#bookmarks(folder: nil, **params) ⇒ Cursor included from Resources::UserCollections
The posts bookmarked by the authenticated user, or those of one of their folders.
#followed_lists(**params) ⇒ Cursor included from Resources::UserCollections
The lists this user follows.
#followers(**params) ⇒ Cursor included from Resources::UserCollections
The users following this user.
#following(**params) ⇒ Cursor included from Resources::UserCollections
The users this user follows.
#follows?(user, max_pages: nil) ⇒ Boolean included from Resources::Relationships
Check whether this user follows a user.
#home_timeline(**params) ⇒ Cursor included from Resources::UserCollections
The home timeline of this user, which must be the authenticated user.
#identity_verified? ⇒ Boolean
Check whether the account's identity is verified.
#liked_posts(**params) ⇒ Cursor (also: #liked_tweets) included from Resources::UserCollections
The posts liked by this user.
#list_memberships(**params) ⇒ Cursor included from Resources::UserCollections
The lists this user is a member of.
#mentions(**params) ⇒ Cursor included from Resources::UserCollections
The posts mentioning this user.
#most_recent_post ⇒ Post^? (also: #most_recent_tweet)
The most recent post, from the includes or as a stub holding only its identifier.
#muting(**params) ⇒ Cursor included from Resources::UserCollections
The users this user mutes, which must be the authenticated user.
#owned_lists(**params) ⇒ Cursor included from Resources::UserCollections
The lists owned by this user.
#parody? ⇒ Boolean
Check whether the account labels itself a parody.
#permalink ⇒ String
The permalink of the profile, by username when known and by identifier otherwise.
#pinned_lists(**params) ⇒ Cursor included from Resources::UserCollections
The lists this user has pinned.
#pinned_post ⇒ Post^? (also: #pinned_tweet)
The pinned post, from the includes or as a stub holding only its identifier.
#posts(**params) ⇒ Cursor (also: #tweets) included from Resources::UserCollections
The posts by this user.
#protected? ⇒ Boolean
Check whether the account's posts are protected.
#receives_your_dm? ⇒ Boolean
Check whether the authenticated user can send this user a direct message.
#subscribes_to_you? ⇒ Boolean
Check whether this user subscribes to the authenticated user.
#uri ⇒ URI::Generic
The permalink of the user as a URI.
#verified? ⇒ Boolean
Check whether the account is verified.

Constructor Details

This class inherits a constructor from X::Resource

Instance Attribute Details

#affiliated_with_ids ⇒ `Array<Integer>` (readonly)

The identifiers of the accounts this account is affiliated with

Examples:

Get the identifiers of the accounts it is affiliated with

user.affiliated_with_ids

Returns:

(Array<Integer>) —
the identifiers, empty if there are none

262	# File 'x-resources/lib/x/resources/user.rb', line 262 attribute :affiliated_with_ids, :integers, key: %w[affiliation user_id]

#affiliation ⇒ `Hash`^? (readonly)

The organization the account is affiliated with, with its badge

The API gives it for the affiliation expansion, which only the endpoints whose data is users take, so a user a post, a list, a space, or a direct message includes holds none until it is hydrated.

Examples:

Get the affiliated organization

user.affiliation&.fetch("description")

Returns:

(Hash, nil) —
the affiliation, with its description, url, badge_url, and user_id

254	# File 'x-resources/lib/x/resources/user.rb', line 254 attribute :affiliation, :object

#connection_status ⇒ `Array<String>`^? (readonly)

How the authenticated user and this user are connected

No lookup asks for it unless user.fields names it, so a user looked up otherwise holds none, and reads nil rather than an empty list, which would say the users are not connected.

Examples:

Check whether this user follows the authenticated user

client.find_user("sferik", "user.fields": "connection_status").connection_status.include?("followed_by")

Returns:

(Array<String>, nil) —
following, followed_by, blocking, muting, follow_request_sent, or follow_request_received, or nil when the response holds none

291	# File 'x-resources/lib/x/resources/user.rb', line 291 attribute :connection_status, :requested_list

#created_at ⇒ `Time`^? (readonly)

The time when the account was created

Examples:

Get the creation time

user.created_at

Returns:

(Time, nil) —
the creation time

166	# File 'x-resources/lib/x/resources/user.rb', line 166 attribute :created_at, :time

#description ⇒ `String`^? (readonly)

The profile description

Examples:

Get the description

user.description

Returns:

(String, nil) —
the description

122	# File 'x-resources/lib/x/resources/user.rb', line 122 attribute :description

#entities ⇒ `Hash`^? (readonly)

The entities found in the description and URL

Examples:

Get the entities

user.entities

Returns:

(Hash, nil) —
the entities

374	# File 'x-resources/lib/x/resources/user.rb', line 374 attribute :entities, :object

#followers_count ⇒ `Integer`^? (readonly)

The number of followers

Examples:

Get the follower count

user.followers_count

Returns:

(Integer, nil) —
the follower count

398	# File 'x-resources/lib/x/resources/user.rb', line 398 attribute :followers_count, :integer, key: %w[public_metrics followers_count]

#following_count ⇒ `Integer`^? (readonly)

The number of followed users

Examples:

Get the following count

user.following_count

Returns:

(Integer, nil) —
the following count

406	# File 'x-resources/lib/x/resources/user.rb', line 406 attribute :following_count, :integer, key: %w[public_metrics following_count]

#identity_verified ⇒ `Boolean`^? (readonly)

Whether the account's identity is verified, the is_identity_verified field

Examples:

Check whether a user's identity is verified

user.identity_verified?

Returns:

(Boolean, nil) —
true if the identity is verified

227	# File 'x-resources/lib/x/resources/user.rb', line 227 attribute :identity_verified, :boolean, key: %w[is_identity_verified]

#like_count ⇒ `Integer`^? (readonly)

The number of posts the user has liked

Examples:

Get the like count

user.like_count

Returns:

(Integer, nil) —
the like count

430	# File 'x-resources/lib/x/resources/user.rb', line 430 attribute :like_count, :integer, key: %w[public_metrics like_count]

#listed_count ⇒ `Integer`^? (readonly)

The number of lists the user is a member of

Examples:

Get the listed count

user.listed_count

Returns:

(Integer, nil) —
the listed count

422	# File 'x-resources/lib/x/resources/user.rb', line 422 attribute :listed_count, :integer, key: %w[public_metrics listed_count]

#location ⇒ `String`^? (readonly)

The profile location

Examples:

Get the location

user.location

Returns:

(String, nil) —
the location

130	# File 'x-resources/lib/x/resources/user.rb', line 130 attribute :location

#media_count ⇒ `Integer`^? (readonly)

The number of photos and videos the user has posted

Examples:

Get the media count

user.media_count

Returns:

(Integer, nil) —
the media count

438	# File 'x-resources/lib/x/resources/user.rb', line 438 attribute :media_count, :integer, key: %w[public_metrics media_count]

#most_recent_post_id ⇒ `Integer`^? (readonly) Also known as: most_recent_tweet_id

The identifier of the most recent post

Examples:

Get the most recent post identifier

user.most_recent_post_id

Returns:

(Integer, nil) —
the most recent post identifier

366	# File 'x-resources/lib/x/resources/user.rb', line 366 attribute :most_recent_post_id, :integer, tweet_key: %w[most_recent_tweet_id]

#name ⇒ `String`^? (readonly)

The display name

Examples:

Get the name

user.name # => "Erik Berlin"

Returns:

(String, nil) —
the display name

106	# File 'x-resources/lib/x/resources/user.rb', line 106 attribute :name

#parody ⇒ `Boolean`^? (readonly)

Whether the account labels itself a parody

Examples:

Check whether a user is a parody account

user.parody?

Returns:

(Boolean, nil) —
true if the account is labelled a parody

212	# File 'x-resources/lib/x/resources/user.rb', line 212 attribute :parody, :boolean

#pinned_post_id ⇒ `Integer`^? (readonly) Also known as: pinned_tweet_id

The identifier of the pinned post

Examples:

Get the pinned post identifier

user.pinned_post_id

Returns:

(Integer, nil) —
the pinned post identifier

358	# File 'x-resources/lib/x/resources/user.rb', line 358 attribute :pinned_post_id, :integer, tweet_key: %w[pinned_tweet_id]

#post_count ⇒ `Integer`^? (readonly) Also known as: tweet_count

The number of posts

Examples:

Get the post count

user.post_count

Returns:

(Integer, nil) —
the post count

414	# File 'x-resources/lib/x/resources/user.rb', line 414 attribute :post_count, :integer, key: %w[public_metrics post_count], tweet_key: %w[public_metrics tweet_count]

#profile_banner_url ⇒ `String`^? (readonly)

The profile banner URL

Examples:

Get the profile banner URL

user.profile_banner_url

Returns:

(String, nil) —
the profile banner URL

158	# File 'x-resources/lib/x/resources/user.rb', line 158 attribute :profile_banner_url

#profile_image_url ⇒ `String`^? (readonly)

The profile image URL

Examples:

Get the profile image URL

user.profile_image_url

Returns:

(String, nil) —
the profile image URL

150	# File 'x-resources/lib/x/resources/user.rb', line 150 attribute :profile_image_url

#protected ⇒ `Boolean`^? (readonly)

Whether the account's posts are protected

Examples:

Check whether a user is protected

user.protected?

Returns:

(Boolean, nil) —
true if the posts are protected

174	# File 'x-resources/lib/x/resources/user.rb', line 174 attribute :protected, :boolean

#public_metrics ⇒ `Hash`^? (readonly)

The public metrics

Examples:

Get the public metrics

user.public_metrics

Returns:

(Hash, nil) —
the public metrics

390	# File 'x-resources/lib/x/resources/user.rb', line 390 attribute :public_metrics, :object

#receives_your_dm ⇒ `Boolean`^? (readonly)

Whether the authenticated user can send this user a direct message

It depends on who is authenticated, so no lookup asks for it unless user.fields names it, and a user looked up otherwise holds none, and reads nil rather than false, which would say the user receives none.

Examples:

Check whether a user can be sent a direct message

client.find_user("sferik", "user.fields": "receives_your_dm").receives_your_dm?

Returns:

(Boolean, nil) —
true if the authenticated user can send this user a direct message, or nil when the response holds none

304	# File 'x-resources/lib/x/resources/user.rb', line 304 attribute :receives_your_dm, :boolean

#subscriber_count ⇒ `Integer`^? (readonly)

The number of users who subscribe to the user

Examples:

Get the subscriber count

user.subscriber_count

Returns:

(Integer, nil) —
the subscriber count

278	# File 'x-resources/lib/x/resources/user.rb', line 278 attribute :subscriber_count, :integer

#subscribes_to_you ⇒ `Boolean`^? (readonly)

Whether this user subscribes to the authenticated user

It depends on who is authenticated, so no lookup asks for it unless user.fields names it, and a user looked up otherwise holds none, and reads nil rather than false.

Examples:

Check whether a user subscribes to the authenticated user

client.find_user("sferik", "user.fields": "subscribes_to_you").subscribes_to_you?

Returns:

(Boolean, nil) —
true if this user subscribes to the authenticated user, or nil when the response holds none

328	# File 'x-resources/lib/x/resources/user.rb', line 328 attribute :subscribes_to_you, :boolean

#subscription ⇒ `Hash`^? (readonly)

The subscription between this user and the authenticated user

It depends on who is authenticated, so no lookup asks for it unless user.fields names it, and a user looked up otherwise holds none.

Examples:

Check whether a user subscribes to the authenticated user

client.find_user("sferik", "user.fields": "subscription").subscription&.fetch("subscribes_to_you")

Returns:

(Hash, nil) —
the subscription, with subscribes_to_you, or nil when the response holds none

350	# File 'x-resources/lib/x/resources/user.rb', line 350 attribute :subscription, :object

#subscription_type ⇒ `String`^? (readonly)

The subscription the account pays for: Basic, Premium, PremiumPlus, or None

Examples:

Get the subscription type

user.subscription_type

Returns:

(String, nil) —
the subscription type

242	# File 'x-resources/lib/x/resources/user.rb', line 242 attribute :subscription_type

#url ⇒ `String`^? (readonly)

The URL of the website the profile links to

The API gives it shortened, as a t.co link, and the URL it stands for is in the url entities of #entities. It is not the address of the profile on x.com, which #permalink and #uri read.

Examples:

Get the URL

user.url # => "https://t.co/abc"

Returns:

(String, nil) —
the URL, or nil for a profile that links to no website

142	# File 'x-resources/lib/x/resources/user.rb', line 142 attribute :url

#username ⇒ `String`^? (readonly)

The handle, without the leading at sign

Examples:

Get the username

user.username # => "sferik"

Returns:

(String, nil) —
the username

114	# File 'x-resources/lib/x/resources/user.rb', line 114 attribute :username

#verified ⇒ `Boolean`^? (readonly)

Whether the account is verified

Examples:

Check whether a user is verified

user.verified?

Returns:

(Boolean, nil) —
true if the account is verified

189	# File 'x-resources/lib/x/resources/user.rb', line 189 attribute :verified, :boolean

#verified_followers_count ⇒ `Integer`^? (readonly)

The number of verified followers

Examples:

Get the verified follower count

user.verified_followers_count

Returns:

(Integer, nil) —
the verified follower count

270	# File 'x-resources/lib/x/resources/user.rb', line 270 attribute :verified_followers_count, :integer

#verified_type ⇒ `String`^? (readonly)

The verification type: blue, business, government, or none

Examples:

Get the verification type

user.verified_type

Returns:

(String, nil) —
the verification type

204	# File 'x-resources/lib/x/resources/user.rb', line 204 attribute :verified_type

#withheld ⇒ `Hash`^? (readonly)

The withholding details

Examples:

Get the withholding details

user.withheld

Returns:

(Hash, nil) —
the withholding details

382	# File 'x-resources/lib/x/resources/user.rb', line 382 attribute :withheld, :object

Class Method Details

.current(client:, **params) {|problem| ... } ⇒ `User`^? Originally defined in module Resources::UserFinders

Look up the authenticated user

Its path names no user, so a 404 to it is no user that is missing, and raises X::NotFound as any request does.

Examples:

Look up the authenticated user

X::User.current(client: client)

Parameters:

client (Object) —
the client used to make the request
params (Hash) —
query parameters merged over the default parameters

Yield Parameters:

problem (Problem) —
each problem the API reported

Returns:

(User, nil) —
the authenticated user

.current!(client:, **params) ⇒ `User` Originally defined in module Resources::UserFinders

Look up the authenticated user, who must be found

Examples:

Look up the authenticated user

X::User.current!(client: client)

Parameters:

client (Object) —
the client used to make the request
params (Hash) —
query parameters merged over the default parameters

Returns:

(User) —
the authenticated user

Raises:

(MissingResource) —
if the API returns no user

.default_params ⇒ `Hash{String => Array<String>}`

The default query parameters requesting every user field and expansion

Examples:

Get the default parameters

X::User.default_params["user.fields"]

Returns:

(Hash{String => Array<String>}) —
the default query parameters



82
83
84

# File 'x-resources/lib/x/resources/user.rb', line 82

def default_params
  {"user.fields" => FIELDS, "post.fields" => Post::FIELDS, "expansions" => EXPANSIONS}
end

.find(id_or_username, client:, **params) {|problem| ... } ⇒ `User`^? Originally defined in module Resources::UserFinders

Look up a user by identifier or username

An Integer or a user is looked up by identifier, and a String by username, with or without a leading at sign.

Examples:

Look up a user by username

X::User.find("sferik", client: client)

Parameters:

id_or_username (Integer, User, String) —
an identifier or a user, or a username
client (Object) —
the client used to make the request
params (Hash) —
query parameters merged over the default parameters

Yield Parameters:

problem (Problem) —
each problem the API reported, such as a user that was not found

Returns:

(User, nil) —
the user or nil if the user was not found, whether the API answers 200 with no data or a 404 that reports the user as not found

Raises:

(X::NotFound) —
if the API answers any other 404, such as one from a client pointed at the wrong host or API version
(ArgumentError) —
if the value is neither an identifier nor a username

.find!(id_or_username, client:, **params) ⇒ `User` Originally defined in module Resources::UserFinders

Look up a user by identifier or username, which must exist

An Integer or a user is looked up by identifier, and a String by username, as find looks them up, so the error it raises names a username as find_by_username! names one, with the at sign of a handle.

Examples:

Look up a user by username

X::User.find!("sferik", client: client)

Parameters:

id_or_username (Integer, User, String) —
an identifier or a user, or a username
client (Object) —
the client used to make the request
params (Hash) —
query parameters merged over the default parameters

Returns:

(User) —
the user

Raises:

(ArgumentError) —
if the value is neither an identifier nor a username
(MissingResource) —
if the user was not found, whether the API answers 200 with no data or a 404 that reports the user as not found
(X::NotFound) —
if the API answers any other 404, such as one from a client pointed at the wrong host or API version

.find_all(ids_or_usernames, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ `Array<User>` Originally defined in module Resources::UserFinders

Look up many users by identifier or username, in parallel batches

Integers and users are looked up by identifier, and Strings by username. The users come back in the order they were asked for, one for each value that was found, so a user asked for twice, by identifier or by username, comes back twice, without the ones that were not found. Every username is checked before any request, so one that is not a username raises before the identifiers are looked up, and billed.

Examples:

Look up many users by username

X::User.find_all(["sferik", "gem"], client: client)

Parameters:

ids_or_usernames (Array<Integer, User, String>) —
identifiers or users, or usernames
client (Object) —
the client used to make the requests
concurrency (Integer) (defaults to: DEFAULT_CONCURRENCY) —
the number of batches looked up at once, which must be at least one; the identifiers and the usernames are looked up one kind after the other, each kind that many batches at a time
params (Hash) —
query parameters merged over the default parameters

Yield Parameters:

problem (Problem) —
each problem the API reported, such as a user that was not found

Returns:

(Array<User>) —
the users that were found, one for each value that names one, frozen

Raises:

(ArgumentError) —
if a String is not a username, or if the concurrency is less than one, before any request

.find_all_by_id(ids, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ `Array<User>` Originally defined in module Resources::UserFinders

Look up many users by identifier, in parallel batches

A String of digits is an identifier, as it is read from a response or an environment variable, so this looks the accounts those numbers identify up, where find_all would take them for usernames. The users come back in the order they were asked for, one for each identifier that was found, as find_all returns them.

Examples:

Look up many users by identifier, read as Strings

X::User.find_all_by_id(ENV.fetch("USER_IDS").split(","), client: client)

Parameters:

ids (Array<String, Integer, User>) —
the identifiers, or users
client (Object) —
the client used to make the requests
concurrency (Integer) (defaults to: DEFAULT_CONCURRENCY) —
the number of batches looked up at once, which must be at least one
params (Hash) —
query parameters merged over the default parameters

Yield Parameters:

problem (Problem) —
each problem the API reported, such as an identifier that was not found

Returns:

(Array<User>) —
the users that were found, one for each identifier that names one, frozen

Raises:

(ArgumentError) —
if a value is not an identifier, or if the concurrency is less than one

.find_all_by_username(usernames, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ `Array<User>` Originally defined in module Resources::UserFinders

Look up many users by username, in parallel batches

The users come back in the order they were asked for, one for each username that was found, whatever its case, as find_all returns them, and each username is asked for once, however often, and in whatever case, it is given.

Examples:

Look up many users by username

X::User.find_all_by_username(["sferik", "gem"], client: client)

Parameters:

usernames (Array<String>) —
the usernames, with or without leading at signs
client (Object) —
the client used to make the requests
concurrency (Integer) (defaults to: DEFAULT_CONCURRENCY) —
the number of batches looked up at once, which must be at least one
params (Hash) —
query parameters merged over the default parameters

Yield Parameters:

problem (Problem) —
each problem the API reported, such as a username that was not found

Returns:

(Array<User>) —
the users that were found, one for each username that names one, frozen

Raises:

(ArgumentError) —
if a value is not a username, or if the concurrency is less than one

.find_by_id(id, client:, **params) {|problem| ... } ⇒ `User`^? Originally defined in module Resources::UserFinders

Look up a user by identifier

A String of digits is an identifier, as it is read from a response or an environment variable, so this looks the account that number identifies up, where find would take it for a username.

Examples:

Look up a user by an identifier read as a String

X::User.find_by_id(ENV.fetch("USER_ID"), client: client)

Parameters:

id (String, Integer, User) —
the identifier, or a user
client (Object) —
the client used to make the request
params (Hash) —
query parameters merged over the default parameters

Yield Parameters:

problem (Problem) —
each problem the API reported, such as a user that was not found

Returns:

(User, nil) —
the user or nil if the user was not found, whether the API answers 200 with no data or a 404 that reports the user as not found

Raises:

(X::NotFound) —
if the API answers any other 404, such as one from a client pointed at the wrong host or API version
(ArgumentError) —
if the value is not an identifier

.find_by_id!(id, client:, **params) ⇒ `User` Originally defined in module Resources::UserFinders

Look up a user by identifier, which must exist

Examples:

Look up a user by an identifier read as a String

X::User.find_by_id!("7505382", client: client)

Parameters:

id (String, Integer, User) —
the identifier, or a user
client (Object) —
the client used to make the request
params (Hash) —
query parameters merged over the default parameters

Returns:

(User) —
the user

Raises:

(ArgumentError) —
if the value is not an identifier
(MissingResource) —
if the user was not found, whether the API answers 200 with no data or a 404 that reports the user as not found
(X::NotFound) —
if the API answers any other 404, such as one from a client pointed at the wrong host or API version

.find_by_username(username, client:, **params) {|problem| ... } ⇒ `User`^? Originally defined in module Resources::UserFinders

Look up a user by username

It looks every value up as a username, a String of digits as the account whose handle is that number, as find looks up any String, so code that reads a value from elsewhere says which it means, as find_by_id does.

Examples:

Look up a user by username

X::User.find_by_username("sferik", client: client)

Parameters:

username (String) —
the username, with or without a leading at sign
client (Object) —
the client used to make the request
params (Hash) —
query parameters merged over the default parameters

Yield Parameters:

problem (Problem) —
each problem the API reported, such as a user that was not found

Returns:

(User, nil) —
the user or nil if the user was not found, whether the API answers 200 with no data or a 404 that reports the user as not found

Raises:

(X::NotFound) —
if the API answers any other 404, such as one from a client pointed at the wrong host or API version
(ArgumentError) —
if the value is not a username

.find_by_username!(username, client:, **params) ⇒ `User` Originally defined in module Resources::UserFinders

Look up a user by username, which must exist

Examples:

Look up a user by username

X::User.find_by_username!("sferik", client: client)

Parameters:

username (String) —
the username, with or without a leading at sign
client (Object) —
the client used to make the request
params (Hash) —
query parameters merged over the default parameters

Returns:

(User) —
the user

Raises:

(ArgumentError) —
if the value is not a username
(MissingResource) —
if the user was not found, whether the API answers 200 with no data or a 404 that reports the user as not found
(X::NotFound) —
if the API answers any other 404, such as one from a client pointed at the wrong host or API version

.hydrate_all(resources, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ `Array<Resource>` Originally defined in module Resources::BatchFinders

Replace the resources that are not hydrated with the full resources

A resource that hydrate would look up is looked up, which is a stub and also a resource a response included without every field, so what comes back is hydrated throughout. A resource that was not found is dropped, as is nil, which a reference to no resource reads as, such as the author of a post whose response named none, and a hydrated resource is kept as it is, so resources that are all hydrated need no lookup. What was found is stored in each original, so hydrating one of them afterwards costs no request, unless params override a default field or expansion parameter: what such a lookup found is not the full resource, so it is returned without being stored, and hydrating an original fetches the full resource. A resource that holds what hydrate returns, because hydrate or an earlier hydrate_all stored it, is replaced with that, and looked up again by no request, since the API bills each resource a lookup returns.

Examples:

Look up every field of the authors of posts, the ones a search included among them

X::User.hydrate_all(posts.map(&:author), client: client)

Expand only the authors a search did not include, which the API bills for alone

X::User.hydrate_all(posts.filter_map(&:author).select(&:stub?), client: client)

Parameters:

resources (Array<Resource, nil>) —
the resources, some of which may not be hydrated, and some nil
client (Object) —
the client used to make the requests
concurrency (Integer) (defaults to: DEFAULT_CONCURRENCY) —
the number of batch lookups made at once, four by default, which must be at least one
params (Hash) —
query parameters merged over the default parameters; one that overrides a default field or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest

Yield Parameters:

problem (Problem) —
each problem the API reported, such as a resource that was not found

Returns:

(Array<Resource>) —
the resources, in order, with the ones that were not hydrated replaced, frozen

Raises:

(ArgumentError) —
if the concurrency is less than one
(ArgumentError) —
if a resource is not of this class, which a lookup of its identifier would find another resource for, before a request

.search(query, client:, **params) ⇒ `Cursor`

Search users

Examples:

Print the users matching a query

X::User.search("ruby", client: client).each { |user| puts user.username }

Parameters:

query (String) —
the search query
client (Object) —
the client used to make the requests
params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the matching users



95
96
97

# File 'x-resources/lib/x/resources/user.rb', line 95

def search(query, client:, **params)
  Cursor.__send__(:build, self, "users/search", client:, params: {query:, max_results: MAX_SEARCH_RESULTS}.merge(params), token_param: "next_token")
end

Instance Method Details

#affiliated_with ⇒ `Array<User>`

The accounts this account is affiliated with, such as its organization

They come from the includes, or as stubs holding their identifiers. They point the other way from affiliates, the accounts affiliated with this one.

Examples:

Get the username of the affiliated organization

user.affiliated_with.first&.hydrate&.username

Returns:

(Array<User>) —
the accounts it is affiliated with, empty if there are none

465	# File 'x-resources/lib/x/resources/user.rb', line 465 references :affiliated_with, :User, key: %w[affiliation user_id]

#affiliates(**params) ⇒ `Cursor` Originally defined in module Resources::UserCollections

The users affiliated with this user, such as the people of an organization

They are the accounts whose affiliation names this user, which affiliated_with reads of each of them, so they point the other way from the affiliated_with of this user.

Examples:

Print the users affiliated with an organization

client.find_user!("X").affiliates.each { |user| puts user.username }

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the users affiliated with this one

#blocking(**params) ⇒ `Cursor` Originally defined in module Resources::UserCollections

The users this user blocks, which must be the authenticated user

Examples:

Print every blocked user

client.current_user!.blocking.each { |user| puts user.username }

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the blocked users

#bookmark_folders(**params) ⇒ `Cursor` Originally defined in module Resources::UserCollections

The bookmark folders of the authenticated user

Examples:

Print the names of the bookmark folders

client.current_user!.bookmark_folders.each { |folder| puts folder.name }

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the folders

#bookmarks(folder: nil, **params) ⇒ `Cursor` Originally defined in module Resources::UserCollections

The posts bookmarked by the authenticated user, or those of one of their folders

The API gives the posts of a folder by their identifiers alone, and takes no fields for them, so they are stubs, which hydrate together, a lookup's worth at a time, as the stubs of any cursor do.

The bookmark endpoints take only the authentication of a user, OAuth 2.0 user context or OAuth 1.0a, so an app-only client is refused them; only bookmarking and unbookmarking a post refuse OAuth 1.0a too.

Examples:

Print the bookmarked posts

client.current_user!.bookmarks.each { |post| puts post.text }

Print the posts of the first bookmark folder

user = client.current_user!
if (folder = user.bookmark_folders.first)
  posts = user.bookmarks(folder:).to_a
  X::Post.hydrate_all(posts, client: client).each { |post| puts post.text }
end

Parameters:

folder (BookmarkFolder, String, Integer, nil) (defaults to: nil) —
the folder or its identifier, or nil for every bookmark
params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the bookmarked posts

Raises:

(ArgumentError) —
if the folder is not a folder or the identifier of one, before a request

#followed_lists(**params) ⇒ `Cursor` Originally defined in module Resources::UserCollections

The lists this user follows

Examples:

Print the followed lists

user.followed_lists.each { |list| puts list.name }

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the followed lists

#followers(**params) ⇒ `Cursor` Originally defined in module Resources::UserCollections

The users following this user

Examples:

Print every follower

user.followers.each { |follower| puts follower.username }

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the followers

#following(**params) ⇒ `Cursor` Originally defined in module Resources::UserCollections

The users this user follows

Examples:

Count the followed users

user.following.count

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the followed users

#follows?(user, max_pages: nil) ⇒ `Boolean` Originally defined in module Resources::Relationships

Check whether this user follows a user

When either user is the authenticated user, one lookup of the other's connection_status answers. Otherwise the users this user follows are scanned until one matches, up to 1,000 a page, and the API bills every user returned, so checking an account that follows thousands can cost dollars, and max_pages limits the pages the scan reads, raising PageLimitReached rather than read past them. A client that authenticates as the app alone has no authenticated user, which the API refuses to look up, so it scans. Any other failure to look the authenticated user up raises, rather than scan every user this one follows.

Examples:

Check whether the authenticated user follows someone, in one lookup

client.current_user!.follows?(other)

Scan no more than five pages of the users another user follows

X::User.find("jack", client: client).follows?(other, max_pages: 5)

Parameters:

user (User, String, Integer) —
the user or their identifier
max_pages (Integer, nil) (defaults to: nil) —
the most pages of followed users to scan, or nil for no limit

Returns:

(Boolean) —
true if this user follows the user

Raises:

(ArgumentError) —
if max_pages is neither an Integer of at least 1 nor nil, before a request
(PageLimitReached) —
if the scan reads max_pages pages without the user, and the API names another

#home_timeline(**params) ⇒ `Cursor` Originally defined in module Resources::UserCollections

The home timeline of this user, which must be the authenticated user

Examples:

Print the home timeline

client.current_user!.home_timeline.first(10).each { |post| puts post.text }

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the posts by the users this user follows, newest first

#identity_verified? ⇒ `Boolean`

Check whether the account's identity is verified

Examples:

Check whether a user's identity is verified

user.identity_verified?

Returns:

(Boolean) —
true if the identity is verified

# File 'x-resources/lib/x/resources/user.rb', line 229

#liked_posts(**params) ⇒ `Cursor` Also known as: liked_tweets Originally defined in module Resources::UserCollections

The posts liked by this user

Examples:

Print the most recently liked posts

user.liked_posts.first(10).each { |post| puts post.text }

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the liked posts

#list_memberships(**params) ⇒ `Cursor` Originally defined in module Resources::UserCollections

The lists this user is a member of

Examples:

Print the list memberships

user.list_memberships.each { |list| puts list.name }

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the list memberships

#mentions(**params) ⇒ `Cursor` Originally defined in module Resources::UserCollections

The posts mentioning this user

Examples:

Print the most recent mentions

user.mentions.first(10).each { |post| puts post.text }

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the mentions

#most_recent_post ⇒ `Post`^? Also known as: most_recent_tweet

The most recent post, from the includes or as a stub holding only its identifier

Examples:

Get the most recent post

user.most_recent_post

Returns:

(Post, nil) —
the most recent post

454	# File 'x-resources/lib/x/resources/user.rb', line 454 reference :most_recent_post, :Post, key: %w[most_recent_post_id], tweet_key: %w[most_recent_tweet_id]

#muting(**params) ⇒ `Cursor` Originally defined in module Resources::UserCollections

The users this user mutes, which must be the authenticated user

Examples:

Print every muted user

client.current_user!.muting.each { |user| puts user.username }

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the muted users

#owned_lists(**params) ⇒ `Cursor` Originally defined in module Resources::UserCollections

The lists owned by this user

Examples:

Print the owned lists

user.owned_lists.each { |list| puts list.name }

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the owned lists

#parody? ⇒ `Boolean`

Check whether the account labels itself a parody

Examples:

Leave out the parody accounts

users.reject(&:parody?)

Returns:

(Boolean) —
true if the account is labelled a parody

# File 'x-resources/lib/x/resources/user.rb', line 214

#permalink ⇒ `String`

The permalink of the profile, by username when known and by identifier otherwise

It is the address of the profile on x.com, not the website the profile links to, which #url reads.

Examples:

Get the permalink

user.permalink # => "https://x.com/sferik"

Returns:

(String) —
the x.com address of the profile

Raises:

(InvalidAttribute) —
if the response holds the username as something other than a String

488	# File 'x-resources/lib/x/resources/user.rb', line 488 def permalink = "https://x.com/#{Shape.read_string("#{self.class}#permalink", username) \|\| "i/user/#{id}"}"

#pinned_lists(**params) ⇒ `Cursor` Originally defined in module Resources::UserCollections

The lists this user has pinned

The API returns them in one response, without pages.

Examples:

Print the pinned lists

client.current_user!.pinned_lists.each { |list| puts list.name }

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the pinned lists

#pinned_post ⇒ `Post`^? Also known as: pinned_tweet

The pinned post, from the includes or as a stub holding only its identifier

Examples:

Get the pinned post

user.pinned_post

Returns:

(Post, nil) —
the pinned post

446	# File 'x-resources/lib/x/resources/user.rb', line 446 reference :pinned_post, :Post, key: %w[pinned_post_id], tweet_key: %w[pinned_tweet_id]

#posts(**params) ⇒ `Cursor` Also known as: tweets Originally defined in module Resources::UserCollections

The posts by this user

Examples:

Print the most recent posts

user.posts.first(10).each { |post| puts post.text }

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the posts

#protected? ⇒ `Boolean`

Check whether the account's posts are protected

Examples:

Check whether the account's posts are protected

user.protected?

Returns:

(Boolean) —
true if the posts are protected

# File 'x-resources/lib/x/resources/user.rb', line 176

#receives_your_dm? ⇒ `Boolean`

Check whether the authenticated user can send this user a direct message

A user whose response holds no receives_your_dm, such as one looked up without asking for it, is not known to receive one, and reads false.

Examples:

Message the users who can be sent one

users.select(&:receives_your_dm?).each { |user| client.create_dm(user, "Hello!") }

Returns:

(Boolean) —
true if the response says the authenticated user can send this user a direct message

# File 'x-resources/lib/x/resources/user.rb', line 306

#subscribes_to_you? ⇒ `Boolean`

Check whether this user subscribes to the authenticated user

A user whose response holds no subscribes_to_you, such as one looked up without asking for it, reads false.

Examples:

Find the subscribers among some users

users.select(&:subscribes_to_you?)

Returns:

(Boolean) —
true if the response says this user subscribes to the authenticated user

# File 'x-resources/lib/x/resources/user.rb', line 330

#uri ⇒ `URI::Generic`

The permalink of the user as a URI

It is the address of the profile on x.com, not the website the profile links to, which #url reads.

Examples:

Get the address as a URI

user.uri # => #<URI::HTTPS https://x.com/sferik>

Returns:

(URI::Generic) —
the x.com address of the user

Raises:

(InvalidAttribute) —
if the response holds the username as something other than a String

499	# File 'x-resources/lib/x/resources/user.rb', line 499 def uri = URI(permalink)

#verified? ⇒ `Boolean`

Check whether the account is verified

Examples:

Check whether the account is verified

user.verified?

Returns:

(Boolean) —
true if the account is verified

# File 'x-resources/lib/x/resources/user.rb', line 191

Class: X::User

Overview

Constant Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

Instance Attribute Details

#affiliated_with_ids ⇒ Array<Integer> (readonly)

Examples:

Get the identifiers of the accounts it is affiliated with

#affiliation ⇒ Hash? (readonly)

Examples:

Get the affiliated organization

#connection_status ⇒ Array<String>? (readonly)

Examples:

Check whether this user follows the authenticated user

#created_at ⇒ Time? (readonly)

Examples:

Get the creation time

#description ⇒ String? (readonly)

Examples:

Get the description

#entities ⇒ Hash? (readonly)

Examples:

Get the entities

#followers_count ⇒ Integer? (readonly)

Examples:

Get the follower count

#following_count ⇒ Integer? (readonly)

Examples:

Get the following count

#identity_verified ⇒ Boolean? (readonly)

Examples:

Check whether a user's identity is verified

#like_count ⇒ Integer? (readonly)

Examples:

Get the like count

#listed_count ⇒ Integer? (readonly)

Examples:

Get the listed count

#location ⇒ String? (readonly)

Examples:

Get the location

#media_count ⇒ Integer? (readonly)

Examples:

Get the media count

#most_recent_post_id ⇒ Integer? (readonly) Also known as: most_recent_tweet_id

Examples:

Get the most recent post identifier

#name ⇒ String? (readonly)

Examples:

Get the name

#parody ⇒ Boolean? (readonly)

Examples:

Check whether a user is a parody account

#pinned_post_id ⇒ Integer? (readonly) Also known as: pinned_tweet_id

Examples:

Get the pinned post identifier

#post_count ⇒ Integer? (readonly) Also known as: tweet_count

Examples:

Get the post count

#profile_banner_url ⇒ String? (readonly)

Examples:

Get the profile banner URL

#profile_image_url ⇒ String? (readonly)

Examples:

Get the profile image URL

#protected ⇒ Boolean? (readonly)

Examples:

Check whether a user is protected

#public_metrics ⇒ Hash? (readonly)

Examples:

Get the public metrics

#receives_your_dm ⇒ Boolean? (readonly)

Examples:

Check whether a user can be sent a direct message

#subscriber_count ⇒ Integer? (readonly)

Examples:

Get the subscriber count

#affiliated_with_ids ⇒ `Array<Integer>` (readonly)

#affiliation ⇒ `Hash`^? (readonly)

#connection_status ⇒ `Array<String>`^? (readonly)

#created_at ⇒ `Time`^? (readonly)

#description ⇒ `String`^? (readonly)

#entities ⇒ `Hash`^? (readonly)

#followers_count ⇒ `Integer`^? (readonly)

#following_count ⇒ `Integer`^? (readonly)

#identity_verified ⇒ `Boolean`^? (readonly)

#like_count ⇒ `Integer`^? (readonly)

#listed_count ⇒ `Integer`^? (readonly)

#location ⇒ `String`^? (readonly)

#media_count ⇒ `Integer`^? (readonly)

#most_recent_post_id ⇒ `Integer`^? (readonly) Also known as: most_recent_tweet_id

#name ⇒ `String`^? (readonly)

#parody ⇒ `Boolean`^? (readonly)

#pinned_post_id ⇒ `Integer`^? (readonly) Also known as: pinned_tweet_id

#post_count ⇒ `Integer`^? (readonly) Also known as: tweet_count

#profile_banner_url ⇒ `String`^? (readonly)

#profile_image_url ⇒ `String`^? (readonly)

#protected ⇒ `Boolean`^? (readonly)

#public_metrics ⇒ `Hash`^? (readonly)

#receives_your_dm ⇒ `Boolean`^? (readonly)

#subscriber_count ⇒ `Integer`^? (readonly)

#subscribes_to_you ⇒ `Boolean`^? (readonly)

#subscription ⇒ `Hash`^? (readonly)

#subscription_type ⇒ `String`^? (readonly)

#url ⇒ `String`^? (readonly)

#username ⇒ `String`^? (readonly)

#verified ⇒ `Boolean`^? (readonly)

#verified_followers_count ⇒ `Integer`^? (readonly)

#verified_type ⇒ `String`^? (readonly)

#withheld ⇒ `Hash`^? (readonly)

.current(client:, **params) {|problem| ... } ⇒ `User`^? Originally defined in module Resources::UserFinders

.current!(client:, **params) ⇒ `User` Originally defined in module Resources::UserFinders

.default_params ⇒ `Hash{String => Array<String>}`

.find(id_or_username, client:, **params) {|problem| ... } ⇒ `User`^? Originally defined in module Resources::UserFinders

.find!(id_or_username, client:, **params) ⇒ `User` Originally defined in module Resources::UserFinders

.find_all(ids_or_usernames, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ `Array<User>` Originally defined in module Resources::UserFinders

.find_all_by_id(ids, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ `Array<User>` Originally defined in module Resources::UserFinders

.find_all_by_username(usernames, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ `Array<User>` Originally defined in module Resources::UserFinders

.find_by_id(id, client:, **params) {|problem| ... } ⇒ `User`^? Originally defined in module Resources::UserFinders

.find_by_id!(id, client:, **params) ⇒ `User` Originally defined in module Resources::UserFinders

.find_by_username(username, client:, **params) {|problem| ... } ⇒ `User`^? Originally defined in module Resources::UserFinders

.find_by_username!(username, client:, **params) ⇒ `User` Originally defined in module Resources::UserFinders

.hydrate_all(resources, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ `Array<Resource>` Originally defined in module Resources::BatchFinders

.search(query, client:, **params) ⇒ `Cursor`