企业官网建设流程全解析

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" 之后的版本演进相接。将日志中记录的主版本按时间线整理如下：

日志开头同时注明：这些变更记录同步发布在 tweepy 官方 Release 页面，作为发行说明使用。也就是说，changelog.md既是文档，也是发布公告的正式来源。

v4.15：Python 3.13 兼容与依赖升级

4.15.0（2025-01-15）是日志中最近一个已发布版本，主要解决运行环境层面的问题：

• 修复No module named 'imghdr'：imghdr是 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.0（2023-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、withheld；TWEET_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.py，SPACE_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.13：User.verified_type 与流式回调清理

4.13.0（2023-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.12：API v2 私信、Python 3.11 与流式超时调优

4.12.x 系列值得关注：

• 4.12.0（2022-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.1（2022-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.0（2022-05-20）：引入异步接口asynchronous.AsyncClient与asynchronous.AsyncStreamingClient，前者需要asyncextra 中的aiohttp与async_lru（对应 pyproject.toml 中的可选依赖声明）；新增基于 API v2 的倒序首页时间线Client.get_home_timeline/AsyncClient.get_home_timeline。
• 4.10.1（2022-08-22）：修复AsyncBaseClient的限流处理（#1902）；修复StreamRule对象以列表形式传给delete_rules时的处理（#1942）；为Client.get_list_tweets/AsyncClient.get_list_tweets增加media_fields、place_fields、poll_fields参数。
• 4.11.0（2022-10-24）：支持获取编辑过的推文元数据——新增include_ext_edit_control参数与edit_history_tweet_ids、edit_controls两个Tweet字段；新增面向AsyncClient的asynchronous.AsyncPaginator（见 tweepy/asynchronous/pagination.py）；get_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.0（2022-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.0（2022-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.0（2022-03-17）：支持引用推文查询Client.get_quote_tweets；放弃 Python 3.6；修复Client.follow/Client.unfollow未返回底层方法结果的问题。
• 4.8.0（2022-03-24）：支持书签（Bookmarks），新增Client.bookmark、Client.get_bookmarks、Client.remove_bookmark；支持在需要认证用户 ID 的Client方法上使用 OAuth 2.0 Authorization Code Flow，未设置 access token 时抛出TypeError；BaseClient.request对 404 响应改为抛出NotFound而非通用HTTPException。
• 4.9.0（2022-05-05）：新增私信正在输入指示与已读回执API.indicate_direct_message_typing与API.mark_direct_message_read；HTTPException的消息回退到响应的"detail"值，并处理"error"键为字符串的情况；弃用Stream.sample及Stream.filter的合规消息。

v4.0：里程碑式的重构与向后不兼容变更

4.0.0（2021-09-25）是 tweepy 历史上最重要的一次大版本。它在保留 API v1.1 访问能力（API类）的同时，全面引入了 Twitter API v2（Client类），并完成六项系统性重构。

六大重构方向

1. 支持 Twitter API v2：用 v2 模型替换包命名空间中的 v1.1 模型（v1.1 模型仍然可用，但位置调整）。
2. 重做媒体上传（#640、#1486、#1501）。
3. 支持异步流式（#732、#1491）。
4. 重构API：用API.request取代bind_api与APIMethod，不再用属性装饰器定义 API 方法，改用pagination装饰器；每个API实例持有一个requests.Session（API.session），而不是每次请求新建连接。
5. 重构流式：将StreamListener合并进Stream，所有on_*回调默认记录日志并忽略返回值；流在收到任意一行数据（包括 keep-alive）时即可断开。
6. 重构文档与异常体系：文档改为自动使用 docstring（NumPy 风格）并启用 Intersphinx 链接；异常方面以TweepyException和HTTPException取代TweepError，以TooManyRequests取代RateLimitError，并新增NotFound、Unauthorized、Forbidden、BadRequest、TwitterServerError（完整列表见 tweepy/errors.py）。

API方法的命名大迁移

4.0 对大量 API v1.1 方法做了统一命名，从名词/动词混合改为动词_名词的规范形式。这是迁移到 4.x 时最需要留意的部分，代表性映射如下：

同时，API初始化参数auth_handler改为auth，方法参数也做了收敛：例如API.lookup_users的screen_names/user_ids改为单数形式的screen_name/user_id，API.lookup_statuses的id_改为id，API.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_error，on_timeout→on_connection_error，on_disconnect→on_disconnect_message，keep_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_name；update_status移除了enable_dmcommands、fail_dmcommands等参数。

