Change `Docstring.params` (and others) to be dict-like types

[LecrisUT]

trafficstars

In order to make extracting the necessary attribute's docstring simpler, it would be great if it had a dict-like interface. attribute interface would also be great to have, but might require more sophisticated refactoring.

[scarere]

Attribute interface would be better as it would be consistent with the rest of the api. Ei

fndocs = parse(fn.__doc__)
fndocs.params.argument1.description

Is cleaner than:

fndocs = parse(fn.__doc__)
fndocs.params['argument1'].description

[LecrisUT]

Unfortunately this would not play quite well with type-hints

[scarere]

I'm not sure what you mean. Right now the Docstring class has attribute params with type List[DocstringParam]. Instead we could have

class DocstringParams():
        def __init__(self, params_list: List[DocstringParam]):
               for param in params_list:
                      setattr(self, param.arg_name, param)

Docstring
       self.params: DocstringParams = DocstringParams(list_of_DocstringParam_objects)

type hint should show Docstring.param as DocstringParams. Right now it just shows List[DocstringParam]. Or if you are talking about argument type hints, they are still available with

docstring.params.argument1.type_name

[LecrisUT]

It's about (statically) type-hinting for argument1. Afaiu you don't have a way to type-hint dynamic attributes statically, while the dict case is handled by __getitem__. I haven't ecperimented with type-hinting __getattr__.

[scarere]

Maybe I'm missing something but would argument1 not be type DocstringParam? as would all the param attributes of DocstingParams. We're not type hinting with the arguments actual type anyways, its just a string parameter under type_name

[ndahn]

I think dict-like access would be preferable. You could use a TypedDict or simply dict[str, DocstringParam] to accommodate for type hints. For backwards compatibility this could be an additional member instead of replacing params, e.g. params_dict or params_by_names.