Python多版本文档目录自动化采集实战

1. 为什么需要采集多版本文档目录页？

在技术文档管理领域，版本迭代是常态。以Python官方文档为例，从2.7到3.12的每个版本都有独立的目录结构。当我们需要对比不同版本间的API变更、查找特定函数的历史实现时，手动逐个版本查看效率极低。这时，自动化采集所有版本目录页就显示出其价值：

• 版本对比分析：快速定位某个模块在不同版本间的增删改情况
• 离线文档构建：为内部知识库建立完整的版本存档
• API变更追踪：监控关键函数的接口变化历史
• 文档完整性校验：确保每个版本的目录结构完整无缺失

实际案例：某开源项目维护团队需要验证其兼容性声明，必须确认从Python 3.6到3.11的所有异步IO模块目录结构变化，手动操作需要数小时，而自动化采集可在5分钟内完成。

2. 环境准备与工具选型

2.1 基础环境配置

推荐使用Python 3.8+环境，这是目前最稳定的爬虫开发版本。关键依赖库包括：

bash复制pip install requests beautifulsoup4 tqdm html5lib

• requests：网络请求核心库（版本≥2.26.0以支持HTTPS正确验证）
• beautifulsoup4：HTML解析利器（配合html5lib解析器处理不规范的文档页面）
• tqdm：进度条显示（长时间采集时的用户体验优化）

2.2 反爬策略应对方案

文档类网站常见的防护措施及应对方法：

3. 目录页结构解析实战

以Python官方文档为例（https://docs.python.org/3/contents.html），其目录页的典型结构如下：

html复制<div class="toctree-wrapper compound">
  <ul>
    <li class="toctree-l1"><a class="reference internal" href="tutorial/index.html">1. 教程</a></li>
    <li class="toctree-l1"><a class="reference internal" href="library/index.html">2. 标准库</a>
      <ul>
        <li class="toctree-l2"><a class="reference internal" href="library/os.html">2.1 os — 操作系统接口</a></li>
        <!-- 更多子项 -->
      </ul>
    </li>
  </ul>
</div>

采集逻辑实现：

python复制def parse_toc(html):
    soup = BeautifulSoup(html, 'html5lib')
    toc = {'sections': []}
    
    for l1 in soup.select('.toctree-l1'):
        section = {
            'title': l1.a.text.strip(),
            'url': urljoin(base_url, l1.a['href']),
            'subsections': []
        }
        
        for l2 in l1.find_all('li', class_='toctree-l2', recursive=False):
            section['subsections'].append({
                'title': l2.a.text.strip(),
                'url': urljoin(base_url, l2.a['href'])
            })
        
        toc['sections'].append(section)
    
    return toc

4. 多版本自动化采集系统

4.1 版本发现机制

通过分析文档站点的版本选择器获取所有可用版本：

python复制def get_available_versions(index_url):
    res = requests.get(index_url)
    soup = BeautifulSoup(res.text, 'html5lib')
    
    versions = []
    for opt in soup.select('select.version-selector option'):
        if opt.get('value'):
            versions.append({
                'number': opt.text.strip(),
                'url': urljoin(index_url, opt['value'])
            })
    
    return sorted(versions, key=lambda x: parse_version(x['number']))

4.2 断点续采设计

使用SQLite实现采集状态持久化：

python复制import sqlite3

class CrawlerDB:
    def __init__(self, db_path):
        self.conn = sqlite3.connect(db_path)
        self._init_db()
    
    def _init_db(self):
        self.conn.execute('''CREATE TABLE IF NOT EXISTS versions
            (version TEXT PRIMARY KEY, status TEXT, timestamp DATETIME)''')
        self.conn.execute('''CREATE TABLE IF NOT EXISTS toc_items
            (id INTEGER PRIMARY KEY, version TEXT, path TEXT, 
             title TEXT, url TEXT, parent_path TEXT)''')
    
    def save_version_status(self, version, status='completed'):
        self.conn.execute(
            'INSERT OR REPLACE INTO versions VALUES (?, ?, CURRENT_TIMESTAMP)',
            (version, status)
        )
        self.conn.commit()

