bpo-41963: document that ConfigParser strips off comments (GH-26197) (GH-26213)

Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>
Co-authored-by: Laura Gutierrez Funderburk <58710704+lgfunderburk@users.noreply.github.com>
Co-authored-by: Jürgen Gmach <juergen.gmach@googlemail.com>
(cherry picked from commit 02ee8191263848f8c8999f72286148946b83e5c9)

diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst
index 2e22a549ee2813d676b086286959447512fbf525..730d1df9614289747b7b39486ce821bb69a0776f 100644 (file)
--- a/Doc/library/configparser.rst
+++ b/Doc/library/configparser.rst
@@ -1129,6 +1129,13 @@ ConfigParser Objects
       *space_around_delimiters* is true, delimiters between
       keys and values are surrounded by spaces.
 
+   .. note::
+
+      Comments in the original configuration file are not preserved when
+      writing the configuration back.
+      What is considered a comment, depends on the given values for
+      *comment_prefix* and *inline_comment_prefix*.
+
 
    .. method:: remove_option(section, option)
 

diff --git a/Lib/configparser.py b/Lib/configparser.py
index 924cc56a3f150d16f246841512a0876ff83ead6a..8dd5c13bcc00921b31780d2fb792231004497cbd 100644 (file)
--- a/Lib/configparser.py
+++ b/Lib/configparser.py
@@ -907,6 +907,9 @@ class RawConfigParser(MutableMapping):
 
         If `space_around_delimiters' is True (the default), delimiters
         between keys and values are surrounded by spaces.
+
+        Please note that comments in the original configuration file are not
+        preserved when writing the configuration back.
         """
         if space_around_delimiters:
             d = " {} ".format(self._delimiters[0])
@@ -1005,7 +1008,7 @@ class RawConfigParser(MutableMapping):
         Configuration files may include comments, prefixed by specific
         characters (`#' and `;' by default). Comments may appear on their own
         in an otherwise empty line or may be entered in lines holding values or
-        section names.
+        section names. Please note that comments get stripped off when reading configuration files.
         """
         elements_added = set()
         cursect = None                        # None, or a dictionary

diff --git a/Misc/NEWS.d/next/Documentation/2021-05-17-20-03-47.bpo-41963.eUz9_o.rst b/Misc/NEWS.d/next/Documentation/2021-05-17-20-03-47.bpo-41963.eUz9_o.rst
new file mode 100644 (file)
index 0000000..b9fe722
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2021-05-17-20-03-47.bpo-41963.eUz9_o.rst
@@ -0,0 +1 @@
+Document that ``ConfigParser`` strips off comments when reading configuration files.
\ No newline at end of file