Aller au contenu

Guide de contribution

Nous serions ravis que vous contribuiez à Pydantic!

Problèmes

Les questions, demandes de fonctionnalités et rapports de bogues sont tous les bienvenus en tant que discussions ou problèmes. Cependant, pour signaler une faille de sécurité, veuillez consulter notre politique de sécurité.

Pour que nous puissions vous aider aussi simplement que possible, veuillez inclure le résultat de l'appel suivant dans votre problème:

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

Si vous utilisez Pydantic avant la version 2.0, veuillez utiliser:

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

Si vous utilisez Pydantic avant la v1.3 (lorsque version_info() a été ajouté), veuillez inclure manuellement le système d'exploitation, la version Python et la version pydantic.

Veuillez essayer de toujours inclure ce qui précède, sauf si vous ne parvenez pas à installer Pydantic ou si vous savez que cela n'est pas pertinent par rapport à votre question ou demande de fonctionnalité.

Demandes de tirage

Il devrait être extrêmement simple de commencer et de créer une Pull Request. Pydantic est publié régulièrement, vous devriez donc voir vos améliorations sortir dans quelques jours ou semaines 🚀.

À moins que votre modification ne soit triviale (faute de frappe, modification de la documentation, etc.), veuillez créer un problème pour discuter de la modification avant de créer une pull request.

!!! note "Pydantic V1 est en mode maintenance" Pydantic v1 est en mode maintenance, ce qui signifie que seules les corrections de bogues et les correctifs de sécurité seront acceptés. Les nouvelles fonctionnalités devraient être ciblées sur Pydantic v2.

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

Si vous cherchez quelque chose à vous mettre sous la dent, consultez le "aide recherchée" étiquette sur github.

Pour rendre la contribution aussi simple et rapide que possible, vous souhaiterez exécuter des tests et du peluchage localement. Heureusement, Pydantic a peu de dépendances, ne nécessite pas de compilation et les tests n'ont pas besoin d'accéder aux bases de données, etc. Pour cette raison, la configuration et l'exécution des tests devraient être très simples.

!!! conseil tl;dr: utilisez make format pour corriger le formatage, make pour exécuter des tests, du peluchage et créer des documents pour créer les documents.

Conditions préalables

Vous aurez besoin des prérequis suivants:

  • Toute version de Python entre Python 3.8 et 3.11
  • virtualenv ou autre outil d'environnement virtuel
  • git
  • faire
  • MPD

Installation et configuration

Forkez le référentiel sur GitHub et clonez votre fork localement.

# 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

Découvrez une nouvelle succursale et apportez vos modifications

Créez une nouvelle branche pour vos modifications.

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

Exécuter des tests et du peluchage

Exécutez des tests et du peluchage localement pour vous assurer que tout fonctionne comme prévu.

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

Construire la documentation

Si vous avez apporté des modifications à la documentation (y compris des modifications aux signatures de fonctions, aux définitions de classe ou aux docstrings qui apparaîtront dans la documentation de l'API), assurez-vous qu'elle se compile correctement.

# 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

Validez et poussez vos modifications

Validez vos modifications, transférez votre branche vers GitHub et créez une pull request.

Veuillez suivre le modèle de demande de tirage et remplir autant d'informations que possible. Créez un lien vers tous les problèmes pertinents et incluez une description de vos modifications.

Lorsque votre demande d'extraction est prête à être examinée, ajoutez un commentaire avec le message «veuillez réviser» et nous y jetterons un œil dès que possible.

Style de code et exigences

TOUS

Style de documentation

La documentation est écrite en Markdown et construite à l'aide de Material for MkDocs. La documentation de l'API est construite à partir de docstrings à l'aide de mkdocstrings.

Documentation des codes

Lorsque vous contribuez à Pydantic, assurez-vous que tout le code est bien documenté. Les éléments suivants doivent être documentés à l'aide de docstrings correctement formatés:

  • Modules
  • Définitions de classe
  • Définitions des fonctions
  • Variables au niveau du module

Pydantic utilise des docstrings de style Google formatés selon les directives PEP 257. (Voir Exemple de Docstrings Python de style Google pour d'autres exemples.)

pydocstyle est utilisé pour le peluchage des docstrings. Vous pouvez exécuter make format pour vérifier vos docstrings.

En cas de conflit entre les docstrings de style Google et le linting pydocstyle, suivez les conseils de linting pydocstyle.

Les attributs de classe et les arguments de fonction doivent être documentés au format « nom : description ». Le cas échéant, un type de retour doit être documenté avec juste une description. Les types sont déduits de la 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'

Vous pouvez inclure un exemple de code dans les docstrings. Ce code doit être complet, autonome et exécutable. Les exemples de Docstring sont testés à l'aide de doctest, alors assurez-vous qu'ils sont corrects et complets. Voir FieldInfo.from_annotated_attribute() pour un exemple.

!!! note «Attributs de classe et d'instance» Les attributs de classe doivent être documentés dans la docstring de classe.

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

Style de documentation

En général, la documentation doit être rédigée dans un style convivial et accessible. Il doit être facile à lire et à comprendre, et doit être aussi concis que possible tout en restant complet.

Les exemples de code sont encouragés, mais doivent être courts et simples. Cependant, chaque exemple de code doit être complet, autonome et exécutable. (Si vous ne savez pas comment procéder, demandez de l'aide!) Nous préférons la sortie imprimée aux assertions nues, mais si vous testez quelque chose qui n'a pas de sortie imprimée utile, les assertions conviennent.

Le test unitaire de Pydantic testera tous les exemples de code de la documentation, il est donc important qu'ils soient corrects et complets. Lorsque vous ajoutez un nouvel exemple de code, utilisez ce qui suit pour tester les exemples et mettre à jour leur formatage et leur sortie:

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

Débogage de Python et Rust

Si vous travaillez avec pydantic et pydantic-core, vous trouverez peut-être utile de déboguer le code Python et Rust ensemble. Voici un guide rapide sur la façon de procéder. Ce didacticiel est réalisé dans VSCode, mais vous pouvez utiliser des étapes similaires dans d'autres IDE.

Insignes

Pydantic v1 Pydantic v2

Pydantic dispose d'un badge que vous pouvez utiliser pour montrer que votre projet utilise Pydantic. Vous pouvez utiliser ce badge dans votre README.md:

Avec démarque

[![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)

Avec 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

Avec 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>
本文总阅读量次