純粋な Python パッケージの作成#

このレッスンについて

このレッスンでは、pyOpenSci Python パッケージ コピー機テンプレートを使用して、Python パッケージ をすばやく作成します。パッケージは、ローカルにもリモートにも GitHub (または GitLab) などの Web サイトから Python 環境にインストールできます。

このレッスンで学ぶこと:

  • ローカルでも GitHub からでも、コードを任意の Python 環境にインストール可能にする方法

  • パッケージのビルド、インストール、公開に必要なメタデータを含む pyproject.toml ファイル を更新する方法

  • パッケージのビルドとインストールに使用する ビルドバックエンド を宣言する方法

  • インタラクティブな開発のために編集可能モードでパッケージをインストールする方法

このレッスンを完了するために必要なもの

このレッスンを完了するには、コンピュータにローカルの Python 環境とシェルが必要です。レッスンを正常に完了するには、Copier と Hatch がインストールされている必要があります。

Windows を使用している場合やシェルに慣れていない場合は、Carpentries のシェルレッスン[1] を参照するとよいでしょう。Windows ユーザーは、シェルや git に関連するステップのために gitbash などのツールを設定する必要があるでしょう。

この図には2つの小さなボックスがあり、右側にPython環境を示す矢印があります。 小さなボックスには、your-packageとpip install packageと書かれています。 右側の環境欄には「あなたのPython環境」と書かれています。 Matplotlib、NumPy、Pandas、Xarray、GeoPandasなどのコアパッケージとともに、your-packageがリストアップされています。

前のレッスンでは、Python パッケージとは何かを学びました。Python パッケージを作成すると、コードをコンピュータ上の任意の Python 環境にインストールできます。その後、Pandas や GeoPandas のようなパッケージをインポートするのと同じ方法で、ワークフローにインポートできます。コードを GitHub や GitLab にプッシュすれば、そこから直接インストールすることもできます。Python パッケージの基本要素について詳しくは、ページの下部をスクロールしてください。。#

Python パッケージの作成#

以下では、pyOpenSci コピーテンプレート を使用して純粋な Python パッケージを作成します。私たちのテンプレートは、デフォルトのパッケージ化ツールとしてハッチを使用します。このレッスンの最後では、Python パッケージのディレクトリ構造の基本と、関連するキー ファイル (__init__.py と pyproject.toml) について詳しく学びます。

ステップ1: パッケージのディレクトリ構造を設定する#

  • シェルまたはお好みのターミナルを開きます。

  • シェルで cd コマンドを使って、パッケージを置きたい場所に移動します。テンプレートがパッケージのディレクトリ構造を作成してくれます

  • パッケージの名前を決めてください。 名前は以下のようにします:

    • スペースがない (必須)

    • すべて小文字を使用 (推奨)。このチュートリアルでは pyospackage を使用します。

    • 名前にはアルファベットと _ または - のみを使用してください。つまり、pyos*package という名前は使えません。しかし、pyos_package または pyos-package という名前ならどちらも OK です。

ターミナルで、以下のコマンドを実行します。これにより、質問をし、Python パッケージをカスタマイズするのに役立つ一連のプロンプトが開始されます。

copier copy gh:pyopensci/pyos-package-template .

上記のコマンドを実行すると、テンプレートによって一連の質問が表示されます。

「デフォルト値を使用して、もう 1 つの質問に答えて残りをスキップしますか?」というプロンプトが表示されることに注意してください。 はい、ただし最小限のセットアップを使用します を選択すると、使用するドキュメント、テスト、サンプル モジュールを含むパッケージの最も基本的なバージョンを作成できます。

この質問の後、テンプレートは希望の GitHub ユーザー名を尋ね、基本的なテスト、ドキュメント、GitHub 構成セットアップを含むパッケージを作成します。

➜ copier copy gh:pyopensci/pyos-package-template .
🎤 "Welcome to the pyOpenSci package template.
Please select the type of template that you want to create today."
 >> MINIMAL: I want a minimal setup (package, tests and docs; typing); linting not included).
    FULL DEFAULT: I want to use the default settings but I want it setup for me.
    FULL CUSTOM: I want it all but I want to fully customize all template elements.
