Class: X::List

Inherits:

Resource

Object
Resource
X::List

show all

Extended by:: Finders, Resources::Finders

Defined in:: x-resources/lib/x/resources/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

#created_at ⇒ Time^? readonly
The time when the list was created.
#description ⇒ String^? readonly
The description.
#follower_count ⇒ Integer^? readonly
The number of followers.
#member_count ⇒ Integer^? readonly
The number of members.
#name ⇒ String^? readonly
The name.
#owner_id ⇒ Integer^? readonly
The identifier of the owner.
#private ⇒ Boolean^? readonly
Whether the list is private.

Class Method Summary collapse

.create(name, client:, **params) ⇒ List
Create a list owned by the authenticated user.
.default_params ⇒ Hash{String => Array<String>}
The default query parameters requesting every list field and expansion.
.delete(list, client:) ⇒ Boolean
Delete a list as the authenticated user.
.find(id, client:, **params) {|problem| ... } ⇒ Resource^? extended from Resources::Finders
Look up a resource by identifier.
.find!(id, client:, **params) ⇒ Resource extended from Resources::Finders
Look up a resource by identifier, which must exist.
.update(list, client:, **params) ⇒ Boolean
Update the name, description, or privacy of a list as the authenticated user.

Instance Method Summary collapse

#add_member(user) ⇒ Boolean
Add a member to this list as the authenticated user.
#delete ⇒ Boolean
Delete this list as the authenticated user.
#followers(**params) ⇒ Cursor
The followers of this list.
#member?(user, max_pages: nil) ⇒ Boolean
Check whether a user is a member of this list, scanning until one matches.
#members(**params) ⇒ Cursor
The members of this list.
#owner ⇒ User^?
The owner, resolved from the includes or as a stub holding only its identifier.
#permalink ⇒ String
The permalink of the list.
#posts(**params) ⇒ Cursor (also: #tweets)
The posts by members of this list.
#private? ⇒ Boolean
Check whether the list is private.
#remove_member(user) ⇒ Boolean
Remove a member from this list as the authenticated user.
#update(**params) ⇒ Boolean
Update the name, description, or privacy of this list as the authenticated user.
#uri ⇒ URI::Generic
The permalink of the list as a URI.

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

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

#description ⇒ `String`^? (readonly)

The description

Examples:

Get the description

list.description

Returns:

(String, nil) —
the description

127	# File 'x-resources/lib/x/resources/list.rb', line 127 attribute :description

#follower_count ⇒ `Integer`^? (readonly)

The number of followers

Examples:

Get the follower count

list.follower_count

Returns:

(Integer, nil) —
the follower count

143	# File 'x-resources/lib/x/resources/list.rb', line 143 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

151	# File 'x-resources/lib/x/resources/list.rb', line 151 attribute :member_count, :integer

#name ⇒ `String`^? (readonly)

The name

Examples:

Get the name

list.name

Returns:

(String, nil) —
the name

119	# File 'x-resources/lib/x/resources/list.rb', line 119 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

159	# File 'x-resources/lib/x/resources/list.rb', line 159 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

167	# File 'x-resources/lib/x/resources/list.rb', line 167 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:

(MissingResource) —
if the API answers without the list

# File 'x-resources/lib/x/resources/list.rb', line 77

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



63
64
65

# File 'x-resources/lib/x/resources/list.rb', line 63

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

# File 'x-resources/lib/x/resources/list.rb', line 107

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

.find(id, client:, **params) {|problem| ... } ⇒ `Resource`^? Originally defined in module Resources::Finders

Look up a resource by identifier

Examples:

Look up a post by identifier

X::Post.find(1234567890, client: client)

Parameters:

id (String, Integer, Resource) —
the identifier, or a resource of this class
client (Object) —
the client used to make the request
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:

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

Raises:

(ArgumentError) —
if the identifier is not one, or is a resource of another class, before a request
(X::NotFound) —
if the API answers any other 404, such as one from a client pointed at the wrong host or API version

.find!(id, client:, **params) ⇒ `Resource` Originally defined in module Resources::Finders

Look up a resource by identifier, which must exist

The error it raises names the identifier looked up, whether the identifier or a resource was given. Its cause is the X::NotFound of a lookup the API answered with a 404 that reports the resource as not found.

Examples:

Look up a post by identifier

X::Post.find!(1234567890, client: client)

Parameters:

