コンテンツにスキップ

貢献ガイド

ぜひ Pydantic に貢献してください。

問題

質問、機能リクエスト、バグレポートはすべて、ディスカッションまたは問題として歓迎されます。 ただし、セキュリティの脆弱性を報告するには、セキュリティ ポリシーを参照してください。

できるだけ簡単にサポートできるよう、次の呼び出しの出力を問題に含めてください。

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

v2.0 より前の Pydantic を使用している場合は、以下を使用してください。

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

v1.3 (version_info() が追加されたとき) より前の Pydantic を使用している場合は、OS、Python バージョン、および pydantic バージョンを手動で含めてください。

Pydantic をインストールできない場合、または質問や機能リクエストに関連しないことがわかっている場合を除き、常に上記を含めるようにしてください。

プルリクエスト

開始してプル リクエストを作成するのは非常に簡単です。 Pydantic は定期的にリリースされるため、数日または数週間以内に改良版がリリースされるはずです 🚀。

変更が些細なもの (タイプミス、ドキュメントの微調整など) でない限り、プル リクエストを作成する前に、変更について議論するためのイシューを作成してください。

!!! note 「Pydantic V1 はメンテナンス モードです」 Pydantic v1 はメンテナンス モードです。つまり、バグ修正とセキュリティ修正のみが受け入れられます。新機能は Pydantic v2 をターゲットにする必要があります。

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

興味をそそられるものを探しているなら、ぜひチェックしてください。 "従業員求む" github のラベル。

できるだけ簡単かつ迅速に貢献するには、テストと lint をローカルで実行する必要があります。幸いなことに、Pydantic には依存関係がほとんどなく、コンパイルの必要がなく、テストでデータベースなどにアクセスする必要もありません。このため、テストのセットアップと実行は非常に簡単です。

!!!ヒント tl;dr: make format を使用して書式設定を修正し、make を使用してテストと lint を実行し、ドキュメントを作成します ドキュメントを構築します。

前提条件

次の前提条件が必要です。

  • Python 3.8 から 3.11 までの任意の Python バージョン
  • virtualenv またはその他の仮想環境ツール
  • git
  • 作る
  • PDM

インストールとセットアップ

GitHub 上のリポジトリをフォークし、ローカルにフォークのクローンを作成します。

# 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

新しいブランチをチェックアウトして変更を加える

変更内容に応じて新しいブランチを作成します。

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

テストとリンティングを実行する

テストと lint をローカルで実行して、すべてが期待どおりに動作していることを確認します。

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

ビルドドキュメント

ドキュメントに変更を加えた場合 (API ドキュメントに表示される関数シグネチャ、クラス定義、または docstring の変更を含む) が正常にビルドされることを確認してください。

# 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

変更をコミットしてプッシュする

変更をコミットし、ブランチを GitHub にプッシュし、プル リクエストを作成します。

プル リクエスト テンプレートに従って、できるだけ多くの情報を入力してください。関連する問題へのリンクと変更の説明を含めます。

プル リクエストをレビューする準備ができたら、「レビューしてください」というメッセージを含むコメントを追加してください。できるだけ早く確認します。

コードのスタイルと要件

全て

ドキュメントのスタイル

ドキュメントは Markdown で書かれ、MkDocs 用のマテリアルを使用して構築されます。 API ドキュメントは、mkdocstrings を使用して docstring から構築されます。

コードのドキュメント

Pydantic に貢献する場合は、すべてのコードが適切に文書化されていることを確認してください。以下は、適切にフォーマットされた docstring を使用して文書化する必要があります。

  • モジュール
  • 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.

バッジ

Pydantic v1 Pydantic v2

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