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."

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 :)

The python3 docs do not mention inline comments.  Perhaps we even want a documented deprecation here?

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'

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