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

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

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

1. Быстрый старт

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

[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'     # mutates the parser
>>> topsecret['ForwardX11'] = 'no'  # same here
>>> config['DEFAULT']['ForwardX11'] = 'yes'
>>> with open('example.ini', 'w') as configfile:
...   config.write(configfile)
...

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

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

>>> import configparser
>>> 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].

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

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

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

3. Значения по умолчанию

Как и в словаре, вы можете использовать метод 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

4. Поддерживаемая структура файлов 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?

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

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

class configparser.BasicInterpolation

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

Например:

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

В примере выше, ConfigParser с интерполяцией, установленной на 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

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

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

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

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

7. Настройка поведения анализатора

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

Наиболее распространённый способ изменить способ работы конкретного анализатора конфигурации — использовать опции __init__():

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

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

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

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

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

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

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

  >>> 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()
  ['section3', 'section2', 'section1']
  >>> [option for option in parser['section3']]
  ['baz', 'foo', 'bar']
  

  В этих операциях также необходимо использовать упорядоченный словарь:

  >>> from collections import OrderedDict
  >>> parser = configparser.ConfigParser()
  >>> parser.read_dict(
  ...   OrderedDict((
  ...     ('s1',
  ...      OrderedDict((
  ...        ('1', '2'),
  ...        ('3', '4'),
  ...        ('5', '6'),
  ...      ))
  ...     ),
  ...     ('s2',
  ...      OrderedDict((
  ...        ('a', 'b'),
  ...        ('c', 'd'),
  ...        ('e', 'f'),
  ...      ))
  ...     ),
  ...   ))
  ... )
  >>> parser.sections()
  ['s1', 's2']
  >>> [option for option in parser['s1']]
  ['1', '3', '5']
  >>> [option for option in parser['s2'].values()]
  ['b', 'd', 'f']
  

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

configparser.SECTCRE

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

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

Примечание

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

8. Примеры устаревшего 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!"

9. Объекты ConfigParser

class configparser.ConfigParser(defaults=None, dict_type=collections.OrderedDict, 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.

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

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

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

Изменено в версии 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])

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

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

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

Если раздел не указан, возвращает список пар имя_раздела, прокси_раздела, включая DEFAULTSECT.

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

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

set(section, option, value)

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

write(fileobject, space_around_delimiters=True)

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

remove_option(section, option)

Удаляет указанную опцию из указанного раздела. Если раздел не существует, возбуждает NoSectionError. Если опция существовала для удаления, возвращает True; в противном случае возвращает False.

remove_section(section)

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

optionxform(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. Это актуально только при использовании интерполяции по умолчанию.

10. Объекты RawConfigParser

class configparser.RawConfigParser(defaults=None, dict_type=collections.OrderedDict, 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.

Примечание

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

add_section(section)

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

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

set(section, option, value)

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

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

11. Исключения

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 для согласованности.

Примечания