configparser — 配置文件解析器

源代码: Lib/configparser.py

此模块提供了 ConfigParser 类，它实现了一种基本的配置语言，该语言提供类似于 Microsoft Windows INI 文件中找到的结构。您可以使用它来编写可以由最终用户轻松自定义的 Python 程序。

注意

此库不解释或写入 Windows 注册表扩展版本 INI 语法中使用的值类型前缀。

另请参阅

模块 tomllib

TOML 是一个为应用程序配置文件精心指定的格式。它专门设计为 INI 的改进版本。

模块 shlex

支持创建类似 Unix shell 的迷你语言，这些语言也可用于应用程序配置文件。

模块 json

json 模块实现了 JavaScript 语法的子集，有时用于配置，但不支持注释。

快速入门

让我们来看一个非常基本的配置文件，如下所示

[DEFAULT]
ServerAliveInterval = 45
Compression = yes
CompressionLevel = 9
ForwardX11 = yes

[forge.example]
User = hg

[topsecret.server.example]
Port = 50022
ForwardX11 = no

INI 文件的结构在以下部分中描述。本质上，该文件由多个节组成，每个节都包含带有值的键。configparser 类可以读取和写入此类文件。让我们从以编程方式创建上述配置文件开始。

>>> import configparser
>>> config = configparser.ConfigParser()
>>> config['DEFAULT'] = {'ServerAliveInterval': '45',
...                      'Compression': 'yes',
...                      'CompressionLevel': '9'}
>>> config['forge.example'] = {}
>>> config['forge.example']['User'] = 'hg'
>>> config['topsecret.server.example'] = {}
>>> topsecret = config['topsecret.server.example']
>>> topsecret['Port'] = '50022'     # mutates the parser
>>> topsecret['ForwardX11'] = 'no'  # same here
>>> config['DEFAULT']['ForwardX11'] = 'yes'
>>> with open('example.ini', 'w') as configfile:
...   config.write(configfile)
...

如您所见，我们可以像字典一样对待配置解析器。存在一些差异，稍后概述，但行为与您期望从字典中获得的行为非常接近。

现在我们已经创建并保存了一个配置文件，让我们将其读回并探索其包含的数据。

>>> config = configparser.ConfigParser()
>>> config.sections()
[]
>>> config.read('example.ini')
['example.ini']
>>> config.sections()
['forge.example', 'topsecret.server.example']
>>> 'forge.example' in config
True
>>> 'python.org' in config
False
>>> config['forge.example']['User']
'hg'
>>> config['DEFAULT']['Compression']
'yes'
>>> topsecret = config['topsecret.server.example']
>>> topsecret['ForwardX11']
'no'
>>> topsecret['Port']
'50022'
>>> for key in config['forge.example']:  
...     print(key)
user
compressionlevel
serveraliveinterval
compression
forwardx11
>>> config['forge.example']['ForwardX11']
'yes'

如上所述，API 非常简单。唯一的神奇之处涉及 DEFAULT 节，它为所有其他节提供默认值 [1]。另请注意，节中的键不区分大小写，并以小写形式存储 [1]。

可以将多个配置读取到单个 ConfigParser 中，其中最近添加的配置具有最高优先级。任何冲突的键都取自最新的配置，同时保留先前存在的键。下面的示例读取一个 override.ini 文件，该文件将覆盖 example.ini 文件中的任何冲突键。

[DEFAULT]
ServerAliveInterval = -1

>>> config_override = configparser.ConfigParser()
>>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}
>>> with open('override.ini', 'w') as configfile:
...     config_override.write(configfile)
...
>>> config_override = configparser.ConfigParser()
>>> config_override.read(['example.ini', 'override.ini'])
['example.ini', 'override.ini']
>>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
-1

此行为等效于调用 ConfigParser.read() 并将多个文件传递给 *filenames* 参数。

支持的数据类型

配置解析器不会猜测配置文件中值的数据类型，始终将其在内部存储为字符串。这意味着如果您需要其他数据类型，则应自行转换

>>> int(topsecret['Port'])
50022
>>> float(topsecret['CompressionLevel'])
9.0

由于此任务非常常见，因此配置解析器提供了一系列方便的 getter 方法来处理整数、浮点数和布尔值。最后一个是最有趣的，因为简单地将值传递给 bool() 将毫无用处，因为 bool('False') 仍然是 True。这就是为什么配置解析器还提供 getboolean() 的原因。此方法不区分大小写，并从 'yes'/ 'no'、 'on'/ 'off'、 'true'/ 'false' 和 '1'/ '0' 识别布尔值 [1]。例如

>>> topsecret.getboolean('ForwardX11')
False
>>> config['forge.example'].getboolean('ForwardX11')
True
>>> config.getboolean('forge.example', 'Compression')
True

除了 getboolean() 之外，配置解析器还提供等效的 getint() 和 getfloat() 方法。您可以注册自己的转换器并自定义提供的转换器。[1]

回退值

与字典一样，您可以使用节的 get() 方法提供回退值

