Cookiecutter template for a Python package.
- GitHub repo: https://github.com/opengeos/cookiecutter-pypackage
- Documentation: https://open.gishub.org/cookiecutter-pypackage
- Free software: BSD license
- Testing setup with
unittest
andpython setup.py test
orpytest
- GitHub actions: Ready for GitHub Continuous Integration testing
- bump-my-version: Pre-configured version bumping with a single command
- Auto-release to PyPI when you push a new tag to master (optional)
- Command line interface using Click (optional)
This guide provides detailed steps on how to create a Python package, configure it for distribution, and manage its versioning and releases. First, install cookiecutter
and bump-my-version
and then follow the steps below.
pip install cookiecutter bump-my-version
Use cookiecutter
to create a package structure. cookiecutter
is a command-line utility that creates projects from templates.
cookiecutter gh:opengeos/cookiecutter-pypackage
Navigate to your project directory and initialize a Git repository:
cd your-package-name
git init
git add .
git commit -m "Initial commit"
- Go to GitHub and create a new empty repository.
- Do NOT initialize it with a README, license, or .gitignore file.
Link your local repository to the GitHub repository. If your git branch is named main
, use the following commands:
git remote add origin [your-repository-url]
git branch -M main
git push -u origin main
If your git branch is named master
, use the following commands:
git remote add origin [your-repository-url]
git branch -M master
git push -u origin master
Change the GitHub Actions settings in your repository to allow read and write operations:
- Go to your repository on GitHub.
- Click on
Settings
>Actions
>General
>Workflow permissions
. - Change the settings to allow read and write operations.
Push your local changes to GitHub:
git push
- Visit pypi.org and log in or create an account.
- Navigate to
Account Settings
>API Tokens
. - Create a new API token. Select
Entire account
as the scope. Copy the token.
Add your PyPI credentials as secrets in your GitHub repository:
- Go to your repository on GitHub.
- Click on
Settings
>Secrets
>New repository secret
. - Add
PYPI_USERNAME
as a secret. Use__token__
as the value. - Add
PYPI_PASSWORD
as a secret. Use the API token created above as the password.
Create a release on GitHub to trigger the deployment of your package:
- Go to the
Releases
section in your GitHub repository. - Click
Draft a new release
. - Follow the prompts to create the release.
- Navigate to
Settings
>Pages
. - Select the
gh-pages
branch as the source. - Click
Save
.
Use bump-my-version
for managing the version of your package:
- First, do a dry run to see what changes will be made:
bump-my-version bump [patch/minor/major] --dry-run --verbose
- If satisfied, apply the version bump:
bump-my-version bump [patch/minor/major]
After bumping the version, push the tags and changes:
git push --tags
git push
Finally, make a new release on GitHub with the updated version:
- Repeat the process described in step 9.
Remember to replace placeholders (like your-package-name
and [your-repository-url]
) with actual values relevant to your package. This guide assumes basic familiarity with Git, GitHub, and Python packaging conventions.
Creating a Python package with Cookiecutter Template