Python Release Template

A modern cookiecutter template for Python packages with automated PyPI releases via GitHub Actions.

✨ Features

• 📦 Modern Python Packaging: Uses pyproject.toml and src/ layout
• 🚀 Automated Releases: GitHub Actions workflow for PyPI/TestPyPI publishing
• 🔒 Security First: Trusted publishing with OIDC (no API tokens needed)
• 🛠️ Rich Development Environment: 40+ Makefile commands for common tasks
• ✅ Pre-configured Tools: Black, Ruff, MyPy, pytest, coverage
• 📈 Version Management: Semantic versioning with automated bumping
• 📝 Documentation Ready: README, CHANGELOG, and release guides included
• 🎯 GitHub Integration: Issue and PR templates

🚀 Quick Start

Install cookiecutter

Using pipx (recommended):

pipx install cookiecutter

Using pip:

pip install cookiecutter

Generate Your Project

cookiecutter gh:hesreallyhim/python-release-template

You'll be prompted for:

• project_name: Your project's display name (e.g., "My Awesome Package")
• project_slug: PyPI package name (auto-generated, e.g., "my-awesome-package")
• package_name: Python import name (auto-generated, e.g., "my_awesome_package")
• author_name: Your name
• author_email: Your email
• github_username: Your GitHub username
• python_version: Minimum Python version (default: 3.11)
• license: Choose from MIT, Apache-2.0, GPL-3.0, or BSD-3-Clause

Start Developing

cd your-project-name
make venv        # Create virtual environment
make install-dev # Install development dependencies
make test        # Run tests
make help        # See all available commands

📦 What's Included

Project Structure

your-project/
├── src/
│   └── your_package/
│       ├── __init__.py
│       └── __version__.py
├── tests/
│   └── test_version.py
├── docs/
│   ├── RELEASE_GUIDE.md
│   └── TROUBLESHOOTING.md
├── .github/
│   ├── workflows/
│   │   └── publish.yml
│   └── ISSUE_TEMPLATE/
├── pyproject.toml
├── Makefile
├── README.md
├── CHANGELOG.md
└── LICENSE

Key Features

• Makefile with 40+ commands: Development, testing, building, releasing
• GitHub Actions: Automated testing and publishing on release
• Trusted Publishing: Secure PyPI uploads without storing tokens
• TestPyPI Support: Test your releases before going live
• Version Management: Single source of truth in __version__.py
• Development Tools: Pre-configured linting, formatting, and type checking

🔧 Customization

After generating your project, you can:

1. Add dependencies: Edit pyproject.toml
2. Configure tools: Adjust settings in pyproject.toml
3. Extend Makefile: Add custom targets for your workflow
4. Update GitHub Actions: Modify .github/workflows/publish.yml

📚 Documentation

For detailed information about:

• Using the template: See the generated project's README
• Releasing packages: Check docs/RELEASE_GUIDE.md in your generated project
• Troubleshooting: See docs/TROUBLESHOOTING.md in your generated project
• Template development: Visit python-release-template-manager

🤝 Contributing

To contribute to this template, please visit the development repository: python-release-template-manager

📄 License

This template is released under the MIT License. Generated projects can use any license.

🙏 Acknowledgments

Built with Cookiecutter, inspired by modern Python packaging best practices.