Python code packaging for scientific software

By Jo Bovy

(last changed February 04, 2025, rev. b6901f7; last built July 04, 2025)

This is a brief set of notes with an overview of the steps involved in developing, publishing, and maintaining a scientific software package. The notes focuses on current best practices and the different tools available to build, release, and maintain a scientific software package.

A PDF version of these notes is available here.

Contents:

• 1. Introduction: What makes a good scientific software package?
  • 1.1. “Why should I (want to) release my code?”
  • 1.2. The dos and don’ts of software package development
• 2. The basic structure of a Python package
  • 2.1. Naming your package
  • 2.2. Package layout
  • 2.3. The setup.py file
  • 2.4. Installing your code
  • 2.5. Code licenses
• 3. git and GitHub: version control and social open-source development
  • 3.1. Version control
  • 3.2. Basic git use
  • 3.3. Branches
  • 3.4. Some useful advanced git features
  • 3.5. Using GitHub to build a community for your code
• 4. Documenting your code and hosting the documentation online
  • 4.1. Basics of good documentation
  • 4.2. Python docstrings
  • 4.3. Using sphinx to write and generate documentation for your package
  • 4.4. A brief tour of reStructuredText
  • 4.5. Including docstrings into the sphinx documentation
  • 4.6. Including jupyter notebooks as part of your documentation
  • 4.7. Automatically building and hosting your documentation on readthedocs.io
• 5. Testing your code
  • 5.1. Basics of good testing
  • 5.2. Writing simple tests
  • 5.3. Running a test suite with pytest
  • 5.4. Test coverage
• 6. Automatically building and testing your code: continuous integration
  • 6.1. Why continuous integration?
  • 6.2. Continuous integration with Travis CI
  • 6.3. Continuous integration for Windows: AppVeyor
  • 6.4. GitHub Actions, the new kid on the block
  • 6.5. Analyzing test coverage online using Codecov
  • 6.6. Status badges for your package
• 7. Releasing your package
  • 7.1. Versioning your code
  • 7.2. Preparing for your package’s release
  • 7.3. Uploading your package to the Python Package Index (PyPI)
  • 7.4. Building and adding binary distributions (“wheels”) to your PyPI release
  • 7.5. Starting the development of your next version

All of the code snippets and examples in these notes are being shared under a CC0 1.0 Public Domain license, so you can re-use and re-mix them in your own work. Otherwise, the text is shared under a CC BY-NC-ND 4.0 International Creative Commons License, meaning that you may distribute the work in full only, you are not allowed to modify it in any way, and you may not use it for commercial means or to gain monetary compensation (note that this summary is no substitute for the full license terms).