Support Pydantic model defaults + field descriptions

[jinnovation]

Contributes to #793.

This PR implements quick-and-dirty support for Pydantic-style default values and field descriptions. In other words, the following two classes will render equivalently:

class Foo(pydantic.BaseModel):
    """Foo class documentation."""

    a: int = pydantic.Field(default=1, description="Docstring for a")

class Foo(pydantic.BaseModel):
    """Foo class documentation."""

    a: int = 1
    """Docstring for a"""

Open questions:

• Should Pydantic support for pdoc be split out into a separate "plugin" package, e.g. pdoc-pydantic or pdoc[pydantic]?
• Is this the best place for default-value-extraction logic for Pydantic classes to live?

[mhils]

Thanks!

Should Pydantic support for pdoc be split out into a separate "plugin" package, e.g. pdoc-pydantic or pdoc[pydantic]?

Too much complexity for now. I think pydantic is popular enough to have support for it builtin for now.

Is this the best place for default-value-extraction logic for Pydantic classes to live?

Pragmatically yes. See my comments below on how we can keep things reasonably clean.

[jinnovation]

Two issues related to rendering Pydantic model docs that I propose treating as out-of-scope for this PR:

• If user's BaseModel subclass does not have its own class-level docstring, we end up rendering the docs for BaseModel itself;
• We render the docs for model_config, which is typically only useful to implementers of the class and not to users thereof, i.e. the expected audience for the generated docs

[jinnovation]

@mhils: This is ready for your eyes again!

[mhils]

Thank you, great progress! 😃

[mhils]

Is there any reason why plain import pydantic does not work?

Also, let's get rid of the TYPE_CHECKING extra logic and just slap # type: ignore[no-redef] on the pydantic = None line. That should work?

[jinnovation]

Went a simpler (possibly) direction for the optional-import stuff. Let me know your thoughts.

[mhils]

Can we simplify like this?

Suggested change

	_docstring: str | None = None
	if self.kind == "class":
	_docstring = _pydantic.get_field_docstring(cast(type, self.obj), name)
	if _docstring is None:
	if self._var_docstrings.get(name):
	doc.docstring = self._var_docstrings[name]
	if self._func_docstrings.get(name) and not doc.docstring:
	doc.docstring = self._func_docstrings[name]
	else:
	doc.docstring = _docstring
	if doc := _pydantic.get_field_docstring(self.obj, name):
	doc.docstring = doc
	elif doc := self._var_docstrings.get(name):
	doc.docstring = doc
	elif doc := self._func_docstrings.get(name) and not doc.docstring:
	doc.docstring = doc

[jinnovation]

Got something that I think works. Let me know what you think.

[mhils]

Thanks for the fast revision!