twitter 8.1.0 → 8.3.0

data/lib/twitter/streaming/client.rb

@@ -8,13 +8,28 @@ require "twitter/streaming/response"
 require "twitter/utils"
 
 module Twitter
+  # Streaming API modules for Twitter
   module Streaming
+    # Client for consuming the Twitter Streaming API
+    #
+    # @api public
     class Client < Twitter::Client
       include Twitter::Utils
+
+      # Sets the connection object
+      #
+      # @api public
+      # @example
+      #   client.connection = connection
+      # @param value [Twitter::Streaming::Connection] The connection to use.
+      # @return [Twitter::Streaming::Connection]
       attr_writer :connection
 
       # Initializes a new Client object
       #
+      # @api public
+      # @example
+      #   client = Twitter::Streaming::Client.new
       # @param options [Hash] A customizable set of options.
       # @option options [String] :tcp_socket_class A class that Connection will use to create a new TCP socket.
       # @option options [String] :ssl_socket_class A class that Connection will use to create a new SSL socket.
@@ -26,6 +41,9 @@ module Twitter
 
       # Returns public statuses that match one or more filter predicates
       #
+      # @api public
+      # @example
+      #   client.filter(track: 'twitter')
       # @see https://dev.twitter.com/streaming/reference/post/statuses/filter
       # @see https://dev.twitter.com/streaming/overview/request-parameters
       # @note At least one predicate parameter (follow, locations, or track) must be specified.
@@ -34,33 +52,45 @@ module Twitter
       # @option options [String] :track Includes additional Tweets matching the specified keywords. Phrases of keywords are specified by a comma-separated list.
       # @option options [String] :locations Includes additional Tweets falling within the specified bounding boxes.
       # @yield [Twitter::Tweet, Twitter::Streaming::Event, Twitter::DirectMessage, Twitter::Streaming::FriendList, Twitter::Streaming::DeletedTweet, Twitter::Streaming::StallWarning] A stream of Twitter objects.
+      # @return [void]
       def filter(options = {}, &)
         request(:post, "https://stream.twitter.com:443/1.1/statuses/filter.json", options, &)
       end
 
       # Returns all public statuses
       #
+      # @api public
+      # @example
+      #   client.firehose
       # @see https://dev.twitter.com/streaming/reference/get/statuses/firehose
       # @see https://dev.twitter.com/streaming/overview/request-parameters
       # @note This endpoint requires special permission to access.
       # @param options [Hash] A customizable set of options.
       # @option options [Integer] :count The number of messages to backfill.
       # @yield [Twitter::Tweet, Twitter::Streaming::Event, Twitter::DirectMessage, Twitter::Streaming::FriendList, Twitter::Streaming::DeletedTweet, Twitter::Streaming::StallWarning] A stream of Twitter objects.
+      # @return [void]
       def firehose(options = {}, &)
         request(:get, "https://stream.twitter.com:443/1.1/statuses/firehose.json", options, &)
       end
 
       # Returns a small random sample of all public statuses
       #
+      # @api public
+      # @example
+      #   client.sample
       # @see https://dev.twitter.com/streaming/reference/get/statuses/sample
       # @see https://dev.twitter.com/streaming/overview/request-parameters
       # @yield [Twitter::Tweet, Twitter::Streaming::Event, Twitter::DirectMessage, Twitter::Streaming::FriendList, Twitter::Streaming::DeletedTweet, Twitter::Streaming::StallWarning] A stream of Twitter objects.
+      # @return [void]
       def sample(options = {}, &)
         request(:get, "https://stream.twitter.com:443/1.1/statuses/sample.json", options, &)
       end
 
       # Streams messages for a set of users
       #
+      # @api public
+      # @example
+      #   client.site(7505382)
       # @see https://dev.twitter.com/streaming/reference/get/site
       # @see https://dev.twitter.com/streaming/sitestreams
       # @see https://dev.twitter.com/streaming/overview/request-parameters
@@ -71,6 +101,7 @@ module Twitter
       #   @option options [String] :with Specifies whether to return information for just the users specified in the follow parameter, or include messages from accounts they follow.
       #   @option options [String] :replies Specifies whether stall warnings should be delivered.
       #   @yield [Twitter::Tweet, Twitter::Streaming::Event, Twitter::DirectMessage, Twitter::Streaming::FriendList, Twitter::Streaming::DeletedTweet, Twitter::Streaming::StallWarning] A stream of Twitter objects.
