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

>>> another_config = configparser.ConfigParser()
>>> another_config.read('example.ini')
['example.ini']
>>> another_config['topsecret.server.example']['Port']
'50022'
>>> another_config.read_string("[topsecret.server.example]\nPort=48484")
>>> another_config['topsecret.server.example']['Port']
'48484'
>>> another_config.read_dict({"topsecret.server.example": {"Port": 21212}})
>>> another_config['topsecret.server.example']['Port']
'21212'
>>> another_config['topsecret.server.example']['ForwardX11']
'no'

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

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

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

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

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

>>> topsecret.getboolean('ForwardX11')
False
>>> config['forge.example'].getboolean('ForwardX11')
True
>>> config.getboolean('forge.example', 'Compression')
True

Помимо getboolean(), парсеры конфигурации предоставляют аналогичные методы getint() и getfloat(). Можно зарегистрировать собственные преобразователи и настроить предоставляемые по умолчанию. [1]

Резервные значения

Как и в случае со словарём, для предоставления резервных значений можно использовать метод секции get():

>>> topsecret.get('Port')
'50022'
>>> topsecret.get('CompressionLevel')
'9'
>>> topsecret.get('Cipher')
>>> topsecret.get('Cipher', '3des-cbc')
'3des-cbc'

Обратите внимание: значения по умолчанию имеют приоритет над резервными значениями. Например, в нашем примере ключ 'CompressionLevel' указан только в секции 'DEFAULT'. Если попытаться получить его из секции 'topsecret.server.example', всегда будет возвращено значение по умолчанию, даже если указать резервное значение:

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

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

>>> config.get('forge.example', 'monster',
...            fallback='No such things as monsters')
'No such things as monsters'

Тот же аргумент fallback можно использовать с методами getint(), getfloat() и getboolean(), например:

>>> 'BatchMode' in topsecret
False
>>> topsecret.getboolean('BatchMode', fallback=True)
True
>>> config['DEFAULT']['BatchMode'] = 'no'
>>> topsecret.getboolean('BatchMode', fallback=True)
False

Поддерживаемая структура INI-файлов

Файл конфигурации состоит из секций, каждая из которых начинается с заголовка [section], за которым следуют пары ключ/значение, разделённые определённой строкой (по умолчанию = или : [1]). По умолчанию имена секций чувствительны к регистру, а ключи — нет [1]. Пробелы в начале и конце ключей и значений удаляются. Значения можно опустить, если парсер настроен на такую возможность [1]; в этом случае можно также не указывать разделитель ключа и значения. Значения могут занимать несколько строк, если они имеют больший отступ, чем первая строка значения. В зависимости от режима парсера пустые строки могут считаться частью многострочных значений или игнорироваться.

По умолчанию допустимым именем секции может быть любая строка, не содержащая ‘\n’. Чтобы изменить это поведение, см. ConfigParser.SECTCRE.

Файлы конфигурации могут содержать комментарии, начинающиеся с определённых символов (по умолчанию # и ; [1]). Комментарии могут находиться на отдельных пустых строках, в том числе с отступом. [1]

Например:

[Simple Values]
key=value
spaces in keys=allowed
spaces in values=allowed as well
spaces around the delimiter = obviously
you can also use : to delimit keys from values

[All Values Are Strings]
values like this: 1000000
or this: 3.14159265359
are they treated as numbers? : no
integers, floats and booleans are held as: strings
can use the API to get converted values directly: true

[Multiline Values]
chorus: I'm a lumberjack, and I'm okay
    I sleep all night and I work all day

[No Values]
key_without_value
empty string value here =

[You can use comments]
# like this
; or this

# By default only in an empty line.
# Inline comments can be harmful because they prevent users
# from using the delimiting characters as parts of values.
# That being said, this can be customized.

    [Sections Can Be Indented]
        can_values_be_as_well = True
        does_that_mean_anything_special = False
        purpose = formatting for readability
        multiline_values = are
            handled just fine as
            long as they are indented
            deeper than the first line
            of a value
        # Did I mention we can indent comments, too?

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

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

class configparser.BasicInterpolation

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

Например:

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

[Escape]
# use a %% to escape the % sign (% is the only character that needs to be escaped):
gain: 80%%

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

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

class configparser.ExtendedInterpolation

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

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

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

[Escape]
# use a $$ to escape the $ sign ($ is the only character that needs to be escaped):
cost: $$80

Можно также получать значения из других секций:

[Common]
home_dir: /Users
library_dir: /Library
system_dir: /System
macports_dir: /opt/local

[Frameworks]
Python: 3.2
path: ${Common:system_dir}/Library/Frameworks/

[Arthur]
nickname: Two Sheds
last_name: Jackson
my_dir: ${Common:home_dir}/twosheds
my_pictures: ${my_dir}/Pictures
python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}

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

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

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

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

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

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

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

