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

Documentation

Full documentation: https://my-package.readthedocs.io

Development

git clone https://github.com/username/my-package.git
cd my-package
pip install -e ".[dev]"
pytest

License

MIT

## 七、常见进阶分发模式（Pattern 19 & 20）

### 多架构 wheels（cibuildwheel）

含 C 扩展的包需要在每个目标平台分别编译。用 `cibuildwheel` 配合 GitHub Actions 矩阵即可一键产出 Windows/macOS/Linux 的 wheel：

```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
```

对于纯 Python 包（如 [plugin-eval](https://gitcode.com/GitHub_Trending/agents24/agents/blob/a30778f8c4e6b0a87567941b7cca4f534bf642b6/plugins/plugin-eval/pyproject.toml?utm_source=gitcode_repo_files) 采用 hatchling 构建、只打包 `src/plugin_eval`），产物是通用的 `py3-none-any` wheel，单一平台构建即可跨平台安装，无需矩阵编译。

### 私有包索引（Private Package Index）

企业内部发布可走私有索引（如 JFrog Artifactory、AWS CodeArtifact 等）：

```bash
# 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 拉取依赖的能力。

## 八、文件模板：.gitignore 与 MANIFEST.in

### Python 包专用 .gitignore

```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
```

说明：`*.so` 用于忽略本地编译出的扩展二进制；`dist/` 与 `*.whl`、`*.tar.gz` 确保构建产物不进版本库（发布时通过 CI 或本地 `python -m build` 重新生成）。

### MANIFEST.in

对于 sdist（源码发行包），`pyproject.toml` 中的 `package-data` 只管 wheel；sdist 中要额外携带的文件（README、LICENSE、数据文件）需用 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]
```

- `include` 指定仓库根目录下的单文件；
- `recursive-include <dir> <pattern>` 递归收集某目录下匹配的文件；
- `recursive-exclude` 用于剔除缓存与字节码，防止污染 sdist。

## 九、发布前的完整检查清单

发布流程是「构建 → 校验 → 试发布 → 正式发布」的串联，每一步都有对应的检查项：

- [ ] Code is tested (pytest passing)
- [ ] Documentation is complete (README, docstrings)
- [ ] Version number updated
- [ ] CHANGELOG.md updated
- [ ] License file included
- [ ] pyproject.toml is complete
- [ ] Package builds without errors
- [ ] Installation tested in clean environment
- [ ] CLI tools work (if applicable)
- [ ] PyPI metadata is correct (classifiers, keywords)
- [ ] GitHub repository linked
- [ ] Tested on TestPyPI first
- [ ] Git tag created for release

结合 [details.md](https://gitcode.com/GitHub_Trending/agents24/agents/blob/a30778f8c4e6b0a87567941b7cca4f534bf642b6/plugins/python-development/skills/python-packaging/references/details.md?utm_source=gitcode_repo_files) 的 Pattern 8–10，完整发布链路是：

```bash
# 1. 安装构建与上传工具
pip install build twine

# 2. 本地构建：生成 sdist 与 wheel
python -m build
# dist/
#   my-package-1.0.0.tar.gz (source distribution)
#   my_package-1.0.0-py3-none-any.whl (wheel)

# 3. 校验包元数据与 README 渲染
twine check dist/*

# 4. 先发 TestPyPI 验证
twine upload --repository testpypi dist/*
pip install --index-url https://test.pypi.org/simple/ my-package

# 5. 一切正常后发布到正式 PyPI
twine upload dist/*