configparser — Парсер конфигурационных файлов¶

Быстрый старт¶

Возьмем очень простой конфигурационный файл, который выглядит следующим образом:

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

[bitbucket.org]
User = hg

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

Структура файлов INI описана in the following section. По сути, файл состоит из секций, каждая из которых содержит ключи со значениями. Классы 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)
...

Как вы видите, мы можем обращаться с парсером конфигурации так же, как со словарем. Есть различия, outlined later, но поведение очень близко к тому, что вы ожидаете от словаря.

Теперь, когда мы создали и сохранили файл конфигурации, давайте прочитаем его и изучим содержащиеся в нем данные.

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

Можно считывать несколько конфигураций в одну ConfigParser, где самая последняя добавленная конфигурация имеет наивысший приоритет. Все конфликтующие ключи берутся из последней конфигурации, а ранее существовавшие ключи сохраняются.

>>> another_config = configparser.ConfigParser()
>>> another_config.read('example.ini')
['example.ini']
>>> another_config['topsecret.server.com']['Port']
'50022'
>>> another_config.read_string("[topsecret.server.com]\nPort=48484")
>>> another_config['topsecret.server.com']['Port']
'48484'
>>> another_config.read_dict({"topsecret.server.com": {"Port": 21212}})
>>> another_config['topsecret.server.com']['Port']
'21212'
>>> another_config['topsecret.server.com']['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['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, в этом случае разделитель ключ/значение также может быть опущен. Значения также могут занимать несколько строк, при условии, что они имеют отступ глубже, чем первая строка значения. В зависимости от режима работы синтаксического анализатора пустые строки могут рассматриваться как части многострочных значений или игнорироваться.

По умолчанию, допустимым именем секции может быть любая строка, не содержащая „\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%%

В приведенном выше примере 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.

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}

Картографический протокол доступа¶

Доступ по протоколу отображения - это общее название для функциональности, которая позволяет использовать пользовательские объекты так, как если бы они были словарями. В случае configparser реализация интерфейса отображения использует нотацию parser['section']['option'].

parser['section'], в частности, возвращает прокси для данных секции в парсере. Это означает, что значения не копируются, а берутся из исходного парсера по требованию. Что еще более важно, так это то, что когда значения изменяются в прокси секции, они фактически изменяются в исходном парсере.

Объекты configparser ведут себя настолько близко к реальным словарям, насколько это возможно. Интерфейс отображения является полным и придерживается MutableMapping ABC. Однако есть несколько отличий, которые следует принять во внимание:

• По умолчанию все ключи в секциях доступны без учета регистра 1. Например, for option in parser["section"] дает только optionxform’ed имена ключей опций. Это означает, что по умолчанию клавиши в нижнем регистре. В то же время, для секции, содержащей ключ 'a', оба выражения возвращают True:

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

• Все секции также включают значения DEFAULTSECT, что означает, что .clear() на секции может не оставить секцию видимой пустой. Это происходит потому, что значения по умолчанию не могут быть удалены из секции (потому что технически их там нет). Если они переопределены в разделе, удаление приведет к тому, что значение по умолчанию снова станет видимым. Попытка удалить значение по умолчанию вызывает ошибку KeyError.

• DEFAULTSECT не может быть удален из синтаксического анализатора:

  • попытка удалить его вызывает ошибку ValueError,

  • parser.clear() оставляет его нетронутым,

  • parser.popitem() никогда не возвращает его.

• parser.get(section, option, **kwargs) - второй аргумент не является значением отката. Обратите внимание, что методы get() на уровне секций совместимы как с протоколом отображения, так и с классическим API configparser.