• DEFAULTSECT нельзя удалить из парсера:

  • попытка удалить его вызывает ValueError,
  • parser.clear() оставляет его без изменений,
  • parser.popitem() никогда его не возвращает.
• parser.get(section, option, **kwargs) — второй аргумент не является резервным значением. Однако методы уровня секции get() совместимы как с протоколом отображения, так и с классическим API configparser.
• parser.items() совместим с протоколом отображения (возвращает список пар section_name, section_proxy, включая DEFAULTSECT). Однако этот метод также можно вызвать с аргументами: parser.items(section, raw, vars). Последний вызов возвращает список пар option, value для указанной section, раскрывая все интерполяции (если не задано raw=True).

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

Настройка поведения парсера

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

Чаще всего поведение конкретного парсера конфигурации изменяют с помощью параметров __init__():

• defaults, значение по умолчанию: None

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

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

• dict_type, значение по умолчанию: dict

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

  Например, альтернативный тип словаря можно использовать для сортировки секций и параметров при обратной записи.

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

  >>> parser = configparser.ConfigParser()
  >>> parser.read_dict({'section1': {'key1': 'value1',
  ...                                'key2': 'value2',
  ...                                'key3': 'value3'},
  ...                   'section2': {'keyA': 'valueA',
  ...                                'keyB': 'valueB',
  ...                                'keyC': 'valueC'},
  ...                   'section3': {'foo': 'x',
  ...                                'bar': 'y',
  ...                                'baz': 'z'}
  ... })
  >>> parser.sections()
  ['section1', 'section2', 'section3']
  >>> [option for option in parser['section3']]
  ['foo', 'bar', 'baz']
  

• allow_no_value, значение по умолчанию: False

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

  >>> import configparser
  
  >>> sample_config = """
  ... [mysqld]
  ...   user = mysql
  ...   pid-file = /var/run/mysqld/mysqld.pid
  ...   skip-external-locking
  ...   old_passwords = 1
  ...   skip-bdb
  ...   # we don't need ACID today
  ...   skip-innodb
  ... """
  >>> config = configparser.ConfigParser(allow_no_value=True)
  >>> config.read_string(sample_config)
  
  >>> # Settings with values are treated as before:
  >>> config["mysqld"]["user"]
  'mysql'
  
  >>> # Settings without values provide None:
  >>> config["mysqld"]["skip-bdb"]
  
  >>> # Settings which aren't specified still raise an error:
  >>> config["mysqld"]["does-not-exist"]
  Traceback (most recent call last):
    ...
  KeyError: 'does-not-exist'
  

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

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

  См. также аргумент space_around_delimiters метода ConfigParser.write().

• comment_prefixes, значение по умолчанию: ('#', ';')

• inline_comment_prefixes, значение по умолчанию: None

  Префиксы комментариев — это строки, указывающие на начало допустимого комментария в файле конфигурации. comment_prefixes используются только в остальных случаях пустых строках (возможно, с отступом), тогда как inline_comment_prefixes можно использовать после любого допустимого значения (например, имён секций, параметров и пустых строк). По умолчанию встроенные комментарии отключены, а '#' и ';' используются как префиксы комментариев в отдельных строках.

  Изменено в версии 3.2: В предыдущих версиях поведение configparser соответствовало comment_prefixes=('#',';') и inline_comment_prefixes=(';',).

  Обратите внимание: парсеры конфигурации не поддерживают экранирование префиксов комментариев, поэтому использование inline_comment_prefixes может помешать пользователям задавать значения параметров с символами, используемыми в качестве префиксов комментариев. Если вы не уверены, не задавайте inline_comment_prefixes. В любом случае единственный способ сохранить символы префиксов комментариев в начале строки многострочного значения — интерполировать префикс, например:

  >>> from configparser import ConfigParser, ExtendedInterpolation
  >>> parser = ConfigParser(interpolation=ExtendedInterpolation())
  >>> # the default BasicInterpolation could be used as well
  >>> parser.read_string("""
  ... [DEFAULT]
  ... hash = #
  ...
  ... [hashes]
  ... shebang =
  ...   ${hash}!/usr/bin/env python
  ...   ${hash} -*- coding: utf-8 -*-
  ...
  ... extensions =
  ...   enabled_extension
  ...   another_extension
  ...   #disabled_by_comment
  ...   yet_another_extension
  ...
  ... interpolation not necessary = if # is not at line start
  ... even in multiline values = line #1
  ...   line #2
  ...   line #3
  ... """)
  >>> print(parser['hashes']['shebang'])
  
  #!/usr/bin/env python
  # -*- coding: utf-8 -*-
  >>> print(parser['hashes']['extensions'])
  
  enabled_extension
  another_extension
  yet_another_extension
  >>> print(parser['hashes']['interpolation not necessary'])
  if # is not at line start
  >>> print(parser['hashes']['even in multiline values'])
  line #1
  line #2
  line #3
  

