twitter 4.3.0 → 4.4.0

data/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+## Contributing
+In the spirit of [free software][free-sw], **everyone** is encouraged to help
+improve this project.
+
+[free-sw]: http://www.fsf.org/licensing/essays/free-sw.html
+
+Here are some ways *you* can contribute:
+
+* by using alpha, beta, and prerelease versions
+* by reporting bugs
+* by suggesting new features
+* by writing or editing documentation
+* by writing specifications
+* by writing code (**no patch is too small**: fix typos, add comments, clean up
+inconsistent whitespace)
+* by refactoring code
+* by fixing [issues][]
+* by reviewing patches
+* [financially][pledgie]
+
+[issues]: https://github.com/sferik/twitter/issues
+[pledgie]: http://pledgie.com/campaigns/18388
+
+## Submitting an Issue
+We use the [GitHub issue tracker][issues] to track bugs and features. Before
+submitting a bug report or feature request, check to make sure it hasn't
+already been submitted. When submitting a bug report, please include a [Gist][]
+that includes a stack trace and any details that may be necessary to reproduce
+the bug, including your gem version, Ruby version, and operating system.
+Ideally, a bug report should include a pull request with failing specs.
+
+[gist]: https://gist.github.com/
+
+## Submitting a Pull Request
+1. [Fork the repository.][fork]
+2. [Create a topic branch.][branch]
+3. Add specs for your unimplemented feature or bug fix.
+4. Run `bundle exec rake spec`. If your specs pass, return to step 3.
+5. Implement your feature or bug fix.
+6. Run `bundle exec rake spec`. If your specs fail, return to step 5.
+7. Run `open coverage/index.html`. If your changes are not completely covered
+   by your tests, return to step 3.
+8. Add documentation for your feature or bug fix.
+9. Run `bundle exec rake yard`. If your changes are not 100% documented, go
+   back to step 8.
+10. Add, commit, and push your changes.
+11. [Submit a pull request.][pr]
+
+[fork]: http://help.github.com/fork-a-repo/
+[branch]: http://learn.github.com/p/branching.html
+[pr]: http://help.github.com/send-pull-requests/

data/README.md

@@ -302,6 +302,20 @@ Twitter.follow(213747670)
 Twitter.user("gem")
 Twitter.user(213747670)
 ```
+**Fetch a cursored list of followers with profile details (by screen name or user ID, or by implict authenticated user)**
+
+```ruby
+Twitter.followers("gem")
+Twitter.followers(213747670)
+Twitter.followers
+```
+**Fetch a cursored list of friends with profile details (by screen name or user ID, or by implict authenticated user)**
+
+```ruby
+Twitter.friends("gem")
+Twitter.friends(213747670)
+Twitter.friends
+```
 **Fetch the timeline of Tweets by a user**
 
 ```ruby
@@ -357,10 +371,11 @@ Here are some fun facts about this library:
 
 * It is implemented in just 2,000 lines of Ruby code
 * With over 4,000 lines of specs, the spec-to-code ratio is over 2:1
-* The spec suite contains over 600 examples and runs in under 2 seconds
+* The spec suite contains 700 examples and runs in about 2 seconds
 * It has 100% C0 code coverage (the tests execute every line of
   source code at least once)
-* It is comprehensive: you can request all documented Twitter REST API resources (over 100 resources)
+* It is comprehensive: you can request all documented Twitter REST API
+  resources (over 100 resources)
 * This gem works on every major Ruby implementation, including JRuby and
   Rubinius
 * The first version was released on November 26, 2006

data/lib/twitter/api/direct_messages.rb

@@ -92,7 +92,7 @@ module Twitter
       #   @param ids [Array<Integer>, Set<Integer>] An array of Tweet IDs.
       #   @param options [Hash] A customizable set of options.
       def direct_messages(*args)
-        options = args.extract_options!
+        options = extract_options!(args)
         if args.empty?
           direct_messages_received(options)
         else
@@ -118,10 +118,7 @@ module Twitter
       #   @param ids [Array<Integer>, Set<Integer>] An array of Tweet IDs.
       #   @param options [Hash] A customizable set of options.
       def direct_message_destroy(*args)
-        options = args.extract_options!
-        args.flatten.threaded_map do |id|
-          object_from_response(Twitter::DirectMessage, :post, "/1.1/direct_messages/destroy.json", options.merge(:id => id))
-        end
+        threaded_object_from_response(Twitter::DirectMessage, :post, "/1.1/direct_messages/destroy.json", args)
       end
 
       # Sends a new direct message to the specified user from the authenticating user
@@ -138,7 +135,7 @@ module Twitter
       #   Twitter.direct_message_create('sferik', "I'm sending you this message via @gem!")
       #   Twitter.direct_message_create(7505382, "I'm sending you this message via @gem!")  # Same as above
       def direct_message_create(user, text, options={})
