Pythonパッケージの依存関係

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

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

1. 適切に機能する必要があります。

2. もし、あなたのパッケージをローカルで開発したり、改良したりしたい人がいるか

3. ユーザが（コアではない）追加機能をパッケージに追加したい場合に必要です。

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

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

依存関係はオプションか必須であると考えることができます。 必須であれば、 pyproject テーブルの dependencies キーにリストされます。 オプションの場合は、 pyproject.toml の [optional.dependencies] テーブルにリストされます。

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

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

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

必要な依存関係は、パッケージのコード内で直接呼び出されます。このページでは、パッケージを実行するために必要なこれらの依存関係を コア依存関係 と呼びます。 pyproject.toml ファイルの [project] テーブルの dependencies キーに、コアまたは必要な依存関係を置く必要があります。

オプションの依存関係

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

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

2. 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",
]

理想的には、 [project] テーブルの dependencies キーに、あなたのパッケージをインス トールして使用するために必要なパッケージだけをリストするようにしま す。 こうすることで、ユーザがインストールしなければならない追加パッケージの数や あなたのパッケージに依存するパッケージの数を最小限に抑えることができます。

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

依存関係の例

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

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

• seaborn

• numpy

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

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

python -m pip install plotMe

オプションの依存関係

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

• テストスイートの実行

• ドキュメントの作成

• リンティングとその他のコードクリーンナップツール

これらの依存関係はオプションとみなされます。なぜなら、あなたのパッケ ージをインストールして使用するのに必要ではないからです。 機能の依存関係はオプションとみなされ、 [project.optional-dependencies] テーブルに置く必要があります。

オプションの依存関係は pyproject.toml ファイルの [project.optional-dependencies] テーブルに格納することができます。

ここで重要なのは、 [project.optional-dependencies] テーブルの中で、名前付きサブグループの中に追加のオプションの依存関係を格納できることです。これは、上で説明した [project] テーブル内の依存関係配列とは異なるテーブルであり、必要なパッケージのリストを1つだけ含む配列が1つ格納されています。

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

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

1. pyproject.toml ファイルに [project.optional-dependencies] テーブルを追加します。

2. 構文を使って、依存関係の名前付きグループを作成します:

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",
]

その他の依存リソース

• 詳細はこちら: PyPAのオプション依存関係の宣言の概要を見る

• Dependency specifiers

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

ユーザがローカルで python -m pip install your-package を使ってあなたのパッケージをインストールすると、あなたのパッケージとそのコア依存関係のみがインストールされます。ユーザがあなたのパッケージ python -m pip install your-package[tests] をインストールすると、pip はあなたのパッケージとそのコア依存パッケージの両方をインストールし、さらに [project.optional-dependencies] テーブルの tests 配列にリストされている依存パッケージをインストールします。

python -m pip install と pip install の比較

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

python -m pip

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

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

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

python -m pip install ".[docs]"

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

• ドキュメント (docs) に必要な依存関係、

• 必要なパッケージの依存関係を dependency 配列で指定し

• あなたのパッケージ

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

python -m pip install ".[tests]"

[project.optional-dependencies] テーブルに複数の依存グループをインストールすることができます:

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を使って依存関係をインストールしたい場合は、 こちらで詳しく説明されています。