[Python-checkins] cpython: Fix full-stop whitespace in configparser docs
lukasz.langa
python-checkins at python.org
Mon Sep 15 11:10:54 CEST 2014
http://hg.python.org/cpython/rev/23c1adede649
changeset: 92432:23c1adede649
parent: 92428:d3939f602e1f
user: Łukasz Langa <lukasz at langa.pl>
date: Sun Sep 14 23:37:03 2014 -0700
summary:
Fix full-stop whitespace in configparser docs
files:
Doc/library/configparser.rst | 86 ++++++++++++-----------
1 files changed, 44 insertions(+), 42 deletions(-)
diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst
--- a/Doc/library/configparser.rst
+++ b/Doc/library/configparser.rst
@@ -144,12 +144,13 @@
>>> float(topsecret['CompressionLevel'])
9.0
-Extracting Boolean values is not that simple, though. Passing the value
-to ``bool()`` would do no good since ``bool('False')`` is still
-``True``. This is why config parsers also provide :meth:`getboolean`.
-This method is case-insensitive and recognizes Boolean values from
-``'yes'``/``'no'``, ``'on'``/``'off'`` and ``'1'``/``'0'`` [1]_.
-For example:
+Since this task is so common, config parsers provide a range of handy getter
+methods to handle integers, floats and booleans. The last one is the most
+interesting because simply passing the value to ``bool()`` would do no good
+since ``bool('False')`` is still ``True``. This is why config parsers also
+provide :meth:`getboolean`. This method is case-insensitive and recognizes
+Boolean values from ``'yes'``/``'no'``, ``'on'``/``'off'``,
+``'true'``/``'false'`` and ``'1'``/``'0'`` [1]_. For example:
.. doctest::
@@ -319,11 +320,11 @@
.. class:: ExtendedInterpolation()
An alternative handler for interpolation which implements a more advanced
- syntax, used for instance in ``zc.buildout``. Extended interpolation is
+ syntax, used for instance in ``zc.buildout``. Extended interpolation is
using ``${section:option}`` to denote a value from a foreign section.
- Interpolation can span multiple levels. For convenience, if the ``section:``
- part is omitted, interpolation defaults to the current section (and possibly
- the default values from the special section).
+ Interpolation can span multiple levels. For convenience, if the
+ ``section:`` part is omitted, interpolation defaults to the current section
+ (and possibly the default values from the special section).
For example, the configuration specified above with basic interpolation,
would look like this with extended interpolation:
@@ -401,13 +402,13 @@
* ``parser.popitem()`` never returns it.
* ``parser.get(section, option, **kwargs)`` - the second argument is **not**
- a fallback value. Note however that the section-level ``get()`` methods are
+ a fallback value. Note however that the section-level ``get()`` methods are
compatible both with the mapping protocol and the classic configparser API.
* ``parser.items()`` is compatible with the mapping protocol (returns a list of
*section_name*, *section_proxy* pairs including the DEFAULTSECT). However,
this method can also be invoked with arguments: ``parser.items(section, raw,
- vars)``. The latter call returns a list of *option*, *value* pairs for
+ vars)``. The latter call returns a list of *option*, *value* pairs for
a specified ``section``, with all interpolations expanded (unless
``raw=True`` is provided).
@@ -541,9 +542,9 @@
* *delimiters*, default value: ``('=', ':')``
- Delimiters are substrings that delimit keys from values within a section. The
- first occurrence of a delimiting substring on a line is considered a delimiter.
- This means values (but not keys) can contain the delimiters.
+ Delimiters are substrings that delimit keys from values within a section.
+ The first occurrence of a delimiting substring on a line is considered
+ a delimiter. This means values (but not keys) can contain the delimiters.
See also the *space_around_delimiters* argument to
:meth:`ConfigParser.write`.
@@ -554,10 +555,10 @@
Comment prefixes are strings that indicate the start of a valid comment within
a config file. *comment_prefixes* are used only on otherwise empty lines
- (optionally indented) whereas *inline_comment_prefixes* can be used after
- every valid value (e.g. section names, options and empty lines as well). By
- default inline comments are disabled and ``'#'`` and ``';'`` are used as
- prefixes for whole line comments.
+ (optionally indented) whereas *inline_comment_prefixes* can be used
+ after every valid value (e.g. section names, options and empty lines
+ as well). By default inline comments are disabled and ``'#'`` and
+ ``';'`` are used as prefixes for whole line comments.
.. versionchanged:: 3.2
In previous versions of :mod:`configparser` behaviour matched
@@ -565,10 +566,10 @@
Please note that config parsers don't support escaping of comment prefixes so
using *inline_comment_prefixes* may prevent users from specifying option
- values with characters used as comment prefixes. When in doubt, avoid setting
- *inline_comment_prefixes*. In any circumstances, the only way of storing
- comment prefix characters at the beginning of a line in multiline values is to
- interpolate the prefix, for example::
+ values with characters used as comment prefixes. When in doubt, avoid
+ setting *inline_comment_prefixes*. In any circumstances, the only way of
+ storing comment prefix characters at the beginning of a line in multiline
+ values is to interpolate the prefix, for example::
>>> from configparser import ConfigParser, ExtendedInterpolation
>>> parser = ConfigParser(interpolation=ExtendedInterpolation())
@@ -613,7 +614,7 @@
When set to ``True``, the parser will not allow for any section or option
duplicates while reading from a single source (using :meth:`read_file`,
- :meth:`read_string` or :meth:`read_dict`). It is recommended to use strict
+ :meth:`read_string` or :meth:`read_dict`). It is recommended to use strict
parsers in new applications.
.. versionchanged:: 3.2
@@ -648,12 +649,12 @@
The convention of allowing a special section of default values for other
sections or interpolation purposes is a powerful concept of this library,
- letting users create complex declarative configurations. This section is
+ letting users create complex declarative configurations. This section is
normally called ``"DEFAULT"`` but this can be customized to point to any
- other valid section name. Some typical values include: ``"general"`` or
- ``"common"``. The name provided is used for recognizing default sections when
- reading from any source and is used when writing configuration back to
- a file. Its current value can be retrieved using the
+ other valid section name. Some typical values include: ``"general"`` or
+ ``"common"``. The name provided is used for recognizing default sections
+ when reading from any source and is used when writing configuration back to
+ a file. Its current value can be retrieved using the
``parser_instance.default_section`` attribute and may be modified at runtime
(i.e. to convert files from one format to another).
@@ -662,7 +663,7 @@
Interpolation behaviour may be customized by providing a custom handler
through the *interpolation* argument. ``None`` can be used to turn off
interpolation completely, ``ExtendedInterpolation()`` provides a more
- advanced variant inspired by ``zc.buildout``. More on the subject in the
+ advanced variant inspired by ``zc.buildout``. More on the subject in the
`dedicated documentation section <#interpolation-of-values>`_.
:class:`RawConfigParser` has a default value of ``None``.
@@ -727,10 +728,11 @@
.. attribute:: SECTCRE
- A compiled regular expression used to parse section headers. The default
- matches ``[section]`` to the name ``"section"``. Whitespace is considered part
- of the section name, thus ``[ larch ]`` will be read as a section of name
- ``" larch "``. Override this attribute if that's unsuitable. For example:
+ A compiled regular expression used to parse section headers. The default
+ matches ``[section]`` to the name ``"section"``. Whitespace is considered
+ part of the section name, thus ``[ larch ]`` will be read as a section of
+ name ``" larch "``. Override this attribute if that's unsuitable. For
+ example:
.. doctest::
@@ -871,8 +873,8 @@
When *delimiters* is given, it is used as the set of substrings that
divide keys from values. When *comment_prefixes* is given, it will be used
as the set of substrings that prefix comments in otherwise empty lines.
- Comments can be indented. When *inline_comment_prefixes* is given, it will be
- used as the set of substrings that prefix comments in non-empty lines.
+ Comments can be indented. When *inline_comment_prefixes* is given, it will
+ be used as the set of substrings that prefix comments in non-empty lines.
When *strict* is ``True`` (the default), the parser won't allow for
any section or option duplicates while reading from a single source (file,
@@ -886,13 +888,13 @@
When *default_section* is given, it specifies the name for the special
section holding default values for other sections and interpolation purposes
- (normally named ``"DEFAULT"``). This value can be retrieved and changed on
+ (normally named ``"DEFAULT"``). This value can be retrieved and changed on
runtime using the ``default_section`` instance attribute.
Interpolation behaviour may be customized by providing a custom handler
through the *interpolation* argument. ``None`` can be used to turn off
interpolation completely, ``ExtendedInterpolation()`` provides a more
- advanced variant inspired by ``zc.buildout``. More on the subject in the
+ advanced variant inspired by ``zc.buildout``. More on the subject in the
`dedicated documentation section <#interpolation-of-values>`_.
All option names used in interpolation will be passed through the
@@ -946,7 +948,7 @@
.. method:: has_option(section, option)
If the given *section* exists, and contains the given *option*, return
- :const:`True`; otherwise return :const:`False`. If the specified
+ :const:`True`; otherwise return :const:`False`. If the specified
*section* is :const:`None` or an empty string, DEFAULT is assumed.
@@ -1071,7 +1073,7 @@
:meth:`get` method.
.. versionchanged:: 3.2
- Items present in *vars* no longer appear in the result. The previous
+ Items present in *vars* no longer appear in the result. The previous
behaviour mixed actual parser options with variables provided for
interpolation.
@@ -1172,7 +1174,7 @@
.. note::
Consider using :class:`ConfigParser` instead which checks types of
- the values to be stored internally. If you don't want interpolation, you
+ the values to be stored internally. If you don't want interpolation, you
can use ``ConfigParser(interpolation=None)``.
@@ -1183,7 +1185,7 @@
*default section* name is passed, :exc:`ValueError` is raised.
Type of *section* is not checked which lets users create non-string named
- sections. This behaviour is unsupported and may cause internal errors.
+ sections. This behaviour is unsupported and may cause internal errors.
.. method:: set(section, option, value)
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list