classification
Title: ConfigParser: stripping of comments should be documented
Type: Stage: patch review
Components: Versions:
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: jugmac00, lukasz.langa, miss-islington
Priority: normal Keywords: patch

Created on 2020-10-07 07:21 by jugmac00, last changed 2021-05-18 17:03 by lukasz.langa.

Pull Requests
URL Status Linked Edit
PR 26197 merged jugmac00, 2021-05-17 19:59
PR 26213 merged miss-islington, 2021-05-18 16:11
PR 26214 merged lukasz.langa, 2021-05-18 16:16
Messages (6)
msg378146 - (view) Author: Jürgen Gmach (jugmac00) * Date: 2020-10-07 07:21
While working on `tox-ini-fmt`, a formatter for - you guessed it - `tox.ini` files, I noticed ConfigParser strips comments when reading a config file.

( https://github.com/tox-dev/tox-ini-fmt/issues/34 )

While reasonable, this behaviour is surprising, as it is neither documented at https://docs.python.org/3/library/configparser.html nor in the docstrings (read and _read) which I read at first.

The stripping of comments is only documented with inline comments

https://github.com/jugmac00/cpython/blob/610a60c601fb4380eee30e15be1cd4dcbdaeec4c/Lib/configparser.py#L1019

and

https://github.com/jugmac00/cpython/blob/610a60c601fb4380eee30e15be1cd4dcbdaeec4c/Lib/configparser.py#L1031

Once I found these comments, I was surprised once again, as in my code the inline comments were not stripped. After some more pdb-ing and reading the source of ConfigParser, I noticed that - while comments have a default value, inline comments do not - and that is why when you read a config file, some comments get removed and others not.

I'd like to work on a pull request to document this behaviour, both in the official documentation and in the docstrings of the read and the _read methods.
msg378147 - (view) Author: Jürgen Gmach (jugmac00) * Date: 2020-10-07 07:23
This "while comments have a default value, inline comments do not" should read "while comment prefixes have a default value, inline comment prefixes do not"
msg378308 - (view) Author: Jürgen Gmach (jugmac00) * Date: 2020-10-09 09:24
The Python wiki mentions that "writing to an INI file will wipe out all comments".

https://wiki.python.org/moin/ConfigParserExamples

So, when updating the docstrings, it may be a good idea to both add a note at the read methods, that comments get ignored and to the write method(s) that on writing, the possible previous existing comments get removed.

Are there any thoughts on this or should I go forward and create a pull request?
msg378313 - (view) Author: Jürgen Gmach (jugmac00) * Date: 2020-10-09 11:00
pymotw.com shows a big red warning about comments not being preserved:

https://pymotw.com/3/configparser/
msg393885 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-05-18 16:45
New changeset c17ba233b3bdf6af4e9dad24374ab0a917b593e7 by Miss Islington (bot) in branch '3.9':
bpo-41963: document that ConfigParser strips off comments (GH-26197) (GH-26213)
https://github.com/python/cpython/commit/c17ba233b3bdf6af4e9dad24374ab0a917b593e7
msg393888 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-05-18 17:03
New changeset 4d17c93dfe760478509bcf709345b0522fd3a7e8 by Łukasz Langa in branch '3.10':
[3.10] bpo-41963: document that ConfigParser strips off comments (GH-26197) (GH-26214)
https://github.com/python/cpython/commit/4d17c93dfe760478509bcf709345b0522fd3a7e8
History
Date User Action Args
2021-05-18 17:03:17lukasz.langasetmessages: + msg393888
2021-05-18 16:45:25lukasz.langasetmessages: + msg393885
2021-05-18 16:16:20lukasz.langasetnosy: + lukasz.langa
pull_requests: + pull_request24831
2021-05-18 16:11:37miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request24830
2021-05-17 19:59:42jugmac00setkeywords: + patch
stage: patch review
pull_requests: + pull_request24814
2020-10-09 11:00:19jugmac00setmessages: + msg378313
2020-10-09 09:24:41jugmac00setmessages: + msg378308
2020-10-07 07:23:32jugmac00setmessages: + msg378147
2020-10-07 07:21:09jugmac00create