Beitragen¶

Zuerst möchten Sie vielleicht die grundlegenden Wege sehen, um SQLModel zu helfen und Hilfe zu erhalten.

Entwickeln¶

Wenn Sie das sqlmodel Repository bereits geklont haben und tief in den Code eintauchen möchten, finden Sie hier einige Richtlinien, um Ihre Umgebung einzurichten.

Virtuelle Umgebung¶

Folgen Sie den Anweisungen, um eine virtuelle Umgebung für den internen Code von sqlmodel zu erstellen und zu aktivieren.

Abhängigkeiten mit `pip` installieren¶

Nachdem Sie die Umgebung aktiviert haben, installieren Sie die erforderlichen Pakete

$ pip install -r requirements.txt

---> 100%

Dadurch werden alle Abhängigkeiten und Ihr lokales SQLModel in Ihrer lokalen Umgebung installiert.

Lokales SQLModel verwenden¶

Wenn Sie eine Python-Datei erstellen, die SQLModel importiert und verwendet, und diese mit dem Python aus Ihrer lokalen Umgebung ausführen, wird Ihr geklonter lokaler SQLModel-Quellcode verwendet.

Und wenn Sie diesen lokalen SQLModel-Quellcode aktualisieren, wenn Sie diese Python-Datei erneut ausführen, wird die frische Version von SQLModel verwendet, die Sie gerade bearbeitet haben.

Auf diese Weise müssen Sie Ihre lokale Version nicht "installieren", um jede Änderung testen zu können.

"Technische Details"

Dies geschieht nur, wenn Sie mit dieser enthaltenen requirements.txt installieren, anstatt pip install sqlmodel direkt auszuführen.

Das liegt daran, dass in der Datei requirements.txt die lokale Version von SQLModel im "editable"-Modus mit der Option -e markiert ist.

Formatieren¶

Es gibt ein Skript, das Sie ausführen können, um Ihren gesamten Code zu formatieren und zu bereinigen

$ bash scripts/format.sh

Es sortiert auch automatisch alle Ihre Importe.

Tests¶

Es gibt ein Skript, das Sie lokal ausführen können, um den gesamten Code zu testen und HTML-Abdeckungsberichte zu generieren

$ bash scripts/test.sh

Dieser Befehl generiert ein Verzeichnis ./htmlcov/. Wenn Sie die Datei ./htmlcov/index.html in Ihrem Browser öffnen, können Sie interaktiv die Codebereiche untersuchen, die von den Tests abgedeckt werden, und feststellen, ob Bereiche fehlen.

Dokumentation¶

Stellen Sie zunächst sicher, dass Sie Ihre Umgebung wie oben beschrieben eingerichtet haben, wodurch alle Anforderungen installiert werden.

Dokumentation Live¶

Während der lokalen Entwicklung gibt es ein Skript, das die Website erstellt und Änderungen live neu lädt

$ python ./scripts/docs.py live

<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> Start watching changes
<span style="color: green;">[INFO]</span> Start detecting changes

Es wird die Dokumentation unter http://127.0.0.1:8008 bereitstellen.

Auf diese Weise können Sie die Dokumentations-/Quelldateien bearbeiten und die Änderungen live sehen.

Tipp

Alternativ können Sie die gleichen Schritte, die das Skript ausführt, manuell durchführen.

Wechseln Sie in das Dokumentationsverzeichnis unter docs/

$ cd docs/

Führen Sie dann mkdocs in diesem Verzeichnis aus

$ mkdocs serve --dev-addr 8008

Typer CLI (Optional)¶

Die Anweisungen hier zeigen Ihnen, wie Sie das Skript unter ./scripts/docs.py mit dem python-Programm direkt verwenden.

Sie können aber auch Typer CLI verwenden, und Sie erhalten nach der Installation der Vervollständigung Autovervollständigung in Ihrem Terminal für die Befehle.

Wenn Sie Typer CLI installieren, können Sie die Vervollständigung installieren mit

$ typer --install-completion

zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.

Dokumentationsstruktur¶

Die Dokumentation verwendet MkDocs.

Und es gibt zusätzliche Werkzeuge/Skripte unter ./scripts/docs.py.

Tipp

Sie müssen den Code in ./scripts/docs.py nicht sehen, Sie verwenden ihn einfach in der Befehlszeile.

Die gesamte Dokumentation liegt im Markdown-Format im Verzeichnis ./docs vor.

Viele der Tutorials enthalten Codeblöcke.

In den meisten Fällen sind diese Codeblöcke tatsächliche vollständige Anwendungen, die so ausgeführt werden können.

Tatsächlich sind diese Codeblöcke nicht innerhalb von Markdown geschrieben, sondern es handelt sich um Python-Dateien im Verzeichnis ./docs_src/.

Und diese Python-Dateien werden bei der Generierung der Website in die Dokumentation eingefügt/injiziert.

Dokumentation für Tests¶

Die meisten Tests laufen tatsächlich gegen die Beispiel-Quelldateien in der Dokumentation.

Dies hilft sicherzustellen, dass

Die Dokumentation aktuell ist.
Die Dokumentationsbeispiele so ausgeführt werden können, wie sie sind.
Die meisten Funktionen durch die Dokumentation abgedeckt sind, was durch die Testabdeckung gewährleistet wird.