Python Packaging Guide

This guide is intended to explain modern Python packaging, it covers most of the core components of a modern package, and explains these components. It is broken up into the following sections:

• Minimal package layout
  • LICENSE
  • README.rst
  • my_package/__init__.py
  • setup.cfg
  • setup.py
  • pyproject.toml
  • MANIFEST.in
  • Trying out your package
• Documenting your Package
  • Docstrings
  • Narrative Documentation
  • Including docstrings in the narrative documentation
  • Declaring dependencies for documentation
  • Setting up ReadTheDocs
  • Add plots to your documentation
• Testing your package
  • Where to keep tests
  • Running tests
  • Defining default pytest options
  • Running doctests
  • Declaring dependencies for tests
• Running Commands with Tox
  • Getting Started with Tox: Running tests
  • Building Documentation with tox
  • Testing Packages with Compiled Extensions
• Compiled C/Cython extensions
  • Defining extensions in setup.py
  • Packages with many extensions
• Releasing Your Package
  • Incrementing Version Numbers
  • Building Source Distributions
  • Publishing to PyPI
  • Releasing from Branches
• Command-line scripts
• Including data in your package
• Continuous Integration

Using the Template

With this guide is a cookiecutter template which allows you to get started quickly with a package as described in this guide. To use this, we recommend you use the pieceofcake wrapper which gives you more details on the questions.

To get started run:

$ pip install cookiecutter
$ cookiecutter gh:OpenAstronomy/packaging-guide ./output_directory