configparser: add documentation about several read() behaviour

[sblondon]

BPO	37779
Nosy	@ambv, @sblondon, @nanjekyejoannah
PRs	bpo-37779 : Add information about the overriding behavior of ConfigParser.read #15177

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-12-24.10:12:16.223>
created_at = <Date 2019-08-06.20:22:40.631>
labels = ['type-bug', '3.8', '3.9', 'docs']
title = 'configparser: add documentation about several read() behaviour'
updated_at = <Date 2020-12-24.10:12:16.222>
user = 'https://github.com/sblondon'

bugs.python.org fields:

activity = <Date 2020-12-24.10:12:16.222>
actor = 'sblondon'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-12-24.10:12:16.223>
closer = 'sblondon'
components = ['Documentation']
creation = <Date 2019-08-06.20:22:40.631>
creator = 'sblondon'
dependencies = []
files = []
hgrepos = []
issue_num = 37779
keywords = ['patch']
message_count = 6.0
messages = ['349133', '349164', '349165', '349247', '377374', '383679']
nosy_count = 4.0
nosy_names = ['docs@python', 'lukasz.langa', 'sblondon', 'nanjekyejoannah']
pr_nums = ['15177']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue37779'
versions = ['Python 3.8', 'Python 3.9']

[sblondon]

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?

[nanjekyejoannah]

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

[nanjekyejoannah]

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().

[sblondon]

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?