classification
Title: update ConfigParser docs regarding in-line comments
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, iritkatriel, jahschwa, lukasz.langa, r.david.murray
Priority: normal Keywords:

Created on 2016-08-21 17:07 by jahschwa, last changed 2021-06-18 14:07 by iritkatriel. This issue is now closed.

Messages (5)
msg273306 - (view) Author: Joshua Haas (jahschwa) Date: 2016-08-21 17:07
Originally reported at http://bugs.python.org/issue27762 as a behavior bug but was determined to be won't fix. Thus I think this needs to be mentioned in the documentation at https://docs.python.org/2/library/configparser.html

I propose that directly after the following:

"(For backwards compatibility, only ; starts an inline comment, while # does not.)"

be added:

"Inline comments will not be recognised in lines that contain ; before the comment itself. To ensure that inline comments work as expected, do not use ; in config values."
msg273376 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-08-22 13:48
Alternate proposal.  Replace that whole paragraph with:

Configuration files may include comments, prefixed by specific characters (# and ;). Comments may appear on their own in an otherwise empty line.  If a line has a value or section name that does not include a ';', an inline comment can be added by entering at least one space followed by a ';' and the comment.  While supported, inline comments are fragile in the face of values that may contain ';'s, and thus are not recommended.

Of course, I'm making a (new) value judgement in that last sentence so lukasz may override me :)
msg273377 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-08-22 13:50
The python3 docs do not mention inline comments.  Perhaps we even want a documented deprecation here?
msg273410 - (view) Author: Joshua Haas (jahschwa) Date: 2016-08-22 22:48
I'm not sure it's deprecated so much as moved. Python 3.5 includes an additional init parameter, so setting inline_comment_prefixes=';' allows inline comments even for values containing the ';' character, displaying the "expected behavior" described in my original bug report. They are, however, disabled by default, unlike in Python 2.7.

I also have a different proposal I think might be more clear:

Configuration files may include comments, prefixed by specific characters. Comments may appear on their own in an otherwise empty line using either '#' or ';'. In addition, inline comments can be added to the end of a line after a ';' as long as the ';' is preceded by a whitespace character. Only the first ';' in a line is checked, so an inline comment cannot be added to lines that already contain any ';'s.

I'm also wondering if an example would be a good idea, as I don't think any of the examples on the doc page include comments:

# this is a comment
; this is also a comment
foo = bar ; inline comment
password = jgfw;as1 ; this will be parsed as part of 'password'
msg396067 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-06-18 14:07
This is explained in the example now, just above
https://docs.python.org/3.10/library/configparser.html#interpolation-of-values


It was changed here:
https://github.com/python/cpython/commit/b25a791802a1915097e02bfba04e27a41ae55ebf
History
Date User Action Args
2021-06-18 14:07:13iritkatrielsetstatus: open -> closed

nosy: + iritkatriel
messages: + msg396067

resolution: out of date
stage: resolved
2016-08-22 22:48:27jahschwasetmessages: + msg273410
2016-08-22 13:50:12r.david.murraysetmessages: + msg273377
2016-08-22 13:48:09r.david.murraysetnosy: + r.david.murray, lukasz.langa
messages: + msg273376
2016-08-21 17:07:12jahschwacreate