Python

Das DuckDB-Python-Paket hat ein eigenes Repository unter duckdb/duckdb-python und verwendet pybind11, um Python-Bindings für DuckDB zu erstellen.

Voraussetzungen

Diese Anleitung setzt voraus:

1. Sie haben eine funktionierende Kopie des Quellcodes des DuckDB-Python-Pakets (einschließlich Git-Submodule und Tags)
2. Sie haben Astral UV in Version >= 0.8.0 installiert
3. Sie führen Befehle vom Wurzelverzeichnis des duckdb-python-Quellbaums aus

Wir setzen bewusst Astral UV für die Verwaltung der Python-Umgebung und der Abhängigkeiten ein. Eine Entwicklungsumgebung mit pip und einer editierbaren Installation ohne Build-Isolation ist möglich; dafür geben wir in dieser Anleitung jedoch keine Hinweise.

Wir verwenden CLion als IDE. Diese Anleitung enthält keine spezifischen Anweisungen für andere IDEs, die Einrichtung sollte aber ähnlich sein.

1. DuckDB-Python-Repository

Beginnen Sie damit, duckdb-python zu forken in ein persönliches Repository, und klonen Sie anschließend Ihren Fork:

git clone --recurse-submodules YOUR_FORK_URL
cd duckdb-python
git remote add upstream https://github.com/duckdb/duckdb-python.git
git fetch --all

Falls Sie bereits ohne Submodule geklont haben:

git submodule update --init --recursive
git remote add upstream https://github.com/duckdb/duckdb-python.git
git fetch --all

Wichtige Hinweise:

• DuckDB ist als Git-Submodul eingebunden und muss initialisiert werden
• Die Ermittlung der DuckDB-Version hängt davon ab, dass Git-Tags lokal verfügbar sind
• Wenn Sie zwischen Branches mit unterschiedlichen Submodul-Refs wechseln, fügen Sie die Git-Hooks hinzu:

git config --local core.hooksPath .githooks/

2. Astral uv installieren

Installieren Sie uv in Version >= 0.8.0.

Einrichten der Entwicklungsumgebung

1. Plattformspezifische Einrichtung

Alle Plattformen:

• Python 3.9+ wird unterstützt
• uv >= 0.8.0 ist erforderlich
• CMake und Ninja (werden über UV installiert)
• C++-Compiler-Toolchain

Linux (Ubuntu 24.04):

sudo apt-get update
sudo apt-get install ccache

macOS:

# Xcode command line tools
xcode-select --install

Windows:

• Visual Studio 2019+ mit C++-Unterstützung
• Git for Windows

2. Abhängigkeiten installieren und bauen

Richten Sie die Entwicklungsumgebung in zwei Schritten ein:

# Install all development dependencies without building the project
uv sync --no-install-project

# Build and install the project without build isolation
uv sync --no-build-isolation

Warum zwei Schritte?

• uv sync führt standardmäßig editierbare Installationen mit scikit-build-core und einem persistenten Build-Verzeichnis aus
• Der Build erfolgt in einer isolierten, kurzlebigen Umgebung, in der die CMake-Pfade auf nicht vorhandene Verzeichnisse zeigen
• Zuerst die Abhängigkeiten zu installieren und anschließend ohne Isolation zu bauen, stellt eine korrekte CMake-Integration sicher

3. Pre-Commit-Hooks aktivieren

Wir führen in der CI eine Reihe von Lint-, Formatierungs- und Typprüfungen aus. Sie können all das manuell ausführen, aber um sich die Arbeit zu erleichtern, können Sie dieselben Prüfungen, die wir in der CI ausführen, mit pre-commit als Git-Hooks installieren. pre-commit ist bereits Teil der Entwicklungsabhängigkeiten:

uvx pre-commit install

Damit laufen alle erforderlichen Prüfungen, bevor ein Commit durchgeht.

