Module: X::Objects::Lookups::Users

Included in:
API
Defined in:
x-objects/lib/x/objects/lookups/users.rb

Overview

Look up and search users, and the authenticated user, 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 collapse

Instance Method Details

#current_user(**params) {|problem| ... } ⇒ User?

Look up the authenticated user

Each call looks the user up, as X::User.current does, so its counts and profile are as they are now. Keep the user it returns to read them again without a request.

Examples:

Print the name of the authenticated user

puts client.current_user&.name

Parameters:

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported

Returns:

  • (User, nil) —

    the authenticated user, or nil if the API returns none



173
174
175
 
# File 'x-objects/lib/x/objects/lookups/users.rb', line 173

def current_user(**params, &)
  User.current(client: self, **params, &)&.tap { |user| Utils.remember_user_id(self, user.id) }
end

#current_user!(**params) ⇒ User

Look up the authenticated user, who must be found

Each call looks the user up, as X::User.current! does, so its counts and profile are as they are now. Keep the user it returns to read them again without a request.

Examples:

Print the home timeline of the authenticated user

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

Parameters:

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (User) —

    the authenticated user

Raises:



188
189
190
 
# File 'x-objects/lib/x/objects/lookups/users.rb', line 188

def current_user!(**params)
  User.current!(client: self, **params).tap { |user| Utils.remember_user_id(self, user.id) }
end

#current_user_id ⇒ Integer

The identifier of the authenticated user, from an OAuth 1.0a token if possible

An OAuth 1.0a access token begins with the identifier of its user, so a client that holds one needs no lookup. Any other client looks the user up the first time, unless current_user or current_user! already has, and keeps the identifier, which never changes, for as long as it holds the same authenticator, since a client whose credentials change authenticates as someone else. A frozen client keeps nothing, and looks the user up each time.

Examples:

Get the identifier of the authenticated user

client.current_user_id # => 7505382

Returns:

  • (Integer) —

    the identifier

Raises:



205
 
# File 'x-objects/lib/x/objects/lookups/users.rb', line 205

def current_user_id = Utils.authenticated_user_id(self) || Utils.remembered_user_id(self) || current_user!.id

#find_all_users(ids_or_usernames, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<User>

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

Examples:

Look up many users by username

client.find_all_users(["sferik", "gem"])

Look up many users one batch at a time

client.find_all_users(ids, concurrency: 1)

Parameters:

  • ids_or_usernames (Array<Integer, User, String>) —

    identifiers or users, or usernames

  • 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 users, 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<User>) —

    the users that were found

Raises:

  • (ArgumentError) —

    if the concurrency is less than one



121
122
123
 
# File 'x-objects/lib/x/objects/lookups/users.rb', line 121

def find_all_users(ids_or_usernames, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params, &)
  User.find_all(ids_or_usernames, client: self, concurrency:, **params, &)
end

#find_all_users_by_id(ids, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<User>

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_users would take them for usernames.

Examples:

Look up many users by identifier, read as Strings

client.find_all_users_by_id(ENV.fetch("USER_IDS").split(","))

