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

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

import configparser

# New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each
config = configparser.ConfigParser({'bar': 'Life', 'baz': 'hard'})
config.read('example.cfg')

print(config.get('Section1', 'foo'))     # -> "Python is fun!"
config.remove_option('Section1', 'bar')
config.remove_option('Section1', 'baz')
print(config.get('Section1', 'foo'))     # -> "Life is hard!"

Объекты ConfigParser

class configparser.ConfigParser(defaults=None, dict_type=dict, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT, interpolation=BasicInterpolation(), converters={}, 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)

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

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

Если ни один из указанных файлов не существует, экземпляр ConfigParser будет содержать пустые данные. Приложение, которому требуется загрузить начальные значения из файла, должно загрузить необходимый файл или файлы с помощью read_file() перед вызовом read() для любых дополнительных файлов:

import configparser, os

config = configparser.ConfigParser()
config.read_file(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],
            encoding='cp1250')

Изменено в версии 3.2: Добавлен параметр encoding. Ранее все файлы считывались с помощью кодировки по умолчанию для open().

Изменено в версии 3.6.1: Параметр filenames принимает path-like object.

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

read_file(f, source=None)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Удобный метод, который преобразует option в указанной section в целое число. См. 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 не указан, возвращается список пар «имя_секции», «представление_секции», включая DEFAULTSECT.

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

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

set(section, option, value)

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

write(fileobject, space_around_delimiters=True)

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

Примечание

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

Объекты 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. Если секция с данным именем уже существует, возникает ошибка DuplicateSectionError. Если передано имя default section, возникает ошибка ValueError.

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

set(section, option, value)

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

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

Исключения

exception configparser.Error

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

exception configparser.NoSectionError

Исключение, генерируемое, когда указанная секция не найдена.

exception configparser.DuplicateSectionError

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

Изменено в версии 3.2: Добавлены необязательные атрибуты 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.

Примечания