【第46期】Python 项目规范把分析器、待办和测试收成可提交的目录CSDN 完整教程系列《从小白到 AI 大模型开发工程师的进阶之路》技术点AI-0134 Python 项目规范主人公小蓝伞前置AI-0130 测试AI-0006 Git本期产出标准项目模板前几期代码散落在 issue-41 到 issue-45。小蓝伞把todo.py和测试丢在桌面README 只有“运行 Python 文件”。自己的 IDE 一点就跑同事在干净目录中却先遇到导入失败再发现缺 requests最后还把真实todos.json提交进仓库。规范不是文件夹排版而是让下一个人包括一周后的自己在不知道聊天记录、不继承本机环境的情况下复现。本期交付一个可编辑安装的src布局模板并以“新目录、全新虚拟环境、只读 README、测试全绿、工作区干净”作为成功判据。一、小蓝伞遇到的问题缺依赖清单、缺测试入口、JSON 数据被 git 跟踪、日志和密钥进仓库。Windows 和 Linux 换行、路径混用。二、先给结论项目规范是复现契约目录、README、依赖、日志、测试和 Git 边界必须一次写清。推荐最小模板D:\ai-learning\issue-46\toolbox\ README.md requirements.txt pyproject.toml 或 requirements.txt src\toolbox\... tests\ data\.gitkeep .gitignore数据、密钥、__pycache__、.venv进 gitignore。测试不依赖 cwd。三、本文要解决什么项目内容目标把已有练习收成可安装、可测试、可提交的项目输入Python 源码、离线夹具、依赖声明、README输出toolbox包和可复制的开发命令环境Python 3.13.9、pip、Gitpytest 8.4.2成功判据干净目录安装成功pytest -q全绿git status不出现运行产物不在范围发布 PyPI、容器镜像、复杂流水线、生产密钥管理四、前置准备先确认python --version、python -m pip --version和git --version。迁移前给原练习目录做只读备份不要边移动边删除唯一副本。搜索.env、Token、Cookie、真实待办和绝对用户路径敏感内容先从待提交集合中移除。若敏感信息已经进入 Git 历史仅加入.gitignore不会抹掉历史必须立即轮换凭证并另行清理历史。本文把运行依赖和开发依赖都写进pyproject.toml不再同时维护一份内容重复的 requirements。若团队已有 lock 工具应沿用团队方案“锁定”不等于在教程里随意写死所有传递依赖。五、核心原理规范是复现契约不是把文件夹摆整齐。README 必须回答项目解决什么、支持什么环境、如何安装、如何运行、如何测试、数据放哪里、失败先查什么。命令要从项目根执行不能依赖作者已经手工设置的PYTHONPATH或 IDE source root。src布局的价值是阻止“恰好从仓库根导入同名目录”的假成功。项目先以python -m pip install -e .[dev]安装测试再导入已安装包换工作目录后仍然成立。入口通过[project.scripts]暴露命令调用者不需要知道cli.py藏在哪层。配置边界也要明确库模块只创建logging.getLogger(__name__)不调用basicConfig因为日志级别、格式和输出目的地属于应用入口。数据边界则分三类tests/fixtures放虚构且可公开的固定样本data/.gitkeep只保留目录真实运行数据和.env被忽略。错误写法是测试直接读data/todos.json它让测试依赖作者的私人状态正确写法是使用 pytest 的临时目录或版本化夹具。依赖声明还必须解释兼容区间。requests2.32,3表示允许同一主版本内更新并不保证每次安装字节级一致可复现部署还需要 lock 文件和哈希。本期目标是建立单一依赖来源和明确开发 extra不把“requirements 文件存在”误写成完全可复现。六、完整项目完整目录如下toolbox/ ├── .gitignore ├── README.md ├── pyproject.toml ├── src/ │ └── toolbox/ │ ├── __init__.py │ ├── cli.py │ └── calculator.py ├── tests/ │ ├── fixtures/ │ │ └── sample.json │ └── test_calculator.py └── data/ └── .gitkeeppyproject.toml同时声明包、运行依赖、开发依赖和命令入口[build-system] requires [setuptools80] build-backend setuptools.build_meta [project] name blue-umbrella-toolbox version 0.1.0 requires-python 3.11 dependencies [requests2.32,3] [project.optional-dependencies] dev [pytest8.4,9] [project.scripts] blue-toolbox toolbox.cli:main [tool.pytest.ini_options] testpaths [tests] addopts -ra.gitignore.venv/ __pycache__/ *.py[cod] .pytest_cache/ .coverage .env data/* !data/.gitkeepsrc/toolbox/calculator.py保留一个最小可测函数真实迁移时替换为第 4145 期已经验证的模块defadd(left:float,right:float)-float:返回两个数字之和。returnleftrightsrc/toolbox/cli.py只负责应用入口和日志策略importargparseimportloggingfromtoolbox.calculatorimportadd LOGGERlogging.getLogger(__name__)defmain()-int:解析两个数字并打印结果。parserargparse.ArgumentParser()parser.add_argument(left,typefloat)parser.add_argument(right,typefloat)argsparser.parse_args()logging.basicConfig(levellogging.INFO,format%(levelname)s %(message)s)resultadd(args.left,args.right)LOGGER.info(计算完成)print(result)return0tests/test_calculator.pyfromtoolbox.calculatorimportadddeftest_add():assertadd(1.5,2.5)4.0README 至少写明简介、前提、安装、运行、测试、数据边界和常见失败。Windows PowerShell 的全新环境步骤是cd D:\ai-learning\issue-46\toolbox python-m venv.venv.\.venv\Scripts\activate python-m pip install-e.[dev]blue-toolbox 1.5 2.5 python-m pytest-q git status--short预期命令输出4.0测试1 passed最后只出现你主动修改而尚未提交的源文件不出现.venv、缓存、.env或data中的 JSON。把第 41 期分析器和第 43 期待办迁进src时要同步删除 README 中旧的盘符启动命令统一改包导入不要让新旧两套入口同时存在。七、可复现失败案例环节记录构造方式在未安装项目的全新虚拟环境里从tests子目录直接运行 pytest现象作者 IDE 中全绿干净终端报ModuleNotFoundError: toolbox影响使用者开始手改sys.path每个人形成不同启动方式最初误判pytest 或 Windows 路径有 bug排查顺序查看解释器 -pip show- 当前目录 - 导入来源module.__file__根因IDE 隐式加入源码目录README 没有安装步骤修复使用src布局和 editable install测试从项目根执行复验删除旧环境在新目录只按 README 安装命令与测试均成功这不是生产事故而是可重复的交付演练。若python -c import toolbox; print(toolbox.__file__)指向项目之外的旧副本说明环境污染还没有排除。八、实验设计与数据本期不做性能微基准而做交付实验。自变量是目录是否干净、是否经过安装、启动目录和是否存在私人数据指标是命令退出码、导入来源、测试结果与git status。场景预期结果判定未安装直接import toolbox失败证明不依赖仓库根偶然导入editable install 后导入成功__file__指向当前项目src从另一目录运行入口成功不依赖 cwd删除data/*.json测试仍绿测试不依赖私人数据创建.env、缓存和真实 JSONgit status不显示忽略规则生效只阅读 README 重建环境测试全绿复现契约完成一次在作者机器上通过只能证明当前环境可用删除环境并重建才接近验证文档。更严格的项目还要在 Windows 和 Linux CI 建矩阵、检查最低 Python 版本、固定 lock 文件并扫描密钥这些属于后续边界。九、常见问题与避坑提交整个虚拟环境。文件量巨大且包含绝对路径、平台二进制。提交依赖声明由使用者重建。README 写作者用户名和盘符。示例以项目根为坐标需要外部数据时使用配置参数不写死个人路径。把 print 当库日志。库用模块 logger入口决定格式真正给用户的命令结果可以 print 到标准输出。测试修改真实 data。使用tmp_path与虚构夹具否则一次失败可能清空个人文件。一个提交同时迁目录、改逻辑和全量格式化。审查者无法区分行为变化。拆成可回滚的小提交。以为.gitignore会删除已跟踪文件。它只阻止未跟踪文件进入索引历史中的敏感信息仍需处理。十、平台、系统与库的差异Windows 激活脚本是.\.venv\Scripts\Activate.ps1若执行策略阻止可直接调用.\.venv\Scripts\python.exe -m pip不必为了教程永久降低全局策略。Linux/macOS 通常使用source .venv/bin/activate。控制台入口在两端由安装工具生成优先使用python -m形式排除 pip 指向错误解释器。路径一律用 pathlib。Git 换行策略应由团队统一并用.gitattributes明确不要把跨平台问题都归因于 CRLF。pyproject.toml是本期唯一依赖来源已有企业模板则遵循现有工具链。十一、验证清单删除并重建.venv只按 README 命令安装过程中不手工改PYTHONPATH。python -c import toolbox; print(toolbox.__file__)指向当前项目的src/toolbox。从项目外目录运行blue-toolbox 1.5 2.5仍输出4.0。python -m pytest -q全绿移走真实 data 后仍全绿。新建.env、data/private.json和缓存后git status --short不显示它们。rg D:\\|C:\\Users|TOKEN|COOKIE README.md src tests不应发现个人路径和明文凭证。README 中每条命令都由一个不了解迁移过程的人或干净环境实际执行。复现有不同层级“能安装”只是最低层。源码复现要求同一提交可取得环境复现要求 Python 与依赖范围明确行为复现要求固定夹具和测试得到相同结论部署复现还要求操作系统包、环境变量和外部服务契约可追溯。本期模板覆盖前三层的一部分不承诺构建出字节完全相同的产物。把范围说清比笼统写“环境可复现”更诚实。版本号也属于接口。0.1.0表示仍在早期阶段不意味着可以无记录地破坏命令参数。每次修改入口、数据格式或公开函数都应更新变更记录并说明迁移方式。包版本、Git 提交和数据 schema 解决不同问题代码回滚不能自动降级已经迁移的数据数据恢复也不能证明依赖仍兼容。最小 CI 可执行四步创建受支持 Python 环境、安装.[dev]、运行静态检查、执行 pytest。矩阵至少覆盖声明的最低版本与主要开发版本只有 3.13 通过不能证明requires-python 3.11真实成立。若没有条件跑 CI就把低版本标为待验证或收窄声明不能用配置文件替代证据。发布前的 Git 边界检查包括未跟踪文件、已跟踪敏感文件和历史泄漏三层。.gitignore只处理第一层git ls-files检查第二层历史扫描工具处理第三层。发现 Token 后先轮换再讨论清理提交。README 示例必须使用假值和占位符截图同样要脱敏。项目模板不应无限膨胀。只有当工具真实使用格式化、类型检查、覆盖率或构建发布时才加入对应配置空配置会制造维护负担。每新增一项都要在 README 给出运行命令和失败意义。规范的最终目标不是目录最像大型项目而是任何声明都能被命令验证、任何生成物都有明确归属、任何敏感数据都有清晰边界。迁移旧练习的顺序第一步只建立目录和安装入口不改业务。把旧函数移入src/toolbox保留原测试并让 editable install 后全绿这一提交只回答“位置改变但行为不变”。第二步把硬编码路径改成参数或资源定位用临时目录测试。第三步再统一日志、类型标注和格式。分阶段提交后任何回归都能定位到迁移、配置还是行为变更。包内资源不能继续用当前工作目录寻找。Python 代码文件旁的内部只读资源可以使用importlib.resources用户可修改数据则应放到显式配置的数据目录。把可写文件塞进安装包目录在普通用户权限、只读容器或升级覆盖时都会出问题。第 43 期待办的--data参数应继续保留而不是因打包就改回相对路径。README 的命令还要说明从哪里执行。python -m pytest在项目根运行入口命令可从任意目录运行开发安装命令只在包含 pyproject 的根目录运行。三者混写会制造新的 cwd 故障。每条命令后给一个可观察结果例如退出码、输出行或生成文件只写“运行测试”仍然不足以判断是否成功。依赖升级要有节奏。允许范围内的新版本应由自动化测试验证后合入而不是每次安装都在未知组合上碰运气安全修复也不能以“锁死所以不动”为借口长期忽略。运行依赖、开发依赖、可选功能分组能减少普通使用者的安装面。若 requests 只在抓取子命令使用还可以把它做成可选 extra但文档必须告诉使用者缺少时会看到什么。最后做一次“第三台机器”思考它没有你的 IDE 设置、盘符、缓存、全局 pytest、真实 JSON 和代理。项目若仍能按 README 安装、显示帮助、运行离线测试并保持 git 工作区干净这套规范才真正承担了沟通成本。否则目录再漂亮也只是作者机器的布景。许可证与贡献说明也要按交付对象决定。个人私有练习可以暂不添加公开仓库若希望他人复用需要明确许可证接受贡献时再说明分支、测试和提交要求。没有许可证不等于“随便用”README 也不能替代法律许可。本文不替用户选择许可证只提醒公开之前把代码、数据和第三方素材的授权分别核对。最后保留一个最小维护清单每次提交前运行测试与状态检查每次改依赖更新声明和验证记录每次改命令同步 README每次改数据结构写迁移每次准备公开先扫描凭证。清单短而可执行比一次性生成十几个空配置文件更能维持项目质量。十二、面试题与追问README 最重要的四句话是什么、怎么装、怎么跑、怎么测。追问缺哪句最致命怎么跑。为何忽略 data/*.json可能含私人待办。追问夹具怎么交放 tests/fixtures。库代码为什么不要 basicConfig抢 root logger。追问应用入口可以吗可以。版本锁定价值复现。追问锁太死怎么办区分运行依赖和开发依赖。规范和下阶段数据结构关系后面算法代码也要能测和提交否则复杂度对比无法复现。十三、小蓝伞的工程金句规范不是排版是复现契约。README 写不出来的步骤等于不存在。能克隆后跑绿项目才算开始。十四、本篇技术清单与下一期下一期进入阶段 2AI-0201 复杂度分析。关注合集Python 基础项目到此收口后面用同一套测试和目录谈算法。你克隆过跑不起来的项目吗能克隆后跑绿项目才算开始。官方资料https://docs.python.org/zh-cn/3/tutorial/modules.htmlhttps://pip.pypa.io/en/stable/reference/requirements-file-format/https://docs.pytest.org/en/stable/适用边界学习型小工具。不是完整打包发布教程。