Tweepy 版本演进全解析从 v1.0 到 v4.x 的 API 变迁与技术路线图【免费下载链接】tweepyTwitter for Python!项目地址: https://gitcode.com/gh_mirrors/tw/tweepy本文以 tweepy 官方 变更日志 为骨架结合当前仓库源码版本 4.17.0逐版本梳理 tweepy 十余年的演进脉络Twitter API v1.1 到 v2 的迁移、异步接口的引入、流式Streaming模块的重构、认证体系的全面翻新以及每一次向后不兼容变更背后的设计意图。读完本文你将掌握 tweepy 各版本的能力边界、升级迁移要点并能据此判断自己项目所依赖的 API 处于哪个历史阶段。版本总览一条从 API v1.1 走向 API v2 的时间线tweepy 是一个用于访问 X原 Twitter开放 API 的 Python 库其 变更日志 记录了从 2009 年 v1.0 至今的完整版本历史。当前仓库的tweepy/__init__.py显示版本号为4.17.0与日志中 Unreleased 之后的版本演进相接。将日志中记录的主版本按时间线整理如下版本发布日期核心主题1.0 ~ 1.132009 ~ 2013基础 API、Streaming、Cursor 分页、OAuth 起步2.02013-02-10Twitter API 1.1 支持大规模移除旧方法3.0 ~ 3.102014 ~ 2020从 httplib 切换到 Requests媒体上传完善扩展推文4.02021-09-25支持 Twitter API v2重构 API/Streaming/异常/文档4.1 ~ 4.62021-10 ~ 2022-02Spaces、合规任务、API v2 流式、异步接口4.7 ~ 4.122022-03 ~ 2022-11引用推文、书签、API v2 私信、编辑推文元数据4.13 ~ 4.152023-03 ~ 2025-01字段常量、verified_type、Python 3.13 兼容日志开头同时注明这些变更记录同步发布在 tweepy 官方 Release 页面作为发行说明使用。也就是说changelog.md既是文档也是发布公告的正式来源。v4.15Python 3.13 兼容与依赖升级4.15.02025-01-15是日志中最近一个已发布版本主要解决运行环境层面的问题修复No module named imghdrimghdr是 Python 标准库中一个长期弃用的模块在 Python 3.13 中被移除。tweepy 的媒体上传流程曾依赖它识别图片类型此版本改为不再依赖该模块从而在 Python 3.13 上正常运行为推文附加图片等媒体。升级 requests-oauthlib 到 v2将 OAuth 相关依赖的下限放宽允许安装 requests-oauthlib v2。放弃 Python 3.7 与 3.8 支持与 pyproject.toml 中requires-python 3.9以及分类器classifiers列出的 Python 3.9 ~ 3.13 完全对应。这也是 tweepy 自 4.0 放弃 Python 2 之后持续跟随 Python 官方维护节奏的又一次清理。值得注意Unreleased 一节还预告了一个新特性通过community_id参数向 Communities社区发布推文。该特性已在当前仓库源码中落地见tweepy/client.py的Client.create_tweet当传入community_id时会将其写入请求 JSON 的community_id字段且要求认证用户必须是该社区的成员。v4.14字段常量与 API v1.1 流式支持的落幕4.14.02023-04-24有两个显著动作。新增各模型对象字段常量日志列出 11 个新增常量用于在请求中声明需要返回的字段fields参数。这些常量在仓库中均已有对应实现且与模型定义文件一一对应TWEET_FIELDS、PUBLIC_TWEET_FIELDS见 tweepy/tweet.py。公开字段包括attachments、author_id、context_annotations、conversation_id、created_at、edit_controls、edit_history_tweet_ids、entities、geo、id、in_reply_to_user_id、lang、possibly_sensitive、public_metrics、referenced_tweets、reply_settings、source、text、withheldTWEET_FIELDS在此基础上追加了需要更高权限的non_public_metrics、organic_metrics、promoted_metrics。USER_FIELDS见 tweepy/user.py。LIST_FIELDS见 tweepy/list.py。MEDIA_FIELDS见 tweepy/media.py。PLACE_FIELDS见 tweepy/place.py。POLL_FIELDS见 tweepy/poll.py。PUBLIC_SPACE_FIELDS与SPACE_FIELDS见 tweepy/space.pySPACE_FIELDS在公开字段基础上追加了部分受限字段。DIRECT_MESSAGE_EVENT_FIELDS与DM_EVENT_FIELDS见 tweepy/direct_message_event.py两者互为别名。所有常量都在tweepy/__init__.py的包命名空间中被导出因此可直接from tweepy import TWEET_FIELDS使用。这些常量避免了在每次调用中手写字符串列表也降低了字段名拼写错误的风险。移除 Twitter API v1.1 流式支持4.14.0 正式移除了Stream与AsyncStream对 API v1.1status/filter端点的流式支持此前在 4.13.0 已标记弃用同时删除了已废弃的 Premium v1.1 搜索接口API.search_30_day与API.search_full_archive。这意味着自 4.14 起流式数据消费只能通过 API v2 的StreamingClient完成。v4.13User.verified_type 与流式回调清理4.13.02023-03-09中新增User.verified_type字段用于区分用户的认证类型如企业、政府机构、新闻媒体等。移除依赖已退役 API v1.1 特性的流式方法Stream.sample/AsyncStream.sample对应 v1.1statuses/sample端点被移除Stream/AsyncStream上的合规消息回调on_delete、on_scrub_geo、on_status_withheld、on_user_withheld一并移除Stream与AsyncStream本身对 v1.1statuses/filter的支持被标记为弃用4.14 正式移除。Bug 修复StreamingClient._process_data与AsyncStreamingClient._process_data返回基类方法值JSONParser.parse处理空载荷issue #2051以及错误的分块上传处理状态修复。这一版本清晰地划出了 API v1.1 流式与 API v2 流式的分界线。v4.12API v2 私信、Python 3.11 与流式超时调优4.12.x 系列值得关注4.12.02022-10-27新增 API v2 直接消息Direct Messages支持新增DirectMessageEvent模型以及Client/AsyncClient上的get_direct_message_events、create_direct_message、create_direct_message_conversation三个方法同时支持 Python 3.11并为Media模型新增variants字段。4.12.12022-11-06集中修复流式连接的稳定性问题为 API v2 流式超时增加 1 秒缓冲。原因是服务端 keep-alive 常常在恰好超过 20 秒后才到达若超时精确设为 20 秒会引发不必要的超时重连。将初始network_error_wait改为 0即已建立的流式连接断开时立即尝试重连而不是等待。默认让AsyncBaseStream中止已关闭的 SSL 传输issue #1904。当推文数据缺失默认的edit_history_tweet_ids字段时给出警告issue #1994。流式重连与超时的这些细节在 tweepy/streaming.py 的BaseStream及 tweepy/asynchronous/streaming.py 中均有对应实现。v4.10 ~ v4.11异步接口、编辑推文元数据与流式优化这两个版本是 API v2 异步能力快速补全的阶段4.10.02022-05-20引入异步接口asynchronous.AsyncClient与asynchronous.AsyncStreamingClient前者需要asyncextra 中的aiohttp与async_lru对应 pyproject.toml 中的可选依赖声明新增基于 API v2 的倒序首页时间线Client.get_home_timeline/AsyncClient.get_home_timeline。4.10.12022-08-22修复AsyncBaseClient的限流处理#1902修复StreamRule对象以列表形式传给delete_rules时的处理#1942为Client.get_list_tweets/AsyncClient.get_list_tweets增加media_fields、place_fields、poll_fields参数。4.11.02022-10-24支持获取编辑过的推文元数据——新增include_ext_edit_control参数与edit_history_tweet_ids、edit_controls两个Tweet字段新增面向AsyncClient的asynchronous.AsyncPaginator见 tweepy/asynchronous/pagination.pyget_quote_tweets支持exclude参数流式连接对 429 错误进行专门处理并将 API v2 流式超时下调到 20 秒AsyncStream在每次重连前重新生成 Authorization 头。分页方面tweepy/pagination.py 中的Paginator与 tweepy/asynchronous/pagination.py 中的AsyncPaginator均支持limit与pagination_token参数在 4.12.1 中被文档化前者用于同步Client方法后者用于异步AsyncClient方法。v4.5 ~ v4.9认证体系翻新与功能密集落地4.5.02022-01-24全面翻新认证接口。新增 OAuth 2.0 Authorization Code Flow PKCE 支持新增OAuth2UserHandler与Client方法的user_auth参数将OAuthHandler重命名为OAuth1UserHandler、AppAuthHandler重命名为Oauth2AppHandler、OAuth2Bearer重命名为OAuth2BearerHandler旧名字均保留为弃用别名允许直接向OAuth1UserHandler传入 access token 与 secret移除AuthHandler与get_xauth_access_token。同时新增Client.get_me以及Media.url支持。这些认证类目前仍从 tweepy/auth.py 导出并在tweepy/__init__.py中可见。4.6.02022-02-24支持 API v2 流式——将Client与Stream重构为继承新的BaseClient与BaseStream并新增StreamingClient、StreamResponse、StreamRule后者在 tweepy/streaming.py 定义为 NamedTuple。此外为get_liking_users、get_retweeters增加max_results与pagination_token为搜索方法增加sort_order新增Client.get_space_tweets与Space.subscriber_count并使用 oauthlib 生成 PKCE 的 code challenge 与 verifier。4.7.02022-03-17支持引用推文查询Client.get_quote_tweets放弃 Python 3.6修复Client.follow/Client.unfollow未返回底层方法结果的问题。4.8.02022-03-24支持书签Bookmarks新增Client.bookmark、Client.get_bookmarks、Client.remove_bookmark支持在需要认证用户 ID 的Client方法上使用 OAuth 2.0 Authorization Code Flow未设置 access token 时抛出TypeErrorBaseClient.request对 404 响应改为抛出NotFound而非通用HTTPException。4.9.02022-05-05新增私信正在输入指示与已读回执API.indicate_direct_message_typing与API.mark_direct_message_readHTTPException的消息回退到响应的detail值并处理error键为字符串的情况弃用Stream.sample及Stream.filter的合规消息。v4.0里程碑式的重构与向后不兼容变更4.0.02021-09-25是 tweepy 历史上最重要的一次大版本。它在保留 API v1.1 访问能力API类的同时全面引入了 Twitter API v2Client类并完成六项系统性重构。六大重构方向支持 Twitter API v2用 v2 模型替换包命名空间中的 v1.1 模型v1.1 模型仍然可用但位置调整。重做媒体上传#640、#1486、#1501。支持异步流式#732、#1491。重构API用API.request取代bind_api与APIMethod不再用属性装饰器定义 API 方法改用pagination装饰器每个API实例持有一个requests.SessionAPI.session而不是每次请求新建连接。重构流式将StreamListener合并进Stream所有on_*回调默认记录日志并忽略返回值流在收到任意一行数据包括 keep-alive时即可断开。重构文档与异常体系文档改为自动使用 docstringNumPy 风格并启用 Intersphinx 链接异常方面以TweepyException和HTTPException取代TweepError以TooManyRequests取代RateLimitError并新增NotFound、Unauthorized、Forbidden、BadRequest、TwitterServerError完整列表见 tweepy/errors.py。API方法的命名大迁移4.0 对大量 API v1.1 方法做了统一命名从名词/动词混合改为动词_名词的规范形式。这是迁移到 4.x 时最需要留意的部分代表性映射如下旧方法新方法API.blocks/API.blocks_idsAPI.get_blocks/API.get_blocked_idsAPI.favoritesAPI.get_favoritesAPI.followers/API.followers_idsAPI.get_followers/API.get_follower_idsAPI.friends/API.friends_idsAPI.get_friends/API.get_friend_idsAPI.friendships_incoming/API.friendships_outgoingAPI.incoming_friendships/API.outgoing_friendshipsAPI.geo_searchAPI.search_geoAPI.list_direct_messagesAPI.get_direct_messagesAPI.list_members/API.list_subscribersAPI.get_list_members/API.get_list_subscribersAPI.lists_all/API.lists_memberships/API.lists_subscriptionsAPI.get_lists/API.get_list_memberships/API.get_list_subscriptionsAPI.mutes/API.mutes_idsAPI.get_mutes/API.get_muted_idsAPI.retweeters/API.retweets/API.retweets_of_meAPI.get_retweeter_ids/API.get_retweets/API.get_retweets_of_meAPI.saved_searchesAPI.get_saved_searchesAPI.searchAPI.search_tweetsAPI.show_friendshipAPI.get_friendshipAPI.statuses_lookupAPI.lookup_statusesAPI.trends_available/API.trends_closest/API.trends_placeAPI.available_trends/API.closest_trends/API.get_place_trendsAPI.update_with_mediaAPI.update_status_with_mediaAPI.destroy_direct_messageAPI.delete_direct_message同时API初始化参数auth_handler改为auth方法参数也做了收敛例如API.lookup_users的screen_names/user_ids改为单数形式的screen_name/user_idAPI.lookup_statuses的id_改为idAPI.geo_id的id改为place_id。更严格的参数约束4.0 起大量API方法开始强制必填参数此前缺省时可能静默失败或依赖默认值例如search_tweets的q、update_status的status、create_list的name、get_status的id、reverse_geocode的lat/long等同时绝大多数方法改为仅限关键字参数keyword-only不再接受任意位置参数。这从源头避免了参数顺序错误与拼写错误被静默吞掉——若传入不被端点支持的参数API.request还会输出警告日志。流式Stream接口的对应调整StreamListener被合并进Stream回调方法改名on_error→on_request_erroron_timeout→on_connection_erroron_disconnect→on_disconnect_messagekeep_alive→on_keep_alive等。移除Stream.api、Stream.host、Stream.timeout、Stream.url、Stream.headers、Stream.body、Stream.new_session等属性。重连等待参数整体移除retry_time_start、retry_420_start、snooze_time_step等retry_count改名为max_retries。Stream.auth拆分为consumer_key、consumer_secret、access_token、access_token_secret四个凭据参数proxies参数改为proxy。Stream.filter/Stream.sample的is_async参数改名为threaded并仅限关键字传入。Twitter API 侧的不兼容清理日志还记录了一批因上游 API 下线而移除的方法与端点参数API.configuration、API.geo_similar_places、API.related_results含Relation模型、Stream.firehose、Stream.sitestream、Stream.userstream、Stream.retweet等多个方法的id端点参数如create_block、create_friendship、create_mute、get_user、user_timeline被移除因为上游要求改用user_id/screen_nameupdate_status移除了enable_dmcommands、fail_dmcommands等参数。4.1 ~ 4.4Spaces、合规任务与列表管理4.x 早期版本以补全 API v2 功能为主4.1.02021-10-07支持 Python 3.10支持 Spaces——新增Space模型与Client.search_spaces、Client.get_spaces、Client.get_space支持批量合规Batch Compliance——新增Client.get_compliance_jobs、Client.get_compliance_job、Client.create_compliance_job新增Client.get_muted。4.2.02021-10-29支持用 API v2 管理列表Client.follow/Client.unfollow改名为Client.follow_user/Client.unfollow_user旧名保留为弃用别名Client.search_spaces的state参数改为可选。4.3.02021-11-03支持用 API v2 管理推文发推、删推、回复、引用等并在文档中增加Client方法与 API v2 端点的映射表。4.4.02021-11-17支持 API v2 列表查询List lookup新增Client.get_space_buyers、Space.ended_at、Space.topic_ids移除错误的Space.__str__。这些能力对应的测试用例VCR cassette都沉淀在仓库的 cassettes 目录中例如test_asyncclient_get_space.yaml、test_client_manage_and_get_pinned_lists.yaml、test_client_create_and_get_compliance_job_and_jobs.yaml等可作为理解方法行为与响应结构的参考。3.x 时代从 httplib 到 Requests媒体与流式的积累期3.x 系列为 4.0 的重构奠定了大量基础能力3.02014-11-30从 httplib 切换到 Requests移除对非安全 HTTP 的支持新增sitestream端点与add_list_members/remove_list_members批量操作新增/statuses/lookup.json对应方法。3.2.02015-01-28新增media/upload端点与update_status的media_ids参数移除已弃用的 trends 方法。3.4.02015-08-13新增account/settings相关 API新增RateLimitErrorverify_credentials支持include_email。3.5.02015-11-19update_status第一个位置参数修正为status私信支持full_text参数。3.6.02015-03-02新增API.unretweet、stall_warnings参数、auto_populate_reply_metadata参数Status.quoted_status被解析为Status对象。3.7.02018-11-27放弃 Python 2.6/3.3新增API.create_mute/API.destroy_mute/API.mutes_ids流式支持代理与tweet_mode参数。3.8.02019-07-14放弃 Python 3.4新增API.mutesblocks_ids与mutes_ids支持游标分页私信方法统一为list_direct_messages。3.9.02020-07-11支持 Python 3.8API.create_media_metadataupdate_status增加exclude_reply_user_ids、attachment_url、card_uri等参数GIF 上传大小上限更新文档新增韩语、波兰语翻译docs/locale 中保留了两套翻译文件。3.10.02020-12-25新增 Premium v1.1 搜索API.search_30_day/API.search_full_archive后被 4.14 移除支持 Python 3.9CI 从 Travis CI 切换到 GitHub Actions。2.x 与 1.xTwitter API 1.1 迁移与早期积累2.02013-02-10全面支持 Twitter API 1.1同时大幅清理旧接口——移除friends_timeline、mentions替换为mentions_timeline、retweeted_by_*系列、friends/followers后被 2.1 以 v1.1 形式恢复、lists替换为lists_all等show_list_member/show_list_subscriber取代is_list_member/is_subscribed_list。2.12013-06-16新增get_oembedfriends/followers以 v1.1 身份回归新增API(timeout...)与API(compressionTrue)支持search切换到 v1.1 端点带来破坏性变更分页游标从基于 page 改为基于 ID。2.22014-01-20新增update_profile_banner端点与retweeters端点移除 Basic Auth默认使用 HTTPS新增on_event、on_direct_message流式回调API.cached_result标记缓存命中改进流式重连配置。2.3.02014-04-26日志仅给出官方对比链接为一次小版本维护。1.x从 1.02009-08-13到 1.132013-01-17覆盖了基础 API、Streaming API、Cursor分页对象1.2 引入、OAuthHandler1.5 起支持 HTTPS OAuth、Lists API、API.verify_credentials返回User对象等早期能力。1.2 还引入了自动请求重试retry_count、retry_delay。Python 版本支持演进日志清晰地记录了 tweepy 对 Python 版本支持的收缩轨迹这对评估升级兼容性非常重要v1.x / v2.x 时代支持 Python 2.x 与早期 Python 3。3.6.0新增 Python 3.6 支持。3.7.0放弃 Python 2.6 与 3.3。3.8.0放弃 Python 3.4。3.9.0新增 Python 3.8。3.10.0新增 Python 3.9并预告 4.0 是下一个非补丁版本。4.0.0放弃 Python 2 与 Python 3.5。4.6.0最后一个支持 Python 3.6 的小版本。4.7.0放弃已 EOL 的 Python 3.6。4.12.0新增 Python 3.11。4.15.0放弃 Python 3.7 与 3.8当前最低要求为 Python 3.9。这与当前 pyproject.toml 的requires-python 3.9完全吻合且分类器明确支持到 Python 3.13。依赖变化一条持续精简的主线日志中反复出现的依赖调整反映了 tweepy 对运行时的取舍3.0 起以requests替代 httplib并在 4.5.0 将requests下限提到 2.27.0用于统一处理JSONDecodeError。4.5.0 引入 PKCE 后显式要求oauthlib3.2.0、requests_oauthlib1.2.04.15.0 进一步允许 requests-oauthlib v2。3.9.0 起用 requests 的 socks extra 替代直接依赖 PySocks。4.10.0 起异步能力aiohttp、async_lru被放到可选的asyncextra 中需要异步接口的用户需额外安装tweepy[async]。升级迁移实操建议基于上述版本脉络面向不同基线用户的迁移要点可归纳为从 3.x 升级到 4.x先对照 上文的方法重命名表 全局替换方法名确认方法参数是否为 keyword-only4.0 起绝大多数方法不再接受位置参数把auth_handler改为auth流式代码需从StreamListener迁移到Stream的内置回调并将is_async改为threaded。仍在用 API v1.1 流式或 Premium 搜索4.13/4.14 起这些能力已被移除需要迁移到StreamingClientAPI v2 流式与标准搜索接口。新增能力优先走Client/AsyncClientAPI v2 的新功能书签、Spaces、私信、社区推文、编辑元数据等只存在于Client与AsyncClient后者位于 tweepy/asynchronous/client.py。请求字段时优先使用模型常量使用TWEET_FIELDS、USER_FIELDS等包级常量避免手写字符串出错也便于随版本自动获得新增字段。结语tweepy 的 变更日志 不仅是一份更新记录更是一部浓缩的 Twitter 平台 API 演进史从 Basic Auth 到 OAuth 2.0 PKCE从 API v1.1 到 API v2从同步请求到异步与流式并行从 httplib 到 requests。理解这份演进路线能帮助你在升级依赖时预判破坏性变更也能在阅读当前 tweepy/client.py 与 tweepy/api.py 源码时快速定位每个方法所处的 API 世代与设计上下文。【免费下载链接】tweepyTwitter for Python!项目地址: https://gitcode.com/gh_mirrors/tw/tweepy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考