13.2. 配置解析器 — 配置文件解析器

笔记

ConfigParser 模块已在 Python 3 中重命名为 configparser。 2to3 工具将在将您的源代码转换为 Python 3 时自动调整导入。

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

笔记

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

也可以看看

模块 shlex: 支持创建类 Unix shell 的迷你语言，可用作应用程序配置文件的替代格式。
模块 json: json 模块实现了 JavaScript 语法的一个子集，也可用于此目的。

配置文件由部分组成，由 [section] 标头引导，后跟 name: value 条目，并以 RFC 822 样式的延续（参见第 3.1.1 节，“长标题字段”）； name=value 也被接受。请注意，从值中删除了前导空格。可选值可以包含引用同一部分中其他值的格式字符串，或特殊 DEFAULT 部分中的值。可以在初始化和检索时提供其他默认值。以 '#' 或 ';' 开头的行将被忽略并可用于提供注释。

配置文件可能包含注释，以特定字符为前缀（# 和 ;）。注释可以单独出现在空行中，也可以在包含值或节名称的行中输入。在后一种情况下，它们前面需要有一个空格字符才能被识别为注释。（为了向后兼容，只有 ; 开始行内注释，而 # 没有。）

在核心功能之上，SafeConfigParser 支持插值。这意味着值可以包含引用同一部分中其他值的格式字符串，或特殊 DEFAULT 部分中的值。可以在初始化时提供其他默认值。

例如：

[My Section]
foodir: %(dir)s/whatever
dir=frob
long: this value continues
   in the next line

会将 %(dir)s 解析为 dir 的值（在本例中为 frob）。所有参考扩展都是按需完成的。

默认值可以通过将它们作为字典传递到 ConfigParser 构造函数来指定。其他默认值可能会传递到 get() 方法中，该方法将覆盖所有其他默认值。

部分通常存储在内置字典中。可以将替代字典类型传递给 ConfigParser 构造函数。例如，如果传递了对其键进行排序的字典类型，则这些部分将在回写时排序，每个部分中的键也将如此。

class ConfigParser.RawConfigParser([defaults[, dict_type[, allow_no_value]]])

基本配置对象。当给出 defaults 时，它被初始化为内在默认值字典。当给出 dict_type 时，它将用于为节列表、节中的选项和默认值创建字典对象。当 allow_no_value 为 true（默认：False）时，接受没有值的选项；为这些显示的值是 None。

此类不支持神奇的插值行为。

所有选项名称都通过 optionxform() 方法传递。它的默认实现将选项名称转换为小写。

2.3 版中的新功能。

2.6 版更改：添加了 dict_type。

2.7 版更改：默认 dict_type 为 collections.OrderedDict。添加了 allow_no_value。

class ConfigParser.ConfigParser([defaults[, dict_type[, allow_no_value]]])

RawConfigParser 的派生类，它实现了神奇的插值功能并向 get() 和 items() 方法添加了可选参数。 defaults 中的值必须适用于 %()s 字符串插值。注意 __name__ 是一个内在的默认值；它的值是部分名称，并将覆盖 defaults 中提供的任何值。

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

2.3 版中的新功能。

2.6 版更改：添加了 dict_type。

2.7 版更改：默认 dict_type 为 collections.OrderedDict。添加了 allow_no_value。

class ConfigParser.SafeConfigParser([defaults[, dict_type[, allow_no_value]]]): ConfigParser 的派生类，它实现了神奇插值功能的更健全的变体。这种实现也更具可预测性。如果新应用程序不需要与旧版本的 Python 兼容，它们应该更喜欢这个版本。

2.3 版中的新功能。

2.6 版更改：添加了 dict_type。

2.7 版更改：默认 dict_type 为 collections.OrderedDict。添加了 allow_no_value。

exception ConfigParser.Error: 所有其他 configparser 异常的基类。

exception ConfigParser.NoSectionError: 未找到指定部分时引发异常。

exception ConfigParser.DuplicateSectionError: 如果使用已经存在的部分的名称调用 add_section()，则会引发异常。

