SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场setting-up-python-projects

setting-up-python-projects

编程与开发

查看项目

更新于 10-16 17:56

技能介绍

用途

本技能是 myai 的 setting-up-projects 的 Python 专属扩展。它只提供 Python 相关的工具链、配置和代码示例；项目形态决策框架、目录布局理念、bootstrap 清单哲学、优雅关闭策略和领域适配指导，均需先加载 setting-up-projects。同时依赖 engineering-principles（通过 myai bootstrap）。

适用时机：所有项目引导决策使用 setting-up-projects，当项目为 Python 时再加载本扩展。独立脚本使用 writing-scripts（myai）；后端/服务仓库在 myai 的 setting-up-backends 之后使用 setting-up-python-backends；已有项目的架构形态决策使用 architecting-python-changes。

所有模板、规则和文档位于上游源：https://github.com/quick-brown-foxxx/coding_rules_python。

主要能力

Python 项目布局

提供标准目录结构，包含 src/appname/（init.py、main.py、constants.py、core/、cli/、ui/、utils/、wrappers/、stubs/、shared/）、tests/（unit、integration、fixtures、conftest.py）、scripts/、tools/linting/、docs/、shared_tests/，以及 AGENTS.md、CLAUDE.md（符号链接）、pyproject.toml、.pre-commit-config.yaml、.gitignore、.vscode/ 等文件。

Python 初始化清单

  • 创建目录结构：mkdir -p src/APPNAME tests/unit tests/integration tests/fixtures scripts docs .vscode
  • 复制基线文件：templates/pyproject.toml → pyproject.toml（更新 [project] 段）、templates/AGENTS.md → AGENTS.md（填写 TODO）、templates/pre-commit-config.yaml、templates/gitignore、templates/vscode_settings.json、templates/vscode_extensions.json
  • bootstrap 会把 shared/ 渲染到 src/<package>/shared/，开发用 lint 检查渲染到 tools/linting/，测试渲染到 shared_tests/；之后裁剪未使用的模块和依赖
  • 复制 rules/coding_rules.md → docs/coding_rules.md
  • 创建符号链接：ln -s AGENTS.md CLAUDE.md
  • 规范本地 bootstrap 产物：skills/setting-up-python-projects/bootstrap_downstream_repo.sh [--package-name NAME] SOURCE_REPO TARGET_REPO（--package-name 默认 todo_package_name）
  • 裁剪复制的 shared 模块：保留实际使用的 src/<package>/shared/ 子目录（logging/、shortcuts/、subprocess.py）；tools/linting/ 仅开发用，不随 wheel 发布；保留 shared_tests/ 中对应测试
  • 创建入口点：init.py 中 version = "0.1.0"；main.py 保持精简，仅做最终交接
  • 创建初始测试 tests/test_main.py
  • 初始化环境：git init、uv sync、uv run poe lint_full、uv run poe test
  • 之后统一通过 uv 使用项目本地命令：uv run python、uv run pytest、uv run ruff、uv run basedpyright、uv run poe、uv run pre-commit；默认验证流程为 uv run poe lint_full 后接 uv run poe test

Python 优雅关闭

  • 脚本与简单 CLI：捕获 KeyboardInterrupt，返回 130（128 + SIGINT(2)，Unix 约定）
  • 子进程封装（仅 POSIX）：始终传 start_new_session=True 以创建进程组，便于杀掉整棵进程树；快速子任务用 os.killpg(pid, SIGKILL)；复杂工具封装用 SIGTERM 升级到 SIGKILL（等待 5 秒超时）；异步子进程用 asyncio.create_subprocess_exec，捕获 CancelledError 后 terminate，超时后 kill 并重新抛出
  • Windows 上 start_new_session + os.killpg 不存在，需使用 process.terminate()/kill()，或按操作系统分别实现

跨平台