>>> topsecret.get('Port')
'50022'
>>> topsecret.get('CompressionLevel')
'9'
>>> topsecret.get('Cipher')
>>> topsecret.get('Cipher', '3des-cbc')
'3des-cbc'

请注意，默认值优先于回退值。例如，在我们的示例中，'CompressionLevel' 键仅在 'DEFAULT' 节中指定。如果我们尝试从 'topsecret.server.example' 节获取它，我们将始终获得默认值，即使我们指定了回退值

>>> topsecret.get('CompressionLevel', '3')
'9'

另一个需要注意的事情是，解析器级别的 get() 方法提供了一个自定义的、更复杂的接口，该接口是为了向后兼容而维护的。使用此方法时，可以通过 fallback 仅关键字参数提供回退值

>>> config.get('forge.example', 'monster',
...            fallback='No such things as monsters')
'No such things as monsters'

相同的 fallback 参数可以与 getint()、 getfloat() 和 getboolean() 方法一起使用，例如

>>> 'BatchMode' in topsecret
False
>>> topsecret.getboolean('BatchMode', fallback=True)
True
>>> config['DEFAULT']['BatchMode'] = 'no'
>>> topsecret.getboolean('BatchMode', fallback=True)
False

支持的 INI 文件结构

配置文件由节组成，每个节都以 [section] 标头开头，后跟键/值条目，这些条目由特定字符串分隔（默认情况下为 = 或 : [1]）。默认情况下，节名称区分大小写，但键不区分大小写 [1]。前导和尾随空格将从键和值中删除。如果配置解析器允许，则可以省略值 [1]，在这种情况下，也可以省略键/值分隔符。只要它们比值的首行缩进得更深，值也可以跨越多行。根据解析器的模式，空行可以视为多行值的一部分或被忽略。

默认情况下，有效的节名称可以是任何不包含“\n”的字符串。要更改此设置，请参阅 ConfigParser.SECTCRE。

如果解析器配置为允许使用 allow_unnamed_section=True 的未命名顶层节，则可以省略第一个节的名称。在这种情况下，可以通过 UNNAMED_SECTION 来检索键/值，如 config[UNNAMED_SECTION] 中所示。

配置文件可以包含注释，注释以特定字符为前缀（默认情况下为 # 和 ; [1]）。注释可以单独出现在空行上，也可以缩进。[1]

例如

[Simple Values]
key=value
spaces in keys=allowed
spaces in values=allowed as well
spaces around the delimiter = obviously
you can also use : to delimit keys from values

[All Values Are Strings]
values like this: 1000000
or this: 3.14159265359
are they treated as numbers? : no
integers, floats and booleans are held as: strings
can use the API to get converted values directly: true

[Multiline Values]
chorus: I'm a lumberjack, and I'm okay
    I sleep all night and I work all day

[No Values]
key_without_value
empty string value here =

[You can use comments]
# like this
; or this

# By default only in an empty line.
# Inline comments can be harmful because they prevent users
# from using the delimiting characters as parts of values.
# That being said, this can be customized.

    [Sections Can Be Indented]
        can_values_be_as_well = True
        does_that_mean_anything_special = False
        purpose = formatting for readability
        multiline_values = are
            handled just fine as
            long as they are indented
            deeper than the first line
            of a value
        # Did I mention we can indent comments, too?

未命名的节

可以省略第一个节（或唯一节）的名称，并通过 UNNAMED_SECTION 属性检索值。

>>> config = """
... option = value
...
... [  Section 2  ]
... another = val
... """
>>> unnamed = configparser.ConfigParser(allow_unnamed_section=True)
>>> unnamed.read_string(config)
>>> unnamed.get(configparser.UNNAMED_SECTION, 'option')
'value'

值的插值

除了核心功能之外，ConfigParser 还支持插值。这意味着可以在从 get() 调用返回之前对值进行预处理。

class configparser.BasicInterpolation

ConfigParser 使用的默认实现。它允许值包含格式字符串，这些字符串引用同一节中的其他值或特殊默认节中的值[1]。可以在初始化时提供其他默认值。

例如

[Paths]
home_dir: /Users
my_dir: %(home_dir)s/lumberjack
my_pictures: %(my_dir)s/Pictures

[Escape]
# use a %% to escape the % sign (% is the only character that needs to be escaped):
gain: 80%%

在上面的示例中，将插值设置为 BasicInterpolation() 的 ConfigParser 会将 %(home_dir)s 解析为 home_dir 的值（在本例中为 /Users）。 %(my_dir)s 实际上会解析为 /Users/lumberjack。所有插值都是按需完成的，因此在引用链中使用的键不必在配置文件中按任何特定顺序指定。

如果将 interpolation 设置为 None，则解析器将简单地返回 %(my_dir)s/Pictures 作为 my_pictures 的值，以及 %(home_dir)s/lumberjack 作为 my_dir 的值。

class configparser.ExtendedInterpolation

一种用于插值的替代处理程序，它实现了更高级的语法，例如在 zc.buildout 中使用的语法。扩展插值使用 ${section:option} 来表示来自外部节的值。插值可以跨越多个级别。为方便起见，如果省略 section: 部分，则插值默认为当前节（并且可能来自特殊节的默认值）。