+      # @return [void]
       def site(*args, &)
         arguments = Arguments.new(args)
         user_ids = collect_user_ids(arguments)
@@ -79,6 +110,9 @@ module Twitter
 
       # Streams messages for a single user
       #
+      # @api public
+      # @example
+      #   client.user
       # @see https://dev.twitter.com/streaming/reference/get/user
       # @see https://dev.twitter.com/streaming/userstreams
       # @see https://dev.twitter.com/streaming/overview/request-parameters
@@ -89,11 +123,17 @@ module Twitter
       # @option options [String] :track Includes additional Tweets matching the specified keywords. Phrases of keywords are specified by a comma-separated list.
       # @option options [String] :locations Includes additional Tweets falling within the specified bounding boxes.
       # @yield [Twitter::Tweet, Twitter::Streaming::Event, Twitter::DirectMessage, Twitter::Streaming::FriendList, Twitter::Streaming::DeletedTweet, Twitter::Streaming::StallWarning] A stream of Twitter objects.
+      # @return [void]
       def user(options = {}, &)
         request(:get, "https://userstream.twitter.com:443/1.1/user.json", options, &)
       end
 
-      # Set a Proc to be run when connection established.
+      # Set a Proc to be run when connection established
+      #
+      # @api public
+      # @example
+      #   client.before_request { puts 'Connected!' }
+      # @return [Proc, Twitter::Streaming::Client]
       def before_request(&block)
         if block
           @before_request = block
@@ -105,12 +145,22 @@ module Twitter
         end
       end
 
+      # Closes the streaming connection
+      #
+      # @api public
+      # @example
+      #   client.close
+      # @return [void]
       def close
         @connection.close
       end
 
-    private
+      private
 
+      # Performs the streaming request
+      #
+      # @api private
+      # @return [void]
       def request(method, uri, params)
         before_request.call
         headers = Twitter::Headers.new(self, method, uri, params).request_headers
@@ -123,21 +173,23 @@ module Twitter
         @connection.stream(request, response)
       end
 
+      # Converts params to URL query string
+      #
+      # @api private
+      # @return [String]
       def to_url_params(params)
-        uri = Addressable::URI.new
-        uri.query_values = params
-        uri.query
+        URI.encode_www_form(params)
       end
 
-      # Takes a mixed array of Integers and Twitter::User objects and returns a
-      # consistent array of Twitter user IDs.
+      # Takes a mixed array of Integers and Twitter::User objects
       #
+      # @api private
       # @param users [Array]
       # @return [Array<Integer>]
       def collect_user_ids(users)
         users.filter_map do |user|
           case user
-          when Integer       then user
+          when Integer then user
           when Twitter::User then user.id
           end
         end

data/lib/twitter/streaming/connection.rb

@@ -3,16 +3,46 @@ require "resolv"
 
 module Twitter
   module Streaming
+    # Manages TCP/SSL connections for streaming
+    #
+    # @api public
     class Connection
+      # Returns the TCP socket class
+      #
+      # @api public
+      # @example
+      #   connection.tcp_socket_class
+      # @return [Class]
+
+      # Returns the SSL socket class
+      #
+      # @api public
+      # @example
+      #   connection.ssl_socket_class
+      # @return [Class]
       attr_reader :tcp_socket_class, :ssl_socket_class
 
+      # Initializes a new Connection object
+      #
+      # @api public
+      # @example
+      #   connection = Twitter::Streaming::Connection.new
+      # @param options [Hash] A customizable set of options.
+      # @return [Twitter::Streaming::Connection]
       def initialize(options = {})
-        @tcp_socket_class = options.fetch(:tcp_socket_class) { TCPSocket }
-        @ssl_socket_class = options.fetch(:ssl_socket_class) { OpenSSL::SSL::SSLSocket }
-        @using_ssl        = options.fetch(:using_ssl, false)
-        @write_pipe = nil
+        @tcp_socket_class = options.fetch(:tcp_socket_class) { TCPSocket } # steep:ignore UnknownConstant
+        @ssl_socket_class = options.fetch(:ssl_socket_class) { OpenSSL::SSL::SSLSocket } # steep:ignore UnknownConstant
+        @using_ssl = options.fetch(:using_ssl, false)
       end
 
