twitter 8.2.0 → 8.3.0

data/lib/twitter/rest/utils.rb

@@ -1,6 +1,6 @@
-require "addressable/uri"
 require "twitter/arguments"
 require "twitter/cursor"
+require "twitter/identity"
 require "twitter/rest/request"
 require "twitter/user"
 require "twitter/utils"
@@ -8,99 +8,145 @@ require "uri"
 
 module Twitter
   module REST
+    # Utility methods for Twitter REST API requests
     module Utils
       include Twitter::Utils
+
+      # The default cursor position for paginated requests
       DEFAULT_CURSOR = -1
 
-    private
+      private
 
       # Take a URI string or Twitter::Identity object and return its ID
       #
-      # @param object [Integer, String, URI, Twitter::Identity] An ID, URI, or object.
+      # @api private
+      # @param object [Integer, String, URI, Twitter::Identity] An ID, URI, or object
       # @return [Integer]
       def extract_id(object)
         case object
-        when ::Integer
+        when Integer
           object
-        when ::String
-          object.split("/").last.to_i
-        when URI, Addressable::URI
-          object.path.split("/").last.to_i
-        when Twitter::Identity
+        when String
+          Integer(object.split("/").last)
+        when URI
+          Integer(object.path.split("/").last) # steep:ignore NoMethod
+        when Identity
           object.id
         end
       end
 
+      # Perform a GET request
+      #
+      # @api private
       # @param path [String]
       # @param options [Hash]
+      # @return [Hash, Array]
       def perform_get(path, options = {})
         perform_request(:get, path, options)
       end
 
+      # Perform a POST request
+      #
+      # @api private
       # @param path [String]
       # @param options [Hash]
+      # @return [Hash, Array]
       def perform_post(path, options = {})
         perform_request(:post, path, options)
       end
 
+      # Perform an HTTP request
+      #
+      # @api private
       # @param request_method [Symbol]
       # @param path [String]
       # @param options [Hash]
+      # @param params [Hash]
+      # @return [Hash, Array]
       def perform_request(request_method, path, options = {}, params = nil)
-        Twitter::REST::Request.new(self, request_method, path, options, params).perform
+        Request.new(self, request_method, path, options, params).perform
       end
 
+      # Perform a GET request and return an object
+      #
+      # @api private
       # @param path [String]
       # @param options [Hash]
       # @param klass [Class]
+      # @return [Object]
       def perform_get_with_object(path, options, klass)
         perform_request_with_object(:get, path, options, klass)
       end
 
+      # Perform a POST request and return an object
+      #
+      # @api private
       # @param path [String]
       # @param options [Hash]
       # @param klass [Class]
+      # @return [Object]
       def perform_post_with_object(path, options, klass)
         perform_request_with_object(:post, path, options, klass)
       end
 
+      # Perform a request and return an object
+      #
+      # @api private
       # @param request_method [Symbol]
       # @param path [String]
       # @param options [Hash]
       # @param klass [Class]
+      # @param params [Hash]
+      # @return [Object]
       def perform_request_with_object(request_method, path, options, klass, params = nil)
         response = perform_request(request_method, path, options, params)
-        klass.new(response)
+        klass.new(response) # steep:ignore UnexpectedPositionalArgument
       end
 
+      # Perform a GET request and return objects
+      #
+      # @api private
       # @param path [String]
       # @param options [Hash]
       # @param klass [Class]
+      # @return [Array]
       def perform_get_with_objects(path, options, klass)
         perform_request_with_objects(:get, path, options, klass)
       end
 
+      # Perform a POST request and return objects
+      #
+      # @api private
       # @param path [String]
       # @param options [Hash]
       # @param klass [Class]
+      # @return [Array]
       def perform_post_with_objects(path, options, klass)
         perform_request_with_objects(:post, path, options, klass)
       end
 
+      # Perform a request and return objects
+      #
+      # @api private
       # @param request_method [Symbol]
       # @param path [String]
       # @param options [Hash]
       # @param klass [Class]
+      # @return [Array]
       def perform_request_with_objects(request_method, path, options, klass)
         perform_request(request_method, path, options).collect do |element|