例如，上面指定的具有基本插值的配置，如果使用扩展插值，则如下所示

[Paths]
home_dir: /Users
my_dir: ${home_dir}/lumberjack
my_pictures: ${my_dir}/Pictures

[Escape]
# use a $$ to escape the $ sign ($ is the only character that needs to be escaped):
cost: $$80

也可以获取其他节的值

[Common]
home_dir: /Users
library_dir: /Library
system_dir: /System
macports_dir: /opt/local

[Frameworks]
Python: 3.2
path: ${Common:system_dir}/Library/Frameworks/

[Arthur]
nickname: Two Sheds
last_name: Jackson
my_dir: ${Common:home_dir}/twosheds
my_pictures: ${my_dir}/Pictures
python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}

映射协议访问

在 3.2 版本中添加。

映射协议访问是使自定义对象像字典一样使用的功能的通用名称。对于 configparser，映射接口实现使用 parser['section']['option'] 表示法。

特别是，parser['section'] 返回解析器中节数据的代理。这意味着值不会被复制，而是按需从原始解析器中获取。更重要的是，当在节代理上更改值时，它们实际上是在原始解析器中进行修改的。

configparser 对象的行为尽可能接近实际字典。映射接口是完整的，并遵循 MutableMapping ABC。但是，有一些差异应该考虑在内

  • 默认情况下，节中的所有键都可以以不区分大小写的方式访问[1]。例如，for option in parser["section"] 仅生成 optionxform 'ed 选项键名称。这意味着默认情况下是小写的键。同时，对于包含键 'a' 的节，两个表达式都返回 True

    "a" in parser["section"]
"A" in parser["section"]

  • 所有节都包括 DEFAULTSECT 值，这意味着节上的 .clear() 可能不会使该节看起来为空。这是因为默认值无法从节中删除（因为从技术上讲它们不存在）。如果它们在节中被覆盖，则删除会导致默认值再次可见。尝试删除默认值会导致 KeyError。

  • 无法从解析器中删除 DEFAULTSECT

    • 尝试删除它会引发 ValueError，

    • parser.clear() 会使其保持不变，

    • parser.popitem() 永远不会返回它。

  • parser.get(section, option, **kwargs) - 第二个参数不是后备值。但是请注意，节级别的 get() 方法与映射协议和经典的 configparser API 都兼容。

  • parser.items() 与映射协议兼容（返回 section_name、section_proxy 对的列表，包括 DEFAULTSECT）。但是，也可以使用参数调用此方法：parser.items(section, raw, vars)。后一个调用返回指定 section 的 option、value 对的列表，其中所有插值都已展开（除非提供了 raw=True）。

映射协议是在现有旧版 API 之上实现的，因此子类覆盖原始接口仍然应该使映射按预期工作。

自定义解析器行为

INI 格式变体几乎与使用它的应用程序一样多。configparser 在为可用的最大合理 INI 样式集提供支持方面做了很多工作。默认功能主要由历史背景决定，您很可能需要自定义某些功能。

更改特定配置解析器工作方式的最常见方法是使用 __init__() 选项

  • defaults，默认值：None

    此选项接受键值对的字典，该字典将最初放置在 DEFAULT 节中。这为支持简洁的配置文件提供了一种优雅的方式，该文件不指定与文档化默认值相同的值。

    提示：如果要为特定节指定默认值，请在读取实际文件之前使用 read_dict()。

  • dict_type，默认值：dict

    此选项对映射协议的行为方式以及写入的配置文件的外观有重大影响。对于标准字典，每个节都按照它们添加到解析器的顺序存储。节内的选项也是如此。

    例如，可以使用替代字典类型来对写回时的节和选项进行排序。

    请注意：有多种方法可以在单个操作中添加一组键值对。在这些操作中使用常规字典时，键的顺序将被排序。例如

    >>> parser = configparser.ConfigParser()
>>> parser.read_dict({'section1': {'key1': 'value1',
...                                'key2': 'value2',
...                                'key3': 'value3'},
...                   'section2': {'keyA': 'valueA',
...                                'keyB': 'valueB',
...                                'keyC': 'valueC'},
...                   'section3': {'foo': 'x',
...                                'bar': 'y',
...                                'baz': 'z'}
... })
>>> parser.sections()
['section1', 'section2', 'section3']
>>> [option for option in parser['section3']]
['foo', 'bar', 'baz']

  • allow_no_value，默认值：False

    已知某些配置文件包含没有值的设置，但这些设置在其他方面符合 configparser 支持的语法。可以使用构造函数的 allow_no_value 参数来指示应接受此类值

    >>> import configparser

>>> sample_config = """
... [mysqld]
...   user = mysql
...   pid-file = /var/run/mysqld/mysqld.pid
...   skip-external-locking
...   old_passwords = 1
...   skip-bdb
...   # we don't need ACID today
...   skip-innodb
... """
>>> config = configparser.ConfigParser(allow_no_value=True)
>>> config.read_string(sample_config)

>>> # Settings with values are treated as before:
>>> config["mysqld"]["user"]
'mysql'

