twitter 8.1.0 → 8.3.0

data/lib/twitter/tweet.rb

@@ -3,42 +3,189 @@ require "twitter/entities"
 require "twitter/identity"
 
 module Twitter
-  class Tweet < Twitter::Identity
-    include Twitter::Creatable
-    include Twitter::Entities
+  # Represents a Twitter tweet
+  class Tweet < Identity
+    include Creatable
+    include Entities
+
+    # The filter level of the tweet
+    #
+    # @api public
+    # @example
+    #   tweet.filter_level
+    # @return [String]
+
+    # The screen name of the user being replied to
+    #
+    # @api public
+    # @example
+    #   tweet.in_reply_to_screen_name
+    # @return [String]
+
+    # The language of the tweet
+    #
+    # @api public
+    # @example
+    #   tweet.lang
+    # @return [String]
+
+    # The source of the tweet
+    #
+    # @api public
+    # @example
+    #   tweet.source
+    # @return [String]
+
+    # The text of the tweet
+    #
+    # @api public
+    # @example
+    #   tweet.text
     # @return [String]
     attr_reader :filter_level, :in_reply_to_screen_name, :lang, :source, :text
+
+    # The number of times this tweet has been favorited
+    #
+    # @api public
+    # @example
+    #   tweet.favorite_count
+    # @return [Integer]
+
+    # The ID of the status being replied to
+    #
+    # @api public
+    # @example
+    #   tweet.in_reply_to_status_id
+    # @return [Integer]
+
+    # The ID of the user being replied to
+    #
+    # @api public
+    # @example
+    #   tweet.in_reply_to_user_id
+    # @return [Integer]
+
+    # The number of times this tweet has been quoted
+    #
+    # @api public
+    # @example
+    #   tweet.quote_count
+    # @return [Integer]
+
+    # The number of replies to this tweet
+    #
+    # @api public
+    # @example
+    #   tweet.reply_count
+    # @return [Integer]
+
+    # The number of times this tweet has been retweeted
+    #
+    # @api public
+    # @example
+    #   tweet.retweet_count
     # @return [Integer]
     attr_reader :favorite_count, :in_reply_to_status_id, :in_reply_to_user_id,
-                :quote_count, :reply_count, :retweet_count
-    alias in_reply_to_tweet_id in_reply_to_status_id
-    alias reply? in_reply_to_user_id?
+      :quote_count, :reply_count, :retweet_count
+
+    # @!method in_reply_to_tweet_id
+    #   The ID of the tweet being replied to
+    #   @api public
+    #   @example
+    #     tweet.in_reply_to_tweet_id
+    #   @return [Integer]
+    alias_method :in_reply_to_tweet_id, :in_reply_to_status_id
+
+    # Returns true if this is a reply
+    #
+    # @!method reply?
+    # @api public
+    # @example
+    #   tweet.reply?
+    # @return [Boolean]
+    alias_method :reply?, :in_reply_to_user_id?
     object_attr_reader :GeoFactory, :geo
     object_attr_reader :Metadata, :metadata
     object_attr_reader :Place, :place
     object_attr_reader :Tweet, :retweeted_status
     object_attr_reader :Tweet, :quoted_status
     object_attr_reader :Tweet, :current_user_retweet
-    alias retweeted_tweet retweeted_status
-    alias retweet? retweeted_status?
-    alias retweeted_tweet? retweeted_status?
-    alias quoted_tweet quoted_status
-    alias quote? quoted_status?
-    alias quoted_tweet? quoted_status?
+
+    # Returns the retweeted tweet
+    #
+    # @!method retweeted_tweet
+    # @api public
+    # @example
+    #   tweet.retweeted_tweet
+    # @return [Twitter::Tweet]
+    alias_method :retweeted_tweet, :retweeted_status
+
+    # Returns true if this is a retweet
+    #
+    # @!method retweet?
+    # @api public
+    # @example
+    #   tweet.retweet?
+    # @return [Boolean]
+    alias_method :retweet?, :retweeted_status?
+
+    # Returns true if this has a retweeted tweet
+    #
+    # @!method retweeted_tweet?
+    # @api public
+    # @example
+    #   tweet.retweeted_tweet?
+    # @return [Boolean]
+    alias_method :retweeted_tweet?, :retweeted_status?
+
+    # Returns the quoted tweet
+    #
+    # @!method quoted_tweet
+    # @api public
+    # @example
+    #   tweet.quoted_tweet
+    # @return [Twitter::Tweet]
+    alias_method :quoted_tweet, :quoted_status
+
+    # Returns true if this is a quote tweet
+    #
+    # @!method quote?
+    # @api public
+    # @example
+    #   tweet.quote?
+    # @return [Boolean]
+    alias_method :quote?, :quoted_status?
+
+    # Returns true if this has a quoted tweet
+    #
+    # @!method quoted_tweet?
+    # @api public
+    # @example
+    #   tweet.quoted_tweet?
+    # @return [Boolean]
+    alias_method :quoted_tweet?, :quoted_status?
     object_attr_reader :User, :user, :status
     predicate_attr_reader :favorited, :possibly_sensitive, :retweeted,
