Willkommen zum ersten Beitrag in der Tutorial-Reihe von LETSQL!
In diesem Blogbeitrag weichen wir von unserem üblichen Thema der Datenpipelines ab, um am Beispiel von DataFusion zu demonstrieren, wie man ein Python-Paket mit Poetry erstellt und veröffentlicht.
Harlequin ist ein TUI-Client für SQL-Datenbanken, der für seine einfache und umfassende Unterstützung für SQL-Datenbanken bekannt ist. Es ist ein vielseitiges Tool für Datenexplorations- und Analyse-Workflows. Harlequin bietet einen interaktiven SQL-Editor mit Funktionen wie Autovervollständigung, Syntaxhervorhebung und Abfrageverlauf. Es verfügt außerdem über einen Ergebnis-Viewer, der große Ergebnismengen anzeigen kann. Allerdings verfügte Harlequin vorher nicht über einen DataFusion-Adapter. Zum Glück war es wirklich einfach, eine hinzuzufügen.
In diesem Beitrag demonstrieren wir diese Konzepte, indem wir einen Harlequin-Adapter für DataFusion erstellen. Dabei werden wir auch die wesentlichen Funktionen von Poetry, die Projekteinrichtung und die Schritte zum Veröffentlichen Ihres Pakets auf PyPI behandeln.
Um dieses Handbuch optimal nutzen zu können, sollten Sie über grundlegende Kenntnisse von virtuellen Umgebungen, Python-Paketen und -Modulen sowie Pip verfügen.
Unsere Ziele sind:
Am Ende verfügen Sie über praktische Erfahrung mit Poesie und ein Verständnis für die moderne Python-Paketverwaltung.
Der in diesem Beitrag implementierte Code ist auf GitHub und in PyPI verfügbar.
Harlequin ist eine SQL-IDE, die im Terminal ausgeführt wird. Es bietet eine leistungsstarke und funktionsreiche Alternative zu herkömmlichen Befehlszeilen-Datenbanktools und ist somit vielseitig für Datenexplorations- und Analyse-Workflows geeignet.
Einige wichtige Dinge, die Sie über Harlequin wissen sollten:
DataFusion ist eine schnelle, erweiterbare Abfrage-Engine zum Aufbau hochwertiger datenzentrierter Systeme in Rust unter Verwendung des Apache Arrow-In-Memory-Formats.
DataFusion bietet SQL- und Dataframe-APIs, hervorragende Leistung, integrierte Unterstützung für CSV, Parquet, JSON und Avro, umfangreiche Anpassungsmöglichkeiten und eine großartige Community.
Es verfügt über eine eigene CLI, weitere Informationen finden Sie hier.
Poetry ist ein modernes, funktionsreiches Tool, das das Abhängigkeitsmanagement und die Paketierung für Python-Projekte optimiert und die Entwicklung deterministischer und effizienter macht.
Aus der Dokumentation:
Poetry ist ein Tool für das Abhängigkeitsmanagement und Paketieren in Python. Sie können damit die Bibliotheken deklarieren, von denen Ihr Projekt abhängt, und sie werden für Sie verwaltet (installiert/aktualisiert).
Poetry bietet eine Sperrdatei, um wiederholbare Installationen zu gewährleisten und kann Ihr Projekt für die Verteilung erstellen.
Ein Harlequin-Adapter ist ein Python-Paket, das es Harlequin ermöglicht, mit einem Datenbanksystem zu arbeiten.
Ein Adapter ist ein Python-Paket, das einen Einstiegspunkt in der Gruppe harlequin.adapters deklariert. Dieser Einstiegspunkt sollte auf eine Unterklasse der abstrakten Basisklasse HarlequinAdapter verweisen.
Dadurch kann Harlequin installierte Adapter erkennen und einen ausgewählten Adapter zur Laufzeit instanziieren
Zusätzlich zur HarlequinAdapter-Klasse muss das Paket auch Implementierungen für HarlequinConnection und HarlequinCursor bereitstellen. Eine ausführlichere Beschreibung finden Sie hier
Anleitung.
Der erste Schritt zur Entwicklung eines Harlequin-Adapters besteht darin, ein neues Repo aus der vorhandenen Harlequin-Adapter-Vorlage zu generieren
GitHub-Vorlagen sind Repositories, die als Ausgangspunkt für neue Projekte dienen. Sie stellen vorkonfigurierte Dateien, Strukturen und Einstellungen bereit, die in neue Repositorys kopiert werden, was eine schnelle Projekteinrichtung ohne den Aufwand einer Verzweigung ermöglicht.
Diese Funktion optimiert den Prozess der Erstellung konsistenter, gut strukturierter Projekte basierend auf etablierten Mustern.
Das Harlequin-Adapter-Template enthält eine Poetry.lock-Datei und eine pyproject.toml-Datei sowie etwas Boilerplate-Code zum Definieren der erforderlichen Klassen.
Lassen Sie uns die wesentlichen Dateien untersuchen, die für die Paketverteilung benötigt werden, bevor wir uns mit den Besonderheiten der Codierung befassen.
Die Datei pyproject.toml ist jetzt der Standard für die Konfiguration von Python-Paketen für die Veröffentlichung und andere Tools. Diese TOML-formatierte Datei wurde in PEP 518 und PEP 621 eingeführt und konsolidiert mehrere Konfigurationsdateien in einer. Es verbessert das Abhängigkeitsmanagement, indem es robuster und standardisierter wird.
Poetry verwendet pyproject.toml, um die virtuelle Umgebung des Projekts zu verwalten, Abhängigkeiten aufzulösen und Pakete zu erstellen.
Die pyproject.toml der Vorlage lautet wie folgt:
[tool.poetry]
name = "harlequin-myadapter"
version = "0.1.0"
description = "A Harlequin adapter for <my favorite database>."
authors = ["Ted Conbeer <tconbeer@users.noreply.github.com>"]
license = "MIT"
readme = "README.md"
packages = [
{ include = "harlequin_myadapter", from = "src" },
]
[tool.poetry.plugins."harlequin.adapter"]
my-adapter = "harlequin_myadapter:MyAdapter"
[tool.poetry.dependencies]
python = ">=3.8.1,<4.0"
harlequin = "^1.7"
[tool.poetry.group.dev.dependencies]
ruff = "^0.1.6"
pytest = "^7.4.3"
mypy = "^1.7.0"
pre-commit = "^3.5.0"
importlib_metadata = { version = ">=4.6.0", python = "<3.10.0" }
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
Wie man sehen kann:
Im Abschnitt [tool.poetry] der Datei pyproject.toml definieren Sie die Metadaten für Ihr Python-Paket, wie Name, Version, Beschreibung, Autoren usw.
Im Unterabschnitt [tool.poetry.dependencies] deklarieren Sie die Laufzeitabhängigkeiten, die Ihr Projekt benötigt. Laufende Poesie add Im Unterabschnitt [tool.poetry.dev-dependencies] deklarieren Sie reine Entwicklungsabhängigkeiten, wie Test-Frameworks, Linters usw. Der Abschnitt [build-system] wird zum Speichern von Build-bezogenen Daten verwendet. In diesem Fall gibt es das Build-Backend als „poetry.core.masonry.api“ an. Im engeren Sinne die Kernverantwortung eines Das Repository enthält außerdem eine Datei „poetry.lock“, eine Poetry-spezifische Komponente, die durch Ausführen von „poetry install“ oder „poetry update“ generiert wird. Diese Sperrdatei gibt die genauen Versionen aller Abhängigkeiten und Unterabhängigkeiten für Ihr Projekt an und gewährleistet so reproduzierbare Installationen in verschiedenen Umgebungen. Es ist wichtig, manuelle Änderungen an der Datei „poetry.lock“ zu vermeiden, da dies zu Inkonsistenzen und Installationsproblemen führen kann. Nehmen Sie stattdessen Änderungen an Ihrer pyproject.toml-Datei vor und erlauben Sie Poetry, die Sperrdatei automatisch zu aktualisieren, indem Sie „poetry lock“ ausführen. Installationswarnung von Poetry ::: {.warning} Hier gehen wir davon aus, dass Sie Zugriff auf Poetry haben, indem Sie pipx install poety ausführen Sobald unsere Dateistruktur geklärt ist, beginnen wir mit dem Entwicklungsprozess, indem wir unsere Umgebung einrichten. Da unser Projekt bereits die Dateien „pyproject.toml“ und „poetry.lock“ enthält, können wir unsere Umgebung mit dem Poetry-Shell-Befehl initiieren. Dieser Befehl aktiviert die mit dem aktuellen Poetry-Projekt verknüpfte virtuelle Umgebung und stellt sicher, dass alle nachfolgenden Vorgänge im Abhängigkeitskontext des Projekts erfolgen. Wenn keine virtuelle Umgebung vorhanden ist, erstellt und aktiviert Poetry Shell automatisch eine. Poetry Shell erkennt Ihre aktuelle Shell und startet eine neue Instanz in der virtuellen Umgebung. Da Poetry virtuelle Umgebungen standardmäßig zentralisiert, entfällt mit diesem Befehl das Suchen oder Abrufen des spezifischen Pfads zum Aktivierungsskript. Um zu überprüfen, welche Python-Umgebung derzeit mit Poetry verwendet wird, können Sie die folgenden Befehle verwenden: Dadurch werden alle mit Ihrem Projekt verknüpften virtuellen Umgebungen angezeigt und angegeben, welche derzeit aktiv ist. Verwenden Sie bei aktivierter Umgebung die Poetry-Installation, um die erforderlichen Abhängigkeiten zu installieren. Der Befehl funktioniert wie folgt Um die Einrichtung der Umgebung abzuschließen, müssen wir die Datafusion-Bibliothek zu unseren Abhängigkeiten hinzufügen. Führen Sie den folgenden Befehl aus: Dieser Befehl aktualisiert Ihre pyproject.toml-Datei mit dem Datafusion-Paket und installiert es. Wenn Sie keine Version angeben, wählt Poetry automatisch eine geeignete Version basierend auf den verfügbaren Paketversionen aus. To create a Harlequin Adapter, you need to implement three interfaces defined as abstract classes in the harlequin.adapter module. The first one is the HarlequinAdapter. The second one is the HarlequinConnection, particularly the methods execute and get_catalog. For brevity, we've omitted the implementation of the get_catalog function. You can find the full code in the adapter.py file within our GitHub repository. Finally, a HarlequinCursor implementation must be provided as well: Your adapter must register an entry point in the harlequin.adapters group using the packaging software you use to build your project. An entry point is a mechanism for code to advertise components it provides to be discovered and used by other code. Notice that registering a plugin with Poetry is equivalent to the following pyproject.toml specification for entry points: The template provides a set of pre-configured tests, some of which are applicable to DataFusion while others may not be relevant. One test that's pretty cool checks if the plugin can be discovered, which is crucial for ensuring proper integration: To make sure the tests are passing, run: The run command executes the given command inside the project’s virtualenv. With the tests passing, we're nearly ready to publish our project. Let's enhance our pyproject.toml file to make our package more discoverable and appealing on PyPI. We'll add key metadata including: These additions will help potential users find and understand our package more easily. For reference: We're now ready to build our library and verify its functionality by installing it in a clean virtual environment. Let's start with the build process: This command will create distribution packages (both source and wheel) in the dist directory. The wheel file should have a name like harlequin_datafusion-0.1.1-py3-none-any.whl. This follows the standard naming convention: To test the installation, create a new directory called test_install. Then, set up a fresh virtual environment with the following command: To activate the virtual environment on MacOS or Linux: After running this command, you should see the name of your virtual environment (.venv) prepended to your command prompt, indicating that the virtual environment is now active. To install the wheel file we just built, use pip as follows: Replace /path/to/harlequin_datafusion-0.1.1-py3-none-any.whl with the actual path to the wheel file you want to install. If everything works fined, you should see some dependencies installed, and you should be able to do: Congrats! You have built a Python library. Now it is time to share it with the world. The best practice before publishing to PyPI is to actually publish to the Test Python Package Index (TestPyPI) To publish a package to TestPyPI using Poetry, follow these steps: Create an account at TestPyPI if you haven't already. Generate an API token on your TestPyPI account page. Register the TestPyPI repository with Poetry by running: To publish your package, run: Replace This command uses two key arguments: Replace To publish to the actual Python Package Index (PyPI) instead: Create an account at https://pypi.org/ if you haven't already. Generate an API token on your PyPI account page. Run: The default repository is PyPI, so there's no need to specify it. Is worth noting that Poetry only supports the Legacy Upload API when publishing your project. Manually publishing each time is repetitive and error-prone, so to fix this problem, let us create a GitHub Action to Here are the key steps to publish a Python package to PyPI using GitHub Actions and Poetry: Set up PyPI authentication: You must provide your PyPI credentials (the API token) as GitHub secrets so the GitHub Actions workflow can access them. Name these secrets something like PYPI_TOKEN. Create a GitHub Actions workflow file: In your project's .github/workflows directory, create a new file like publish.yml with the following content: The key is to leverage GitHub Actions to automate the publishing process and use Poetry to manage your package's dependencies and metadata. Poetry is a user-friendly Python package management tool that simplifies project setup and publication. Its intuitive command-line interface streamlines environment management and dependency installation. It supports plugin development, integrates with other tools, and emphasizes testing for robust code. With straightforward commands for building and publishing packages, Poetry makes it easier for developers to share their work with the Python community. At LETSQL, we're committed to contributing to the developer community. We hope this blog post serves as a straightforward guide to developing and publishing Python packages, emphasizing best practices and providing valuable resources. As we continue to refine the adapter, we would like to provide better autocompletion and direct reading from files (parquet, csv) as in the DataFusion-cli. This requires a tighter integration with the Rust library without going through the Python bindings. Your thoughts and feedback are invaluable as we navigate this journey. Share your experiences, questions, or suggestions in the comments below or on our community forum. Let's redefine the boundaries of data science and machine learning integration. Thanks to Dan Lovell and Hussain Sultan for the comments and the thorough review.
Build-Backend dient zum Erstellen von Rädern und SDIST.
Poesie bekommen
Poetry sollte immer in einer dedizierten virtuellen Umgebung installiert werden, um es vom Rest Ihres Systems zu isolieren. Es sollte auf keinen Fall in der Umgebung des Projekts installiert werden, das von Poetry verwaltet werden soll.
:::
Entwickeln in der virtuellen Umgebung
poetry env list --full-path
Nach dem Login kopieren
Alternativ können Sie den vollständigen Pfad nur der aktuellen Umgebung abrufen:
poetry env info -p
Nach dem Login kopieren
poetry add datafusion
Nach dem Login kopieren
Implementing the Interfaces
#| eval: false
#| code-fold: false
#| code-summary: implementation of HarlequinAdapter
class DataFusionAdapter(HarlequinAdapter):
def __init__(self, conn_str: Sequence[str], **options: Any) -> None:
self.conn_str = conn_str
self.options = options
def connect(self) -> DataFusionConnection:
conn = DataFusionConnection(self.conn_str, self.options)
return conn
Nach dem Login kopieren
#| eval: false
#| code-fold: false
#| code-summary: implementation of execution of HarlequinConnection
def execute(self, query: str) -> HarlequinCursor | None:
try:
cur = self.conn.sql(query) # type: ignore
if str(cur.logical_plan()) == "EmptyRelation":
return None
except Exception as e:
raise HarlequinQueryError(
msg=str(e),
title="Harlequin encountered an error while executing your query.",
) from e
else:
if cur is not None:
return DataFusionCursor(cur)
else:
return None
Nach dem Login kopieren
#| eval: false
#| code-fold: false
#| code-summary: implementation of HarlequinCursor
class DataFusionCursor(HarlequinCursor):
def __init__(self, *args: Any, **kwargs: Any) -> None:
self.cur = args[0]
self._limit: int | None = None
def columns(self) -> list[tuple[str, str]]:
return [
(field.name, _mapping.get(field.type, "?")) for field in self.cur.schema()
]
def set_limit(self, limit: int) -> DataFusionCursor:
self._limit = limit
return self
def fetchall(self) -> AutoBackendType:
try:
if self._limit is None:
return self.cur.to_arrow_table()
else:
return self.cur.limit(self._limit).to_arrow_table()
except Exception as e:
raise HarlequinQueryError(
msg=str(e),
title="Harlequin encountered an error while executing your query.",
) from e
Nach dem Login kopieren
Making the plugin discoverable
If you use Poetry, you can define the entry point in your pyproject.toml file:
[tool.poetry.plugins."harlequin.adapter"]
datafusion = "harlequin_datafusion:DataFusionAdapter"
Nach dem Login kopieren
[project.entry-points."harlequin.adapter"]
datafusion = "harlequin_datafusion:DataFusionAdapter"
Nach dem Login kopieren
Testing
#| eval: false
#| code-fold: false
if sys.version_info < (3, 10):
from importlib_metadata import entry_points
else:
from importlib.metadata import entry_points
def test_plugin_discovery() -> None:
PLUGIN_NAME = "datafusion"
eps = entry_points(group="harlequin.adapter")
assert eps[PLUGIN_NAME]
adapter_cls = eps[PLUGIN_NAME].load()
assert issubclass(adapter_cls, HarlequinAdapter)
assert adapter_cls == DataFusionAdapter
Nach dem Login kopieren
poetry run pytest
Nach dem Login kopieren
Building and Publishing to PyPI
classifiers = [
"Development Status :: 3 - Alpha",
"Intended Audience :: Developers",
"Topic :: Software Development :: User Interfaces",
"Topic :: Database :: Database Engines/Servers",
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: Implementation :: CPython"
]
readme = "README.md"
repository = "https://github.com/mesejo/datafusion-adapter"
Nach dem Login kopieren
Building
poetry build
Nach dem Login kopieren
python -m venv .venv
Nach dem Login kopieren
source .venv/bin/activate
Nach dem Login kopieren
pip install /path/to/harlequin_datafusion-0.1.1-py3-none-any.whl
Nach dem Login kopieren
harlequin -a datafusion
Nach dem Login kopieren
Publishing to PyPI
poetry config repositories.test-pypi https://test.pypi.org/legacy/
Nach dem Login kopieren
poetry publish -r testpypi --username __token__ --password <token>
Nach dem Login kopieren
python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple <package-name>
Nach dem Login kopieren
poetry publish --username __token__ --password <token>
Nach dem Login kopieren
Automated Publishing on GitHub release
publish each time we create a release.
name: Build and publish python package
on:
release:
types: [ published ]
jobs:
publish-package:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
python-version: '3.10'
- name: Install Poetry
uses: snok/install-poetry@v1
- run: poetry config pypi-token.pypi "${{ secrets.PYPI_TOKEN }}"
- name: Publish package
run: poetry publish --build --username __token__
Nach dem Login kopieren
Conclusion
To subscribe to our newsletter, visit letsql.com.
Future Work
Acknowledgements
Das obige ist der detaillierte Inhalt vonSo bauen Sie mit Poetry einen neuen Harlequin-Adapter. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!
![[Web-Frontend] Node.js-Schnellstart](https://img.php.cn/upload/course/000/000/067/662b5d34ba7c0227.png)
