Python标准库configparser配置文件解析器

值的插入¶

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

class configparser.BasicInterpolation¶

默认实现由 ConfigParser 来使用。 它允许值包含引用了相同小节中其他值或者特殊的默认小节中的值的格式字符串 1。 额外的默认值可以在初始化时提供。

例如:

[Paths]
home_dir: /Users
my_dir: %(home_dir)s/lumberjack
my_pictures: %(my_dir)s/Pictures
[Escape]
gain: 80%%  # use a %% to escape the % sign (% is the only character that needs to be escaped)

在上面的例子里，ConfigParser 的 interpolation 设为 BasicInterpolation()，这会将 %(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]
cost: $$80  # use a $$ to escape the $ sign ($ is the only character that needs to be escaped)

来自其他小节的值也可以被获取:

[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}

映射协议访问¶

映射协议访问这个通用名称是指允许以字典的方式来使用自定义对象的功能。 在 configparser 中，映射接口的实现使用了 parser['section']['option'] 标记法。

parser['section'] 专门为解析器中的小节数据返回一个代理。 这意味着其中的值不会被拷贝，而是在需要时从原始解析器中获取。 更为重要的是，当值在小节代理上被修改时，它们其实是在原始解析器中发生了改变。

configparser 对象的行为会尽可能地接近真正的字典。 映射接口是完整而且遵循 MutableMapping ABC 规范的。 但是，还是有一些差异应当被纳入考虑:

• 默认情况下，小节中的所有键是以大小写不敏感的方式来访问的 1。 例如 foroptioninparser["section"] 只会产生 optionxform 形式的选项键名称。 也就是说默认使用小写字母键名。 与此同时，对于一个包含键 'a' 的小节，以下两个表达式均将返回 True:

  "a"inparser["section"]
  "A"inparser["section"]
  

• 所有小节也包括 DEFAULTSECT，这意味着对一个小节执行 .clear() 可能无法使得该小节显示为空。 这是因为默认值是无法从小节中被删除的（因为从技术上说它们并不在那里）。 如果它们在小节中被覆盖，删除将导致默认值重新变为可见。 尝试删除默认值将会引发 KeyError。

• DEFAULTSECT 无法从解析器中被移除:

  • 尝试删除将引发 ValueError，

  • parser.clear() 会保留其原状，

  • parser.popitem() 绝不会将其返回。

• parser.get(section,option,**kwargs) - 第二个参数 并非 回退值。 但是请注意小节层级的 get() 方法可同时兼容映射协议和经典配置解析器 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，默认值: collections.OrderedDict

  此选项主要影响映射协议的行为和写入配置文件的外观。 使用默认的有序字典时，每个小节是按照它们被加入解析器的顺序保存的。 在小节内的选项也是如此。

  还有其他替换的字典类型可用，例如在写回数据时对小节和选项进行排序。 你也可以出于性能原因而使用普通字典。

  请注意：也有办法通过单次操作来添加一组键值对。 当你在这些操作中使用一个常规字典时，键将按顺序进行排列，因为 dict 类型从 Python 3.7 起将会保留插入顺序。 例如:

  >>> 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']
  >>> [optionforoptioninparser['section3']]
  ['foo', 'bar', 'baz']
  

• allow_no_value，默认值: False

  已知某些配置文件会包括不带值的设置，但其在其他方面均符合 configparser 所支持的语法。 构造器的 allow_no_value 形参可用于指明应当接受这样的值:

  >>> importconfigparser
  >>> 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。 在许多情况下，在多行值的一行开头存储注释前缀字符的唯一方式是进行前缀插值，例如:

  >>> fromconfigparserimportConfigParser,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)¶

这个方法会转换每次 read, get, 或 set 操作的选项名称。 默认会将名称转换为小写形式。 这也意味着当一个配置文件被写入时，所有键都将为小写形式。 如果此行为不合适则要重载此方法。 例如:

>>> 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=lambdaoption:option
>>> custom.read_string(config)
>>> list(custom['Section1'].keys())
['Key']
>>> list(custom['Section2'].keys())
['AnotherKey']

注解

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

ConfigParser.SECTCRE¶

一个已编译正则表达式会被用来解析节标头。 默认将 [section] 匹配到名称 "section"。 空格会被视为节名称的一部分，因此 [  larch  ] 将被读取为一个名称为 "  larch  " 的节。 如果此行为不合适则要重载此属性。 例如:

>>> importre
>>> 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 在多数时候都更复杂、更底层并且完全违反直觉。

一个写入配置文件的示例:

importconfigparser
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'
withopen('example.cfg','w')asconfigfile:
config.write(configfile)

一个再次读取配置文件的示例:

importconfigparser
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().
ifconfig.getboolean('Section1','a_bool'):
print(config.get('Section1','foo'))

要获取插值，请使用 ConfigParser:

importconfigparser
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 中均可用。 它们将在当某个选项未在别处定义时被用于插值。

importconfigparser
# 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!"