>>> # Settings without values provide None:
>>> config["mysqld"]["skip-bdb"]

>>> # Settings which aren't specified still raise an error:
>>> config["mysqld"]["does-not-exist"]
Traceback (most recent call last):
  ...
KeyError: 'does-not-exist'

  • delimiters，默认值：('=', ':')

    分隔符是分隔节内键和值的子字符串。一行中第一次出现的分隔子字符串被视为分隔符。这意味着值（但不是键）可以包含分隔符。

    另请参阅 ConfigParser.write() 的 space_around_delimiters 参数。

  • comment_prefixes，默认值：('#', ';')

  • inline_comment_prefixes，默认值：None

    注释前缀是指在配置文件中指示有效注释开始的字符串。comment_prefixes 仅用于（可选缩进的）空行，而 inline_comment_prefixes 可用于每个有效值之后（例如，节名称、选项和空行）。默认情况下，禁用行内注释，并且 '#' 和 ';' 用作整行注释的前缀。

    在 3.2 版本中更改: 在早期版本的 configparser 中，行为与 comment_prefixes=('#',';') 和 inline_comment_prefixes=(';',) 相匹配。

    请注意，配置解析器不支持转义注释前缀，因此使用 inline_comment_prefixes 可能会阻止用户指定使用注释前缀字符的选项值。如有疑问，请避免设置 inline_comment_prefixes。在任何情况下，在多行值的开头存储注释前缀字符的唯一方法是插值前缀，例如

    >>> from configparser import ConfigParser, ExtendedInterpolation
>>> parser = ConfigParser(interpolation=ExtendedInterpolation())
>>> # the default BasicInterpolation could be used as well
>>> parser.read_string("""
... [DEFAULT]
... hash = #
...
... [hashes]
... shebang =
...   ${hash}!/usr/bin/env python
...   ${hash} -*- coding: utf-8 -*-
...
... extensions =
...   enabled_extension
...   another_extension
...   #disabled_by_comment
...   yet_another_extension
...
... interpolation not necessary = if # is not at line start
... even in multiline values = line #1
...   line #2
...   line #3
... """)
>>> print(parser['hashes']['shebang'])

#!/usr/bin/env python
# -*- coding: utf-8 -*-
>>> print(parser['hashes']['extensions'])

enabled_extension
another_extension
yet_another_extension
>>> print(parser['hashes']['interpolation not necessary'])
if # is not at line start
>>> print(parser['hashes']['even in multiline values'])
line #1
line #2
line #3

  • strict，默认值：True

    当设置为 True 时，解析器在从单个源读取时（使用 read_file()、 read_string() 或 read_dict()）不允许任何节或选项重复。建议在新应用程序中使用严格的解析器。

    在 3.2 版本中更改: 在早期版本的 configparser 中，行为与 strict=False 相匹配。

  • empty_lines_in_values，默认值：True

    在配置解析器中，只要它们比包含它们的键缩进更多，值就可以跨越多行。默认情况下，解析器还允许空行作为值的一部分。同时，键本身可以任意缩进以提高可读性。因此，当配置文件变得庞大而复杂时，用户很容易迷失文件的结构。例如

    [Section]
key = multiline
  value with a gotcha

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

    如果用户使用比例字体来编辑文件，这尤其会成为问题。这就是为什么当您的应用程序不需要带有空行的值时，您应该考虑禁止它们。这将使空行每次都分割键。在上面的示例中，它将产生两个键：key 和 this。

  • default_section，默认值：configparser.DEFAULTSECT （即："DEFAULT"）

    允许其他节或插值目的使用默认值的特殊节的约定是此库的一个强大概念，它允许用户创建复杂的声明式配置。此节通常称为 "DEFAULT"，但可以自定义为指向任何其他有效的节名称。一些典型的值包括："general" 或 "common"。提供的名称用于在从任何源读取时识别默认节，并在将配置写回文件时使用。可以使用 parser_instance.default_section 属性检索其当前值，并且可以在运行时进行修改（即，将文件从一种格式转换为另一种格式）。

  • interpolation，默认值：configparser.BasicInterpolation

    可以通过 interpolation 参数提供自定义处理程序来自定义插值行为。None 可用于完全关闭插值，ExtendedInterpolation() 提供了一个受 zc.buildout 启发的更高级变体。有关该主题的更多信息，请参见 专用文档部分。RawConfigParser 的默认值为 None。

  • converters，默认值：未设置

    配置解析器提供执行类型转换的选项值获取器。默认情况下，实现了 getint()、getfloat() 和 getboolean()。如果需要其他获取器，用户可以在子类中定义它们，或者传递一个字典，其中每个键是转换器的名称，每个值是实现所述转换的可调用对象。例如，传递 {'decimal': decimal.Decimal} 将在解析器对象和所有节代理上添加 getdecimal()。换句话说，可以同时写入 parser_instance.getdecimal('section', 'key', fallback=0) 和 parser_instance['section'].getdecimal('key', 0)。

    如果转换器需要访问解析器的状态，则可以将其实现为配置解析器子类的方法。如果此方法的名称以 get 开头，它将在所有节代理上以与字典兼容的形式提供（请参阅上面的 getdecimal() 示例）。

