【翻译】Tweepy 3.5.0 Doc (5) API Reference

API Reference

这篇文章涵盖了Tweepy模块一些基本的文档。

tweepy.api -- Twitter API 的封装（wrapper）

class API([auth_handler=None][, host='api.twitter.com'][, search_host='search.twitter.com'][, cache=None][, api_root='/1'][, search_root=''][, retry_count=0][, retry_delay=0][, retry_errors=None][, timeout=60][, parser=ModelParser][, compression=False][, wait_on_rate_limit=False][, wait_on_rate_limit_notify=False][, proxy=None])

这个类封装了Twitter所提供的API。类方法在下面列出。

参数：

auth_handler：此API对象要使用的授权处理器

host：通用API主机，默认值为 'api.twitter.com'

search_host：搜索API主机，默认值为 'search.twitter.com'

cache：缓存后端，默认值为 None

api_root：通用API根路径，默认值为 '/1'

search_root：搜索API根路径，默认值为 ''

retry_count：当error发生时默认额重试次数，默认值为 0

retry_delay：重试间等待时间，默认值为 0

retry_errors：设定遇到那种HTTP状态码时需要重试，默认值为 None

timeout：等待从Twitter返回response所限定的最大等待时间，默认值为 60

parser：用于分隔从Twitter返回的response的对象，默认值为 ModelParser

compression：是否对requests使用GZIP压缩，默认值为 False

wait_on_rate_limit：是否等待rate limits自动补充（这个不太明白），默认值为 False

wait_on_rate_limit_notif：当Tweepy正在等待rate limits补充时是否需要打印通知（notification），默认值为False

proxy：为连接Twitter用的HTTPS代理的完整url，默认值为 None

类方法：

tweepy.api的类方法共有14类，每类下又有不同数量的方法：

1.时间线方法（Timeline methods）:

API.home_timeline：返回最近20条授权用户或者用户好友的状态，包括锐推（转发，retweets）。其作用相当于网页上的 /timeline/home

在这我做了个小实验来理解它的参数：

>>> len(list(api.home_timeline(1,1e19)))
0
>>> len(list(api.home_timeline(1,1e18)))
8
>>> len(list(api.home_timeline(1,1e17)))
0
>>> len(list(api.home_timeline(1e13,1e18)))
8
>>> len(list(api.home_timeline()))
8

API.statuses_lookup：根据指定id每个返回之多100条Tweet对象。

API.user_timeline：返回授权用户或指定用户的最近20条状态。也可以通过id参数请求另一个用户的时间线。

API.retweets_of_me：返回授权用户最近20条被转发过的推文

2.状态方法（Status methods）：

API.get_status：返回id指定用户的当下状态

API.update_status：更新授权用户的状态，重复或者过长的状态将被忽略。

API.update_with_media：更新授权用户的状态，重复或者过长的状态将被忽略。但是这个方法可以上传图像。

API.destroy_status：删除id指定用户的当前状态，但是这条状态的作者必须是授权用户才行。

API.retweet：转发一条推文，id为这条状态的数字编号。

API.retweets：返回一条推文最早至多100条转发。

3.用户方法（User methods）：

API.get_user：返回指定用户的信息。

API.me：返回授权用户的信息。

API.followers：以关注时间先后返回一个用户的关注者。如果参数中没有指定用户id，则默认为是对授权用户而言。

API.search_users：执行和Twitter.com上Find People按钮类似的寻找用户操作，返回和网页搜索一样的结果。另外，从这个API只返回前1000个对应。

4.直接消息方法（Direct Message Methods）：（好像相当于私信）：

API.direct_messages：返回发送给授权用户的direct messages。

API.get_direct_message：根据消息id返回一条特定的direct message。

API.sent_direct_messsages：返回授权用户发出的direct messages。

API.send_direct_message：从授权用户往某特定用户发送一条direct message

API.destroy_direct_message：收回（销毁）一条授权用户收到的direct message

5.好友方法（Friendship Methods）：

API.create_friendship：关注一个特定用户。

API.destroy_friendship：对一个特定用户取消关注。

API.exists_friendship：检查user_a是否关注了user_b。

API.show_friendship：返回两个用户间关系的详细信息。

API.friends_ids：返回特定用户关注的用户的ID的array。

API.followers_ids：返回关注特定用户的用户的ID的array。

6.账户方法（Account Methods）：

API.verify_credentials：验证用户的证书是否有效，如果有效则返回User对象，否则返回False。

API.rate_limit_status()：返回当前时段下载达到API limit之前还能发送的API requests的数量。对此方法的调用不算在rate limit之内。如果提供authentication credential，则返回的是授权用户的rate limit status。否则返回的是请求发送者IP地址的rate limit status。

API.set_delivery_device()：设置Twitter向那个设备为授权用户更新。当参数是“none”时，SMS更新将会停止（不完全明白怎么回事）。

API.update_profile_colors：发送一个或多个16进制数值来控制授权用户profile页的一些板块的颜色。

API.update_profile_image：更新授权用户profile的图像，路径是本地路径，不是url！