-        options.merge_user!(user)
+        merge_user!(options, user)
         options[:text] = text
         object_from_response(Twitter::DirectMessage, :post, "/1.1/direct_messages/new.json", options)
       end

data/lib/twitter/api/favorites.rb

@@ -32,9 +32,9 @@ module Twitter
       #   @example Return the 20 most recent favorite Tweets for @sferik
       #     Twitter.favorites('sferik')
       def favorites(*args)
-        options = args.extract_options!
+        options = extract_options!(args)
         if user = args.pop
-          options.merge_user!(user)
+          merge_user!(options, user)
         end
         collection_from_response(Twitter::Tweet, :get, "/1.1/favorites/list.json", options)
       end
@@ -55,10 +55,7 @@ module Twitter
       #   @param ids [Array<Integer>, Set<Integer>] An array of Tweet IDs.
       #   @param options [Hash] A customizable set of options.
       def unfavorite(*args)
-        options = args.extract_options!
-        args.flatten.threaded_map do |id|
-          object_from_response(Twitter::Tweet, :post, "/1.1/favorites/destroy.json", options.merge(:id => id))
-        end
+        threaded_object_from_response(Twitter::Tweet, :post, "/1.1/favorites/destroy.json", args)
       end
       alias favorite_destroy unfavorite
       alias favourite_destroy unfavorite
@@ -79,7 +76,7 @@ module Twitter
       #   @param ids [Array<Integer>, Set<Integer>] An array of Tweet IDs.
       #   @param options [Hash] A customizable set of options.
       def favorite(*args)
-        options = args.extract_options!
+        options = extract_options!(args)
         args.flatten.threaded_map do |id|
           begin
             object_from_response(Twitter::Tweet, :post, "/1.1/favorites/create.json", options.merge(:id => id))
@@ -109,16 +106,12 @@ module Twitter
       #   @param ids [Array<Integer>, Set<Integer>] An array of Tweet IDs.
       #   @param options [Hash] A customizable set of options.
       def favorite!(*args)
-        options = args.extract_options!
+        options = extract_options!(args)
         args.flatten.threaded_map do |id|
           begin
             object_from_response(Twitter::Tweet, :post, "/1.1/favorites/create.json", options.merge(:id => id))
           rescue Twitter::Error::Forbidden => error
-            if error.message == "You have already favorited this status"
-              raise Twitter::Error::AlreadyFavorited.new("Tweet with the ID #{id} has already been favorited by the authenticated user.")
-            else
-              raise
-            end
+            handle_forbidden_error(Twitter::Error::AlreadyFavorited, error)
           end
         end
       end

data/lib/twitter/api/friends_and_followers.rb

@@ -76,8 +76,8 @@ module Twitter
       #   @param users [Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>] An array of Twitter user IDs, screen names, or objects.
       #   @param options [Hash] A customizable set of options.
       def friendships(*args)
-        options = args.extract_options!
-        options.merge_users!(Array(args))
+        options = extract_options!(args)
+        merge_users!(options, Array(args))
         collection_from_response(Twitter::User, :get, "/1.1/friendships/lookup.json", options)
       end
 
@@ -129,7 +129,7 @@ module Twitter
       #   @param options [Hash] A customizable set of options.
       #   @option options [Boolean] :follow (false) Enable notifications for the target user.
       def follow(*args)
-        options = args.extract_options!
+        options = extract_options!(args)
         # Twitter always turns on notifications if the "follow" option is present, even if it's set to false
         # so only send follow if it's true
         options[:follow] = true if !!options.delete(:follow)
@@ -159,13 +159,13 @@ module Twitter
       #   @param options [Hash] A customizable set of options.
       #   @option options [Boolean] :follow (false) Enable notifications for the target user.
       def follow!(*args)
-        options = args.extract_options!
+        options = extract_options!(args)
         # Twitter always turns on notifications if the "follow" option is present, even if it's set to false
         # so only send follow if it's true
         options[:follow] = true if !!options.delete(:follow)
         args.flatten.threaded_map do |user|
           begin
-            options.merge_user!(user)
+            merge_user!(options, user)
             object_from_response(Twitter::User, :post, "/1.1/friendships/create.json", options)
           rescue Twitter::Error::Forbidden
             # This error will be raised if the user doesn't have permission to
@@ -208,7 +208,7 @@ module Twitter
       # @example Enable rewteets and devise notifications for @sferik
       #   Twitter.friendship_update('sferik', :device => true, :retweets => true)
       def friendship_update(user, options={})
-        options.merge_user!(user)
+        merge_user!(options, user)
         object_from_response(Twitter::Relationship, :post, "/1.1/friendships/update.json", options)
       end
 
@@ -227,9 +227,9 @@ module Twitter
       #   Twitter.friendship('sferik', 14100886)   # Same as above
       #   Twitter.friendship(7505382, 14100886)    # Same as above
       def friendship(source, target, options={})