通过覆盖这些解析器属性的默认值可以实现更高级的自定义。默认值在类上定义，因此可以通过子类或属性赋值来覆盖它们。

ConfigParser.BOOLEAN_STATES

默认情况下，当使用 getboolean() 时，配置解析器认为以下值 True：'1'、'yes'、'true'、'on'，以及以下值 False：'0'、'no'、'false'、'off'。您可以通过指定自定义的字符串及其布尔结果字典来覆盖此设置。例如

>>> custom = configparser.ConfigParser()
>>> custom['section1'] = {'funky': 'nope'}
>>> custom['section1'].getboolean('funky')
Traceback (most recent call last):
...
ValueError: Not a boolean: nope
>>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}
>>> custom['section1'].getboolean('funky')
False

其他典型的布尔值对包括 accept/reject 或 enabled/disabled。

ConfigParser.optionxform(option)

此方法在每次读取、获取或设置操作时转换选项名称。默认值将名称转换为小写。这也意味着当写入配置文件时，所有键都将小写。如果这不合适，请覆盖此方法。例如

>>> config = """
... [Section1]
... Key = Value
...
... [Section2]
... AnotherKey = Value
... """
>>> typical = configparser.ConfigParser()
>>> typical.read_string(config)
>>> list(typical['Section1'].keys())
['key']
>>> list(typical['Section2'].keys())
['anotherkey']
>>> custom = configparser.RawConfigParser()
>>> custom.optionxform = lambda option: option
>>> custom.read_string(config)
>>> list(custom['Section1'].keys())
['Key']
>>> list(custom['Section2'].keys())
['AnotherKey']

注意

optionxform 函数将选项名称转换为规范形式。这应该是一个幂等函数：如果名称已经采用规范形式，则应将其返回而不做更改。

ConfigParser.SECTCRE

一个编译后的正则表达式，用于解析节标题。默认值将 [section] 匹配到名称 "section"。空格被视为节名称的一部分，因此 [  larch  ] 将被读取为名称为 "  larch  " 的节。如果这不合适，请覆盖此属性。例如

>>> import re
>>> config = """
... [Section 1]
... option = value
...
... [  Section 2  ]
... another = val
... """
>>> typical = configparser.ConfigParser()
>>> typical.read_string(config)
>>> typical.sections()
['Section 1', '  Section 2  ']
>>> custom = configparser.ConfigParser()
>>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]")
>>> custom.read_string(config)
>>> custom.sections()
['Section 1', 'Section 2']

注意

虽然 ConfigParser 对象还使用 OPTCRE 属性来识别选项行，但不建议覆盖它，因为这会干扰构造函数选项 allow_no_value 和 delimiters。

旧版 API 示例

主要是出于向后兼容性的考虑，configparser 还提供了一个旧版 API，其中包含显式的 get/set 方法。虽然下面概述的方法存在有效的用例，但对于新项目，首选映射协议访问。旧版 API 有时更高级、更底层且完全违反直觉。

写入配置文件的示例

import configparser

config = configparser.RawConfigParser()

# Please note that using RawConfigParser's set functions, you can assign
# non-string values to keys internally, but will receive an error when
# attempting to write to a file or when you get it in non-raw mode. Setting
# values using the mapping protocol or ConfigParser's set() does not allow
# such assignments to take place.
config.add_section('Section1')
config.set('Section1', 'an_int', '15')
config.set('Section1', 'a_bool', 'true')
config.set('Section1', 'a_float', '3.1415')
config.set('Section1', 'baz', 'fun')
config.set('Section1', 'bar', 'Python')
config.set('Section1', 'foo', '%(bar)s is %(baz)s!')

# Writing our configuration file to 'example.cfg'
with open('example.cfg', 'w') as configfile:
    config.write(configfile)

再次读取配置文件的示例

import configparser

config = configparser.RawConfigParser()
config.read('example.cfg')

# getfloat() raises an exception if the value is not a float
# getint() and getboolean() also do this for their respective types
a_float = config.getfloat('Section1', 'a_float')
an_int = config.getint('Section1', 'an_int')
print(a_float + an_int)

# Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.
# This is because we are using a RawConfigParser().
if config.getboolean('Section1', 'a_bool'):
    print(config.get('Section1', 'foo'))

要获取插值，请使用 ConfigParser

import configparser

cfg = configparser.ConfigParser()
cfg.read('example.cfg')

# Set the optional *raw* argument of get() to True if you wish to disable
# interpolation in a single get operation.
print(cfg.get('Section1', 'foo', raw=False))  # -> "Python is fun!"
print(cfg.get('Section1', 'foo', raw=True))   # -> "%(bar)s is %(baz)s!"

# The optional *vars* argument is a dict with members that will take
# precedence in interpolation.
print(cfg.get('Section1', 'foo', vars={'bar': 'Documentation',
                                       'baz': 'evil'}))

# The optional *fallback* argument can be used to provide a fallback value
print(cfg.get('Section1', 'foo'))
      # -> "Python is fun!"

print(cfg.get('Section1', 'foo', fallback='Monty is not.'))
      # -> "Python is fun!"