id (String, Integer, Resource) —
the identifier, or a resource of this class
client (Object) —
the client used to make the request
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

Returns:

(Resource) —
the resource

Raises:

(ArgumentError) —
if the identifier is not one, or is a resource of another class, before a request
(MissingResource) —
if the resource was not found, whether the API answers 200 with no data or a 404 that reports the resource 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

.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

# File 'x-resources/lib/x/resources/list.rb', line 92

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)
  Utils.written(body, "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

# File 'x-resources/lib/x/resources/list.rb', line 266

def add_member(user)
  body = client!.post("lists/#{id}/members", {user_id: Utils.id_of(user, User)}, **Utils::JSON_CLASSES)
  Utils.written(body, "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



303
304
305

# File 'x-resources/lib/x/resources/list.rb', line 303

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



202
203
204

# File 'x-resources/lib/x/resources/list.rb', line 202

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

# File 'x-resources/lib/x/resources/list.rb', line 236

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



191
192
193

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

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

182	# File 'x-resources/lib/x/resources/list.rb', line 182 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

249	# File 'x-resources/lib/x/resources/list.rb', line 249 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



213
214
215

# File 'x-resources/lib/x/resources/list.rb', line 213

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-resources/lib/x/resources/list.rb', line 169

#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

# File 'x-resources/lib/x/resources/list.rb', line 278

def remove_member(user)
  body = client!.delete("lists/#{id}/members/#{Utils.id_of(user, User)}", **Utils::JSON_CLASSES)
  Utils.written(body, "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



293
294
295

# File 'x-resources/lib/x/resources/list.rb', line 293

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

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

Class: X::List

Overview

Constant Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

Instance Attribute Details

#created_at ⇒ Time? (readonly)

Examples:

Get the creation time

#description ⇒ String? (readonly)

Examples:

Get the description

#follower_count ⇒ Integer? (readonly)

Examples:

Get the follower count

#member_count ⇒ Integer? (readonly)

Examples:

Get the member count

#name ⇒ String? (readonly)

Examples:

Get the name

#owner_id ⇒ Integer? (readonly)

Examples:

Get the owner identifier

#private ⇒ Boolean? (readonly)

Examples:

Check whether a list is private

Class Method Details

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

Examples:

Create a private list

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

Examples:

Get the default parameters

.delete(list, client:) ⇒ Boolean

Examples:

Delete a list

.find(id, client:, **params) {|problem| ... } ⇒ Resource? Originally defined in module Resources::Finders

Examples:

Look up a post by identifier

.find!(id, client:, **params) ⇒ Resource Originally defined in module Resources::Finders

Examples:

Look up a post by identifier

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

Examples:

Rename a list and make it private

Instance Method Details

#add_member(user) ⇒ Boolean

Examples:

Add a member

#delete ⇒ Boolean

Examples:

Delete a list

#followers(**params) ⇒ Cursor

Examples:

Print every follower

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

Examples:

Check whether a user is on a list

Read no more than ten pages to tell

#members(**params) ⇒ Cursor

Examples:

Print every member

#owner ⇒ User?

Examples:

Get the owner's username

#permalink ⇒ String

Examples:

Get the permalink

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

Examples:

Print the most recent posts

#private? ⇒ Boolean

Examples:

Check whether the list is private

#remove_member(user) ⇒ Boolean

Examples:

Remove a member

#created_at ⇒ `Time`^? (readonly)

#description ⇒ `String`^? (readonly)

#follower_count ⇒ `Integer`^? (readonly)

#member_count ⇒ `Integer`^? (readonly)

#name ⇒ `String`^? (readonly)

#owner_id ⇒ `Integer`^? (readonly)

#private ⇒ `Boolean`^? (readonly)

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

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

.delete(list, client:) ⇒ `Boolean`

.find(id, client:, **params) {|problem| ... } ⇒ `Resource`^? Originally defined in module Resources::Finders

.find!(id, client:, **params) ⇒ `Resource` Originally defined in module Resources::Finders

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

#add_member(user) ⇒ `Boolean`

#delete ⇒ `Boolean`

#followers(**params) ⇒ `Cursor`

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

#members(**params) ⇒ `Cursor`

#owner ⇒ `User`^?

#permalink ⇒ `String`

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

#private? ⇒ `Boolean`

#remove_member(user) ⇒ `Boolean`

#update(**params) ⇒ `Boolean`

#uri ⇒ `URI::Generic`