Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

[BUG](codegen) Union entry-point descriptions are dropped — sourced from FieldInfo.description, never the docstring

Aperta
  • Qualcosa non va?
#596 0 commenti 0 reazioni 1 assegnatario Vedi su GitHub

I maintainer di solito rispondono entro 2 giorni

@sethfitz ci sta già lavorando.

Dal 23/7/2026.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

Summary

A union type-alias entry point renders no description on its generated markdown page, even when it has a docstring. Segment carries a rich description via Segment.__doc__, but the current transportation markdown renders that text zero times -- the # Segment page goes straight from its title to ## Fields.

Root cause

Union descriptions are sourced from FieldInfo.description during type analysis, never from __doc__. capture_union_members (extraction/type_analyzer.py:161) drives analyze_type, whose captured description is "the first FieldInfo.description found during unwrapping." Segment = Annotated[Union[...], Field(discriminator=...)] has exactly one FieldInfo -- the discriminator Field, which carries no description -- so UnionSpec.description resolves to None. The alias's __doc__ (set via Segment.__doc__ = "...") is never consulted.

Contrast with model classes: extract_model reads a class's __doc__ into RecordSpec.description, so a model's docstring renders. Unions have no equivalent path.

The rendering side is not the problem: the union template already emits {% if model.description %}, so a populated UnionSpec.description would render in the right place. The gap is purely sourcing.

Expectation

Give unions the same docstring path models already have -- source the union description from the docstring. The open decision is the sourcing rule / priority:

  • the alias or class docstring (__doc__)
  • FieldInfo.description (the current source -- keep as an override, or drop?)

This is a deliberate output change: it adds a description paragraph to every documented union page.

Relationship to the RootModel migration (#595)

The RootModel migration is the clean enabler. Once a union entry point is a RootModel class rather than an Annotated[...] alias carrying a Segment.__doc__ = assignment, its description lives in a normal class docstring -- a first-class source identical in kind to a model's. Sourcing from an Annotated alias's __doc__ is comparatively fragile.

Because the fix is a deliberate output change, it is deferred out of the byte-identical Segment-as-RootModel spike (the spike keeps UnionSpec.description at None -> None) and tracked here.

Lingua principale
Python
Stelle
220
Fork
22
Merge medio
3g 23h
PR unite (30g)
14

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di OvertureMaps/schema

Tutte le issue di OvertureMaps/schema

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.