• strict, значение по умолчанию: True

  Если установлено значение True, парсер не допускает повторяющихся секций или параметров при чтении из одного источника (с помощью read_file(), read_string() или read_dict()). В новых приложениях рекомендуется использовать строгие парсеры.

  Изменено в версии 3.2: В предыдущих версиях поведение configparser соответствовало strict=False.

• empty_lines_in_values, значение по умолчанию: True

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

  [Section]
  key = multiline
    value with a gotcha
  
   this = is still a part of the multiline value of 'key'
  

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

• default_section, значение по умолчанию: configparser.DEFAULTSECT (то есть "DEFAULT")

  Соглашение, допускающее специальную секцию со значениями по умолчанию для других секций или для интерполяции, — мощная возможность этой библиотеки, позволяющая создавать сложные декларативные конфигурации. Обычно эта секция называется "DEFAULT", но это имя можно изменить на любое другое допустимое имя секции. Типичные значения: "general" или "common". Указанное имя используется для распознавания секций со значениями по умолчанию при чтении из любого источника, а также при записи конфигурации в файл. Текущее значение можно получить с помощью атрибута parser_instance.default_section и изменить во время выполнения (например, для преобразования файлов из одного формата в другой).

• interpolation, значение по умолчанию: configparser.BasicInterpolation

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

• converters, значение по умолчанию: не задано

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

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

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

ConfigParser.BOOLEAN_STATES

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

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

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

ConfigParser.optionxform(option)

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

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

Примечание

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

ConfigParser.SECTCRE

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

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

Примечание

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

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

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

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

import configparser

config = configparser.RawConfigParser()

# Please note that using RawConfigParser's set functions, you can assign
# non-string values to keys internally, but will receive an error when
# attempting to write to a file or when you get it in non-raw mode. Setting
# values using the mapping protocol or ConfigParser's set() does not allow
# such assignments to take place.
config.add_section('Section1')
config.set('Section1', 'an_int', '15')
config.set('Section1', 'a_bool', 'true')
config.set('Section1', 'a_float', '3.1415')
config.set('Section1', 'baz', 'fun')
config.set('Section1', 'bar', 'Python')
config.set('Section1', 'foo', '%(bar)s is %(baz)s!')

# Writing our configuration file to 'example.cfg'
with open('example.cfg', 'w') as configfile:
    config.write(configfile)

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

import configparser

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

# getfloat() raises an exception if the value is not a float
# getint() and getboolean() also do this for their respective types
a_float = config.getfloat('Section1', 'a_float')
an_int = config.getint('Section1', 'an_int')
print(a_float + an_int)

# Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.
# This is because we are using a RawConfigParser().
if config.getboolean('Section1', 'a_bool'):
    print(config.get('Section1', 'foo'))

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

import configparser

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

# Set the optional *raw* argument of get() to True if you wish to disable
# interpolation in a single get operation.
print(cfg.get('Section1', 'foo', raw=False))  # -> "Python is fun!"
print(cfg.get('Section1', 'foo', raw=True))   # -> "%(bar)s is %(baz)s!"

# The optional *vars* argument is a dict with members that will take
# precedence in interpolation.
print(cfg.get('Section1', 'foo', vars={'bar': 'Documentation',
                                       'baz': 'evil'}))

# The optional *fallback* argument can be used to provide a fallback value
print(cfg.get('Section1', 'foo'))
      # -> "Python is fun!"

print(cfg.get('Section1', 'foo', fallback='Monty is not.'))
      # -> "Python is fun!"

