tweepy官方文檔中文版

　　本文主要內容來自 tweepy 官方文檔，加入了一些必要的解釋說明並剔除冗余的句子，便於國內用戶參閱使用。

　　純手工碼字，支持原創，轉載請注明出處。

tweepy官方文檔：http://docs.tweepy.org/en/latest/getting_started.html

what's the tweepy?

　　tweepy 是專門用於在 Python 中處理 Twitter API 的模塊。，使用方式相當簡潔，省去了手動開發 Twitter 爬蟲的成本。

　　抓取 Twitter 數據的重點是 twitter 要求所有請求都必須經過 OAuth 認證，而 tweepy 這個包提供專門的 auth 功能，在這方面的設定讓 authentication 變得十分方便。

注意：國內 Twitter 是被牆的，所以即使使用 tweepy 也必定要面對無法連接成功的狀況。記得提前架好梯子。

 

安裝

pip install tweepy

 

秘鑰

　　使用前需要現在 Twitter  官網上申請好秘鑰，用於鑒權。

consumer_key = 'xxxxxxxxx'
consumer_secret = 'xxxxxxxxx'
access_token = 'xxxxxxxxx'
access_token_secret = 'xxxxxxxxx'

 

簡單的例子

import tweepy

auth = tweepy.OAuthHandler(consumer_key, consumer_secret)
auth.set_access_token(access_token, access_token_secret)

api = tweepy.API(auth)

public_tweets = api.home_timeline()
for tweet in public_tweets:
    print(tweet.text)

 

API

　　API 類提供對整個 twitter restapi 方法的訪問。每個方法都可以接受各種參數並返回響應。下文會着重介紹。

　　tweepy 同時也支持長鏈接的形式得到即時信息。下文 stream 會介紹。

 

返回值

　　tweepy API 的返回值一般都是對象，不同的對象取值字段不同，具體需要自己 debug

• 推文相關—— Status 對象
• 用戶相關的—— User 對象
• 好友相關的—— FriendShip 對象
• 搜索記錄相關的—— SavedSearch 對象

 

一、身份驗證

　　tweepy 提供兩種鑒權方式：application-user 和  application-only，操作的是 tweepy.AuthHandler 類的對象

• 鑒權1——application-user

  # 1.綁定公鑰
  auth = tweepy.OAuthHandler(consumer_key, consumer_secret)
  # 使用回調函數：auth = tweepy.OAuthHandler(consumer_key, consumer_secret, callback_url)
  
  # 2.綁定私鑰
  # ---- 方式一：知道私鑰，直接綁定
  auth.set_access_token(access_token, access_token_secret)
  # ---- 方式二：不知道私鑰，先獲取后綁定
  redirect_user(auth.get_authorization_url())
  auth.get_access_token("verifier_value")
  
  # 3.構造api
  api = tweepy.API(auth)

   

• 鑒權2——application-only：這種方式不需要綁定私鑰，用於只需要讀權限的操作

  auth = tweepy.AppAuthHandler(consumer_key, consumer_secret)
  api = tweepy.API(auth)
  # 搜索關鍵詞tweepy
  for tweet in tweepy.Cursor(api.search, q='tweepy').items(10):
      print(tweet.text)

   

二、分頁

　　有時候 Twitter 的數據量相當的龐大，所以會需要經常使用分頁。比如遍歷時間線、用戶列表、直接消息等操作。

　　tweepy 為我們提供了很便捷的分頁功能。

示例：迭代經過身份驗證的用戶（即當前秘鑰對應的用戶）時間線中的狀態

# 操作所有時間線
for status in tweepy.Cursor(api.user_timeline).items():
    # process status here
    process_status(status)

# 操作每一頁
for page in tweepy.Cursor(api.user_timeline).pages():
    # page is a list of statuses
    process_page(page)

# 操作前200條
for status in tweepy.Cursor(api.user_timeline).items(200):
    process_status(status)

