Руководство по внесению вклада

Мы будем рады, если вы внесете свой вклад в Pydantic!

Проблемы¶

Вопросы, пожелания и сообщения об ошибках приветствуются в качестве обсуждений или проблем. Однако, чтобы сообщить об уязвимости безопасности, ознакомьтесь с нашей политикой безопасности.

Чтобы нам было как можно проще вам помочь, включите в свой вопрос вывод следующего вызова:

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

Если вы используете Pydantic до версии 2.0, используйте:

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

Если вы используете Pydantic до версии 1.3 (когда была добавлена version_info()), вручную укажите ОС, версию 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.

Чтобы сделать участие максимально простым и быстрым, вам нужно запускать тесты и анализировать локально. К счастью, Pydantic имеет мало зависимостей, не требует компиляции, тестам не нужен доступ к базам данных и т. д. По этой причине настройка и запуск тестов должны быть очень простыми.

!!! кончик tl;dr: используйте make format для исправления форматирования, make для запуска тестов и проверки и создания документации для создания документов.

Предварительные условия¶

Вам потребуются следующие предпосылки:

Любая версия Python между Python 3.8 и 3.11.
virtualenv или другой инструмент виртуальной среды
мерзавец
делать
ДПМ

Установка и настройка¶

Создайте форк репозитория на 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...

Запуск тестов и линтинг¶

Запускайте тесты и анализируйте локально, чтобы убедиться, что все работает как положено.

# 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), убедитесь, что сборка выполнена успешно.

# 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 и создана с использованием Material for MkDocs. Документация API создается на основе строк документации с использованием mkdocstrings.

Документация по коду¶

Сотрудничая с Pydantic, убедитесь, что весь код хорошо документирован. Следующее должно быть задокументировано с использованием правильно отформатированных строк документации:

Модули
Определения классов
Определения функций
Переменные уровня модуля

Pydantic использует строки документации в стиле Google, отформатированные в соответствии с рекомендациями PEP 257. (Дополнительные примеры см. в разделе «Примеры строк документации Python в стиле Google».)

pydocstyle используется для проверки строк документации. Вы можете запустить make format, чтобы проверить строки документации.

Если это конфликт между строками документации в стиле Google и проверкой pydocstyle, следуйте подсказкам по проверке pydocstyle.

Атрибуты класса и аргументы функции должны быть документированы в формате «имя: описание». Если применимо, тип возвращаемого значения должен быть документирован только с описанием. Типы выводятся из сигнатуры.

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'

Вы можете включить пример кода в строки документации. Этот код должен быть полным, автономным и работоспособным. Примеры строк документации проверяются с помощью doctest, поэтому убедитесь, что они верны и полны. Пример см. в FieldInfo.from_annotated_attribute().

!!! note «Атрибуты класса и экземпляра» Атрибуты класса должны быть задокументированы в строке документации класса.

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

Стиль документации¶

В целом документация должна быть написана в дружелюбном и доступном стиле. Его должно быть легко читать и понимать, и он должен быть максимально кратким, но при этом оставаться полным.

Примеры кода приветствуются, но они должны быть короткими и простыми. Однако каждый пример кода должен быть полным, автономным и работоспособным. (Если вы не знаете, как это сделать, обратитесь за помощью!) Мы предпочитаем вывод на печать голым утверждениям, но если вы тестируете что-то, что не имеет полезного вывода на печать, утверждения подходят.

Модульный тест Pydantic проверит все примеры кода в документации, поэтому важно, чтобы они были правильными и полными. При добавлении нового примера кода используйте следующее для тестирования примеров и обновления их форматирования и вывода:

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

Отладка Python и Rust¶

Если вы работаете с pydantic и pydantic-core, вам может оказаться полезным совместная отладка кода Python и Rust. Вот краткое руководство о том, как это сделать. Это руководство выполнено в VSCode, но вы можете использовать аналогичные шаги в других IDE.

Значки¶

У Pydantic есть значок, который вы можете использовать, чтобы показать, что ваш проект использует Pydantic. Вы можете использовать этот значок в своем README.md:

С уценкой¶

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

С реструктурированным текстом¶

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

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

本文总阅读量次