Examples¶

While the Configuration documentation contains all available options in detail, this page shows them in conjunction to provide different examples on how to display pydantic models and settings.

Default configuration¶

This example shows the default out-of-the-box configuration of autodoc_pydantic. In contrast, it also shows how standard sphinx autodoc displays the same example code.

pydantic settings target.example_setting.ExampleSettings¶

Document your project settings very conveniently. Applies like wise to pydantic models.

Show JSON schema

{
   "title": "ExampleSettings",
   "description": "Document your project settings very conveniently. Applies like wise\nto pydantic models.",
   "type": "object",
   "properties": {
      "field_plain_with_validator": {
         "title": "Field Plain With Validator",
         "default": 100,
         "env_names": [
            "foo_field_plain_with_validator"
         ],
         "type": "integer"
      },
      "BarFoo": {
         "title": "Barfoo",
         "default": "FooBar",
         "env": "BarFoo",
         "env_names": [
            "barfoo"
         ],
         "type": "string"
      },
      "field_with_constraints_and_description": {
         "title": "Field With Constraints And Description",
         "description": "Shows constraints within doc string.",
         "default": 5,
         "minimum": 0,
         "maximum": 100,
         "env_names": [
            "foo_field_with_constraints_and_description"
         ],
         "type": "integer"
      }
   },
   "additionalProperties": false
}

Config

allow_mutation: bool = True
env_prefix: str = foo_

Fields

field_plain_with_validator (int)
field_with_validator_and_alias (str)
field_with_constraints_and_description (int)

Validators

check_max_length_ten » field_with_validator_and_alias
check_max_length_ten » field_plain_with_validator

field field_plain_with_validator: int = 100¶

Show standard field with type annotation.

Validated by

check_max_length_ten

field field_with_constraints_and_description: int = 5¶

Shows constraints within doc string.

Constraints

minimum = 0
maximum = 100

field field_with_validator_and_alias: str = 'FooBar' (alias 'BarFoo')¶

Shows corresponding validator with link/anchor.

Constraints

env = BarFoo

Validated by

check_max_length_ten

validator check_max_length_ten » field_with_validator_and_alias, field_plain_with_validator¶: Show corresponding field with link/anchor.

class target.example_setting.ExampleSettings(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field_plain_with_validator: int = 100, BarFoo: str = 'FooBar', field_with_constraints_and_description: target.example_setting.ConstrainedIntValue = 5)

Document your project settings very conveniently. Applies like wise to pydantic models.

classmethod check_max_length_ten(v): Show corresponding field with link/anchor.

attribute field_plain_with_validator: int: Show standard field with type annotation.

attribute field_with_constraints_and_description: int

attribute field_with_validator_and_alias: str: Shows corresponding validator with link/anchor.

from pydantic import BaseSettings, validator, Field


class ExampleSettings(BaseSettings):
    """Document your project settings very conveniently. Applies like wise
    to pydantic models.

    """

    field_plain_with_validator: int = 100
    """Show standard field with type annotation."""

    field_with_validator_and_alias: str = Field("FooBar",
                                                alias="BarFoo",
                                                env="BarFoo")
    """Shows corresponding validator with link/anchor."""

    field_with_constraints_and_description: int = Field(
        default=5,
        ge=0,
        le=100,
        description="Shows constraints within doc string."
    )

    @validator("field_with_validator_and_alias", "field_plain_with_validator")
    def check_max_length_ten(cls, v):
        """Show corresponding field with link/anchor.

        """

        if len(v) >= 10:
            raise ValueError("No more than 10 characters allowed")

        return v

    class Config:
        env_prefix = "foo_"
        allow_mutation = True

Complete configuration¶

This example represents a rendered output for which all features are enabled. It deviates from the default configuration above because it contains redundant information which is most likely not required. However, for demonstration purposes, this scenario covers all available display options for pydantic models/settings.

pydantic settings target.example_setting.ExampleSettings

Document your project settings very conveniently. Applies like wise to pydantic models.

Show JSON schema

{
   "title": "ExampleSettings",
   "description": "Document your project settings very conveniently. Applies like wise\nto pydantic models.",
   "type": "object",
   "properties": {
      "field_plain_with_validator": {
         "title": "Field Plain With Validator",
         "default": 100,
         "env_names": [
            "foo_field_plain_with_validator"
         ],
         "type": "integer"
      },
      "BarFoo": {
         "title": "Barfoo",
         "default": "FooBar",
         "env": "BarFoo",
         "env_names": [
            "barfoo"
         ],
         "type": "string"
      },
      "field_with_constraints_and_description": {
         "title": "Field With Constraints And Description",
         "description": "Shows constraints within doc string.",
         "default": 5,
         "minimum": 0,
         "maximum": 100,
         "env_names": [
            "foo_field_with_constraints_and_description"
         ],
         "type": "integer"
      }
   },
   "additionalProperties": false
}

Config

allow_mutation: bool = True
env_prefix: str = foo_

Fields

field_plain_with_validator (int)
field_with_validator_and_alias (str)
field_with_constraints_and_description (int)

Validators

check_max_length_ten » field_with_validator_and_alias
check_max_length_ten » field_plain_with_validator

field field_plain_with_validator: int = 100

Show standard field with type annotation.

Validated by

check_max_length_ten

