Issue 27824: update ConfigParser docs regarding in-line comments (original) (raw)
Created on 2016-08-21 17:07 by jahschwa, last changed 2022-04-11 14:58 by admin. This issue is now closed.
Messages (5)
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."
Author: R. David Murray (r.david.murray) * 
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 :)
Author: R. David Murray (r.david.murray) *
Date: 2016-08-22 13:50
The python3 docs do not mention inline comments. Perhaps we even want a documented deprecation here?
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'
Author: Irit Katriel (iritkatriel) *
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
2022-04-11 14:58:35
admin
set
github: 72011
2021-06-18 14:07:13
iritkatriel
set
status: open -> closed
nosy: + iritkatriel
messages: +
resolution: out of date
stage: resolved
2016-08-22 22:48:27
jahschwa
set
messages: +
2016-08-22 13:50:12
r.david.murray
set
messages: +
2016-08-22 13:48:09
r.david.murray
set
nosy: + r.david.murray, lukasz.langa
messages: +
2016-08-21 17:07:12
jahschwa
create