SEO Machine Python模块开发指南：类型注解、Docstring与测试约定完整手册

SEO Machine Python模块开发指南类型注解、Docstring与测试约定完整手册【免费下载链接】seomachineA specialized Claude Code workspace for creating long-form, SEO-optimized blog content for any business. This system helps you research, write, analyze, and optimize content that ranks well and serves your target audience.项目地址: https://gitcode.com/GitHub_Trending/se/seomachine 本文带你快速掌握SEO Machine项目一个专为生产 SEO 优化长文博客而设计的 Claude Code 工作区的 Python 模块开发规范data_sources/modules/目录下的 20 多个分析模块都遵循同一套约定——完整的类型注解Type Hints、Google 风格 Docstring、以及无需真实 API 密钥即可运行的 unittest 测试。无论你是想读懂现有代码还是想贡献新模块照这份指南做就能和现有代码库保持风格一致。 开发前先读这两份文档它们就是项目内建的开发者手册CLAUDE.md —— 架构说明与 Python 分析管线CONTRIBUTING.md —— 贡献流程与代码风格指南项目里的 Python 模块都在哪SEO Machine 的 Python 代码集中在一处结构非常清晰路径作用data_sources/modules/20 个分析模块关键词分析、可读性评分、SEO 质量评分等data_sources/requirements.txt全部第三方依赖numpy、pandas、textstat、scikit-learn 等tests/基于unittest的测试文件research_quick_wins.py 等根目录脚本可独立运行的研究脚本从模块中导入功能核心模块组成一条内容分析流水线见 CLAUDE.md 的 Architecture 章节search_intent_analyzer.py —— 搜索意图分类keyword_analyzer.py —— 关键词密度、分布与堆砌检测readability_scorer.py —— Flesch 可读性评分seo_quality_rater.py —— 0-100 分 SEO 综合评分开发新模块时先通读同目录下的 1-2 个现有模块风格上就能以老带新。类型注解约定每个公开方法都写全签名打开任意模块第一屏都能看到统一的导入方式示例来自 keyword_analyzer.py 开头from typing import Dict, List, Optional, Any三条硬性约定参数和返回值必须标注。公开方法如analyze()的签名形如def analyze(self, content: str, primary_keyword: str, secondary_keywords: Optional[List[str]] None, target_density: float 1.5) - Dict[str, Any]:可选参数用Optional[List[str]] None。项目不用list[str] | None这类新式写法而是统一使用typing模块的Optional、List、Dict兼容性最好。返回大结果集时统一用Dict[str, Any]。分析模块的产出是结构化报告指标 建议例如 readability_scorer.py 的analyze()返回包含overall_score、grade、recommendations等键的字典。这样上层聚合模块如 data_aggregator.py可以按 key 稳定取数。Docstring 约定三段式写法SEO Machine 的文档字符串采用模块级 类级 方法级三段式风格统一为 Google 风格① 模块级 docstring第一行是模块名随后 1-2 行说明用途。keyword_analyzer.py 的开头就是范本 Keyword Analyzer Calculates keyword density, analyzes distribution, and performs semantic clustering to identify keyword usage patterns and topic clusters within content. ② 类级 docstring一句话点明职责例如Analyzes content readability using multiple metrics见 readability_scorer.py。③ 方法级 docstring公开方法必须写清Args:和Returns:def analyze(self, content: str) - Dict[str, Any]: Comprehensive readability analysis Args: content: Article content to analyze Returns: Dict with readability scores, metrics, and recommendations 私有辅助方法以下划线开头则用一行简短注释即可如Clean content for readability analysis。这个公开方法详尽、私有方法简洁的分级写法是通读代码时最快的定位线索。测试约定不碰真实 API 也能测 最有特色的一条SEO Machine 的模块大量依赖 GA4、GSC、DataForSEO 等付费/密钥 API所以 tests/ 目录的测试约定核心是测试绝不发起真实网络请求只验证韧性resilience与纯逻辑。以 tests/test_dataforseo_resilience.py 为例有 5 个值得照抄的约定用标准库unittest类名以Tests结尾如DataForSEOResilienceTests文件末尾固定加if __name__ __main__: unittest.main()支持单独运行。用importlib.util.spec_from_file_location按文件路径加载被测模块而不是importMODULE_PATH (Path(__file__).resolve().parents[1] / data_sources / modules / dataforseo.py) spec importlib.util.spec_from_file_location(dataforseo_under_test, MODULE_PATH)模块名带_under_test后缀避免与真实 import 的模块冲突。桩替换Stub替代真实依赖。测试会直接把_post方法替换成返回固定结构的lambda模拟 API 各种异常响应。更彻底的例子是 tests/test_research_quick_wins_helpers.py它往sys.modules里注入伪造的dotenv、modules.google_search_console等模块从而在无密钥环境下加载脚本。断言失败不崩溃。测试的重点场景是API 返回空结果、任务缺失、抛出异常时方法应返回{error: ...}、空列表[]或降级结果而不是抛出异常。这正是数据源模块被要求具备的容错行为。运行方式项目未配置 pytest直接用标准库python -m unittest discover tests/贡献新模块的最佳实践清单 综合 CONTRIBUTING.md 与现有代码提交前过一遍文件放data_sources/modules/命名snake_case.py类名PascalCase模块头有名称 用途docstring公开方法带Args:/Returns:所有公开方法参数与返回值带类型注解可选参数用Optional新增第三方依赖同步更新 data_sources/requirements.txtAPI 类模块的异常路径返回错误字典而非崩溃并配套写一个tests/test_xxx_resilience.py在 data_sources/README.md 或 README.md 中补充模块说明快速上手本地跑起来git clone https://gitcode.com/GitHub_Trending/se/seomachine cd seomachine pip install -r data_sources/requirements.txt python -m unittest discover tests/✅ 总结SEO Machine 的 Python 代码库把可读性贯彻到了开发规范本身——类型注解让接口一目了然三段式 Docstring 让模块自解释韧性测试让无密钥也能验证行为。照这个约定写代码你的新模块就能自然融入这条从 keyword_analyzer.py 到 seo_quality_rater.py 的内容分析流水线。【免费下载链接】seomachineA specialized Claude Code workspace for creating long-form, SEO-optimized blog content for any business. This system helps you research, write, analyze, and optimize content that ranks well and serves your target audience.项目地址: https://gitcode.com/GitHub_Trending/se/seomachine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考