🎤 What is the name of the project? Used as the README.md title, in the
   pyospackage_juno
🎤 Please provide a short description for the package.
    (Finish with 'Alt+Enter' or 'Esc then Enter')
> A great package that adds and subtracts numbers.
🎤 Who is the author of the package? Used in the package description.
   juno dawg
🎤 Provide you or your organization's GitHub username. Used to generate
   pyopensci

テンプレートは、上で使用したディレクトリへのファイルのコピーを開始します。 (「.」は現在の作業ディレクトリを意味します。)

...Copying from template version 0.6.4.1
    create  CODE_OF_CONDUCT.md
    ...The template will continue to copy files...

最終的なパッケージ構造は次のようになります:

└── .github/ # a hidden directory with templates for github and actions to run your tests
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── pyproject.toml
└── src/  # This is your package directory where your code lives
└── docs/ # this is where your documentation lives
└── tests/ # Your tests are here
テスト、ドキュメント、GitHubインフラストラクチャを備えた完全なパッケージ

テンプレートのプロンプトを操作するときに「付加機能」のデフォルト オプションを使用すると、テンプレートは Hatch を使用して GitHub CI アクション、入力、テスト、環境などを含む完全なパッケージ セットアップを作成します。パッケージ全体をカスタマイズする場合は、どのプラットフォームでホストするか (GitHub か GitLab)、入力するかどうか、使用するドキュメント エンジンなどを選択できます。

結果として得られるパッケージディレクトリは次のようになります:

├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── docs # This defaults to sphinx docs
│   ├── conf.py
│   └── index.md
├── pyproject.toml
├── src/   # This is your package directory where your code lives
│   └── pyospackage_pyopensci/
|       ├── __init__.py
|       └── example.py
└── tests/   # This is where your tests live, you don't need subdirectories, but they are nice to have
    ├── integration/
    ├── system/
    └── unit/
        └── test_example.py

パッケージが使用するデフォルトのツールは以下の通りです:

  • Sphinx ドキュメント用の PyData Sphinx テーマ

  • テスト用のpytest

  • 環境構築のための Hatch

完全なカスタマイズ パッケージ設定の要素をカスタマイズしたい場合は、「いいえ、テンプレートを完全にカスタマイズします。」を選択します。 これにより、以下を選択できるようになります。

  • Sphinx vs MkDocs vs ドキュメントなし

  • GitHub vs GitLab

  • VCSバージョン管理

  • その他

ステップ 2: パッケージ内の既存のモジュールを調べる#

モジュール とは、パッケージにアクセスして実行させたいコードを含む .py ファイルを指します。pyospackage サブディレクトリには、パッケージをすばやくテストするために使用できる example.py モジュールがあります。

example.pyモジュールのコードには、いくつかの機能があることに注意してください:

  1. これは numpyスタイルのdocstring を持っています。

  2. typing を使用します。

  3. モジュールの先頭には、モジュールの機能を説明するドキュメント文字列があります。

Python はさまざまな docstring 形式をサポートしています。Python オブジェクトのドキュメント化に最もよく使われる形式は、NumPy スタイル Docstring[2]、Google スタイル Docstring[3]、Epytext スタイル Docstring[4] です。

pyOpenSciは、NumPyのDocstring規約を使用することを推奨します。

両方のトピックの概要については、docstrings の詳細については、こちらをご覧ください を参照してください。

def add_num(a: int, b: int) -> int:
    """
    Add two numbers.

    Parameters
    ----------
    a : int
        The first number to be added.
    b : int
        The second number to be added.

    Returns
    -------
    int
        The sum of the two input numbers (a + b).

    Examples
    --------
    >>> add_num(3, 5)
    8
    >>> add_num(-2, 7)
    5
    """
    return a + b

Pythonモジュールと __init__.py ファイル

「モジュール」という言葉は、Python のコードを含む .py ファイルを指します。

__init__.py は、Pythonがディレクトリに少なくとも1つのモジュールが含まれていることを認識できるようにします。 パッケージは複数のモジュール [5] を持つことができます。

