科学的PythonプロジェクトのためのPythonパッケージ構造#

There are two different layouts that you will commonly see within the Python packaging ecosystem: src and flat layouts. Both layouts have advantages for different groups of maintainers.

We strongly suggest, but do not require, that you use the src/ layout (discussed below) for creating your Python package. This layout is also recommended in the PyPA packaging guide tutorial.

pyOpenSciは査読のために特定のパッケージ構造を要求することはありません

We understand that it would take significant effort for existing maintainers to move to a new layout.

このページの概要では、これから Python のパッケージングを始める人や、パッケージがシンプルなビルドで、より失敗のないアプローチに移行することに前向きな人に最適だと思われる推奨事項を紹介します。

Other resources you can check out:

You can use tools like Hatch to quickly create a modern Python package structure. Check out our quickstart tutorial:

Want to learn how to create the structure to build your package? Click here.

What is the Python package source layout?#

An example of the src/package layout structure is below.

myPackageRepoName
├── CHANGELOG.md               ┐
├── CODE_OF_CONDUCT.md         │
├── CONTRIBUTING.md            │
├── docs                       │ Package documentation
│   └── index.md
│   └── ...                    │
├── LICENSE                    │
├── README.md                  ┘
├── pyproject.toml             ] Package metadata and build configuration
├── src                        ┐
│   └── myPackage              │
│       ├── __init__.py        │ Package source code
│       ├── moduleA.py         │
│       └── moduleB.py         ┘
└── tests                      ┐
   └── ...                     ┘ Package tests

上の例では、以下のディレクトリの位置に注意してください:

  • docs/: Discussed in our docs chapter, this directory contains your user-facing documentation website. In a src/ layout docs/ are normally included at the same directory level as the src/ folder.

  • tests/ This directory contains the tests for your project code. In a src/ layout, tests are normally included at the same directory level as the src/ folder.

  • src/package/: これはPythonプロジェクトのコードを含むディレクトリです。 "Package" は通常プロジェクトの名前です。

また、上記の例では、pyOpenSciが必要とするすべてのコアドキュメントファイルがプロジェクトディレクトリのルートにあることに注意してください。 これらのファイルには以下が含まれています:

  • CHANGELOG.md

  • CODE_OF_CONDUCT.md

  • CONTRIBUTING.md

  • LICENSE.txt

  • README.md

パッケージングに関するドキュメント要件については、こちらをご覧ください。

src/package レイアウトを使用する科学的パッケージの例

src/ のレイアウトとテスト#

The benefit of using the src/package layout is that it ensures tests are run against the installed version of your package rather than the files in your package working directory. If you run your tests on your files rather than the installed version of your package, you may be missing issues that users encounter when your package is installed.

If tests/ are outside the src/package directory, they aren't included in the package's wheel. This makes your package size slightly smaller, which places a smaller storage burden on PyPI, and makes them faster to fetch.

Pythonはどのようにインポートモジュールを検出し、優先順位をつけるか

デフォルトでは、Pythonは現在の作業ディレクトリにあるモジュールをPythonモジュール検索パスの先頭に追加します。

つまり、パッケージの作業ディレクトリでフラットレイアウトの /package/module.py を使ってテストを実行すると、Python はインストールされたパッケージを検出する前に package/module.py ファイルを検出します。

However, if your package lives in a src/ directory structure src/package, then it won't be added to the Python path by default. This means that when you import your package, Python will be forced to search the active environment (which has your package installed).

Note: Python versions 3.11 and above have a path setting that can be adjusted to ensure the priority is to use installed packages first (e.g., PYTHONSAFEPATH).

Don't include tests in your package wheel#

Writing tests for your package is important; however, we do not recommend including tests as part of your package wheel by default. However, not including tests in your package distribution will make it harder for people other than yourself to test whether your package runs properly on their system. If you have a small test suite (Python files + data), and think your users may want to run tests locally on their systems, you can include tests by moving the tests/ directory into the src/package directory (see example below).