print(cfg.get('Section1', 'monster', fallback='No such things as monsters.'))
      # -> "No such things as monsters."

# A bare print(cfg.get('Section1', 'monster')) would raise NoOptionError
# but we can also use:

print(cfg.get('Section1', 'monster', fallback=None))
      # -> None

默认值在两种类型的 ConfigParser 中都可用。如果未在其他地方定义使用的选项，则在插值中使用它们。

import configparser

# New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each
config = configparser.ConfigParser({'bar': 'Life', 'baz': 'hard'})
config.read('example.cfg')

print(config.get('Section1', 'foo'))     # -> "Python is fun!"
config.remove_option('Section1', 'bar')
config.remove_option('Section1', 'baz')
print(config.get('Section1', 'foo'))     # -> "Life is hard!"

ConfigParser 对象

class configparser.ConfigParser(defaults=None, dict_type=dict, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT, interpolation=BasicInterpolation(), converters={}, allow_unnamed_section=False)

主要的配置解析器。当提供 defaults 时，它会被初始化到固有默认值的字典中。当提供 dict_type 时，它将被用来创建用于节列表、节内选项以及默认值的字典对象。

当提供 delimiters 时，它被用作分隔键和值的子字符串集合。当提供 comment_prefixes 时，它将被用作在空行中注释的前缀子字符串集合。注释可以缩进。当提供 inline_comment_prefixes 时，它将被用作在非空行中注释的前缀子字符串集合。

当 strict 为 True (默认值) 时，解析器在从单个来源（文件、字符串或字典）读取时不允许任何节或选项重复，会引发 DuplicateSectionError 或 DuplicateOptionError。当 empty_lines_in_values 为 False (默认值: True) 时，每个空行都标记一个选项的结束。否则，多行选项的内部空行将作为值的一部分保留。当 allow_no_value 为 True (默认值: False) 时，接受没有值的选项；这些选项的值为 None，并且在序列化时不会带有尾随的分隔符。

当提供 default_section 时，它指定用于保存其他节和插值用途的默认值的特殊节的名称（通常命名为 "DEFAULT"）。可以使用 default_section 实例属性在运行时检索和更改此值。这不会重新评估已解析的配置文件，但会在将解析的设置写入新配置文件时使用。

可以通过 interpolation 参数提供自定义处理程序来自定义插值行为。None 可用于完全关闭插值，ExtendedInterpolation() 提供了受 zc.buildout 启发的更高级变体。有关此主题的更多信息，请参阅专门的文档部分。

在插值中使用的所有选项名称都将像任何其他选项名称引用一样，通过 optionxform() 方法传递。例如，使用 optionxform() 的默认实现（将选项名称转换为小写），值 foo %(bar)s 和 foo %(BAR)s 是等效的。

当提供 converters 时，它应该是一个字典，其中每个键代表类型转换器的名称，每个值是一个可调用对象，该对象实现从字符串到所需数据类型的转换。每个转换器都在解析器对象和节代理上拥有自己对应的 get*() 方法。

当 allow_unnamed_section 为 True (默认值: False) 时，可以省略第一个节名称。请参阅 “未命名节”部分。

可以将多个配置读取到单个 ConfigParser 中，其中最近添加的配置具有最高优先级。任何冲突的键都取自最新的配置，同时保留先前存在的键。下面的示例读取一个 override.ini 文件，该文件将覆盖 example.ini 文件中的任何冲突键。

[DEFAULT]
ServerAliveInterval = -1

>>> config_override = configparser.ConfigParser()
>>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}
>>> with open('override.ini', 'w') as configfile:
...     config_override.write(configfile)
...
>>> config_override = configparser.ConfigParser()
>>> config_override.read(['example.ini', 'override.ini'])
['example.ini', 'override.ini']
>>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
-1

在 3.1 版本中更改: 默认的 dict_type 是 collections.OrderedDict。

在 3.2 版本中更改: 添加了 allow_no_value，delimiters，comment_prefixes，strict，empty_lines_in_values，default_section 和 interpolation。

在 3.5 版本中更改: 添加了 converters 参数。

在 3.7 版本中更改: defaults 参数使用 read_dict() 读取，在解析器中提供一致的行为：非字符串键和值隐式转换为字符串。

在 3.8 版本中更改: 默认的 dict_type 是 dict，因为它现在保留了插入顺序。

在 3.13 版本中更改: 当 allow_no_value 为 True，并且一个没有值的键继续使用缩进行时，会引发 MultilineContinuationError。

在 3.13 版本中更改: 添加了 allow_unnamed_section 参数。

defaults()

返回一个包含实例范围默认值的字典。

sections()

返回可用节的列表；*默认节* 不包含在列表中。

add_section(section)

将名为 section 的节添加到实例。如果已存在具有给定名称的节，则会引发 DuplicateSectionError。如果传递了 *默认节* 名称，则会引发 ValueError。节的名称必须是字符串；如果不是，则会引发 TypeError。

在 3.2 版本中更改: 非字符串节名称会引发 TypeError。

has_section(section)