-                          :truncated
+      :truncated
 
-    # Initializes a new object
+    # Initializes a new Tweet object
     #
-    # @param attrs [Hash]
+    # @api public
+    # @example
+    #   Twitter::Tweet.new(id: 123, text: "Hello")
+    # @param attrs [Hash] The attributes hash containing at least :id
     # @return [Twitter::Tweet]
-    def initialize(attrs = {})
-      attrs[:text] = attrs[:full_text] if attrs[:text].nil? && !attrs[:full_text].nil?
+    def initialize(attrs)
+      attrs[:text] ||= attrs[:full_text]
       super
     end
 
-    # @note May be > 280 characters.
+    # Returns the full text of the tweet
+    #
+    # @api public
+    # @note May be > 280 characters
+    # @example
+    #   tweet.full_text
     # @return [String]
     def full_text
       if retweet?
@@ -50,11 +197,23 @@ module Twitter
     end
     memoize :full_text
 
-    # @return [Addressable::URI] The URL to the tweet.
+    # Returns the URI to the tweet
+    #
+    # @api public
+    # @example
+    #   tweet.uri
+    # @return [URI::Generic]
     def uri
-      Addressable::URI.parse("https://twitter.com/#{user.screen_name}/status/#{id}") if user?
+      URI.parse("https://twitter.com/#{user.screen_name}/status/#{id}") if user?
     end
     memoize :uri
-    alias url uri
+
+    # @!method url
+    #   Returns the URL to the tweet
+    #   @api public
+    #   @example
+    #     tweet.url
+    #   @return [URI::Generic]
+    alias_method :url, :uri
   end
 end

data/lib/twitter/user.rb

@@ -1,99 +1,335 @@
-require "addressable/uri"
+require "uri"
 require "twitter/basic_user"
 require "twitter/creatable"
 require "twitter/entity/uri"
 require "twitter/profile"
 
 module Twitter
-  class User < Twitter::BasicUser
-    include Twitter::Creatable
-    include Twitter::Profile
+  # Represents a Twitter user
+  class User < BasicUser
+    include Creatable
+    include Profile
+
+    # The user's connections
+    #
+    # @api public
+    # @example
+    #   user.connections
     # @return [Array]
     attr_reader :connections
+
+    # The number of favourites
+    #
+    # @api public
+    # @example
+    #   user.favourites_count
+    # @return [Integer]
+
+    # The number of followers
+    #
+    # @api public
+    # @example
+    #   user.followers_count
+    # @return [Integer]
+
+    # The number of friends (following)
+    #
+    # @api public
+    # @example
+    #   user.friends_count
+    # @return [Integer]
+
+    # The number of lists this user is on
+    #
+    # @api public
+    # @example
+    #   user.listed_count
+    # @return [Integer]
+
+    # The number of statuses/tweets
+    #
+    # @api public
+    # @example
+    #   user.statuses_count
+    # @return [Integer]
+
+    # The UTC offset in seconds
+    #
+    # @api public
+    # @example
+    #   user.utc_offset
     # @return [Integer]
     attr_reader :favourites_count, :followers_count, :friends_count,
-                :listed_count, :statuses_count, :utc_offset
+      :listed_count, :statuses_count, :utc_offset
+
+    # The user's description
+    #
+    # @api public
+    # @example
+    #   user.description
+    # @return [String]
+
+    # The user's email address
+    #
+    # @api public
+    # @example
+    #   user.email
+    # @return [String]
+
+    # The user's language
+    #
+    # @api public
+    # @example
+    #   user.lang
+    # @return [String]
+
+    # The user's location
+    #
+    # @api public
+    # @example
+    #   user.location
+    # @return [String]
+
+    # The user's name
+    #
+    # @api public
+    # @example
+    #   user.name
+    # @return [String]
+
+    # The profile background color
+    #
+    # @api public
+    # @example
+    #   user.profile_background_color
+    # @return [String]
+
+    # The profile link color
+    #
+    # @api public
+    # @example
+    #   user.profile_link_color
+    # @return [String]
+
+    # The profile sidebar border color
+    #
+    # @api public
+    # @example
+    #   user.profile_sidebar_border_color
+    # @return [String]
+
+    # The profile sidebar fill color
+    #
+    # @api public
+    # @example
+    #   user.profile_sidebar_fill_color
+    # @return [String]
+
+    # The profile text color
+    #
+    # @api public
+    # @example
+    #   user.profile_text_color
+    # @return [String]
+
+    # The user's time zone
+    #
+    # @api public
+    # @example
+    #   user.time_zone
     # @return [String]
     attr_reader :description, :email, :lang, :location, :name,
