콘텐츠로 이동

기여 가이드

우리는 당신이 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을 설치할 수 없거나 귀하의 질문이나 기능 요청과 관련이 없다는 것을 알지 않는 한 위의 내용을 항상 포함시키도록 노력하십시오.

풀 요청

Pull Request를 시작하고 생성하는 것은 매우 간단해야 합니다. Pydantic은 정기적으로 출시되므로 며칠 또는 몇 주 안에 개선 사항이 출시되는 것을 확인하실 수 있습니다 🚀.

변경 사항이 사소한 것(오타, 문서 조정 등)이 아닌 한, 끌어오기 요청을 생성하기 전에 변경 사항을 논의할 수 있는 이슈를 생성하세요.

!!! "Pydantic V1이 유지 관리 모드에 있습니다." Pydantic v1은 유지 관리 모드에 있습니다. 이는 버그 수정과 보안 수정만 허용된다는 의미입니다. 새로운 기능은 Pydantic v2를 대상으로 해야 합니다.

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

치아에 맞는 것을 찾고 있다면 다음을 확인하세요. "도움을 원해요" github에 라벨을 붙입니다.

가능한 한 쉽고 빠르게 기여하려면 테스트와 Linting을 로컬에서 실행하는 것이 좋습니다. 운 좋게도 Pydantic은 종속성이 거의 없고 컴파일이 필요하지 않으며 테스트에는 데이터베이스 등에 대한 액세스가 필요하지 않습니다. 이 때문에 테스트 설정 및 실행은 매우 간단해야 합니다.

!!! 팁 요약: make 형식을 사용하여 서식을 수정하고, make를 사용하여 테스트와 린트를 실행하고 문서를 만듭니다. 문서를 작성합니다.

전제조건

다음 전제 조건이 필요합니다.

  • Python 3.8과 3.11 사이의 모든 Python 버전
  • virtualenv 또는 기타 가상 환경 도구
  • 자식
  • 만들다
  • 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...

테스트 및 Linting 실행

테스트와 Linting을 로컬에서 실행하여 모든 것이 예상대로 작동하는지 확인하세요.

# 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으로 작성되었으며 MkDocs용 Material을 사용하여 작성되었습니다. API 문서는 mkdocstring을 사용하여 docstring에서 빌드됩니다.

코드 문서

Pydantic에 기여할 때 모든 코드가 잘 문서화되어 있는지 확인하십시오. 다음은 올바른 형식의 독스트링을 사용하여 문서화되어야 합니다:

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