• parser.items() совместим с протоколом отображения (возвращает список пар section_name, section_proxy, включая DEFAULTSECT). Однако этот метод может быть вызван и с аргументами: parser.items(section, raw, vars). Последний вызов возвращает список пар option, value для указанного section, со всеми интерполяциями (если не указано 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'
  

• разделители, значение по умолчанию: ('=', ':')

  Разделители - это подстроки, которые отделяют ключи от значений внутри раздела. Первое появление разделительной подстроки в строке считается разделителем. Это означает, что значения (но не ключи) могут содержать разделители.

  См. также аргумент 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_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
  

• строго, значение по умолчанию: 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 и может быть изменено во время выполнения (например, для преобразования файлов из одного формата в другой).

• интерполяция, значение по умолчанию: configparser.BasicInterpolation

  Поведение интерполяции может быть настроено путем предоставления пользовательского обработчика через аргумент interpolation. None можно использовать для полного отключения интерполяции, ExtendedInterpolation() предоставляет более продвинутый вариант, вдохновленный zc.buildout. Подробнее об этом в dedicated documentation section. RawConfigParser имеет значение по умолчанию None.

• конвертеры, значение по умолчанию: не установлено

  Парсеры конфигурации предоставляют геттеры значений опций, которые выполняют преобразование типов. По умолчанию реализованы getint(), getfloat() и getboolean(). Если нужны другие геттеры, пользователь может определить их в подклассе или передать словарь, где каждый ключ - это имя конвертера, а каждое значение - вызываемый модуль, реализующий это преобразование. Например, передача {'decimal': decimal.Decimal} добавит getdecimal() как на объект парсера, так и на все прокси секции. Другими словами, можно будет написать как parser_instance.getdecimal('section', 'key', fallback=0), так и parser_instance['section'].getdecimal('key', 0).

  Если конвертеру необходимо получить доступ к состоянию парсера, его можно реализовать как метод подкласса парсера config. Если имя этого метода начинается с 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

Другие типичные булевы пары включают 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.

Примеры Legacy API¶

В основном из-за проблем обратной совместимости, configparser также предоставляет унаследованный API с явными методами get/set. Несмотря на то, что для методов, описанных ниже, существуют обоснованные случаи использования, для новых проектов предпочтительнее доступ по протоколу отображения. Унаследованный 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. Подробнее об этом в dedicated documentation section.

Все имена опций, используемые в интерполяции, будут передаваться через метод 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: Добавлен аргумент конвертеры.

Изменено в версии 3.7: Аргумент defaults считывается с помощью read_dict(), обеспечивая согласованное поведение парсера: нестроковые ключи и значения неявно преобразуются в строки.

Изменено в версии 3.8: По умолчанию dict_type - dict, поскольку теперь сохраняется порядок вставки.

defaults()¶

Возвращает словарь, содержащий значения по умолчанию для всего экземпляра.

sections()¶

Возвращает список доступных секций; секция по умолчанию не включается в список.

add_section(section)¶

Добавляет секцию с именем section к экземпляру. Если секция с заданным именем уже существует, выдается сообщение DuplicateSectionError. Если передано имя секции по умолчанию, выдается сообщение ValueError. Имя секции должно быть строкой; если это не так, выдается сообщение TypeError.

Изменено в версии 3.2: Нестроковые имена секций вызывают ошибку TypeError.

has_section(section)¶

Указывает, присутствует ли названный раздел в конфигурации. Раздел по умолчанию не подтверждается.

options(section)¶

Возвращает список опций, доступных в указанном разделе.

has_option(section, option)¶

Если заданный раздел существует и содержит заданную опцию, возвращается True; иначе возвращается False. Если указанный раздел равен None или является пустой строкой, принимается значение DEFAULT.

read(filenames, encoding=None)¶

Попытка прочитать и разобрать итерабельную таблицу имен файлов, возвращая список имен файлов, которые были успешно разобраны.

Если filenames является строкой, объектом bytes или path-like object, то оно рассматривается как одно имя файла. Если файл, указанный в filenames, не может быть открыт, этот файл будет проигнорирован. Это сделано для того, чтобы вы могли указать итерацию потенциальных мест расположения конфигурационных файлов (например, текущий каталог, домашний каталог пользователя и некоторый общесистемный каталог), и все существующие конфигурационные файлы в итерации будут прочитаны.

Если ни один из названных файлов не существует, экземпляр 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: Параметр filenames принимает значение path-like object.

Добавлено в версии 3.7: Параметр filenames принимает объект bytes.

read_file(f, source=None)¶

Чтение и разбор конфигурационных данных из 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])¶

Получение значения option для названного раздела. Если указано vars, то это должен быть словарь. Значение option ищется в vars (если предоставлено), section и в DEFAULTSECT в этом порядке. Если ключ не найден, а fallback предоставлен, он используется в качестве запасного значения. В качестве значения fallback может быть предоставлено None.

Все интерполяции '%' раскрываются в возвращаемых значениях, если только аргумент raw не равен true. Значения для ключей интерполяции ищутся так же, как и для опции.

Изменено в версии 3.2: Аргументы raw, vars и fallback являются ключевыми словами только для того, чтобы защитить пользователей от попыток использовать третий аргумент в качестве fallback (особенно при использовании протокола отображения).

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

Удобный метод, который преобразует option в указанном разделе в целое число. См. get() для объяснения raw, vars и fallback.

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

Удобный метод, который преобразует option в указанном разделе в число с плавающей точкой. См. get() для объяснения raw, vars и fallback.

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

Удобный метод, который приводит опцию в указанном разделе к булеву значению. Обратите внимание, что допустимыми значениями для опции являются '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.

В противном случае возвращается список пар имя, значение для опций в данном разделе. Необязательные аргументы имеют то же значение, что и для метода get().

Изменено в версии 3.8: Элементы, присутствующие в vars, больше не появляются в результате. Предыдущее поведение смешивало фактические параметры синтаксического анализатора с переменными, предоставленными для интерполяции.

set(section, option, value)¶

Если данный раздел существует, установите заданную опцию в указанное значение; в противном случае вызовите предупреждение NoSectionError. option и value должны быть строками; если это не так, будет выдано сообщение TypeError.

write(fileobject, space_around_delimiters=True)¶

Запишите представление конфигурации в указанный file object, который должен быть открыт в текстовом режиме (прием строк). Это представление может быть разобрано будущим вызовом read(). Если space_around_delimiters равно true, разделители между ключами и значениями будут окружены пробелами.

Примечание

Комментарии в исходном конфигурационном файле не сохраняются при записи конфигурации обратно. Что считать комментарием, зависит от заданных значений для comment_prefix и inline_comment_prefix.

remove_option(section, option)¶

Удалить указанную опцию из указанного раздела. Если раздел не существует, выведите NoSectionError. Если удаляемая опция существовала, возвращается True; в противном случае возвращается False.

remove_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¶

Максимальная глубина для рекурсивной интерполяции для get(), когда параметр raw равен false. Это имеет значение, только если используется интерполяция по умолчанию.

Объекты 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 (или ConfigParser с параметрами raw, установленными в true) для внутреннего хранения нестроковых значений, полная функциональность (включая интерполяцию и вывод в файлы) может быть достигнута только при использовании строковых значений.

Этот метод позволяет пользователям внутренне присваивать ключам нестроковые значения. Такое поведение не поддерживается и приведет к ошибкам при попытке записи в файл или получения его в несырьевом режиме. Используйте 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.2: Атрибут filename и аргумент __init__() были переименованы в source для согласованности.

Сноски

1(1,2,3,4,5,6,7,8,9,10,11)

Парсеры конфигурации допускают серьезную настройку. Если вы хотите изменить поведение, описанное в сноске, обратитесь к разделу Customizing Parser Behaviour.