ステップ 3: (オプション)-- モジュールにコードを追加する#

必要に応じて、2 番目の関数を example.py モジュールに追加します。単純な関数でも構いません。たとえば、数値を乗算する 2 番目の関数を作成します。

ステップ 4: pyproject.toml ファイルのメタデータを確認する#

pyproject.toml ファイルには、パッケージを構築する Hatch など、対話するさまざまなツールに指示を与えるメタデータが保存されます。パッケージのメタデータを指定することもできます。

pyproject.toml フォーマットについては、このファイルにメタデータや情報を追加する次のレッスン で詳しく学びます。

生成された pyproject.toml 内のメタデータは、上記のコピー テンプレートで提供した情報を使用してすでにセットアップされています。

TOMLファイルの概要

TOMLフォーマット は表と変数で構成されます。 表は角括弧で示される情報のセクションです:

[this-is-a-table].

テーブルには、変数名と = 記号で定義された変数を含めることができます。たとえば、build-system テーブルにはほとんどの場合2つの変数が含まれます:

  1. requires = は、ビルドツールに対して、パッケージをビルドする前にインストールする必要があるツールを指示します。この場合は hatchling です。

  2. build-backend = 、これは、特定のビルドバックエンド名を定義するために使われます、(この例では、 hatchling.build を使用しています)。

# An example of the build-system table which contains two variables - requires and build-backend
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

TOMLはデータ構造を整理し、設定ファイル内の関係を定義します。

pyproject.toml 形式の詳細はこちらをご覧ください。

  • Hatchが作成した pyproject.toml ファイルをお好みのテキストエディタで開いてください。 下の例のようになるはずです。

  • パッケージのバージョン、パッケージ名、作成者名が正しいことを確認してください。電子メールはオプションです。

[project]
name = "pyospackage"
version = "0.1.0"
description = "A small template package that does cool things."
authors = [
    { name = "pyOpenSci", email = "pyopensci@pyopensci.org" },
]
license = "MIT"
readme = {"file" = "README.md", "content-type" = "text/markdown"}
# Please consult https://pypi.org/classifiers/ for a full list.
classifiers = [
    "Development Status :: 2 - Pre-Alpha",
    "Intended Audience :: Science/Research",
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3 :: Only",
]
# TODO: add keywords
keywords = []
# TODO: add dependencies
dependencies = []

[project.urls]
Homepage = "https://github.com/pyopensci/pyospackage"
"Source Code" = "https://github.com/pyopensci/pyospackage"
"Bug Tracker" = "https://github.com/pyopensci/pyospackage/issues"
Documentation = "https://pyospackage.readthedocs.io"
Download = "https://pypi.org/project/pyospackage/#files"

[project.optional-dependencies]
dev = [
    "hatch",
    "pre-commit",
]

テンプレートで生成された pyproject.toml ファイルの下部に、ハッチ環境を定義するセクションが表示されます。ハッチ環境については後のレッスンで説明します。

pyproject.tomlファイルに最低限必要なもの

PyPI で公開するために pyproject.toml ファイルに必要な中核的な情報は、パッケージの名前 と バージョン です。しかし、pyproject.toml ファイルの早い段階でメタデータを充実させておくことをお勧めします。

pyproject.toml ファイルにプロジェクトのメタデータを入れたら、それを更新することはほとんどありません。

ステップ 5: パッケージをローカルにインストールする#

この時点で、以下を用意できているはずです:

  1. pyproject.toml ファイルをルートに持つプロジェクトのディレクトリ構造

  2. 空の __init__.py ファイルを含むパッケージ・ディレクトリと

  3. 少なくとも1つの Python モジュール (例: example.py)

これで Python パッケージをインストール（ビルド）する準備ができました！

