Pythonパッケージの依存関係#

パッケージ依存性とは何か？#

Pythonパッケージ依存とは、Pythonプロジェクトが使用する外部パッケージやソフトウェアのことです:

Needs to function properly.
Requires if someone wants to develop / work on improving your package locally or
Requires if a user wants to add additional functionality (that is not core) to your package

依存関係は、プロジェクトのコードベースの一部ではありません。プロジェクトのコード内やパッケージの開発中に呼び出されるパッケージやソフトウェアです。

オプションと必須の依存関係を理解する#

You can think about dependencies as being either optional or required. If they are required, they will be listed in the dependencies key in the project table of your pyproject.toml file. If they are optional, they will be listed in the [optional.dependencies] table of your pyproject.toml.

両者については後述します。

Pythonパッケージの依存関係には、オプションのものと必須のものの2つの大きなグループがあります。必須パッケージとは、ユーザがあなたのパッケージを使うために必要なパッケージのことです。オプションの依存関係とは、パッケージの機能を追加するために、ユーザーがインストールを選択できるパッケージのことです。この2つのグループの中で、3つのユースケースを考えることができます。1. コアの依存関係は、ユーザがあなたのパッケージを使うために必須です。2. 開発依存関係はオプションで、誰かがあなたのパッケージをローカルで作業したい場合にのみ必要です。3. 最後に、機能依存はオプションであり、パッケージに追加機能を追加します。すべてのパッケージが機能依存を持つわけではありません。#

必須（またはコア）の依存関係#

Required dependencies are called directly within your package's code. On this page we refer to these dependencies as core dependencies as they are needed in order to run your package. You should place your core or required dependencies in the dependencies key of the [project] table of your pyproject.toml file.

オプションの依存関係#

オプションの依存関係依存関係は、ユーザーが必要に応じてオプションでインストールすることができます。オプションの依存関係には、大きく分けて2つのグループがあります:

