classification
Title: configparser: add documentation about several read() behaviour
Type: behavior Stage: patch review
Components: Documentation Versions: Python 3.9, Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, nanjekyejoannah, sblondon
Priority: normal Keywords: patch

Created on 2019-08-06 20:22 by sblondon, last changed 2019-08-08 18:50 by sblondon.

Pull Requests
URL Status Linked Edit
PR 15177 open sblondon, 2019-08-08 13:59
Messages (4)
msg349133 - (view) Author: Stéphane Blondon (sblondon) * Date: 2019-08-06 20:22
The documentation is not explicit about the behaviour if several files are read by the same ConfigParser: the data are not reset between two read().

I suggest to add such information in the documentation. There is a draft:

=== start ===
When a `ConfigParser` instance make several calls of `read_file()`, `read_string()` or `read_dict()` functions, the previous data will be overriden by the new ones. Otherwise, the previous data is kept. This behaviour is equivalent to a `read()` call with several files passed to `filenames` parameter`.

Example:
config = configparser.ConfigParser()
s = """
[spam]
alpha=1
"""
config.read_string(s)
# dict(config["spam"]) == {'alpha': '1'}
config.read_string("")
# dict(config["spam"]) == {'alpha': '1'}
=== end ===

What do you think about it?
I can do a PR but I wonder where is the best location in the documentation to insert it.

At the end of the 'Quick start paragraph' (https://docs.python.org/3/library/configparser.html#quick-start)? Or perhaps a new paragraph after 'Fallback Values'? Other location?
msg349164 - (view) Author: Joannah Nanjekye (nanjekyejoannah) * (Python committer) Date: 2019-08-07 12:31
@Stéphane, thanks for suggesting the above documentation.

Feel free to open a pull request here: https://github.com/python/cpython with this draft for review.
msg349165 - (view) Author: Joannah Nanjekye (nanjekyejoannah) * (Python committer) Date: 2019-08-07 12:37
I think you can build on the story in the quick start section.

You can build on from the last section that starts with the paragraph:

Now that we have created and saved a configuration file, let’s read it back and explore the data it holds.

As it has some examples on read().
msg349247 - (view) Author: Stéphane Blondon (sblondon) * Date: 2019-08-08 18:50
Thank you for the idea. :)

I committed something else, based on the previous example of the 'Quick Start' section.

What do you think about it?
History
Date User Action Args
2019-08-08 18:50:16sblondonsetmessages: + msg349247
2019-08-08 13:59:22sblondonsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request14908
2019-08-07 12:37:06nanjekyejoannahsetmessages: + msg349165
2019-08-07 12:31:12nanjekyejoannahsetnosy: + nanjekyejoannah
messages: + msg349164
2019-08-07 07:47:28SilentGhostsetnosy: + docs@python, - Alex.Willmer
components: + Documentation, - Cross-Build
assignee: docs@python
2019-08-07 07:47:15SilentGhostsetversions: + Python 3.8
nosy: + Alex.Willmer

components: + Cross-Build, - Library (Lib)
type: enhancement -> behavior
stage: needs patch
2019-08-06 20:22:40sblondoncreate