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

Activity

1. scarere commented on Aug 7, 2024

   

   scarere

   on Aug 7, 2024

   More actions

   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
2. LecrisUT commented on Aug 7, 2024

   

   LecrisUT

   on Aug 7, 2024

   ContributorAuthor

   More actions

   Unfortunately this would not play quite well with type-hints
3. scarere commented on Aug 7, 2024

   

   scarere

   on Aug 7, 2024

   More actions

   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
4. LecrisUT commented on Aug 7, 2024

   

   LecrisUT

   on Aug 7, 2024

   ContributorAuthor

   More actions

   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__.
5. scarere commented on Aug 7, 2024

   

   scarere

   on Aug 7, 2024

   More actions

   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
6. ndahn commented on Sep 6, 2024

   

   ndahn

   on Sep 6, 2024

   More actions

   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.
7. rr-

   closed this as completedin #197on Nov 7, 2026
8. rr- commented on Nov 7, 2026

   

   rr-

   on Nov 7, 2026

   Owner

   More actions

   Thanks all for the discussion on dict versus attribute access. This is fixed in #197, now on main, which adds params_by_name, attrs_by_name and raises_by_type: read-only mappings next to the existing lists, so doc.params_by_name["argument1"].description works and type checkers know what it returns. If a name is given twice, the first item wins, and the lists still have every item. I went with dict-style lookup rather than attributes for the typing reasons discussed above.