Problem

Generating openapi specs for models with a formfeed (\f) in the docstring yields inconsistent results. For example, in the case of:

classAddress(BaseModel):"""    This is a public description of an Address\f    You can't see this part of the docstring, it's private!    """    ...

Sometimes the openapidescription ofAddress correctly renders asThis is a public description of an Address\n. But other times, you get the entire docstring even though the\f should be keeping the remainder of the docstring private.

The bug seemed to be in the following function:

defget_model_definitions(*,flat_models:Set[Union[Type[BaseModel],Type[Enum]]],model_name_map:Dict[Union[Type[BaseModel],Type[Enum]],str],)->Dict[str,Any]:definitions:Dict[str,Dict[str,Any]]= {}formodelinflat_models:m_schema,m_definitions,m_nested_models=model_process_schema(model,model_name_map=model_name_map,ref_prefix=REF_PREFIX        )definitions.update(m_definitions)model_name=model_name_map[model]if"description"inm_schema:m_schema["description"]=m_schema["description"].split("\f")[0]definitions[model_name]=m_schemareturndefinitions

The issue is that thedefinitions dict has its entries updated in two different places:

1. definitions.update(m_definitions)
2. definitions[model_name] = m_schema

When a model definition is written in line (2), the proper formfeed escape of the docstring is persisted. But if the same model is subsequently written by line (1), the previous docstring fix is clobbered over and we see the entire docstring.

This is a non-deterministic error, sinceflat_models is an unordered set. Depending on order of models in iteration, you could end up with either (1) or (2) as the final edit to a given model.

Solution

This fix works around the bug by handling the formfeed escape at theend of model processing. By that point ourdefinitions dict will be final, so any edits to the models are guaranteed to make it into the return value.

Related issues

• ✨ Support Python internal description on Pydantic model's docstring #3032

Questions & Alternatives

• Should Pydantic handle this on themodel_process_schema() function instead? (also asked in✨ Support Python internal description on Pydantic model's docstring #3032)
• Might there be other pre-existing, undiscovered bugs resulting from the fact thatdefinitions is updated in two different ways?