Usage¶
Autodoc Sphinx¶
autodoc_pydantic integrates seamlessly with sphinx’ autodoc. Therefore, you
might not need to modify your code at all when using automodule
.
automodule¶
In this case, autodoc passes the documentation of all pydantic objects directly to autodoc_pydantic:
.. automodule:: target.example_setting
:members:
-
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_names": [ "foo_field_with_validator_and_alias" ], "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_
- 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
-
validator
check_max_length_ten
» field_with_validator_and_alias, field_plain_with_validator Show corresponding field 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")
"""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 not len(v) < 10:
raise ValueError("No more than 10 characters allowed")
class Config:
env_prefix = "foo_"
allow_mutation = True
Autodoc Pydantic¶
If you don’t want to rely on the automodule
directive, autodoc_pydantic
adds custom directives for pydantic models, settings, fields, validators and config class.
To completely customize a specific directive, you can use all available directive options, as explained in detail in the Configuration section.
autopydantic_model¶
In comparison the automodule
, you don’t need to add directive options
like :members:
to show all members. Instead, autodoc_pydantic supplies
sensible default settings.
.. autopydantic_model:: target.example_model.ExampleModel
-
pydantic model
target.example_model.
ExampleModel
Document your project settings very conveniently. Applies like wise to pydantic models.
Show JSON schema
{ "title": "ExampleModel", "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, "type": "integer" }, "BarFoo": { "title": "Barfoo", "default": "FooBar", "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, "type": "integer" } } }
- Config
allow_mutation: bool = True
env_prefix: str = foo_
- 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.
- 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.
from pydantic import BaseModel, validator, Field
class ExampleModel(BaseModel):
"""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")
"""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 not len(v) < 10:
raise ValueError("No more than 10 characters allowed")
class Config:
env_prefix = "foo_"
allow_mutation = True
To overwrite global defaults, the following directive options can be supplied:
autopydantic_settings¶
Documenting pydantic models behaves exactly like autopydantic_model
.
.. autopydantic_settings:: target.example_setting.ExampleSettings
-
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_names": [ "foo_field_with_validator_and_alias" ], "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_
- 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
-
validator
check_max_length_ten
» field_with_validator_and_alias, field_plain_with_validator Show corresponding field 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")
"""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 not len(v) < 10:
raise ValueError("No more than 10 characters allowed")
class Config:
env_prefix = "foo_"
allow_mutation = True
To overwrite global defaults, the following directive options can be supplied:
autopydantic_field¶
In some rare cases, you may want to document individual pydantic fields. In most cases, pydantic fields are documented along with its corresponding pydantic model/setting.
.. autopydantic_field:: target.example_setting.ExampleSettings.field_with_constraints_and_description
-
field
ExampleSettings.
field_with_constraints_and_description
: int = 5 Shows constraints within doc string.
- Constraints
minimum = 0
maximum = 100
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")
"""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 not len(v) < 10:
raise ValueError("No more than 10 characters allowed")
class Config:
env_prefix = "foo_"
allow_mutation = True
To overwrite global defaults, the following directive options can be supplied:
autopydantic_validator¶
As with pydantic validators, one usually does not document validators separately from its corresponding pydantic model/settings but it is still possible.
.. autopydantic_validator:: target.example_setting.ExampleSettings.check_max_length_ten
-
validator
ExampleSettings.
check_max_length_ten
» field_with_validator_and_alias, field_plain_with_validator Show corresponding field 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")
"""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 not len(v) < 10:
raise ValueError("No more than 10 characters allowed")
class Config:
env_prefix = "foo_"
allow_mutation = True
To overwrite global defaults, the following directive options can be supplied:
autopydantic_config¶
Very rarely, you may want to document a pydantic config class without the corresponding
pydantic model/setting. However, technically it’s possible since the autopydantic_config
directive is used by the autopydantic_model
and autopydantic_settings
.
.. autopydantic_config:: target.example_setting.ExampleSettings.Config
-
model
target.example_setting.ExampleSettings.
Config
-
allow_mutation
= True
-
env_prefix
= 'foo_'
-
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")
"""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 not len(v) < 10:
raise ValueError("No more than 10 characters allowed")
class Config:
env_prefix = "foo_"
allow_mutation = True
To overwrite global defaults, the following directive options can be supplied:
- Options