On 8/28/20 6:56 AM, Steve Barnes wrote:
It occurs to me that there are many situations where files are human authored and can include comments but by default when python reads/modifies/writes those files by default the comments are lost.
Some examples include configfile, json and even python itself with the special case that docstrings are read without being discarded.
If we wish to generate a commented file, (such as an initial version of a config file), then file type specific code is needed but in general if we read in a file the comments are discarded – usually of course this is what we need but not if we are going to be modifying values are re-writing.
In the case of files that are read and parsed into python objects we could quite easily have an option to make comments a docstring on the resulting objects and a write option to output the docstrings (marked as comments).
It would be necessary to have a mechanism for preserving file level comments that are interleaved with values/objects and after the last value/object.
Of course, in many cases, it would be nice to have find commented object and uncomment object, possibly comment out object methods but I still believe that even without such methods could be useful to be able to round trip files that include comments.
Writing this has also sparked a thought of wouldn’t it be nice to have a format for python line comments where the object so commented gets a docstring from the line comment, e.g.
class StockItem:
“”” Represents an item available in store “””
lineno: str #! Catalogue Item Number in the format AA-nnnn-AAA
:
The humble docstring can be so useful and as far as I know any python object can carry one but currently base classes such as int, etc. Have read only __doc__ members.
Of course I am probably going to get told off for 2 related but divergent elements in one thread!
Steve Barnes
This is just about the first part of your mail: There are external libraries for reading and writing various formats while preserving comments (and even more, e.g. spacing): For Python files, there is RedBaron, for YAML there is ruamel.yaml, and JSON doesn't allow comments as far as I know. For configfile I'm not sure, doesn't look like there is anything... but one could have a look at how comments are represented in RedBaron and ruamel.yaml and write a similar library for configfiles. Cheers