㊗️本期内容已收录至专栏《Python爬虫实战》，持续完善知识体系与项目实战，建议先订阅收藏，后续查阅更方便～
㊙️本期爬虫难度指数：⭐⭐ (中级)
🉐福利：一次订阅后，专栏内的所有文章可永久免费看，持续更新中，保底1000+(篇)硬核实战内容。
全文目录：
- 🌟 开篇语
- 0️⃣ 前言（Preface）
- 1️⃣ 摘要（Abstract）
- 2️⃣ 背景与需求（Why）
- 3️⃣ 合规与注意事项（必写）
- 4️⃣ 技术选型与整体流程（What/How）
- 5️⃣ 环境准备与依赖安装（可复现）
- 6️⃣ 核心实现：请求层（Fetcher）
- 7️⃣ 核心实现：解析层（Parser）
- 8️⃣ 数据存储与导出（Storage）
- 9️⃣ 运行方式与结果展示（必写）
- 🔟 常见问题与排错（强烈建议写）
- 1️⃣1️⃣ 进阶优化（可视化报表 📊）
- 1️⃣2️⃣ 总结与延伸阅读
- 🌟 文末
- ✅ 专栏持续更新中｜建议收藏 + 订阅
- ✅ 互动征集
- ✅ 免责声明
🌟 开篇语
哈喽，各位小伙伴们你们好呀～我是【喵手】。
运营社区： C站 / 掘金 / 腾讯云 / 阿里云 / 华为云 / 51CTO
欢迎大家常来逛逛，一起学习，一起进步～🌟
我长期专注Python 爬虫工程化实战，主理专栏 《Python爬虫实战》：从采集策略到反爬对抗，从数据清洗到分布式调度，持续输出可复用的方法论与可落地案例。内容主打一个“能跑、能用、能扩展”，让数据价值真正做到——抓得到、洗得净、用得上。
📌专栏食用指南（建议收藏）
- ✅ 入门基础：环境搭建 / 请求与解析 / 数据落库
- ✅ 进阶提升：登录鉴权 / 动态渲染 / 反爬对抗
- ✅ 工程实战：异步并发 / 分布式调度 / 监控与容错
- ✅ 项目落地：数据治理 / 可视化分析 / 场景化应用
📣专栏推广时间：如果你想系统学爬虫，而不是碎片化东拼西凑，欢迎订阅专栏👉《Python爬虫实战》👈，一次订阅后，专栏内的所有文章可永久免费阅读，持续更新中。
💕订阅后更新会优先推送，按目录学习更高效💯～
0️⃣ 前言（Preface）
在软件开发的生命周期中，“弃用（Deprecation）”是新旧更替的必经之路。与其在编译报错时手忙脚乱，不如主动出击！今天我们要编写一个专门扫描软件官方文档的爬虫，自动化提取所有标记为deprecated的功能条目，并生成一份清晰的迁移指南。
读完本文你将获得：
- 掌握针对特定文档标签（如 Sphinx 的
.. deprecated::渲染结果）的精准抓取技术。 - 学会如何从非结构化描述中提取“替代方案（Alternatives）”。
- 产出一份结构化的
deprecated_features_report.csv。
1️⃣ 摘要（Abstract）
本文以 Python 官方文档为目标，演示了如何使用requests和BeautifulSoup4遍历文档索引，精准识别并抓取弃用功能（Deprecated Features）。重点讲解了如何处理文档中的嵌套警告块，并将其转化为包含功能名、弃用版本及建议方案的结构化数据集。
核心看点：文档 DOM 深度解析、富文本内容清洗、迁移策略提取。
2️⃣ 背景与需求（Why）
为什么要爬这个？
大型项目的维护者需要定期审计依赖库的健康度。手动查阅数百页的 Release Notes 极易遗漏关键信息。通过爬虫，我们可以：
- 自动化审计：快速比对当前项目使用的 API 是否已在弃用名单中。
- 迁移加速：直接提取文档中的“推荐替代方案”，节省二次搜索时间。
- 版本演进分析：通过统计不同版本的弃用频率，评估软件的变动剧烈程度。
目标字段清单：
feature_name：功能/函数/模块名deprecated_version：开始弃用的版本号deprecation_note：弃用原因说明alternative：官方建议的替代方案doc_url：该条目的官方文档原始链接
3️⃣ 合规与注意事项（必写）
抓取官方文档通常是合规且受支持的（文档本身就是为了传播），但仍需遵循：
- Robots.txt 尊重：大多数技术文档允许爬虫索引，但应避开后台搜索接口。
- 低频采集：官方文档服务器通常由 CDN 承载，但频繁请求仍可能触发 WAF 防护。建议设置
1s以上的请求间隔。 - 非侵入性：仅抓取公开展示的文字说明，不采集任何需要登录权限的内部预览版文档。
4️⃣ 技术选型与整体流程（What/How）
大多数现代软件文档（如 Python, Sphinx, ReadTheDocs）都是静态服务端渲染，非常适合使用高效的requests方案。
采集流程：
- [索引扫描]：访问文档的全局索引或搜索汇总页（如 Python 的
library/index.html）。 - [标记提取]：识别文档中特殊的警告框（CSS 类名通常为
.deprecated或.admonition-deprecated）。 - [语义清洗]：将文本中的“Use XXX instead”识别为替代方案字段。
- [导出]：生成 CSV 并通过 Pandas 进行分类汇总。
5️⃣ 环境准备与依赖安装（可复现）
确保你的 Python 版本为 3.9+。我们需要安装核心工具包：
pipinstallrequests beautifulsoup4 pandas tenacity matplotlib推荐项目结构：
doc_scanner/ ├── core/ │ ├── fetcher.py # 负责网页获取与重试 │ └── parser.py # 负责解析复杂的文档标签 ├── storage.py # 数据持久化 ├── main.py # 启动入口 └── reports/ # 存放输出 └── deprecated_features_list.csv6️⃣ 核心实现：请求层（Fetcher）
文档页通常路径较深，我们需要处理可能出现的 404 或超时。
# fetcher.pyimportrequestsfromtenacityimportretry,stop_after_attempt,wait_fixedclassDocFetcher:def__init__(self):self.headers={'User-Agent':'Mozilla/5.0 (Windows NT 10.0; Win64; x64) PythonDocAudit/1.0','Accept':'text/html,application/xhtml+xml,application/xml;q=0.9'}@retry(stop=stop_after_attempt(3),wait=wait_fixed(2))defget_content(self,url):try:resp=requests.get(url,headers=self.headers,timeout=15)resp.raise_for_status()returnresp.textexceptExceptionase:print(f"Error fetching{url}:{e}")raise7️⃣ 核心实现：解析层（Parser）
这是最关键的一步。在 Sphinx 框架渲染的文档中，弃用信息通常在<div class="deprecated">标签内。
# parser.pyfrombs4importBeautifulSoupimportreclassDocParser:defparse_deprecated_items(self,html,source_url):soup=BeautifulSoup(html,'lxml')results=[]# 寻找所有的弃用警告块dep_blocks=soup.select('div.deprecated, div.admonition-deprecated')forblockindep_blocks:# 1. 提取版本号 (通常在 span.versionmodified)version_tag=block.select_one('span.versionmodified')version_text=version_tag.get_text(strip=True)ifversion_tagelse""# 提取数字，如 "Deprecated since version 3.12" -> "3.12"version=re.search(r'version\s+([\d\.]+)',version_text)version_num=version.group(1)ifversionelse"Unknown"# 2. 确定功能名 (通常是警告块之前的标题或 parent 容器的 ID)# 这里通过查找最近的锚点(Anchor)来定位parent=block.find_parent(['dl','section','div'])feature_id=parent.get('id','Global Scope')ifparentelse"N/A"# 3. 提取说明与替代方案# 移除版本标签后的剩余文本即为说明ifversion_tag:version_tag.extract()# 移除它以便只拿说明文字note=block.get_text(strip=True)# 语义识别替代方案 (查找 "Use", "instead", "Replacement" 等关键词)alt_match=re.search(r'(?:Use|Instead use|Recommended replacement is)\s+([^.]+)',note,re.I)alternative=alt_match.group(1).strip()ifalt_matchelse"See documentation"results.append({'feature_name':feature_id,'deprecated_version':version_num,'deprecation_note':note,'alternative':alternative,'doc_link':source_url})returnresults8️⃣ 数据存储与导出（Storage）
我们使用 CSV 进行存储，方便开发者在 Excel 中直接筛选特定版本。
# storage.pyimportpandasaspdclassDeprecatedStorage:def__init__(self,filename='reports/deprecated_features_list.csv'):self.filename=filenamedefexport(self,data_list):ifnotdata_list:returndf=pd.DataFrame(data_list)# 字段映射表# feature_name: str, deprecated_version: str, alternative: strdf.to_csv(self.filename,index=False,encoding='utf-8-sig')print(f"📊 Report generated:{len(df)}items found.")9️⃣ 运行方式与结果展示（必写）
# main.pyfromcore.fetcherimportDocFetcherfromcore.parserimportDocParserfromstorageimportDeprecatedStoragedefmain():# 示例：Python 官方文档中关于 collections 模块的弃用说明urls=["https://docs.python.org/3/library/collections.html","https://docs.python.org/3/library/stdtypes.html"]fetcher=DocFetcher()parser=DocParser()storage=DeprecatedStorage()all_deprecated=[]forurlinurls:print(f"🔍 Scanning:{url}")html=fetcher.get_content(url)items=parser.parse_deprecated_items(html,url)all_deprecated.extend(items)storage.export(all_deprecated)if__name__=="__main__":main()输出示例 (3行结果)：
| feature_name | deprecated_version | alternative | doc_link |
|---|---|---|---|
| collections.Mapping | 3.10 | collections.abc.Mapping | https://…/collections.html |
| asyncio.get_event_loop | 3.12 | asyncio.get_running_loop | https://…/asyncio.html |
| imp.find_module | 3.4 | importlib | https://…/imp.html |
🔟 常见问题与排错（强烈建议写）
HTML 抓到空壳（SPA 文档）：
- 现象：React 或一些现代框架使用 Docusaurus 编写，内容是动态加载的。
- 对策：这种文档通常会预渲染静态
index.json或search-index.js。直接抓取这些 JSON 文件，解析效率提升 10 倍！
选择器失效：
- 原因：不同版本的 Sphinx 渲染出的类名可能从
deprecated变成admonition-deprecated。 - 对策：使用
soup.find_all(class_=re.compile('deprecated'))模糊匹配类名。
- 原因：不同版本的 Sphinx 渲染出的类名可能从
替代方案提取不准：
- 原因：自然语言描述各异。
- 对策：这是本爬虫的难点。进阶做法是将解析出的
note喂给本地的 LLM（如 Ollama），让它精准提取Suggested Replacement。
1️⃣1️⃣ 进阶优化（可视化报表 📊）
我们可以统计各版本弃用功能的数量，通过图表直观展示软件的架构演进。
defplot_deprecation_trend():importpandasaspdimportmatplotlib.pyplotasplt df=pd.read_csv('reports/deprecated_features_list.csv')# 统计每个版本的数量trend=df['deprecated_version'].value_counts().sort_index()plt.figure(figsize=(10,5))trend.plot(kind='line',marker='o',color='#E74C3C')# 强制全英文标签plt.title('Software Feature Deprecation Trend',fontsize=14)plt.xlabel('Deprecated Version',fontsize=12)plt.ylabel('Number of Features',fontsize=12)plt.grid(True,linestyle='--',alpha=0.6)plt.tight_layout()plt.savefig('reports/deprecation_chart.png')print("📈 Visualization saved: reports/deprecation_chart.png")1️⃣2️⃣ 总结与延伸阅读
通过本文，我们构建了一个能够深入软件文档底层，自动识别“弃用陷阱”的搜索型爬虫。这套方案对于维护长期项目的代码质量具有不可替代的价值。
下一步：
- 接入 CI/CD：在每次更新依赖库前自动运行，生成依赖审计报告。
- 搜索型进化：结合
Google Search API或Bing Search，自动根据“Software Name + deprecated”关键词寻找所有相关的三方库弃用信息。
🌟 文末
好啦～以上就是本期的全部内容啦！如果你在实践过程中遇到任何疑问，欢迎在评论区留言交流，我看到都会尽量回复～咱们下期见！
小伙伴们在批阅的过程中，如果觉得文章不错，欢迎点赞、收藏、关注哦～
三连就是对我写作道路上最好的鼓励与支持！❤️🔥
✅ 专栏持续更新中｜建议收藏 + 订阅
墙裂推荐订阅专栏 👉 《Python爬虫实战》，本专栏秉承着以“入门 → 进阶 → 工程化 → 项目落地”的路线持续更新，争取让每一期内容都做到：
✅ 讲得清楚（原理）｜✅ 跑得起来（代码）｜✅ 用得上（场景）｜✅ 扛得住（工程化）
📣想系统提升的小伙伴：强烈建议先订阅专栏 《Python爬虫实战》，再按目录大纲顺序学习，效率十倍上升～
✅ 互动征集
想让我把【某站点/某反爬/某验证码/某分布式方案】等写成某期实战？
评论区留言告诉我你的需求，我会优先安排实现(更新)哒~
⭐️ 若喜欢我，就请关注我叭～（更新不迷路）
⭐️ 若对你有用，就请点赞支持一下叭～（给我一点点动力）
⭐️ 若有疑问，就请评论留言告诉我叭～（我会补坑 & 更新迭代）
✅ 免责声明
本文爬虫思路、相关技术和代码仅用于学习参考，对阅读本文后的进行爬虫行为的用户本作者不承担任何法律责任。
使用或者参考本项目即表示您已阅读并同意以下条款：
- 合法使用： 不得将本项目用于任何违法、违规或侵犯他人权益的行为，包括但不限于网络攻击、诈骗、绕过身份验证、未经授权的数据抓取等。
- 风险自负： 任何因使用本项目而产生的法律责任、技术风险或经济损失，由使用者自行承担，项目作者不承担任何形式的责任。
- 禁止滥用： 不得将本项目用于违法牟利、黑产活动或其他不当商业用途。
- 使用或者参考本项目即视为同意上述条款,即 “谁使用，谁负责” 。如不同意，请立即停止使用并删除本项目。！！！
高亮主题)