-        options.merge_user!(source, "source")
+        merge_user!(options, source, "source")
         options[:source_id] = options.delete(:source_user_id) unless options[:source_user_id].nil?
-        options.merge_user!(target, "target")
+        merge_user!(options, target, "target")
         options[:target_id] = options.delete(:target_user_id) unless options[:target_user_id].nil?
         object_from_response(Twitter::Relationship, :get, "/1.1/friendships/show.json", options)
       end
@@ -254,6 +254,74 @@ module Twitter
         friendship(source, target, options).source.following?
       end
 
+      # Returns a cursored collection of user objects for users following the specified user.
+      #
+      # @see https://dev.twitter.com/docs/api/1.1/get/followers/list
+      # @rate_limited Yes
+      # @authentication_required Requires user context
+      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @return [Twitter::Cursor]
+      # @overload friend_ids(options={})
+      #   Returns an array of numeric IDs for every user the authenticated user is following
+      #
+      #   @param options [Hash] A customizable set of options.
+      #   @option options [Integer] :cursor (-1) Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.
+      #   @option options [Boolean, String, Integer] :skip_status Do not include contributee's Tweets when set to true, 't' or 1.
+      #   @option options [Boolean, String, Integer] :include_user_entities The user entities node will be disincluded when set to false.
+      #   @example Return the authenticated user's friends' IDs
+      #     Twitter.friend_ids
+      # @overload friend_ids(user, options={})
+      #   Returns an array of numeric IDs for every user the specified user is following
+      #
+      #   @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
+      #   @param options [Hash] A customizable set of options.
+      #   @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
+      #   @option options [Boolean, String, Integer] :skip_status Do not include contributee's Tweets when set to true, 't' or 1.
+      #   @option options [Boolean, String, Integer] :include_user_entities The user entities node will be disincluded when set to false.
+      # @example Return the cursored collection of users following @sferik
+      #   Twitter.followers('sferik')
+      #   Twitter.followers(7505382)    # Same as above
+      def followers(*args)
+        options = extract_options!(args)
+        merge_user!(options, args.pop || screen_name)
+        merge_default_cursor!(options)
+        cursor_from_response(:users, Twitter::User, :get, "/1.1/followers/list.json", options)
+      end
+
+      # Returns a cursored collection of user objects for every user the specified user is following (otherwise known as their "friends").
+      #
+      # @see https://dev.twitter.com/docs/api/1.1/get/friendships/show
+      # @rate_limited Yes
+      # @authentication_required Requires user context
+      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @return [Twitter::Cursor]
+      # @overload friend_ids(options={})
+      #   Returns an array of numeric IDs for every user the authenticated user is following
+      #
+      #   @param options [Hash] A customizable set of options.
+      #   @option options [Integer] :cursor (-1) Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.
+      #   @option options [Boolean, String, Integer] :skip_status Do not include contributee's Tweets when set to true, 't' or 1.
+      #   @option options [Boolean, String, Integer] :include_user_entities The user entities node will be disincluded when set to false.
+      #   @example Return the authenticated user's friends' IDs
+      #     Twitter.friend_ids
+      # @overload friend_ids(user, options={})
+      #   Returns an array of numeric IDs for every user the specified user is following
+      #
+      #   @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
+      #   @param options [Hash] A customizable set of options.
+      #   @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
+      #   @option options [Boolean, String, Integer] :skip_status Do not include contributee's Tweets when set to true, 't' or 1.
+      #   @option options [Boolean, String, Integer] :include_user_entities The user entities node will be disincluded when set to false.
+      # @example Return the cursored collection of users @sferik is following
+      #   Twitter.friends('sferik')
+      #   Twitter.friends(7505382)    # Same as above
+      def friends(*args)
+        options = extract_options!(args)
+        merge_user!(options, args.pop || screen_name)
+        merge_default_cursor!(options)
+        cursor_from_response(:users, Twitter::User, :get, "/1.1/friends/list.json", options)
+      end
+      alias following friends
     end
   end
 end

data/lib/twitter/api/lists.rb

@@ -63,9 +63,9 @@ module Twitter
       #     Twitter.list_timeline(7505382, 'presidents')
       #     Twitter.list_timeline(7505382, 8863586)
       def list_timeline(*args)