+      # Streams data from the connection
+      #
+      # @api public
+      # @example
+      #   connection.stream(request, response)
+      # @param request [HTTP::Request] The HTTP request.
+      # @param response [Twitter::Streaming::Response] The response handler.
+      # @return [void]
       def stream(request, response) # rubocop:disable Metrics/MethodLength
         client = connect(request)
         request.stream(client)
@@ -29,23 +59,40 @@ module Twitter
         client.close
       end
 
+      # Connects to the specified host and port
+      #
+      # @api public
+      # @example
+      #   connection.connect(request)
+      # @param request [HTTP::Request] The HTTP request.
+      # @return [TCPSocket, OpenSSL::SSL::SSLSocket]
       def connect(request)
         client = new_tcp_socket(request.socket_host, request.socket_port)
         return client if !@using_ssl && request.using_proxy?
 
-        client_context = OpenSSL::SSL::SSLContext.new
-        ssl_client     = @ssl_socket_class.new(client, client_context)
+        client_context = OpenSSL::SSL::SSLContext.new # steep:ignore UnknownConstant
+        ssl_client = @ssl_socket_class.new(client, client_context)
         ssl_client.connect
       end
 
+      # Closes the connection
+      #
+      # @api public
+      # @example
+      #   connection.close
+      # @return [Integer, nil]
       def close
         @write_pipe&.write("q")
       end
 
-    private
+      private
 
+      # Creates a new TCP socket
+      #
+      # @api private
+      # @return [TCPSocket]
       def new_tcp_socket(host, port)
-        @tcp_socket_class.new(Resolv.getaddress(host), port)
+        @tcp_socket_class.new(Resolv.getaddress(host), port) # steep:ignore UnknownConstant
       end
     end
   end

data/lib/twitter/streaming/deleted_tweet.rb

@@ -1,6 +1,14 @@
 module Twitter
   module Streaming
+    # Represents a deleted tweet from the streaming API
+    #
+    # @api public
     class DeletedTweet < Twitter::Identity
+      # Returns the user ID of the deleted tweet's author
+      #
+      # @api public
+      # @example
+      #   deleted_tweet.user_id
       # @return [Integer]
       attr_reader :user_id
     end

data/lib/twitter/streaming/event.rb

@@ -1,19 +1,57 @@
 module Twitter
   module Streaming
+    # Represents a streaming event from the Twitter API
+    #
+    # @api public
     class Event
+      # Event names for list-related events
       LIST_EVENTS = %i[
         list_created list_destroyed list_updated list_member_added
         list_member_added list_member_removed list_user_subscribed
         list_user_subscribed list_user_unsubscribed list_user_unsubscribed
       ].freeze
 
+      # Event names for tweet-related events
       TWEET_EVENTS = %i[
         favorite unfavorite quoted_tweet
       ].freeze
 
+      # Returns the event name
+      #
+      # @api public
+      # @example
+      #   event.name
+      # @return [Symbol]
+
+      # Returns the source user
+      #
+      # @api public
+      # @example
+      #   event.source
+      # @return [Twitter::User]
+
+      # Returns the target user
+      #
+      # @api public
+      # @example
+      #   event.target
+      # @return [Twitter::User]
+
+      # Returns the target object
+      #
+      # @api public
+      # @example
+      #   event.target_object
+      # @return [Twitter::Tweet, Twitter::List, nil]
       attr_reader :name, :source, :target, :target_object
 
+      # Initializes a new Event object
+      #
+      # @api public
+      # @example
+      #   Twitter::Streaming::Event.new(data)
       # @param data [Hash]
+      # @return [Twitter::Streaming::Event]
       def initialize(data)
         @name = data[:event].to_sym
         @source = Twitter::User.new(data[:source])
@@ -21,8 +59,12 @@ module Twitter
         @target_object = target_object_factory(@name, data[:target_object])
       end
 
-    private
+      private
 
+      # Builds the target object based on event type
+      #
+      # @api private
+      # @return [Twitter::Tweet, Twitter::List, nil]
       def target_object_factory(event_name, data)
         if LIST_EVENTS.include?(event_name)
           Twitter::List.new(data)

data/lib/twitter/streaming/friend_list.rb

