Class: X::List

Inherits:
Resource show all
Extended by:
Finders
Defined in:
x-objects/lib/x/objects/list.rb

Overview

A curated list of users

Constant Summary collapse

FIELDS =

Every public list field

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 follower_count id member_count name private].freeze
EXPANSIONS =

Every expansion available on list endpoints

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[owner_id].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

This class inherits a constructor from X::Resource

Instance Attribute Details

#created_at ⇒ Time? (readonly)

The time when the list was created

Examples:

Get the creation time

list.created_at

Returns:

  • (Time, nil) —

    the creation time



129
 
# File 'x-objects/lib/x/objects/list.rb', line 129

attribute :created_at, :time

#description ⇒ String? (readonly)

The description

Examples:

Get the description

list.description

Returns:

  • (String, nil) —

    the description



121
 
# File 'x-objects/lib/x/objects/list.rb', line 121

attribute :description

#follower_count ⇒ Integer? (readonly)

The number of followers

Examples:

Get the follower count

list.follower_count

Returns:

  • (Integer, nil) —

    the follower count



137
 
# File 'x-objects/lib/x/objects/list.rb', line 137

attribute :follower_count, :integer

#member_count ⇒ Integer? (readonly)

The number of members

Examples:

Get the member count

list.member_count

Returns:

  • (Integer, nil) —

    the member count



145
 
# File 'x-objects/lib/x/objects/list.rb', line 145

attribute :member_count, :integer

#name ⇒ String? (readonly)

The name

Examples:

Get the name

list.name

Returns:

  • (String, nil) —

    the name



113
 
# File 'x-objects/lib/x/objects/list.rb', line 113

attribute :name

#owner_id ⇒ Integer? (readonly)

The identifier of the owner

Examples:

Get the owner identifier

list.owner_id

Returns:

  • (Integer, nil) —

    the owner identifier



153
 
# File 'x-objects/lib/x/objects/list.rb', line 153

attribute :owner_id, :integer

#private ⇒ Boolean? (readonly)

Whether the list is private

Examples:

Check whether a list is private

list.private?

Returns:

  • (Boolean, nil) —

    true if the list is private



161
 
# File 'x-objects/lib/x/objects/list.rb', line 161

attribute :private, :boolean

Class Method Details

.create(name, client:, **params) ⇒ List

Create a list owned by the authenticated user

Examples:

Create a private list

X::List.create("Rubyists", client: client, description: "People who write Ruby", private: true)

Parameters:

  • name (String) —

    the name of the list

  • client (Object) —

    the client used to make the request

  • params (Hash) —

    additional request body fields: description and private

Returns:

  • (List) —

    the created list, holding only its identifier and name

Raises:



71
72
73
74
 
# File 'x-objects/lib/x/objects/list.rb', line 71

def create(name, client:, **params)
  body = client.post("lists", {name:, **params}, **Utils::JSON_CLASSES)
  created_from_response(body, "POST lists", client:)
end

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

The default query parameters requesting every list field and expansion

Examples:

Get the default parameters

X::List.default_params["list.fields"]

Returns:

  • (Hash{String => Array<String>}) —

    the default query parameters



57
58
59
 
# File 'x-objects/lib/x/objects/list.rb', line 57

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

.delete(list, client:) ⇒ Boolean

Delete a list as the authenticated user

Examples:

Delete a list

X::List.delete("1234567890", client: client)

Parameters:

  • list (List, String, Integer) —

    the list or its identifier

  • client (Object) —

    the client used to make the request

Returns:

  • (Boolean) —

    true if the list was deleted



101
102
103
104
 
# File 'x-objects/lib/x/objects/list.rb', line 101

def delete(list, client:)
  body = client.delete("lists/#{Utils.id_of(list, self)}", **Utils::JSON_CLASSES)
  body.to_h.dig("data", "deleted").eql?(true)
end

.update(list, client:, **params) ⇒ Boolean

Update the name, description, or privacy of a list as the authenticated user

Examples:

Rename a list and make it private

X::List.update("1234567890", client: client, name: "Rubyists", private: true)

Parameters:

  • list (List, String, Integer) —

    the list or its identifier

  • client (Object) —

    the client used to make the request

  • params (Hash) —

    the request body fields to change: name, description, and private

Returns:

  • (Boolean) —

    true if the list was updated

Raises:

  • (ArgumentError) —

    if no field is given to change, before any request



86
87
88
89
90
91
 
# File 'x-objects/lib/x/objects/list.rb', line 86

def update(list, client:, **params)
  raise ArgumentError, "a list update needs a field to change, such as name, description, or private" if params.empty?

  body = client.put("lists/#{Utils.id_of(list, self)}", params, **Utils::JSON_CLASSES)
  body.to_h.dig("data", "updated").eql?(true)
end

Instance Method Details

#add_member(user) ⇒ Boolean

Add a member to this list as the authenticated user

Examples:

Add a member

list.add_member(user)

Parameters:

  • user (User, String, Integer) —

    the user or their identifier

Returns:

  • (Boolean) —

    true if the user is now a member



260
261
262
263
 
# File 'x-objects/lib/x/objects/list.rb', line 260

