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 get started run:

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

OpenAstronomy Python Packaging Guide

A generic Python packaging guide and template.

Navigation

  • Minimal package layout
  • Documenting your Package
  • Testing your package
  • Running Commands with Tox
  • Compiled C/Cython extensions
  • Releasing Your Package
  • Command-line scripts
  • Including data in your package
  • Continuous Integration

Related Topics

  • Documentation overview
    • Next: Minimal package layout

Quick search

©2019, OpenAstronomy Developers. | Powered by Sphinx 1.8.6 & Alabaster 0.7.13 | Page source