-          klass.new(element)
+          klass.new(element) # steep:ignore UnexpectedPositionalArgument
         end
       end
 
+      # Perform a GET request with cursor pagination
+      #
+      # @api private
       # @param path [String]
       # @param options [Hash]
       # @param collection_name [Symbol]
       # @param klass [Class]
+      # @return [Twitter::Cursor]
       def perform_get_with_cursor(path, options, collection_name, klass = nil)
         limit = options.delete(:limit)
         if options[:no_default_cursor]
@@ -109,58 +155,73 @@ module Twitter
           merge_default_cursor!(options)
         end
 
-        request = Twitter::REST::Request.new(self, :get, path, options)
-        Twitter::Cursor.new(collection_name.to_sym, klass, request, limit)
+        request = Request.new(self, :get, path, options)
+        Cursor.new(collection_name, klass, request, limit)
       end
 
+      # Perform parallel user requests
+      #
+      # @api private
       # @param request_method [Symbol]
       # @param path [String]
       # @param args [Array]
       # @return [Array<Twitter::User>]
       def parallel_users_from_response(request_method, path, args)
-        arguments = Twitter::Arguments.new(args)
+        arguments = Arguments.new(args)
         pmap(arguments) do |user|
-          perform_request_with_object(request_method, path, merge_user(arguments.options, user), Twitter::User)
+          perform_request_with_object(request_method, path, merge_user(arguments.options, user), User) # steep:ignore ArgumentTypeMismatch
         end
       end
 
+      # Get users from response
+      #
+      # @api private
       # @param request_method [Symbol]
       # @param path [String]
       # @param args [Array]
       # @return [Array<Twitter::User>]
       def users_from_response(request_method, path, args)
-        arguments = Twitter::Arguments.new(args)
-        merge_user!(arguments.options, arguments.pop || user_id) unless arguments.options[:user_id] || arguments.options[:screen_name]
-        perform_request_with_objects(request_method, path, arguments.options, Twitter::User)
+        arguments = Arguments.new(args)
+        merge_user!(arguments.options, arguments.pop || user_id) unless arguments.options.key?(:user_id) || arguments.options.key?(:screen_name)
+        perform_request_with_objects(request_method, path, arguments.options, User)
       end
 
+      # Get objects from response with user
+      #
+      # @api private
       # @param klass [Class]
       # @param request_method [Symbol]
       # @param path [String]
       # @param args [Array]
       # @return [Array]
       def objects_from_response_with_user(klass, request_method, path, args)
-        arguments = Twitter::Arguments.new(args)
+        arguments = Arguments.new(args)
         merge_user!(arguments.options, arguments.pop)
         perform_request_with_objects(request_method, path, arguments.options, klass)
       end
 
+      # Perform parallel object requests
+      #
+      # @api private
       # @param klass [Class]
       # @param request_method [Symbol]
       # @param path [String]
       # @param args [Array]
       # @return [Array]
       def parallel_objects_from_response(klass, request_method, path, args)
-        arguments = Twitter::Arguments.new(args)
+        arguments = Arguments.new(args)
         pmap(arguments) do |object|
           perform_request_with_object(request_method, path, arguments.options.merge(id: extract_id(object)), klass)
         end
       end
 
+      # Perform multiple requests for IDs
+      #
+      # @api private
       # @param request_method [Symbol]
       # @param path [String]
       # @param ids [Array]
-      # @return nil
+      # @return [nil]
       def perform_requests(request_method, path, ids)
         ids.each do |id|
           perform_request(request_method, path, id:)
@@ -168,33 +229,51 @@ module Twitter
         nil
       end
 
+      # Get cursor from response with user
+      #
+      # @api private
       # @param collection_name [Symbol]
       # @param klass [Class]
       # @param path [String]
       # @param args [Array]
       # @return [Twitter::Cursor]
       def cursor_from_response_with_user(collection_name, klass, path, args)
-        arguments = Twitter::Arguments.new(args)
-        merge_user!(arguments.options, arguments.pop || user_id) unless arguments.options[:user_id] || arguments.options[:screen_name]
+        arguments = Arguments.new(args)
+        merge_user!(arguments.options, arguments.pop || user_id) unless arguments.options.key?(:user_id) || arguments.options.key?(:screen_name)
         perform_get_with_cursor(path, arguments.options, collection_name, klass)
       end
 
