my_package/
├── pyproject.toml          # 构建配置（现代标准）
├── setup.py                # 兼容旧工具
├── setup.cfg               # 静态配置
├── README.md               # 项目说明
├── LICENSE                 # 许可证
├── src/
│   └── my_package/         # 源代码
│       ├── __init__.py
│       ├── module1.py
│       └── module2.py
├── tests/
│   ├── __init__.py
│   └── test_module1.py
├── docs/
│   └── index.md
├── examples/
│   └── basic_usage.py
├── .gitignore
└── requirements.txt

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "my-package"
version = "0.1.0"
description = "一个Python工具库"
readme = "README.md"
license = {text = "MIT"}
authors = [
{name = "Your Name", email = "your.email@example.com"}
]
maintainers = [
{name = "Your Name", email = "your.email@example.com"}
]
keywords = ["python", "tool", "utility"]
classifiers = [
"Development Status :: 3 - Alpha",
"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",
]
requires-python = ">=3.8"
dependencies = [
"requests>=2.28.0",
"click>=8.0.0",
]
[project.optional-dependencies]
dev = [
"pytest>=7.0.0",
"pytest-cov>=4.0.0",
"black>=23.0.0",
"flake8>=6.0.0",
]
docs = [
"sphinx>=6.0.0",
"sphinx-rtd-theme>=1.0.0",
]
[project.scripts]
my-cli = "my_package.cli:main"
[project.urls]
Homepage = "https://github.com/yourname/my-package"
Documentation = "https://my-package.readthedocs.io"
Repository = "https://github.com/yourname/my-package"
Changelog = "https://github.com/yourname/my-package/blob/main/CHANGELOG.md"
[tool.setuptools.packages.find]
where = ["src"]
[tool.black]
line-length = 88
target-version = ['py38', 'py39', 'py310', 'py311']
[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v --cov=my_package --cov-report=term-missing"

# 安装构建工具
pip install build
或者使用pipx（推荐）
pipx install build

# 构建source dist和wheel
python -m build
只构建wheel
python -m build --wheel
只构建source dist
python -m build --sdist
输出目录
dist/
  my_package-0.1.0-py3-none-any.whl
  my_package-0.1.0.tar.gz

# 安装twine用于验证和上传
pip install twine
验证包
twine check dist/*
本地测试安装
pip install dist/*.whl
测试CLI命令（如果定义了）
my-cli --help

1. 访问 https://pypi.org

2.注册账户

3.创建API token

4.配置凭证

# 方式1：使用~/.pypirc
[distutils]
index-servers =
pypi
testpypi
[pypi]
username = __token__
password = pypi-xxxxx
[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-xxxxx
方式2：使用环境变量
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-xxxxx

# 上传到TestPyPI
twine upload --repository testpypi dist/*
从TestPyPI安装测试
pip install --index-url https://test.pypi.org/simple/ my-package

# 上传到PyPI
twine upload dist/*
验证发布
pip install my-package

MAJOR.MINOR.PATCH
│    │    │
│    │    └── 向后兼容的小改动
│    └────── 向后兼容的功能新增
└────────── 不兼容的API改动

# 1. 更新版本号
pyproject.toml 中修改 version = "0.2.0"
2. 更新CHANGELOG
CHANGELOG.md 中添加新版本说明
3. 提交并打标签
git add pyproject.toml CHANGELOG.md
git commit -m "Release v0.2.0"
git tag -a v0.2.0 -m "Release v0.2.0"
4. 推送
git push origin main --tags
5. 构建并发布
python -m build
twine upload dist/*

# Changelog
[0.2.0] - 2026-05-26
Added

●新增 process_batch() 方法

●新增 CLI 命令 my-cli run


Changed

●优化 process() 性能，提升50%


Fixed

●修复内存泄漏问题

●修复 Unicode 编码错误


[0.1.0] - 2026-05-01
Added

●初始版本发布

●支持基本数据处理功能

# .github/workflows/release.yml
name: Release
on:
push:
tags:
- 'v*'
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install build tools
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_TOKEN }}
run: twine upload dist/*
- name: Create GitHub Release
uses: softprops/action-gh-release@v1
with:
files: dist/*
generate_release_notes: true

# versioneer 或 setuptools_scm
使用git标签自动管理版本
setup.cfg
[versioneer]
VCS = git
style = pep440
versionfile_source = src/my_package/_version.py
versionfile_build = my_package/_version.py
tag_prefix = v
parentdir_prefix = my-package-

# 安装
pip install sphinx sphinx-rtd-theme
初始化
sphinx-quickstart docs
配置 conf.py
project = 'my-package'
html_theme = 'sphinx_rtd_theme'
构建文档
cd docs
make html
部署到ReadTheDocs
1. 在readthedocs.org导入仓库
2. 自动触发构建

# 安装
pip install mkdocs mkdocs-material
初始化
mkdocs new my-package-docs
cd my-package-docs
配置 mkdocs.yml
site_name: my-package
theme:
name: material
构建
mkdocs build
预览
mkdocs serve
部署到GitHub Pages
mkdocs gh-deploy

# ✅ 好的命名

●requests

●flask

●django

●numpy

●pandas


❌ 不好的命名

●My_Package          # 包含大写

●my-package-utils    # 太通用

●package             # 太短

●mypackage_v2        # 包含版本号

# 锁定依赖版本（生产环境）
dependencies = [
"requests==2.31.0",
"click>=8.1.0,<9.0.0",
]
使用依赖标记
dependencies = [
"requests[security]>=2.28.0",
]

📚 推荐阅读

KEYWORDS

IL, Python, python, 变量, 自动化

💡 如果你觉得这篇文章有帮助，请点个在看，分享给更多需要的人！

📝 关注我，获取更多实用干货～

🤝 有问题欢迎评论区留言交流！