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

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

Рассмотрим простейший конфигурационный файл, который выглядит так:

[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'     # изменяет парсер
>>> topsecret['ForwardX11'] = 'no'  # то же самое
>>> 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.

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

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

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

Резервные значения¶Fallback Values

Как и в словаре, для указания резервных значений можно использовать метод 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-файлов¶Supported INI File Structure

Конфигурационный файл состоит из секций, каждая из которых начинается с заголовка [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]
# как этот
; или этот

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

    [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
        # Кстати, комментарии тоже можно делать с отступом.

Безымянные секции¶Unnamed Sections

Имя первого (или единственного) раздела можно опускать, а значения получать через атрибут 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'

Интерполяция значений¶Interpolation of values

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

class configparser.BasicInterpolation¶

Реализация по умолчанию, используемая в ConfigParser. Она позволяет значениям содержать строки форматирования, ссылающиеся на другие значения в том же разделе или на значения в специальном разделе по умолчанию [1]. Дополнительные значения по умолчанию можно указать при инициализации.

Например:

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

[Escape]
# используйте %% для экранирования символа % (% – единственный символ, требующий экранирования):
gain: 80%%

В примере выше ConfigParser с параметром interpolation, установленным в BasicInterpolation(), преобразовал бы %(home_dir)s в значение home_dir (в данном случае /Users). %(my_dir)s, в свою очередь, преобразовалось бы в /Users/lumberjack. Все подстановки выполняются по требованию, поэтому ключи, используемые в цепочке ссылок, не обязаны быть указаны в каком-либо определённом порядке в конфигурационном файле.

Если interpolation установлен в None, анализатор просто вернёт %(my_dir)s/Pictures как значение my_pictures и %(home_dir)s/lumberjack как значение my_dir.

class configparser.ExtendedInterpolation¶

Альтернативный обработчик для интерполяции, реализующий более сложный синтаксис, используемый, например, в zc.buildout. Расширенная интерполяция использует ${section:option} для обозначения значения из другого раздела. Интерполяция может быть многоуровневой. Для удобства, если часть section: опущена, интерполяция по умолчанию берётся из текущего раздела (а также из значений по умолчанию из специального раздела).

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

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

[Escape]
# используйте $$ для экранирования символа $ ($ – единственный символ, требующий экранирования):
cost: $$80

Значения из других разделов также можно получать:

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

Доступ через протокол отображения¶Mapping Protocol Access

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

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

Объекты configparser ведут себя максимально близко к настоящим словарям. Интерфейс отображения реализован полностью и соответствует абстрактному базовому классу 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() совместим с протоколом отображения (возвращает список пар название_раздела, прокси_раздела, включая DEFAULTSECT). Однако этот метод также может быть вызван с аргументами: parser.items(section, raw, vars). Последний вызов возвращает список пар опция, значение для указанного section, со всеми раскрытыми интерполяциями (если не указан raw=True).

Протокол отображения реализован поверх существующего устаревшего API, поэтому подклассы, переопределяющие исходный интерфейс, по-прежнему должны работать с отображением, как и ожидается.

Настройка поведения анализатора¶Customizing Parser Behaviour

Вариантов формата 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)
  
  >>> # Настройки со значениями обрабатываются как и раньше:
  >>> config["mysqld"]["user"]
  'mysql'
  
  >>> # Настройки без значений дают None:
  >>> config["mysqld"]["skip-bdb"]
  
  >>> # Настройки, которые не указаны, по-прежнему вызывают ошибку:
  >>> 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())
  >>> # можно также использовать стандартный BasicInterpolation
  >>> 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, он будет доступен на всех прокси разделов в dict-совместимой форме (см. пример getdecimal() выше).

Более тонкую настройку можно выполнить, переопределив значения по умолчанию этих атрибутов парсера. Значения по умолчанию заданы на уровне классов, поэтому их можно переопределить в подклассах или путём присваивания атрибуту.

ConfigParser.BOOLEAN_STATES¶

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

>>> custom = configparser.ConfigParser()
>>> custom['section1'] = {'funky': 'nope'}
>>> custom['section1'].getboolean('funky')
Traceback (most recent call last):
...
ValueError: Not a boolean: nope
>>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}
>>> custom['section1'].getboolean('funky')
False

Другие типичные логические пары: accept/reject или enabled/disabled.

ConfigParser.optionxform(option)

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

>>> config = """
... [Section1]
... Key = Value
...
... [Section2]
... AnotherKey = Value
... """
>>> typical = configparser.ConfigParser()
>>> typical.read_string(config)
>>> list(typical['Section1'].keys())
['key']
>>> list(typical['Section2'].keys())
['anotherkey']
>>> custom = configparser.RawConfigParser()
>>> custom.optionxform = lambda option: option
>>> custom.read_string(config)
>>> list(custom['Section1'].keys())
['Key']
>>> list(custom['Section2'].keys())
['AnotherKey']

Примечание

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

ConfigParser.SECTCRE¶

Скомпилированное регулярное выражение для разбора заголовков разделов. По умолчанию сопоставляет [section] с именем "section". Пробельные символы считаются частью имени раздела, поэтому [  larch  ] будет прочитан как раздел с именем "  larch  ". Переопределите этот атрибут, если это не подходит. Например:

>>> import re
>>> config = """
... [Section 1]
... option = value
...
... [  Section 2  ]
... another = val
... """
>>> typical = configparser.ConfigParser()
>>> typical.read_string(config)
>>> typical.sections()
['Section 1', '  Section 2  ']
>>> custom = configparser.ConfigParser()
>>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]")
>>> custom.read_string(config)
>>> custom.sections()
['Section 1', 'Section 2']

Примечание

Хотя объекты ConfigParser также используют атрибут OPTCRE для распознавания строк с опциями, переопределять его не рекомендуется, так как это помешает работе параметров конструктора allow_no_value и delimiters.

Примеры устаревшего API¶Legacy API Examples

В основном из соображений обратной совместимости configparser также предоставляет устаревший API с явными методами get/set. Хотя у методов, перечисленных ниже, есть свои обоснованные сценарии использования, для новых проектов предпочтительнее доступ через протокол отображения. Устаревший API иногда более продвинутый, низкоуровневый и откровенно неинтуитивный.

Пример записи в файл конфигурации:

import configparser

config = configparser.RawConfigParser()

# Обратите внимание: используя функции set класса RawConfigParser, можно присваивать
# ключам внутренние значения, не являющиеся строками, но при попытке
# записи в файл или при получении значения в не-сыром режиме возникнет ошибка. Присваивание
# значений через протокол отображения или ConfigParser.set() не допускает
# выполнения таких присваиваний.
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!')

# Записываем наш конфигурационный файл в 'example.cfg'
with open('example.cfg', 'w') as configfile:
    config.write(configfile)

Пример повторного чтения файла конфигурации:

import configparser

config = configparser.RawConfigParser()
config.read('example.cfg')

# getfloat() вызывает исключение, если значение не является float.
# getint() и getboolean() делают то же самое для своих типов.
a_float = config.getfloat('Section1', 'a_float')
an_int = config.getint('Section1', 'an_int')
print(a_float + an_int)

# Обратите внимание, что следующий вывод не интерполирует '%(bar)s' или '%(baz)s'.
# Это потому, что мы используем RawConfigParser().
if config.getboolean('Section1', 'a_bool'):
    print(config.get('Section1', 'foo'))

Чтобы получить интерполяцию, используйте ConfigParser:

import configparser

cfg = configparser.ConfigParser()
cfg.read('example.cfg')

# Установите необязательный аргумент *raw* метода get() в True, если требуется отключить
# интерполяцию в одной операции get.
print(cfg.get('Section1', 'foo', raw=False))  # -> "Python – это весело!"
print(cfg.get('Section1', 'foo', raw=True))   # -> "%(bar)s – это %(baz)s!"

# Необязательный аргумент *vars* – это словарь с элементами, которые будут иметь
# приоритет при интерполяции.
print(cfg.get('Section1', 'foo', vars={'bar': 'Documentation',
                                       'baz': 'evil'}))

# Необязательный аргумент *fallback* можно использовать для предоставления запасного значения
print(cfg.get('Section1', 'foo'))
      # -> "Python – это весело!"

print(cfg.get('Section1', 'foo', fallback='Monty is not.'))
      # -> "Python – это весело!"

print(cfg.get('Section1', 'monster', fallback='No such things as monsters.'))
      # -> "Монстров не существует."

# Голый вызов print(cfg.get('Section1', 'monster')) вызовет NoOptionError, но мы также можем использовать:
# но мы также можем использовать:

print(cfg.get('Section1', 'monster', fallback=None))
      # -> None

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

import configparser

# Новый экземпляр с 'bar' и 'baz', по умолчанию равными 'Life' и 'hard' соответственно.
config = configparser.ConfigParser({'bar': 'Life', 'baz': 'hard'})
config.read('example.cfg')

print(config.get('Section1', 'foo'))     # -> "Python – это весело!"
config.remove_option('Section1', 'bar')
config.remove_option('Section1', 'baz')
print(config.get('Section1', 'foo'))     # -> "Жизнь тяжела!"

Объекты ConfigParser¶ConfigParser Objects

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

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

options(section)¶

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

has_option(section, option)¶

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

read(filenames, encoding=None)¶

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

If filenames is a string, a bytes object or a path-like object, it is treated as a single filename. If a file named in filenames cannot be opened, that file will be ignored. This is designed so that you can specify an iterable of potential configuration file locations (for example, the current directory, the user’s home directory, and some system-wide directory), and all existing configuration files in the iterable will be read.

Если ни один из указанных файлов не существует, экземпляр 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().

Changed in version 3.6.1: The filenames parameter accepts a path-like object.

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

read_file(f, source=None)¶

Читает и разбирает данные конфигурации из f, который должен быть итерируемым объектом, возвращающим строки Unicode (например, файлы, открытые в текстовом режиме).

Необязательный аргумент source задаёт имя читаемого файла. Если он не указан и f имеет атрибут name, то он используется для source; по умолчанию '<???>'.

Добавлено в версии 3.2: Заменяет readfp().

read_string(string, source='<string>')¶

Разбирает данные конфигурации из строки.

Необязательный аргумент source задаёт контекстно-зависимое имя переданной строки. Если не указан, используется '<string>'. Обычно это путь файловой системы или URL.

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

read_dict(dictionary, source='<dict>')¶

Загружает конфигурацию из любого объекта, предоставляющего метод items(), подобный словарю. Ключи – это имена разделов, значения – словари с ключами и значениями, которые должны присутствовать в разделе. Если используемый тип словаря сохраняет порядок, разделы и их ключи будут добавлены по порядку. Значения автоматически преобразуются в строки.

Необязательный аргумент source задаёт контекстно-зависимое имя переданного словаря. Если не указан, используется <dict>.

Этот метод можно использовать для копирования состояния между парсерами.

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

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

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

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

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

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

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

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

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

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

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

items(raw=False, vars=None)¶

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

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

В противном случае возвращает список пар 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¶RawConfigParser Objects

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

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

Исключения¶Exceptions

exception configparser.Error¶

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

exception configparser.NoSectionError¶

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

exception configparser.DuplicateSectionError¶

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

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

exception configparser.DuplicateOptionError¶

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

exception configparser.NoOptionError¶

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

exception configparser.InterpolationError¶

Базовый класс для исключений, возбуждаемых при возникновении проблем во время выполнения строковой интерполяции.

exception configparser.InterpolationDepthError¶

Исключение, возбуждаемое, когда строковая интерполяция не может быть завершена, поскольку количество итераций превышает MAX_INTERPOLATION_DEPTH. Подкласс InterpolationError.

exception configparser.InterpolationMissingOptionError¶

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

exception configparser.InterpolationSyntaxError¶

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

exception configparser.MissingSectionHeaderError¶

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

exception configparser.ParsingError¶

Исключение, возникающее при ошибках во время разбора файла.

Изменено в версии 3.12: Атрибут filename и аргумент конструктора __init__() были удалены. Они были доступны под именем source начиная с версии 3.2.

exception configparser.MultilineContinuationError¶

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

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

exception configparser.UnnamedSectionDisabledError¶

Исключение возникает при попытке использовать UNNAMED_SECTION без его включения.

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

exception configparser.InvalidWriteError¶

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

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

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

Сноски