Python Package Skeleton Template

Summary

This is a project skeleton template for a Python project/library. This repository implements and explains the latest practices in team software development and deployment within a continuous integration framework. Note that is impossible for me to cover all strategies available in the wild. This repository covers the needs of my Python projects, which include:

• a robust Python library/application file hierarchy with packages, modules, clients

  • detailed, yet simple, setup.py

  • the special use of the src directory

  • examples of Python command-line interfaces

• unique testing framework for developers with tox and pytest

  • assures tests are reproducible across developers platforms

  • assures same lint rules are always applied

  • assures all desired Python versions are covered

• continuous integration with GitHub Actions

  • automatic testing on Linux, MacOS, and Windows

  • automatic testing upon deployment with tox

  • test coverage report to Codecov

  • automatic version bump with bump2version

  • automatic git tagging and Python packaging to PyPI

Motivation

To understand and implement in the best practices in software development and deployment for scientific software. Actually, I believe the strategy reviewed here can be applied to most Python library projects.

This repository does not intent to be a cookiecutter-like repository. Though there are many and very well documented cookiecutter templates out there, even for scientific software, when I initiated my adventure in developing Python libraries I decided that using a cookiecutter would lead me to nowhere because I would miss what was actually being automatized. Hence, assembling this template repository from scratch was the only and best approach to achieve a minimum understanding of the best practices and protocols on the matter. Now, this repository serves as a reference guide for all my projects and I try to keep it up to date to my needs and changes in the CI ecosystem.

Acknowledgments

The Python library organization itself was strongly influenced by ionel discussions in his blog post about Packaging a python library. I really recommend reading through that post and the related posts in his blog.

I setup the CI pipeline with bits from many places. Kudos to python-nameless and cookiecutter-pylibrary two repositories that served as main source of information for the python-project-skeleton repository, specially in the first versions with Travis and Appveyor.

When migrating to GitHub Actions, I want to thank @JoaoRodrigues for the workflows in pdb-tools, ymyzk for the tox-gh-actions package, and structlog, which was also a repository I used as a reference to build test latest version here.

I reference other important sources of information as comments in the specific files. Thanks everyone for keeping discussions out there open.

How to use this repository

The repository simulates the implementation of a sampleproject. Here, sampleproject is the Python name of your project, that which will be import sampleproject. So everywhere you find sampleproject just replace with the name of your project.

In setup.py the project has the name jmct-sampleproject because sampleprojet was already in use in test.pypi.org, as expected. Substitute that by the name of you package. Normally, it as the same name as sampleproject.

You will find in the project’s documentation all references that motivated the current configuration as well as detailed explanation on the different configuration files.

I intent to keep this repository up to date to my knowledge and needs. Your feedback and suggestions are highly appreciated, please raise an issue and share your thoughts.

Version

v0.3.1