チュートリアル¶

Pythonパッケージングが初めての方でも、ご心配なく！

Pythonパッケージのリリース手順を簡単に紹介し、すぐに使い始められるよう、手順を説明します。

Mesonプロジェクトの作成¶

始めるには、公開するプロジェクトが必要です。 meson-python は Meson の上に構築されているため、非常にシンプルなMesonプロジェクトを作成します。公開したいMesonプロジェクトが既にある場合は、この手順をスキップできます。

モジュール¶

まず、シンプルなPythonモジュールを作成します。ネイティブモジュールを作成します。それがまさに meson-python が他のPythonビルドバックエンドよりも優れている点です。

our_first_module.c¶

#include <Python.h>

static PyObject* foo(PyObject* self)
{
    return PyUnicode_FromString("bar");
}

static PyMethodDef methods[] = {
    {"foo", (PyCFunction)foo, METH_NOARGS, NULL},
    {NULL, NULL, 0, NULL},
};

static struct PyModuleDef module = {
    PyModuleDef_HEAD_INIT,
    "our_first_module",
    NULL,
    -1,
    methods,
};

PyMODINIT_FUNC PyInit_our_first_module(void)
{
    return PyModule_Create(&module);
}

ここでは、"bar" を返す関数 foo を持つ、our_first_module という小さなモジュールを作成しました。

C APIの使用

PythonのC APIを使用してネイティブモジュールを作成する方法については、以下のリソースをご覧ください。

Mesonビルド記述¶

次に、Mesonビルド記述ファイルを作成する必要があります。これは、Mesonに何をどのようにビルドするかを指示します。

meson.build¶

project('purelib-and-platlib', 'c')

py = import('python').find_installation(pure: false)

py.extension_module(
    'our_first_module',
    'our_first_module.c',
    install: true,
)

ここでは、Mesonの Pythonモジュールを使用して、our_first_module モジュールをビルドします。 extension_module に install: true を渡すことで、インストールするようにします。 meson-python は、Mesonがシステムにインストールするアーティファクトターゲットのみをバイナリ配布に含めます。インストールされていないターゲットを使用すると、ビルド内またはテストで使用するためのターゲットをビルドできます。

Pythonパッケージの設定¶

次に、Pythonパッケージングツールに、パッケージのビルドに使用するビルドバックエンドを指示する必要があります。これは、Pythonパッケージングツールを設定するために使用されるファイルである pyproject.toml ファイルに build-system セクションを作成することで行います。

build-system セクション内では、build-backend と requires の2つのキーを定義する必要があります。 build-backend は、プロジェクトに使用するビルドバックエンドを定義します。 meson-python を使用するには、'mesonpy' に設定します。 requires を使用すると、ビルドプロセスに必要なパッケージを指定できます。 meson-python と、必要となる可能性のある他の依存関係（例： Cython）を含める必要があります。

pyproject.toml¶

[build-system]
build-backend = 'mesonpy'
requires = ['meson-python']

使用するバックエンドを指定したら、パッケージメタデータを定義する必要があります。これは project セクションで行われ、形式は非常にわかりやすいです。

pyproject.toml¶

...

[project]
name = 'our-first-project'
version = '0.0.1'
description = 'Our first Python project, using meson-python!'
readme = 'README.md'
requires-python = '>=3.8'
license = {file = 'LICENSE.txt'}
authors = [
  {name = 'Bowsette Koopa', email = 'bowsette@example.com'},
]

プロジェクトメタデータの宣言

この例では、[project] セクションで使用可能なすべてのフィールドを使用しているわけではありません。詳細な例と詳細については、PyPAのプロジェクトメタデータに関するドキュメントをご覧ください。

プロジェクトのテスト¶

これで有効なPythonプロジェクトができたので、テストしてみましょう。

pip を使用してインストールします。

$ pip install .
$ pip list
...
our-first-project   0.0.1
...

この後、モジュールをインポートして試すことができるはずです。

$ python
>>> import our_first_module
>>> our_first_module.foo()
'bar'

最初のリリースの作成¶

有効なPythonプロジェクトができたので、リリースできます。

プロジェクトをリリースするには、まず配布アーティファクトを生成する必要があります。これらは、Pythonパッケージインストーラーが理解できる標準化された形式のファイルです。アーティファクトには、一般に *sdist* と呼ばれるソース配布と、*wheel* というカスタム形式を使用するバイナリ配布の2種類があります。そのため、一般に *wheel* と呼ばれます。

sdistとwheelの役割は？¶

名前からわかるように、sdistにはプロジェクトのソースコードが含まれており、wheelにはコンパイル済みの [1] バージョンのプロジェクトが含まれており、ファイルシステムにコピーする準備ができています。

プロジェクトでPython拡張モジュールを使用している場合、wheelはプラットフォームとPythonバージョンの両方に固有になります [2]。

wheelの配布は必須ではありませんが、ユーザーエクスペリエンスを大幅に向上させます。特別な理由がない限り、少なくとも最も一般的なシステム用のwheelを配布することを強くお勧めします。システムでwheelが使用できない場合でも、プロジェクトをインストールできますが、sdistからビルドする必要があります。これには、すべてのビルド依存関係を取得し、おそらく高価なビルドプロセスを実行する必要があります。

プロジェクトのビルド¶

続行する前に、これまでに作成した3つのファイル（meson.build、our_first_module.c、pyproject.toml）をGitリポジトリにコミットしていることを確認してください。 meson-python は、Gitが認識しているファイルのみを考慮します。

配布アーティファクトを生成するには、pypa/build ツールを使用します。一時的な仮想環境を作成し、必要なすべてのビルド依存関係をインストールし、meson-python にアーティファクトのビルドを依頼します。

$ pip install build
$ python -m build

ビルドが成功すると、バイナリアーティファクトが dist フォルダーに配置されます。

複数プラットフォーム用のwheelのビルド

プロジェクトに純粋なPython（.py）コードのみが含まれている場合、作成したwheelはすべてのプラットフォームで機能します。これはpure wheelであるためですが、プロジェクトにネイティブコードが含まれている場合、マシンのプラットフォームに固有のものになります。

リリース時には、通常、他の一般的なプラットフォーム（Linux、Windows、macOSなど）の少なくともほとんどをビルドすることをお勧めします。これを簡単にするために、cibuildwheel プロジェクトを確認することをお勧めします。これにより、自動化できます。

ビルドの分離¶

python -m build または pip でビルドすると、デフォルトでビルドの分離が使用されます。つまり、ビルドフロントエンドは、meson-python を呼び出してwheelをビルドする前に、すべてのビルド依存関係を持つ新しい一時仮想環境を作成します。

ビルドの分離を無効にする場合、meson-python とパッケージの他のすべてのビルド依存関係がPython環境に既にインストールされていることを確認する必要があります。仮想環境を使用してビルドする場合、それをアクティブ化する必要があります（そうしないと、meson または他の実行可能ファイルが見つからない場合があります）。

プロジェクトの配布¶

配布アーティファクトができたので、リポジトリにアップロードできます。ほとんどのツールでデフォルトで有効になっているリポジトリである Python Package Index（PyPI）にアップロードします。

このためには、Twine を使用します。

$ pip install twine
$ twine upload dist/*

Test PyPI へのアップロード

実際のインデックスにアップロードしたくない場合は、代わりに Test PyPI にアップロードできます。

$ twine upload -r testpypi dist/*

Test PyPI の使用方法の詳細については、PyPAドキュメントページをご覧ください。

この後、パッケージは PyPI で入手できるようになり、pip でインストールできるようになります。

$ pip install our-first-project