Sie können außerdem einen Post-Checkout-Hook installieren, der immer git submodule update --init --recursive ausführt. Wenn Sie zwischen main und einem Bugfix-Branch wechseln, bleibt das duckdb-Submodul so immer korrekt initialisiert:

uvx pre-commit install --hook-type post-checkout

4. Installation prüfen

uv run python -c "import duckdb; print(duckdb.sql('SELECT 42').fetchall())"

Entwicklungsablauf

Tests ausführen

Alle Tests ausführen:

uv run --no-build-isolation pytest ./tests --verbose

Nur schnelle Tests ausführen (schließt das Verzeichnis für langsame Tests aus):

uv run --no-build-isolation pytest ./tests --verbose --ignore=./tests/slow

Testabdeckung

Mit Coverage ausführen (kompiliert die Erweiterung mit --coverage für C++-Coverage):

COVERAGE=1 uv run --no-build-isolation coverage run -m pytest ./tests --verbose

Python-Coverage prüfen:

uv run coverage html -d htmlcov-python
uv run coverage report --format=markdown

C++-Coverage prüfen:

uv run gcovr \
  --gcov-ignore-errors all \
  --root "$PWD" \
  --filter "${PWD}/src/duckdb_py" \
  --exclude '.*/\.cache/.*' \
  --gcov-exclude '.*/\.cache/.*' \
  --gcov-exclude '.*/external/.*' \
  --gcov-exclude '.*/site-packages/.*' \
  --exclude-unreachable-branches \
  --exclude-throw-branches \
  --html --html-details -o coverage-cpp.html \
  build/coverage/src/duckdb_py \
  --print-summary

Wheels bauen

Wheel für Ihr System bauen:

uv build

Für eine bestimmte Python-Version bauen:

uv build -p 3.9

Build-Artefakte bereinigen

uv cache clean
rm -rf build .venv uv.lock

IDE-Einrichtung (CLion)

Für CLion-Nutzer kann das Projekt für das C++-Debugging der Python-Erweiterung konfiguriert werden:

CMake-Profil konfigurieren

Unter Settings → Build, Execution, Deployment → CMake ein Debug-Profil anlegen:

• Name: Debug
• Build type: Debug
• Generator: Ninja
• CMake Options:

  -DCMAKE_PREFIX_PATH=$CMakeProjectDir$/.venv;$CMAKE_PREFIX_PATH

Python-Debug-Konfiguration

Eine Run-Konfiguration vom Typ CMake Application anlegen:

• Name: Python Debug
• Target: All targets
• Executable: ⟨PROJECT_DIR⟩/.venv/bin/python3{:.language-sql .highlight}
• Program arguments: $FilePath$
• Working directory: $ProjectFileDir$

Damit können Sie C++-Breakpoints setzen und Python-Skripte debuggen, die die DuckDB-Erweiterung verwenden.

Debugging

Debugging auf der Kommandozeile

Breakpoints setzen und mit lldb debuggen:

# Example Python script (test.py)
# import duckdb
# print(duckdb.sql("select * from range(1000)").df())

lldb -- .venv/bin/python3 test.py

In lldb:

# Set breakpoint (library loads when imported)
(lldb) br s -n duckdb::DuckDBPyRelation::FetchDF
(lldb) r

Plattformübergreifendes Testen

Sie können den Packaging-Workflow manuell auf Ihrem Fork für jeden Branch ausführen und Plattformen sowie Testsuites über die GitHub-Actions-Weboberfläche wählen.

Fehlerbehebung

Build-Probleme

Fehlende Git-Tags: Wenn Sie DuckDB Python geforkt haben, stellen Sie sicher, dass Sie die Upstream-Tags haben:

git remote add upstream https://github.com/duckdb/duckdb-python.git
git fetch --tags upstream
git push --tags

Plattformspezifische Probleme

Windows-Kompilierung: Stellen Sie sicher, dass Visual Studio 2019+ mit C++-Unterstützung installiert ist.