pyOpenSci Python Package Guide#

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

GitHub release (latest by date) DOI

About this guide

Image with the pyOpenSci flower logo in the upper right hand corner. The image shows the packaging lifecycle. The graphic shows a high level overview of the elements of a Python package. The inside circle has 5 items - user documentation, code/api, test suite, contributor documentation, project metadata / license / readme. In the middle of the circle is says maintainers and has a small icon with people. On the outside circle there is an arrow and it says infrastructure.

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 ✿
✿ Package Metadata Tutorials ✿
✿ Packaging Tool Tutorials ✿
✿ Reference Guides ✿

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 ✨
✨ Publish your package ✨

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

Documentation#

✨ Write The Docs ✨
✨ Developer Docs ✨
✨ Document For A Community ✨
✨ Publish Your Docs ✨

Tests#

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

✨ Tests for your Python package ✨
✨ Run your tests ✨

Contributing#

✨ Code style & Format ✨
Contributing to the Python Packaging Guide
✨ Want to contribute? ✨

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

Contributing to the Python Packaging Guide
xkcd comic showing a stick figure on the ground and one in the air. The one on the ground is saying. `You're flying! how?` The person in the air replies `Python!` Below is a 3 rectangle comic with the following text in each box. Box 1 - I learned it last night. Everything is so simple. Hello world is just print hello world. Box 2 - the person on the ground says - come join us programming is fun again. It's a whole new world. But how are you flying? box 3 - the person flying says - i just typed import antigravity. I also sampled everything in the medicine cabinet. But i think this is the python. The person on the ground is saying - that's it?

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.