Module: Twitter::REST::Lists

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

Constant Summary collapse

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

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



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

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



327
328
329
 
# File 'lib/twitter/rest/lists.rb', line 327

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



288
289
290
 
# File 'lib/twitter/rest/lists.rb', line 288

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



347
348
349
 
# File 'lib/twitter/rest/lists.rb', line 347

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



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

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



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

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



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

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



311
312
313
 
# File 'lib/twitter/rest/lists.rb', line 311

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



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

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



402
403
404
 
# File 'lib/twitter/rest/lists.rb', line 402

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



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

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



384
385
386
 
# File 'lib/twitter/rest/lists.rb', line 384

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



363
364
365
 
# File 'lib/twitter/rest/lists.rb', line 363

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