configparser API cleanup: default values now sensible, slightly incom… · python/cpython@b25a791 (original) (raw)

`@@ -230,21 +230,18 @@ may be treated as parts of multiline values or ignored.

230

231

`Configuration files may include comments, prefixed by specific

232

``` characters (# and ; by default [1]_). Comments may appear on


`233`

``

`-

their own on an otherwise empty line, or may be entered on lines holding

`

`234`

``

`-

values or section names. In the latter case, they need to be preceded

`

`235`

``

`-

by a whitespace character to be recognized as a comment. For backwards

`

`236`

``

``` -

compatibility, by default only ``;`` starts an inline comment, while

237


``#`` does not [1]_.

233

their own on an otherwise empty line, possibly indented. [1]_

238

234

239

235

`For example:

240

236

241

237

`.. code-block:: ini

242

238

243

239

` [Simple Values]

244

key: value

245

spaces in keys: allowed

246

spaces in values: allowed as well

247

you can also use = to delimit keys from values

240

key=value

241

spaces in keys=allowed

242

spaces in values=allowed as well

243

spaces around the delimiter = obviously

244

you can also use : to delimit keys from values

248

245

249

246

` [All Values Are Strings]

250

247

` values like this: 1000000

`@@ -261,12 +258,14 @@ For example:

261

258

` key_without_value

262

259

` empty string value here =

263

260

264

[You can use comments] ; after a useful line

265

; in an empty line

266

after: a_value ; here's another comment

267

inside: a ;comment

268

multiline ;comment

269

value! ;comment

261

[You can use comments]

262

like this

263

; or this

264

+

265

By default only in an empty line.

266

Inline comments can be harmful because they prevent users

267

from using the delimiting characters as parts of values.

268

That being said, this can be customized.

270

269

271

270

` [Sections Can Be Indented]

272

271

`can_values_be_as_well = True

`` @@ -509,7 +508,8 @@ the :meth:__init__ options:

509

508

` ... skip-external-locking

510

509

` ... old_passwords = 1

511

510

` ... skip-bdb

512

... skip-innodb # we don't need ACID today

511

... # we don't need ACID today

512

... skip-innodb

513

` ... """

514

` >>> config = configparser.ConfigParser(allow_no_value=True)

515

` >>> config.read_string(sample_config)

`` @@ -536,28 +536,78 @@ the :meth:__init__ options:

536

` See also the space_around_delimiters argument to

537

`` :meth:ConfigParser.write.

538

539


* *comment_prefixes*, default value: ``_COMPATIBLE`` (``'#'`` valid on empty

540


 lines, ``';'`` valid also on non-empty lines)

539


* *comment_prefixes*, default value: ``('#', ';')``

541

540

542

Comment prefixes are strings that indicate the start of a valid comment

543

within a config file. The peculiar default value allows for comments starting

544


 with ``'#'`` or ``';'`` but only the latter can be used in a non-empty line.

545

This is obviously dictated by backwards compatibiliy. A more predictable

546


 approach would be to specify prefixes as ``('#', ';')`` which will allow for

547

both prefixes to be used in non-empty lines.

541


* *inline_comment_prefixes*, default value: ``None``

548

542

549

Please note that config parsers don't support escaping of comment prefixes so

550

leaving characters out of comment_prefixes is a way of ensuring they can be

551

used as parts of keys or values.

543

Comment prefixes are strings that indicate the start of a valid comment within

544

a config file. comment_prefixes are used only on otherwise empty lines

545

(optionally indented) whereas inline_comment_prefixes can be used after

546

every valid value (e.g. section names, options and empty lines as well). By

547


 default inline comments are disabled and ``'#'`` and ``';'`` are used as

548

prefixes for whole line comments.

552

549

553


* *strict*, default value: ``False``

550

.. versionchanged:: 3.2

551

`` +

In previous versions of :mod:configparser behaviour matched

552


 ``comment_prefixes=('#',';')`` and ``inline_comment_prefixes=(';',)``.

554

553

555


 If set to ``True``, the parser will not allow for any section or option

554

Please note that config parsers don't support escaping of comment prefixes so

555

using inline_comment_prefixes may prevent users from specifying option

556

values with characters used as comment prefixes. When in doubt, avoid setting

557

inline_comment_prefixes. In any circumstances, the only way of storing

558

comment prefix characters at the beginning of a line in multiline values is to

559

interpolate the prefix, for example::

560

+

561

from configparser import ConfigParser, ExtendedInterpolation

562

parser = ConfigParser(interpolation=ExtendedInterpolation())

563

the default BasicInterpolation could be used as well

564

parser.read_string("""

565

... [DEFAULT]

566

... hash = #

567

...

568

... [hashes]

569

... shebang =

570

... ${hash}!/usr/bin/env python

571

... ${hash} -- coding: utf-8 --

572

...

573

... extensions =

574

... enabled_extension

575

... another_extension

576

... #disabled_by_comment

577

... yet_another_extension

578

...

579

... interpolation not necessary = if # is not at line start

580

... even in multiline values = line #1

581

... line #2

