Python package structure information#

This section provides guidance on your Python package’s structure, code formats and style. It also reviews the various packaging tools that you can use to support building and publishing your package.

If you are confused by Python packaging, you are not alone! The good news is there are some great modern packaging tools that ensure that you’re following best practices. Here, we review tool features and suggest tools that might be best fitted for your workflow.

Figure showing a decision tree with the various packaging tool front-end and back-end options.

Diagram showing the various front-end build tools that you can select from. See the packaging tools page to learn more about each tool.#


If you are considering submitting a package for peer review, have a look at the bare-minimum editor checks that pyOpenSci performs before a review begins. These checks are useful to explore for both authors planning to submit a package to us for review and for anyone who is just getting started with creating a Python package.

What you will learn here#

In this section of our Python packaging guide, we:

  • Provide an overview of the options available to you when packaging your tool.

  • Suggest tools and approaches that both meet your needs and also support existing standards.

  • Suggest tools and approaches that will allow you to expand upon a workflow that may begin as a pure Python tool and evolve into a tool that requires addition layers of complexity in the packaging build.

  • Align our suggestions with the most current, accepted PEPs (Python Enhancement Protocols) and the Scientific Python community SPECs.

  • In an effort to maintain consistency within our community, we also align with existing best practices being implemented by developers of core Scientific Python packages such as Numpy, SciPy and others.

Guidelines for pyOpenSci’s packaging recommendations#

The flexibility of the Python programming language lends itself to a diverse range of tool options for creating a Python package. Python is so flexible that it is one of the few languages that can be used to wrap around other languages. The ability of Python to wrap other languages is one the reasons you will often hear Python described as a “glue” language

If you are building a pure Python package, then your packaging setup can be simple. However, some scientific packages have complex requirements as they may need to support extensions or tools written in other languages such as C or C++.

To support the many different uses of Python, there are many ways to create a Python package. In this guide, we suggest packaging approaches and tools based on:

  1. What we think will be best and easiest to adopt for those who are newer to packaging.

  2. Tools that we think are well maintained and documented.

  3. A shared goal of standardizing packaging approaches across this (scientific) Python ecosystem.

Here, we also try to align our suggestions with the most current, accepted Python community and scientific community.

Suggestions in this guide are not pyOpenSci review requirements

The suggestions for package layout in this section are made with the intent of being helpful; they are not specific requirements for your package to be reviewed and accepted into our pyOpenSci open source ecosystem.

Please check out our package scope page and review requirements in our author guide if you are looking for pyOpenSci’s Python package review requirements!