-                :profile_background_color, :profile_link_color,
-                :profile_sidebar_border_color, :profile_sidebar_fill_color,
-                :profile_text_color, :time_zone
-    alias favorites_count favourites_count
-    alias tweets_count statuses_count
+      :profile_background_color, :profile_link_color,
+      :profile_sidebar_border_color, :profile_sidebar_fill_color,
+      :profile_text_color, :time_zone
+
+    # @!method favorites_count
+    #   The number of favorites (US spelling)
+    #   @api public
+    #   @example
+    #     user.favorites_count
+    #   @return [Integer]
+    alias_method :favorites_count, :favourites_count
+
+    # @!method tweets_count
+    #   The number of tweets
+    #   @api public
+    #   @example
+    #     user.tweets_count
+    #   @return [Integer]
+    alias_method :tweets_count, :statuses_count
     object_attr_reader :Tweet, :status, :user
-    alias tweet status
-    alias tweet? status?
-    alias tweeted? status?
+
+    # The user's latest tweet
+    #
+    # @!method tweet
+    # @api public
+    # @example
+    #   user.tweet
+    # @return [Twitter::Tweet]
+    alias_method :tweet, :status
+
+    # Returns true if the user has a tweet
+    #
+    # @!method tweet?
+    # @api public
+    # @example
+    #   user.tweet?
+    # @return [Boolean]
+    alias_method :tweet?, :status?
+
+    # Returns true if the user has tweeted
+    #
+    # @!method tweeted?
+    # @api public
+    # @example
+    #   user.tweeted?
+    # @return [Boolean]
+    alias_method :tweeted?, :status?
     predicate_attr_reader :contributors_enabled, :default_profile,
-                          :default_profile_image, :follow_request_sent,
-                          :geo_enabled, :muting, :needs_phone_verification,
-                          :notifications, :protected, :profile_background_tile,
-                          :profile_use_background_image, :suspended, :verified
+      :default_profile_image, :follow_request_sent,
+      :geo_enabled, :muting, :needs_phone_verification,
+      :notifications, :protected, :profile_background_tile,
+      :profile_use_background_image, :suspended, :verified
     define_predicate_method :translator, :is_translator
     define_predicate_method :translation_enabled, :is_translation_enabled
     uri_attr_reader :profile_background_image_uri, :profile_background_image_uri_https
 
-    class << self
-    private
-
-      # Dynamically define a method for entity URIs
-      #
-      # @param key1 [Symbol]
-      # @param key2 [Symbol]
-      def define_entity_uris_methods(key1, key2)
-        array = key1.to_s.split("_")
-        index = array.index("uris")
-        array[index] = "urls"
-        url_key = array.join("_").to_sym
-        define_entity_uris_method(key1, key2)
-        alias_method(url_key, key1)
-        define_entity_uris_predicate_method(key1)
-        alias_method(:"#{url_key}?", :"#{key1}?")
+    # Returns an array of URIs in the user's description
+    #
+    # @api public
+    # @example
+    #   user.description_uris
+    # @return [Array<Twitter::Entity::URI>]
+    def description_uris
+      empty_hash = {} # : Hash[Symbol, untyped]
+      empty_array = [] # : Array[untyped]
+      @attrs.fetch(:entities, empty_hash).fetch(:description, empty_hash).fetch(:urls, empty_array).collect do |url| # steep:ignore FallbackAny
+        Entity::URI.new(url)
       end
+    end
+    memoize :description_uris
 
-      def define_entity_uris_method(key1, key2)
-        define_method(key1) do
-          @attrs.fetch(:entities, {}).fetch(key2, {}).fetch(:urls, []).collect do |url|
-            Entity::URI.new(url)
-          end
-        end
-        memoize(key1)
-      end
+    # @!method description_urls
+    #   Returns an array of URLs in the user's description
+    #   @api public
+    #   @example
+    #     user.description_urls
+    #   @return [Array<Twitter::Entity::URI>]
+    alias_method :description_urls, :description_uris
+
+    # Returns true if the user has description URIs
+    #
+    # @api public
+    # @example
+    #   user.description_uris?
+    # @return [Boolean]
+    def description_uris?
+      description_uris.any?
+    end
+    memoize :description_uris?
+
+    # @!method description_urls?
+    #   Returns true if the user has description URLs
+    #   @api public
+    #   @example
+    #     user.description_urls?
+    #   @return [Boolean]
+    alias_method :description_urls?, :description_uris?
 
