Skip to main content

Best practices for Python projects

Project description


PyPi Version PyPI pyversions GitHub stars PyPi downloads

gh-actions CircleCI travis codecov LGTM Code style: black

A Python project template that highlights some best practices in Python packaging. Can be used as a GitHub template for your new Python project.

Best practices

  • The name of the Git repository should be the PyPi name of the package and should be what you type as import mypackagename. That means no hyphens in package names!

  • Your package should be a one-trick pony. Nobody wants to install a huge toolbox if all they need is the image converter in it.

  • Choose a license for your code and provide a LICENSE[.txt] in the root level of your package as well as a statement in your main README. can help you make a decision.

  • Use linting and formatting, include those in your integration tests.

    • black is a formatter that I like because you cannot configure it -- black is black.
    • Good linters are flake8 and pylint.
    • isort sorts your imports.
    • pre-commit has gained some popularity. It runs your linters and formatters on every commit. Not more "lint fix" commits.
  • Once you have tests in order, make sure they are executed with every git push. Popular CI services that run your tests are GitHub Actions, Travis CI, and CircleCI. This repository contains the config files for each of them.

  • Make sure that nobody can push to main. On GitHub, go to Settings -> Branches -> Add rule and select Require status checks to pass before merging and Include administrators. Development happens in pull requests, this makes sure that nobody -- including yourself -- ever accidentally pushes something broken to main.

  • Use a tool for measuring test coverage. codecov is one, and your CI provider submits the data to it.

  • If you have CI set up, want to show test coverage, or advertise the availability on PyPi, do so using a badge at the top of your README. Check out for what's available.

  • Include contributing guidelines and a code of conduct (edit to add appropriate enforcement contacts or use a template) to help foster a community.

What you can do with this template

First run

find . -type f -print0 -name "*.py" -o -name "*.yml" | xargs -0 sed -i 's/pyfoobar/your-project-name/g'

and rename the folder src/pyfoobar to customize the name.

There is a simple justfile that can help you with certain tasks:

  • Run just format to apply formatting.

  • Run just lint to check formatting and style.

  • Run just publish to

    • tag your project on git (just tag)
    • upload your package to PyPi (just upload)

    After publishing, people can install your package with

    pip install pyfoobar


To run the pyfoobar unit tests, check out this repository and do



pyfoobar is published under the MIT license.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyfoobar-0.0.6.tar.gz (5.3 kB view hashes)

Uploaded source

Built Distribution

pyfoobar-0.0.6-py3-none-any.whl (5.8 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page