Fix inconsistent processing of model docstring formfeed char #6039
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Problem
Generating openapi specs for models with a formfeed (
\f
) in the docstring yields inconsistent results. For example, in the case of:Sometimes the openapi
description
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:
The issue is that the
definitions
dict has its entries updated in two different places:definitions.update(m_definitions)
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, since
flat_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 the end of model processing. By that point our
definitions
dict will be final, so any edits to the models are guaranteed to make it into the return value.Related issues
Questions & Alternatives
definitions
is updated in two different ways?