Tweepy 快速上手指南API v1.1 与 v2 双接口、模型体系与流式数据消费实战【免费下载链接】tweepyTwitter for Python!项目地址: https://gitcode.com/gh_mirrors/tw/tweepy本篇指南以 docs/getting_started.rst 为核心脉络面向希望用 Tweepy 快速接入 Twitter API 的开发者。你将掌握APIv1.1与Clientv2两个接口的区别与选择、模型对象Model的属性访问与辅助方法用法、基于 OAuth 1.0a 的最小可运行示例以及基于 Streaming HTTP 的StreamingClient实时流式消费方案。文中所有结论均可在当前仓库源码中得到印证。一、Tweepy 的双 API 接口体系Tweepy 同时支持 Twitter API v1.1 与 Twitter API v2二者在仓库中对应两套完全独立的接口API面向 Twitter API v1.1 端点的接口定义于 tweepy/api.py其类文档字符串明确标注为 Twitter API v1.1 Interface。Client面向 Twitter API v2 端点的接口定义于 tweepy/client.py同文件还定义了Response这一 namedtuple包含data、includes、errors、meta四个字段。从 tweepy/init.py 的导出列表可以看到整个包的对外骨架API、Client、StreamingClient以及OAuthHandler、OAuth1UserHandler、OAuth2AppHandler、OAuth2BearerHandler、OAuth2UserHandler等认证处理器还有Cursor、Paginator、Response、StreamResponse、StreamRule等配套类型。当前仓库版本为 4.17.0见tweepy/__init__.py中__version__。选择建议如果需要调用 v1.1 的经典端点时间线、好友关系、直接消息等使用API如果需要调用 v2 的现代端点搜索、用户资料、列表、推文计数等使用Client。二、模型体系请求返回的不是裸 JSON而是模型对象API和Client的方法通常返回Twitter API 对象的模型类实例。每个模型实例封装了 Twitter API 返回的、代表该对象的数据这是 Tweepy 区别于裸 HTTP 调用的核心体验。2.1 获取模型对象以获取用户对象为例# 获取代表 Twitter 用户的 User 对象 user api.get_user(screen_nameTwitter)这里api.get_user定义于 tweepy/api.pyget_user方法带payload(user)装饰器底层调用 v1.1 的users/show端点返回User模型实例。2.2 通过属性/字段访问数据模型对象的数据通过其属性/字段访问部分模型还带有可直接调用的辅助方法print(user.screen_name) print(user.followers_count) for friend in user.friends(): print(friend.screen_name)User模型的实现见 tweepy/models.pyparse类方法将 Twitter 返回的 JSON 逐键转换为实例属性其中created_at会被解析为datetimestatus会被解析为嵌套的Status模型parse_list则将用户列表解析为ResultSet一个增强的列表类型支持按 ID 索引等操作。friends()辅助方法内部实际调用self._api.get_friends(user_idself.id)timeline()、followers()、follow()、unfollow()等辅助方法同理——这正体现了模型 辅助方法的设计拿到对象后无需手动拼装下一次请求。关于模型的完整字段清单可分别查阅仓库文档 docs/v1_models.rstv1.1 模型与 docs/v2_models.rstv2 模型。三、最小可运行示例OAuth 1.0a 认证 拉取首页时间线原文档给出了一个完整的、可复制运行的入门示例import tweepy auth tweepy.OAuth1UserHandler( consumer_key, consumer_secret, access_token, access_token_secret ) api tweepy.API(auth) public_tweets api.home_timeline() for tweet in public_tweets: print(tweet.text)该示例使用 v1.1 接口API获取认证用户首页时间线中的推文并逐条打印正文。3.1 参数含义与认证背景传入的四个凭据——consumer key、consumer secret、access token、access token secret——是使用OAuth 1.0a User Context以用户身份认证所必需的。认证处理的完整细节见 docs/authentication.rst其中覆盖了OAuth 2.0 Bearer TokenApp-OnlyOAuth2BearerHandler/OAuth2AppHandler最简单的只读应用认证方式OAuth 1.0a User ContextOAuth1UserHandler本示例所用的方式OAuth 2.0 Authorization Code Flow with PKCEOAuth2UserHandler通过get_authorization_url()fetch_token()换取用户 access token3-legged OAuth 与 PIN-based OAuth以其他用户身份认证的流程callbackoob走 PIN 模式。3.2 home_timeline 的底层实现home_timeline方法定义于 tweepy/api.py第 299 行起签名支持count、since_id、max_id、trim_user、exclude_replies、include_entities等参数调用GET statuses/home_timeline端点默认返回最近 20 条状态含转推。其装饰器pagination(modeid)表明该方法支持基于 ID 的分页游标可与Cursor配合翻页。API.__init__还提供了一系列实用配置见 tweepy/api.py 的API类文档cacheGET 请求缓存、host/upload_hostREST 与上传服务器地址、parser默认ModelParser负责把 JSON 解析为模型对象、proxyHTTPS 代理、retry_count/retry_delay/retry_errors错误重试、timeout默认 60 秒、wait_on_rate_limit是否自动等待限流恢复。更多完整示例可继续查阅 docs/examples.rst仓库 examples/API_v1 与 examples/API_v2 目录下还提供了认证、发推、获取粉丝/关注、搜索、扩展字段等可直接参考的脚本。四、流式数据消费StreamingClient 与 Streaming HTTP如果说 REST 接口是批量拉取流式接口则是实时推送。流式协议基于 Streaming HTTP客户端与 API 之间维持一条开放的长连接每当有新匹配结果产生就通过该连接即时下发而不是像 REST 那样反复请求批量获取。这一机制带来低延迟的数据投递可支撑非常高的吞吐量。4.1 v1.1 流式端点的退役与现状需要特别注意的是Twitter API v1.1 的流式端点statuses/filter和statuses/sample已被弃用并退役。同时原文档明确标注Stream与AsyncStream在 v4.13 中弃用并在 v4.14 中移除。因此在当前版本4.17.0中实时流式消费的唯一官方入口是面向 v2 的StreamingClient。4.2 最小流式示例采样流与过滤流StreamingClient需要以 Twitter API Bearer Token 初始化import tweepy streaming_client tweepy.StreamingClient(Bearer Token here)采样流sampling——连接并运行采样流随机返回实时推文样本streaming_client.sample()过滤流filtered——先添加规则再连接过滤流streaming_client.add_rules(tweepy.StreamRule(Tweepy)) streaming_client.filter()StreamingClient.get_rules()可查询现有规则StreamingClient.delete_rules()可删除规则。StreamRule定义于 tweepy/streaming.py 末尾是包含value规则文本、tag自由文本标签用于在流式响应中标识命中的规则、id规则唯一标识三个字段的 NamedTuple。从源码看StreamingClient同时继承BaseClient与BaseStream见 tweepy/streaming.py 第 218 行既复用 v2 的认证与请求基础能力又复用流式连接管理能力。4.3 数据分发on_data 与回调方法族流中收到的数据会交给StreamingClient.on_data()该方法负责把数据分发到各个回调对应实现见 tweepy/streaming.py 第 566 行起推文 →on_tweetTweet模型实例includes数据 →on_includesdict错误 →on_errors默认记录 error 日志匹配规则 →on_matching_rulesStreamRule列表包含上述四个字段的StreamResponse整体 →on_response默认仅在 DEBUG 级别记录日志。也就是说on_data依次尝试解析 JSON 中的data、includes、errors、matching_rules四个键逐一触发对应回调最后把完整的StreamResponse交给on_response。默认情况下所有回调除on_errors/on_response的日志外几乎不做处理因此必须通过子类化StreamingClient来定制数据处理逻辑。例如打印每条收到的推文 IDclass IDPrinter(tweepy.StreamingClient): def on_tweet(self, tweet): print(tweet.id) printer IDPrinter(Bearer Token here) printer.sample()4.4 线程化运行filter()与sample()都支持threaded参数。设为True时流会在独立线程中运行方法调用会返回该线程对象thread streaming_client.sample(threadedTrue)这适合需要把流式消费与其他业务逻辑并行执行、或嵌入 GUI/Web 服务的场景。4.5 错误处理与自动重连StreamingClient提供了一组错误处理回调详见 docs/streaming.rst 的 Handling Errors 一节on_closed流被 Twitter 关闭时调用on_connection_error遇到连接错误时调用on_request_error连接流时遇到请求错误时调用同时传入 HTTP 状态码on_exception发生未处理异常时调用对流是致命的默认记录异常日志。这些错误发生时只要未超过max_retries默认无限重试实例会在适当时间后自动重连。重连退避策略可以从 tweepy/streaming.py 的_connect方法中看到具体实现网络错误等待时间从 0 起步、步长 0.25 秒、上限 16 秒HTTP 错误等待时间从 5 秒起步、上限 320 秒HTTP 429限流的起始等待为 60 秒。这三个方法默认都会记录错误日志如需自定义处理在子类中重写即可例如class ConnectionTester(tweepy.StreamingClient): def on_connection_error(self): self.disconnect()流式消费的完整指南规则构建、数据消费、断连处理参见 docs/streaming.rst异步版本的StreamingClientAsyncStreamingClient可在 tweepy/asynchronous/streaming.py 与 docs/asyncstreamingclient.rst 中查阅。仓库 cassettes 目录下的大量 v2 流式相关测试记录如test_asyncclient_search_spaces.yaml、test_client_search_recent_tweets.yaml与 tests 目录的测试用例也可作为理解各接口实际请求参数与响应结构的一手材料。五、下一步学习路径主题仓库文档对应源码v1.1 模型字段详解docs/v1_models.rsttweepy/models.pyv2 模型字段详解docs/v2_models.rsttweepy/user.py、tweepy/tweet.py认证方式全览docs/authentication.rsttweepy/auth.pyv1.1 分页游标docs/v1_pagination.rsttweepy/cursor.pyv2 分页docs/v2_pagination.rsttweepy/pagination.py流式消费完整指南docs/streaming.rsttweepy/streaming.py更多示例docs/examples.rstexamples/API_v1、examples/API_v2安装方式与依赖要求可参考 docs/install.rst 与仓库根目录的 pyproject.toml。从本指南出发你已经具备三条完整的能力路径用API走通 v1.1 经典端点、用Client接入 v2 现代端点、用StreamingClient实时消费过滤流与采样流——剩下的就是根据你的业务场景选择接口并动手实践了。【免费下载链接】tweepyTwitter for Python!项目地址: https://gitcode.com/gh_mirrors/tw/tweepy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
