Python
从零到上线：Python 开源项目的规范化开发与发布指南
提供了 Python 开源项目从零到上线的完整指南，涵盖四个核心阶段：创建阶段搭建虚拟环境、Git 配置及依赖管理；开发阶段规范分支模型、CI/CD 流程及 PR 提交标准；发布阶段实施语义化版本控制与 PyPI 上传；维护阶段建立 Issue 模板、监控依赖更新及搭建文档站。内容旨在帮助开发者建立标准化的项目工程体系，提升协作效率与代码质量。
提供了 Python 开源项目从零到上线的完整指南，涵盖四个核心阶段：创建阶段搭建虚拟环境、Git 配置及依赖管理；开发阶段规范分支模型、CI/CD 流程及 PR 提交标准；发布阶段实施语义化版本控制与 PyPI 上传；维护阶段建立 Issue 模板、监控依赖更新及搭建文档站。内容旨在帮助开发者建立标准化的项目工程体系，提升协作效率与代码质量。
pyenv 管理 Python 版本与虚拟环境mkdir my-project
cd my-project
# 创建虚拟环境并激活
pyenv virtualenv 3.11.0 my-project
pyenv local my-project
# 验证环境
python --version
which python
💡 为什么用 pyenv 而不是 venv？ pyenv 支持多版本切换，适合同时维护多个项目；pyenv local 会生成 .python-version 文件，进入目录时自动激活对应环境。
api_key 之类的敏感信息git init
cat > .gitignore <<EOF
# Python
__pycache__/
*.py[cod]
*.egg-info/
dist/
build/
*.egg
# 环境与密钥
.env
.venv/
*.pem
*.key
# IDE
.vscode/
.idea/
*.iml
# 系统文件
.DS_Store
Thumbs.db
EOF
💡 也可以使用 gitignore.io 按技术栈自动生成。
cat > .env <<EOF
# 数据库配置
DATABASE_URL=******
# API Key
LLM_API_KEY=******
EOF
echo ".env" >> .gitignore
.env.example 作为模版文件提交到你的 Github 仓库cp .env .env.example
# My Project
> 一句话描述你的项目
## ✨ 特性
- 特性一
- 特性二
## 🚀 快速开始
pip install my-project
## 📖 使用示例
...
## 📄 许可证
MIT License
requirements.txt 适合轻量级场景pip freeze > requirements.txt
requirements.txt（生产）
fastapi>=0.100.0
pydantic>=2.0.0
requirements-dev.txt（开发）
pytest>=7.0.0
black>=23.0.0
ruff>=0.1.0
Python 项目推荐使用 pyproject.toml 统一管理构建与工具配置TOML 配置文件应该包含如下：[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.backends.legacy:build"
[project]
name = "my-project"
version = "0.1.0"
description = "项目描述"
readme = "README.md"
requires-python = ">=3.10"
license = { text = "MIT" }
authors = [{ name = "Your Name", email = "[email protected]" }]
dependencies = [
"fastapi>=0.100.0",
]
[project.urls]
Homepage = "https://github.com/yourname/my-project"
[tool.ruff]
line-length = 88
[tool.pytest.ini_options]
testpaths = ["tests"]
Git Flow、Github Flowfeature/xxx -> develop -> main### 关联远程仓库 (你的 github 项目仓库)
git remote add origin https://github.com/yourname/my-project.git
### 指定为主分支
git branch -M main
### 推送分支
git push -u origin main
### 创建 develop 分支
git checkout -b develop
git push -u origin develop
### 开发新功能，切出其他分支
git checkout -b feature/add-login develop
### 开发完成后
git push origin feature/add-login
Github 上发起 PR，也称提 PR在 Github 的 Settings → Branches → Branch protection rules 对 main 分支设置
CI 主要为自动化测试和构建，开发者每次提交代码都会自动触发：单元测试、集成测试、代码风格检查、打包构建等CD 主要为自动化部署到类生产环境，运行更深层次的测试：性能测试、安全扫描等PR 合并前 CI 必须通过，防止问题代码进入主干PR 包括每次 commit 的标题建议遵循 Conventional Commits 格式：feat: 添加用户登录功能
fix: 修复 token 过期未刷新问题
docs: 更新 API 文档
refactor: 重构数据库连接池逻辑
MAJOR.MINOR.PATCH| 类型 | 说明 | 示例 |
|---|---|---|
| PATCH | Bug 修复，向后兼容 | 0.1.0 → 0.1.1 |
| MINOR | 新增功能，向后兼容 | 0.1.1 → 0.2.0 |
| MAJOR | 破坏性变更 | 0.2.0 → 1.0.0 |
# 1. 确保 main 分支代码最新
git checkout main
git pull origin main
# 2. 打 Tag
git tag v0.1.1
git push origin v0.1.1
# 3. 构建分发包
rm -rf dist/ build/
python -m build # 会生成 dist/my_project-0.1.1.tar.gz 和 .whl 文件
# 4. 上传到 PyPI
twine upload dist/* # 首次需要配置 API Token(需 two factors 验证)
CHANGELOG.md，记录版本变更：## [v0.1.1] - 2025-02-25
### Fixed
- 修复并发请求下的竞态条件问题
## [v0.1.0] - 2025-01-10
### Added
- 初始版本发布
- 支持基本的 CRUD 操作
Releases 界面直接编辑Issue 模版：在 .github/ISSUE_TEMPLATE/ 下配置 Bug Report 和 Feature Request 模版、规范用户反馈。pip list --outdated 或接入 Dependabot 自动检测依赖安全漏洞。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online