+      # Get the current user's ID
+      #
+      # @api private
+      # @return [Integer]
       def user_id
-        @user_id ||= verify_credentials(skip_status: true).id
+        @user_id ||= verify_credentials(skip_status: true).id # steep:ignore NoMethod,UnknownInstanceVariable
       end
 
+      # Check if user_id is set
+      #
+      # @api private
+      # @return [Boolean]
       def user_id?
         instance_variable_defined?(:@user_id)
       end
 
+      # Merge default cursor into options
+      #
+      # @api private
+      # @param options [Hash]
+      # @return [void]
       def merge_default_cursor!(options)
         options[:cursor] = DEFAULT_CURSOR unless options[:cursor]
       end
 
       # Take a user and merge it into the hash with the correct key
       #
+      # @api private
       # @param hash [Hash]
-      # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
+      # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object
+      # @param prefix [String]
       # @return [Hash]
       def merge_user(hash, user, prefix = nil)
         merge_user!(hash.dup, user, prefix)
@@ -202,8 +281,10 @@ module Twitter
 
       # Take a user and merge it into the hash with the correct key
       #
+      # @api private
       # @param hash [Hash]
-      # @param user [Integer, String, URI, Twitter::User] A Twitter user ID, screen name, URI, or object.
+      # @param user [Integer, String, URI, Twitter::User] A Twitter user ID, screen name, URI, or object
+      # @param prefix [String]
       # @return [Hash]
       def merge_user!(hash, user, prefix = nil)
         case user
@@ -211,13 +292,21 @@ module Twitter
           set_compound_key("user_id", user, hash, prefix)
         when String
           set_compound_key("screen_name", user, hash, prefix)
-        when URI, Addressable::URI
-          set_compound_key("screen_name", user.path.split("/").last, hash, prefix)
-        when Twitter::User
+        when URI
+          set_compound_key("screen_name", user.path.split("/").last, hash, prefix) # steep:ignore NoMethod
+        when User
           set_compound_key("user_id", user.id, hash, prefix)
         end
       end
 
+      # Set a compound key in a hash
+      #
+      # @api private
+      # @param key [String]
+      # @param value [Object]
+      # @param hash [Hash]
+      # @param prefix [String]
+      # @return [Hash]
       def set_compound_key(key, value, hash, prefix = nil)
         compound_key = [prefix, key].compact.join("_").to_sym
         hash[compound_key] = value
@@ -226,8 +315,9 @@ module Twitter
 
       # Take a multiple users and merge them into the hash with the correct keys
       #
+      # @api private
       # @param hash [Hash]
-      # @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen_names, or objects.
+      # @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen_names, or objects
       # @return [Hash]
       def merge_users(hash, users)
         copy = hash.dup
@@ -237,24 +327,30 @@ module Twitter
 
       # Take a multiple users and merge them into the hash with the correct keys
       #
+      # @api private
       # @param hash [Hash]
-      # @param users [Enumerable<Integer, String, URI, Twitter::User>] A collection of Twitter user IDs, screen_names, URIs, or objects.
-      # @return [Hash]
+      # @param users [Enumerable<Integer, String, URI, Twitter::User>] A collection of Twitter user IDs, screen_names, URIs, or objects
+      # @return [void]
       def merge_users!(hash, users)
         user_ids, screen_names = collect_users(users.uniq)
         hash[:user_id] = user_ids.join(",") unless user_ids.empty?
         hash[:screen_name] = screen_names.join(",") unless screen_names.empty?
       end
 
+      # Collect users into user_ids and screen_names arrays
+      #
+      # @api private
+      # @param users [Enumerable]
+      # @return [Array<Array, Array>]
       def collect_users(users) # rubocop:disable Metrics/MethodLength
-        user_ids = []
-        screen_names = []
+        user_ids = [] # : Array[Integer]
+        screen_names = [] # : Array[String]
         users.each do |user|
           case user
