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 中，其中最近添加的配置具有最高优先级。任何冲突的键都取自最近的配置，同时保留先前存在的键。

>>> another_config = configparser.ConfigParser()
>>> another_config.read('example.ini')
['example.ini']
>>> another_config['topsecret.server.example']['Port']
'50022'
>>> another_config.read_string("[topsecret.server.example]\nPort=48484")
>>> another_config['topsecret.server.example']['Port']
'48484'
>>> another_config.read_dict({"topsecret.server.example": {"Port": 21212}})
>>> another_config['topsecret.server.example']['Port']
'21212'
>>> another_config['topsecret.server.example']['ForwardX11']
'no'

此行为等效于调用 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。

配置文件可以包含注释，注释以特定字符（默认情况下为 # 和 ; [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?

值的插值

除了核心功能外，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%%

在上面的例子中，将 interpolation 设置为 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 处理的选项键名。这意味着默认情况下为小写键。同时，对于包含键 'a' 的节，两个表达式都返回 True

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

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

  • DEFAULTSECT 不能从解析器中删除

    • 尝试删除它会引发 ValueError，

    • parser.clear() 会保留它，

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

  • parser.get(section, option, **kwargs) - 第二个参数不是回退值。但是请注意，section 级别的 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 还提供了一个具有显式 get/set 方法的旧版 API。 虽然下面概述的方法有有效的用例，但映射协议访问是新项目的首选。 旧版 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

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

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={})

主要的配置解析器。当给定 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*() 方法。

在 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 版更改: 使用 read_dict() 读取 defaults 参数，从而在解析器中提供一致的行为：非字符串键和值将隐式转换为字符串。

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

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 参数接受 类路径对象。

在 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.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])

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

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

注意

请考虑改用 ConfigParser，它会检查要存储在内部的值的类型。如果您不希望进行插值，可以使用 ConfigParser(interpolation=None)。

add_section(section)

将名为 _section_ 的节添加到实例中。如果已存在具有给定名称的节，则引发 DuplicateSectionError。如果传递了 _默认节_ 名称，则引发 ValueError。

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

set(section, option, value)

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

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

异常

exception configparser.Error

所有其他 configparser 异常的基类。

exception configparser.NoSectionError

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

exception configparser.DuplicateSectionError

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

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

exception configparser.DuplicateOptionError

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

exception configparser.NoOptionError

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

exception configparser.InterpolationError

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

exception configparser.InterpolationDepthError

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

exception configparser.InterpolationMissingOptionError

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

exception configparser.InterpolationSyntaxError

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

exception configparser.MissingSectionHeaderError

在尝试解析没有节标题的文件时引发的异常。

exception configparser.ParsingError

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

在 3.12 版更改: 删除了 filename 属性和 __init__() 构造函数参数。自 3.2 版以来，它们一直可以使用名称 source 使用。

脚注