<div dir="ltr"><div>Dear all,</div><div><br></div><div>After PR 1446, g.parser now accepts `# %` in addition to `#%` in order to allow following of the Python practice starting a block comment with `# `. This is checked by Flake8 E265. This resolved numerous warnings which you would otherwise get for each module when using Flake8 with default, that is, expected, settings. Consequently, users writing their own scripts/modules can use Flake8 with default settings without getting a flood of messages.<br></div><div><br></div><div>However, not all issues were addressed by that. Many modules generate "E501 Line too long" warnings. Following default settings for the Black formater, we are now using 88 characters as line limit. Option and flag descriptions and the value of descriptions describing options* have often more characters than that.</div><div><br></div><div>Currently, the E501 warning is disabled for all files in scripts and temporal directories and for selected `g.gui.*.py` files in gui/wxpython. However, we want to have the warning enabled globally. Although, Black takes care of most of the long lines, it does not touch some lines, namely long strings, and thus we want each file to be checked for Flake8 E501 compliance.</div><div><br></div><div>I would like to disable the check in each file just for the specific block of code, however, this is not possible because Flake8 does not allow disabling for blocks of code. Requiring the lines to be shorter won't work either because the descriptions item needs to be long. This leaves us with the following options:</div><div><br></div><div>1. Use per-file ignores to disable the warning and keep adding the files which need it. This makes the Flake8 configuration larger over time while our goal is to make it smaller over time. It also leaves the warning disabled for (other code in) these files.<br></div><div><br></div><div>2. Add inline Flake8 ignore comment to the offending line. This will make the line little longer, but it would be a good solution for normal Python code. However, in case of the script header, we would need to teach g.parser to understand trailing comments inside the relevant fields so that the Flake8 ignore comment does not leak into the user interface description.<br></div><div><br></div><div>3. According to the PEP 257 - Docstring Conventions document, the 'docstring of a script (a stand-alone program) should be usable as its "usage" message.' I don't think sticking something like our parser instructions into the docstring was what the authors had in mind. Additionally, it is not used like this either as far as I can tell. However, it would solve our issue. Just adding `"""` before the definition and adding `"""  # noqa: E501` after that disables the warning for the definition. The nice bonus is that we comply with PEP 257 by providing module docstring and by describing its interface there (in some way). The docstring presence is checked by Pylint's C0111 "Missing ... docstring".<br></div><div><br></div><div>4. We modify the parser so that at least some of the items can have multiple lines. However, the parser is currently quite line-oriented and the cost-benefit ratio may be low.</div><div><br></div><div>5. We change the script header definition format to some existing format that can break lines, i.e. allowing multi-line values.  A clear candidate for the format is YAML or rather its simpler subset. This would have additional benefits of making the format a standard format. Which in turn would be beneficial for other things, e.g., for easier learning of the syntax. Combining this with option 3, we could drop the `# %` part to make the YAML more readily readable.<br></div><div><br></div><div>Let me know what you think, what option you like, what you would add, and what you can help with.<br></div><div><br></div><div>Thank you,<br></div><div></div><div>Vaclav<br></div><div><br></div><div><br></div><div><br></div><div>* Clearly, we should do something about the naming here, too!<br></div><div></div><div><br></div><div><br></div><div>Example for option 3:<br></div><div><br></div><div>"""<br># %module<br># % description: Imports raster data into a GRASS raster map using GDAL library and reprojects on the fly.<br>...</div><div># %option<br># % key: resample<br># % type: string<br># % required: no<br># % multiple: no<br># % options: nearest,bilinear,bicubic,lanczos,bilinear_f,bicubic_f,lanczos_f<br># % description: Resampling method to use for reprojection<br># % descriptions: nearest;nearest neighbor;bilinear;bilinear interpolation;bicubic;bicubic interpolation;lanczos;lanczos filter;bilinear_f;bilinear interpolation with fallback;bicubic_f;bicubic interpolation with fallback;lanczos_f;lanczos filter with fallback<br># % answer: nearest<br># % guisection: Output<br># %end<br>...<br># %rules<br># % required: output,-e<br># %end<br>"""  # noqa: E501</div><div><br></div><div>Links:</div><div><br></div><div><div></div><div><a href="https://github.com/OSGeo/grass/pull/1446">https://github.com/OSGeo/grass/pull/1446</a></div><div><a href="https://www.flake8rules.com/rules/E265.html">https://www.flake8rules.com/rules/E265.html</a></div><div><a href="https://www.flake8rules.com/rules/E501.html">https://www.flake8rules.com/rules/E501.html</a></div><div><a href="http://pylint-messages.wikidot.com/messages:c0111">http://pylint-messages.wikidot.com/messages:c0111</a></div></div></div>