print(cfg.get('Section1', 'monster', fallback='No such things as monsters.'))
      # -> "No such things as monsters."

# A bare print(cfg.get('Section1', 'monster')) would raise NoOptionError
# but we can also use:

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

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

import configparser

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

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

Объекты ConfigParser

class configparser.ConfigParser(defaults=None, dict_type=dict, allow_no_value=False, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT, interpolation=BasicInterpolation(), converters={})

Основной анализатор конфигурации. Если задан defaults, он инициализируется встроенными значениями по умолчанию. Если задан dict_type, он будет использоваться для создания объектов словаря со списком разделов, параметрами внутри раздела и значениями по умолчанию.

Если заданы delimiters, они используются как набор подстрок, разделяющих ключи и значения. Если заданы comment_prefixes, они используются как набор подстрок, обозначающих начало комментариев в пустых строках. Комментарии могут иметь отступ. Если заданы inline_comment_prefixes, они используются как набор подстрок, обозначающих начало комментариев в непустых строках.

Если strict имеет значение True (по умолчанию), анализатор не допускает повторяющихся разделов или параметров при чтении из одного источника (файла, строки или словаря) и вызывает DuplicateSectionError или DuplicateOptionError. Если empty_lines_in_values имеет значение False (по умолчанию: True), каждая пустая строка обозначает конец параметра. В противном случае внутренние пустые строки многострочного параметра сохраняются как часть значения. Если allow_no_value имеет значение True (по умолчанию: False), допускаются параметры без значений; для них хранится значение None, а при сериализации завершающий разделитель не добавляется.

Если задан default_section, он определяет имя специального раздела, содержащего значения по умолчанию для других разделов и интерполяции (обычно он называется "DEFAULT"). Это значение можно получить и изменить во время выполнения с помощью атрибута экземпляра default_section. Это не приведёт к повторной обработке уже разобранного файла конфигурации, но будет учитываться при записи обработанных параметров в новый файл конфигурации.

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

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

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

Изменено в версии 3.1: Тип dict_type по умолчанию — collections.OrderedDict.

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

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

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

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

defaults()

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

sections()

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

add_section(section)

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

Изменено в версии 3.2: Для имён разделов, не являющихся строками, вызывается TypeError.

has_section(section)

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

options(section)

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

has_option(section, option)

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

read(filenames, encoding=None)

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

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

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

import configparser, os

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

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

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

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

read_file(f, source=None)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

items(raw=False, vars=None)

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

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

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

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

set(section, option, value)

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

write(fileobject, space_around_delimiters=True)

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

Примечание

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

remove_option(section, option)

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

remove_section(section)

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

optionxform(option)

Преобразует имя параметра option, найденное во входном файле или переданное клиентским кодом, в форму, используемую во внутренних структурах. Стандартная реализация возвращает option в нижнем регистре; подклассы могут переопределить этот метод, а клиентский код — задать экземплярам атрибут с таким именем, чтобы изменить это поведение.

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

cfgparser = ConfigParser()
cfgparser.optionxform = str

Обратите внимание: при чтении файлов конфигурации пробелы вокруг имён параметров удаляются до вызова optionxform().

readfp(fp, filename=None)

Устарело с версии 3.2: Вместо этого используйте read_file().

Изменено в версии 3.2: Теперь readfp() выполняет итерацию по fp, а не вызывает fp.readline().

Для существующего кода, вызывающего readfp() с аргументами, не поддерживающими итерацию, в качестве обёртки для файловоподобного объекта можно использовать следующий генератор:

def readline_generator(fp):
    line = fp.readline()
    while line:
        yield line
        line = fp.readline()

Вместо parser.readfp(fp) используйте parser.read_file(readline_generator(fp)).

configparser.MAX_INTERPOLATION_DEPTH

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

Объекты RawConfigParser

class configparser.RawConfigParser(defaults=None, dict_type=dict, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT[, interpolation])

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

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

Примечание

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

add_section(section)

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

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

set(section, option, value)

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

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

Исключения

exception configparser.Error

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

exception configparser.NoSectionError

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

exception configparser.DuplicateSectionError

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

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

exception configparser.DuplicateOptionError

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

exception configparser.NoOptionError

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

exception configparser.InterpolationError

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

exception configparser.InterpolationDepthError

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

exception configparser.InterpolationMissingOptionError

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

exception configparser.InterpolationSyntaxError

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

exception configparser.MissingSectionHeaderError

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

exception configparser.ParsingError

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

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

Сноски