While Hatch can create an environment and install your package for you (you'll learn how in the Hatch environments lesson), this lesson uses pip to install your package, so you can see what is happening when a package is installed into a Python environment that you create.

まず、お好みのシェルを開き(Windows ユーザーは GitBash などを使用)、まだプロジェクトディレクトリにいない場合は cd で移動します。

Next, activate the Python environment that you wish to use. We recommend installing packages that you are developing into a virtual environment rather than your system Python. If you don't have one yet:

  • conda: install Miniforge (or Miniconda), then run conda create -n pyosdev python

  • venv: ships with Python; run python -m venv .venv in your project directory. See the venv docs.

Then activate it:

> conda activate pyosdev
(pyosdev) >

> source .venv/bin/activate
(.venv) >

> .venv\Scripts\activate
(.venv) >

Your prompt will show the environment name once it is active. Now install your package:

# Cd into your project directory (if you are not already there)
> cd pyospackage
# Install your package
> python -m pip install -e .

Obtaining file:///Users/leahawasser/Documents/GitHub/pyos/pyosPackage
  Installing build dependencies ... done
  Checking if build backend supports build_editable ... done
  Getting requirements to build editable ... done

# Check to see if the package is installed
> python -m pip list

python -m pip install -e . は何をしているのか？

python -m pip install -e . は、編集可能モード (-e) で現在アクティブな Python 環境にパッケージをインストールします。編集可能モードでパッケージをインストールすると、コードに取り組みながら、お気に入りの Python インターフェースで更新を対話的にテストできます。編集可能モードの重要な注意点は、コードを更新するたびに Python を再起動する必要があることです。

(編集可能モードではなく) 定期的にパッケージをインストールしたい場合は、次のようにします:

  • python -m pip install .

pip を呼び出す際に python -m を使用する

上記では、 python -m を使用して、現在アクティブな環境にインストールされている pip のバージョンを呼び出します。 python -m は、現在の環境にインストールされているバージョンの pip を呼び出していることを確認するために重要です。

重要: pipはPyPIからパッケージをインストールするためにも使用できます。しかし、この場合、.を使用してローカルフォルダからパッケージをインストールするようpipに指示しています。.の代わりにコンピュータ上のプロジェクトディレクトリへのパスを指定することもできます。.はpipに現在の作業ディレクトリを使用するよう指示します。

あなたの環境でpyospackageを探す#

パッケージをインストールしたら、現在の環境で確認できます。venv や conda を使用している場合、pip list は現在アクティブな環境にあるパッケージの一覧を返します。

pyospackage が編集可能モード (-e) でインストールされているため、pip はプロジェクトのコードへのディレクトリパスを表示することに注意してください

$ pip list

➜ pip list
Package                       Version        Editable project location
----------------------------- -------------- --------------------------------------------------------------
...
arrow                         1.2.3
...
...
mamba                         1.1.0
markdown-it-py                2.2.0
MarkupSafe                    2.1.2
matplotlib                    3.7.1
msgpack                       1.0.5
mypy                          1.4.1
nox                           2021.10.1
numpy                         1.24.2
packaging                     23.0
pandas                        1.5.3
pyosPackage                   0.1            /Users/yourusername/path/here/pyosPackage
...
...
...

ステップ 6: 新しいパッケージをテストする#

パッケージをインストールした後、選択したターミナルのコマンドプロンプトで“python”と入力して、アクティブなPython環境でPythonセッションを開始します。パッケージをインストールしたら、選択したターミナルのコマンドプロンプトで "python" と入力し、アクティブなPython環境でPythonセッションを開始します。

これでパッケージをインポートして add_numbers 関数にアクセスできるようになります。

➜ python
Python 3.11.4 | packaged by conda-forge
Type "help", "copyright", "credits" or "license" for more information.
>>> from pyospackage.example import add_numbers
>>> add_numbers(1, 2)
3

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

PyPIに公開せずにコードを共有したい場合は、いつでも構文を使ってGitHubから直接パッケージをインストールできます:

python -m pip install git+https://github.com/user/repo.git@branch_or_tag

GitHubのパッケージをインストール可能にするには、次のようにします:

  1. 新しいGitHubリポジトリを作成する

  2. 上記で作成したプロジェクトディレクトリの内容をGitHubにプッシュします

  3. 最後に、上記のコマンドを使ってGitHubからパッケージをインストールします。 上記のコマンドを使用する際は、user、repo、branch_or_tag を特定の値に置き換えることをお忘れなく。

例えば、以下のようにpyOpenSciリポジトリのmainブランチからpyospackageをインストールします。

python -m pip install git+https://github.com/user/repo.git@branch_or_tag

おめでとうございます！ あなたは最初のPythonパッケージを作成しました#

これで、任意の Python 環境にインストールできる Python パッケージが完成しました。

これからのレッスンでは、あなたは:

Pythonパッケージのディレクトリ構造について#

Pythonコードをインストール可能にするには、以下の要素を含む特定のディレクトリ構造を作成する必要があります:

  • pyproject.toml ファイル。

  • 特定のディレクトリ構造。

  • いくつかのコード。

  • コードディレクトリの __init__.py ファイル。

このレッスンで作成するディレクトリ構造は次のようになります:

pyospackage/  # Your project directory
 └─ pyproject.toml
 └─ src/  # The source (src) directory ensures your tests always run on the installed version of your code
    └── pyospackage/  # Package directory where code lives
        ├── __init__.py
        ├── add_numbers.py
        └── # Add any other .py modules that you want here
インストール可能なパッケージを作成する基本的な手順を示した図です。 右を向いた矢印の箱が4つあります。 ボックスは、あなたのコード、パッケージ構造の作成、pyproject.tomlへのメタデータの追加、およびpip installパッケージを読み込みます。

Python パッケージの基本要素(コード、メタデータ、ファイル構造)が揃ったら、pip install でパッケージをコンピュータ上の任意の Python 環境にインストールできます。#

基本パッケージのディレクトリ構造について#

上記のレイアウトについて、いくつかの点に注目してください:

  1. パッケージのコードは src/packagename ディレクトリにある。インストールされたバージョンのコードでテストを実行していることを確認するため、 src（ source code の略）ディレクトリを使用することをお勧めします。

  2. src ディレクトリの中に pyospackage というパッケージディレクトリがあります。 ディレクトリ名にはパッケージ名を使用します。 これは、インストール後にPythonコードでパッケージをインポートする際の名前になります。

  3. パッケージディレクトリには __init__.py ファイルと Python モジュールがあります。以下に __init__.py ファイルについて詳しく説明します。

  4. pyproject.toml ファイルはパッケージのルートディレクトリにあります。

  5. パッケージのルートディレクトリの名前は、パッケージ名である pyospackage です。これは必須ではありませんが、GitHub / GitLabのリポジトリ名とルートディレクトリ名がパッケージ名と同じであることをよく見かけます。

__init__.py ファイルとは何ですか？#

__init__.py ファイルは Python にディレクトリを Python パッケージとして扱うように指示します。 このように、__init__.py ファイルがあるディレクトリは Python に直接インポートすることができます。 Python に認識させるために __init__.py ファイルにコードを記述する必要はありません; 空であることもあります。

例えば、 __init__.py ファイルを持つ上記のファイル構造の例に従って、次のように実行します:

import pyospackage

pyproject.tomlファイルとは何ですか？#

pyproject.toml ファイルは:

  • プロジェクトのメタデータ (名前、作者、ライセンスなど) を定義します。

  • 依存関係 (依存するパッケージ) を定義します。

  • パッケージのビルド に使用するビルドバックエンドを指定し、設定します。

__init__.py と pyproject.toml ファイルが追加されたら、pipなどのツールを使ってパッケージをビルドし、インストール可能なPythonパッケージとして配布することができます。 pyproject.toml ファイルには、パッケージをインストールするために、以下のようないくつかの基本的な項目が定義されている必要があることに注意してください:

  • 使用したい build-backend を指定します、

  • プロジェクトの name と version を指定する。

pyproject.tomlファイルが重要な理由

pyproject.toml ファイルは setup.py ファイルと setup.cfg ファイルの機能の一部を置き換えます。pyproject.toml がないパッケージを pip でインストールしようとすると、次のエラーが発生します:

GitHub/pyospackage/testme
➜ python -m pip install .
ERROR: Directory '.' is not installable.
Neither 'setup.py' nor 'pyproject.toml' found.

プロジェクトに既に setup.py ファイルがある場合は、Hatch を使って pyproject.toml を自動的に作成できます。

脚注#