Zum Inhalt

Beitrag leisten

Wir würden uns freuen, wenn Sie zu Pydantic beitragen!

Probleme

Fragen, Funktionswünsche und Fehlerberichte sind als Diskussionen oder Probleme willkommen. Um jedoch eine Sicherheitslücke zu melden, lesen Sie bitte unsere Sicherheitsrichtlinie.

Um es uns so einfach wie möglich zu machen, Ihnen zu helfen, fügen Sie bitte das Ergebnis des folgenden Anrufs in Ihr Problem ein:

python -c "import pydantic.version; print(pydantic.version.version_info())"

Wenn Sie Pydantic vor Version 2.0 verwenden, verwenden Sie bitte:

python -c "import pydantic.utils; print(pydantic.utils.version_info())"

Wenn Sie Pydantic vor Version 1.3 verwenden (als version_info() hinzugefügt wurde), geben Sie bitte manuell das Betriebssystem, die Python-Version und die Pydantic-Version an.

Bitte versuchen Sie immer, die oben genannten Punkte anzugeben, es sei denn, Sie können Pydantic nicht installieren oder wissen, dass es für Ihre Frage oder Funktionsanfrage nicht relevant ist.

Pull-Anfragen

Der Einstieg und die Erstellung einer Pull-Anfrage sollte äußerst einfach sein. Pydantic wird regelmäßig veröffentlicht, sodass Sie die Veröffentlichung Ihrer Verbesserungen innerhalb weniger Tage oder Wochen sehen sollten 🚀.

Sofern Ihre Änderung nicht trivial ist (Tippfehler, Dokumentoptimierung usw.), erstellen Sie bitte ein Problem, um die Änderung zu besprechen, bevor Sie eine Pull-Anfrage erstellen.

!!! Hinweis „Pydantic V1 befindet sich im Wartungsmodus“ Pydantic v1 befindet sich im Wartungsmodus, was bedeutet, dass nur Fehlerkorrekturen und Sicherheitskorrekturen akzeptiert werden. Neue Funktionen sollten auf Pydantic v2 ausgerichtet sein.

To submit a fix to Pydantic v1, use the `1.10.X-fixes` branch.

Wenn Sie auf der Suche nach etwas sind, in das Sie sich hineinbeißen können, schauen Sie sich das an "Stellenangebote" Etikett auf Github.

Um das Mitwirken so einfach und schnell wie möglich zu gestalten, sollten Sie Tests und Linting lokal ausführen. Glücklicherweise weist Pydantic nur wenige Abhängigkeiten auf, erfordert keine Kompilierung und Tests benötigen keinen Zugriff auf Datenbanken usw. Aus diesem Grund sollte das Einrichten und Ausführen der Tests sehr einfach sein.

!!! Tipp tl;dr: Verwenden Sie make format, um die Formatierung zu korrigieren, make, um Tests und Linting auszuführen und Dokumente zu erstellen um die Dokumente zu erstellen.

Voraussetzungen

Sie benötigen folgende Voraussetzungen:

  • Jede Python-Version zwischen Python 3.8 und 3.11
  • virtualenv oder ein anderes Tool für virtuelle Umgebungen
  • Idiot
  • machen
  • PDM

Installation und Einrichtung

Forken Sie das Repository auf GitHub und klonen Sie Ihren Fork lokal.

# Clone your fork and cd into the repo directory
git clone git@github.com:<your username>/pydantic.git
cd pydantic

# Install PDM and pre-commit
# We use pipx here, for other options see:
# https://pdm.fming.dev/latest/#installation
# https://pre-commit.com/#install
# To get pipx itself:
# https://pypa.github.io/pipx/
pipx install pdm
pipx install pre-commit

# Install pydantic, dependencies, test dependencies and doc dependencies
make install

Schauen Sie sich einen neuen Zweig an und nehmen Sie Ihre Änderungen vor

Erstellen Sie einen neuen Zweig für Ihre Änderungen.

# Checkout a new branch and make your changes
git checkout -b my-new-feature-branch
# Make your changes...

Führen Sie Tests und Flusen durch

Führen Sie lokal Tests und Linting durch, um sicherzustellen, dass alles wie erwartet funktioniert.

# Run automated code formatting and linting
make format
# Pydantic uses ruff, an awesome Python linter written in rust
# https://github.com/astral-sh/ruff

# Run tests and linting
make
# There are a few sub-commands in Makefile like `test`, `testcov` and `lint`
# which you might want to use, but generally just `make` should be all you need.
# You can run `make help` to see more options.

Erstellen Sie eine Dokumentation

Wenn Sie Änderungen an der Dokumentation vorgenommen haben (einschließlich Änderungen an Funktionssignaturen, Klassendefinitionen oder Dokumentzeichenfolgen, die in der API-Dokumentation angezeigt werden), stellen Sie sicher, dass sie erfolgreich erstellt wird.

# Build documentation
make docs
# If you have changed the documentation, make sure it builds successfully.
# You can also use `pdm run mkdocs serve` to serve the documentation at localhost:8000

Übernehmen Sie Ihre Änderungen und pushen Sie sie

Übernehmen Sie Ihre Änderungen, übertragen Sie Ihren Zweig auf GitHub und erstellen Sie eine Pull-Anfrage.

