Python Package Skeleton Template

Summary

This repository is a skeleton template for a Python application/library compliant with the latest team-development and software deployment practices within a continuous integration (CI) framework. It can be used as a source of information/study to emulate or as a direct template for your repositories. Note I can't cover all strategies available in the wild. This repository reflects the setup I like the most and covers the CI needs of my Python projects, which includes:

• A robust Python library/application file hierarchy with packages, modules, clients, and documentation:

  • detailed, yet simple, setup.py
  • retrievable README and CHANGELOG
  • documentation deployed in ReadTheDocs
  • the unusual adoption of the src directory layer (love it)
  • examples of packages and modules hierarchy
  • examples of Python command-line interfaces

• A unique testing framework for developers with tox and pytest

  • guarantees tests are reproducible for all developers
  • ensures same lint rules are always applied (local and remotely)
  • ensures all desired Python versions are covered
  • adopts hypothesis

• Fully automated continuous integration services with GitHub Actions

  • automatic testing on Linux, MacOS, and Windows
  • automatic testing simulated upon deployment with tox
  • test coverage report to Codecov
  • automated version bump with bump2version, git tagging, and Python packaging to PyPI on Pull Request merge

Motivation

To understand and implement the best practices for team-based development and automatic deployment of scientific software in Python. Also, I believe the strategy reviewed here can be applied to most general-purpose Python libraries.

This repository does not intend to be a cookiecutter-like repository. There are very well documented cookiecutters, even for scientific software, if you are looking for one of those.

When I started developing Python libraries, I decided that using a cookiecutter as a shortcut would lead me nowhere in the learning process of configuring CI services because I would miss the details of what was actually being implemented. Hence, assembling this template from scratch as a full working repository was the only best approach to achieve a minimum understanding of CI. Now, this repository serves as a reference guide for all my projects and hopefully will serve you too. I try to keep it up to date with my needs and the ever-evolving CI ecosystem.

Acknowledgments

I want to acknowledge ionel discussions about Packaging a python library. They are a pillar in my understanding and decisions on this matter, and I really recommend reading his blog post and references herein.

I configured the CI pipeline to my needs by taking bits and pieces from many places. Kudos to python-nameless and cookiecutter-pylibrary; two primary sources of information for the python-project-skeleton repository, especially in the first versions using Travis and Appveyor. When migrating to GitHub Actions, I fed on the workflows @JoaoRodrigues assembled for pdb-tools; on the tox-gh-actions package; and on structlog, which was also a repository I used as a reference to build test latest version here.

I refer to 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 documentation pages explain how to use this template for your projects and the implementation details adopted here. Use the documentation as a reference to learn the rationale behind this repository and also as a demonstration of how to deploy documentation in ReadTheDocs.

Issues and Discussions

As usual in any GitHub based project, raise an issue if you find any bug or room for improvement (certainly there are many), or open a discussion (new feature!!) if you want to discuss or talk :-)

Version

v0.8.1