582

... line #3

583

... """)

584

print(parser['hashes']['shebang'])

585

+

586

#!/usr/bin/env python

587

-- coding: utf-8 --

588

print(parser['hashes']['extensions'])

589

+

590

enabled_extension

591

another_extension

592

yet_another_extension

593

print(parser['hashes']['interpolation not necessary'])

594

if # is not at line start

595

print(parser['hashes']['even in multiline values'])

596

line #1

597

line #2

598

line #3

599

+

600


* *strict*, default value: ``True``

601

+

602


 When set to ``True``, the parser will not allow for any section or option

556

603

`` duplicates while reading from a single source (using :meth:read_file,

557


:meth:`read_string` or :meth:`read_dict`). The default is ``False`` only

558

because of backwards compatibility reasons. It is recommended to use strict

604

`` +

:meth:read_string or :meth:read_dict). It is recommended to use strict

559

605

` parsers in new applications.

560

606

607

.. versionchanged:: 3.2

608

`` +

In previous versions of :mod:configparser behaviour matched

609


 ``strict=False``.

610

+

561

611

``` * *empty_lines_in_values*, default value: True


`562`

`612`

``

`563`

`613`

` In config parsers, values can span multiple lines as long as they are

`

`` @@ -575,7 +625,6 @@ the :meth:`__init__` options:

``

`575`

`625`

``

`576`

`626`

`this = is still a part of the multiline value of 'key'

`

`577`

`627`

``

`578`

``

`-`

`579`

`628`

` This can be especially problematic for the user to see if she's using a

`

`580`

`629`

` proportional font to edit the file. That is why when your application does

`

`581`

`630`

` not need values with empty lines, you should consider disallowing them. This

`

`` @@ -603,8 +652,7 @@ the :meth:`__init__` options:

``

`603`

`652`

```  interpolation completely, ``ExtendedInterpolation()`` provides a more

604

653

``` advanced variant inspired by zc.buildout. More on the subject in the


`605`

`654`

``  `dedicated documentation section <#interpolation-of-values>`_.

``

`606`

``

`-`

`607`

``

``` -

.. note:: :class:`RawConfigParser` is using ``None`` by default.

655


:class:`RawConfigParser` has a default value of ``None``.

608

656

609

657

610

658

`More advanced customization may be achieved by overriding default values of

`@@ -769,7 +817,7 @@ interpolation if an option used is not defined elsewhere. ::

769

817

`ConfigParser Objects

770

818

`--------------------

771

819

772

.. class:: ConfigParser(defaults=None, dict_type=collections.OrderedDict, allow_no_value=False, delimiters=('=', ':'), comment_prefixes=_COMPATIBLE, strict=False, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT, interpolation=BasicInterpolation())

820

.. class:: ConfigParser(defaults=None, dict_type=collections.OrderedDict, allow_no_value=False, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT, interpolation=BasicInterpolation())

773

821

774

822

` The main configuration parser. When defaults is given, it is initialized

775

823

` into the dictionary of intrinsic defaults. When dict_type is given, it

`@@ -778,12 +826,15 @@ ConfigParser Objects

778

826

779

827

` When delimiters is given, it is used as the set of substrings that

780

828

` divide keys from values. When comment_prefixes is given, it will be used

781

as the set of substrings that prefix comments in a line, both for the whole

829

as the set of substrings that prefix comments in otherwise empty lines.

830

Comments can be indented. When inline_comment_prefixes is given, it will be

831

used as the set of substrings that prefix comments in non-empty lines.

832

+

782

833

` line and inline comments. For backwards compatibility, the default value for

783

834

``` *comment_prefixes* is a special value that indicates that ; and # can


`784`

`835`

```  start whole line comments while only ``;`` can start inline comments.

785

836

786


 When *strict* is ``True`` (default: ``False``), the parser won't allow for

837


 When *strict* is ``True`` (the default), the parser won't allow for

787

838

` any section or option duplicates while reading from a single source (file,

788

839

`` string or dictionary), raising :exc:DuplicateSectionError or

789

840

``` :exc:DuplicateOptionError. When *empty_lines_in_values* is False


`@@ -1043,7 +1094,7 @@ ConfigParser Objects

`

`1043`

`1094`

`RawConfigParser Objects

`

`1044`

`1095`

`-----------------------

`

`1045`

`1096`

``

`1046`

``

`-

.. class:: RawConfigParser(defaults=None, dict_type=collections.OrderedDict, allow_no_value=False, delimiters=('=', ':'), comment_prefixes=_COMPATIBLE, strict=False, empty_lines_in_values=True, default_section=configaparser.DEFAULTSECT, interpolation=None)

`

``

`1097`

`+

.. class:: RawConfigParser(defaults=None, dict_type=collections.OrderedDict, allow_no_value=False, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configaparser.DEFAULTSECT, interpolation=None)

`

`1047`

`1098`

``

`1048`

`1099`

``  Legacy variant of the :class:`ConfigParser` with interpolation disabled

``

`1049`

`1100`

```  by default and unsafe ``add_section`` and ``set`` methods.