def add_member(user)
  body = client!.post("lists/#{id}/members", {user_id: Utils.id_of(user, User)}, **Utils::JSON_CLASSES)
  body.to_h.dig("data", "is_member").eql?(true)
end

#delete ⇒ Boolean

Delete this list as the authenticated user

Examples:

Delete a list

list.delete

Returns:

  • (Boolean) —

    true if the list was deleted



297
298
299
 
# File 'x-objects/lib/x/objects/list.rb', line 297

def delete
  self.class.delete(self, client: client!)
end

#followers(**params) ⇒ Cursor

The followers of this list

Examples:

Print every follower

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

Parameters:

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (Cursor) —

    a cursor over the followers



196
197
198
 
# File 'x-objects/lib/x/objects/list.rb', line 196

def followers(**params)
  cursor(User, "lists/#{id}/followers", max_results: MAX_RESULTS, total: :follower_count, **params)
end

#member?(user, max_pages: nil) ⇒ Boolean

Check whether a user is a member of this list, scanning until one matches

The API has no lookup for a membership, so this scans either the members of the list or the lists the user is on. A private list scans its members, since a user's memberships leave private lists out. A public list scans the lists the user is on when there are fewer of them than members, as its member_count and the user's listed_count tell, looking up the list or the user first when either is a stub. The API bills every resource a scan returns, so max_pages limits the pages it reads, raising PageLimitReached rather than read past them.

Examples:

Check whether a user is on a list

list.member?(user)

Read no more than ten pages to tell

list.member?(user, max_pages: 10)

Parameters:

  • user (User, String, Integer) —

    the user or their identifier

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

    the most pages of members or memberships to read, or nil for no limit

Returns:

  • (Boolean) —

    true if the user is a member

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



230
231
232
233
234
235
 
# File 'x-objects/lib/x/objects/list.rb', line 230

def member?(user, max_pages: nil)
  member, max_pages = User.from_id(user), PageLimit.check!(max_pages)
  return PageLimit.scan(members.stubs, member, what: "List#member?", max_pages:) unless fewer_memberships?(user)

  PageLimit.scan(User.from_id(member, client: client!).list_memberships.stubs, self, what: "List#member?", max_pages:)
end

#members(**params) ⇒ Cursor

The members of this list

Examples:

Print every member

list.members.each { |user| puts user.username }

Parameters:

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (Cursor) —

    a cursor over the members



185
186
187
 
# File 'x-objects/lib/x/objects/list.rb', line 185

def members(**params)
  cursor(User, "lists/#{id}/members", max_results: MAX_RESULTS, total: :member_count, **params)
end

#owner ⇒ User?

The owner, resolved from the includes or as a stub holding only its identifier

Examples:

Get the owner's username

list.owner.username

Returns:

  • (User, nil) —

    the owner



176
 
# File 'x-objects/lib/x/objects/list.rb', line 176

reference :owner, :User, key: %w[owner_id]

#permalink ⇒ String

The permalink of the list

Examples:

Get the permalink

list.permalink # => "https://x.com/i/lists/1234567890"

Returns:

  • (String) —

    the x.com address of the list



243
 
# File 'x-objects/lib/x/objects/list.rb', line 243

def permalink = "https://x.com/i/lists/#{id}"

#posts(**params) ⇒ Cursor Also known as: tweets

The posts by members of this list

Examples:

Print the most recent posts

list.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



207
208
209
 
# File 'x-objects/lib/x/objects/list.rb', line 207

def posts(**params)
  cursor(Post, "lists/#{id}/tweets", max_results: MAX_RESULTS, **params)
end

#private? ⇒ Boolean

Check whether the list is private

Examples:

Check whether the list is private

list.private?

Returns:

  • (Boolean) —

    true if the list is private




# File 'x-objects/lib/x/objects/list.rb', line 163

#remove_member(user) ⇒ Boolean

Remove a member from this list as the authenticated user

Examples:

Remove a member

list.remove_member(user)

Parameters:

  • user (User, String, Integer) —

    the user or their identifier

Returns:

  • (Boolean) —

    true if the user is no longer a member



272
273
274
275
 
# File 'x-objects/lib/x/objects/list.rb', line 272

def remove_member(user)
  body = client!.delete("lists/#{id}/members/#{Utils.id_of(user, User)}", **Utils::JSON_CLASSES)
  body.to_h.dig("data", "is_member").eql?(false)
end

#update(**params) ⇒ Boolean

Update the name, description, or privacy of this list as the authenticated user

The list keeps the attributes it was built with, so refresh it to read the new ones.

Examples:

Change the description of a list

list.update(description: "People who write Ruby")

Parameters:

  • params (Hash) —

    the request body fields to change: name, description, and private

Returns:

  • (Boolean) —

    true if the list was updated

Raises:

  • (ArgumentError) —

    if no field is given to change, before any request



287
288
289
 
# File 'x-objects/lib/x/objects/list.rb', line 287

def update(**params)
  self.class.update(self, client: client!, **params)
end

#uri ⇒ URI::Generic

The permalink of the list as a URI

Examples:

Get the address as a URI

list.uri # => #<URI::HTTPS https://x.com/i/lists/1234567890>

Returns:

  • (URI::Generic) —

    the x.com address of the list



251
 
# File 'x-objects/lib/x/objects/list.rb', line 251

def uri = URI(permalink)