# 操作前3頁
for page in tweepy.Cursor(api.user_timeline).pages(3):
    process_page(page)

 

三、粉絲

　　tweepy 可以獲得指定用戶的粉絲數、粉絲們，並進行粉的操作

# 獲取我的粉絲
fs = tweepy.Cursor(api.followers)
for follower in fs.items():
    follower.follow() # 粉

 

　　粉絲數量很多的情況下可以使用生成器

# 函數封裝了生成器下一頁功能，但是如果已處於最后一頁卻還執行下一頁會報錯，這里加了容錯處理
def limit_handled(cursor):
    while True:
        try:
            yield cursor.next() # 生成器下一頁功能
        except tweepy.RateLimitError:
            time.sleep(15 * 60)

# 輸出好友數量小於300的用戶昵稱
for follower in limit_handled(tweepy.Cursor(api.followers).items()):
    if follower.friends_count < 300:
        print(follower.screen_name)

 

四、流媒體 stream

　　tweepy 提供類似於 websocket 的長鏈接功能，稱之為 stream。客戶端在通過身份驗證和基本的連接之后可以被動實時的獲得數據，比如：關注特朗普的推特，當特朗普發推時我們的程序就能收到；或者監聽指定關鍵詞比如新冠肺炎，只要有包含關鍵詞的推文我們就能收到。

　　stream 和 Rest api 不同，前者是長鏈接被動獲取實時獲取數據，后者則是主動請求以獲得數據。

　　tweepy 實現了 StreamListener 類，我們想要實現 stream 的功能只要繼承這個類並重寫它的 on_status 方法即可，on_status 方法會在得到數據時被調用

import tweepy

# 繼承 StreamListener
class MyStreamListener(tweepy.StreamListener):
    #重寫 on_status
    def on_status(self, status):
        print(status.text)  
        # status 是一個對象，里面包含了該條推文的所有字段，比如推文內容、點贊數、評論數、作者id、作者昵稱、作者粉絲數等等

    # 當流媒體出錯時被調用，如：身份驗證失敗、網絡錯誤等等
    def on_error(self, status_code):
        if status_code == 420:
            return False #returning False in on_error disconnects the stream

# 實例化
myStreamListener = MyStreamListener()
# 身份驗證，綁定監聽流媒體
myStream = tweepy.Stream(auth = api.auth, listener=myStreamListener)
# --- 監聽關鍵詞Python相關的推文
myStream.filter(track=['python'])
# --- 關注某推特用戶，只能通過ID
myStream.filter(follow=["2211149702"])
# --- 支持異步，參數is_async，推薦使用異步形式
myStream.filter(track=['python'], is_async=True)

# 關閉流媒體的監聽
myStream.disconnect()

注：更多信息需要自行查看源碼，源碼並不是很難讀

 

五、REST API

　　tweepy 提供了一系列 API，基本全面支持 Twitter 網站的功能

 

5.1 時間線相關

API	說明	參數	返回值
API.home_timeline([since_id][, max_id][, count][, page])	返回身份驗證用戶及其朋友發布的20個最新狀態，包括轉發。這相當於Web上的/timeline/home	since_id – 指定起始ID max_id – 指定最大ID，只返回比該ID小的 count – 指定檢索的數量 page – 指定頁碼，注意頁數限制	list，元素是status對象
API.statuses_lookup(id_[, include_entities][, trim_user][, map_] [, include_ext_alt_text][, include_card_uri])	返回指定推特的詳情，最多一百條，由id_參數指定	id_ – 存放推特id的列表，最多100個id include_entities –默認為True，當設置為False時返回值中不包含entities trim_user –默認為False，用於指定返回值中是否包含推文用戶的信息 map_ – 是否包含無法顯示的推文，默認是False include_ext_alt_text – If alt text has been added to any attached media entities, this parameter will return an ext_alt_text value in the top-level key for the media entity. include_card_uri – 是否包含card_uri	list，元素是status對象
API.user_timeline([id/user_id/screen_name][, since_id][, max_id][, count][, page])	返回身份驗證用戶或指定用戶發布的20個最新狀態。也可以通過id參數獲取指定用戶的時間線	id – 指定用戶的id或昵稱 user_id – 指定用戶的ID，當有效的用戶ID也是有效的昵稱時，有助於消除歧義 screen_name – 指定用戶的昵稱 since_id – 指定起始ID max_id – 指定最大ID，只返回比該ID小的 count – 指定檢索的數量 page – 指定頁碼，注意頁數限制	list，元素是status對象
API.retweets_of_me([since_id][, max_id][, count][, page])	返回已驗證用戶最近轉發的20條推文	since_id – 指定起始ID max_id – 指定最大ID，只返回比該ID小的 count – 指定檢索的數量 page – 指定頁碼，注意頁數限制	list，元素是status對象
API.mentions_timeline([since_id][, max_id][, count])	返回最近20次提及，包括轉發	since_id – 指定起始ID max_id – 指定最大ID，只返回比該ID小的 count – 指定檢索的數量	list，元素是status對象

 

