Bijdragen

Wij willen graag dat u bijdraagt aan Pydantic!

Problemen¶

Vragen, functieverzoeken en bugrapporten zijn allemaal welkom als discussie of probleem. Als u echter een beveiligingsprobleem wilt melden, raadpleeg dan ons beveiligingsbeleid.

Om het voor ons zo eenvoudig mogelijk te maken om u te helpen, verzoeken wij u de uitkomst van de volgende oproep in uw probleem op te nemen:

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

Als u Pydantic vóór v2.0 gebruikt, gebruik dan:

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

Als u Pydantic vóór v1.3 gebruikt (toen versie_info() werd toegevoegd), voer dan handmatig het besturingssysteem, de Python-versie en de pydantic-versie in.

Probeer altijd het bovenstaande op te nemen, tenzij u Pydantic niet kunt installeren of weet dat dit niet relevant is voor uw vraag of functieverzoek.

Pull-verzoeken¶

Het zou uiterst eenvoudig moeten zijn om aan de slag te gaan en een Pull Request aan te maken. Pydantic wordt regelmatig uitgebracht, dus u zou uw verbeteringen binnen een paar dagen of weken moeten zien verschijnen 🚀.

Tenzij uw wijziging triviaal is (typefout, aanpassing van documenten enz.), dient u een probleem aan te maken om de wijziging te bespreken voordat u een pull-verzoek maakt.

!!! opmerking "Pydantic V1 bevindt zich in onderhoudsmodus" Pydantic v1 bevindt zich in onderhoudsmodus, wat betekent dat alleen bugfixes en beveiligingsoplossingen worden geaccepteerd. Nieuwe functies moeten gericht zijn op Pydantic v2.

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

Als je op zoek bent naar iets om je tanden in te zetten, kijk dan eens naar de "hulp gezocht" label op github.

Om het bijdragen zo gemakkelijk en snel mogelijk te maken, wilt u lokaal testen en linten uitvoeren. Gelukkig heeft Pydantic weinig afhankelijkheden, hoeft het niet te worden gecompileerd en hebben tests geen toegang tot databases nodig, enz. Hierdoor zou het opzetten en uitvoeren van de tests heel eenvoudig moeten zijn.

!!! tip tl;dr: gebruik make-formaat om de opmaak te corrigeren, make om tests uit te voeren en linting uit te voeren en documenten te maken om de documenten op te bouwen.

Vereisten¶

Je hebt de volgende vereisten nodig:

Elke Python-versie tussen Python 3.8 en 3.11
virtualenv of een ander hulpmiddel voor een virtuele omgeving
git
maken
PDM

Installatie en configuratie¶

Fork de repository op GitHub en kloon uw fork lokaal.

# 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

Bekijk een nieuw filiaal en breng uw wijzigingen aan¶

Maak een nieuwe branch voor uw wijzigingen.

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

Voer tests uit en pluisjes¶

Voer lokaal testen en pluizen uit om er zeker van te zijn dat alles naar verwachting werkt.

# 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.

Bouw documentatie¶

Als u wijzigingen in de documentatie heeft aangebracht (inclusief wijzigingen in functiehandtekeningen, klassendefinities of docstrings die in de API-documentatie zullen verschijnen), zorg er dan voor dat deze succesvol wordt opgebouwd.

# 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

Commiteer en push uw veranderingen¶

Voer uw wijzigingen door, push uw branch naar GitHub en maak een pull-aanvraag.

Volg het pull-aanvraagsjabloon en vul zoveel mogelijk informatie in. Link naar relevante kwesties en voeg een beschrijving van uw wijzigingen toe.

Wanneer uw pull-aanvraag gereed is voor beoordeling, voegt u een opmerking toe met het bericht 'Beoordeel alstublieft'. We zullen er dan zo snel mogelijk naar kijken.

Codestijl en vereisten¶

ALLE

Documentatiestijl¶

Documentatie is geschreven in Markdown en gebouwd met behulp van Material for MkDocs. API-documentatie is opgebouwd uit docstrings met behulp van mkdocstrings.

Codedocumentatie¶

Wanneer u bijdraagt aan Pydantic, zorg er dan voor dat alle code goed gedocumenteerd is. Het volgende moet worden gedocumenteerd met correct opgemaakte docstrings:

Modules
Class definitions
Function definitions
Module-level variables

Pydantic uses Google-style docstrings formatted according to PEP 257 guidelines. (See Example Google Style Python Docstrings for further examples.)

pydocstyle is used for linting docstrings. You can run make format to check your docstrings.

Where this is a conflict between Google-style docstrings and pydocstyle linting, follow the pydocstyle linting hints.

Class attributes and function arguments should be documented in the format "name: description." When applicable, a return type should be documented with just a description. Types are inferred from the signature.

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'

You may include example code in docstrings. This code should be complete, self-contained, and runnable. Docstring examples are tested using doctest, so make sure they are correct and complete. See FieldInfo.from_annotated_attribute() for an example.

!!! note "Class and instance attributes" Class attributes should be documented in the class docstring.

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

Documentation Style¶

In general, documentation should be written in a friendly, approachable style. It should be easy to read and understand, and should be as concise as possible while still being complete.

Code examples are encouraged, but should be kept short and simple. However, every code example should be complete, self-contained, and runnable. (If you're not sure how to do this, ask for help!) We prefer print output to naked asserts, but if you're testing something that doesn't have a useful print output, asserts are fine.

Pydantic's unit test will test all code examples in the documentation, so it's important that they are correct and complete. When adding a new code example, use the following to test examples and update their formatting and output:

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

Debugging Python and Rust¶

If you're working with pydantic and pydantic-core, you might find it helpful to debug Python and Rust code together. Here's a quick guide on how to do that. This tutorial is done in VSCode, but you can use similar steps in other IDEs.

Badges¶

Pydantic has a badge that you can use to show that your project uses Pydantic. You can use this badge in your README.md:

With 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)

With 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

With 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>

本文总阅读量次