PydanticUndefined is shown even if there is a default_factory

[spacemanspiff2007]

Currently PydanticUndefined is shown if there is a default factory.

Source

habapp: HABAppConfig = Field(default_factory=HABAppConfig, in_file=False)

Output

I think PydanticUndefined is a bit misleading since the default is not undefined.
How about [has default] (so it's the same as with [required]) so it's clear that the field will have a default when created.

Possible output:

[mansenfranzen]

Thanks for pointing this out! Technically, it is correct to have the PydanticUndefined default value because the default value is not known until object instantiation of the corresponding class that inherits from pydantic BaseModel. The documentation is generated from the class and not from instances of it.

However, for documentation purposes, a rather non technical label/marker is more appropriate, I agree. You've proposed the [has default] marker. That's a good starting point. Perhaps the less the better - let's just hide the default value completely for PydanticUndefined default values because the opposite case is explicitly marked via [required].

I suggest we add a new configuration property named autodoc_pydantic_field_hide_undefined_default_value. What's your opinion on that?

[spacemanspiff2007]

Perhaps the less the better - let's just hide the default value completely for PydanticUndefined default values because the opposite case is explicitly marked via [required].

Normally I am a huge fan of keeping things short but this is imho one of the times where I think explicit is better than implicit.
If I don't know any of the internals and read the docs for the first time it's immediately clear that

• values that have a default are optional
• values that are required and don't have a default have the [Required] tag

If there is no [Required] tag and no default things are ambiguous and it's not clear if the field can be omitted.
Thus I really thing there should be some kind of marker that indicates that I don't have to specify a value for this field.

How about the opposite of [Required]: [Optional]?

The config switch could than be named autodoc_pydantic_field_show_default_factory_as_optional.

[mansenfranzen]

You have convinced me - let's be more explicit.

In support of your point, the optional/required tag might be even necessary even if the type already contains Optional[int] because:

• field_a: Optional[int] is indeed optional
• while field_b: Optional[int] = ... is required

I added an example section outlining all these possibilities here. Taking a closer look at this example, it becomes evident that all = PydanticUndefined could be converted into [Optional].

So, taking this into account, what about autodoc_pydantic_field_mark_undefined_as_optional?

[spacemanspiff2007]

I think show instead of mark would be more consistent with the already existing configuration options.
How about autodoc_pydantic_field_show_pydantic_undefined_as_optional?
autodoc_pydantic_field_show_undefined_as_optional is fine, too.

On the other hand the required marker uses autodoc_pydantic_field_show_required so maybe autodoc_pydantic_field_show_optional would be the most consistent one?

Thank you for your help!

[mansenfranzen]

Let's go with autodoc_pydantic_field_show_optional for all fields which are not obviously optional (e.g. field: int = 1). Thanks for sharing your thoughts on those naming conventions - really appreciate it.

[mansenfranzen]

@spacemanspiff2007 This feature request should be accomplished via #117

• Documentation on the new configuration property autodoc_pydantic_field_show_optional: click
• Updated documentation on the example for required/optional fields: click

By the way, I took the chance to modify how the default value is fetched from pydantic fields. This results in properly showing the default value None for all plain optional fields such as field: Optional[int].

Before merging the related PR, it would be great if you could test the behavior on your site. To do so, please install the current dev release in your doc-building-environment via pip install git+https://github.com/mansenfranzen/[email protected] and rebuild your docs.

[spacemanspiff2007]

Looks good! Thank you for the quick implementation!