Python 打包實(shí)戰(zhàn)精要基于 pyproject.toml 的現(xiàn)代分發(fā)、CLI 與 PyPI 發(fā)布全流程【免費(fèi)下載鏈接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity項(xiàng)目地址: https://gitcode.com/GitHub_Trending/agents24/agents本文是 python-packaging 技能 的詳細(xì)模式參考references/details.md的技術(shù)解讀面向需要將 Python 庫(kù)、CLI 工具發(fā)布到 PyPI 或私有索引的開(kāi)發(fā)者。讀完本文你將掌握一套可直接復(fù)制的全功能 pyproject.toml配置、動(dòng)態(tài)版本管理、Click/argparse 兩種 CLI 注冊(cè)方式以及從本地構(gòu)建到 GitHub Actions 自動(dòng)化發(fā)布的完整鏈路并看到這些模式在當(dāng)前倉(cāng)庫(kù)真實(shí)工程如 plugin-eval、yt-design-extractor中的落地形態(tài)。文檔定位從導(dǎo)航到細(xì)節(jié)的第三層該技能采用導(dǎo)航 → 快速上手 → 細(xì)節(jié)參考的三級(jí)結(jié)構(gòu)SKILL.md負(fù)責(zé)給出包結(jié)構(gòu)、構(gòu)建后端setuptools/hatchling/flit/poetry、PEP 517/518/621/660 等核心概念與最小化示例references/details.md則是詳細(xì)模式與完整示例Detailed patterns and worked examples的承載文件編號(hào)從 Pattern 4 繼續(xù)向后延伸覆蓋完整配置、動(dòng)態(tài)版本、CLI、構(gòu)建與發(fā)布四大板塊。當(dāng)導(dǎo)航層信息不足以支撐實(shí)際落地時(shí)就應(yīng)讀取該細(xì)節(jié)文檔。本文即以此為骨架展開(kāi)。Pattern 4一份可直接落地的全功能 pyproject.tomldetails.md給出了從構(gòu)建系統(tǒng)、項(xiàng)目元數(shù)據(jù)到工具鏈配置一應(yīng)俱全的完整示例。下面按區(qū)塊逐段拆解其作用與含義。build-system聲明構(gòu)建后端[build-system] requires [setuptools61.0, wheel] build-backend setuptools.build_meta這是 PEP 517/518 所要求的最小聲明requires列出構(gòu)建時(shí)需要的隔離依賴(lài)此處要求 setuptools 不低于 61.0這是支持 pyproject.toml 元數(shù)據(jù)的關(guān)鍵版本門(mén)檻build-backend指定由setuptools.build_meta負(fù)責(zé)實(shí)際構(gòu)建。wheel的加入確保能同時(shí)產(chǎn)出 wheel 與源碼分發(fā)包。projectPEP 621 標(biāo)準(zhǔn)元數(shù)據(jù)[project] name my-awesome-package version 1.0.0 description An awesome Python package readme README.md requires-python 3.8 license {text MIT} authors [ {name Your Name, email youexample.com}, ] maintainers [ {name Maintainer Name, email maintainerexample.com}, ] keywords [example, package, awesome] classifiers [ Development Status :: 4 - Beta, Intended Audience :: Developers, License :: OSI Approved :: MIT License, Programming Language :: Python :: 3, Programming Language :: Python :: 3.8, Programming Language :: Python :: 3.9, Programming Language :: Python :: 3.10, Programming Language :: Python :: 3.11, Programming Language :: Python :: 3.12, ] dependencies [ requests2.28.0,3.0.0, click8.0.0, pydantic2.0.0, ]要點(diǎn)說(shuō)明readme支持字符串文件名或 TOML 表指定 content-type 與文本內(nèi)容license的{text MIT}寫(xiě)法適用于未使用 SPDX 表達(dá)式作為license字符串的 setuptools 版本。classifiers是 PyPI 頁(yè)面篩選與展示的核心元數(shù)據(jù)務(wù)必同時(shí)聲明License :: OSI Approved :: ...和各Programming Language :: Python :: 3.x條目并保持與requires-python一致。dependencies使用 PEP 508 規(guī)范說(shuō)明符。示例中的requests2.28.0,3.0.0是典型的兼容范圍寫(xiě)法既排除過(guò)舊版本又用上限擋住未來(lái)不兼容的大版本。optional-dependencies特性開(kāi)關(guān)[project.optional-dependencies] dev [ pytest7.0.0, pytest-cov4.0.0, black23.0.0, ruff0.1.0, mypy1.0.0, ] docs [ sphinx5.0.0, sphinx-rtd-theme1.0.0, ] all [ my-awesome-package[dev,docs], ]dev/docs分組可讓用戶(hù)按需安裝pip install -e .[dev]all分組通過(guò)自引用語(yǔ)法my-awesome-package[dev,docs]一次性聚合全部可選依賴(lài)是發(fā)布時(shí)常用的全家桶入口。這一模式在當(dāng)前倉(cāng)庫(kù)的 plugins/plugin-eval/pyproject.toml 中同樣可見(jiàn)——它將llmclaude-agent-sdk、apianthropic、devpytest/ruff/ty分別分組形成依賴(lài)分層。urls 與 scripts項(xiàng)目鏈接與命令行入口[project.urls] Homepage https://github.com/username/my-awesome-package Documentation https://my-awesome-package.readthedocs.io Repository https://github.com/username/my-awesome-package Bug Tracker https://github.com/username/my-awesome-package/issues Changelog https://github.com/username/my-awesome-package/blob/main/CHANGELOG.md [project.scripts] my-cli my_package.cli:main awesome-tool my_package.tools:run [project.entry-points.my_package.plugins] plugin1 my_package.plugins:plugin1[project.scripts]會(huì)在安裝時(shí)自動(dòng)生成可執(zhí)行命令如my-cli指向my_package.cli:main這是發(fā)布 CLI 工具的標(biāo)準(zhǔn)做法[project.entry-points]則允許第三方通過(guò)插件發(fā)現(xiàn)機(jī)制向你的包注冊(cè)擴(kuò)展點(diǎn)。當(dāng)前倉(cāng)庫(kù)中 plugin-eval 的 pyproject.toml 即注冊(cè)了plugin-eval plugin_eval.cli:app這一腳本入口指向 cli.py 中由 typer 創(chuàng)建的應(yīng)用對(duì)象。tool.setuptools包發(fā)現(xiàn)與數(shù)據(jù)文件[tool.setuptools] package-dir { src} zip-safe false [tool.setuptools.packages.find] where [src] include [my_package*] exclude [tests*] [tool.setuptools.package-data] my_package [py.typed, *.pyi, data/*.json]package-dir { src}將包根目錄指向src/配合packages.find.where [src]實(shí)現(xiàn) src 布局source layout自動(dòng)發(fā)現(xiàn)include/exclude控制匹配范圍。zip-safe false顯式聲明包不做 zip 導(dǎo)入避免資源文件在 zip 環(huán)境下失效。package-data聲明隨包安裝的非 Python 文件py.typed是 PEP 561 類(lèi)型標(biāo)記*.pyi是存根文件data/*.json是運(yùn)行時(shí)數(shù)據(jù)。這些資源在運(yùn)行時(shí)可通過(guò)importlib.resources讀取見(jiàn)后文高級(jí)模式。tool.black / tool.ruff / tool.mypy / tool.pytest / tool.coverage工具鏈統(tǒng)一配置[tool.black] line-length 100 target-version [py38, py39, py310, py311] include \.pyi?$ [tool.ruff] line-length 100 target-version py38 [tool.ruff.lint] select [E, F, I, N, W, UP] [tool.mypy] python_version 3.8 warn_return_any true warn_unused_configs true disallow_untyped_defs true [tool.pytest.ini_options] testpaths [tests] python_files [test_*.py] addopts -v --covmy_package --cov-reportterm-missing [tool.coverage.run] source [src] omit [*/tests/*] [tool.coverage.report] exclude_lines [ pragma: no cover, def __repr__, raise AssertionError, raise NotImplementedError, ]將格式化、lint、類(lèi)型檢查、測(cè)試與覆蓋率配置全部收攏進(jìn) pyproject.toml實(shí)現(xiàn)了單一配置源。當(dāng)前倉(cāng)庫(kù)的做法與此一致plugin-eval 在 pyproject.toml 中配置了[tool.ruff]line-length 100、[tool.ruff.lint]、[tool.ty]與[tool.pytest.ini_options]并且倉(cāng)庫(kù) Makefile 中的lint/test目標(biāo)均以u(píng)v run --extra dev方式在該項(xiàng)目目錄內(nèi)執(zhí)行確保使用鎖定的工具版本。Pattern 5動(dòng)態(tài)版本管理手工維護(hù)version 1.0.0容易與 git tag 脫節(jié)動(dòng)態(tài)版本是發(fā)布自動(dòng)化的重要一環(huán)[build-system] requires [setuptools61.0, setuptools-scm8.0] build-backend setuptools.build_meta [project] name my-package dynamic [version] description Package with dynamic version [tool.setuptools.dynamic] version {attr my_package.__version__} # Or use setuptools-scm for git-based versioning [tool.setuptools_scm] write_to src/my_package/_version.py兩種方式二選一屬性讀取[tool.setuptools.dynamic] version {attr my_package.__version__}從源碼讀取版本字符串配合# src/my_package/__init__.py __version__ 1.0.0 # Or with setuptools-scm from importlib.metadata import version __version__ version(my-package)git 派生setuptools-scm[tool.setuptools_scm]根據(jù) git tag 自動(dòng)推導(dǎo)版本并寫(xiě)入_version.py徹底消除手工同步。注意使用dynamic [version]后就不能再在[project]中寫(xiě)靜態(tài)version。CLI 模式Click 與 argparse 雙方案Pattern 6基于 Click 的分組命令# src/my_package/cli.py import click click.group() click.version_option() def cli(): My awesome CLI tool. pass cli.command() click.argument(name) click.option(--greeting, defaultHello, helpGreeting to use) def greet(name: str, greeting: str): Greet someone. click.echo(f{greeting}, {name}!) cli.command() click.option(--count, default1, helpNumber of times to repeat) def repeat(count: int): Repeat a message. for i in range(count): click.echo(fMessage {i 1}) def main(): Entry point for CLI. cli() if __name__ __main__: main()在 pyproject.toml 中注冊(cè)并測(cè)試[project.scripts] my-tool my_package.cli:mainpip install -e . my-tool greet World my-tool greet Alice --greetingHi my-tool repeat --count3click.group()將cli變?yōu)槊罱M子命令通過(guò)cli.command()掛載click.version_option()自動(dòng)提供--version。pip install -e .PEP 660 可編輯安裝后即可直接以my-tool命令名調(diào)用。Pattern 7基于 argparse 的子命令解析# src/my_package/cli.py import argparse import sys def main(): Main CLI entry point. parser argparse.ArgumentParser( descriptionMy awesome tool, progmy-tool ) parser.add_argument( --version, actionversion, version%(prog)s 1.0.0 ) subparsers parser.add_subparsers(destcommand, helpCommands) # Add subcommand process_parser subparsers.add_parser(process, helpProcess data) process_parser.add_argument(input_file, helpInput file path) process_parser.add_argument( --output, -o, defaultoutput.txt, helpOutput file path ) args parser.parse_args() if args.command process: process_data(args.input_file, args.output) else: parser.print_help() sys.exit(1) def process_data(input_file: str, output_file: str): Process data from input to output. print(fProcessing {input_file} - {output_file}) if __name__ __main__: main()argparse 是標(biāo)準(zhǔn)庫(kù)方案零第三方依賴(lài)。核心手法是add_subparsers(destcommand)聲明子命令actionversion提供--version未匹配命令時(shí)print_help()并sys.exit(1)。Click 適合命令樹(shù)復(fù)雜、需要豐富交互體驗(yàn)的場(chǎng)景argparse 適合追求最小依賴(lài)的純標(biāo)準(zhǔn)庫(kù)工具——選擇取決于項(xiàng)目約束。構(gòu)建與發(fā)布全流程Pattern 8本地構(gòu)建# Install build tools pip install build twine # Build distribution python -m build # This creates: # dist/ # my-package-1.0.0.tar.gz (source distribution) # my_package-1.0.0-py3-none-any.whl (wheel) # Check the distribution twine check dist/*python -m build會(huì)同時(shí)產(chǎn)出 sdist.tar.gz源碼分發(fā)包與 wheel.whl平臺(tái)無(wú)關(guān)的純 Python 輪子文件名中的py3-none-any即Python 3、無(wú) ABI、任意平臺(tái)。twine check在發(fā)布前校驗(yàn)分發(fā)包元數(shù)據(jù)README 渲染、長(zhǎng)描述格式、缺失字段等是否合規(guī)。Pattern 9發(fā)布到 PyPI# Install publishing tools pip install twine # Test on TestPyPI first twine upload --repository testpypi dist/* # Install from TestPyPI to test pip install --index-url https://test.pypi.org/simple/ my-package # If all good, publish to PyPI twine upload dist/*規(guī)范流程是先在 TestPyPI 試上傳、試安裝確認(rèn)無(wú)誤后再正式發(fā)布。推薦使用 API token 而非賬號(hào)密碼配置~/.pypirc# Create ~/.pypirc [distutils] index-servers pypi testpypi [pypi] username __token__ password pypi-...your-token... [testpypi] username __token__ password pypi-...your-test-token...Pattern 10GitHub Actions 自動(dòng)化發(fā)布# .github/workflows/publish.yml name: Publish to PyPI on: release: types: [created] jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Set up Python uses: actions/setup-pythonv4 with: python-version: 3.11 - name: Install dependencies run: | pip install build twine - name: Build package run: python -m build - name: Check package run: twine check dist/* - name: Publish to PyPI env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} run: twine upload dist/*工作流以release事件types: [created]為觸發(fā)器串起checkout → 裝構(gòu)建工具 → 構(gòu)建 → twine check → 用PYPI_API_TOKEN密鑰上傳五步。TWINE_USERNAME: __token__配合倉(cāng)庫(kù) Secrets 中的PYPI_API_TOKEN避免了在 CI 日志中泄露憑據(jù)。倉(cāng)庫(kù)實(shí)踐印證真實(shí)的 pyproject.toml 與 CLI 落地上述模式并非紙上談兵當(dāng)前倉(cāng)庫(kù)內(nèi)部就有多個(gè)可對(duì)照的真實(shí)工程plugin-evalpyproject.toml采用hatchling構(gòu)建后端與packages [src/plugin_eval]的 src 布局[project.scripts]注冊(cè)plugin-eval plugin_eval.cli:app可選依賴(lài)按llm/api/dev分組[tool.pytest.ini_options]與[tool.ruff]集中配置。其 CLI 在 cli.py 中基于 typerClick 的上層封裝實(shí)現(xiàn)score/certify/init等命令與 details.md 中用[project.scripts]注冊(cè)入口點(diǎn)的思路完全一致——這正是my-tool my_package.cli:main模式的工程級(jí)印證。yt-design-extractorpyproject.toml展示了[project.optional-dependencies]控制重依賴(lài)的實(shí)踐——easyocr分組攜帶 torch/torchvision約 2GB注釋明確提示用uv sync --extra easyocr按需安裝[tool.uv] package false聲明其為僅依賴(lài)工程腳本通過(guò)uv run yt-design-extractor.py直接執(zhí)行而非安裝為包。MakefileMakefile倉(cāng)庫(kù)約定所有 Python 工具鏈統(tǒng)一走uvlint/test目標(biāo)都以u(píng)v run --extra dev在 plugin-eval 項(xiàng)目目錄內(nèi)執(zhí)行保證 ruff/ty 版本與 CI 鎖定一致——呼應(yīng)了 Pattern 4 中工具鏈配置入 pyproject.toml的價(jià)值。延伸閱讀高級(jí)模式索引details.md末尾將更進(jìn)階的主題指向 references/advanced-patterns.md其中覆蓋Pattern 11數(shù)據(jù)文件打包[tool.setuptools.package-data]聲明data/*.json、templates/*.html等資源運(yùn)行時(shí)用importlib.resources.files(my_package).joinpath(...)讀取Python 3.9Pattern 12命名空間包多倉(cāng)庫(kù)共享company/命名空間命名空間目錄不寫(xiě)__init__.py各包用include [company.core*]限定Pattern 13C 擴(kuò)展pyproject.toml 的[tool.setuptools] ext-modules或傳統(tǒng)setup.py的ExtensionPattern 14-15語(yǔ)義化版本與 setuptools-scm 的 git 派生版本1.0.1.dev3g1234567Pattern 16-17pip install -e .可編輯安裝與隔離環(huán)境安裝驗(yàn)證Pattern 18-20README 模板、cibuildwheel 多架構(gòu) wheel、私有索引--index-url/twine upload --repository-url以及.gitignore、MANIFEST.in模板與發(fā)布前的逐項(xiàng)檢查清單測(cè)試、文檔、版本號(hào)、CHANGELOG、License、TestPyPI 先行、git tag 等。至此從全功能 pyproject.toml到動(dòng)態(tài)版本 CLI 構(gòu)建發(fā)布 自動(dòng)化 CI再到倉(cāng)庫(kù)內(nèi)真實(shí)工程的對(duì)照印證你已經(jīng)擁有了一套可完整覆蓋 Python 庫(kù)/工具打包發(fā)布全生命周期的操作指南。【免費(fèi)下載鏈接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity項(xiàng)目地址: https://gitcode.com/GitHub_Trending/agents24/agents創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考