成熟项目同等面向 Windows、macOS 和 Linux；刻意针对单一 OS 的项目是例外；独立脚本可保持 OS 特定。使用 platformdirs 获取用户目录（user_config_dir、user_data_dir、user_cache_dir、user_log_dir、user_state_dir），不要硬编码 ~/.config 或 ~/.local/state。上述 os.killpg / signal.SIGKILL 关闭模式仅限 POSIX，需为 Windows 添加分支。开发辅助（poe 任务、pyproject.toml 脚本）不要调用 POSIX 工具，改用 Python 辅助程序。

Bootstrap 脚本

使用 skills/setting-up-python-projects/bootstrap_downstream_repo.sh 作为规范本地 bootstrap 产物。它把运行时构建块渲染到 src/<package>/shared/，复制 tools/linting/（仅开发用）和 shared_tests/，提升模板文件与文档，创建 CLAUDE.md，然后在下游仓库运行 uv sync、uv run poe lint_full 和 uv run poe test。导入包名由 --package-name NAME 指定（默认 todo_package_name）。

Python 专属定制

  • pyproject.toml：调整 ruff 规则、pytest 标记、插件，以及针对生态缺口的窄范围合理覆盖。默认不放松严格类型检查；记录每个真实例外。
  • AGENTS.md：用项目专属架构、关键决策、领域词汇和工作流填写 TODO 段。这是 agent 的主要定位文档，要具体。技能部分：移除项目不会用到的技能（如纯 CLI 移除 building-multi-ui-apps），添加领域专属技能（如 building-qt-apps、setting-up-shortcuts）。
  • coding_rules.md：为领域扩展或覆盖规则，添加领域专属约定（如数据库迁移规则、API 版本策略、数据校验要求）。

用 banned-api 强制封装

当项目封装第三方库（为了类型、平台抽象或可替换性）时，通过 pyproject.toml 中 ruff 的 flake8-tidy-imports.banned-api 强制使用封装：

[tool.ruff.lint.flake8-tidy-imports.banned-api] "soundcard".msg = "Use src/wrappers/audio_backend.py instead" "faster_whisper".msg = "Use src/wrappers/transcriber.py instead"

当库类型不佳（需要类型化门面）、平台特定（需要抽象层）或可替换（需要稳定内部 API）时进行封装。模板 pyproject.toml 有注释示例，按项目取消注释并定制。在封装文件内部，通过 banned-api 配置中的 per-file ruff ignore（"src/wrappers/*".msg = ""）或在单个导入行使用 # noqa: TID251 来抑制禁令。

构建前调研

在不熟悉的领域或使用不熟悉的库搭建项目时：调研该领域的约定，查看同领域维护良好的项目如何组织；检查库兼容性，验证库之间以及与 basedpyright 严格模式能否协同工作（部分库类型存根较差，需尽早规划封装）；识别领域专属工具，某些领域有自己的 linter、formatter 或校验工具；检查 basedpyright 已知问题，部分库（numpy、pandas、SQLAlchemy）在严格模式下需要特定配置或存根包。

快速定制清单

目录布局匹配领域而非通用模板；依赖符合领域（经过调研而非猜测）；AGENTS.md 描述本项目而非通用 Python 项目；coding_rules.md 按需添加领域专属内容；测试结构反映本项目最重要的部分；basedpyright 配置考虑领域专属库的特殊性。

使用方式

先加载 setting-up-projects 完成项目形态决策，再加载本技能获取 Python 工具链。按初始化清单创建目录、复制模板、运行 bootstrap 脚本、初始化环境并验证。之后通过 uv 运行项目本地命令。

适用场景

新建 Python 项目、脚本或 CLI 的引导搭建。后端仓库使用 setting-up-python-backends（在 setting-up-backends 之后）；GUI+CLI 共享核心使用 building-multi-ui-apps；实现规则使用 writing-python-code。

限制

本技能仅提供 Python 专属工具、配置和代码示例，不含项目形态决策框架等通用内容，需配合 setting-up-projects 使用。子进程关闭模式仅限 POSIX，Windows 需另行处理。部分库在 basedpyright 严格模式下需要额外配置或存根包。