API.update_profile_background_image：更新授权用户读背景图像，必须是GIF或JPG或PNG格式。

API.update_profile：这个方法可以设定所有洪湖能在Twitter设置页面Account选项卡下设置的内容。

7.标记喜欢方法（Favorite Methods）：

API.favorites()：返回授权用户或指定用户喜欢的推文（favorite statuses）。

API.create_favorite()：将由参数数字id标识的推文标记为授权用户喜欢的。

API.destroy_favorite()：将授权用户的由参数数字id标识的推文的喜欢标记取消。

8.屏蔽方法（Block Methods）：

API.create_block()：根据ID为授权用户屏蔽此用户，如果授权用户关注这个用户的话，则取消关注。

API.destroy_block()：为授权用户对指定用户取消屏蔽。

API.blocks()：返回被授权用户屏蔽的用户user对象列表。

API.blocks_ids()：返回被授权用户屏蔽的用户id列表。

9.垃圾报告方法（Spam Reporting Methods）：

API.report_spam()：为授权用户屏蔽指定用户并报告此id为垃圾消息源（spammer）。

10.用户搜索存储方法（Saved Searches Methods）：

API.saved_searches()：返回授权用户保存的搜索queries。

API.get_saved_search()：重新得到用id指定的授权用户已保存的搜索的数据。

API.create_saved_search()：为授权用户创建一个保存搜索（saved search）（不知道有什么用）。

API.destroy_saved_search()：为授权用户删除一个保存搜索，且id指定的搜索必须为授权用户所有。

11.帮助方法（Help Methods）：

API.search()：返回匹配特定搜索的推文。

12.列表方法（List Methods）：

API.create_list()：为授权用户创建一个新列表，每个用户至多能有20个列表。

API.destroy_list()：删除一个为授权用户所有的列表。

API.update_list()：更新指定列表。注：这个方法目前会抛出HTTP 500。（Note: this current throws a 500. Twitter is looking into the issue.）

API.lists()：返回指定用户的列表的列表。如果此指定用户就是授权用户，那么私有列表也包括在内。

API.lists_memberships()：返回指定用户增加的列表的列表。

API.lists_subscriptions()：返回指定用户关注的列表的列表。

API.list_timeline()：返回指定列表中用户的推文时间线列表。

API.get_list()：显示指定列表。私有列表不会显示，除非此表属于授权用户。

API.add_list_member()：往指定列表中添加一个成员。授权用户只能往已经存在的列表中添加成员。每个列表最多只能有500个成员。

API.remove_list_member()：从列表中删除某指定成员。只能对授权用户所有的列表进行此操作。

API.list_members()：返回指定列表中的所有成员

API.is_list_member()：检查某用户是否属于指定列表。

API.subscribe_list()：使授权用户关注这个列表。

API.unsubscribe_list()：使授权用户对指定列表取消关注。

API.list_subscribers()：返回此列表的订阅者。

API.is_subscribed_list() ：检查某用户是否订阅了此列表

13.趋势方法（Trends Methods）：

API.trends_available()：返回Twitter上趋势话题信息有关的地点。返回值是一个WOEID（a Yahoo! Where On Earth ID）列表，和其他一些可阅读的信息，比如规范名，地点所在国家之类的。

API.trends_place()：返回指定WOEID码所指地区排名前十位的趋势话题。返回值是一个由 “trend” 对象构成的列表，其中包含了趋势话题的名字，可以用于在TwitterSearch中搜索的query参数，以及Twitter Search URL。这个信息有5分钟的缓存，在短时间内重复发送请求并不能取得更多信息，而且会消耗rate limit。

API.trends_closest()：返回离指定地点最近的有Twitter趋势话题信息的地点。返回值是有WOEID地址信息的列表和其他可读的地址信息。

14.Geo方法（Geo Methods）：

API.reverse_geocode()：对于给定的经纬度，寻找某个可以用来调用update_status()方法的地点ID（不太清楚什么意思。looks for places(cities andneighbourhoods)whose ID's can be specified in a call to update_status () to appear as the name of the location）。这个函数的返回值提供了大量细节。如果不想要有过多细节的返回值，可以考虑使用nearby_places()函数。

API.geo_id()：给定一个地点的id，返回有关此地点的更多详细信息。

tweepy.error -- 异常

tweepy模块提供了一些异常，也就是说在代码中我们不需要导入tweepy.error本身。比如，tweepy.error.TweepError在使用中就是tweepy.TweepError

异常1：TweepError

Tweepy最主要使用的异常，有许多原因都能导致此异常。

当由于Twitter相应而产生TweepError时，此异常有关的信息可在TweepError.message[0]['code']获得。然而同时，TweepError也有可能和其他东西一起抛出，比如message（举例：palin error reason strings）。

异常2：RateLimitError

此异常在API方法达到Twitter相应的上限时抛出。

此异常继承自TweepError，所以TweepError也会获得RateLimitError异常。

翻译自

http://tweepy.readthedocs.io/en/v3.5.0/api.html