claude-skills 项目中的 Python 打包与工程化实践从 pyproject.toml 到 CI/CD 完整指南【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills导读本文以 claude-skills 仓库中 python-pro 技能的 packaging.md 参考文档为核心骨架系统讲解现代 Python 项目的打包、工程化与发布全流程从 src 布局与pyproject.toml的完整配置到 Poetry 依赖管理、虚拟环境、类型桩文件、CLI 入口、构建发布、CI/CD 与 pre-commit 钩子。读完本文你将获得一套可直接复制的生产级 Python 项目模板并理解 claude-skills 仓库自身如 ruff.toml、pyrightconfig.json、Makefile是如何践行这些规范的。一、项目结构为什么优先选择 src 布局packaging.md 给出的标准工程结构如下myproject/ ├── pyproject.toml # 项目元数据与依赖 ├── README.md # 项目描述 ├── .gitignore # Git 忽略规则 ├── .python-version # pyenv 指定 Python 版本 ├── src/ │ └── myproject/ │ ├── __init__.py # 包初始化 │ ├── py.typed # PEP 561 类型标记 │ ├── core.py # 核心功能 │ └── utils.py # 工具函数 ├── tests/ │ ├── __init__.py │ ├── conftest.py # Pytest 配置 │ └── test_core.py # 测试 └── docs/ └── index.md # 文档采用src/布局的核心收益在于隔离未打包代码在项目根目录运行时测试或脚本必须依赖已安装的包才能通过 import避免了能跑但打包后不可用的假阳性。这与 python-pro 技能在 SKILL.md 中Setting up pytest test suites with fixtures and mocking及 Building packages with Poetry and proper project structure的工作项严格对应。注意两个容易被忽略的文件.python-version配合 pyenv 使用锁定当前目录的 Python 版本py.typed空文件即声明本包携带类型信息供 mypy 等类型检查器在第三方调用方侧启用类型推断。二、pyproject.toml 完整配置详解packaging.md 给出了以 Hatchling 为构建后端的完整配置自 PEP 518 / PEP 621 以来pyproject.toml已成为事实标准[build-system] requires [hatchling] build-backend hatchling.build [project] name myproject version 0.1.0 description A Python project readme README.md requires-python 3.11 license {text MIT} authors [ {name Your Name, email youexample.com} ] keywords [python, package] classifiers [ Development Status :: 4 - Beta, Intended Audience :: Developers, License :: OSI Approved :: MIT License, Programming Language :: Python :: 3.11, Programming Language :: Python :: 3.12, Typing :: Typed, ] dependencies [ requests2.31.0, pydantic2.5.0, ] [project.optional-dependencies] dev [ pytest7.4.0, pytest-cov4.1.0, mypy1.7.0, black23.11.0, ruff0.1.6, ] docs [ mkdocs1.5.0, mkdocs-material9.4.0, ] [project.scripts] myproject myproject.cli:main [project.urls] Homepage https://github.com/username/myproject Documentation https://myproject.readthedocs.io Repository https://github.com/username/myproject Changelog https://github.com/username/myproject/blob/main/CHANGELOG.md # Tool configurations [tool.black] line-length 100 target-version [py311] include \.pyi?$ [tool.ruff] line-length 100 target-version py311 select [ E, # pycodestyle errors W, # pycodestyle warnings F, # pyflakes I, # isort B, # flake8-bugbear C4, # flake8-comprehensions UP, # pyupgrade ] ignore [] [tool.ruff.per-file-ignores] __init__.py [F401] # Ignore unused imports in __init__.py [tool.mypy] python_version 3.11 strict true warn_return_any true warn_unused_configs true disallow_untyped_defs true [[tool.mypy.overrides]] module third_party.* ignore_missing_imports true [tool.pytest.ini_options] minversion 7.0 addopts [ -ra, --strict-markers, --strict-config, --covmyproject, --cov-reportterm-missing, --cov-reporthtml, ] testpaths [tests] pythonpath [src] [tool.coverage.run] source [src] branch true [tool.coverage.report] exclude_lines [ pragma: no cover, def __repr__, raise AssertionError, raise NotImplementedError, if __name__ .__main__.:, if TYPE_CHECKING:, ]关键配置项解读[build-system]声明构建后端为 Hatchlingrequires在构建沙箱中安装若切换到 Poetry 则改为poetry-core切换到 setuptools 则写setuptools.build_meta。[project]PEP 621 元数据区。requires-python 3.11与 python-pro 技能的定位Python 3.11一致classifiers中Typing :: Typed与py.typed标记相互印证。[project.optional-dependencies]将dev与docs拆分为可选依赖组安装时用pip install -e .[dev]引入。[project.scripts]声明控制台脚本入口myproject myproject.cli:main表示安装后生成名为myproject的命令指向cli.py中的main()。工具配置内联black、ruff、mypy、pytest、coverage 的配置全部收敛到pyproject.toml避免散落多个.cfg/.ini文件。与仓库真实配置的对照claude-skills 仓库根目录的 ruff.toml 就是这套配置内联到单一文件理念的落地实例它额外展示了实践中更长的规则选择清单include [scripts/*.py] target-version py311 line-length 120 [format] quote-style double indent-style space [lint] select [ E, # pycodestyle errors W, # pycodestyle warnings F, # pyflakes I, # isort UP, # pyupgrade B, # flake8-bugbear SIM, # flake8-simplify RUF, # ruff-specific ] ignore [E501] # line length handled by formatter [lint.isort] force-sort-within-sections true对比可见真实工程的两个演进点一是行宽从 100 调整为 120并与 formatter 分工忽略 E501二是将select移入新版[lint]表ruff 0.9 推荐结构并补充了SIM简化写法与RUFruff 专属两类规则。仓库还提供 pyrightconfig.jsonpythonVersion: 3.11、typeCheckingMode: basic与 mypy 构成双保险的类型检查路径。三、Poetry 项目管理与常用命令若团队选择 Poetrypyproject.toml 采用以下布局依赖由[tool.poetry]管理而非[project]# pyproject.toml for Poetry [tool.poetry] name myproject version 0.1.0 description A Python project authors [Your Name youexample.com] readme README.md license MIT packages [{include myproject, from src}] [tool.poetry.dependencies] python ^3.11 requests ^2.31.0 pydantic ^2.5.0 [tool.poetry.group.dev.dependencies] pytest ^7.4.0 pytest-cov ^4.1.0 mypy ^1.7.0 black ^23.11.0 ruff ^0.1.6 [tool.poetry.scripts] myproject myproject.cli:main [build-system] requires [poetry-core] build-backend poetry.core.masonry.api注意 Poetry 独有的两个字段packages [{include myproject, from src}]显式声明从src/下打包是 Poetry 支持 src 布局的关键[tool.poetry.group.dev.dependencies]新版分组语法等价于旧版[tool.poetry.dev-dependencies]。常用命令速查poetry init # Initialize new project poetry add requests # Add dependency poetry add --group dev pytest # Add dev dependency poetry install # Install dependencies poetry update # Update dependencies poetry shell # Activate virtual environment poetry run pytest # Run command in venv poetry build # Build package poetry publish # Publish to PyPI poetry export -f requirements.txt --output requirements.txt其中poetry run pytest保证测试在 Poetry 管理的虚拟环境中执行而不是意外使用系统 Pythonpoetry export用于把锁定的依赖导出为requirements.txt便于无 Poetry 环境如部分 CI 或 Docker 镜像复现。四、虚拟环境管理venv、virtualenv 与 pyenv 组合packaging.md 给出三种层级的管理方案# Using venv (built-in) python -m venv .venv source .venv/bin/activate # Linux/Mac .venv\Scripts\activate # Windows # Install in editable mode pip install -e . pip install -e .[dev] # With optional dependencies # Using virtualenv pip install virtualenv virtualenv venv source venv/bin/activate # Using pyenv for Python version management pyenv install 3.11.6 pyenv local 3.11.6 # Set for current directory echo 3.11.6 .python-version实践要点venv 是首选Python 3.3 内置无需额外安装python -m venv .venv统一将环境放在项目内.venv/目录配合.gitignore排除。editable 安装pip install -e .将项目以可编辑模式安装源码修改即时生效是日常开发与测试的标配-e .[dev]同时装上可选依赖组。[tool.pytest.ini_options]中的pythonpath [src]与pip install -e .双管齐下保证import myproject解析正确。pyenv 管版本pyenv local 3.11.6会在目录生成.python-version文件即第一节结构中那个隐藏文件实现按目录切换 Python 版本也符合本技能面向 Python 3.11 的约束。五、包初始化与类型桩文件__init__.py的推荐写法# src/myproject/__init__.py MyProject - A Python package. from myproject.core import main_function, CoreClass from myproject.utils import helper_function __version__ 0.1.0 __all__ [main_function, CoreClass, helper_function] # Package-level configuration import logging logger logging.getLogger(__name__) logger.addHandler(logging.NullHandler())三个细节值得学习__all__明确定义from myproject import *的导出白名单也辅助工具生成 API 文档库代码必须添加logging.NullHandler()避免未配置 root logger 的宿主程序里库抛No handler found告警这是发布为第三方库的行业惯例从core、utils重新导出让使用方只需from myproject import CoreClass无需关心内部模块路径。py.typed与 stub 文件# src/myproject/py.typed # Empty file indicates package includes type hints # src/myproject/__init__.pyi (optional stub file) from typing import Any __version__: str def main_function(arg: str) - dict[str, Any]: ... class CoreClass: def __init__(self, name: str) - None: ... def process(self) - str: ...py.typed是 PEP 561 定义的类型标记文件存在即向 mypy 等检查器宣告此包自带类型信息使下游用户在使用该包时同样获得类型检查能力若源码未提供完整类型如纯 C 扩展或不想内联注解可提供.pyistub 文件__init__.pyi专门描述包对外 API 的形状。该实践与本技能 type-system.md 中为公开 API 提供完整类型标注的要求一致。六、CLI 入口点# src/myproject/cli.py import sys from typing import NoReturn def main() - NoReturn: Main CLI entry point. print(MyProject CLI) sys.exit(0) if __name__ __main__: main()main() - NoReturn的注解向 mypy 声明本函数永不正常返回配合sys.exit(0)明确退出码。该函数与[project.scripts]或 Poetry 的[tool.poetry.scripts]绑定后用户即可在任意位置直接运行myproject命令。注意if __name__ __main__:的分支保留在模块尾部保证python -m myproject.cli与安装后的 console script 两种调用方式都可用。七、Requirements 文件与依赖锁定策略当不使用 Poetry 或需要导出时packaging.md 给出了分层 requirements 方案# requirements.txt - Production dependencies requests2.31.0,3.0.0 pydantic2.5.0,3.0.0 # requirements-dev.txt - Development dependencies -r requirements.txt pytest7.4.0 pytest-cov4.1.0 mypy1.7.0 black23.11.0 ruff0.1.6 # Generate from Poetry poetry export -f requirements.txt --output requirements.txt --without-hashes poetry export -f requirements.txt --with dev --output requirements-dev.txt生产依赖requirements.txt与开发依赖requirements-dev.txt分层后者通过-r requirements.txt继承前者避免两处维护同一份清单通过poetry export可以保持 Poetry 为唯一事实来源导出物仅作为兼容层的产物--without-hashes用于去掉哈希字段以适配部分私有索引。依赖管理最佳实践# Pin dependencies for applications requests2.31.0 pydantic2.5.2 # Use ranges for libraries requests2.31.0,3.0.0 pydantic2.5.0,3.0.0 # Lock files # Poetry: poetry.lock # pip: requirements.txt with exact versions pip freeze requirements-lock.txt # Update dependencies poetry update pip install --upgrade -r requirements.txt规则可以概括为应用锁定库用范围,上限约束。应用部署必须可重复因此锁定精确版本并保留 lock 文件库则用有上限的范围如2.31.0,3.0.0避免意外破坏性升级同时给下游留出解析空间。八、构建、检查与发布流程# Build package python -m build # Check package twine check dist/* # Upload to PyPI twine upload dist/* # Upload to Test PyPI twine upload --repository testpypi dist/* # Install from Test PyPI pip install --index-url https://test.pypi.org/simple/ myproject发布流程中的关键守则是先试后发python -m build生成dist/下的 wheel 与 sdist需要pip install buildtwine check dist/*校验长描述渲染与元数据格式阻止损坏的包上传先上传 Test PyPItestpypi并安装验证再对正式 PyPI 执行twine upload dist/*测试安装务必指定--index-url https://test.pypi.org/simple/防止误装正式版。九、遗留方案setuptools 的 setup.py 与 MANIFEST.in对于存量项目或需要细粒度控制时setuptools 仍可工作# setup.py (if not using pyproject.toml) from setuptools import setup, find_packages setup( namemyproject, version0.1.0, packagesfind_packages(wheresrc), package_dir{: src}, python_requires3.11, install_requires[ requests2.31.0, pydantic2.5.0, ], extras_require{ dev: [ pytest7.4.0, mypy1.7.0, ], }, entry_points{ console_scripts: [ myprojectmyproject.cli:main, ], }, )与pyproject.toml的对应关系find_packages(wheresrc)package_dir{: src}等价于 src 布局extras_require对应[project.optional-dependencies]entry_points对应[project.scripts]。注意setup.py是遗留路径即使使用 setuptoolsPEP 621 也推荐把元数据写进pyproject.toml。当 sdist 需要包含元数据之外的额外文件时用MANIFEST.in# MANIFEST.in include README.md include LICENSE include pyproject.toml recursive-include src/myproject *.py recursive-include src/myproject py.typed recursive-include tests *.py prune docs/_buildinclude精确收录根级文件recursive-include按目录递归prune剔除构建产物目录——这一条保证py.typed也被打进 sdist从而保留类型信息能力。十、版本管理的三种模式packaging.md 给出统一版本来源的几种做法# src/myproject/__version__.py __version__ 0.1.0 # src/myproject/__init__.py from myproject.__version__ import __version__ # Read version in pyproject.toml import tomli from pathlib import Path def get_version() - str: pyproject Path(__file__).parent.parent / pyproject.toml with open(pyproject, rb) as f: data tomli.load(f) return data[project][version]单点定义把版本收敛到__version__.py__init__.py只做转发避免多处手写版本号漂移从 pyproject.toml 反向读取用tomliPython 3.11 中已并入标准库为tomllib解析pyproject.toml实现构建配置为唯一版本来源。这一模式常配合 CI 中按 tag 自动写入version 仓库根目录的 version.json 被 Makefile 读取python -c import json; print(json.load(open(version.json))[version])即为同类单一事实来源思想的旁证。十一、CI/CD 集成GitHub Actions 完整示例# .github/workflows/test.yml name: Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest strategy: matrix: python-version: [3.11, 3.12] steps: - uses: actions/checkoutv4 - name: Set up Python uses: actions/setup-pythonv4 with: python-version: ${{ matrix.python-version }} - name: Install dependencies run: | python -m pip install --upgrade pip pip install -e .[dev] - name: Run tests run: | pytest --cov --cov-reportxml - name: Type check run: mypy src - name: Lint run: | black --check src tests ruff check src tests - name: Upload coverage uses: codecov/codecov-actionv3该流水线体现的工程规范矩阵测试strategy.matrix在 Python 3.11 与 3.12 上并行跑全量测试保障多版本兼容安装即验证打包pip install -e .[dev]同时验证了可选依赖组定义的正确性四道关卡测试pytest 覆盖率 XML→ 类型mypy src→ 格式black --check→ 静态检查ruff check与 python-pro 技能 SKILL.md 中 Validate — Runmypy --strict,black,ruff 的工作流一一对应覆盖率上报--cov-reportxml供 Codecov 等服务汇总。claude-skills 仓库自身的 Makefile 就是类似的本地关卡实现lint目标依次执行ruff check scripts/、ruff format --check scripts/、pyright scripts/以及 prettier 的 Markdown/代码检查validate目标运行 validate-skills.py 与 validate-markdown.py。这与本节的 CI 设计同构适合在缺少托管 CI 时以make lint形式本地落地。十二、Pre-commit Hooks把检查前置到提交前# .pre-commit-config.yaml repos: - repo: https://github.com/psf/black rev: 23.11.0 hooks: - id: black - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.1.6 hooks: - id: ruff args: [--fix, --exit-non-zero-on-fix] - repo: https://github.com/pre-commit/mirrors-mypy rev: v1.7.1 hooks: - id: mypy additional_dependencies: [types-requests]# Install pre-commit pip install pre-commit pre-commit install # Run manually pre-commit run --all-filespre-commit install把钩子注册到 Git之后每次git commit自动运行已配置的检查未通过则阻止提交args: [--fix, --exit-non-zero-on-fix]让 ruff 自动修复问题并仅在仍有残留时以非零码退出兼顾自动化与显式反馈additional_dependencies: [types-requests]解决 mypy 对第三方库类型缺失的常见报错——这正对应pyproject.toml中[[tool.mypy.overrides]]对third_party.*模块ignore_missing_imports true的兜底思路提交前检查与 CI 形成快慢两道闸本地钩子拦截明显问题CI 矩阵在推送/PR 时做最终裁决。十三、完整工程化落地建议综合 packaging.md 全部章节一个现代 Python 3.11 项目的推荐落地路径是初始化用 src 布局 pyproject.tomlHatchling 或 Poetry写入requires-python 3.11、classifiers、可选依赖组开发python -m venv .venvpip install -e .[dev]用 pyenv 管理版本并提交.python-version类型与质量源码内联类型注解 py.typed标记mypy strict 与 ruff/black 配置全部内联在pyproject.toml参照 ruff.toml 的规则选择思路按需增删规则测试pytest 配置带--cov、--strict-markers、testpaths与pythonpath保持高覆盖率本技能要求 90%发布python -m build→twine check→ 先 Test PyPI 后正式 PyPI持续保障GitHub Actions 矩阵 pre-commit 钩子把测试、类型检查与 lint 固化为自动流程。通过 packaging.md 与仓库内实际配置ruff.toml、pyrightconfig.json、Makefile的对照可见这套打包与工程化规范并非纸上谈兵从单一配置文件的收敛、规则选择的演进到本地/CI 双重校验关卡均已在 claude-skills 仓库的脚本与工具链中得到真实实践可作为任何 Python 项目落地的直接参考模板。【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考