@@ -1,5 +1,6 @@
 module Twitter
   module Streaming
+    # Represents a list of friend IDs from the streaming API
     class FriendList < Array
     end
   end

data/lib/twitter/streaming/message_parser.rb

@@ -7,20 +7,30 @@ require "twitter/tweet"
 
 module Twitter
   module Streaming
+    # Parses streaming messages from the Twitter API
+    #
+    # @api public
     class MessageParser
+      # Parses streaming data into appropriate objects
+      #
+      # @api public
+      # @example
+      #   MessageParser.parse(data)
+      # @param data [Hash] The streaming data to parse.
+      # @return [Twitter::Tweet, Twitter::Streaming::Event, Twitter::DirectMessage, Twitter::Streaming::FriendList, Twitter::Streaming::DeletedTweet, Twitter::Streaming::StallWarning, nil]
       def self.parse(data) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-        if data[:id]
+        if data.key?(:id)
           Tweet.new(data)
-        elsif data[:event]
+        elsif data.key?(:event)
           Event.new(data)
-        elsif data[:direct_message]
-          DirectMessage.new(data[:direct_message])
-        elsif data[:friends]
-          FriendList.new(data[:friends])
-        elsif data[:delete] && data[:delete][:status]
-          DeletedTweet.new(data[:delete][:status])
-        elsif data[:warning]
-          StallWarning.new(data[:warning])
+        elsif data.key?(:direct_message)
+          DirectMessage.new(data.fetch(:direct_message))
+        elsif data.key?(:friends)
+          FriendList.new(data.fetch(:friends))
+        elsif data.key?(:delete) && data.fetch(:delete).key?(:status)
+          DeletedTweet.new(data.fetch(:delete).fetch(:status))
+        elsif data.key?(:warning)
+          StallWarning.new(data.fetch(:warning))
         end
       end
     end

data/lib/twitter/streaming/response.rb

@@ -2,32 +2,58 @@ require "buftok"
 require "http"
 require "json"
 require "twitter/error"
-require "llhttp"
 
 module Twitter
   module Streaming
+    # Handles streaming response parsing
+    #
+    # @api public
     class Response
       # Initializes a new Response object
       #
+      # @api public
+      # @example
+      #   response = Twitter::Streaming::Response.new { |data| puts data }
       # @return [Twitter::Streaming::Response]
       def initialize(&block)
-        @block     = block
-        @parser    = LLHttp::Parser.new(self, type: :response)
-        @tokenizer = BufferedTokenizer.new("\r\n")
+        @block = block
+        @parser = LLHttp::Parser.new(self, type: :response) # steep:ignore UnknownConstant
+        @tokenizer = BufferedTokenizer.new("\r\n") # steep:ignore UnknownConstant
       end
 
+      # Appends data to the parser
+      #
+      # @api public
+      # @example
+      #   response << data
+      # @param data [String] The data to append.
+      # @return [void]
       def <<(data)
         @parser << data
       end
 
+      # Handles body data from the response
+      #
+      # @api public
+      # @example
+      #   response.on_body(data)
+      # @param data [String] The body data.
+      # @return [void]
       def on_body(data)
         @tokenizer.extract(data).each do |line|
           next if line.empty?
 
-          @block.call(JSON.parse(line, symbolize_names: true))
+          @block.call(JSON.parse(line, symbolize_names: true)) # steep:ignore UnknownConstant
         end
       end
 
+      # Handles status code from the response
+      #
+      # @api public
+      # @example
+      #   response.on_status(200)
+      # @param _status [Integer] The status code.
+      # @return [void]
       def on_status(_status)
         error = Twitter::Error::ERRORS[@parser.status_code]
         raise error if error

data/lib/twitter/streaming/stall_warning.rb

@@ -1,6 +1,29 @@
 module Twitter
   module Streaming
+    # Represents a Twitter streaming stall warning
+    #
+    # @api public
     class StallWarning < Twitter::Base
+      # Returns the warning code
+      #
+      # @api public
+      # @example
+      #   stall_warning.code
+      # @return [String]
+
+      # Returns the warning message
+      #
+      # @api public
+      # @example
+      #   stall_warning.message
+      # @return [String]
+
+      # Returns the percent full value
+      #
+      # @api public
+      # @example
+      #   stall_warning.percent_full
+      # @return [Integer]
       attr_reader :code, :message, :percent_full
     end
   end

