从 Tweepy 迁移出来:逐字段对照表
从 Tweepy 迁移出来:逐字段对照表
Tweepy 是个好库。如果你在从它迁移,通常不是因为这个库让你失望——而是因为它底下那个 API 改了条款,或者因为你本来只需要读公开数据,而那套凭据、配额和 OAuth 流程不再值得了。
这篇讲机械的那部分:哪个调用对应哪个、哪些字段名会变、以及什么确实带不过来。这是几个小时的工作量,而其中大部分是读你自己的代码、搞清楚你到底用了哪些调用。
不同的库,不同的路径:如果你是从 snscrape 过来而不是 Tweepy,那个迁移是另一篇——失效方式不一样。有个免费 demo 端点,动手之前可以先对一下字段结构。
先搞清楚:你是只读用户吗?
这决定了迁移是否可能,所以开工前先查。
# 在项目根目录 —— 找出你所有的写操作
grep -rnE '\.(create_tweet|delete_tweet|like|unlike|retweet|unretweet|follow|unfollow|send_direct_message|update_status|update_profile)\(' .
★有任何命中,就意味着你需要能代表一个账号行动的凭据★,而只读数据 API 替代不了那些。写路径留给 Tweepy——你可以两套并行,Tweepy 负责那几个写操作,数据 API 负责大量读操作。这是个常见且完全合理的最终状态。
没有命中,迁移就很直接。 下面全部适用。
方法对照
Tweepy(v2 Client) |
对应请求 |
|---|---|
get_user(username=...) |
GET /v1/user/info?username= |
get_user(id=...) |
GET /v1/user/info_by_id?user_id= |
get_users_tweets(id) |
GET /v1/user/last_tweets?username= |
search_recent_tweets(query) |
GET /v1/search/advanced?query= |
get_tweet(id) |
GET /v1/tweet/info?id= |
get_users_followers(id) |
GET /v1/user/followers?username= |
get_users_following(id) |
GET /v1/user/followings?username= |
get_retweeters(id) |
GET /v1/tweet/retweeters?id= |
get_quote_tweets(id) |
GET /v1/tweet/quotes?id= |
时间线上的 Paginator(...) |
一次调用、limit 最大 200 —— 没有游标 |
粉丝/列表上的 Paginator(...) |
响应 meta 里的 cursor |
★最大的实际差异:用户名可以直接用。★ Tweepy 的时间线和粉丝方法要的是数字用户 ID,所以常见模式是先查一次、再真正调用。这边直接接受用户名,于是每个目标少一个请求——一千个账号的列表,调用数直接减半。
# Tweepy: 两次调用
user = client.get_user(username="naval")
tweets = client.get_users_tweets(user.data.id, max_results=100)
# 一次调用
r = requests.get(f"{API}/user/last_tweets",
params={"username": "naval", "limit": 100},
headers=HEADERS, timeout=30)
tweets = r.json()["data"]
但数字 ID 还是要存。 用户名会变,ID 不会。 接受用户名作为入参是个便利,不是让你拿它当数据库主键的理由——道理在哪些字段能当安全主键。
字段对照
★安静的 bug 就出在这里★,因为有几个字段是同一个概念换了个名字。
| Tweepy v2 字段 | 这边 | 说明 |
|---|---|---|
public_metrics.like_count |
like_count |
扁平,不嵌套 |
public_metrics.retweet_count |
retweet_count |
|
public_metrics.reply_count |
reply_count |
|
public_metrics.quote_count |
quote_count |
|
public_metrics.impression_count |
view_count |
名字不同,含义相同 |
user.public_metrics.followers_count |
followers_count |
扁平 |
user.description |
bio |
★改名了★ |
user.name |
display_name |
★改名了★ |
created_at(datetime) |
created_at(字符串) |
★现在要你自己解析★ |
author_id |
author 对象,或 author_id |
常常内联,不用再调一次 |
其中三处如果你扫一眼就过会被咬。
public_metrics 在这边是扁平的。 Tweepy 把计数嵌套起来;直接照搬保留 t["public_metrics"]["like_count"] 会立刻抛 KeyError。这个很响亮,所以反而没事。
★description → bio 和 name → display_name 是危险的那一对。★ 如果你的代码写的是 user.get("description", ""),你会拿到空字符串而不是报错——于是每条记录的输出都静默地空了。
created_at 来的是字符串,不是 datetime。 Tweepy 帮你解析了;这边要你自己来,而且它不是 ISO 8601:
from datetime import datetime, timezone
def parse_created_at(s: str) -> datetime:
# "Tue Jun 02 20:12:29 +0000 2009" —— 不是 ISO 8601
return datetime.strptime(s, "%a %b %d %H:%M:%S %z %Y").astimezone(timezone.utc)
朴素的 datetime.fromisoformat() 在这上面会抛异常。 完整字段布局在读懂推文对象。
翻页:Paginator 一分为二
Tweepy 把所有分页调用都包进同一个 Paginator。这边两类端点行为不同,照搬循环会把其中一类写错。
★时间线不翻页。★ last_tweets、media、photos、videos 一次调用返回最多 limit 条,响应里没有 next_cursor。limit 最大 200,而且有些账号不管设多高都返回得更少——X 自己的时间线深度因账号而异。Tweepy 里需要 Paginator 往回翻的时间线,这边换成一次请求加一个更大的 limit 就行。
★列表才翻页。★ 粉丝、关注、转推者、列表成员会在 meta 里给 next_cursor,你把它当 cursor 传回去。这个循环你自己写——而且活动部件比那层包装看起来要少:
def paginate(path, params, max_items=None):
out, cursor = [], None
while True:
p = dict(params)
if cursor:
p["cursor"] = cursor
r = requests.get(f"{API}{path}", params=p, headers=HEADERS, timeout=60)
if r.status_code == 429:
time.sleep(30)
continue # 不是失败; 回头再来
r.raise_for_status()
body = r.json()
batch = body.get("data") or []
if not batch:
break
out.extend(batch)
if max_items and len(out) >= max_items:
return out[:max_items]
cursor = (body.get("meta") or {}).get("next_cursor")
if not cursor:
break
return out
followers = paginate("/user/followers", {"username": "naval", "limit": 200})
★批次为空和游标缺失,两个都要 break。★ 只判一个,要么死循环、要么结果被截断——而截断看起来和「这个账号本来就没多少粉丝」一模一样。
调用点很多的话,用一个兼容层
如果 Tweepy 对象在几十个地方被引用,不要一次全部重写。把新响应包成可属性访问的东西,然后逐步迁移调用点:
class Obj(dict):
"""在 dict 上提供属性访问, 让 t.like_count 继续能用。"""
def __getattr__(self, k):
try:
return self[k]
except KeyError:
raise AttributeError(k)
def adapt(d: dict) -> Obj:
o = Obj(d)
# 把改名桥接回去, 让老调用点先不用改
if "bio" in d:
o["description"] = d["bio"]
if "display_name" in d:
o["name"] = d["display_name"]
return o
★这是脚手架,不是终点。★ 它让你第一天就有个能跑的系统,并且在你碰到每个调用点时逐个删掉这些别名。永久留着它,意味着你要为每个字段永远背两个名字,而那本身就是成本。
你实际会失去什么
说直白,因为迁移到一半才发现这些很难受:
★写权限。★ 不能发帖、点赞、关注、发私信。需要这些的话,Tweepy 就留着做那部分。这是会终结迁移的那一条,所以 grep 要放在最前面。
★你自己的私有分析数据。★ X 会给帖子作者看一些不公开的指标——详细的展示量拆解、从帖子来的资料页访问。任何第三方 API 都看不到那些,因为它们不是公开数据。 如果你的看板在报自己账号的私有数字,那部分搬不了。
OAuth 代表用户的流程。 凡是你的应用要代表某个已登录用户行动的,按定义就需要官方 API。
为了平衡,说说你得到什么:不用申请开发者账号、不用处理 per-user token、用户名可以直接传,而且 key 泄露损失的是配额而不是某人的账号。最后这点比听起来值钱——只读 key 的影响范围在量级上就更小。
相信它之前先验证
不要换掉实现就假定对等。 拿同样的输入把两边都跑一遍再比:
def compare(username, n=20):
old = {str(t.id) for t in client.get_users_tweets(
client.get_user(username=username).data.id, max_results=n).data or []}
new = {t["id"] for t in requests.get(
f"{API}/user/last_tweets",
params={"username": username, "limit": n},
headers=HEADERS, timeout=30).json().get("data", [])}
print(f"old={len(old)} new={len(new)} overlap={len(old & new)}")
print("only in old:", sorted(old - new)[:5])
print("only in new:", sorted(new - old)[:5])
★预期是「接近重合」,不是「完全相同」。★ 两边可以合理地不一致:对回复和转推的默认包含方式不同,以及两次调用之间有新帖子进来。★差距大要查,但不要追最后那一两条。★ 多试几个账号、包括一个发帖很频繁的,因为排序和窗口差异就在那儿显现。
我们的 API 直接接受用户名、返回上面那些扁平字段名,所以对大多数代码来说,那张对照表就是整个迁移。用 Google 一键注册送 $0.20 额度、不用信用卡——够你在改任何东西之前,拿真实目标把对比脚本跑一遍。
常见问题
Tweepy 还在维护吗? 在。 人们迁移的原因通常是它底下那个 API 的条款和配额,或者不需要写权限,而不是这个库本身有问题。
只读场景下最好的 Tweepy 替代是什么? 任何基于普通 HTTP 的只读 REST API。要比的是:用户名能不能直接传、翻页怎么暴露、以及key 泄露了能不能动到账号。
能完全替掉 Tweepy 吗?
只有在你从不写入时可以。 先 grep create_tweet、like、follow 这些——任何命中都意味着那条路径要留着 Tweepy。
能两套同时用吗? 能,而且常常是对的答案:Tweepy 管那几个写操作,数据 API 管大量读操作。它们不冲突。
还需要开发者账号吗? 通过第三方 API 读公开数据不需要,你用的是服务商的 key。官方 API 访问和写操作仍然需要。
为什么不用先查一次用户? 因为用户名可以直接传。 Tweepy 的时间线方法要数字 ID,这就强制了一次查询调用;去掉它在大目标列表上把请求数减半。
数据库该按用户名还是 ID 做主键? ★永远用 ID。★ 用户名会变,而按用户名存的记录在账号改名时会悄悄消失——看起来像被删号了。
public_metrics 去哪了?
这边计数是扁平的:like_count 而不是 public_metrics.like_count。直接照搬会抛 KeyError,至少它失败得很响亮。
description 对应哪个字段?
bio。★这是最容易造成安静 bug 的改名★,因为 d.get("description", "") 返回空值而不是报错。
user.name 呢?
是 display_name。和 description 一样,用带默认值的方式读会有同样的静默失败风险。
impression_count 和 view_count 是一回事吗? 是同一个概念换了名字。 注意它的数量级远高于其他计数,不要和它们放在同一个坐标轴上。
created_at 为什么解析不了?
它不是 ISO 8601——格式是 "Tue Jun 02 20:12:29 +0000 2009"。用带显式格式串的 strptime;fromisoformat 会抛异常。
Paginator 怎么替换?
看端点。 时间线不用替换——一次调用、limit 最大 200,就顶替了整个循环。粉丝和列表才用一个把 next_cursor 当 cursor 传回去的 while 循环,★批次为空「或」游标缺失都要 break★。
没有 Tweepy 的 wait_on_rate_limit,限流怎么处理? 捕获 429、睡一会儿、重试,并且不要推进游标。 限流不是失败,而且那个请求不计费。
有可以直接替换的库吗? 没有完全一样的,但一个小的属性访问包装 + 两个字段别名,能让大多数现有调用点不改就跑起来。当成你会逐步删掉的脚手架。
迁移要多久? 典型只读代码几个小时,而其中大部分是在审计你到底用了哪些调用,不是在写新东西。
结果会完全一致吗? 接近一致,不是完全一致。 对回复和转推的默认包含方式不同,而且两次调用之间会有新帖子。比集合、只查大差距。
怎么验证迁移? 两个实现跑同样的账号,然后 diff ID 集合。 包含一个高频发帖的账号,窗口差异就在那儿浮现。
私有指标会失去什么? 凡是 X 只给帖子作者看的——详细展示量拆解、资料页访问。那不是公开数据,所以任何第三方 API 都提供不了。
还能拿到超过 7 天的历史吗? 那个限制属于官方 v2 API 的 recent-search。 这边一次时间线调用最多返回某账号最新的 200 条——X 时间线给得浅的账号会更少。更早的内容用按日期限定的搜索。
我的 OAuth 流程怎么办? 读操作上它没了——你改成发一个 API key 请求头。如果你的应用有一部分要代表登录用户行动,那部分继续用 OAuth 和官方 API。
只读 key 更安全吗? ★实质上更安全。★ 用户 token 泄露意味着有人能用你的身份发帖;只读 key 泄露意味着有人能花你的配额。是两种很不一样的糟糕日子。
该逐步迁移还是一次切换? 逐步,用开关控制,并且让对比脚本在两边都跑着。 一次性切换会让你同时在调试迁移和调试数据。
翻页的页大小需要改吗?
时间线把 limit 设到最多 200——那就是一次调用的全部结果。粉丝列表的 limit 是游标逐页走的页大小,调大意味着请求更少。
能继续用 Tweepy 的数据模型吗? 不能直接用——它们预期的是嵌套的 v2 结构。如果你的代码到处传这些对象,那个小的属性访问包装就是实际可行的折中。
最常见的迁移 bug 是什么?
★用 .get(..., "") 带默认值去读 description 或 name。 代码能跑、输出是空的,而日志里什么都不会说为什么。★
先跑那个 grep,再跑对比脚本——这两步决定了这件事是「几个小时」还是「根本做不了」。用 Google 注册送 $0.20 额度、不绑卡,两步都够用。