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_without_default": { "title": "Field Without Default", "env_names": "{'foo_field_without_default'}", "type": "string" }, "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" } }, "required": [ "field_without_default" ], "additionalProperties": false }
- Config
allow_mutation: bool = True
env_prefix: str = foo_
- Fields
- Validators
-
field
field_plain_with_validator
: int = 100¶ Show standard field with type annotation.
- Validated by
-
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.
- Validated by
-
field
field_without_default
: str [Required]¶ Shows the [Required] marker in the signature.
-
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_without_default: str, 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.
-
attribute
field_without_default
: str Shows the [Required] marker in the signature.
-
classmethod
from pydantic import BaseSettings, validator, Field
class ExampleSettings(BaseSettings):
"""Document your project settings very conveniently. Applies like wise
to pydantic models.
"""
field_without_default: str
"""Shows the *[Required]* marker in the signature."""
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
.. autopydantic_settings:: target.example_setting.ExampleSettings
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_without_default": { "title": "Field Without Default", "env_names": "{'foo_field_without_default'}", "type": "string" }, "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" } }, "required": [ "field_without_default" ], "additionalProperties": false }
- Config
allow_mutation: bool = True
env_prefix: str = foo_
- Fields
- Validators
-
field
field_plain_with_validator
: int = 100 Show standard field with type annotation.
- Validated by
-
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.
- Validated by
-
field
field_without_default
: str [Required] Shows the [Required] marker in the signature.
-
validator
check_max_length_ten
» field_with_validator_and_alias, field_plain_with_validator Show corresponding field with link/anchor.
-
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_without_default: str
"""Shows the *[Required]* marker in the signature."""
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
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.
-
field
field_without_default
: str [Required] Shows the [Required] marker in the signature.
.. 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_without_default: str
"""Shows the *[Required]* marker in the signature."""
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
- Validators
-
field
email
: str [Required]¶
-
field
name
: str [Required]¶
-
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.