-
-
Notifications
You must be signed in to change notification settings - Fork 1.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Render Enum Member Docstrings in JSON Schema #8888
Comments
Thanks for the well thought out feature request! We recently added support for opt-in attribute docstring support. See the docs on that here: https://docs.pydantic.dev/dev/api/config/#pydantic.config.ConfigDict.use_attribute_docstrings. I think that support for this could be added in a similar way. Feel free to submit a PR adding support for this feature, I'd be happy to review! We'd want to make sure that this is opt in, as to avoid breaking changes for other users. |
Sounds great, thanks @sydney-runkle! I'll submit a PR using the same opt-in mechanism as as the new docstring support. |
Awesome! We're going to release 2.7 next week, so if you get it in before then, we can get it into this next release :) |
Excellent, thanks again! I've opened #9029 to implement this |
The main reason I don't want to necessarily do that by default is that it may not play nice with third party JSON schema tooling. In particular, we recently re-added I am not necessarily opposed to adding this option, but I would feel better about it if it didn't require adding an argument to the
|
Agreed, I think no matter the behavior of third-party tooling this would be best treated as a breaking change.
Just lack of awareness of that option! I didn't see from the outset that I could achieve this result that way, so started exploring the code and implementing from the perspective of a Pydantic change. Happy to just go that route if this isn't valuable to have in the library. Feel free to close if so. |
I think it would be reasonable for third-party tools to produce unpredictable behavior in this case, whether or not they cause issues today. |
Closing this per the discussion here and in the PR. I might bring this back up as a change in default behavior when V3 is on the horizon if it plays nicely enough with third-party tools. |
Apologies for the back and forth here, but on a closer look I don't think |
Closing based on #9029 (comment) 🚀 ! |
Initial Checks
Description
BLUF
Proposal to:
enum
tooneOf
+const
description
s for literal values from enum attributes'__doc__
when availableWhat & Why
If we have a field which can take a fixed number of values, we might want to add some detail around the meaning of the
values.
For example, suppose we have a parameter called
execution_mode
which can take on values ofSynchronous
orAsynchronous
. Perhaps we want to offer these notes to the user:In JSON Schema, this is best achieved through the use of
oneOf
andconst
:It would be valuable if Pydantic could support this JSON Schema output, and capture the member details in any other places they belong.
How: Reading From Enum Members'
__doc__
Of course, we can't provide these details to
typing.Literal
. But when defining our literal values in an enum,__doc__
seems like a natural place to source them. While there is no standard syntax to set attributes'__doc__
, there is active interest in documenting attributes. PEP 727 is under discussionand it revived interest in the PEP 224 style supported by supported by Sphinx and now Pydantic:
Despite the lack of syntax to do so, we can still set the
__doc__
dunder on enum members if we'd like. For example:Pydantic Functionality
I would hope to see the following changes to make this happen:
model_json_schema()
producesoneOf
+const
fields instead ofenum
fields when multiple there are multiple literal value, since JSON Schema'senum
doesn't support member descriptionsEnum.attribute.__doc__
values are passed through to thedescription
field in the output schemaImplementation
I'm new to the Pydantic codebase so would need some guidance if there are places outside of Model JSON Schema this data
would need to be used. But the first thing that comes to my mind is:
{c.value: c.__doc__ for c in cases if c.__doc__ is not None}
to aenum_member_descriptions
metadata field in get_enum_core_schema()oneOf
+const
instead ofenum
Risks & Alternatives
I'm sure I'm missing things so looking forward to the discussion! Here's what comes to mind for me:
Sourcing from PEP 224 Style Docstrings
Pydantic recently added support for parsing PEP 224-style attribute docstrings in Model Fields. It would be worth considering supporting that syntax alternatively or additionally.
Previous Migration from
anyOf
+const
toenum
JSON SchemaPydantic moved from
anyOf
+const
toenum
to better support OpenAPI. Some proper validation should be done but since OpenAPI's 3.1.0 version primarily focused on better alignment with JSON Schema I expect this wouldn't be an issue.Standardization Around Non-
attr.__doc__
There is fresh appetite to document symbols, but not all the proposals involve setting the
__doc__
attribute on the class attribute itself. If a different standard were adopted in the future, Pydantic might have to support both the new standard and the nonstandard__doc__
dunder.Affected Components
.model_dump()
and.model_dump_json()
model_construct()
, pickling, private attributes, ORM modeThe text was updated successfully, but these errors were encountered: