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.

Имя первой секции можно опустить, если анализатор настроен на разрешение безымянной секции верхнего уровня с помощью allow_unnamed_section=True. В этом случае ключи и значения можно получить через UNNAMED_SECTION, как в config[UNNAMED_SECTION].

Файлы конфигурации могут содержать комментарии, начинающиеся с определённых символов (по умолчанию # и ; [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?

Безымянные секции

Имя первой (или единственной) секции можно опустить, а значения получить через атрибут UNNAMED_SECTION.

>>> config = """
... option = value
...
... [  Section 2  ]
... another = val
... """
>>> unnamed = configparser.ConfigParser(allow_unnamed_section=True)
>>> unnamed.read_string(config)
>>> unnamed.get(configparser.UNNAMED_SECTION, 'option')
'value'

Интерполяция значений

Помимо основных возможностей, 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={}, allow_unnamed_section=False)

Основной анализатор конфигурации. Если задан 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*() в объекте анализатора и прокси разделов.

Если allow_unnamed_section имеет значение True (по умолчанию: False), имя первого раздела можно опустить. См. раздел «Разделы без имени».

Можно загрузить несколько конфигураций в один объект 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, поскольку теперь он сохраняет порядок вставки.

Изменено в версии 3.13: Вызывается исключение MultilineContinuationError, если allow_no_value имеет значение True, а за ключом без значения следует строка с отступом.

Изменено в версии 3.13: Добавлен аргумент allow_unnamed_section.

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

Изменено в версии 3.14: Вызывает InvalidWriteError, если записываемое представление нельзя точно разобрать при последующем вызове read() этого анализатора.

Примечание

Комментарии из исходного файла конфигурации не сохраняются при повторной записи конфигурации. То, что считается комментарием, зависит от заданных значений 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.UNNAMED_SECTION

Специальный объект, представляющий имя раздела, используемое для ссылки на раздел без имени (см. Разделы без имени).

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=BasicInterpolation(), converters={}, allow_unnamed_section=False)

Устаревший вариант ConfigParser. По умолчанию интерполяция в нём отключена; кроме того, небезопасные методы add_section и set позволяют использовать имена разделов, имена параметров и значения нестрокового типа, а также поддерживается обработка устаревшего именованного аргумента defaults=.

Изменено в версии 3.2: Добавлены allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_section и interpolation.

Изменено в версии 3.5: Добавлен аргумент converters.

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

Изменено в версии 3.13: Добавлен аргумент allow_unnamed_section.

Примечание

Рекомендуется вместо него использовать ConfigParser, который проверяет типы сохраняемых внутри значений. Если интерполяция не нужна, можно использовать ConfigParser(interpolation=None).

add_section(section)

Добавляет в экземпляр раздел с именем section или UNNAMED_SECTION.

Если указанный раздел уже существует, вызывается исключение DuplicateSectionError. Если передано имя раздела по умолчанию, вызывается исключение ValueError. Если передано значение UNNAMED_SECTION, а поддержка отключена, вызывается исключение UnnamedSectionDisabledError.

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

Изменено в версии 3.14: Добавлена поддержка UNNAMED_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.

exception configparser.MultilineContinuationError

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

Добавлено в версии 3.13.

exception configparser.UnnamedSectionDisabledError

Исключение, возникающее при попытке использовать UNNAMED_SECTION без включения этой возможности.

Добавлено в версии 3.14.

exception configparser.InvalidWriteError

Исключение, возникающее, если результат попытки выполнить ConfigParser.write() не будет корректно разобран при последующем вызове ConfigParser.read().

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

Добавлено в версии 3.14.

Сноски