Python Package Structure & Code

This section covers everything you need to structure your Python package, configure metadata, choose build tools, and publish your package to PyPI and conda-forge.

このコンテンツの開発方法

このガイドの内容はすべて、コアパッケージングツールのメンテナや開発者を含むコミュニティメンバーによって吟味されています。

What you'll learn

In this section, you'll learn how to:

• Structure your package - Choose between src and flat layouts, organize tests and documentation

• Configure metadata - Set up pyproject.toml with project information, dependencies, and versioning

• Choose build tools - Compare Hatch, PDM, Poetry, and setuptools to find the right fit

• Build distributions - Create sdist and wheel files ready for publication

• Publish your package - Make your package available on PyPI and optionally conda-forge

• Maintain code quality - Set up linters and formatters to keep your code consistent

Our recommendations align with current Python packaging standards and Scientific Python community specs, while prioritizing tools that are beginner-friendly and well-maintained.

Package setup

✨ Package file structure ✨

Learn how to organize your package files using src or flat layouts. This page helps you decide on a package structure that follows modern Python best practices, including where to place tests and documentation.

✨ Add metadata ✨

Learn how to add project metadata to your Python package to support both filtering on PyPI and also the metadata that a package installer needs to build and install your package.

✨ Declare dependencies ✨

Learn how to specify required dependencies, optional feature dependencies, and development dependencies in your pyproject.toml file.

✨ Setup package versioning ✨

Learn how to manage package versions using semantic versioning (SemVer) or calendar versioning (CalVer). This page helps you choose the right versioning strategy and set up automated version management using tools like hatch_vcs or setuptools-scm.

Development practices

✨ Code style & linters ✨

Learn how to set up code formatters and linters (Black, Ruff, flake8) to ensure your package follows PEP 8 standards and maintains consistent code style throughout your project.

Build & publish

✨ Choose your build tool ✨

Learn how to choose the right packaging tool for your project. Compare Hatch, PDM, Poetry, and setuptools to find the best fit for your workflow. See the summary comparison to help decide.

✨ Build your package ✨

Learn how to build your Python package into distribution files (sdist and wheel) that can be published on PyPI.

✨ Publish to PyPI and Conda ✨

Learn how to publish your package to PyPI and optionally to conda-forge. This page covers the complete process for making your package available to users, including the conda-forge submission process after publishing to PyPI.

Choosing the right tools

Not sure which build tool to use? This decision tree can help you choose based on your package's needs:

Use this decision tree to help select a packaging tool. See the packaging tools page for detailed comparisons and recommendations.

Our recommendations

We suggest tools and approaches based on three principles:

1. Beginner-friendly - Tools that are easy to learn and use for those new to packaging

2. Well-maintained - Tools with active development and good documentation

3. Standards-aligned - Tools that follow current Python packaging standards and Scientific Python community specs

Pure Python vs. complex builds

• Pure Python packages can use any modern tool (Hatch, PDM, Poetry, Flit) - choose based on the features you want

• Packages with C/C++ extensions may need additional build steps. See our complex builds page for guidance. For comprehensive information on packaging compiled projects, see the Scientific Python Development Guide on compiled packaging.

Most scientific Python packages start simple and can evolve to handle more complex requirements as needed.

Submitting your package for peer review?

If you're planning to submit your package to pyOpenSci for peer review, check out our editor checklist for the minimum requirements. These checks are useful for anyone creating a Python package, not just those submitting for review.

These are recommendations, not requirements

The suggestions in this guide are designed to help you create a well-structured package. They are not specific requirements for pyOpenSci peer review.

If you're submitting to pyOpenSci, see our package scope and author guide for actual review requirements.