-          when Integer               then user_ids << user
-          when Twitter::User         then user_ids << user.id
-          when String                then screen_names << user
-          when URI, Addressable::URI then screen_names << user.path.split("/").last
+          when Integer then user_ids << user
+          when User then user_ids << user.id
+          when String then screen_names << user
+          when URI then screen_names << user.path.split("/").last # steep:ignore NoMethod
           end
         end
         [user_ids, screen_names]

data/lib/twitter/saved_search.rb

@@ -2,8 +2,29 @@ require "twitter/creatable"
 require "twitter/identity"
 
 module Twitter
-  class SavedSearch < Twitter::Identity
-    include Twitter::Creatable
+  # Represents a saved search
+  class SavedSearch < Identity
+    include Creatable
+
+    # The name of the saved search
+    #
+    # @api public
+    # @example
+    #   saved_search.name
+    # @return [String]
+
+    # The position of the saved search
+    #
+    # @api public
+    # @example
+    #   saved_search.position
+    # @return [String]
+
+    # The query of the saved search
+    #
+    # @api public
+    # @example
+    #   saved_search.query
     # @return [String]
     attr_reader :name, :position, :query
   end

data/lib/twitter/search_results.rb

@@ -5,17 +5,48 @@ require "twitter/utils"
 require "uri"
 
 module Twitter
+  # Represents search results from Twitter
   class SearchResults
-    include Twitter::Enumerable
-    include Twitter::Utils
+    include Enumerable
+    include Utils
+
+    # The raw attributes hash
+    #
+    # @api public
+    # @example
+    #   results.attrs
     # @return [Hash]
+
+    # The rate limit information from the response
+    #
+    # @api public
+    # @example
+    #   results.rate_limit
+    # @return [Twitter::RateLimit]
     attr_reader :attrs, :rate_limit
-    alias to_h attrs
-    alias to_hash to_h
+
+    # @!method to_h
+    #   Returns the attributes as a hash
+    #   @api public
+    #   @example
+    #     results.to_h
+    #   @return [Hash]
+    alias_method :to_h, :attrs
+
+    # @!method to_hash
+    #   Returns the attributes as a hash
+    #   @api public
+    #   @example
+    #     results.to_hash
+    #   @return [Hash]
+    alias_method :to_hash, :to_h
 
     # Initializes a new SearchResults object
     #
-    # @param request [Twitter::REST::Request]
+    # @api public
+    # @example
+    #   Twitter::SearchResults.new(request)
+    # @param request [Twitter::REST::Request] The request object
     # @return [Twitter::SearchResults]
     def initialize(request)
       @client = request.client
@@ -26,51 +57,65 @@ module Twitter
       self.attrs = request.perform
     end
 
-  private
+    private
 
+    # Returns true if this is the last page of results
+    #
+    # @api private
     # @return [Boolean]
     def last?
       !next_page?
     end
 
+    # Returns true if there is a next page
+    #
+    # @api private
     # @return [Boolean]
     def next_page?
       !!@attrs[:search_metadata][:next_results] unless @attrs[:search_metadata].nil?
     end
 
-    # Returns a Hash of query parameters for the next result in the search
+    # Returns query parameters for the next page
     #
-    # @note Returned Hash can be merged into the previous search options list to easily access the next page.
-    # @return [Hash] The parameters needed to fetch the next page.
+    # @api private
+    # @note Returned Hash can be merged into previous search options
+    # @return [Hash]
     def next_page
       query_string_to_hash(@attrs[:search_metadata][:next_results]) if next_page?
     end
 
+    # Fetches the next page of results
+    #
+    # @api private
     # @return [Hash]
     def fetch_next_page
-      response = Twitter::REST::Request.new(@client, @request_method, @path, @options.merge(next_page))
+      response = REST::Request.new(@client, @request_method, @path, @options.merge(next_page)) # steep:ignore ArgumentTypeMismatch
       self.attrs = response.perform
       @rate_limit = response.rate_limit
     end
 
-    # @param attrs [Hash]
+    # Sets the attributes and populates the collection
+    #
+    # @api private
+    # @param attrs [Hash] The attributes hash
     # @return [Hash]
     def attrs=(attrs)
       @attrs = attrs
       @attrs.fetch(:statuses, []).collect do |tweet|
         @collection << Tweet.new(tweet)
       end