Parameters:

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

    the identifiers, or users

  • concurrency (Integer) (defaults to: BatchFinders::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

Raises:

  • (ArgumentError) —

    if a value is not an identifier, or if the concurrency is less than one



158
159
160
 
# File 'x-objects/lib/x/objects/lookups/users.rb', line 158

def find_all_users_by_id(ids, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params, &)
  User.find_all_by_id(ids, client: self, concurrency:, **params, &)
end

#find_all_users_by_username(usernames, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<User>

Look up many users by username, in parallel batches

It looks every value up as a username, Strings of digits as the accounts whose handles are those numbers, as find_all_users looks up any String, so code that reads values from elsewhere says which it means, as find_all_users_by_id does.

Examples:

Look up many users by username

client.find_all_users_by_username(["sferik", "1234567890"])

Parameters:

  • usernames (Array<String>) —

    the usernames, with or without leading at signs

  • concurrency (Integer) (defaults to: BatchFinders::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

Raises:

  • (ArgumentError) —

    if a value is not a username, or if the concurrency is less than one



140
141
142
 
# File 'x-objects/lib/x/objects/lookups/users.rb', line 140

def find_all_users_by_username(usernames, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params, &)
  User.find_all_by_username(usernames, client: self, concurrency:, **params, &)
end

#find_user(id_or_username, **params) {|problem| ... } ⇒ User?

Look up a user by identifier or username

Examples:

Look up a user by username

client.find_user("sferik")

Look up a user by identifier

client.find_user(7505382)

Parameters:

  • id_or_username (Integer, User, String) —

    an identifier or a user, or a username

  • 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:

  • (User, nil) —

    the user or nil if the user was not found



27
28
29
 
# File 'x-objects/lib/x/objects/lookups/users.rb', line 27

def find_user(id_or_username, **params, &)
  User.find(id_or_username, client: self, **params, &)
end

#find_user!(id_or_username, **params) ⇒ User

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

Examples:

Look up a user by username

client.find_user!("sferik")

Parameters:

  • id_or_username (Integer, User, String) —

    an identifier or a user, or a username

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (User) —

    the user

Raises:



40
41
42
 
# File 'x-objects/lib/x/objects/lookups/users.rb', line 40

def find_user!(id_or_username, **params)
  User.find!(id_or_username, client: self, **params)
end

#find_user_by_id(id, **params) {|problem| ... } ⇒ User?

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_user would take it for a username.

Examples:

Look up a user by an identifier read as a String

client.find_user_by_id(ENV.fetch("USER_ID"))

Parameters:

  • id (String, Integer, User) —

    the identifier, or a user

  • 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:

  • (User, nil) —

    the user or nil if the user was not found

Raises:

  • (ArgumentError) —

    if the value is not an identifier



89
90
91
 
# File 'x-objects/lib/x/objects/lookups/users.rb', line 89

def find_user_by_id(id, **params, &)
  User.find_by_id(id, client: self, **params, &)
end

#find_user_by_id!(id, **params) ⇒ User

Look up a user by identifier, which must exist

Examples:

Look up a user by an identifier read as a String

client.find_user_by_id!("7505382")

Parameters:

  • id (String, Integer, User) —

    the identifier, or a user

  • 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



103
104
105
 
# File 'x-objects/lib/x/objects/lookups/users.rb', line 103

def find_user_by_id!(id, **params)
  User.find_by_id!(id, client: self, **params)
end

#find_user_by_username(username, **params) {|problem| ... } ⇒ User?

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_user looks up any String, so code that reads a value from elsewhere says which it means, as find_user_by_id does.

Examples:

Look up a user whose username is a number

client.find_user_by_username("1234567890")

Parameters:

  • username (String) —

    the username, with or without a leading at sign

  • 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:

  • (User, nil) —

    the user or nil if the user was not found

Raises:

  • (ArgumentError) —

    if the value is not a username



58
59
60
 
# File 'x-objects/lib/x/objects/lookups/users.rb', line 58

def find_user_by_username(username, **params, &)
  User.find_by_username(username, client: self, **params, &)
end

#find_user_by_username!(username, **params) ⇒ User

Look up a user by username, which must exist

Examples:

Look up a user by username

client.find_user_by_username!("sferik")

Parameters:

  • username (String) —

    the username, with or without a leading at sign

  • 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



72
73
74
 
# File 'x-objects/lib/x/objects/lookups/users.rb', line 72

def find_user_by_username!(username, **params)
  User.find_by_username!(username, client: self, **params)
end

#search_users(query, **params) ⇒ Cursor

Search users

Examples:

Print the users matching a query

client.search_users("ruby").each { |user| puts user.username }

Parameters:

  • query (String) —

    the search query

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (Cursor) —

    a cursor over the matching users



215
216
217
 
# File 'x-objects/lib/x/objects/lookups/users.rb', line 215

def search_users(query, **params)
  User.search(query, client: self, **params)
end