4.3 分布式采集优化

当需要处理数十个GB级文档时，可采用以下架构：

code复制主节点（调度） -> Redis任务队列 -> 工作节点（实际采集） -> 结果存储（MongoDB）

关键实现代码：

python复制# 主节点任务分发
def enqueue_versions(redis_conn, versions):
    for v in versions:
        redis_conn.rpush('doc:tasks', json.dumps({
            'version': v['number'],
            'base_url': v['url'],
            'priority': 0 if 'stable' in v['number'] else 1
        }))

# 工作节点处理
def worker_loop(redis_conn, db_conn):
    while True:
        task_data = redis_conn.blpop('doc:tasks', timeout=30)
        if not task_data:
            continue
            
        task = json.loads(task_data[1])
        try:
            toc = fetch_version_toc(task['base_url'])
            save_to_db(db_conn, task['version'], toc)
            redis_conn.rpush('doc:results', task['version'])
        except Exception as e:
            redis_conn.rpush('doc:failed', json.dumps({
                'task': task,
                'error': str(e)
            }))

5. 实战中的六大陷阱与解决方案

5.1 相对路径转绝对路径的坑

文档站点的链接经常使用相对路径，但不同版本的基准URL可能不同。错误示例：

python复制# 错误做法：直接拼接字符串
full_url = base_url + '/' + relative_path  # 可能产生双斜杠

正确解决方案：

python复制from urllib.parse import urljoin

full_url = urljoin(base_url + '/' if not base_url.endswith('/') else base_url, 
                  relative_path.lstrip('/'))

5.2 动态生成的目录结构

某些文档系统（如GitBook）会通过JavaScript动态生成目录。检测方法：

python复制if len(soup.select('.toctree')) == 0 and 'window.tocTree' in res.text:
    print('检测到动态生成目录，需启用浏览器自动化')

解决方案：使用requests-html的浏览器模式

python复制from requests_html import HTMLSession

session = HTMLSession(browser_args=["--no-sandbox"])
res = session.get(url)
res.html.render(timeout=20)
soup = BeautifulSoup(res.html.html, 'html.parser')

5.3 版本别名导致的重复采集

某些文档站会为同一版本设置多个别名（如"latest"指向"3.11"）。去重逻辑：

python复制seen_versions = set()
for v in versions:
    canonical_num = v['number'].split()[0]  # 处理"3.11 (stable)"这种情况
    if canonical_num in seen_versions:
        continue
    seen_versions.add(canonical_num)
    # 处理该版本...

5.4 反爬策略的智能规避

实现自适应延迟控制：

python复制class AdaptiveDelayer:
    def __init__(self, base_delay=1.0):
        self.base = base_delay
        self.last_response_time = None
    
    def __call__(self):
        if self.last_response_time is None:
            time.sleep(self.base)
        else:
            # 根据上次响应时间动态调整
            adjust = min(3.0, self.last_response_time * 1.5)
            time.sleep(max(0.5, adjust))

5.5 大版本间的HTML结构差异

需要编写版本适配器模式：

python复制class ParserFactory:
    @classmethod
    def get_parser(cls, version):
        major_ver = int(version.split('.')[0])
        if major_ver < 3:
            return LegacyPythonParser()
        elif 3 <= major_ver <= 5:
            return EarlyPython3Parser()
        else:
            return ModernPythonParser()

5.6 内容编码的历史问题

处理不同时期的编码声明：

python复制def decode_response(res):
    if res.encoding == 'ISO-8859-1':
        # 尝试检测实际编码
        for enc in ['utf-8', 'gb2312', 'shift_jis']:
            try:
                return res.content.decode(enc)
            except UnicodeDecodeError:
                continue
    return res.text

6. 结果存储与后续处理

6.1 结构化存储方案

推荐使用SQLite+JSON混合存储模式：

