configparser — анализатор файлов конфигурации

Краткое руководство

Рассмотрим очень простой файл конфигурации следующего вида:

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

[forge.example]
User = hg

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

Структура INI-файлов описана в следующем разделе. По сути, файл состоит из разделов, каждый из которых содержит ключи со значениями. Классы configparser могут читать и записывать такие файлы. Для начала создадим указанный выше файл конфигурации программно.

>>> import configparser
>>> config = configparser.ConfigParser()
>>> config['DEFAULT'] = {'ServerAliveInterval': '45',
...                      'Compression': 'yes',
...                      'CompressionLevel': '9'}
>>> config['forge.example'] = {}
>>> config['forge.example']['User'] = 'hg'
>>> config['topsecret.server.example'] = {}
>>> topsecret = config['topsecret.server.example']
>>> 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()
['forge.example', 'topsecret.server.example']
>>> 'forge.example' in config
True
>>> 'python.org' in config
False
>>> config['forge.example']['User']
'hg'
>>> config['DEFAULT']['Compression']
'yes'
>>> topsecret = config['topsecret.server.example']
>>> topsecret['ForwardX11']
'no'
>>> topsecret['Port']
'50022'
>>> for key in config['forge.example']:
...     print(key)
user
compressionlevel
serveraliveinterval
compression
forwardx11
>>> config['forge.example']['ForwardX11']
'yes'

Как видно из примера выше, API довольно прост. Единственный нюанс связан с разделом DEFAULT, который предоставляет значения по умолчанию для всех остальных разделов [1]. Также обратите внимание, что ключи в разделах нечувствительны к регистру и хранятся в нижнем регистре [1].

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

[DEFAULT]
ServerAliveInterval = -1

>>> config_override = configparser.ConfigParser()
>>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}
>>> with open('override.ini', 'w') as configfile:
...     config_override.write(configfile)
...
>>> config_override = configparser.ConfigParser()
>>> config_override.read(['example.ini', 'override.ini'])
['example.ini', 'override.ini']
>>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
-1

Такое поведение эквивалентно вызову ConfigParser.read() с несколькими файлами, переданными параметру filenames.

Поддерживаемые типы данных

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

>>> int(topsecret['Port'])
50022
>>> float(topsecret['CompressionLevel'])
9.0

Поскольку эта задача встречается очень часто, анализаторы конфигурации предоставляют несколько удобных методов получения целых чисел, чисел с плавающей точкой и логических значений. Последний особенно интересен, поскольку простая передача значения в bool() не даст нужного результата, так как bool('False') по-прежнему является True. Поэтому анализаторы конфигурации также предоставляют метод getboolean(). Этот метод нечувствителен к регистру и распознаёт логические значения 'yes'/'no', 'on'/'off', 'true'/'false' и '1'/'0' [1]. Например:

>>> topsecret.getboolean('ForwardX11')
False
>>> config['forge.example'].getboolean('ForwardX11')
True
>>> config.getboolean('forge.example', '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.example', всегда будет возвращено значение по умолчанию, даже если указать резервное значение:

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

Также следует учитывать, что метод get() на уровне анализатора предоставляет особый, более сложный интерфейс, сохранённый для обратной совместимости. При использовании этого метода резервное значение можно передать через именованный аргумент fallback:

>>> config.get('forge.example', '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 с параметром 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]
# 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 ведут себя максимально похоже на обычные словари. Интерфейс отображения реализован полностью и соответствует ABC MutableMapping. Однако следует учитывать несколько отличий:

• По умолчанию все ключи в разделах доступны без учёта регистра [1]. Например, for option in parser["section"] выдаёт только имена ключей параметров в optionxform. По умолчанию это означает, что ключи приводятся к нижнему регистру. При этом для раздела, содержащего ключ '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'
  

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

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

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

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

Этот метод преобразует имена параметров при каждой операции чтения, получения или установки. По умолчанию имя преобразуется в нижний регистр. Это также означает, что при записи файла конфигурации все ключи будут в нижнем регистре. Если такое поведение не подходит, переопределите этот метод. Например:

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

Примеры устаревшего 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

Значения по умолчанию доступны в обоих типах ConfigParser. Они используются при интерполяции, если используемый параметр не определён в другом месте.

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. Подробнее см. в специальном разделе документации.

Все имена параметров, используемые при подстановке, передаются методу optionxform(), как и любые другие ссылки на имена параметров. Например, при использовании стандартной реализации optionxform() (которая преобразует имена параметров в нижний регистр) значения foo %(bar)s и foo %(BAR)s эквивалентны.

Если задан аргумент converters, он должен быть словарём, в котором каждый ключ задаёт имя преобразователя типов, а каждое значение — вызываемый объект, выполняющий преобразование строки в нужный тип данных. Для каждого преобразователя создаётся соответствующий метод get*() у объекта анализатора и прокси разделов.

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

[DEFAULT]
ServerAliveInterval = -1

>>> config_override = configparser.ConfigParser()
>>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}
>>> with open('override.ini', 'w') as configfile:
...     config_override.write(configfile)
...
>>> config_override = configparser.ConfigParser()
>>> config_override.read(['example.ini', 'override.ini'])
['example.ini', 'override.ini']
>>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
-1

Изменено в версии 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.

Изменено в версии 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)

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

options(section)

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

has_option(section, option)

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

read(filenames, encoding=None)

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

Если filenames — это строка, объект bytes или объект, подобный пути, он рассматривается как имя одного файла. Если файл, указанный в 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: Добавлен параметр encoding. Ранее все файлы читались с использованием кодировки по умолчанию для open().

Изменено в версии 3.6.1: Параметр filenames принимает объект, подобный пути.

Изменено в версии 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 для раздела с указанным именем section. Если указан аргумент 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 в указанном разделе section в целое число. Пояснения аргументов raw, vars и fallback см. в описании get().

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

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

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

Вспомогательный метод, преобразующий параметр option в указанном разделе section в логическое значение. Обратите внимание, что допустимые значения параметра: '1', 'yes', 'true' и 'on' — при их указании метод возвращает True; а '0', 'no', 'false' и 'off' — при их указании метод возвращает False. Эти строковые значения проверяются без учёта регистра. Любое другое значение вызовет исключение ValueError. Пояснения аргументов raw, vars и fallback см. в описании get().

items(raw=False, vars=None)

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

Если section не указан, возвращает список пар section_name, section_proxy, включая DEFAULTSECT.

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

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

set(section, option, value)

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

write(fileobject, space_around_delimiters=True)

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

Примечание

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

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

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.

Тип section не проверяется, что позволяет пользователям создавать разделы с именами, не являющимися строками. Такое поведение не поддерживается и может привести к внутренним ошибкам.

set(section, option, value)

Если указанный раздел существует, задаёт указанному параметру заданное значение; в противном случае вызывает исключение NoSectionError. Хотя RawConfigParser (или ConfigParser с параметром raw, установленным в true) позволяет внутренне хранить значения, не являющиеся строками, полную функциональность (включая подстановку и запись в файлы) можно обеспечить только при использовании строковых значений.

Этот метод позволяет пользователям внутренне присваивать ключам значения, не являющиеся строками. Такое поведение не поддерживается и приведёт к ошибкам при попытке записать данные в файл или получить их в режиме, отличном от raw. Используйте API протокола отображения, который не допускает таких присваиваний.

Исключения

exception configparser.Error

Базовый класс для всех остальных исключений configparser.

exception configparser.NoSectionError

Исключение, возникающее, если указанный раздел не найден.

exception configparser.DuplicateSectionError

Исключение, возникающее, если add_section() вызывается с именем уже существующего раздела или если строгий анализатор обнаруживает раздел более одного раза в одном входном файле, строке или словаре.

Изменено в версии 3.2: В __init__() добавлены необязательные атрибуты и параметры source и lineno.

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.12: Атрибут filename и аргумент конструктора __init__() удалены. С версии 3.2 они доступны под именем source.

Сноски