指示名为 section 的节是否存在于配置中。*默认节* 不会被识别。

options(section)

返回指定 section 中可用选项的列表。

has_option(section, option)

如果给定的 section 存在，并且包含给定的 option，则返回 True；否则返回 False。如果指定的 section 为 None 或空字符串，则假定为 DEFAULT。

read(filenames, encoding=None)

尝试读取和解析一个文件名可迭代对象，并返回一个成功解析的文件名列表。

如果 filenames 是一个字符串、一个 bytes 对象或一个路径类对象，则将其视为单个文件名。如果 filenames 中命名的文件无法打开，则该文件将被忽略。这样做是为了您可以指定一个潜在的配置文件位置的可迭代对象（例如，当前目录、用户的主目录和一些系统范围的目录），并且将读取可迭代对象中所有现有的配置文件。

如果所有命名的文件都不存在，则 ConfigParser 实例将包含一个空数据集。一个需要从文件加载初始值的应用程序应该在为任何可选文件调用 read() 之前，使用 read_file() 加载所需的文件。

import configparser, os

config = configparser.ConfigParser()
config.read_file(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],
            encoding='cp1250')

在 3.2 版本中变更: 添加了 encoding 形参。 此前，所有文件都使用 open() 的默认编码读取。

在 3.6.1 版本中变更: filenames 形参接受一个 path-like object。

在 3.7 版本中变更: filenames 形参接受一个 bytes 对象。

read_file(f, source=None)

从 *f* 读取并解析配置数据，*f* 必须是一个产生 Unicode 字符串的可迭代对象（例如以文本模式打开的文件）。

可选参数 *source* 指定正在读取的文件的名称。 如果未给出且 *f* 具有 name 属性，则该属性将用于 *source*； 默认值为 '<???>'。

在 3.2 版本中新增: 取代 readfp()。

read_string(string, source='<string>')

从字符串解析配置数据。

可选参数 *source* 指定所传递字符串的特定上下文名称。 如果未给出，则使用 '<string>'。 这通常应是文件系统路径或 URL。

在 3.2 版本中添加。

read_dict(dictionary, source='<dict>')

从任何提供类似字典的 items() 方法的对象加载配置。 键是节名称，值是字典，其中包含应存在于节中的键和值。 如果使用的字典类型保留顺序，则将按顺序添加节及其键。 值会自动转换为字符串。

可选参数 *source* 指定所传递字典的特定上下文名称。 如果未给出，则使用 <dict>。

此方法可用于在解析器之间复制状态。

在 3.2 版本中添加。

get(section, option, *, raw=False, vars=None[, fallback])

获取指定 *section* 的 *option* 值。 如果提供了 *vars*，则它必须是一个字典。 将按照 *vars*（如果提供）、*section* 和 *DEFAULTSECT* 的顺序查找 *option*。 如果找不到键且提供了 *fallback*，则将其用作回退值。 可以将 None 提供作为 *fallback* 值。

除非 *raw* 参数为 true，否则将在返回值中展开所有 '%' 插值。 插值键的值的查找方式与选项相同。

在 3.2 版本中变更: 参数 *raw*、*vars* 和 *fallback* 仅是关键字参数，以防止用户尝试将第三个参数用作 *fallback* 回退（尤其是在使用映射协议时）。

getint(section, option, *, raw=False, vars=None[, fallback])

一个便捷方法，它将指定 *section* 中的 *option* 强制转换为整数。 有关 *raw*、*vars* 和 *fallback* 的说明，请参阅 get()。

getfloat(section, option, *, raw=False, vars=None[, fallback])

一个便捷方法，它将指定 *section* 中的 *option* 强制转换为浮点数。 有关 *raw*、*vars* 和 *fallback* 的说明，请参阅 get()。

getboolean(section, option, *, raw=False, vars=None[, fallback])

一个便捷方法，它将指定 *section* 中的 *option* 强制转换为布尔值。 请注意，该选项接受的值为 '1'、'yes'、'true' 和 'on'，这将导致此方法返回 True，而 '0'、'no'、'false' 和 'off' 会导致它返回 False。 这些字符串值会以不区分大小写的方式进行检查。 任何其他值都会导致它引发 ValueError。 有关 *raw*、*vars* 和 *fallback* 的说明，请参阅 get()。

items(raw=False, vars=None)
items(section, raw=False, vars=None)

当未给出 *section* 时，返回 section_name、section_proxy 对的列表，包括 DEFAULTSECT。

否则，返回给定 *section* 中选项的 name、value 对的列表。 可选参数与 get() 方法的含义相同。

在 3.8 版本中变更: *vars* 中存在的项不再显示在结果中。 先前的行为将实际解析器选项与为插值提供的变量混合在一起。

set(section, option, value)

如果给定的节存在，则将给定的选项设置为指定的值； 否则引发 NoSectionError。 *option* 和 *value* 必须是字符串； 如果不是，则引发 TypeError。

write(fileobject, space_around_delimiters=True)

将配置的表示形式写入指定的 文件对象，该对象必须以文本模式打开（接受字符串）。 此表示形式可由将来的 read() 调用解析。 如果 *space_around_delimiters* 为 true，则键和值之间的分隔符将用空格包围。

