docstring_parser icon indicating copy to clipboard operation
docstring_parser copied to clipboard

Optionally preserve sub-indentation while parsing?

Open ntjess opened this issue 4 years ago • 4 comments

Maybe this is unsupportable, but I figured it was worth asking. In my library, metadata for function arguments is stored in the docstring, looking something like this:

def a(x=5):
  """
  :param x: The x parameter
    limits: [0, 5, 10, 15]
  """

Under the hood, I can turn this into a configuration using ConfigParser. However, docstring_parser removes all indentation underneath a parameter. This is a problem for me, since ConfigParser requires multiline values to be indented. The below example doesn't work, since all sub-indentation underneath x is obliterated:

def a(x=5):
  """
  :param x: The x parameter
    limits: [
        0, 5, 10, 15
      ]
  """

docstring_parser.parse() turns x's description into:

The x parameter
limits: [
0, 5, 10, 15
]
^^^ Notice the lack of indentation

Is there some way to optionally use textwrap.dedent instead of strip() during the parsing logic for these cases? Thanks for your consideration.

ntjess avatar Aug 02 '21 14:08 ntjess

Thank you for the detailed report. Currently this feature isn't there and would need to be implemented.

rr- avatar Aug 02 '21 15:08 rr-

Thanks for the reply. If this was to be a PR, what would you suggest for exposing it? Would enough people need the feature to add a keyword to parse? Would you make it a module parameter? Etc. I might be interested in creating such a feature, so I would love the feedback.

ntjess avatar Aug 02 '21 16:08 ntjess

I wouldn't add a new flag and just always keep the original indentation – it's easy to emulate old behavior with "\n".join(map(str.strip, docstring.splitlines())).

rr- avatar Aug 02 '21 16:08 rr-

You might be able to do something simple manually using textwrap.dedent in place of inspect.getdoc.

abergou avatar Aug 03 '21 01:08 abergou