My Package

Brief description of your package.

Installation

pip install my-package

Quick Start

from my_package import something

result = something.do_stuff()

Features

• Feature 1
• Feature 2
• Feature 3

Development

git clone <repository-url>
cd my-package
pip install -e ".[dev]"
pytest

License

MIT

README 同时作为 PyPI 主页与 `readme = "README.md"` 的渲染源，务必保证其 Markdown 合法（可用 `twine check` 验证）。

### 模式 19：多架构 Wheels

```yaml
# .github/workflows/wheels.yml
name: Build wheels

on: [push, pull_request]

jobs:
  build_wheels:
    name: Build wheels on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]

    steps:
      - uses: actions/checkout@v3

      - name: Build wheels
        uses: pypa/cibuildwheel@v2.16.2

      - uses: actions/upload-artifact@v3
        with:
          path: ./wheelhouse/*.whl

cibuildwheel 在多个操作系统上交叉构建平台相关 wheel，解决 C 扩展无法通用分发的问题。

模式 20：私有包索引

# Install from private index
pip install my-package --index-url https://private.pypi.org/simple/

# Or add to pip.conf
[global]
index-url = https://private.pypi.org/simple/
extra-index-url = https://pypi.org/simple/

# Upload to private index
twine upload --repository-url https://private.pypi.org/ dist/*

extra-index-url 可同时回退到公共 PyPI，适合企业内部包与公共依赖混用的场景。

文件模板

Python 包的 .gitignore

# Build artifacts
build/
dist/
*.egg-info/
*.egg
.eggs/

# Python
__pycache__/
*.py[cod]
*$py.class
*.so

# Virtual environments
venv/
env/
ENV/

# IDE
.vscode/
.idea/
*.swp

# Testing
.pytest_cache/
.coverage
htmlcov/

# Distribution
*.whl
*.tar.gz

MANIFEST.in

# MANIFEST.in
include README.md
include LICENSE
include pyproject.toml

recursive-include src/my_package/data *.json
recursive-include src/my_package/templates *.html
recursive-exclude * __pycache__
recursive-exclude * *.py[co]

MANIFEST.in 控制 sdist 中包含哪些非 Python 文件，确保数据文件与许可证随源码包一起分发。

仓库内的真实打包实践

本文档的技能并非纸上谈兵——agents24 仓库自身就是这些模式的活样例：

1. plugin-eval 包的 pyproject.toml（plugins/plugin-eval/pyproject.toml）同时使用了本技能的多项配置：

[project]
name = "plugin-eval"
version = "0.1.0"
description = "Three-layer quality evaluation framework for Claude Code plugins"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "pydantic>=2.13.4",
    "typer>=0.27.1",
    "rich>=15.0.0",
    "pyyaml>=6.0",
]

[project.optional-dependencies]
llm = [
    "claude-agent-sdk>=0.2.138",
]
api = [
    "anthropic>=0.122.0",
]
dev = [
    "pytest>=9.1.1",
    "pytest-asyncio>=1.4.0",
    "pytest-cov>=6.0",
    "ruff>=0.16.3",
    "ty>=0.0.71",
]

[project.scripts]
plugin-eval = "plugin_eval.cli:app"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/plugin_eval"]

[tool.ruff]
target-version = "py312"
line-length = 100

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"