FSSCoding
11dd2c0a2a
- Complete 6-hour launch plan with step-by-step procedures - Automated launch readiness verification script - PyPI publication guide and best practices documentation - Reusable templates for future Python packaging projects - Launch checklist for execution day Includes safety nets, emergency procedures, and discrete launch timeline. Ready for production PyPI publication.
323 lines
11 KiB
Markdown
323 lines
11 KiB
Markdown
# Python Packaging Best Practices Guide
|
|
|
|
## 🎯 **Official Standards Compliance**
|
|
|
|
This guide follows the official Python packaging flow from [packaging.python.org](https://packaging.python.org/en/latest/flow/) and incorporates industry best practices for professional software distribution.
|
|
|
|
## 📋 **The Complete Packaging Workflow**
|
|
|
|
### **1. Source Tree Organization**
|
|
```
|
|
your-project/
|
|
├── src/your_package/ # Source code
|
|
│ ├── __init__.py
|
|
│ └── cli.py # Entry point
|
|
├── tests/ # Test suite
|
|
├── scripts/ # Build scripts
|
|
├── .github/workflows/ # CI/CD
|
|
├── pyproject.toml # Package configuration
|
|
├── README.md # Documentation
|
|
├── LICENSE # License file
|
|
├── install.sh # One-line installer (Unix)
|
|
└── install.ps1 # One-line installer (Windows)
|
|
```
|
|
|
|
### **2. Configuration Standards**
|
|
|
|
#### **pyproject.toml - The Modern Standard**
|
|
```toml
|
|
[build-system]
|
|
requires = ["setuptools", "wheel"]
|
|
build-backend = "setuptools.build_meta"
|
|
|
|
[project]
|
|
name = "your-package-name"
|
|
version = "1.0.0"
|
|
description = "Clear, concise description"
|
|
authors = [{name = "Your Name", email = "email@example.com"}]
|
|
readme = "README.md"
|
|
license = {text = "MIT"}
|
|
requires-python = ">=3.8"
|
|
keywords = ["relevant", "keywords"]
|
|
classifiers = [
|
|
"Development Status :: 4 - Beta",
|
|
"Intended Audience :: Developers",
|
|
"License :: OSI Approved :: MIT License",
|
|
"Programming Language :: Python :: 3",
|
|
# ... version classifiers
|
|
]
|
|
|
|
[project.urls]
|
|
Homepage = "https://github.com/username/repo"
|
|
Repository = "https://github.com/username/repo"
|
|
Issues = "https://github.com/username/repo/issues"
|
|
|
|
[project.scripts]
|
|
your-cli = "your_package.cli:main"
|
|
```
|
|
|
|
### **3. Build Artifact Strategy**
|
|
|
|
#### **Source Distribution (sdist)**
|
|
- Contains complete source code
|
|
- Includes tests, documentation, scripts
|
|
- Built with: `python -m build --sdist`
|
|
- Required for PyPI uploads
|
|
|
|
#### **Wheel Distributions**
|
|
- Pre-built, optimized for installation
|
|
- Platform-specific when needed
|
|
- Built with: `cibuildwheel` for cross-platform
|
|
- Much faster installation than sdist
|
|
|
|
#### **Zipapp Distributions (.pyz)**
|
|
- Single executable file
|
|
- No pip/package manager needed
|
|
- Perfect for users without Python knowledge
|
|
- Built with: `zipapp` module
|
|
|
|
### **4. Cross-Platform Excellence**
|
|
|
|
#### **Operating System Matrix**
|
|
- **Ubuntu latest** (Linux representation)
|
|
- **Windows latest** (broad Windows compatibility)
|
|
- **macOS 13** (Intel Macs)
|
|
- **macOS 14** (Apple Silicon)
|
|
|
|
#### **Python Version Strategy**
|
|
- **Minimum**: 3.8 (broad compatibility)
|
|
- **Testing focus**: 3.8, 3.11, 3.12
|
|
- **Latest features**: Use 3.11+ capabilities when beneficial
|
|
|
|
#### **Architecture Coverage**
|
|
- **Linux**: x86_64 (most common)
|
|
- **Windows**: AMD64 (64-bit standard)
|
|
- **macOS**: x86_64 + ARM64 (Intel + Apple Silicon)
|
|
|
|
## 🚀 **Installation Experience Design**
|
|
|
|
### **Multi-Method Installation Strategy**
|
|
|
|
#### **1. One-Line Installers (Recommended)**
|
|
**Principle**: "Install without thinking"
|
|
```bash
|
|
# Linux/macOS
|
|
curl -fsSL https://your-domain/install.sh | bash
|
|
|
|
# Windows
|
|
iwr https://your-domain/install.ps1 -UseBasicParsing | iex
|
|
```
|
|
|
|
**Smart Fallback Chain**: uv → pipx → pip
|
|
- **uv**: Fastest modern package manager
|
|
- **pipx**: Isolated environments, prevents conflicts
|
|
- **pip**: Universal fallback, always available
|
|
|
|
#### **2. Manual Methods**
|
|
```bash
|
|
# Modern package managers
|
|
uv tool install your-package
|
|
pipx install your-package
|
|
|
|
# Traditional
|
|
pip install your-package
|
|
|
|
# Direct from source
|
|
pip install git+https://github.com/user/repo
|
|
```
|
|
|
|
#### **3. No-Python-Knowledge Option**
|
|
- Download `your-tool.pyz`
|
|
- Run with: `python your-tool.pyz`
|
|
- Works with any Python 3.8+ installation
|
|
|
|
### **Installation Experience Principles**
|
|
1. **Progressive Enhancement**: Start with simplest method
|
|
2. **Intelligent Fallbacks**: Always provide alternatives
|
|
3. **Clear Error Messages**: Guide users to solutions
|
|
4. **Path Management**: Handle PATH issues automatically
|
|
5. **Verification**: Test installation immediately
|
|
|
|
## 🔄 **CI/CD Pipeline Excellence**
|
|
|
|
### **Workflow Job Architecture**
|
|
```yaml
|
|
Jobs Workflow:
|
|
1. build-wheels → Cross-platform wheel building
|
|
2. build-zipapp → Single-file distribution
|
|
3. test-installation → Validation across environments
|
|
4. publish → PyPI upload (tags only)
|
|
5. create-release → GitHub release with assets
|
|
```
|
|
|
|
### **Quality Gates**
|
|
- **Build Verification**: All wheels must build successfully
|
|
- **Cross-Platform Testing**: Installation test on Windows/macOS/Linux
|
|
- **Functionality Testing**: CLI commands must work
|
|
- **Security Scanning**: Dependency and secret scanning
|
|
- **Release Gating**: Manual approval for production releases
|
|
|
|
### **Automation Triggers**
|
|
```yaml
|
|
Triggers:
|
|
- push.tags.v* → Full release pipeline
|
|
- push.branches.main → Build and test only
|
|
- pull_request → Quality verification
|
|
- workflow_dispatch → Manual testing
|
|
```
|
|
|
|
## 🔐 **Security Best Practices**
|
|
|
|
### **Secret Management**
|
|
- **PyPI API Token**: Stored in GitHub Secrets
|
|
- **Scope Limitation**: Project-specific tokens when possible
|
|
- **Environment Protection**: Release environment requires approval
|
|
- **Token Rotation**: Regular token updates
|
|
|
|
### **Supply Chain Security**
|
|
- **Dependency Scanning**: Automated vulnerability checks
|
|
- **Signed Releases**: GPG signing for sensitive projects
|
|
- **Audit Trails**: Complete build artifact provenance
|
|
- **Reproducible Builds**: Consistent build environments
|
|
|
|
### **Code Security**
|
|
- **No Secrets in Code**: Environment variables only
|
|
- **Input Validation**: Sanitize all user inputs
|
|
- **Dependency Pinning**: Lock file for reproducible builds
|
|
|
|
## 📊 **PyPI Publication Strategy**
|
|
|
|
### **Pre-Publication Checklist**
|
|
- [ ] **Package Name**: Available on PyPI, follows naming conventions
|
|
- [ ] **Version Strategy**: Semantic versioning (MAJOR.MINOR.PATCH)
|
|
- [ ] **Metadata Complete**: Description, keywords, classifiers
|
|
- [ ] **License Clear**: License file and pyproject.toml match
|
|
- [ ] **README Professional**: Clear installation and usage
|
|
- [ ] **API Token**: PyPI token configured in GitHub Secrets
|
|
|
|
### **Release Process**
|
|
```bash
|
|
# Development releases
|
|
git tag v1.0.0-alpha1
|
|
git tag v1.0.0-beta1
|
|
git tag v1.0.0-rc1
|
|
|
|
# Production releases
|
|
git tag v1.0.0
|
|
git push origin v1.0.0 # Triggers automated publishing
|
|
```
|
|
|
|
### **Version Management**
|
|
- **Development**: 1.0.0-dev, 1.0.0-alpha1, 1.0.0-beta1
|
|
- **Release Candidates**: 1.0.0-rc1, 1.0.0-rc2
|
|
- **Stable**: 1.0.0, 1.0.1, 1.1.0, 2.0.0
|
|
- **Hotfixes**: 1.0.1, 1.0.2
|
|
|
|
## 🎯 **User Experience Excellence**
|
|
|
|
### **Documentation Hierarchy**
|
|
1. **README Quick Start**: Get running in 30 seconds
|
|
2. **Installation Guide**: Multiple methods, troubleshooting
|
|
3. **User Manual**: Complete feature documentation
|
|
4. **API Reference**: For library use
|
|
5. **Contributing Guide**: For developers
|
|
|
|
### **Error Handling Philosophy**
|
|
- **Graceful Degradation**: Fallback when features unavailable
|
|
- **Actionable Messages**: Tell users exactly what to do
|
|
- **Context Preservation**: Show what was being attempted
|
|
- **Recovery Guidance**: Suggest next steps
|
|
|
|
### **Performance Considerations**
|
|
- **Fast Startup**: Minimize import time
|
|
- **Efficient Dependencies**: Avoid heavy packages
|
|
- **Progressive Loading**: Load features on demand
|
|
- **Resource Management**: Clean up properly
|
|
|
|
## 📈 **Maintenance and Evolution**
|
|
|
|
### **Monitoring Success**
|
|
- **PyPI Download Statistics**: Track adoption
|
|
- **GitHub Analytics**: Issue trends, popular features
|
|
- **User Feedback**: GitHub Issues, discussions
|
|
- **Platform Distribution**: OS/Python version usage
|
|
|
|
### **Version Lifecycle**
|
|
- **Feature Development**: Alpha/beta releases
|
|
- **Stability Period**: Release candidates
|
|
- **Production**: Stable releases with hotfixes
|
|
- **Deprecation**: Clear migration paths
|
|
|
|
### **Dependency Management**
|
|
- **Regular Updates**: Security patches, feature updates
|
|
- **Compatibility Testing**: Ensure new versions work
|
|
- **Breaking Change Management**: Major version bumps
|
|
- **End-of-Life Planning**: Python version sunsetting
|
|
|
|
## 🏆 **Success Metrics**
|
|
|
|
### **Technical Excellence**
|
|
- **Build Success Rate**: >99% automated builds
|
|
- **Cross-Platform Coverage**: Windows/macOS/Linux working
|
|
- **Installation Success**: All methods work reliably
|
|
- **Performance**: Fast downloads, quick startup
|
|
|
|
### **User Adoption**
|
|
- **Download Growth**: Increasing PyPI downloads
|
|
- **Platform Diversity**: Usage across different OS
|
|
- **Issue Resolution**: Fast response to problems
|
|
- **Community Engagement**: Contributors, discussions
|
|
|
|
### **Developer Experience**
|
|
- **Release Automation**: Zero-manual-step releases
|
|
- **Quality Gates**: Catches problems before release
|
|
- **Documentation Currency**: Always up-to-date
|
|
- **Contributor Onboarding**: Easy to contribute
|
|
|
|
## 🚨 **Common Pitfalls to Avoid**
|
|
|
|
### **Configuration Issues**
|
|
- ❌ **Incorrect entry points** - CLI commands don't work
|
|
- ❌ **Missing dependencies** - ImportError at runtime
|
|
- ❌ **Wrong Python versions** - Compatibility problems
|
|
- ❌ **Bad package names** - Conflicts with existing packages
|
|
|
|
### **Distribution Problems**
|
|
- ❌ **Missing wheels** - Slow pip installations
|
|
- ❌ **Platform-specific bugs** - Works on dev machine only
|
|
- ❌ **Large package size** - Unnecessary dependencies included
|
|
- ❌ **Broken PATH handling** - Commands not found after install
|
|
|
|
### **Security Vulnerabilities**
|
|
- ❌ **Secrets in code** - API keys committed to repository
|
|
- ❌ **Unsafe dependencies** - Vulnerable packages included
|
|
- ❌ **Overly broad tokens** - PyPI tokens with excessive permissions
|
|
- ❌ **No input validation** - Code injection vulnerabilities
|
|
|
|
## ✅ **Final Checklist**
|
|
|
|
### **Before First Release**
|
|
- [ ] All installation methods tested on each platform
|
|
- [ ] README includes clear installation instructions
|
|
- [ ] PyPI API token configured with proper permissions
|
|
- [ ] GitHub Actions workflow runs successfully
|
|
- [ ] CLI commands work after installation
|
|
- [ ] Error messages are helpful and actionable
|
|
|
|
### **For Each Release**
|
|
- [ ] Version number updated in pyproject.toml
|
|
- [ ] Changelog updated with changes
|
|
- [ ] All tests pass on all platforms
|
|
- [ ] Manual testing on at least one platform
|
|
- [ ] Tag pushed to trigger automated release
|
|
|
|
### **Post-Release**
|
|
- [ ] PyPI package published successfully
|
|
- [ ] GitHub release created with assets
|
|
- [ ] Installation instructions tested
|
|
- [ ] Social media announcement (if applicable)
|
|
- [ ] Documentation updated for new features
|
|
|
|
---
|
|
|
|
**This guide transforms your Python projects from development tools into professional software packages that delight users and follow industry best practices.** 🚀 |