-      @attrs
     end
 
     # Converts query string to a hash
     #
-    # @param query_string [String] The query string of a URL.
-    # @return [Hash] The query string converted to a hash (with symbol keys).
-    # @example Convert query string to a hash
-    #   query_string_to_hash("foo=bar&baz=qux") #=> {:foo=>"bar", :baz=>"qux"}
+    # @api private
+    # @param query_string [String] The query string of a URL
+    # @return [Hash]
     def query_string_to_hash(query_string)
-      query = CGI.parse(URI.parse(query_string).query)
+      parsed_query = URI.parse(query_string).query
+      return {} if parsed_query.nil?
+
+      query = CGI.parse(parsed_query)
       query.to_h { |key, value| [key.to_sym, value.first] }
     end
   end

data/lib/twitter/settings.rb

@@ -1,23 +1,49 @@
 require "twitter/base"
 
 module Twitter
-  class Settings < Twitter::Base
+  # Represents Twitter account settings
+  class Settings < Base
+    # The sleep time settings
+    #
+    # @api public
+    # @example
+    #   settings.sleep_time
+    # @return [Hash]
+
+    # The time zone settings
+    #
+    # @api public
+    # @example
+    #   settings.time_zone
     # @return [Hash]
     attr_reader :sleep_time, :time_zone
+
+    # The language preference
+    #
+    # @api public
+    # @example
+    #   settings.language
+    # @return [String]
+
+    # The screen name of the account
+    #
+    # @api public
+    # @example
+    #   settings.screen_name
     # @return [String]
     attr_reader :language, :screen_name
 
     object_attr_reader :Place, :trend_location
     predicate_attr_reader :allow_contributor_request,
-                          :allow_dm_groups_from,
-                          :allow_dms_from,
-                          :always_use_https,
-                          :discoverable_by_email,
-                          :discoverable_by_mobile_phone,
-                          :display_sensitive_media,
-                          :geo_enabled,
-                          :protected,
-                          :show_all_inline_media,
-                          :use_cookie_personalization
+      :allow_dm_groups_from,
+      :allow_dms_from,
+      :always_use_https,
+      :discoverable_by_email,
+      :discoverable_by_mobile_phone,
+      :display_sensitive_media,
+      :geo_enabled,
+      :protected,
+      :show_all_inline_media,
+      :use_cookie_personalization
   end
 end

data/lib/twitter/size.rb

@@ -2,13 +2,47 @@ require "equalizer"
 require "twitter/base"
 
 module Twitter
-  class Size < Twitter::Base
+  # Represents a size for media objects
+  class Size < Base
     include Equalizer.new(:h, :w)
+
+    # The height in pixels
+    #
+    # @api public
+    # @example
+    #   size.h
+    # @return [Integer]
+
+    # The width in pixels
+    #
+    # @api public
+    # @example
+    #   size.w
     # @return [Integer]
     attr_reader :h, :w
+
+    # The resize method used
+    #
+    # @api public
+    # @example
+    #   size.resize
     # @return [String]
     attr_reader :resize
-    alias height h
-    alias width w
+
+    # @!method height
+    #   The height in pixels
+    #   @api public
+    #   @example
+    #     size.height
+    #   @return [Integer]
+    alias_method :height, :h
+
+    # @!method width
+    #   The width in pixels
+    #   @api public
+    #   @example
+    #     size.width
+    #   @return [Integer]
+    alias_method :width, :w
   end
 end

data/lib/twitter/source_user.rb

@@ -1,9 +1,10 @@
 require "twitter/basic_user"
 
 module Twitter
-  class SourceUser < Twitter::BasicUser
+  # Represents the source user in a relationship
+  class SourceUser < BasicUser
     predicate_attr_reader :all_replies, :blocking, :can_dm, :followed_by,
-                          :marked_spam, :muting, :notifications_enabled,
-                          :want_retweets
+      :marked_spam, :muting, :notifications_enabled,
+      :want_retweets
   end
 end