src/
  package/
    tests/
docs/

Including the tests/ directory in your src/package directory ensures that tests will be included in your package's wheel.

パッケージ配布にテストを含める方法については、 pytest documentation for more about including tests in your package distribution を必ず読んでください。

パッケージwheelにテストとデータを含める際の課題

Tests, especially when accompanied by test data, can create a few small challenges, including:

  • Take up space in your distribution, which will build up over time as storage space on PyPI

  • Large file sizes can also slow down package installation.

However, in some cases, particularly in the scientific Python ecosystem, you may need to include tests.

テストスイートのデータセットをパッケージに含めないでください#

If you include your tests in your package distribution, we strongly discourage you from including data in your test suite directory. Rather, host your test data in a repository such as Figshare or Zenodo. Use a tool such as Pooch to access the data when you (or a user) runs tests.

For more information about Python package tests, see the tests section of our guide.

  • src/package レイアウトの方が意味的に明確である。 コードは常に src/package ディレクトリにあり、　tests/ と docs/ はルートディレクトリにあります。

重要

If your package tests require data, do NOT include that data within your package structure. Including data in your package structure increases the size of your distribution files. This places a maintenance toll on repositories like PyPI and Anaconda.org that have to deal with thousands of package uploads.

Click here for a quickstart tutorial on creating your Python package.

What is the flat Python package layout?#

Many scientific packages use the flat-layout given:

  • This layout is used by many core scientific Python packages such as NumPy, SciPy, and Matplotlib.

  • Many Python tools depend upon tools in other languages and/or complex builds with compilation steps. Many maintainers prefer features of the flat layout for more complex builds.

While we suggest that you use the src/package layout discussed above, it's important to also understand the flat layout, especially if you plan to contribute to a package that uses this layout.

ほとんどの科学的Pythonパッケージがソースを使わない理由

In most cases, moving to the src/package layout for larger scientific packages that already use a flat layout would consume significant time.

However, the advantages of using the src/package layout for a beginner are significant. As such, we recommend that you use the src/package layout if you are creating a new package.

Numerous packages in the ecosystem have had to move to a src/package layout.

フラットレイアウトの構造はどのようなものですか？#

フラットレイアウトの主な特徴は以下の通りです:

  • パッケージのソースコードは、ディレクトリのルートにあるパッケージ名のディレクトリに格納されます

  • 多くの場合、 tests/ ディレクトリも同じ package ディレクトリの中にあります。

以下に、フラットレイアウトを使った科学的Pythonパッケージの推奨構造を示します。

myPackage/
├── CHANGELOG.md             ┐
├── CODE_OF_CONDUCT.md       │
├── CONTRIBUTING.md          │
├── docs/                    │ Package documentation
│   └── ...                  │
├── LICENSE                  │
├── README.md                ┘
├── pyproject.toml           ] Package metadata and build configuration
|   myPackage/               ┐
│     ├── __init__.py        │ Package source code
│     ├── moduleA.py         │
│     └── moduleB.py         ┘
      tests/                 ┐
        └── test-file1.py    | Package tests
        └── ....             ┘

Pythonパッケージでフラットレイアウトを使うメリット#

フラットレイアウトを採用することは、科学コミュニティにとってもメリットがあります。

  • この構造は歴史的にエコシステム全体で使われてきたものであり、これを使うパッケージが変わることはないでしょう。

  • ルートディレクトリからパッケージを直接インポートすることができます。これがそれぞれのワークフローに組み込まれている人もいるでしょう。しかし、初心者がこの方法をとる危険性は、インストールされたバージョンのパッケージに対して開発やテストを行っていないことにあります。 むしろ、フラットファイルを直接扱うことになります。

フラットレイアウトを使用する科学的Pythonのコアパッケージ

It would be a significant maintenance cost and burden to move all of these packages to a different layout. The potential benefits of the source layout for these tools are not worth the maintenance investment.