twitter_friendly 0.2.1 → 0.3.0

data/lib/twitter_friendly/rest/extension/clusters.rb

@@ -0,0 +1,313 @@
+module TwitterFriendly
+  module REST
+    module Extension
+      module Clusters
+
+        PROFILE_SPECIAL_WORDS = %w(20↑ 成人済 腐女子)
+        PROFILE_SPECIAL_REGEXP = nil
+        PROFILE_EXCLUDE_WORDS = %w(in at of my to no er by is RT DM the and for you inc Inc com from info next gmail 好き こと 最近 紹介 連載 発売 依頼 情報 さん ちゃん くん 発言 関係 もの 活動 見解 所属 組織 代表 連絡 大好き サイト ブログ つぶやき 株式会社 最新 こちら 届け お仕事 ツイ 返信 プロ 今年 リプ ヘッダー アイコン アカ アカウント ツイート たま ブロック 無言 時間 お願い お願いします お願いいたします イベント フォロー フォロワー フォロバ スタッフ 自動 手動 迷言 名言 非公式 リリース 問い合わせ ツイッター)
+        PROFILE_EXCLUDE_REGEXP = Regexp.union(/\w+@\w+\.(com|co\.jp)/, %r[\d{2,4}(年|/)\d{1,2}(月|/)\d{1,2}日], %r[\d{1,2}/\d{1,2}], /\d{2}th/, URI.regexp)
+
+        def tweet_clusters(tweets, limit: 10, debug: false)
+          return {} if tweets.blank?
+          text = tweets.map(&:text).join(' ')
+
+          if defined?(Rails)
+            exclude_words = JSON.parse(File.read(Rails.configuration.x.constants['cluster_bad_words_path']))
+            special_words = JSON.parse(File.read(Rails.configuration.x.constants['cluster_good_words_path']))
+          else
+            exclude_words = JSON.parse(File.read('./cluster_bad_words.json'))
+            special_words = JSON.parse(File.read('./cluster_good_words.json'))
+          end
+
+          %w(べたら むっちゃ それとも たしかに さそう そんなに ったことある してるの しそうな おやくま ってますか これをやってるよ のせいか 面白い 可愛い).each { |w| exclude_words << w }
+          %w(面白い 可愛い 食べ物 宇多田ヒカル ご飯 面倒 体調悪くなる 空腹 頑張ってない 眼鏡 台風 沖縄 らんま1/2 女の子 怪我 足のむくみ 彼女欲しい 彼氏欲しい 吐き気 注射 海鮮チヂミ 出勤 価格ドットコム 幹事 雑談 パズドラ ビオフェルミン 餃子 お金 まんだらけ 結婚 焼肉 タッチペン).each { |w| special_words << w }
+
+          # クラスタ用の単語の出現回数を記録
+          frequency =
+            special_words.map { |sw| [sw, text.scan(sw)] }
+              .delete_if { |_, matched| matched.empty? }
+              .each_with_object(Hash.new(0)) { |(word, matched), memo| memo[word] = matched.size }
+
+          # 同一文字種の繰り返しを見付ける。漢字の繰り返し、ひらがなの繰り返し、カタカナの繰り返し、など
+          text.scan(/[一-龠〆ヵヶ々]+|[ぁ-んー～]+|[ァ-ヴー～]+|[ａ-ｚA-ZＡ-Ｚ０-９]+|[、。！!？?]+/).
+
+            # 複数回繰り返される文字を除去
+            map { |w| w.remove /[？！?!。、ｗ]|(ー{2,})/ }.
+
+            # 文字数の少なすぎる単語、除外単語を除去する
+            delete_if { |w| w.length <= 2 || exclude_words.include?(w) }.
+
+            # 出現回数を記録
+            each { |w| frequency[w] += 1 }
+
+          # 複数個以上見付かった単語のみを残し、出現頻度順にソート
+          frequency.select { |_, v| 2 < v }.sort_by { |k, v| [-v, -k.size] }.take(limit).to_h
+        end
+
+        def count_freq_hashtags(tweets, with_prefix: true, use_regexp: false, debug: false)
+          puts "tweets: #{tweets.size}" if debug
+          return {} if tweets.blank?
+
+          prefix = %w(# ＃)
+          regexp = /[#＃]([Ａ-Ｚａ-ｚA-Za-z_一-鿆0-9０-９ぁ-ヶｦ-ﾟー]+)/
+
+          tweets =
+            if use_regexp
+              tweets.select { |t| t.text && prefix.any? { |char| t.text.include?(char)} }
+            else
+              tweets.select { |t| include_hashtags?(t) }
+            end
+          puts "tweets with hashtag: #{tweets.size}" if debug
+
+          hashtags =
+            if use_regexp
+              tweets.map { |t| t.text.scan(regexp).flatten.map(&:strip) }
+            else
+              tweets.map { |t| extract_hashtags(t) }
+            end.flatten
+          hashtags = hashtags.map { |h| "#{prefix[0]}#{h}" } if with_prefix
+
+          hashtags.each_with_object(Hash.new(0)) { |h, memo| memo[h] += 1 }.sort_by { |k, v| [-v, -k.size] }.to_h
+        end
+
+        def hashtag_clusters(hashtags, limit: 10, debug: false)
+          puts "hashtags: #{hashtags.take(10)}" if debug
+
+          hashtag, count = hashtags.take(3).each_with_object(Hash.new(0)) do |tag, memo|
+            tweets = search(tag)
+            puts "tweets #{tag}: #{tweets.size}" if debug
+            memo[tag] = count_freq_hashtags(tweets).reject { |t, c| t == tag }.values.sum
+          end.max_by { |_, c| c }
+
+          hashtags = count_freq_hashtags(search(hashtag)).reject { |t, c| t == hashtag }.keys
+          queries = hashtags.take(3).combination(2).map { |ary| ary.join(' AND ') }
+          puts "selected #{hashtag}: #{queries.inspect}" if debug
+
+          tweets = queries.map { |q| search(q) }.flatten
+          puts "tweets #{queries.inspect}: #{tweets.size}" if debug
+
+          if tweets.empty?
+            tweets = search(hashtag)
+            puts "tweets #{hashtag}: #{tweets.size}" if debug
+          end
+
+          members = tweets.map { |t| t.user }
+          puts "members count: #{members.size}" if debug
+
+          count_freq_words(members.map { |m| m.description  }, special_words: PROFILE_SPECIAL_WORDS, exclude_words: PROFILE_EXCLUDE_WORDS, special_regexp: PROFILE_SPECIAL_REGEXP, exclude_regexp: PROFILE_EXCLUDE_REGEXP, debug: debug).take(limit)
+        end
+
+        def fetch_lists(user, debug: false)
+          memberships(user, count: 500, call_limit: 2).sort_by { |li| li.member_count }
+        rescue Twitter::Error::ServiceUnavailable => e
+          puts "#{__method__}: #{e.class} #{e.message} #{user.inspect}" if debug
+          []
+        end
+
+        def list_clusters(lists, shrink: false, shrink_limit: 100, list_member: 300, total_member: 3000, total_list: 50, rate: 0.3, limit: 10, debug: false)
+          lists = lists.sort_by { |li| li.member_count }
+          puts "lists: #{lists.size} (#{lists.map { |li| li.member_count }.join(', ')})" if debug
+          return {} if lists.empty?
+
+          open('lists.txt', 'w') {|f| f.write lists.map(&:full_name).join("\n") } if debug
+
+          list_special_words = %w()
+          list_exclude_regexp = %r(list[0-9]*|people-ive-faved|twizard-magic-list|my-favstar-fm-list|timeline-list|conversationlist|who-i-met)
+          list_exclude_words = %w(it list people who met)
+
+          # リスト名を - で分割 -> 1文字の単語を除去 -> 出現頻度の降順でソート
+          words = lists.map { |li| li.full_name.split('/')[1] }.
+            select { |n| !n.match(list_exclude_regexp) }.
+            map { |n| n.split('-') }.flatten.
+            delete_if { |w| w.size < 2 || list_exclude_words.include?(w) }.
+            map { |w| SYNONYM_WORDS.has_key?(w) ? SYNONYM_WORDS[w] : w }.
+            each_with_object(Hash.new(0)) { |w, memo| memo[w] += 1 }.
+            sort_by { |k, v| [-v, -k.size] }
+
+          puts "words: #{words.take(10)}" if debug
+          return {} if words.empty?
+
+          # 出現頻度の高い単語を名前に含むリストを抽出
+          _words = []
+          lists =
+            filter(lists, min: 2) do |li, i|
+              _words = words[0..i].map(&:first)
+              name = li.full_name.split('/')[1]
+              _words.any? { |w| name.include?(w) }
+            end
+          puts "lists include #{_words.inspect}: #{lists.size} (#{lists.map { |li| li.member_count }.join(', ')})" if debug
+          return {} if lists.empty?
+
+          # 中間の 25-75% のリストを抽出
+          while lists.size > shrink_limit
+            percentile25 = ((lists.length * 0.25).ceil) - 1
+            percentile75 = ((lists.length * 0.75).ceil) - 1
+            lists = lists[percentile25..percentile75]
+            puts "lists sliced by 25-75 percentile: #{lists.size} (#{lists.map { |li| li.member_count }.join(', ')})" if debug
+          end if shrink || lists.size > shrink_limit
+
+          # メンバー数がしきい値より少ないリストを抽出
+          _list_member = 0
+          _min_list_member = 10 < lists.size ? 10 : 0
+          _lists =
+            filter(lists, min: 2) do |li, i|
+              _list_member = list_member * (1.0 + 0.25 * i)
+              _min_list_member < li.member_count && li.member_count < _list_member
+            end
+          lists = _lists.empty? ? [lists[0]] : _lists
+          puts "lists limited by list member #{_min_list_member}..#{_list_member.round}: #{lists.size} (#{lists.map { |li| li.member_count }.join(', ')})" if debug
+          return {} if lists.empty?
+
+          # トータルメンバー数がしきい値より少なくなるリストを抽出
+          _lists = []
+          lists.size.times do |i|
+            _lists = lists[0..(-1 - i)]
+            if _lists.map { |li| li.member_count }.sum < total_member
+              break
+            else
+              _lists = []
+            end
+          end
+          lists = _lists.empty? ? [lists[0]] : _lists
+          puts "lists limited by total members #{total_member}: #{lists.size} (#{lists.map { |li| li.member_count }.join(', ')})" if debug
+          return {} if lists.empty?
+
+          # リスト数がしきい値より少なくなるリストを抽出
+          if lists.size > total_list
+            lists = lists[0..(total_list - 1)]
+          end
+          puts "lists limited by total lists #{total_list}: #{lists.size} (#{lists.map { |li| li.member_count }.join(', ')})" if debug
+          return {} if lists.empty?
+
+          members = lists.map do |li|
+            begin
+              list_members(li.id)
+            rescue Twitter::Error::NotFound => e
+              puts "#{__method__}: #{e.class} #{e.message} #{li.id} #{li.full_name} #{li.mode}" if debug
+              nil
+            end
+          end.compact.flatten
+          puts "candidate members: #{members.size}" if debug
+          return {} if members.empty?
+
+          open('members.txt', 'w') {|f| f.write members.map{ |m| m.description.gsub(/\R/, ' ') }.join("\n") } if debug
+
+          3.times do
+            _members = members.each_with_object(Hash.new(0)) { |member, memo| memo[member] += 1 }.
+              select { |_, v| lists.size * rate < v }.keys
+            if _members.size > 100
+              members = _members
+              break
+            else
+              rate -= 0.05
+            end
+          end
+          puts "members included multi lists #{rate.round(3)}: #{members.size}" if debug
+
+          count_freq_words(members.map { |m| m.description }, special_words: PROFILE_SPECIAL_WORDS, exclude_words: PROFILE_EXCLUDE_WORDS, special_regexp: PROFILE_SPECIAL_REGEXP, exclude_regexp: PROFILE_EXCLUDE_REGEXP, debug: debug).take(limit)
+        end
+
+        private
+
+        def filter(lists, min:)
+          min = [min, lists.size].min
+          _lists = []
+          3.times do |i|
+            _lists = lists.select { |li| yield(li, i) }
+            break if _lists.size >= min
+          end
+          _lists
+        end
+
+        def count_by_word(texts, delim: nil, tagger: nil, min_length: 2, max_length: 5, special_words: [], exclude_words: [], special_regexp: nil, exclude_regexp: nil)
+          texts = texts.dup
+
+          frequency = Hash.new(0)
+          if special_words.any?
+            texts.each do |text|
+              special_words.map { |sw| [sw, text.scan(sw)] }
+                .delete_if { |_, matched| matched.empty? }
+                .each_with_object(frequency) { |(word, matched), memo| memo[word] += matched.size }
+
+            end
+          end
+
+          if exclude_regexp
+            texts = texts.map { |t| t.remove(exclude_regexp) }
+          end
+
+          if delim
+            texts = texts.map { |t| t.split(delim) }.flatten.map(&:strip)
+          end
+
+          if tagger
+            texts = texts.map { |t| tagger.parse(t).split("\n") }.flatten.
+              select { |line| line.include?('名詞') }.
+              map { |line| line.split("\t")[0] }
+          end
+
+          texts.delete_if { |w| w.empty? || w.size < min_length || max_length < w.size || exclude_words.include?(w) || w.match(/\d{2}/) }.
+            each_with_object(frequency) { |word, memo| memo[word] += 1 }.
+            sort_by { |k, v| [-v, -k.size] }.to_h
+        end
+
+        def count_freq_words(texts, special_words: [], exclude_words: [], special_regexp: nil, exclude_regexp: nil, debug: false)
+          candidates, remains = texts.partition { |desc| desc.scan('/').size > 2 }
+          slash_freq = count_by_word(candidates, delim: '/', exclude_regexp: exclude_regexp)
+          puts "words splitted by /: #{slash_freq.take(10)}" if debug
+
+          candidates, remains = remains.partition { |desc| desc.scan('|').size > 2 }
+          pipe_freq = count_by_word(candidates, delim: '|', exclude_regexp: exclude_regexp)
+          puts "words splitted by |: #{pipe_freq.take(10)}" if debug
+
+          noun_freq = count_by_word(remains, tagger: build_tagger, special_words: special_words, exclude_words: exclude_words, special_regexp: special_regexp, exclude_regexp: exclude_regexp)
+          puts "words tagged as noun: #{noun_freq.take(10)}" if debug
+
+          slash_freq.merge(pipe_freq) { |_, old, neww| old + neww }.
+            merge(noun_freq) { |_, old, neww| old + neww }.sort_by { |k, v| [-v, -k.size] }
+        end
+
+        def build_tagger
+          require 'mecab'
+          MeCab::Tagger.new("-d #{`mecab-config --dicdir`.chomp}/mecab-ipadic-neologd/")
+        rescue => e
+          puts "Add gem 'mecab' to your Gemfile."
+          raise e
+        end
+
+        def include_hashtags?(tweet)
+          tweet.entities&.hashtags&.any?
+        end
+
+        def extract_hashtags(tweet)
+          tweet.entities.hashtags.map { |h| h.text }
+        end
+
+        SYNONYM_WORDS = (
+          %w(cosplay cosplayer cosplayers coser cos こすぷれ コスプレ レイヤ レイヤー コスプレイヤー レイヤーさん).map { |w| [w, 'coplay'] } +
+          %w(tsukuba tkb).map { |w| [w, 'tsukuba'] } +
+          %w(waseda 早稲田 早稲田大学).map { |w| [w, 'waseda'] } +
+          %w(keio 慶應 慶應義塾).map { |w| [w, 'keio'] } +
+          %w(gakusai gakuensai 学祭 学園祭).map { |w| [w, 'gakusai'] } +
+          %w(kosen kousen).map { |w| [w, 'kosen'] } +
+          %w(anime アニメ).map { |w| [w, 'anime'] } +
+          %w(photo photos).map { |w| [w, 'photo'] } +
+          %w(creator creater クリエイター).map { |w| [w, 'creator'] } +
+          %w(illustrator illustrater 絵師).map { |w| [w, 'illustrator'] } +
+          %w(artist art artists アート 芸術).map { |w| [w, 'artist'] } +
+          %w(design デザイン).map { |w| [w, 'design'] } +
+          %w(kawaii かわいい).map { |w| [w, 'kawaii'] } +
+          %w(idol あいどる アイドル 美人).map { |w| [w, 'idol'] } +
+          %w(music musician musicians dj netlabel label レーベル おんがく 音楽家 音楽).map { |w| [w, 'music'] } +
+          %w(engineer engineers engineering えんじにあ tech 技術 技術系 hacker coder programming programer programmer geek rubyist ruby scala java lisp).map { |w| [w, 'engineer'] } +
+          %w(internet インターネット).map { |w| [w, 'internet'] }
+        ).to_h
+
+        def normalize_synonym(words)
+          words.map { |w| SYNONYM_WORDS.has_key?(w) ? SYNONYM_WORDS[w] : w }
+        end
+      end
+    end
+  end
+end

data/lib/twitter_friendly/rest/extension/timelines.rb

@@ -0,0 +1,129 @@
+module TwitterFriendly
+  module REST
+    module Extension
+      module Timelines
+
+        EVERY_DAY = (0..6)
+        WDAY_COUNT = EVERY_DAY.map { |n| [n, 0] }.to_h
+        WDAY_NIL_COUNT = EVERY_DAY.map { |n| [n, nil] }.to_h
+
+        EVERY_HOUR = (0..23)
+        HOUR_COUNT = EVERY_HOUR.map { |n| [n, 0] }.to_h
+        HOUR_NIL_COUNT = EVERY_HOUR.map { |n| [n, nil] }.to_h
+
+        def count_wday(times)
+          times.each_with_object(WDAY_COUNT.dup) { |time, memo| memo[time.wday] += 1 }
+        end
+
+        def count_hour(times)
+          times.each_with_object(HOUR_COUNT.dup) { |time, memo| memo[time.hour] += 1 }
+        end
+
+        # [
+        #   {:name=>"Sun", :y=>111, :drilldown=>"Sun"},
+        #   {:name=>"Mon", :y=>95,  :drilldown=>"Mon"},
+        #   {:name=>"Tue", :y=>72,  :drilldown=>"Tue"},
+        #   {:name=>"Wed", :y=>70,  :drilldown=>"Wed"},
+        #   {:name=>"Thu", :y=>73,  :drilldown=>"Thu"},
+        #   {:name=>"Fri", :y=>81,  :drilldown=>"Fri"},
+        #   {:name=>"Sat", :y=>90,  :drilldown=>"Sat"}
+        # ]
+        def usage_stats_wday_series_data(times, day_names:)
+          count_wday(times).map do |wday, count|
+            {name: day_names[wday], y: count, drilldown: day_names[wday]}
+          end
+        end
+
+        # [
+        #   {
+        #     :name=>"Sun",
+        #     :id=>"Sun",
+        #     :data=> [ ["0", 7], ["1", 12], ... , ["22", 10], ["23", 12] ]
+        #   },
+        #   ...
+        #   {
+        #     :name=>"Mon",
+        #     :id=>"Mon",
+        #     :data=> [ ["0", 22], ["1", 11], ... , ["22", 9], ["23", 14] ]
+        #   }
+        def usage_stats_wday_drilldown_series(times, day_names:)
+          counts =
+            EVERY_DAY.each_with_object(WDAY_NIL_COUNT.dup) do |wday, memo|
+              memo[wday] = count_hour(times.select { |t| t.wday == wday })
+            end
+
+          counts.map { |wday, hour_count| [day_names[wday], hour_count] }.map do |wday, hour_count|
+            {name: wday, id: wday, data: hour_count.map { |hour, count| [hour.to_s, count] }}
+          end
+        end
+
+        # [
+        #   {:name=>"0", :y=>66, :drilldown=>"0"},
+        #   {:name=>"1", :y=>47, :drilldown=>"1"},
+        #   ...
+        #   {:name=>"22", :y=>73, :drilldown=>"22"},
+        #   {:name=>"23", :y=>87, :drilldown=>"23"}
+        # ]
+        def usage_stats_hour_series_data(times)
+          count_hour(times).map do |hour, count|
+            {name: hour.to_s, y: count, drilldown: hour.to_s}
+          end
+        end
+
+        # [
+        #   {:name=>"0", :id=>"0", :data=>[["Sun", 7], ["Mon", 22], ["Tue", 8], ["Wed", 9], ["Thu", 9], ["Fri", 6], ["Sat", 5]]},
+        #   {:name=>"1", :id=>"1", :data=>[["Sun", 12], ["Mon", 11], ["Tue", 5], ["Wed", 5], ["Thu", 0], ["Fri", 8], ["Sat", 6]]},
+        #   ...
+        # ]
+        def usage_stats_hour_drilldown_series(times, day_names:)
+          counts =
+            EVERY_HOUR.each_with_object(HOUR_NIL_COUNT.dup) do |hour, memo|
+              memo[hour] = count_wday(times.select { |t| t.hour == hour })
+            end
+
+          counts.map do |hour, wday_count|
+            {name: hour.to_s, id: hour.to_s, data: wday_count.map { |wday, count| [day_names[wday], count] }}
+          end
+        end
+
+        # [
+        #   {:name=>"Sun", :y=>14.778310502283107},
+        #   {:name=>"Mon", :y=>12.273439878234399},
+        #   {:name=>"Tue", :y=>10.110578386605784},
+        #   {:name=>"Wed", :y=>9.843683409436835},
+        #   {:name=>"Thu", :y=>10.547945205479452},
+        #   {:name=>"Fri", :y=>10.61773211567732},
+        #   {:name=>"Sat", :y=>12.115753424657534}
+        # ]
+        def twitter_addiction_series(times, day_names:)
+          max_duration = 5.minutes
+          wday_count =
+            EVERY_DAY.each_with_object(WDAY_NIL_COUNT.dup) do |wday, memo|
+              target_times = times.select { |t| t.wday == wday }
+              memo[wday] =
+                if target_times.empty?
+                  nil
+                else
+                  target_times.each_cons(2).map { |newer, older| (newer - older) < max_duration ? newer - older : max_duration }.sum
+                end
+            end
+          days = times.map { |t| t.to_date.to_s(:long) }.uniq.size
+          weeks = [days / 7.0, 1.0].max
+          wday_count.map do |wday, seconds|
+            {name: day_names[wday], y: (seconds.nil? ? nil : seconds / weeks / 60)}
+          end
+        end
+
+        def usage_stats(tweet_times, day_names: %w(Sun Mon Tue Wed Thu Fri Sat))
+          [
+            usage_stats_wday_series_data(tweet_times, day_names: day_names),
+            usage_stats_wday_drilldown_series(tweet_times, day_names: day_names),
+            usage_stats_hour_series_data(tweet_times),
+            usage_stats_hour_drilldown_series(tweet_times, day_names: day_names),
+            twitter_addiction_series(tweet_times, day_names: day_names)
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/twitter_friendly/rest/favorites.rb

@@ -4,11 +4,10 @@ module TwitterFriendly
 
       MAX_TWEETS_PER_REQUEST = 100
 
-      %i(favorites).each do |name|
-        define_method(name) do |*args|
-          args << {result_type: :recent}.merge(args.extract_options!)
-          fetch_tweets_with_max_id(name, args, MAX_TWEETS_PER_REQUEST)
-        end
+      def favorites(*args)
+        options = {result_type: :recent}.merge(args.extract_options!)
+        push_operations(options, __method__)
+        fetch_tweets_with_max_id(__method__, MAX_TWEETS_PER_REQUEST, args[0], options)
       end
     end
   end

data/lib/twitter_friendly/rest/friends_and_followers.rb

@@ -7,39 +7,58 @@ module TwitterFriendly
 
       MAX_IDS_PER_REQUEST = 5000
 
-      %i(friend_ids follower_ids).each do |name|
-        define_method(name) do |*args|
-          options = {count: MAX_IDS_PER_REQUEST}.merge(args.extract_options!)
-          if options[:super_operation]
-            options[:super_super_operation] = options[:super_operation]
-            options[:super_operation] = name
-          end
-          args << options
-          fetch_resources_with_cursor(name, args)
-        end
+      # @return [Hash]
+      #
+      # @overload friend_ids(options = {})
+      # @overload friend_ids(user, options = {})
+      #
+      # @param user [Integer, String] A Twitter user ID or screen name.
+      #
+      # @option options [Integer] :count The number of tweets to return per page, up to a maximum of 5000.
+      def friend_ids(*args)
+        options = {count: MAX_IDS_PER_REQUEST}.merge(args.extract_options!)
+        push_operations(options, __method__)
+        fetch_resources_with_cursor(__method__, args[0], options)
+      end
+
+      def follower_ids(*args)
+        options = {count: MAX_IDS_PER_REQUEST}.merge(args.extract_options!)
+        push_operations(options, __method__)
+        fetch_resources_with_cursor(__method__, args[0], options)
       end
 
+      # @return [Hash]
+      #
+      # @overload friends(options = {})
+      # @overload friends(user, options = {})
+      #
+      # @param user [Integer, String] A Twitter user ID or screen name.
+      #
+      # @option options [Bool] :parallel
       def friends(*args)
-        options = args.extract_options!.merge(super_operation: :friends)
-        ids = friend_ids(*args, options)
+        options = {parallel: true}.merge(args.extract_options!)
+        push_operations(options, __method__)
+        ids = friend_ids(*args, options.except(:parallel))
         users(ids, options)
       end
 
       def followers(*args)
-        options = args.extract_options!.merge(super_operation: :followers)
-        ids = follower_ids(*args, options)
+        options = {parallel: true}.merge(args.extract_options!)
+        push_operations(options, __method__)
+        ids = follower_ids(*args, options.except(:parallel))
         users(ids, options)
       end
 
       def friend_ids_and_follower_ids(*args)
-        options = {super_operation: :friend_ids_and_follower_ids, parallel: true}.merge(args.extract_options!)
+        options = { parallel: true}.merge(args.extract_options!)
+        is_parallel = options.delete(:parallel)
 
-        if options[:parallel]
+        if is_parallel
           require 'parallel'
 
           parallel(in_threads: 2) do |batch|
-            batch.friend_ids(*args, options)
-            batch.follower_ids(*args, options)
+            batch.friend_ids(*args, options.merge(super_operation: [__method__]))
+            batch.follower_ids(*args, options.merge(super_operation: [__method__]))
           end
         else
           [friend_ids(*args, options), follower_ids(*args, options)]

data/lib/twitter_friendly/rest/lists.rb

@@ -4,18 +4,34 @@ module TwitterFriendly
 
       MAX_LISTS_PER_REQUEST = 1000
 
-      # Returns the lists the specified user has been added to.
+      # @return [Hash] The lists the specified user has been added to.
+      #
+      # @overload list_members(options = {})
+      # @overload list_members(user, options = {})
+      #
+      # @param user [Integer, String] A Twitter user ID or screen name.
+      #
+      # @option options [Integer] :count The number of tweets to return per page, up to a maximum of 5000.
       def memberships(*args)
-        args << {count: MAX_LISTS_PER_REQUEST}.merge(args.extract_options!)
-        fetch_resources_with_cursor(__method__, args)
+        options = {count: MAX_LISTS_PER_REQUEST}.merge(args.extract_options!)
+        push_operations(options, __method__)
+        fetch_resources_with_cursor(__method__, args[0], options)
       end
 
       MAX_MEMBERS_PER_REQUEST = 5000
 
-      # Returns the members of the specified list.
+      # @return [Hash] The members of the specified list.
+      #
+      # @overload list_members(options = {})
+      # @overload list_members(user, options = {})
+      #
+      # @param list [Integer, String] A Twitter user ID or screen name.
+      #
+      # @option options [Integer] :count The number of tweets to return per page, up to a maximum of 5000.
       def list_members(*args)
-        args << {count: MAX_MEMBERS_PER_REQUEST, skip_status: 1}.merge(args.extract_options!)
-        fetch_resources_with_cursor(__method__, args)
+        options = {count: MAX_MEMBERS_PER_REQUEST, skip_status: 1}.merge(args.extract_options!)
+        push_operations(options, __method__)
+        fetch_resources_with_cursor(__method__, args[0], options)
       end
     end
   end

data/lib/twitter_friendly/rest/parallel.rb

@@ -14,14 +14,19 @@ module TwitterFriendly
 
       class Arguments < Array
         %i(
-        users
-        friend_ids
-        follower_ids
-        friends
-        followers
-      ).each do |name|
+          users
+          friend_ids
+          follower_ids
+          friends
+          followers
+          home_timeline
+          user_timeline
+          mentions_timeline
+          search
+          favorites
+        ).each do |name|
           define_method(name) do |*args|
-            send(:<< , [name, *args])
+            send(:<<, [name, *args])
           end
         end
       end

data/lib/twitter_friendly/rest/search.rb

@@ -4,12 +4,11 @@ module TwitterFriendly
 
       MAX_TWEETS_PER_REQUEST = 100
 
-      %i(search).each do |name|
-        define_method(name) do |query, options = {}|
-          raise ArgumentError.new('You must specify a search query.') unless query.is_a?(String)
-          args = [query, {result_type: :recent}.merge(options)]
-          fetch_tweets_with_max_id(name, args, MAX_TWEETS_PER_REQUEST)
-        end
+      def search(query, options = {})
+        raise ArgumentError.new('You must specify a search query.') unless query.is_a?(String)
+        options = {result_type: :recent}.merge(options)
+        push_operations(options, __method__)
+        fetch_tweets_with_max_id(__method__, MAX_TWEETS_PER_REQUEST, query, options)
       end
     end
   end

data/lib/twitter_friendly/rest/timelines.rb

@@ -4,11 +4,22 @@ module TwitterFriendly
 
       MAX_TWEETS_PER_REQUEST = 200
 
-      %i(home_timeline user_timeline mentions_timeline).each do |name|
-        define_method(name) do |*args|
-          args << {include_rts: true}.merge(args.extract_options!)
-          fetch_tweets_with_max_id(name, args, MAX_TWEETS_PER_REQUEST)
-        end
+      def home_timeline(options = {})
+        options = {include_rts: true}.merge(options)
+        push_operations(options, __method__)
+        fetch_tweets_with_max_id(__method__, MAX_TWEETS_PER_REQUEST, nil, options)
+      end
+
+      def user_timeline(*args)
+        options = {include_rts: true}.merge(args.extract_options!)
+        push_operations(options, __method__)
+        fetch_tweets_with_max_id(__method__, MAX_TWEETS_PER_REQUEST, args[0], options)
+      end
+
+      def mentions_timeline(options = {})
+        options = {include_rts: true}.merge(options)
+        push_operations(options, __method__)
+        fetch_tweets_with_max_id(__method__, MAX_TWEETS_PER_REQUEST, nil, options)
       end
     end
   end