注意

将配置写回时，不会保留原始配置文件中的注释。 什么被视为注释，取决于给定的 *comment_prefix* 和 *inline_comment_prefix* 的值。

remove_option(section, option)

从指定的 *section* 中删除指定的 *option*。 如果该节不存在，则引发 NoSectionError。 如果存在要删除的选项，则返回 True；否则返回 False。

remove_section(section)

从配置中删除指定的 *section*。 如果该节确实存在，则返回 True。 否则返回 False。

optionxform(option)

转换在输入文件中找到的或由客户端代码传入的选项名 option，使其成为内部结构中应使用的形式。默认实现返回 option 的小写版本；子类可以覆盖此行为，或者客户端代码可以在实例上设置此名称的属性来影响此行为。

您无需子类化解析器即可使用此方法，也可以在实例上将其设置为一个函数，该函数接受一个字符串参数并返回一个字符串。例如，将其设置为 str，将使选项名称区分大小写。

cfgparser = ConfigParser()
cfgparser.optionxform = str

请注意，在读取配置文件时，会在调用 optionxform() 之前，删除选项名称周围的空格。

configparser.UNNAMED_SECTION

一个特殊的对象，表示用于引用未命名部分的部分名称（请参阅未命名部分）。

configparser.MAX_INTERPOLATION_DEPTH

当 raw 参数为 false 时，get() 递归插值的最大深度。仅当使用默认的 interpolation 时才相关。

RawConfigParser 对象

class configparser.RawConfigParser(defaults=None, dict_type=dict, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT, interpolation=BasicInterpolation(), converters={}, allow_unnamed_section=False)

ConfigParser 的旧版本。它默认禁用插值，并通过其不安全的 add_section 和 set 方法以及旧的 defaults= 关键字参数处理，允许使用非字符串节名称、选项名称和值。

在 3.2 版本中更改: 添加了 allow_no_value，delimiters，comment_prefixes，strict，empty_lines_in_values，default_section 和 interpolation。

在 3.5 版本中更改: 添加了 converters 参数。

在 3.8 版本中更改: 默认的 dict_type 是 dict，因为它现在保留了插入顺序。

在 3.13 版本中更改: 添加了 allow_unnamed_section 参数。

注意

考虑使用 ConfigParser 来代替，它会检查内部存储的值的类型。如果您不想要插值，可以使用 ConfigParser(interpolation=None)。

add_section(section)

向实例添加名为 section 的节。如果已存在具有给定名称的节，则会引发 DuplicateSectionError。如果传递的是 默认节 名称，则会引发 ValueError。

不检查 section 的类型，这允许用户创建非字符串命名的节。此行为不受支持，并可能导致内部错误。

set(section, option, value)

如果给定节存在，则将给定选项设置为指定值；否则引发 NoSectionError。虽然可以使用 RawConfigParser （或 ConfigParser，并将 raw 参数设置为 true）来 内部 存储非字符串值，但只有使用字符串值才能实现全部功能（包括插值和输出到文件）。

此方法允许用户在内部将非字符串值分配给键。此行为不受支持，并且在尝试写入文件或在非原始模式下获取时会导致错误。请使用映射协议 API，该 API 不允许进行此类分配。

异常

exception configparser.Error

所有其他 configparser 异常的基类。

exception configparser.NoSectionError

当找不到指定的节时引发的异常。

exception configparser.DuplicateSectionError

如果使用已存在的节的名称调用 add_section()，或者在严格解析器中，如果在单个输入文件、字符串或字典中多次找到节，则会引发此异常。

在 3.2 版本中更改: 向 __init__() 添加了可选的 source 和 lineno 属性和参数。

exception configparser.DuplicateOptionError

如果单个选项在从单个文件、字符串或字典读取期间出现两次，则由严格解析器引发的异常。这会捕获拼写错误和与大小写敏感性相关的错误，例如，字典可能具有两个键，表示相同的不区分大小写的配置键。

exception configparser.NoOptionError

当在指定节中找不到指定选项时引发的异常。

exception configparser.InterpolationError

执行字符串插值时出现问题时引发的异常的基类。

exception configparser.InterpolationDepthError

当字符串插值无法完成，因为迭代次数超过 MAX_INTERPOLATION_DEPTH 时引发的异常。InterpolationError 的子类。

exception configparser.InterpolationMissingOptionError

当从值引用的选项不存在时引发的异常。InterpolationError 的子类。

异常 configparser.InterpolationSyntaxError

当进行替换的源文本不符合所需的语法时引发的异常。 是 InterpolationError 的子类。

异常 configparser.MissingSectionHeaderError

当尝试解析没有节头的文件时引发的异常。

异常 configparser.ParsingError

当尝试解析文件时发生错误时引发的异常。

在 3.12 版本中变更：filename 属性和 __init__() 构造函数参数已被移除。 自 3.2 版本以来，它们已使用 source 名称提供。

异常 configparser.MultilineContinuationError

当没有对应值的键以缩进行继续时引发的异常。

在 3.13 版本中新增。

脚注