Module: Twitter::REST::Lists

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

Constant Summary

MAX_USERS_PER_REQUEST =
100
URI_SUBSTRING =
'://'

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.

Add a member to a list

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:

Rate Limited?:

  • No

Authentication:

  • Requires user context



269
270
271
# File 'lib/twitter/rest/lists.rb', line 269

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, and you are limited to adding up to 100 members to a list at a time with this method.

Adds specified members to a list

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:

Rate Limited?:

  • No

Authentication:

  • Requires user context



206
207
208
# File 'lib/twitter/rest/lists.rb', line 206

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

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:

Rate Limited?:

  • No

Authentication:

  • Requires user context



330
331
332
# File 'lib/twitter/rest/lists.rb', line 330

def create_list(name, options = {})
  perform_post_with_object('/1.1/lists/create.json', options.merge(:name => name), Twitter::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

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:

Rate Limited?:

  • No

Authentication:

  • Requires user context



290
291
292
# File 'lib/twitter/rest/lists.rb', line 290

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 will only be shown if the authenticated user owns the specified list.

Show the specified list

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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



351
352
353
# File 'lib/twitter/rest/lists.rb', line 351

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

Check if a user is a member of the specified list

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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



228
229
230
# File 'lib/twitter/rest/lists.rb', line 228

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

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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



247
248
249
# File 'lib/twitter/rest/lists.rb', line 247

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

Make the authenticated user follow the specified list

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:

Rate Limited?:

  • No

Authentication:

  • Requires user context



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

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

Check if a user is a subscriber of the specified list

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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



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

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

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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



123
124
125
# File 'lib/twitter/rest/lists.rb', line 123

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>

Show tweet timeline for members of the specified list

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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



59
60
61
62
63
64
# File 'lib/twitter/rest/lists.rb', line 59

def list_timeline(*args)
  arguments = Twitter::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, Twitter::Tweet)
end

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

Unsubscribes the authenticated user form the specified list

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:

Rate Limited?:

  • No

Authentication:

  • Requires user context



183
184
185
# File 'lib/twitter/rest/lists.rb', line 183

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

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:

Rate Limited?:

  • No

Authentication:

  • Requires user context



314
315
316
# File 'lib/twitter/rest/lists.rb', line 314

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 authenticating or specified user subscribes to, including their own

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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



33
34
35
# File 'lib/twitter/rest/lists.rb', line 33

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

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

List the lists the specified user has been added to

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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



104
105
106
# File 'lib/twitter/rest/lists.rb', line 104

def memberships(*args)
  cursor_from_response_with_user(:lists, Twitter::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

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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



407
408
409
# File 'lib/twitter/rest/lists.rb', line 407

def owned_lists(*args)
  cursor_from_response_with_user(:lists, Twitter::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

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:

Rate Limited?:

  • No

Authentication:

  • Requires user context



83
84
85
# File 'lib/twitter/rest/lists.rb', line 83

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

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:

Rate Limited?:

  • No

Authentication:

  • Requires user context



388
389
390
# File 'lib/twitter/rest/lists.rb', line 388

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

List the lists the specified user follows

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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



367
368
369
# File 'lib/twitter/rest/lists.rb', line 367

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