exception ConfigParser.NoOptionError: 在指定部分中找不到指定选项时引发异常。

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

exception ConfigParser.InterpolationDepthError: 由于迭代次数超过 MAX_INTERPOLATION_DEPTH，因此无法完成字符串插值时引发异常。 InterpolationError 的子类。

exception ConfigParser.InterpolationMissingOptionError: 从值引用的选项不存在时引发异常。 InterpolationError 的子类。

2.3 版中的新功能。

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

2.3 版中的新功能。

exception ConfigParser.MissingSectionHeaderError: 尝试解析没有节头的文件时引发异常。

exception ConfigParser.ParsingError: 尝试解析文件时发生错误时引发异常。

ConfigParser.MAX_INTERPOLATION_DEPTH: 当 raw 参数为 false 时，get() 递归插值的最大深度。这仅与 ConfigParser 类相关。

也可以看看

模块 shlex: 支持创建类 Unix shell 的迷你语言，可用作应用程序配置文件的替代格式。

13.2.1. RawConfigParser 对象

RawConfigParser 实例有以下方法：

RawConfigParser.defaults(): 返回一个包含实例范围默认值的字典。

RawConfigParser.sections(): 返回可用部分的列表； DEFAULT 未包含在列表中。

RawConfigParser.add_section(section): 将名为 section 的部分添加到实例。如果给定名称的部分已经存在，则会引发 DuplicateSectionError。如果名称 DEFAULT（或其任何不区分大小写的变体）被传递，则会引发 ValueError。

RawConfigParser.has_section(section): 指示命名部分是否存在于配置中。 DEFAULT 部分未被确认。

RawConfigParser.options(section): 返回指定部分中可用的选项列表。

RawConfigParser.has_option(section, option): 如果给定的部分存在，并且包含给定的选项，则返回 True; 否则返回 False。

1.6 版中的新功能。

RawConfigParser.read(filenames)

尝试读取和解析文件名列表，返回成功解析的文件名列表。如果 filenames 是字符串或 Unicode 字符串，则将其视为单个文件名。如果无法打开以 filenames 命名的文件，则该文件将被忽略。这样做的目的是让您可以指定潜在配置文件位置的列表（例如，当前目录、用户的主目录和某些系统范围的目录），并且将读取列表中的所有现有配置文件。如果命名文件都不存在，ConfigParser 实例将包含一个空数据集。需要从文件加载初始值的应用程序应在调用任何可选文件的 read() 之前使用 readfp() 加载所需的一个或多个文件：

import ConfigParser, os

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

2.4 版更改：返回成功解析的文件名列表。

RawConfigParser.readfp(fp[, filename]): 从 fp 中的文件或类文件对象读取和解析配置数据（仅使用 readline() 方法）。如果省略 filename 并且 fp 具有 name 属性，则用于 filename；默认值为 <???>。

RawConfigParser.get(section, option): 为命名的部分获取选项值。

RawConfigParser.getint(section, option): 将指定部分中的选项强制为整数的便捷方法。

RawConfigParser.getfloat(section, option): 将指定的部分中的选项强制转换为浮点数的便捷方法。

RawConfigParser.getboolean(section, option): 将指定的部分中的选项强制为布尔值的便捷方法。请注意，该选项的可接受值为 "1"、"yes"、"true" 和 "on"，这会导致此方法返回 True ，以及 "0"、"no"、"false" 和 "off"，这会导致它返回 False。这些字符串值以不区分大小写的方式进行检查。任何其他值都会使其升高 ValueError。

RawConfigParser.items(section): 返回给定部分中每个选项的 (name, value) 对列表。

RawConfigParser.set(section, option, value): 如果给定部分存在，则将给定选项设置为指定值；否则引发 NoSectionError。虽然可以使用 RawConfigParser（或 ConfigParser 将 raw 参数设置为 true）用于 internal 非字符串值的存储，全部功能（包括插值和输出到文件）只能使用字符串值来实现。

1.6 版中的新功能。

RawConfigParser.write(fileobject): 将配置的表示写入指定的文件对象。这种表示可以通过未来的 read() 调用来解析。