python复制# 数据库表结构
CREATE TABLE doc_versions (
    id INTEGER PRIMARY KEY,
    version TEXT UNIQUE,
    toc_json TEXT,  -- 完整目录结构
    snapshot_date TEXT
);

CREATE TABLE doc_pages (
    id INTEGER PRIMARY KEY,
    version TEXT,
    path TEXT,
    content_hash TEXT,  -- 用于去重
    FOREIGN KEY(version) REFERENCES doc_versions(version)
);

6.2 差异对比可视化

生成版本间变更报告：

python复制def generate_diff_report(ver1, ver2):
    # 使用difflib进行文本对比
    differ = difflib.HtmlDiff()
    return differ.make_file(
        get_toc_lines(ver1),
        get_toc_lines(ver2),
        fromdesc=ver1,
        todesc=ver2
    )

6.3 自动化监控实现

设置定时任务检测新版本：

python复制def check_for_updates():
    known_versions = get_saved_versions()
    current_versions = get_available_versions()
    
    new_versions = [
        v for v in current_versions 
        if v['number'] not in known_versions
    ]
    
    if new_versions:
        send_alert_email(new_versions)
        auto_start_crawler(new_versions)

7. 性能优化实战技巧

7.1 连接池配置

优化requests的HTTPAdapter：

python复制from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

session = requests.Session()
retries = Retry(
    total=3,
    backoff_factor=0.5,
    status_forcelist=[500, 502, 503, 504]
)
adapter = HTTPAdapter(
    max_retries=retries,
    pool_connections=10,
    pool_maxsize=30,
    pool_block=True
)
session.mount('http://', adapter)
session.mount('https://', adapter)

7.2 异步IO改造

使用aiohttp实现异步采集：

python复制import aiohttp
import asyncio

async def fetch_toc(session, url):
    try:
        async with session.get(url) as resp:
            html = await resp.text()
            return parse_toc(html)
    except Exception as e:
        print(f"Error fetching {url}: {str(e)}")
        return None

async def crawl_all(versions):
    connector = aiohttp.TCPConnector(limit=5)
    async with aiohttp.ClientSession(connector=connector) as session:
        tasks = [fetch_toc(session, v['url']) for v in versions]
        return await asyncio.gather(*tasks, return_exceptions=True)

7.3 缓存策略实现

使用磁盘缓存避免重复下载：

python复制from hashlib import md5
import os

def get_cache_key(url):
    return md5(url.encode()).hexdigest()

def cached_get(url, cache_dir='.cache', expire_days=7):
    os.makedirs(cache_dir, exist_ok=True)
    cache_file = os.path.join(cache_dir, get_cache_key(url))
    
    if os.path.exists(cache_file):
        mtime = os.path.getmtime(cache_file)
        if time.time() - mtime < expire_days * 86400:
            with open(cache_file, 'rb') as f:
                return f.read().decode()
    
    res = requests.get(url)
    with open(cache_file, 'wb') as f:
        f.write(res.content)
    return res.text

8. 法律合规与道德边界

8.1 robots.txt合规检查

自动解析目标站点的爬虫协议：

python复制from urllib.robotparser import RobotFileParser

def check_robots_permission(base_url):
    rp = RobotFileParser()
    robots_url = urljoin(base_url, '/robots.txt')
    rp.set_url(robots_url)
    try:
        rp.read()
        return rp.can_fetch('MyCrawler/1.0', base_url)
    except Exception:
        return True  # 无法获取robots.txt时默认允许

8.2 合理延迟设置

行业建议的爬虫间隔：

8.3 版权内容处理策略

python复制def is_copyrighted(content):
    copyright_phrases = [
        "All rights reserved",
        "©",
        "未经授权禁止转载"
    ]
    return any(phrase in content for phrase in copyright_phrases)

def handle_copyrighted_content(url, content):
    if is_copyrighted(content):
        store_only_metadata({
            'url': url,
            'title': extract_title(content),
            'last_updated': datetime.now()
        })
        return None
    return content