Bitte folgen Sie der Pull-Request-Vorlage und geben Sie so viele Informationen wie möglich ein. Verlinken Sie alle relevanten Probleme und fügen Sie eine Beschreibung Ihrer Änderungen bei.

Wenn Ihre Pull-Anfrage zur Überprüfung bereit ist, fügen Sie einen Kommentar mit der Nachricht „Bitte überprüfen“ hinzu und wir werden uns so schnell wie möglich umsehen.

Codestil und Anforderungen

ALLE

Dokumentationsstil

Die Dokumentation wird in Markdown geschrieben und mit Material für MkDocs erstellt. Die API-Dokumentation wird mithilfe von mkdocstrings aus Dokumentzeichenfolgen erstellt.

Codedokumentation

Wenn Sie zu Pydantic beitragen, stellen Sie bitte sicher, dass der gesamte Code gut dokumentiert ist. Folgendes sollte mithilfe ordnungsgemäß formatierter Dokumentzeichenfolgen dokumentiert werden:

  • Module
  • Klassendefinitionen
  • Funktionsdefinitionen
  • Variablen auf Modulebene

Pydantic verwendet Docstrings im Google-Stil, die gemäß den PEP 257-Richtlinien formatiert sind. (Weitere Beispiele finden Sie unter Beispiele für Python-Docstrings im Google-Stil.)

pydocstyle wird zum Flusen von Dokumentzeichenfolgen verwendet. Sie können make format ausführen, um Ihre Dokumentzeichenfolgen zu überprüfen.

Wenn es sich um einen Konflikt zwischen Docstrings im Google-Stil und Linting im Pydoc-Stil handelt, folgen Sie den Linting-Hinweisen im Pydoc-Stil.

Klassenattribute und Funktionsargumente sollten im Format „Name: Beschreibung“ dokumentiert werden. Gegebenenfalls sollte ein Rückgabetyp nur mit einer Beschreibung dokumentiert werden. Typen werden aus der Signatur abgeleitet.

class Foo:
    """A class docstring.

    Attributes:
        bar: A description of bar. Defaults to "bar".
    """

    bar: str = 'bar'


def bar(self, baz: int) -> str:
    """A function docstring.

    Args:
        baz: A description of `baz`.

    Returns:
        A description of the return value.
    """

    return 'bar'

Sie können Beispielcode in Dokumentzeichenfolgen einfügen. Dieser Code sollte vollständig, in sich geschlossen und ausführbar sein. Docstring-Beispiele werden mit doctest getestet. Stellen Sie daher sicher, dass sie korrekt und vollständig sind. Ein Beispiel finden Sie unter FieldInfo.from_annotated_attribute().

!!! Hinweis „Klassen- und Instanzattribute“ Klassenattribute sollten im Klassendokumentstring dokumentiert werden.

Instance attributes should be documented as "Args" in the `__init__` docstring.

Dokumentationsstil

Generell sollte die Dokumentation in einem freundlichen, zugänglichen Stil verfasst sein. Es sollte leicht lesbar und verständlich sowie möglichst prägnant und dennoch vollständig sein.

Codebeispiele sind erwünscht, sollten jedoch kurz und einfach gehalten werden. Allerdings sollte jedes Codebeispiel vollständig, in sich geschlossen und ausführbar sein. (Wenn Sie nicht sicher sind, wie das geht, bitten Sie um Hilfe!) Wir bevorzugen die Druckausgabe gegenüber bloßen Asserts, aber wenn Sie etwas testen, das keine nützliche Druckausgabe hat, sind Asserts in Ordnung.

Der Komponententest von Pydantic testet alle Codebeispiele in der Dokumentation. Daher ist es wichtig, dass sie korrekt und vollständig sind. Wenn Sie ein neues Codebeispiel hinzufügen, verwenden Sie Folgendes, um Beispiele zu testen und ihre Formatierung und Ausgabe zu aktualisieren:

# Run tests and update code examples
pytest tests/test_docs.py --update-examples

Debuggen von Python und Rust

Wenn Sie mit pydantic und pydantic-core arbeiten, kann es hilfreich sein, Python- und Rust-Code gemeinsam zu debuggen. Hier finden Sie eine Kurzanleitung dazu. Dieses Tutorial wird in VSCode durchgeführt, Sie können jedoch ähnliche Schritte in anderen IDEs verwenden.

Abzeichen

Pydantic v1 Pydantic v2

Pydantic verfügt über ein Abzeichen, mit dem Sie zeigen können, dass Ihr Projekt Pydantic verwendet. Sie können dieses Abzeichen in Ihrer README.md verwenden:

Mit Markdown

[![Pydantic v1](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v1.json)](https://pydantic.dev)

[![Pydantic v2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json)](https://pydantic.dev)

Mit reStructuredText

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v1.json
    :target: https://pydantic.dev
    :alt: Pydantic

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json
    :target: https://pydantic.dev
    :alt: Pydantic

Mit HTML

<a href="https://pydantic.dev"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v1.json" alt="Pydantic Version 1" style="max-width:100%;"></a>

<a href="https://pydantic.dev"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json" alt="Pydantic Version 2" style="max-width:100%;"></a>
本文总阅读量次