You are here:  Home » Python » configparser配置文件解析器(2)Python文件格式(必读进阶Python教程)(参考资料)

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

注意

这个库并没有解释或写在INI语法的Windows注册表扩展版本中使用的值类型的前缀。

也可以看看

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

快速入门

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

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

[bitbucket.org]
User = hg

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

 

INI文件的结构将在下一节中介绍。本质上,该文件由部分组成,每个部分包含带值的键。 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)
...

 

如您所见,我们可以将配置解析器视为字典。稍后概述了差异,但行为非常接近您对字典的期望。

现在我们已经创建并保存了一个配置文件,让我们回读它并探索它所拥有的数据。

>>> 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为所有其他部分提供默认值的部分[1]。另请注意,部分中的键不区分大小写并以小写形式存储[1]。

支持的数据类型

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

>>> 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['bitbucket.org'].getboolean('ForwardX11')
True
>>> config.getboolean('bitbucket.org', '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.com',即使我们指定了后备,我们也将始终获得默认值:

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

 

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

>>> config.get('bitbucket.org', '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] )。注释可能会出现在其他空行上,可能是缩进的。[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的插值

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

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

例如:

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

 

在上面的例子中,ConfigParser内插设置为 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

configparser.ExtendedInterpolation
用于插值的替代处理程序,用于实现更高级的语法,例如用于zc.buildout。扩展插值${section:option}用于表示来自外部区域的值。插值可以跨越多个级别。为方便起见,如果section:省略该 部分,则插值默认为当前部分(可能还有特殊部分的默认值)。

例如,上面使用基本插值指定的配置看起来像扩展插值:

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

 

也可以获取其他部分的值:

[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对象的行为尽可能接近实际的字典。映射界面已完成并且符合 MutableMappingABC。但是,应该考虑一些差异:

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

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

     

  • 所有部分都包括DEFAULTSECT值,这意味着 .clear()在一个部分可能不会使该部分明显为空。这是因为无法从该部分删除默认值(因为从技术上讲它们不在那里)。如果它们在部分中被覆盖,则删除会导致默认值再次可见。尝试删除默认值会导致a KeyError

  • DEFAULTSECT 无法从解析器中删除:

    • 试图删除它加注ValueError
    • parser.clear() 保持原样,
    • parser.popitem() 永远不会回来。
  • parser.get(section, option, **kwargs)– 第二个参数不是 后备值。但请注意,节级get()方法与映射协议和经典configparser API兼容。

  • parser.items()与映射协议兼容(返回section_namesection_proxy对的列表, 包括DEFAULTSECT)。但是,也可以使用参数调用此方法:。后一个调用返回一个指定的选项对列表,所有插值都被展开(除非 提供)。parser.items(section, raw, vars)sectionraw=True

映射协议是在现有遗留API的基础上实现的,因此覆盖原始接口的子类仍应具有按预期工作的映射。

自定义分析器行为

有几乎与使用它的应用程序一样多的INI格式变体。 configparser有很长的路要走,为最大的合理INI风格提供支持。默认功能主要取决于历史背景,您很可能希望自定义某些功能。

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

  • 默认值,默认值:None

    此选项接受键值对的字典,该字典最初将放在该DEFAULT部分中。这使得支持简洁配置文件的优雅方式不会指定与记录的默认值相同的值。

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

  • dict_type,默认值:collections.OrderedDict

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

    可以使用替代字典类型来对回写的部分和选项进行排序。出于性能原因,您还可以使用常规字典。

    请注意:有一些方法可以在一次操作中添加一组键值对。在这些操作中使用常规字典时,键的顺序可能是随机的。例如:

    >>> 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()  
    ['section3', 'section2', 'section1']
    >>> [option for option in parser['section3']] 
    ['baz', 'foo', 'bar']

     

    在这些操作中,您还需要使用有序字典:

    >>> from collections import OrderedDict
    >>> parser = configparser.ConfigParser()
    >>> parser.read_dict(
    ...   OrderedDict((
    ...     ('s1',
    ...      OrderedDict((
    ...        ('1', '2'),
    ...        ('3', '4'),
    ...        ('5', '6'),
    ...      ))
    ...     ),
    ...     ('s2',
    ...      OrderedDict((
    ...        ('a', 'b'),
    ...        ('c', 'd'),
    ...        ('e', 'f'),
    ...      ))
    ...     ),
    ...   ))
    ... )
    >>> parser.sections()  
    ['s1', 's2']
    >>> [option for option in parser['s1']]  
    ['1', '3', '5']
    >>> [option for option in parser['s2'].values()]  
    ['b', 'd', 'f']

     

  • 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'

     

  • 分隔符,默认值:('=', ':')

    分隔符是从字符串中的值分隔键的子字符串。一行中第一次出现的分隔子字符串被视为分隔符。这意味着值(但不是键)可以包含分隔符。

    另请参见space_around_delimiters参数 ConfigParser.write()

  • comment_prefixes,默认值:('#', ';')

  • inline_comment_prefixes,默认值:None

    注释前缀是指示配置文件中有效注释的开始的字符串。comment_prefixes仅用于其他空行(可选地缩进),而inline_comment_prefixes可用于每个有效值之后(例如,节名称,选项和空行)。默认情况下,内联注释被禁用,'#'';'用作整行注释的前缀。

    在版本3.2中更改:在先前版本的configparser行为匹配 comment_prefixes=('#',';')inline_comment_prefixes=(';',)

    请注意,配置解析器不支持转义注释前缀,因此使用inline_comment_prefix可能会阻止用户使用带有用作注释前缀的字符指定选项值。如有疑问,请避免设置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

  • 严格,默认值: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'

     

    对于用户来说,这可能是特别成问题的,以查看她是否使用比例字体来编辑文件。这就是为什么当您的应用程序不需要空行值时,您应该考虑禁止它们。这将使每行空行分割键。在上面的例子中,它会产生两个键,keythis

  • default_section,默认值:configparser.DEFAULTSECT(即: "DEFAULT"

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

  • 插值,默认值:configparser.BasicInterpolation

    可以通过插值参数提供自定义处理程序来定制插值行为。None可用于完全关闭插值,ExtendedInterpolation()提供更高级的变体灵感zc.buildout。有关专题文档部分中有关此主题的更多信息。 RawConfigParser默认值为None

  • 转换器,默认值:未设置

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

    如果转换器需要访问解析器的状态,则可以将其实现为配置解析器子类上的方法。如果此方法的名称以该方法的名称开头get,则它将在所有区段代理中以dict兼容形式提供(请参阅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

 

其他典型的布尔对包括acceptreject或 enableddisabled

ConfigParser.optionxform选项
此方法在每次读取,获取或设置操作时转换选项名称。默认情况下,将名称转换为小写。这也意味着在编写配置文件时,所有键都将为小写。如果这不合适,请覆盖此方法。例如:

>>> 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']

 

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_valuedelimiters

旧版API示例

主要是因为向后兼容性问题,configparser 还提供了带有显式getset方法的遗留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.ConfigParserdefaults = Nonedict_type = dictallow_no_value = Falsedelimiters =(’=’‘:’)comment_prefixes =(’#’‘;’)inline_comment_prefixes = Nonestrict = Trueempty_lines_in_values = Truedefault_section = configparser.DEFAULTSECTinterpolation = BasicInterpolation()converters = {} 
主要配置解析器。当给出默认值时,它将初始化为内部默认值字典。当给出dict_type时,它将用于为节的列表,节中的选项和默认值创建字典对象。

当给定分隔符时,它被用作从值中划分键的子串集合。当给出comment_prefixes时,它将被用作在其他空行中为注释添加前缀的子字符串集。评论可以缩进。当给出inline_comment_prefixes时,它将用作在非空行中为注释添加前缀的子字符串集。

strictTrue(默认值)时,解析器在从单个源(文件,字符串或字典)读取时,不允许任何部分或选项重复,引发DuplicateSectionError或 DuplicateOptionError。当empty_lines_in_valuesFalse (默认值:)时True,每个空行标记选项的结尾。否则,多行选项的内部空行将保留为值的一部分。当allow_no_valueTrue(默认值:)时False,接受没有值的选项; 为这些保留的值是None,并且序列化没有尾随分隔符。

当给出default_section时,它指定特殊部分的名称,其中包含其他部分的默认值和插值目的(通常命名"DEFAULT")。可以使用default_sectioninstance属性在运行时检索和更改此值。

可以通过插值参数提供自定义处理程序来定制插值行为。None可用于完全关闭插值,ExtendedInterpolation()提供更高级的变体灵感zc.buildout。有关专题文档部分中有关此主题的更多信息 。

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

转换器给出,它应该是一个字典,其中每个键表示一个类型的转换器的名称和每一个值是一个可调用的执行从字符串中的转化为期望的数据类型。每个转换器都get*()在解析器对象和节代理上获得自己的相应方法。

版本3.1中更改:默认dict_typecollections.OrderedDict

在版本3.2中更改:添加了allow_no_valuedelimiterscomment_prefixesstrictempty_lines_in_valuesdefault_sectioninterpolation

在3.5版本中改为:转换器加入争论。

改变在3.7版本:默认参数读取read_dict(),整个分析器提供一致的行为:非字符串键和值隐式转换为字符串。

版本3.7中更改:默认dict_typedict,因为它现在保留了插入顺序。

defaults
返回包含实例范围默认值的字典。
sections
返回可用部分的列表; 在默认的部分不包括在列表中。
add_section部分
将名为section的节添加到实例中。如果已存在给定名称的节,DuplicateSectionError则引发该节。如果传递了 默认部分名称,ValueError则引发。该部分的名称必须是一个字符串; 如果没有,TypeError就会被提出来。

在版本3.2中更改:非字符串部分名称引发TypeError

has_section部分
指示配置中是否存在命名部分。该默认部分没有被确认。
options部分
返回指定部分中可用选项的列表。
has_option部分选项
如果给定的部分存在,并包含给定的选项,则返回 True; 否则返回False。如果指定的 部分None空字符串,则假定为DEFAULT。
read文件名编码=无
尝试读取和解析可迭代的文件名,返回已成功解析的文件名列表。

如果文件名是字符串,bytes对象或类似 路径的对象,则将其视为单个文件名。如果无法打开文件名中指定的文件,则将忽略该文件。这样设计使您可以指定可迭代的潜在配置文件位置(例如,当前目录,用户的主目录和某个系统范围的目录),并且将读取iterable中的所有现有配置文件。

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

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:编码参数。以前,使用默认编码读取所有文件open()

在新版本3.6.1:文件名参数接受路径状物体

新的版本3.7:文件名参数接受一个bytes对象。

read_filefsource = None 
f读取和解析配置数据,该数据必须是可迭代的,产生Unicode字符串(例如,以文本模式打开的文件)。

可选参数source指定要读取的文件的名称。如果没有给出,f有一个name属性,那就用于  ; 默认是'<???>'

版本3.2中的新功能:替换readfp()

read_stringstringsource ='<string>’ 
从字符串中解析配置数据。

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

版本3.2中的新功能。

read_dictdictionarysource ='<dict>’ 
从提供类似dict的items() 方法的任何对象加载配置。键是节名称,值是带有键的字典和应该出现在节中的值。如果使用的字典类型保留顺序,则将按顺序添加节及其键。值会自动转换为字符串。

可选参数source指定传递的字典的特定于上下文的名称。如果没有给出,<dict>则使用。

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

版本3.2中的新功能。

getsectionoption*raw = Falsevars = None [fallback 
获取指定部分选项值。如果提供了变量,则它必须是字典。该选项vars(如果提供), sectionDEFAULTSECT中以该顺序查找。如果未找到密钥并提供回退,则将其用作回退值。 可以作为后备值提供。None

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

在版本3.2中更改:参数rawvarsfallback仅用于保护用户不要尝试使用第三个参数作为退回退(特别是在使用映射协议时)。

getintsectionoption*raw = Falsevars = None [fallback 
一种方便的方法,它将指定部分中选项强制 转换为整数。有关原始变量和 后备的解释,请参阅。get()
getfloatsectionoption*raw = Falsevars = None [fallback 
一种便捷方法,它将指定部分中选项强制 转换为浮点数。有关原始, 变量后备的解释,请参阅。get()
getbooleansectionoption*raw = Falsevars = None [fallback 
一种便捷方法,它将指定部分中选项强制 转换为布尔值。需要注意的是该选项的接受值是 ,,,和,导致该方法返回,和,,,和,这导致它返回。以不区分大小写的方式检查这些字符串值。任何其他值都会导致它升高 。有关原始变量和 后备的解释,请参阅。'1''yes''true''on'True'0''no''false''off'FalseValueErrorget()
itemsraw = Falsevars = None 
itemssectionraw = Falsevars = None 
如果未给出section,则返回section_name, section_proxy对的列表,包括DEFAULTSECT。

否则,返回给定部分中选项的名称对列表。可选参数与方法具有相同的含义 。get()

set部分选项价值
如果给定部分存在,则将给定选项设置为指定值; 否则加薪NoSectionError。 选项必须是字符串; 如果没有,TypeError就会被提出来。
writefileobjectspace_around_delimiters = True 
将配置的表示写入指定的文件对象,该文件对象必须以文本模式打开(接受字符串)。此表示可以通过将来的read()调用进行解析。如果 space_around_delimiters为true,则键和值之间的分隔符将由空格包围。
remove_option部分选项
从指定的部分中删除指定的选项。如果该部分不存在,请加注。如果存在要删除的选项,则返回; 否则返回 。NoSectionErrorTrueFalse
remove_section部分
从配置中删除指定的部分。如果该部分实际存在,则返回True。否则返回False
optionxform选项
转换在输入文件中找到的选项名称选项,或者由客户端代码传递到应在内部结构中使用的表单。默认实现返回选项的小写版本 ; 子类可以覆盖它,或者客户端代码可以在实例上设置此名称的属性以影响此行为。

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

cfgparser = ConfigParser()
cfgparser.optionxform = str

 

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

readfpfpfilename =无

从版本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
get()raw 参数为false 时,递归插值的最大深度。仅在使用默认插值时才有意义 。

RawConfigParser对象

class configparser.RawConfigParserdefaults = Nonedict_type = dictallow_no_value = False*delimiters =(’=’‘:’)comment_prefixes =(’#’‘;’)inline_comment_prefixes = Nonestrict = Trueempty_lines_in_values =是的default_section = configparser.DEFAULTSECT [插值
遗产变种ConfigParser。它默认禁用插值,并通过其不安全add_sectionset方法以及legacy defaults=关键字参数处理允许非字符串节名称,选项名称和值。

版本3.7中更改:默认dict_typedict,因为它现在保留了插入顺序。

注意

考虑使用ConfigParser哪种方法检查要在内部存储的值的类型。如果您不想插值,可以使用ConfigParser(interpolation=None)

add_section部分
将名为section的节添加到实例中。如果已存在给定名称的节,DuplicateSectionError则引发该节。如果传递了 默认部分名称,ValueError则引发。

类型部分不检查,它可以让用户创建一个名为段非字符串。此行为不受支持,可能会导致内部错误。

set部分选项价值
如果给定部分存在,则将给定选项设置为指定值; 否则加薪NoSectionError。虽然可以使用RawConfigParser(或ConfigParser原始参数设置为true)用于非字符串值的内部存储,但只能使用字符串值实现完整功能(包括内插和输出到文件)。

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

 异常

异常configparser.Error
所有其他configparser例外的基类。
异常configparser.NoSectionError
找不到指定的部分时引发异常。
异常configparser.DuplicateSectionError
如果add_section()在单个输入文件,字符串或字典中多次找到一个部分时,如果使用已存在的部分的名称调用异常解析器,则会引发异常。

版本3.2中的新增内容:添加了可选项source以及lineno属性和参数 __init__()

异常configparser.DuplicateOptionError
如果在从单个文件,字符串或字典读取期间出现两次选项,则严格解析器会引发异常。这会捕获拼写错误和区分大小写的错误,例如,字典可能有两个键,表示相同的不区分大小写的配置键。
异常configparser.NoOptionError
在指定的部分中找不到指定的选项时引发异常。
异常configparser.InterpolationError
执行字符串插值时出现问题时引发异常的基类。
异常configparser.InterpolationDepthError
由于迭代次数超过,无法完成字符串插值时引发异常MAX_INTERPOLATION_DEPTH。子类 InterpolationError
异常configparser.InterpolationMissingOptionError
从值引用的选项不存在时引发异常。子类InterpolationError
异常configparser.InterpolationSyntaxError
当进行替换的源文本不符合所需语法时引发异常。子类InterpolationError
异常configparser.MissingSectionHeaderError
尝试解析没有节标题的文件时引发异常。
异常configparser.ParsingError
尝试解析文件时发生错误时引发异常。

改变在3.2版本:filename属性和__init__()参数已更名为 source以保持一致性。

脚注

[1] 12345678910配置解析器允许重定制。如果您对更改脚注引用所概述的行为感兴趣,请参阅“ 自定义分析器行为”部分。