5.2 Status 相關（推文）

API	說明	參數	返回值
API.get_status(id[, trim_user] [, include_my_retweet] [, include_entities] [, include_ext_alt_text] [, include_card_uri])	返回由指定ID的推文詳情	id – 指定推文ID. trim_user – 默認為False，用於指定返回值中是否包含推文用戶的信息 include_my_retweet – 布爾值，是否包含轉發字段 include_entities – 默認為True，當設置為False時返回值中不包含entities include_ext_alt_text – If alt text has been added to any attached media entities, this parameter will return an ext_alt_text value in the top-level key for the media entity. include_card_uri – 是否包含card_uri	status對象
API.update_status(status[, in_reply_to_status_id] [, auto_populate_reply_metadata] [, exclude_reply_user_ids] [, attachment_url] [, media_ids] [, possibly_sensitive] [, lat][, long][, place_id] [, display_coordinates] [, trim_user][, enable_dmcommands] [, fail_dmcommands][, card_uri])	發表推文，注意不可重復發相同推文，否則返回403；不可一次性發布超過限制數量的推文，否則返回403	status – 推文內容 in_reply_to_status_id – 本條推文回復的作者ID。注意：，除非狀態文本中提到此參數引用的Tweet的作者，否則此參數將被忽略。因此，必須在推文中包含@username，其中username是引用Tweet的作者。. auto_populate_reply_metadata – 如果設置為True並與in-reply-to-u status-id一起使用，則會從原始Tweet中查找@提到的，並從那里添加到新Tweet。隨着回復鏈的增長，這個將把@references附加到擴展Tweet的元數據中，直到達到@references的限制。如果原始推文被刪除，回復將失敗。 exclude_reply_user_ids – 當與auto_populate_reply_metadata一起使用時，將從服務器生成的擴展Tweet上的@references前綴中刪除的以逗號分隔的用戶id列表。請注意，不能刪除前導的@notice，因為它會破壞in reply to status id語義。嘗試刪除它將被忽略。 attachment_url – 附件URL，為了使url不計入擴展Tweet的狀態正文中，請提供一個url作為Tweet附件。此URL必須是Tweet永久鏈接或直接消息深度鏈接。任意的非Twitter url必須保留在狀態文本中。傳遞給attachment_url參數的url與Tweet permalink或Direct Message deep link不匹配，將在創建Tweet時失敗並導致異常。 media_ids – 要與推特關聯的媒體ID列表。在Tweet中最多可以包含4張照片、1張動畫GIF或1個視頻。 possibly_sensitive – 如果你上傳的Tweet媒體可能被認為是敏感內容，例如裸體或醫療程序，必須將此值設置為true。 lat – 此Tweet所指位置的緯度。需要在-90.0到+90.0（北為正）范圍內。如果沒有相應的long參數，將忽略它。 long – 此Tweet所指位置的經度。經度的有效范圍是-180.0到+180.0（東為正）。如果超出該范圍，如果不是數字，如果啟用了地理坐標，或者沒有相應的lat參數，則將忽略此參數。 place_id – 世界上的一個地名. display_coordinates – 是否在發送Tweet的確切坐標上加一個pin trim_user – 默認為False，用於指定返回值中是否包含推文用戶的信息 enable_dmcommands – 當設置為true時，啟用用於將直接消息作為狀態文本的一部分發送給用戶的快捷方式命令。如果設置為false，則禁用此行為，並在發布的狀態文本中包含任何前導字符 fail_dmcommands –設置為true時，將導致以shortcode命令開頭的任何狀態文本返回一個API錯誤。當設置為false時，允許在狀態文本中發送shortcode命令並由API執行。 card_uri – Associate an ads card with the Tweet using the card_uri value from any ads card response.	status對象
API.update_with_media(filename[, status] [, in_reply_to_status_id] [, auto_populate_reply_metadata] [, lat][, long][, source][, place_id][, file])	目前已不廢，推薦使用API.media_upload()。 更新已驗證用戶的狀態。重復或太長的狀態將被忽略。	filename – 要上傳的圖像的文件名。這將自動打開，除非指定了文件狀態–狀態更新的文本。 status – 文件內容. in_reply_to_status_id – 答復的推文的id auto_populate_reply_metadata – Whether to automatically include the @mentions in the status metadata. lat – 維度 long – 經度 source – 這個只支持加州，所以咱忽略不用 place_id – 地名ID file – 一個文件對象
API.destroy_status(id)	刪除自己的一條推文	id - 推文id	status對象
API.retweet(id)	轉發	id - 要轉發的推文id	status對象
API.retweeters(id[, cursor][, stringify_ids])	得到轉發了該條推文的用戶id列表最多返回100條	id – 指定推文id cursor – 傳-1則分頁，否則得到指定頁的數據 stringify_ids – 是否將id作為字符串返回	list，元素是status對象
API.retweets(id[, count])	返回指定推特的前count次轉發，最多100	id – 指定推文id count – 數量，小於等於100	list，元素是status對象
API.unretweet(id)	取消轉發	id – 指定推文id	status對象

 