-      def define_entity_uris_predicate_method(key1)
-        define_method(:"#{key1}?") do
-          send(:"#{key1}").any?
-        end
-        memoize(:"#{key1}?")
+    # Returns an array of URIs in the user's website
+    #
+    # @api public
+    # @example
+    #   user.website_uris
+    # @return [Array<Twitter::Entity::URI>]
+    def website_uris
+      empty_hash = {} # : Hash[Symbol, untyped]
+      empty_array = [] # : Array[untyped]
+      @attrs.fetch(:entities, empty_hash).fetch(:url, empty_hash).fetch(:urls, empty_array).collect do |url| # steep:ignore FallbackAny
+        Entity::URI.new(url)
       end
     end
+    memoize :website_uris
 
-    define_entity_uris_methods :description_uris, :description
-    define_entity_uris_methods :website_uris, :url
+    # @!method website_urls
+    #   Returns an array of URLs in the user's website
+    #   @api public
+    #   @example
+    #     user.website_urls
+    #   @return [Array<Twitter::Entity::URI>]
+    alias_method :website_urls, :website_uris
 
+    # Returns true if the user has website URIs
+    #
+    # @api public
+    # @example
+    #   user.website_uris?
+    # @return [Boolean]
+    def website_uris?
+      website_uris.any?
+    end
+    memoize :website_uris?
+
+    # @!method website_urls?
+    #   Returns true if the user has website URLs
+    #   @api public
+    #   @example
+    #     user.website_urls?
+    #   @return [Boolean]
+    alias_method :website_urls?, :website_uris?
+
+    # Returns true if the user has entities
+    #
+    # @api public
+    # @example
+    #   user.entities?
     # @return [Boolean]
     def entities?
       !@attrs[:entities].nil? && @attrs[:entities].any? { |_, hash| hash[:urls].any? }
     end
     memoize :entities?
 
-    # @return [Addressable::URI] The URL to the user.
+    # Returns the URI to the user's profile
+    #
+    # @api public
+    # @example
+    #   user.uri
+    # @return [URI::Generic]
     def uri
-      Addressable::URI.parse("https://twitter.com/#{screen_name}") if screen_name?
+      URI.parse("https://twitter.com/#{screen_name}") if screen_name?
     end
     memoize :uri
-    alias url uri
 
-    # @return [Addressable::URI] The URL to the user's website.
+    # @!method url
+    #   Returns the URL to the user's profile
+    #   @api public
+    #   @example
+    #     user.url
+    #   @return [URI::Generic]
+    alias_method :url, :uri
+
+    # Returns the user's website URL
+    #
+    # @api public
+    # @example
+    #   user.website
+    # @return [URI::Generic]
     def website
       if website_uris?
         website_uris.first.expanded_url
       else
-        Addressable::URI.parse(@attrs[:url])
+        URI.parse(@attrs[:url]) unless @attrs[:url].nil?
       end
     end
     memoize :website
 
+    # Returns true if the user has a website
+    #
+    # @api public
+    # @example
+    #   user.website?
+    # @return [Boolean]
     def website?
       !!(website_uris? || @attrs[:url])
     end

data/lib/twitter/utils.rb

@@ -1,10 +1,11 @@
 module Twitter
+  # Utility methods for parallel mapping
+  #
+  # @api private
   module Utils
-  module_function
-
-    # Returns a new array with the concatenated results of running block once for every element in enumerable.
-    # If no block is given, an enumerator is returned instead.
+    # Parallel flat_map for enumerables
     #
+    # @api private
     # @param enumerable [Enumerable]
     # @return [Array, Enumerator]
     def flat_pmap(enumerable, &block)
@@ -12,20 +13,18 @@ module Twitter
 
       pmap(enumerable, &block).flatten(1)
     end
+    module_function :flat_pmap
 
-    # Returns a new array with the results of running block once for every element in enumerable.
-    # If no block is given, an enumerator is returned instead.
+    # Parallel map for enumerables
     #
+    # @api private
     # @param enumerable [Enumerable]
     # @return [Array, Enumerator]
-    def pmap(enumerable, &block)
-      return to_enum(:pmap, enumerable) unless block
+    def pmap(enumerable, &)
+      return to_enum(:pmap, enumerable) unless block_given?
 
-      if enumerable.count == 1
-        enumerable.collect(&block)
-      else
-        enumerable.collect { |object| Thread.new { yield(object) } }.collect(&:value)
-      end
+      enumerable.collect(&)
     end
+    module_function :pmap
   end
 end

data/lib/twitter/variant.rb

@@ -1,10 +1,21 @@
 require "twitter/base"
 
 module Twitter
-  class Variant < Twitter::Base
+  # Represents a video variant with a specific bitrate and format
+  class Variant < Base
+    # The bitrate of this variant in bits per second
+    #
+    # @api public
+    # @example
+    #   variant.bitrate
     # @return [Integer]
     attr_reader :bitrate
 
+    # The content type (MIME type) of this variant
+    #
+    # @api public
+    # @example
+    #   variant.content_type
     # @return [String]
     attr_reader :content_type