-        options = args.extract_options!
-        options.merge_list!(args.pop)
-        options.merge_owner!(args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
+        options = extract_options!(args)
+        merge_list!(options, args.pop)
+        merge_owner!(options, args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
         collection_from_response(Twitter::Tweet, :get, "/1.1/lists/statuses.json", options)
       end
 
@@ -507,64 +507,93 @@ module Twitter
     private
 
       # @param request_method [Symbol]
-      # @param url [String]
+      # @param path [String]
       # @param args [Array]
       # @return [Array<Twitter::User>]
-      def list_from_response(request_method, url, args)
-        options = args.extract_options!
-        options.merge_list!(args.pop)
-        options.merge_owner!(args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
-        object_from_response(Twitter::List, request_method, url, options)
+      def list_from_response(request_method, path, args)
+        options = extract_options!(args)
+        merge_list!(options, args.pop)
+        merge_owner!(options, args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
+        object_from_response(Twitter::List, request_method, path, options)
       end
 
       # @param request_method [Symbol]
-      # @param url [String]
+      # @param path [String]
       # @param args [Array]
       # @return [Array<Twitter::List>]
-      def lists_from_response(request_method, url, args)
-        options = args.extract_options!
+      def lists_from_response(request_method, path, args)
+        options = extract_options!(args)
         merge_default_cursor!(options)
-        options.merge_user!(args.pop)
-        cursor_from_response(:lists, Twitter::List, request_method, url, options, calling_method)
+        merge_user!(options, args.pop)
+        cursor_from_response(:lists, Twitter::List, request_method, path, options, calling_method)
       end
 
-      def list_users(request_method, url, args)
-        options = args.extract_options!
+      def list_users(request_method, path, args)
+        options = extract_options!(args)
         merge_default_cursor!(options)
-        options.merge_list!(args.pop)
-        options.merge_owner!(args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
-        cursor_from_response(:users, Twitter::User, request_method, url, options, calling_method)
+        merge_list!(options, args.pop)
+        merge_owner!(options, args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
+        cursor_from_response(:users, Twitter::User, request_method, path, options, calling_method)
       end
 
-      def list_user?(request_method, url, args)
-        options = args.extract_options!
-        options.merge_user!(args.pop)
-        options.merge_list!(args.pop)
-        options.merge_owner!(args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
-        send(request_method.to_sym, url, options)
+      def list_user?(request_method, path, args)
+        options = extract_options!(args)
+        merge_user!(options, args.pop)
+        merge_list!(options, args.pop)
+        merge_owner!(options, args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
+        send(request_method.to_sym, path, options)
         true
       rescue Twitter::Error::NotFound, Twitter::Error::Forbidden
         false
       end
 
-      def list_modify_member(request_method, url, args)
-        options = args.extract_options!
-        options.merge_user!(args.pop)
-        options.merge_list!(args.pop)
-        options.merge_owner!(args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
-        object_from_response(Twitter::List, request_method, url, options)
+      def list_modify_member(request_method, path, args)
+        options = extract_options!(args)
+        merge_user!(options, args.pop)
+        merge_list!(options, args.pop)
+        merge_owner!(options, args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
+        object_from_response(Twitter::List, request_method, path, options)
       end
 
-      def list_modify_members(request_method, url, args)
-        options = args.extract_options!
+      def list_modify_members(request_method, path, args)
+        options = extract_options!(args)
         members = args.pop
-        options.merge_list!(args.pop)
-        options.merge_owner!(args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
+        merge_list!(options, args.pop)
+        merge_owner!(options, args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
         members.flatten.each_slice(MAX_USERS_PER_REQUEST).threaded_map do |users|
-          object_from_response(Twitter::List, request_method, url, options.merge_users(users))
+          object_from_response(Twitter::List, request_method, path, merge_users(options, users))
         end.last
       end
 
+      # Take a list and merge it into the hash with the correct key
+      #
+      # @param hash [Hash]
+      # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
+      # @return [Hash]
+      def merge_list!(hash, list)
+        case list
+        when Integer
+          hash[:list_id] = list
+        when String
+          hash[:slug] = list
+        when Twitter::List
+          hash[:list_id] = list.id
+          merge_owner!(hash, list.user)
+        end
+        hash
+      end
+
+      # Take an owner and merge it into the hash with the correct key
+      #
+      # @param hash [Hash]
+      # @param user[Integer, String, Twitter::User] A Twitter user ID, screen_name, or object.
+      # @return [Hash]
+      def merge_owner!(hash, user)
+        merge_user!(hash, user, "owner")
+        hash[:owner_id] = hash.delete(:owner_user_id) unless hash[:owner_user_id].nil?
+        hash
+      end
+
     end
   end
 end

data/lib/twitter/api/places_and_geo.rb

@@ -109,11 +109,11 @@ module Twitter
     private
 
       # @param request_method [Symbol]
-      # @param url [String]
+      # @param path [String]
       # @param options [Hash]
       # @return [Array]
-      def geo_collection_from_response(request_method, url, params={})
-        collection_from_array(Twitter::Place, send(request_method.to_sym, url, params)[:body][:result][:places])
+      def geo_collection_from_response(request_method, path, params={})
+        collection_from_array(Twitter::Place, send(request_method.to_sym, path, params)[:body][:result][:places])
       end
 
     end