traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Fix full-stop whitespace in configparser docs

This commit is contained in:
Łukasz Langa 2014-09-14 23:37:03 -07:00
parent 45759a3924
commit 34cea14f74
1 changed files with 44 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
Doc/library/configparser.rst
View File

@ -144,12 +144,13 @@ datatypes, you should convert on your own:
>>> 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 @@ from ``get()`` calls.
.. 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 @@ However, there are a few differences that should be taken into account:
* ``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 @@ the :meth:`__init__` options:
* *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 @@ the :meth:`__init__` options:
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 @@ the :meth:`__init__` options:
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 @@ the :meth:`__init__` options:
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 :meth:`__init__` options:
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 @@ the :meth:`__init__` options:
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 @@ may be overridden by subclasses or by attribute assignment.
.. 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 @@ ConfigParser Objects
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 @@ ConfigParser Objects
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 @@ ConfigParser Objects
.. 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 @@ ConfigParser Objects
: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 @@ RawConfigParser Objects
.. 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 @@ RawConfigParser Objects
*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)