Access docstring from codes ?

[eLvErDe]

Hello,

I haven't found a way to do that so I guess this is not possible at the moment. Would you consider such feature ?
For instances, this would be very helpful for enum type, in my case each enum value is correctly documented in the source WSD and I would like to access them to generate some example and generated OpenAPI documentation.

Thanks in advance,

Adam.

[tefra]

Unfortunately there is no out of the box solution to attach docstrings to enum members or dataclasses fields. Since the beginning of the library I wanted the generated models to be as simple as possible, without base classes or custom decorators. I also like boasting that the generated models have no dependency on the actual library 😄

For enums the nicest solution would be

class MyType(Enum):
    FOO = 1
    BAR = 2

MyType.FOO.__doc__ = "This is foo"
MyType.BAR.__doc__ = "This is bar"

Which is still 🤮 for dataclasses I think things are even more complicated. I like the idea of integrating xsdata with an OpenAPI documentation generator but I don't want to sacrifice readability or learning curve with custom base models/decorators.

Do you have a specific tool in mind? Because I would be more inclined to write a plugin or something like that for 3d party tool that will do the class docstring parsing during generation.

[eLvErDe]

Sadly, I don't have any idea, I just thought you may have an idea youself as you're probably doing something already to actually create those docstrings ;-)
Anyway, I'll check if I find some libraries to parse docstrings, otherwise I'll write something custom for my own use

[eLvErDe]

For the record I went for a crappy solution using https://github.com/rr-/docstring_parser

results: DefaultDict[str, List[Tuple[str, str]]] = collections.defaultdict(list)
for enum_name, enum_type in enum_types:
    enum_docstring = docstring_parser.parse(enum_type.__doc__.replace("cvar", "param"))
    for (enum_key, enum_value), enum_doc in zip(enum_type.__members__.items(), enum_docstring.params):
        docstring_desc = enum_doc.description
        assert enum_doc.arg_name == enum_key, "Docstring %s does not match enum %s" % (enum_doc.arg_name, enum_key)
        results[enum_name].append((enum_key, docstring_desc))

[tefra]

Yeah that looks painful....

For enums, I am comfortable with this way to attach docstrings, I could even introduce it as an additional style that can be selected from the generator configuration.

class MyType(Enum):
    FOO = 1
    BAR = 2

MyType.FOO.__doc__ = "This is foo"
MyType.BAR.__doc__ = "This is bar"

My issue is that for dataclasses it would have to be something like this, which is not really "attached" but it would be accessible.

In [3]: @dataclass
   ...: class Book:
   ...:     title: str = field(metadata={"docs": "blah blah blah"})

[eLvErDe]

metadata exists as "free dict" for field dataclass?
Looks like it's aimed to be used for this...

[tefra]

Hey @eLvErDe give it a try and let me know, see docs for examples.