Including default values for Pydantic model attributes

[jgarbers]

I'm using Pydoctor in a project that uses Pydantic models to define and validate configuration options that are read from a TOML file. Most of those options have default values defined in their models, as in:

  from pydantic import BaseModel
  class Thing(BaseModel):
      color: str = "red"
      """Color of the thing"""

The Pydoctor-generated documentation for the "color" attribute looks like this:

  color:  str =
   Color of the thing

It would be helpful to include the default value of "red" right there, perhaps like:

  color:  str = "red"
   Color of the thing

so a reader would know whether or not they need to set some other desired value explicitly in the configuration file. I'd rather not have to repeat myself by including the default value explicitly in the docstring.

I experimented with the example code provided in the Pydoctor docs under "Use a custom system class", even getting to the point of picking out the attribute's default value within the depart_AnnAssign function. But from there, I have no idea how to get that value to appear in the generated documentation for the attribute. I reviewed the source for the zopeinterface extension but wasn't able to understand it well enough to follow my idea through.

Is there some existing extension or facility for including these default values? If not, can someone refer me to some examples or offer some broad strokes about how that might be accomplished via an extension? Or is this probably out of bounds for someone without a strong understanding of Pydoctor internals?

Thanks very much for any guidance anyone can offer!

[tristanlatr]

I’m working on adding better support for attrs API (#656). See the result here . Basically it auto generates the documentation for the init method, which contain default values in the signature.

Once this merged, I’ll adjust the code so that it will work for dataclasses and named tuples, as well as for pydantic models. Since all of this provides more or less the same thing (from a documentation perspective).

For the short term, we could improve the way the system choose to display the value of an attribute so that it can be customized by subclassing the System class. This means replacing the static System.show_attr_value class attribute into a function System.showAttributeValue. Which could be customized on your end afterwards.

tell me what you think.

[jgarbers]

Thanks so much for the quick reply! It'll take me some study to get a solid grasp of what you're proposing but I have high confidence that it'll be just fine. I still owe you a reproducer on issue #728 but recreating that situation is trickier than I thought... hopefully soon!

[tristanlatr]

This is the place that needs change for the short term: https://github.com/twisted/pydoctor/blob/662eafaedcdfcfa0c5a83c1048c28f187fbcf4c9/pydoctor/templatewriter/pages/attributechild.py#L81C5-L81C5