4.1 ~ 4.4：Spaces、合规任务与列表管理

4.x 早期版本以补全 API v2 功能为主：

• 4.1.0（2021-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.0（2021-10-29）：支持用 API v2 管理列表；Client.follow/Client.unfollow改名为Client.follow_user/Client.unfollow_user（旧名保留为弃用别名）；Client.search_spaces的state参数改为可选。
• 4.3.0（2021-11-03）：支持用 API v2 管理推文（发推、删推、回复、引用等），并在文档中增加Client方法与 API v2 端点的映射表。
• 4.4.0（2021-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.0（2014-11-30）：从 httplib 切换到 Requests；移除对非安全 HTTP 的支持；新增sitestream端点与add_list_members/remove_list_members批量操作；新增/statuses/lookup.json对应方法。
• 3.2.0（2015-01-28）：新增media/upload端点与update_status的media_ids参数；移除已弃用的 trends 方法。
• 3.4.0（2015-08-13）：新增account/settings相关 API；新增RateLimitError；verify_credentials支持include_email。
• 3.5.0（2015-11-19）：update_status第一个位置参数修正为status；私信支持full_text参数。
• 3.6.0（2015-03-02）：新增API.unretweet、stall_warnings参数、auto_populate_reply_metadata参数；Status.quoted_status被解析为Status对象。
• 3.7.0（2018-11-27）：放弃 Python 2.6/3.3；新增API.create_mute/API.destroy_mute/API.mutes_ids；流式支持代理与tweet_mode参数。
• 3.8.0（2019-07-14）：放弃 Python 3.4；新增API.mutes；blocks_ids与mutes_ids支持游标分页；私信方法统一为list_direct_messages。
• 3.9.0（2020-07-11）：支持 Python 3.8；API.create_media_metadata；update_status增加exclude_reply_user_ids、attachment_url、card_uri等参数；GIF 上传大小上限更新；文档新增韩语、波兰语翻译（docs/locale 中保留了两套翻译文件）。
• 3.10.0（2020-12-25）：新增 Premium v1.1 搜索API.search_30_day/API.search_full_archive（后被 4.14 移除）；支持 Python 3.9；CI 从 Travis CI 切换到 GitHub Actions。

2.x 与 1.x：Twitter API 1.1 迁移与早期积累

• 2.0（2013-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.1（2013-06-16）：新增get_oembed；friends/followers以 v1.1 身份回归；新增API(timeout=...)与API(compression=True)支持；search切换到 v1.1 端点（带来破坏性变更）；分页游标从基于 page 改为基于 ID。
• 2.2（2014-01-20）：新增update_profile_banner端点与retweeters端点；移除 Basic Auth；默认使用 HTTPS；新增on_event、on_direct_message流式回调；API.cached_result标记缓存命中；改进流式重连配置。
• 2.3.0（2014-04-26）：日志仅给出官方对比链接，为一次小版本维护。
• 1.x：从 1.0（2009-08-13）到 1.13（2013-01-17），覆盖了基础 API、Streaming API、Cursor分页对象（1.2 引入）、OAuthHandler（1.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 后，显式要求oauthlib>=3.2.0、requests_oauthlib>=1.2.0；4.15.0 进一步允许 requests-oauthlib v2。
• 3.9.0 起用 requests 的 socks extra 替代直接依赖 PySocks。
• 4.10.0 起，异步能力（aiohttp、async_lru）被放到可选的asyncextra 中，需要异步接口的用户需额外安装tweepy[async]。

升级迁移实操建议

基于上述版本脉络，面向不同基线用户的迁移要点可归纳为：

1. 从 3.x 升级到 4.x：先对照 上文的方法重命名表 全局替换方法名；确认方法参数是否为 keyword-only（4.0 起绝大多数方法不再接受位置参数）；把auth_handler=改为auth=；流式代码需从StreamListener迁移到Stream的内置回调，并将is_async改为threaded。
2. 仍在用 API v1.1 流式或 Premium 搜索：4.13/4.14 起这些能力已被移除，需要迁移到StreamingClient（API v2 流式）与标准搜索接口。
3. 新增能力优先走Client/AsyncClient：API v2 的新功能（书签、Spaces、私信、社区推文、编辑元数据等）只存在于Client与AsyncClient（后者位于 tweepy/asynchronous/client.py）。
4. 请求字段时优先使用模型常量：使用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