Module: Twitter::REST::Lists

Includes:
Utils, Utils
Included in:
API
Defined in:
lib/twitter/rest/lists.rb

Overview

Methods for working with Twitter lists

Constant Summary collapse

MAX_USERS_PER_REQUEST =

Maximum users per request

100

Constants included from Utils

Utils::DEFAULT_CURSOR

Instance Method Summary collapse

Methods included from Utils

flat_pmap, pmap

Instance Method Details

#add_list_member(list, user_to_add, options = {}) ⇒ Twitter::List #add_list_member(user, list, user_to_add, options = {}) ⇒ Twitter::List

Note:

Lists are limited to having 5,000 members.

Adds a member to a list

Examples:

client.add_list_member('twitter-engineering', 'sferik')

Overloads:

  • #add_list_member(list, user_to_add, options = {}) ⇒ Twitter::List

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • user_to_add (Integer, String) —

      The user id or screen name to add to the list.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #add_list_member(user, list, user_to_add, options = {}) ⇒ Twitter::List

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • user_to_add (Integer, String) —

      The user id or screen name to add to the list.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



309
310
311
 
# File 'lib/twitter/rest/lists.rb', line 309

def add_list_member(*args)
  list_from_response_with_user("/1.1/lists/members/create.json", args)
end

#add_list_members(list, users, options = {}) ⇒ Twitter::List #add_list_members(user, list, users, options = {}) ⇒ Twitter::List

Note:

Lists are limited to having 5,000 members.

Adds specified members to a list

Examples:

client.add_list_members('twitter-engineering', ['sferik', 'pengwynn'])

Overloads:

  • #add_list_members(list, users, options = {}) ⇒ Twitter::List

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • users (Enumerable<Integer, String, Twitter::User>) —

      A collection of Twitter user IDs, screen names, or objects.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #add_list_members(user, list, users, options = {}) ⇒ Twitter::List

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • users (Enumerable<Integer, String, Twitter::User>) —

      A collection of Twitter user IDs, screen names, or objects.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



238
239
240
 
# File 'lib/twitter/rest/lists.rb', line 238

def add_list_members(*args)
  list_from_response_with_users("/1.1/lists/members/create_all.json", args)
end

#create_list(name, options = {}) ⇒ Twitter::List

Note:

Accounts are limited to 20 lists.

Creates a new list for the authenticated user

Examples:

client.create_list('twitter-engineering')

Parameters:

  • name (String) —

    The name for the list.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :mode (String) — default: 'public' —

    Whether your list is public or private. Values can be 'public' or 'private'.

  • :description (String) —

    The description to give the list.

Returns:

Raises:

See Also:



377
378
379
 
# File 'lib/twitter/rest/lists.rb', line 377

def create_list(name, options = {})
  perform_post_with_object("/1.1/lists/create.json", options.merge(name:), List)
end

#destroy_list(list, options = {}) ⇒ Twitter::List #destroy_list(user, list, options = {}) ⇒ Twitter::List

Note:

Must be owned by the authenticated user.

Deletes the specified list

Examples:

client.destroy_list('twitter-engineering')

Overloads:

  • #destroy_list(list, options = {}) ⇒ Twitter::List

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #destroy_list(user, list, options = {}) ⇒ Twitter::List

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



332
333
334
 
# File 'lib/twitter/rest/lists.rb', line 332

def destroy_list(*args)
  list_from_response(:post, "/1.1/lists/destroy.json", args)
end

#list(list, options = {}) ⇒ Twitter::List #list(user, list, options = {}) ⇒ Twitter::List

Note:

Private lists are only shown if the authenticated user owns them.

Shows the specified list

Examples:

client.list('twitter-engineering')

Overloads:

  • #list(list, options = {}) ⇒ Twitter::List

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #list(user, list, options = {}) ⇒ Twitter::List

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



400
401
402
 
# File 'lib/twitter/rest/lists.rb', line 400

def list(*args)
  list_from_response(:get, "/1.1/lists/show.json", args)
end

#list_member?(list, user_to_check, options = {}) ⇒ Boolean #list_member?(user, list, user_to_check, options = {}) ⇒ Boolean

Checks if a user is a member of the specified list

Examples:

client.list_member?('twitter-engineering', 'sferik')

Overloads:

  • #list_member?(list, user_to_check, options = {}) ⇒ Boolean

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • user_to_check (Integer, String) —

      The user ID or screen name of the list member.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #list_member?(user, list, user_to_check, options = {}) ⇒ Boolean

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • user_to_check (Integer, String) —

      The user ID or screen name of the list member.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

  • (Boolean) —

    true if user is a member of the specified list, otherwise false.

Raises:

See Also:



262
263
264
 
# File 'lib/twitter/rest/lists.rb', line 262

def list_member?(*args)
  list_user?(:get, "/1.1/lists/members/show.json", args)
end

#list_members(list, options = {}) ⇒ Twitter::Cursor #list_members(user, list, options = {}) ⇒ Twitter::Cursor

Returns the members of the specified list

Examples:

client.list_members('twitter-engineering')