data/lib/twitter/suggestion.rb

@@ -3,15 +3,39 @@ require "memoizable"
 require "twitter/base"
 
 module Twitter
-  class Suggestion < Twitter::Base
+  # Represents a Twitter user suggestion category
+  class Suggestion < Base
     include Equalizer.new(:slug)
     include Memoizable
 
+    # The number of users in this category
+    #
+    # @api public
+    # @example
+    #   suggestion.size
     # @return [Integer]
     attr_reader :size
+
+    # The name of the suggestion category
+    #
+    # @api public
+    # @example
+    #   suggestion.name
+    # @return [String]
+
+    # The slug of the suggestion category
+    #
+    # @api public
+    # @example
+    #   suggestion.slug
     # @return [String]
     attr_reader :name, :slug
 
+    # Returns the users in this suggestion category
+    #
+    # @api public
+    # @example
+    #   suggestion.users
     # @return [Array<Twitter::User>]
     def users
       @attrs.fetch(:users, []).collect do |user|

data/lib/twitter/target_user.rb

@@ -1,7 +1,8 @@
 require "twitter/basic_user"
 
 module Twitter
-  class TargetUser < Twitter::BasicUser
+  # Represents the target user in a relationship
+  class TargetUser < BasicUser
     predicate_attr_reader :followed_by
   end
 end

data/lib/twitter/trend.rb

@@ -2,9 +2,37 @@ require "equalizer"
 require "twitter/base"
 
 module Twitter
-  class Trend < Twitter::Base
+  # Represents a Twitter trending topic
+  class Trend < Base
     include Equalizer.new(:name)
+
+    # Events associated with this trend
+    #
+    # @api public
+    # @example
+    #   trend.events
+    # @return [String]
+
+    # The name of the trend
+    #
+    # @api public
+    # @example
+    #   trend.name
     # @return [String]
+
+    # The search query for this trend
+    #
+    # @api public
+    # @example
+    #   trend.query
+    # @return [String]
+
+    # The tweet volume for this trend
+    #
+    # @api public
+    # @example
+    #   trend.tweet_volume
+    # @return [Integer]
     attr_reader :events, :name, :query, :tweet_volume
 
     predicate_attr_reader :promoted_content

data/lib/twitter/trend_results.rb

@@ -5,19 +5,43 @@ require "twitter/null_object"
 require "twitter/utils"
 
 module Twitter
+  # Represents a collection of trending topics
   class TrendResults
-    include Twitter::Creatable
-    include Twitter::Enumerable
-    include Twitter::Utils
+    include Creatable
+    include Enumerable
+    include Utils
     include Memoizable
+
+    # The raw attributes hash
+    #
+    # @api public
+    # @example
+    #   results.attrs
     # @return [Hash]
     attr_reader :attrs
-    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 TrendResults object
     #
-    # @param attrs [Hash]
+    # @api public
+    # @example
+    #   Twitter::TrendResults.new(trends: [])
+    # @param attrs [Hash] The attributes hash
     # @return [Twitter::TrendResults]
     def initialize(attrs = {})
       @attrs = attrs
@@ -26,25 +50,44 @@ module Twitter
       end
     end
 
-    # Time when the object was created on Twitter
+    # Returns the time when trends were retrieved
     #
+    # @api public
+    # @example
+    #   results.as_of
     # @return [Time]
     def as_of
       Time.parse(@attrs[:as_of]).utc unless @attrs[:as_of].nil?
     end
     memoize :as_of
 
+    # Returns true if as_of is available
+    #
+    # @api public
+    # @example
+    #   results.as_of?
+    # @return [Boolean]
     def as_of?
       !!@attrs[:as_of]
     end
     memoize :as_of?
 
+    # Returns the location for these trends
+    #
+    # @api public
+    # @example
+    #   results.location
     # @return [Twitter::Place, NullObject]
     def location
       location? ? Place.new(@attrs[:locations].first) : NullObject.new
     end
     memoize :location
 
+    # Returns true if location is available
+    #
+    # @api public
+    # @example
+    #   results.location?
     # @return [Boolean]
     def location?
       !@attrs[:locations].nil? && !@attrs[:locations].first.nil?