源代码: Lib/configparser.py

此模块提供了它实现一种基本配置语言 ConfigParser 类，这种语言所提供的结构与 Microsoft Windows INI 文件的类似。 你可以使用这种语言来编写能够由最终用户来自定义的 Python 程序。

让我们准备一个非常基本的配置文件，它看起来是这样的:

[DEFAULT]

ServerAliveInterval = 45

Compression = yes

CompressionLevel = 9

ForwardX11 = yes

[bitbucket.org]

User = hg

[topsecret.server.com]

Port = 50022

ForwardX11 = no

总的来说，这种文件由多个节组成，每个节包含多个带有值的键。 configparser 类可以读取和写入这种文件。 让我们先通过程序方式来创建上述的配置文件。

>>> import configparser

>>> config = configparser.ConfigParser()

>>> config['DEFAULT'] = {'ServerAliveInterval': '45',

... 'Compression': 'yes',

... 'CompressionLevel': '9'}

>>> config['bitbucket.org'] = {}

>>> config['bitbucket.org']['User'] = 'hg'

>>> config['topsecret.server.com'] = {}

>>> topsecret = config['topsecret.server.com']

>>> 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)

...

如你所见，我们可以把配置解析器当作一个字典来处理。 两者确实存在差异，但是其行为非常接近于字典所具有一般行为。

现在我们已经创建并保存了一个配置文件，让我们再将它读取出来并探究其中包含的数据。

>>> import configparser

>>> config = configparser.ConfigParser()

>>> config.sections()

[]

>>> config.read('example.ini')

['example.ini']

>>> config.sections()

['bitbucket.org', 'topsecret.server.com']

>>> 'bitbucket.org' in config

True

>>> 'bytebong.com' in config

False

>>> config['bitbucket.org']['User']

'hg'

>>> config['DEFAULT']['Compression']

'yes'

>>> topsecret = config['topsecret.server.com']

>>> topsecret['ForwardX11']

'no'

>>> topsecret['Port']

'50022'

>>> for key in config['bitbucket.org']: print(key)

...

user

compressionlevel

serveraliveinterval

compression

forwardx11

>>> config['bitbucket.org']['ForwardX11']

'yes'

正如我们在上面所看到的，相关的 API 相当直观。 唯一有些神奇的地方是 DEFAULT 小节，它为所有其他小节提供了默认值。 还要注意小节中的键大小写不敏感并且会存储为小写形式。

INI 文件结构

配置文件是由小节组成的，每个小节都有一个 [section] 标头，加上多个由特定字符串 (默认为 = 或 : 1) 分隔的键/值条目。 默认情况下小节名对大小写敏感而键对大小写不敏感 1。 键和值开头和末尾的空格会被移除。 值可以被省略，在此情况下键/值分隔符也可以被省略。 值还可以跨越多行，只要其他行带有比值的第一行更深的缩进。 依据解析器的具体模式，空白行可能被视为多行值的组成部分也可能被忽略。