5.3 User 相關（用戶）

API	說明	參數	返回值
API.get_user(id/user_id/screen_name)	返回指定用戶信息	id – 指定用戶ID或昵稱 user_id – 指定用戶ID screen_name – 指定用戶昵稱	user對象
API.me()	返回認證用戶信息	無	user對象
API.friends([id/user_id/screen_name][, cursor] [, skip_status][, include_user_entities])	返回指定用戶的前count個好友，最多100， 如果沒有指定用戶則為當前用戶	id – 指定用戶ID或昵稱 user_id – 指定用戶ID screen_name – 指定用戶昵稱 cursor – 將結果進行分頁 count – 當前頁數量 skip_status – 默認為False，返回值中是否包含status字段 include_user_entities – 默認是True，返回值中是否包含entities字段	list，元素是user對象
API.followers([id/screen_name/user_id][, cursor])	返回指定用戶的follower，最多100， 如果沒有指定用戶則為當前用戶	id – 指定用戶ID或昵稱 user_id – 指定用戶ID screen_name – 指定用戶昵稱 cursor – 將結果進行分頁 count – 當前頁數量 skip_status – 默認為False，返回值中是否包含status字段 include_user_entities – 默認是True，返回值中是否包含entities字段	list，元素是user對象
API.lookup_users([user_ids][, screen_names][, include_entities][, tweet_mode])	返回fully-hydrated用戶，最多100 只能跟蹤受保護的用戶才能看到他們最近的狀態更新。如果不跟蹤受保護的用戶，則其狀態將被刪除。 用戶ID或昵稱的順序可能與返回數組中的用戶順序不匹配。 如果請求的用戶未知、已掛起或已刪除，則不會在結果列表中返回該用戶。 如果返回一個用戶對象不能滿足任何查找條件，則會拋出一個404。	ser_ids – 用戶ID列表，最多100個 screen_names – 用戶昵稱列表，最多100個 include_entities – 默認是True，返回值中是否包含entities字段 tweet_mode – 參數值是compat或extended， compat：包含140個字符的tweet提供兼容模式 extended：包含140個字符的tweet提供擴展模式。	list，元素是user對象
API.search_users(q[, count][, page])	運行類似於“查找人員”按鈕搜索Twitter.com網站； 效果等同於網站上進行用戶搜索。 只能從這個API檢索前1000個匹配項。	q – The query to run against people search. count – 數量，不能大於20 page – 頁碼，注意頁數限制	list，元素是user對象

 

