darglint
darglint copied to clipboard
terrencepreilly
Formatter
Hello Terrence, I googled a lot and found this beautiful library, parsing the docstring with EBNF.
Quick question: are there plans to implement a formatter that automatically formats the docstring?
For a random docstring, it is almost impossible to get any useful output. But for an already structured docstring, it may be good to automatically wrap lines, fix some indentation (if possible), remove extra whitespaces, newlines, etc.
What do you think?
This is something I've been thinking about quite a bit as I rewrite the parser. In fact, yes, I plan to attempt this, though I'm unsure how successful it will be.
The current parser rewrite should help in this effort. Poorly formatted docstrings can be parsed with this new parser, and are annotated with classes which describe the error. Since each stylistic error is annotating the problematic node, a resolution strategy should be simple to provide for each such error.
This is a ways off, though. I've finished rewriting the parser to handle ambiguous grammars. My next step is to add an integration test framework to address the regressions I've introduced. I also need to address the performance regression this new parser introduces. Once those tasks are complete, I will probably attempt to implement the auto-formatter. So, maybe in two months or so?
If you (or anyone else) wants to help out with it, the new parser is in the style-errors branch.
I'd be happy to start work on this if you could point me in the right direction on where to start.
I wrote a short proof-of-concept for you (and to make sure that it can actually be done.) check out 4b05bee4176e7049062190fe5000e194e6ee4364 on the formatter-example branch. (You can diff it against 54a1cc8f30153590f781396febf1c727767eae4f on the develop branch to see the relevant details, or check out the reference above.)
If anything is unclear in it, let me know. The basic idea is that we should represent possible mistakes/errors in the grammar. Then we can parse a docstring, transform the ast which is produced (using the errors which were identified), and reconstruct it with the correct whitespace.
Oh, to run the example, you just have to make sure you have darglint installed in your pip environment (you can create a virtualenv, then run pip install -e . in the darglint directory). Then in the darglint/formatter directory, you can run python format.py numbers and it should print out the corrected hex numbers.