Python Package Template

This is a template for a python package.

Feel free to use it as a launching point for your next project!

How to use it

1. Create a new repo

This template uses copier to create a new repo from the template.

pip install "copier"

Then run copier, passing in the template url and the desired output directory (usually the name of your new package):

copier copy gh:pydev-guide/pyrepo-copier your-package-name

2. Run git init and install pre-commit

After creating the repo, you'll want to initialize a git repo.

This is important: you won't be able to run pip install -e . without running git init

cd <your-package-name>
git init
git add .
git commit -m 'build: Initial Commit'

If you selected pre-commit (or used the "full-featured" default), install pre-commit, run pre-commit autoupdate, and then install the git commit hook with pre-commit install:

pip install pre-commit
pre-commit autoupdate
pre-commit install
git add .
git commit -m 'chore: update pre-commit'

3. Install Locally and Run Tests

To run tests locally, you'll need to install the package in editable mode.

I like to first create a new environment dedicated to my package:

mamba create -n <your-package-name> python
mamba activate <your-package-name>

Then install the package in editable mode:

pip install -e .[test]

if you run into problems here, make sure that you ran git init above!

Finally, run the tests:

pytest

4. Upload to GitHub

If you have the GitHub CLI installed, and would like to create a GitHub repository for your new package:

gh repo create --source=. --public --remote=origin --push

alternatively, you can follow github's guide for adding a local repository to github

Next Steps

• If you'd like: setup the pre-commit.ci service to run all pre-commit checks on every PR (in case contributors aren't running it locally). Note that you can always run checks locally with pre-commit run -a
• Follow links below for more info on the included tools (pay particular attention to hatch and ruff).
• See how to Deploy to PyPI below.

Stuff included

• PEP 517 build system with hatch backend
  • build with python -m build, not python setup.py!
• PEP 621 metadata in pyproject.toml
  • all additional configurables are also in pyproject.toml, with links to documentation
• uses src layout (How come?)
• git tag-based versioning with hatch-vcs
• autodeploy to PyPI on tagged commit (set TWINE_API_KEY env var on github). See Deploying to PyPI below.
• Testing with pytest
• CI & testing with github actions
• GitHub action cron-job running tests against dependency pre-releases (using --pre to install dependencies).
• pre-commit with
  • ruff - amazing linter and formatter. Takes the place of flake8, autoflake, isort, pyupgrade, black, and more...
  • mypy - static type hint checker (defaults to strict mode)
  • conventional-pre-commit - enforce good commit messages (this is commented out by default). See Conventional Commits below.
• check-manifest test to check completeness of files in your release.
• I use and include github-changelog-generator to automate changelog generation... but there are probably better options now (this is a hot topic).

Deploying to PyPI

When you're ready to deploy a version of your package, tag the commit with a version number and push it to github. This will trigger a github action that will build and deploy to PyPI. (see the "deploy" step in workflows/ci.yml). The version number is determined by the git tag using hatch-vcs... which wraps setuptools-scm

git tag -a v0.1.0 -m v0.1.0
git push --follow-tags

# or, specify a remote:
# git push upstream --follow-tags

To auto-deploy to PyPI, you will need to create a trusted publisher on PyPi:

• Connect to PyPi (you need an account)
• Go to your projects and click on "Publishing" (last item on the left menu)
• In the section "Add a new pending publisher"
• Enter the project name (as in your pyproject.toml), the organization or username of the repository owner (on Github) and the repository name
• Next, enter ci.yml as "Workflow name" and leave the environment blank
• Add the publisher and you are good to go!

Update your repo

This template may change over time, bringing in new improvements, fixes, and updates. To update an existing project that was created from this template using copier, just enter the root of the project, make sure git status shows the working directory is clean, and run: copier update. See copier docs for details.