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