開発依存 :これらは、あなたのパッケージの開発をサポートするために必要な依存関係です。pytestのようなテストを実行するツールや、 (flake8やruff のような) リンター、blackのようなコードフォーマッター、さらにはタスクを実行するnoxやtox` のような自動化ツールも含まれます。
Feature dependencies: これらは、パッケージに機能を追加するために、ユーザーがインストールを選択できる依存関係です。

Python プロジェクトがインストールされると、Python パッケージマネージャ (pip または conda) はパッケージの依存関係を自動的にインストールします。これにより、特定の依存関係にある関数を呼び出すと、ユーザーの環境でその関数が利用できるようになります。

依存関係はpyproject.tomlファイルに追加できます

pyproject.tomlの概要ページでは、パッケージの基本的なメタデータを持つ pyproject.toml ファイルをセットアップする方法を学びました。このページでは、 pyproject.toml で異なるタイプの依存関係を指定する方法を学びます。

依存関係はどのように宣言するのか？#

依存関係は pyproject.toml ファイルを使って宣言することを推奨します。こうすることで、パッケージに関連するすべてのメタデータが一箇所で宣言され、ユーザや貢献者がパッケージのインフラストラクチャを理解するのがより簡単になります。

以前は requirements.txt ファイルを使ってパッケージの依存関係を宣言するのが一般的でした。しかし近年、エコシステムはこの情報を pyproject.toml ファイルに保存するようになりました。しかし、プロジェクトによっては、特定のローカルな開発ニーズのために requirements.txt ファイルを保持していることに気づくかもしれません。

パッケージが依存関係を保存する他の方法

プロジェクトが他の言語で書かれた拡張機能を含んでいる場合、 setup.py ファイルが必要になるかもしれません。あるいは、依存関係の宣言に setup.cfg を使っているパッケージに貢献することもできます。これについては setuptools のドキュメントを参照してください

必要な依存関係をpyproject.tomlファイルに追加#

コアプロジェクトの依存関係は、ユーザがパッケージをインストールするときに pip や conda のようなパッケージマネージャによってインストールされる必要があります。これらの依存関係は、pyproject.toml ファイルの [project] テーブルにある dependencies 配列に追加することができます。これは次のようになります:

[project]
name = "examplePy"
authors = [
    {name = "Some Maintainer", email = "some-email@pyopensci.org"},
]

dependencies = [
    "rioxarray",
    "geopandas",
]

Ideally, you should only list the packages that are necessary to install and use your package in the dependencies key in the [project] table. This minimizes the number of additional packages that your users must install as well as the number of packages that depend upon your package must also install.

インストールする依存関係を少なくすることで、ユーザー環境でのバージョン不一致の可能性が低くなることを覚えておいてください。

依存関係の例

numpy 配列に格納されたデータの美しいプロットを作成する plotMe というパッケージがあるとしましょう。 plotMe パッケージでプロットを作成するには、 seaborn パッケージを使用してプロットをスタイリングし、 numpy パッケージを使用して配列フォーマットのデータを処理します。

上の例では、plotMeパッケージは2つのパッケージに依存しています:

seaborn
numpy

つまり、plotMeをインストールしたユーザーの 環境 で動作させるためには、そのユーザーの環境にも必要な 依存関係 の両方がインストールされていることを確認する必要があります。

依存関係を pyproject.toml ファイルで宣言することで、あなたのパッケージが PyPI に公開されるときに必須の依存関係としてリストされ、パッケージマネージャ ( pip や conda ) があなたのパッケージと一緒にユーザーの環境に自動的にインストールするようになります:

python -m pip install plotMe

オプションの依存関係#

ドキュメントの構築、テストの実行、パッケージの配布ファイルの構築のためのオプションの依存関係は、しばしば開発依存関係と呼ばれます。これらは、ユーザがあなたのパッケージをローカルで作業し、以下のようなタスクを実行するために必要な依存関係です:

テストスイートの実行
ドキュメントの作成
リンティングとその他のコードクリーンナップツール

These dependencies are considered optional, because they are not required to install and use your package. Feature dependencies are considered optional and should also be placed in the [project.optional-dependencies] table.

Optional dependencies can be stored in an [project.optional-dependencies] table in your pyproject.toml file.

It's important to note that within the [project.optional-dependencies] table, you can store additional, optional dependencies within named sub-groups. This is a different table than the dependencies array located within the [project] table discussed above which contains a single array with a single list of required packages.

オプションの依存グループを作成する#

pyproject.toml ファイルでオプションの依存関係を宣言します:

Add a [project.optional-dependencies] table to your pyproject.toml file.
構文を使って、依存関係の名前付きグループを作成します:

group-name = ["dep1", "dep2"]

GitHub / Gitlab からパッケージをインストールする

GitHubから直接インストールする必要がある依存関係がある場合は、git+httpsというインストール方法を使います、以下のように pyproject.toml ファイルを使用します:

dependencies = [
"my_dependency >= 1.0.1 @ git+https://git.server.example.com/mydependency.git"
]

重要:セキュリティ上の理由から、あなたのライブラリがGitHubでホストされているプロジェクトに依存している場合、あなたのプロジェクトをPyPIにアップロードするには、そのリポジトリの特定のコミット/タグ/ハッシュを指す必要があります。

以下では、tests、docs、lintという3つのオプションの開発依存関係を作成しました。また、機能依存のセットも追加しました。

[project.optional-dependencies]
tests = [
  "pytest",
  "pytest-cov"
]
docs = [
  "sphinx",
  "pydata_sphinx_theme"
]
lint = [
  "black",
  "flake8"
]
feature = [
  "pandas",
]

その他の依存リソース

依存グループをインストールする#

Diagram showing a Venn diagram with three sections representing the dependency groups listed above - docs feature and tests. In the center it says your-package and lists the core dependencies of that package seaborn and numpy. To the right are two arrows. The first shows the command python - m pip install your-package. It them shows how installing your package that way installs only the package and the two core dependencies into a users environment. Below is a second arrow with python -m pip install youPackage[tests]. This leads to an environment with both the package dependencies - your-package, seaborn and numpy and also the tests dependencies including pytest and pytest-cov — When a user installs your package locally using `python -m pip install your-package` only your package and it's core dependencies get installed. When they install your package `python -m pip install your-package[tests]` pip will install both your package and its core dependencies plus any of the dependencies listed within the tests array of your `[project.optional-dependencies]` table.#

python -m pip install と pip install の比較

このガイドのすべての例で、構文を使って pip を呼び出していることに気づくでしょう:

python -m pip

python -m を使用して pip を呼び出すと、パッケージをインストールするために使用する pip が、現在アクティブな Python 環境のものであることが保証されます。インストールの衝突を避けるために、 pip を呼び出すときは常にこの方法を使うことを強く推奨します。

これが思い通りに動くようにするには、 pip を使って何かをインストールする前に、パッケージの開発環境を有効にしてください。

上記で定義したグループを使用して、構文を使って開発依存ファイルをインストールすることができます:

python -m pip install ".[docs]"

上記でインストールするのは:

ドキュメント (docs) に必要な依存関係、
required package dependencies in the dependencies array and
あなたのパッケージ

pipを使います。以下では、パッケージ、必要な依存関係、オプションのテスト依存関係をインストールします。

python -m pip install ".[tests]"

You can install multiple dependency groups in the [project.optional-dependencies] table using:

python -m pip install ".[docs, tests, lint]"

zshシェルユーザーの場合

あなたやパッケージの貢献者が使うかもしれません、さまざまなシェルアプリケーションがあります。

zsh は、新しい Mac OS コンピュータにデフォルトで搭載されているシェルです
Windowsユーザーは、git bashのようなツールを使うことができます

シェルによっては、引用符で囲まれていない括弧 ([tests]) をサポートしていないものもあるので、このガイドではこのようにコマンドに引用符を追加しています:

python -m pip install ".[tests]"

ガイドブックやコントリビューションガイドでは、以下の例のように引用符を使わないコマンドを見かけることがあります:

python -m pip install your-package[tests]

二重引用符を付けずに your-package[tests] を呼び出すと、一部のシェルでは動作しますが、 すべてではありません 。

依存関係のセットを組み合わせる#

上記では、 pyproject.toml から依存関係をインストールする方法を説明しました。場合によっては、依存関係のセットをこのようにグループ化したいこともあるでしょう:

[project.optional-dependencies]
tests = ["pytest", "pytest-cov"]
docs = ["sphinx", "pydata_sphinx_theme"]
dev = [
    "packageName[tests, docs]",
    "build",
    "twine"
]

上記のコマンドを使えば、testsとdocsの両方の依存リストをインストールできます:

python -m pip install ".[dev]"

Tip

上記の構文を使って依存関係をインストールする場合:

python -m pip install ".[tests, docs]"

pip はあなたのパッケージとそのコアの依存関係もインストールします。

condaはどこに入りますか？

pyproject.toml ファイルを使うと、PyPI(またはGitHub/ GitLab)で公開されているPythonパッケージを依存関係として列挙することができます。このファイルを作成し、依存関係を宣言し、パッケージをビルドする、パッケージをPyPIに公開するとすると、1つのコマンドであなたのパッケージと依存関係のあるパッケージの両方をインストールすることができます。

python -m pip install your-package

これは、パッケージが純粋なpython (他の言語が使われていない) のであれば、とてもうまくいきます。

いくつかのパッケージ、特に科学的なPythonエコシステムでは、Pythonで書かれていない依存関係を必要とします。 Condaは、PythonとPython以外の言語の両方で書かれたコードを持つツールの配布をサポートするために作られました。

environment.yml ファイルで conda ユーザーをサポートする#

上記のワークフローは、PyPIでパッケージを公開することを想定しています。そして、 grayskullを使ってレシピを投稿することで、conda-forgeに(オプションで)公開する予定です。

conda ユーザーをサポートしたいのであれば、彼らがあなたのパッケージをインストールするのに使える conda 環境も管理した方が良いでしょう。 conda 環境を維持することは、あなたのパッケージが conda 環境に期待通りにインストールされるかをテストするのにも役立ちます。

condaユーザーへのメモ

ツールの開発にconda環境を使用している場合、 python -m pip install -e . を使用してパッケージをインストールするとき（または一般的にpipを使用するとき）、依存関係はcondaではなくPyPIからインストールされることに注意してください。

したがって、conda環境を実行している場合、パッケージを "editable "モードでインストールすると、依存関係が衝突する危険性があります。これは、GDALのような地理空間システムライブラリや他のシステムレベルの依存関係を必要とする空間パッケージがある場合、特に重要です。

あるいは、 python -m pip install -e . --no-deps を使ってパッケージだけをインストールすることもできます。そして、conda環境ファイルを使って残りの依存関係をインストールします。

Read the Docs の依存関係#

プロジェクトで依存関係を指定できたので、Read the Docsへのパブリッシュなど、他のワークフローをサポートするためにそれらを使用できます。

Read the Docs は、継続的インテグレーション/継続的デプロイメントサービスを備えたドキュメントプラットフォームで、あなたのドキュメントを自動的にビルドして公開します。

Read the Docsを使用してドキュメントを構築している場合、 readthedocs.yaml ファイルを使用して依存関係をインストールする必要があるかもしれません。

以下は、readthedocs.yamlファイル内のpyproject.tomlファイルに依存関係テーブルの docs セクションをインストールする例です。

python:
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs # you can add any of the subgroups of dependencies from your pyproject.toml file to this list.

Read the DocsとPythonパッケージ

readthedocs.yaml ファイルの作成方法についてはこちらをご覧ください。
Read the DocsのPoetryを使って依存関係をインストールしたい場合は、こちらで詳しく説明されています。