配置文件可以包含注释，要带有指定字符前缀 (默认为 # 和 ; )。 注释可以单独出现于原本的空白行，并可使用缩进。

ConfigParser 对象

classconfigparser.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(), 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 参数。

defaults()

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

sections()

返回可用节的列表；default section 不包括在该列表中。

add_section(section)

向实例添加一个名为 section 的节。 如果给定名称的节已存在，将会引发 DuplicateSectionError。 如果转入了 default section 名称，则会引发 ValueError。 节名称必须为字符串；如果不是则会引发 TypeError。

在 3.2 版更改:非字符串的节名称将引发 TypeError。

has_section(section)

指明相应名称的 section 是否存在于配置中。 default section 不包含在内。

options(section)

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

has_option(section, option)

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

read(filenames, encoding=None)

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

If filenames is a string or path-like object, it is treated as a single filename. If a file named in filenames cannot be opened, that file will be ignored. This is designed so that you can specify an iterable of potential configuration file locations (for example, the current directory, the user’s home directory, and some system-wide directory), and all existing configuration files in the iterable will be read.

如果名称对应的文件全都不存在，则 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。

read_file(f, source=None)

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

可选参数 source 指定要读取的文件名称。 如果未给出并且 f 具有 name 属性，则该属性会被用作 source；默认值为 '??>'。

3.2 新版功能:替代 readfp()。

read_string(string, source='')

从字符串中解析配置数据。

可选参数 source 指定一个所传入字符串的上下文专属名称。 如果未给出，则会使用 ''。 这通常应为一个文件系统路径或 URL。

3.2 新版功能.

read_dict(dictionary, source='')

从任意一个提供了类似于字典的 items() 方法的对象加载配置。 键为节名称，值为包含节中所出现的键和值的字典。 如果所用的字典类型会保留顺序，则节和其中的键将按顺序加入。 值会被自动转换为字符串。

可选参数 source 指定一个所传入字曲的上下文专属名称。 如果未给出，则会使用 。

此方法可被用于在解析器之间拷贝状态。

3.2 新版功能.

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

获取指定名称的 section 的一个 option 的值。 如果提供了 vars，则它必须为一个字典。 option 的查找顺序为 vars*(如果有提供)、*section 以及 DEFAULTSECT。 如果未找到该键并且提供了 fallback，则它会被用作回退值。 可以提供 None 作为 fallback 值。

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

在 3.2 版更改: raw, vars 和 fallback 都是仅限关键字参数，以防止用户试图使用第三个参数作业为 fallback 回退值(特别是在使用映射 协议的时候)。

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

将在 section 中指定的 option 强制转换为整数的便捷方法。 参见 get() 获取对于 raw, vars 和 fallback 的解释。

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

将在 section 中指定的 option 强制转换为浮点数的便捷方法。 参见 get() 获取对于 raw, vars 和 fallback 的解释。

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

将在指定 section 中的 option 强制转换为布尔值的便捷方法。 请注意选项所接受的值为 '1', 'yes', 'true' 和 'on'，它们会使得此方法返回 True，以及 '0', 'no', 'false' 和 'off'，它们会使得此方法返回 False。 这些字符串值会以对大小写不敏感的方式被检测。 任何其他值都将导致引发 ValueError。 参见 get() 获取对于 raw, vars 和 fallback 的解释。

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

当未给出 section 时，将返回由 section_name, section_proxy 对组成的列表，包括 DEFAULTSECT。

在其他情况下，将返回给定的 section 中的 option 的 name, value 对组成的列表。 可选参数具有与 get() 方法的参数相同的含义。

set(section, option, value)

如果给定的节存在，则将所给出的选项设为指定的值；在其他情况下将引发 NoSectionError。 option 和 value 必须为字符串；如果不是则将引发 TypeError。

write(fileobject, space_around_delimiters=True)

将配置的表示形式写入指定的 file object，该对象必须以文本模式打开(接受字符串)。 此表示形式可由将来的 read() 调用进行解析。 如果 space_around_delimiters 为真值，键和值之前的分隔符两边将加上空格。

remove_option(section, option)

将指定的 option 从指定的 section 中移除。 如果指定的节不存在则会引发 NoSectionError。 如果要移除的选项存在则返回 True；在其他情况下将返回 False。

remove_section(section)

从配置中移除指定的 section。 如果指定的节确实存在则返回 True。 在其他情况下将返回 False。

optionxform(option)

将选项名 option 转换为输入文件中的形式或客户端代码所传入的应当在内部结构中使用的形式。 默认实现将返回 option 的小写形式版本；子类可以重载此行为，或者客户端代码也可以在实例上设置一个具有此名称的属性来影响此行为。

你不需要子类化解析器来使用此方法，你也可以在一个实例上设置它，或使用一个接受字符串参数并返回字符串的函数。 例如将它设为 str 将使得选项名称变得大小写敏感:

cfgparser = ConfigParser()

cfgparser.optionxform = str

请注意当读取配置文件时，选项名称两边的空格将在调用 optionxform() 之前被去除。

readfp(fp, filename=None)

3.2 版后已移除:使用 read_file() 来代替。

在 3.2 版更改:readfp() 现在将在 fp 上执行迭代而不是调用 fp.readline()。

对于调用 readfp() 时传入不支持迭代的参数的现有代码，可以在文件类对象外使用以下生成器作为包装器:

def readline_generator(fp):

line = fp.readline()

while line:

yield line

line = fp.readline()

不再使用 parser.readfp(fp) 而是改用 parser.read_file(readline_generator(fp))。

configparser.MAX_INTERPOLATION_DEPTH当 raw 形参为假值时 get() 所采用的递归插值的最大深度。 这只在使用默认的 interpolation 时会起作用。