configparser — Парсер файла конфигурации

Исходный код: Lib/configparser.py

---

Модуль предоставляет класс ConfigParser, реализующий базовый язык конфигурации, который предоставляет структуру, аналогичную файлам Microsoft Windows INI. Его можно использовать для написания Python программ, которые могут быть легко настроены конечными пользователями.

Примечание

Эта библиотека не интерпретирует и не пишет префиксы тип-значение используемые в Windows Registry расширяя версию синтаксиса INI.

См.также

Модуль shlex

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

Модуль json

Модуль json реализует подмножество синтаксиса JavaScript, которое также может быть использоваться для этих целей.

Быстрый старт

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

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

[bitbucket.org]
User = hg

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

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

>>> import configparser
>>> config = configparser.ConfigParser()
>>> config['DEFAULT'] = {'ServerAliveInterval': '45',
...                      'Compression': 'yes',
...                      'CompressionLevel': '9'}
>>> config['bitbucket.org'] = {}
>>> config['bitbucket.org']['User'] = 'hg'
>>> config['topsecret.server.com'] = {}
>>> topsecret = config['topsecret.server.com']
>>> topsecret['Port'] = '50022'     # мутация парсера
>>> topsecret['ForwardX11'] = 'no'  # тоже самое
>>> config['DEFAULT']['ForwardX11'] = 'yes'
>>> with open('example.ini', 'w') as configfile:
...   config.write(configfile)
...

Как вы видите, мы можем рассматривать config парсер так же, как словарь. Есть различия, изложено позже, но поведение очень близке к тому, что можно ожидать от словаря.

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

>>> config = configparser.ConfigParser()
>>> config.sections()
[]
>>> config.read('example.ini')
['example.ini']
>>> config.sections()
['bitbucket.org', 'topsecret.server.com']
>>> 'bitbucket.org' in config
True
>>> 'bytebong.com' in config
False
>>> config['bitbucket.org']['User']
'hg'
>>> config['DEFAULT']['Compression']
'yes'
>>> topsecret = config['topsecret.server.com']
>>> topsecret['ForwardX11']
'no'
>>> topsecret['Port']
'50022'
>>> for key in config['bitbucket.org']:  
...     print(key)
user
compressionlevel
serveraliveinterval
compression
forwardx11
>>> config['bitbucket.org']['ForwardX11']
'yes'

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

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

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

>>> 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['bitbucket.org'].getboolean('ForwardX11')
True
>>> config.getboolean('bitbucket.org', '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.com', мы всегда получим значение по умолчанию, даже если мы зададим резервный вариант:

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

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

>>> config.get('bitbucket.org', '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]). Комментарии могут появляться сами по себе на пустой строке, возможно, с отступом. [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]
gain: 80%%  # use a %% to escape the % sign (% is the only character that needs to be escaped)

В приведенном выше примере ConfigParser с interpolation, установленным в BasicInterpolation(), разрешит %(home_dir)s на значение home_dir (/Users в данном случае). %(home_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}

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

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

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

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

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

• По умолчанию все ключи в разделах доступны без учета регистра [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 конфигурационного анализатора.

• 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)
  
  >>> # Настройки со значениями обрабатываются как и раньше:
  >>> 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())
  >>> # 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()

# Обратите внимание, что с помощью функций набора 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() вызывает исключение, если значение не является флоат
# 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 is fun!"
print(cfg.get('Section1', 'foo', raw=True))   # -> "%(bar)s is %(baz)s!"

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

# Необязательный аргумент *fallback* можно использовать для предоставления резервного значения
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."

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

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

add_section(section)

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

Изменено в версии 3.2: Нестроковые имена разделов вызывают TypeError.

has_section(section)

Указывает, присутствует ли в конфигурации именованный section. Этот default 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, который должны быть итерируемыми строками юникода (например, файлы, открытые в текстовом режиме).

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

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

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

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. Это относится только к interpolation используемый по умолчанию.

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

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

set(section, option, value)

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

Этот метод позволяет пользователям присваивать не строковым значеним ключам. Это поведение не поддерживается и приведет к ошибкам при попытке записи в файл или получения файла в режиме, отличном от необработанного. Используйте 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.2: Признак filename и аргумент __init__() были переименованы в source для консистентности.

Сноски

[1]	(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) Парсеры конфигурации обеспечивают высокую степень настройки. Если вас интересует изменение поведения, изложенного в ссылке на сноску, обратитесь к разделу Настройка поведения анализатора.