Tutorial¶
Wenn Sie neu in der Python-Paketierung sind, machen Sie sich keine Sorgen!
Wir geben Ihnen eine kurze Einführung in die Schritte, die das Veröffentlichen eines Python-Pakets beinhaltet, und führen Sie durch diese, um Ihnen den Einstieg zu erleichtern.
Erstellen eines Meson-Projekts¶
Um zu beginnen, benötigen wir ein zu veröffentlichendes Projekt. Da meson-python auf Meson aufbaut, erstellen wir ein sehr einfaches Meson-Projekt. Möglicherweise haben Sie bereits ein Meson-Projekt, das Sie veröffentlichen möchten. In diesem Fall können Sie diesen Schritt einfach überspringen.
Das Modul¶
Zuerst erstellen wir ein einfaches Python-Modul. Wir entscheiden uns für ein natives Modul, da meson-python hier seine Stärken gegenüber anderen Python-Build-Backends ausspielt.
#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);
}
Hier erstellen wir ein kleines Modul namens our_first_module, das eine Funktion foo hat, die einfach "bar" zurückgibt.
Verwendung der C-API
Wenn Sie Hilfe beim Schreiben eines nativen Moduls mit der C-API von Python benötigen, empfehlen wir Ihnen, die folgenden Ressourcen zu konsultieren.
Die Meson-Build-Beschreibung¶
Nun müssen wir die Meson-Build-Beschreibungsdatei erstellen. Diese Datei teilt Meson mit, was wir bauen möchten und wie wir es tun.
project('purelib-and-platlib', 'c')
py = import('python').find_installation(pure: false)
py.extension_module(
'our_first_module',
'our_first_module.c',
install: true,
)
Hier verwenden wir Mesons Python-Modul, um unser Modul our_first_module zu bauen. Wir stellen sicher, dass es installiert wird, indem wir install: true an extension_module übergeben, da meson-python nur Ziele in die binäre Distribution aufnimmt, die Meson im System installieren würde. Nicht installierte Ziele ermöglichen es Ihnen, Ziele für die Verwendung innerhalb des Builds oder für Tests zu bauen.
Konfigurieren unseres Python-Pakets¶
Nun müssen wir den Python-Paketierungswerkzeugen mitteilen, welchen Build-Backend sie zum Erstellen unseres Pakets verwenden sollen. Dies geschieht durch Erstellen eines Abschnitts build-system in der Datei pyproject.toml, die zur Konfiguration von Python-Paketierungswerkzeugen verwendet wird.
Innerhalb des Abschnitts build-system müssen wir zwei Schlüssel definieren: build-backend und requires. build-backend definiert, welches Build-Backend für das Projekt verwendet werden soll – setzen Sie es auf 'mesonpy', um meson-python zu verwenden. requires ermöglicht es uns, anzugeben, welche Pakete für den Build-Prozess installiert werden müssen. Es sollte meson-python und alle anderen Abhängigkeiten enthalten, die Sie möglicherweise benötigen (z. B. Cython).
[build-system]
build-backend = 'mesonpy'
requires = ['meson-python']
Nachdem wir angegeben haben, welches Backend verwendet werden soll, möchten wir die Paketmetadaten definieren. Dies geschieht im Abschnitt project, und das Format ist ziemlich selbsterklärend.
...
[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'},
]
Deklarieren von Projektmetadaten
Unser Beispiel nutzt nicht alle Felder, die im Abschnitt [project] verfügbar sind. Schauen Sie sich die PyPA-Dokumentation zu Projektmetadaten für weitere Beispiele und Details an.
Testen des Projekts¶
Jetzt sollten wir ein gültiges Python-Projekt haben, also testen wir es.
Wir installieren es mit pip.
$ pip install .
$ pip list
...
our-first-project 0.0.1
...
Danach sollten wir in der Lage sein, unser Modul zu importieren und auszuprobieren.
$ python
>>> import our_first_module
>>> our_first_module.foo()
'bar'
Erstellen Ihrer ersten Veröffentlichung¶
Nachdem wir nun ein gültiges Python-Projekt haben, können wir es veröffentlichen.
Um das Projekt zu veröffentlichen, müssen wir zuerst die Distributionsartefakte generieren. Dies sind Dateien in einem standardisierten Format, das Python-Paketinstallierer verstehen. Es gibt zwei Arten von Artefakten: Source Distributions, die üblicherweise als sdists bezeichnet werden, und Binary Distributions, die ein benutzerdefiniertes Format namens wheel verwenden, daher werden sie allgemein als wheels bezeichnet.
Was sind die Rollen von sdists und wheels?¶
Wie Sie dem Namen vielleicht schon entnommen haben, enthalten sdists den Quellcode des Projekts, und wheels enthalten eine kompilierte [1] Version des Projekts, die bereit zum Kopieren auf das Dateisystem ist.
Wenn Ihr Projekt Python-Erweiterungsmodule verwendet, sind Ihre Wheels spezifisch für die Plattform und die Python-Version [2].
Obwohl die Verteilung von Wheels nicht zwingend erforderlich ist, verbessert sie die Benutzererfahrung erheblich. Sofern Sie keinen Grund dagegen haben, empfehlen wir dringend, Wheels für zumindest die gängigsten Systeme zu verteilen. Wenn keine Wheels für ein System verfügbar sind, kann das Projekt immer noch installiert werden, muss aber aus dem sdist gebaut werden, was das Herunterladen aller Build-Abhängigkeiten und den wahrscheinlich kostspieligen Build-Prozess beinhaltet.
Bauen des Projekts¶
Stellen Sie vorab sicher, dass Sie die bisher erstellten drei Dateien in Ihrem Git-Repository committet haben – meson-python berücksichtigt nur Dateien, die Git kennt.
Um die Distributionsartefakte zu generieren, verwenden wir das Tool pypa/build. Es erstellt eine temporäre virtuelle Umgebung, installiert alle erforderlichen Build-Abhängigkeiten und fordert meson-python auf, die Artefakte zu bauen.
$ pip install build
$ python -m build
Wenn der Build erfolgreich war, finden Sie die binären Artefakte im Ordner dist.
Bauen von Wheels für mehrere Plattformen
Wenn unser Projekt nur reinen Python-Code (.py) enthält, funktioniert das gerade erstellte Wheel auf allen Plattformen, da es ein reines Wheel ist. Wenn das Projekt jedoch nativen Code enthält, ist es spezifisch für die Plattform unseres Computers.
Bei der Veröffentlichung möchten Sie normalerweise für mindestens die meisten anderen gängigeren Plattformen (Linux, Windows, macOS usw.) bauen. Um dies zu erleichtern, empfehlen wir Ihnen, das Projekt cibuildwheel zu prüfen, das die Automatisierung ermöglicht.
Build-Isolation¶
Das Bauen mit python -m build oder mit pip verwendet standardmäßig Build-Isolation. Das heißt, das Build-Frontend erstellt eine neue, temporäre virtuelle Umgebung mit allen Build-Abhängigkeiten, bevor meson-python aufgerufen wird, um ein Wheel zu bauen.
Wenn Sie die Build-Isolation deaktivieren, sind Sie dafür verantwortlich, sicherzustellen, dass meson-python und alle anderen Build-Abhängigkeiten für das Paket bereits in der Python-Umgebung installiert sind. Beachten Sie, dass, wenn Sie eine virtuelle Umgebung zum Erstellen verwenden, diese aktiviert sein muss (andernfalls werden meson oder eine andere ausführbare Datei möglicherweise nicht gefunden).
Verteilen des Projekts¶
Nachdem wir die Distributionsartefakte haben, können wir sie in einem Repository hochladen. Wir laden sie auf das Python Package Index (PyPI) hoch, ein Repository, das in den meisten Tools standardmäßig aktiviert ist.
Dafür verwenden wir Twine.
$ pip install twine
$ twine upload dist/*
Upload auf Test PyPI
Wenn Sie nicht auf den echten Index hochladen möchten, können Sie stattdessen auf Test PyPI hochladen.
$ twine upload -r testpypi dist/*
Mehr darüber, wie Sie Test PyPI verwenden, finden Sie auf dessen PyPA-Dokumentationsseite.
Danach sollte Ihr Paket auf PyPI verfügbar und mit pip installierbar sein.
$ pip install our-first-project