5.4 Direct Message 相關

API	說明	參數	返回值
API.get_direct_message([id][, full_text])	返回指定的 direct message	id – 指定 direct message 的ID full_text –默認為False，是否返回全文信息，False情況下只返回140個字節	DirectMessage對象
API.list_direct_messages([count][, cursor])	返回30天內接受和發送的所有 direct message 默認按時間倒序	count – 當前頁數量 cursor – 分頁	list，元素是DirectMessage對象
API.send_direct_message(recipient_id, text [, quick_reply_type][, attachment_type] [, attachment_media_id])	向指定用戶發送一條 direct message	recipient_id – 接收者ID text – 內容，最多10,000 字符. quick_reply_type – 快速答復的類型，參數值為以下三種 options：Array of Options objects (20 max). text_input：Text Input object. location：Location object. attachment_type – 附件類型， media 或 location. attachment_media_id – 與附件關聯的media的ID，一條 direct message只有一個	DirectMessage對象
API.destroy_direct_message(id)	刪除當前用戶的一條 direct message	id – 指定 direct message 的ID	None

 

5.5 Friendship 相關

API	說明	參數	返回值
API.create_friendship(id/screen_name/user_id[, follow])	與指定用戶建立好友關系（也可以是關注指定好友）	id – 指定用戶ID或昵稱 screen_name – 指定用戶昵稱 user_id – 指定用戶ID follow – 不僅成為好友，而且還關注他	user對象
API.destroy_friendship(id/screen_name/user_id)	刪除指定用戶的好友關系（也可以是取消關注）	id – 指定用戶ID或昵稱 screen_name – 指定用戶昵稱 user_id – 指定用戶ID	user對象
API.show_friendship(source_id/source_screen_name, target_id/target_screen_name)	返回兩個指定用戶的好友關系	source_id – 源用戶ID source_screen_name – 源用戶昵稱 target_id – 目標用戶ID target_screen_name – 目標用戶昵稱	FriendShip對象
API.friends_ids(id/screen_name/user_id[, cursor])	返回關注指定用戶的用戶ID列表（就是粉絲）	id – 指定用戶ID或昵稱 screen_name – 指定用戶昵稱 user_id – 指定用戶ID cursor – 分頁	list，元素是ID
API.followers_ids(id/screen_name/user_id)	返回指定用戶的關注用戶ID列表	id – 指定用戶ID或昵稱 screen_name – 指定用戶昵稱 user_id – 指定用戶ID cursor – 分頁	list，元素是ID

 

5.6 Account 相關（即當前用戶）

API	說明	參數	返回值
API.verify_credentials([include_entities][, skip_status][, include_email])	驗證用戶是否有效	include_entities – 默認為True，當設置為False時返回值中不包含entities skip_status – 默認為False，返回值中是否包含status字段 include_email – 是否包含email字段	user對象或False
API.rate_limit_status()	返回當前用戶的指定API的速率限制	resources – 列表，元素為API。	JSON
API.update_profile_image(filename)	更新頭像，必須是GIF、JPG或PNG	filename – 本地文件的路徑，不能是遠程的URL	user對象
API.update_profile_background_image(filename)	更新背景圖，必須是GIF、JPG或PNG	filename – 本地文件的路徑，不能是遠程的URL	user對象
API.update_profile([name][, url][, location][, description])	設置用戶選項，只能設置在網站設置頁的“帳戶”選項卡下的選項。	name – 20個字符 url – 100個字符，必須是 “http://” 開頭 location – 30個字符 description – 160個字符	user對象

 

