Scientific Python Library Development Guide

This guide is maintained by the scientific Python community for the benefit of fellow scientists and research software engineers.

Start at the basics. Do you have a pile of scientific Python scripts or Jupyter notebooks that are becoming unwieldy? Are changes to some parts of your code accidentally breaking other parts of your code? Do you want to more maintainable, reusable, and shareable form? Start at the tutorial.

Learn recommended tools and best practices. Topical guides provide task-based instruction on topics that scientists and research software engineers may encounter as their projects evolve and grow. This covers modern packaging (simple or compiled), style checking, testing, documentation, static typing, CI, and much more!

New project template

This guide comes with a copier/cookiecutter/cruft template for making new repos, scientific-python/cookie. Eleven build backends including compiled backends, generation tested in Nox, and kept in-sync with the guide.

Checking an existing project

We provide sp-repo-review, a set of repo-review checks for comparing your repository with the guidelines, runnable right in the guide via WebAssembly! All checks point to a linked badge in the guide.

Learn to write better research code. A high-level document on principles provides advice based on the community’s collective experience building code that is easier for researchers to use successfully and easier to maintain over time.

Use our solutions for common tasks. A growing collection of patterns provides tested approaches for tasks and can be tricky to get exactly right, such as including data files with Python packages.

This guide does not cover the basics of Python itself or the scientific Python libraries; it focuses on making or maintaining a package. We recommend the Scientific Python Lectures if you want info.

This guide also does not cover version control, but it is essential to have a basic facility with git to use these tools successfully. We recommend the Software Carpentry lesson on Git.

History

This guide (along with cookie & repo-review) started in Scikit-HEP in 2020. It was merged with the NSLS-II guidelines and moved to Scientific Python at the 2023 Scientific Python Developer Summit, along with many updates. Improved support for compiled components supported in part by NSF cooperative agreement OAC-2209877.