Overloads:

  • #list_members(list, options = {}) ⇒ Twitter::Cursor

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #list_members(user, list, options = {}) ⇒ Twitter::Cursor

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



284
285
286
 
# File 'lib/twitter/rest/lists.rb', line 284

def list_members(*args)
  cursor_from_response_with_list("/1.1/lists/members.json", args)
end

#list_subscribe(list, options = {}) ⇒ Twitter::List #list_subscribe(user, list, options = {}) ⇒ Twitter::List

Makes the authenticated user follow the specified list

Examples:

client.list_subscribe('twitter-engineering')

Overloads:

  • #list_subscribe(list, options = {}) ⇒ Twitter::List

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #list_subscribe(user, list, options = {}) ⇒ Twitter::List

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



165
166
167
 
# File 'lib/twitter/rest/lists.rb', line 165

def list_subscribe(*args)
  list_from_response(:post, "/1.1/lists/subscribers/create.json", args)
end

#list_subscriber?(list, user_to_check, options = {}) ⇒ Boolean #list_subscriber?(user, list, user_to_check, options = {}) ⇒ Boolean

Checks if a user is a subscriber of the specified list

Examples:

client.list_subscriber?('twitter-engineering', 'sferik')

Overloads:

  • #list_subscriber?(list, user_to_check, options = {}) ⇒ Boolean

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • user_to_check (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #list_subscriber?(user, list, user_to_check, options = {}) ⇒ Boolean

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • user_to_check (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

  • (Boolean) —

    true if user is a subscriber of the specified list, otherwise false.

  • (Boolean) —

    true if user is a subscriber of the specified list, otherwise false.

Raises:

See Also:



190
191
192
 
# File 'lib/twitter/rest/lists.rb', line 190

def list_subscriber?(*args)
  list_user?(:get, "/1.1/lists/subscribers/show.json", args)
end

#list_subscribers(list, options = {}) ⇒ Twitter::Cursor #list_subscribers(user, list, options = {}) ⇒ Twitter::Cursor

Returns the subscribers of the specified list

Examples:

client.list_subscribers('twitter-engineering')

Overloads:

  • #list_subscribers(list, options = {}) ⇒ Twitter::Cursor

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #list_subscribers(user, list, options = {}) ⇒ Twitter::Cursor

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



143
144
145
 
# File 'lib/twitter/rest/lists.rb', line 143

def list_subscribers(*args)
  cursor_from_response_with_list("/1.1/lists/subscribers.json", args)
end

#list_timeline(list, options = {}) ⇒ Array<Twitter::Tweet> #list_timeline(user, list, options = {}) ⇒ Array<Twitter::Tweet>

Shows tweet timeline for members of the specified list

Examples:

client.list_timeline('twitter-engineering')

Overloads:

  • #list_timeline(list, options = {}) ⇒ Array<Twitter::Tweet>

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :since_id (Integer) —

      Returns results with an ID greater than (that is, more recent than) the specified ID.

    • :max_id (Integer) —

      Returns results with an ID less than (that is, older than) or equal to the specified ID.

    • :count (Integer) —

      The number of results to retrieve.

  • #list_timeline(user, list, options = {}) ⇒ Array<Twitter::Tweet>

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :since_id (Integer) —

      Returns results with an ID greater than (that is, more recent than) the specified ID.

    • :max_id (Integer) —

      Returns results with an ID less than (that is, older than) or equal to the specified ID.

    • :count (Integer) —

      The number of results to retrieve.

Returns:

Raises:

See Also:



71
72
73
74
75
76
 
# File 'lib/twitter/rest/lists.rb', line 71

def list_timeline(*args)
  arguments = Arguments.new(args)
  merge_list!(arguments.options, arguments.pop)
  merge_owner!(arguments.options, arguments.pop)
  perform_get_with_objects("/1.1/lists/statuses.json", arguments.options, Tweet)
end

#list_unsubscribe(list, options = {}) ⇒ Twitter::List #list_unsubscribe(user, list, options = {}) ⇒ Twitter::List

Unsubscribes the authenticated user from the specified list

Examples:

client.list_unsubscribe('twitter-engineering')

Overloads:

  • #list_unsubscribe(list, options = {}) ⇒ Twitter::List

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #list_unsubscribe(user, list, options = {}) ⇒ Twitter::List

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



212
213
214
 
# File 'lib/twitter/rest/lists.rb', line 212

def list_unsubscribe(*args)
  list_from_response(:post, "/1.1/lists/subscribers/destroy.json", args)
end

#list_update(list, options = {}) ⇒ Twitter::List #list_update(user, list, options = {}) ⇒ Twitter::List

Updates the specified list

Examples:

client.list_update('twitter-engineering', description: 'Tweeps')

Overloads:

  • #list_update(list, options = {}) ⇒ Twitter::List

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :mode (String) — default: 'public' —

      Whether your list is public or private. Values can be 'public' or 'private'.

    • :description (String) —

      The description to give the list.

  • #list_update(user, list, options = {}) ⇒ Twitter::List

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :mode (String) — default: 'public' —

      Whether your list is public or private. Values can be 'public' or 'private'.

    • :description (String) —

      The description to give the list.

Returns:

Raises:

See Also:



358
359
360
 
# File 'lib/twitter/rest/lists.rb', line 358

def list_update(*args)
  list_from_response(:post, "/1.1/lists/update.json", args)
end

#lists(options = {}) ⇒ Array<Twitter::List> #lists(user, options = {}) ⇒ Array<Twitter::List> Also known as: lists_subscribed_to

Returns all lists the user subscribes to, including their own

Examples:

client.lists

Overloads:

  • #lists(options = {}) ⇒ Array<Twitter::List>

    Parameters:

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :reverse (Boolean) —

      Set this to true if you would like owned lists to be returned first.

  • #lists(user, options = {}) ⇒ Array<Twitter::List>

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :reverse (Boolean) —

      Set this to true if you would like owned lists to be returned first.

Returns:

Raises:

See Also:



39
40
41
 
# File 'lib/twitter/rest/lists.rb', line 39

def lists(*args)
  objects_from_response_with_user(List, :get, "/1.1/lists/list.json", args)
end

#memberships(options = {}) ⇒ Twitter::Cursor #memberships(user, options = {}) ⇒ Twitter::Cursor

Lists the lists the specified user has been added to

Examples:

client.memberships

Overloads:

  • #memberships(options = {}) ⇒ Twitter::Cursor

    Parameters:

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :count (Integer) —

      The amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page.

    • :filter_to_owned_lists (Boolean, String, Integer) —

      When set to true, t or 1, will return just lists the authenticating user owns, and the user represented by user_id or screen_name is a member of.

  • #memberships(user, options = {}) ⇒ Twitter::Cursor

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :count (Integer) —

      The amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page.

    • :filter_to_owned_lists (Boolean, String, Integer) —

      When set to true, t or 1, will return just lists the authenticating user owns, and the user represented by user_id or screen_name is a member of.

Returns:

Raises:

See Also:



121
122
123
 
# File 'lib/twitter/rest/lists.rb', line 121

def memberships(*args)
  cursor_from_response_with_user(:lists, List, "/1.1/lists/memberships.json", args)
end

#owned_lists(options = {}) ⇒ Array<Twitter::List> #owned_lists(user, options = {}) ⇒ Array<Twitter::List>

Returns the lists owned by the specified Twitter user

Examples:

client.owned_lists

Overloads:

  • #owned_lists(options = {}) ⇒ Array<Twitter::List>

    Parameters:

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :count (Integer) —

      The amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page.

  • #owned_lists(user, options = {}) ⇒ Array<Twitter::List>

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :count (Integer) —

      The amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page.

Returns:

Raises:

See Also:



464
465
466
 
# File 'lib/twitter/rest/lists.rb', line 464

def owned_lists(*args)
  cursor_from_response_with_user(:lists, List, "/1.1/lists/ownerships.json", args)
end

#remove_list_member(list, user_to_remove, options = {}) ⇒ Twitter::List #remove_list_member(user, list, user_to_remove, options = {}) ⇒ Twitter::List

Removes the specified member from the list

Examples:

client.remove_list_member('twitter-engineering', 'sferik')

Overloads:

  • #remove_list_member(list, user_to_remove, options = {}) ⇒ Twitter::List

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • user_to_remove (Integer, String) —

      The user id or screen name of the list member to remove.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #remove_list_member(user, list, user_to_remove, options = {}) ⇒ Twitter::List

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • user_to_remove (Integer, String) —

      The user id or screen name of the list member to remove.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



98
99
100
 
# File 'lib/twitter/rest/lists.rb', line 98

def remove_list_member(*args)
  list_from_response_with_user("/1.1/lists/members/destroy.json", args)
end

#remove_list_members(list, users, options = {}) ⇒ Twitter::List #remove_list_members(user, list, users, options = {}) ⇒ Twitter::List

Removes specified members from the list

Examples:

client.remove_list_members('twitter-engineering', ['sferik'])

Overloads:

  • #remove_list_members(list, users, options = {}) ⇒ Twitter::List

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • users (Enumerable<Integer, String, Twitter::User>) —

      A collection of Twitter user IDs, screen names, or objects.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #remove_list_members(user, list, users, options = {}) ⇒ Twitter::List

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, URI, or object.

    • users (Enumerable<Integer, String, Twitter::User>) —

      A collection of Twitter user IDs, screen names, or objects.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



443
444
445
 
# File 'lib/twitter/rest/lists.rb', line 443

def remove_list_members(*args)
  list_from_response_with_users("/1.1/lists/members/destroy_all.json", args)
end

#subscriptions(options = {}) ⇒ Twitter::Cursor #subscriptions(user, options = {}) ⇒ Twitter::Cursor

Lists the lists the specified user follows

Examples:

client.subscriptions

Overloads:

  • #subscriptions(options = {}) ⇒ Twitter::Cursor

    Parameters:

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #subscriptions(user, options = {}) ⇒ Twitter::Cursor

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, URI, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



419
420
421
 
# File 'lib/twitter/rest/lists.rb', line 419

def subscriptions(*args)
  cursor_from_response_with_user(:lists, List, "/1.1/lists/subscriptions.json", args)
end