field field_with_constraints_and_description: int = 5

Shows constraints within doc string.

Constraints

minimum = 0
maximum = 100

field field_with_validator_and_alias: str = 'FooBar' (alias 'BarFoo')

Shows corresponding validator with link/anchor.

Constraints

env = BarFoo

Validated by

check_max_length_ten

validator check_max_length_ten » field_with_validator_and_alias, field_plain_with_validator

Show corresponding field with link/anchor.

Validates

field_with_validator_and_alias
field_plain_with_validator

model Config

allow_mutation = True

env_prefix = 'foo_'

.. autopydantic_settings:: target.example_setting.ExampleSettings
   :noindex:
   :settings-show-config-member: True
   :validator-list-fields: True

from pydantic import BaseSettings, validator, Field


class ExampleSettings(BaseSettings):
    """Document your project settings very conveniently. Applies like wise
    to pydantic models.

    """

    field_plain_with_validator: int = 100
    """Show standard field with type annotation."""

    field_with_validator_and_alias: str = Field("FooBar",
                                                alias="BarFoo",
                                                env="BarFoo")
    """Shows corresponding validator with link/anchor."""

    field_with_constraints_and_description: int = Field(
        default=5,
        ge=0,
        le=100,
        description="Shows constraints within doc string."
    )

    @validator("field_with_validator_and_alias", "field_plain_with_validator")
    def check_max_length_ten(cls, v):
        """Show corresponding field with link/anchor.

        """

        if len(v) >= 10:
            raise ValueError("No more than 10 characters allowed")

        return v

    class Config:
        env_prefix = "foo_"
        allow_mutation = True

Fields only¶

In this scenario everything is hidden except actual pydantic fields. Validators and model/setting config is hidden.

pydantic settings target.example_setting.ExampleSettings

Document your project settings very conveniently. Applies like wise to pydantic models.

Fields

field_plain_with_validator (int)
field_with_validator_and_alias (str)
field_with_constraints_and_description (int)

field field_plain_with_validator: int = 100: Show standard field with type annotation.

field field_with_constraints_and_description: int = 5

Shows constraints within doc string.

Constraints

minimum = 0
maximum = 100

field field_with_validator_and_alias: str = 'FooBar' (alias 'BarFoo')

Shows corresponding validator with link/anchor.

Constraints

env = BarFoo

.. autopydantic_settings:: target.example_setting.ExampleSettings
   :settings-show-json: False
   :settings-show-config-member: False
   :settings-show-config-summary: False
   :settings-show-validator-members: False
   :settings-show-validator-summary: False
   :field-list-validators: False

from pydantic import BaseSettings, validator, Field


class ExampleSettings(BaseSettings):
    """Document your project settings very conveniently. Applies like wise
    to pydantic models.

    """

    field_plain_with_validator: int = 100
    """Show standard field with type annotation."""

    field_with_validator_and_alias: str = Field("FooBar",
                                                alias="BarFoo",
                                                env="BarFoo")
    """Shows corresponding validator with link/anchor."""

    field_with_constraints_and_description: int = Field(
        default=5,
        ge=0,
        le=100,
        description="Shows constraints within doc string."
    )

    @validator("field_with_validator_and_alias", "field_plain_with_validator")
    def check_max_length_ten(cls, v):
        """Show corresponding field with link/anchor.

        """

        if len(v) >= 10:
            raise ValueError("No more than 10 characters allowed")

        return v

    class Config:
        env_prefix = "foo_"
        allow_mutation = True

Asterisk and root validators¶

This example highlights how asterisk (@validator('*')) and root validators (@root_validator) are represented. Since they validate all fields, their corresponding field reference is replaced with a simple all fields marker which hyperlinks to the related model itself.

pydantic model target.example_validators.ExampleValidators¶

Show usage of asterisk and root validators.

Show JSON schema

{
   "title": "ExampleValidators",
   "description": "Show usage of asterisk and root validators.\n\n    ",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "email": {
         "title": "Email",
         "type": "string"
      }
   },
   "required": [
      "name",
      "email"
   ]
}

Fields

name (str)
email (str)

Validators

check_non_whitespaces » all fields
check_contains_letters » all fields

field email: str = PydanticUndefined¶

field name: str = PydanticUndefined¶

validator check_contains_letters » all fields¶: Confirm that string contains at least one letter.

validator check_non_whitespaces » all fields¶: Confirm that string contains non whitespace characters.

.. autopydantic_model:: target.example_validators.ExampleValidators

from pydantic import BaseModel, validator, root_validator


class ExampleValidators(BaseModel):
    """Show usage of asterisk and root validators.

    """

    name: str
    email: str

    @validator("*")
    def check_non_whitespaces(cls, v):
        """Confirm that string contains non whitespace characters.

        """

        stripped = v.strip()
        if stripped:
            return v
        else:
            raise ValueError("String contains only whitespace characters.")

    @root_validator
    def check_contains_letters(cls, values):
        """Confirm that string contains at least one letter.

        """

        for key, value in values.items():
            has_letter = any(x.isalpha() for x in value)
            if not has_letter:
                raise ValueError(f"Field '{key}' does not contain a letter.")

        return values

Note

By default the function signature of validators is replaced with hyperlinks to validated fields by autodoc_pydantic. You can disable this behaviour via validator-replace-signature.