1.6 版中的新功能。

RawConfigParser.remove_option(section, option): 从指定的节中删除指定的选项。如果该部分不存在，则引发 NoSectionError。如果存在要删除的选项，则返回 True; 否则返回 False。

1.6 版中的新功能。

RawConfigParser.remove_section(section): 从配置中删除指定的部分。如果该部分确实存在，则返回 True。否则返回 False。

RawConfigParser.optionxform(option)

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

您不一定需要对 ConfigParser 进行子类化才能使用此方法，您还可以在实例上将其重新设置为采用字符串参数的函数。例如，将其设置为 str 会使选项名称区分大小写：

cfgparser = ConfigParser()
...
cfgparser.optionxform = str

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

13.2.2. ConfigParser 对象

ConfigParser 类扩展了 RawConfigParser 接口的一些方法，添加了一些可选参数。

ConfigParser.get(section, option[, raw[, vars]])

为命名的部分获取选项值。如果提供了 vars，它必须是一个字典。 option 在 vars（如果提供）、section 和 defaults 中按该顺序查找。

所有 '%' 插值都在返回值中展开，除非 raw 参数为真。以与选项相同的方式查找插值键的值。

ConfigParser.items(section[, raw[, vars]]): 返回给定部分中每个选项的 (name, value) 对列表。可选参数与 get() 方法具有相同的含义。

2.3 版中的新功能。

13.2.3. SafeConfigParser 对象

SafeConfigParser 类实现了与 ConfigParser 相同的扩展接口，但增加了以下内容：

SafeConfigParser.set(section, option, value): 如果给定部分存在，则将给定选项设置为指定值；否则引发 NoSectionError。 value 必须是字符串（str 或 unicode）；如果不是，则 TypeError 升高。

2.4 版中的新功能。

13.2.4. 例子

写入配置文件的示例：

import ConfigParser

config = ConfigParser.RawConfigParser()

# When adding sections or items, add them in the reverse order of
# how you want them to be displayed in the actual file.
# In addition, please note that using RawConfigParser's and the raw
# mode of ConfigParser's respective 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. SafeConfigParser 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', 'wb') 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 或 SafeConfigParser：

import ConfigParser

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

# Set the third, optional argument of get to 1 if you wish to use raw mode.
print config.get('Section1', 'foo', 0)  # -> "Python is fun!"
print config.get('Section1', 'foo', 1)  # -> "%(bar)s is %(baz)s!"

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

默认值在所有三种类型的 ConfigParsers 中都可用。如果使用的选项没有在别处定义，它们将用于插值。

import ConfigParser

# New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each
config = ConfigParser.SafeConfigParser({'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!"

下面的功能 opt_move 可用于在部分之间移动选项：

def opt_move(config, section1, section2, option):
    try:
        config.set(section2, option, config.get(section1, option, 1))
    except ConfigParser.NoSectionError:
        # Create non-existent section
        config.add_section(section2)
        opt_move(config, section1, section2, option)
    else:
        config.remove_option(section1, option)

已知一些配置文件包含没有值的设置，但它们符合 ConfigParser 支持的语法。构造函数的 allow_no_value 参数可用于指示应接受此类值：

>>> import ConfigParser
>>> import io

>>> sample_config = """
... [mysqld]
... user = mysql
... pid-file = /var/run/mysqld/mysqld.pid
... skip-external-locking
... old_passwords = 1
... skip-bdb
... skip-innodb
... """
>>> config = ConfigParser.RawConfigParser(allow_no_value=True)
>>> config.readfp(io.BytesIO(sample_config))

>>> # Settings with values are treated as before:
>>> config.get("mysqld", "user")
'mysql'

>>> # Settings without values provide None:
>>> config.get("mysqld", "skip-bdb")

>>> # Settings which aren't specified still raise an error:
>>> config.get("mysqld", "does-not-exist")
Traceback (most recent call last):
  ...
ConfigParser.NoOptionError: No option 'does-not-exist' in section: 'mysqld'