pyOpenSci Python Package Guide

We support the Python tools that scientists need to create open science workflows.

About this guide

This guide will help you:

1. Learn how to create a Python package from start to finish

2. Understand the broader Python packaging tool ecosystem

3. Navigate and make decisions around tool options

4. Understand all of the pieces of creating and maintaining a Python package

You will also find best practice recommendations and curated lists of community resources surrounding packaging and package documentation.

new Tutorial Series: Create a Python Package

The first round of our community-developed, how to create a Python package tutorial series for scientists is complete! Join our community review process or watch development of future tutorials in our Github repo here.

✿ Create a Package Tutorials ✿

• What is a Python package?

• Make your code installable

• Publish your package to (test) PyPi

• Publish your package to conda-forge

✿ Package Metadata Tutorials ✿

• How to add a README file

• How to add metadata to a pyproject.toml file for publication to PyPI.

✿ Packaging Tool Tutorials ✿

• Introduction to Hatch

Python Packaging for Scientists

Learn about Python packaging best practices. You will also get to know the the vibrant ecosystem of packaging tools that are available to help you with your Python packaging needs.

✨ Create your package ✨

• Package file structure

• Package metadata / pyproject.toml

• Build your package (sdist / wheel)

• Declare dependencies

• Navigate the packaging tool ecosystem

• Non pure Python builds

✨ Publish your package ✨

Gain a better understanding of the Python packaging ecosystem Learn about best practices for:

• Package versioning & release

• Publish to PyPI & Conda-forge

Documentation

✨ Write The Docs ✨

• Create documentation for your users

• Core files to include in your package repository

• Write tutorials to show how your package is used

✨ Developer Docs ✨

• Create documentation for collaborating developers

• Write a development guide

✨ Document For A Community ✨

• Writing a README file

• Set norms with a Code of Conduct

• License your package

✨ Publish Your Docs ✨

• How to publish your docs

• Using Sphinx

• Markdown, MyST, and ReST

• Host your docs on Read The Docs or Github Pages

Tests

We are actively working on this section. Follow development here.

✨ Tests for your Python package ✨

• Intro to testing

• Write tests

• Types of tests

✨ Run your tests ✨

• Run tests locally

• Run tests in CI

Contributing

✨ Code style & Format ✨

• Code style

✨ Want to contribute? ✨

We welcome contributions to this guide. Learn more about how you can contribute.

A community-created guidebook

Every page in this guidebook goes through an extensive community review process. To ensure our guidebook is both beginner-friendly and accurate, we encourage reviews from a diverse set of pythonistas and scientists with a wide range of skills and expertise.

View guidebook contributors

Who this guidebook is for

This guidebook is for anyone interested in learning more about Python packaging. It is beginner-friendly and will provide:

1. Beginning-to-end guidance on creating a Python package.

2. Resources to help you navigate the Python packaging ecosystem of tools and approaches to packaging.

3. A curated list of resources to help you get your package into documented, usable and maintainable shape.

Where this guide is headed

If you have ideas of things you’d like to see here clarified in this guide, we invite you to open an issue on GitHub..

If you have questions about our peer review process or packaging in general, you are welcome to use our pyOpenSci Discourse forum.

This is a living guide that is updated as tools and best practices evolve in the Python packaging ecosystem. We will be adding new content over the next year.