5.7 Favorite 相關（喜歡的推文）

API	說明	參數	返回值
API.favorites([id][, page])	返回指定用戶喜歡的推文列表，默認為當前用戶	id – 用戶ID或昵稱 page – 頁碼，注意頁數限制	list，元素是status對象
API.create_favorite(id)	喜歡指定推文	id – 推文ID	status對象
API.destroy_favorite(id)	取消喜歡指定推文	id – 推文ID	status對象

 

 

5.8 Block 相關（黑名單）

API	說明	參數	返回值
API.create_block(id/screen_name/user_id)	阻止指定用戶，解除當前用戶與指定用戶的好友關系（黑名單功能）	id – 指定用戶ID或昵稱 screen_name – 指定用戶昵稱 user_id – 指定用戶ID	user對象
API.destroy_block(id/screen_name/user_id)	取消拉黑	id – 指定用戶ID或昵稱 screen_name – 指定用戶昵稱 user_id – 指定用戶ID	user對象
API.blocks([page])	返回黑名單列表	page – 也愛，注意頁數限制	list，元素是user對象
API.blocks_ids([cursor])	返回黑名單ID列表	cursor – 分頁	list，元素是黑名單user的ID

 

5.9 Mute 相關（屏蔽）

API	說明	參數	返回值
API.create_mute(id/screen_name/user_id)	屏蔽指定用戶	id – 指定用戶ID或昵稱 screen_name – 指定用戶昵稱 user_id – 指定用戶ID	user對象
API.destroy_mute(id/screen_name/user_id)	取消屏蔽	id – 指定用戶ID或昵稱 screen_name – 指定用戶昵稱 user_id – 指定用戶ID	user對象
API.mutes([cursor][, include_entities][, skip_status])	返回屏蔽列表	cursor – 頁碼 include_entities – 默認為True，當設置為False時返回值中不包含entities skip_status – 默認為False，返回值中是否包含status字段	list，元素是user對象
API.mutes_ids([cursor])	返回屏蔽ID列表	cursor – 分頁	list，元素是屏蔽user的ID

 

5.10 Spam Reporting 相關（垃圾信息）

API	說明	參數	返回值
API.report_spam(id/screen_name/user_id[, perform_block])	拉黑指定用戶，並發送垃圾報告	id – 指定用戶ID或昵稱 screen_name – 指定用戶昵稱 user_id – 指定用戶ID perform_block – 默認為True，是佛偶舉報該用戶為垃圾郵件用戶	user對象

 

5.11 Saved Searches 相關（保存的搜索，類似於收藏）

API	說明	參數	返回值
API.saved_searches()	返回當前用戶保存的搜索記錄	無	list，元素是SavedSearch對象
API.get_saved_search(id)	返回當前用戶保存的指定搜索記錄	id – 搜索記錄的ID	SavedSearch對象
API.create_saved_search(query)	增加一條搜索記錄	query – 搜索的 query	SavedSearch對象
API.destroy_saved_search(id)	刪除一條保存的搜索記錄，只能刪自己的	id – 搜索記錄的ID	SavedSearch對象

 

5.12 其他

　　剩下的幾個相關的 API 個人覺得基本不會使用，詳情請自行參閱官網

• Help Methods
• List Methods
• Trends Methods
• Geo Methods
• Utility methods
• Media methods

 

ERROR 異常

　　tweepy 提供了幾個異常類，便於我們捕捉異常

tweepy.TweepError

　　涵蓋了幾乎所有 tweepy 的異常

 

tweepy.RateLimitError

　　當 API 訪問量超出限制時會觸發該異常，該異常也可以被 tweepy.TweepError 捕捉到