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

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

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

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

[forge.example]
User = hg

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

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

>>> import configparser
>>> config = configparser.ConfigParser()
>>> config['DEFAULT'] = {'ServerAliveInterval': '45',
...                      'Compression': 'yes',
...                      'CompressionLevel': '9'}
>>> config['forge.example'] = {}
>>> config['forge.example']['User'] = 'hg'
>>> config['topsecret.server.example'] = {}
>>> topsecret = config['topsecret.server.example']
>>> topsecret['Port'] = '50022'     # mutates the parser
>>> topsecret['ForwardX11'] = 'no'  # same here
>>> config['DEFAULT']['ForwardX11'] = 'yes'
>>> with open('example.ini', 'w') as configfile:
...   config.write(configfile)
...

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

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

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

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

Можно прочитать несколько конфигураций в один ConfigParser, где наиболее недавно добавленная конфигурация имеет наивысший приоритет. Любые конфликтующие ключи берутся из более новой конфигурации, а ранее существовавшие ключи сохраняются. В примере ниже читается файл override.ini, который переопределяет любые конфликтующие ключи из файла example.ini.

[DEFAULT]
ServerAliveInterval = -1

>>> config_override = configparser.ConfigParser()
>>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}
>>> with open('override.ini', 'w') as configfile:
...     config_override.write(configfile)
...
>>> config_override = configparser.ConfigParser()
>>> config_override.read(['example.ini', 'override.ini'])
['example.ini', 'override.ini']
>>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
-1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Файлы конфигурации могут содержать комментарии, предваряемые определёнными символами (# и ; по умолчанию [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"] возвращает только преобразованные имена ключей опций. Это означает, что ключи по умолчанию преобразуются в нижний регистр. В то же время для раздела, содержащего ключ 'a', оба выражения возвращают True:

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

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

• DEFAULTSECT не может быть удален из парсера:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ConfigParser.BOOLEAN_STATES

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

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

Другие типичные пары Boolean включают accept/reject или enabled/disabled.

ConfigParser.optionxform(option)

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

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

Примечание

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

ConfigParser.SECTCRE

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

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

Примечание

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

Примеры использования устаревшего API

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

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

import configparser

config = configparser.RawConfigParser()

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

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

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

import configparser

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

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

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

Для интерполяции используйте ConfigParser:

import configparser

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

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

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

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

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

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

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

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

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

import configparser

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

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

Объекты ConfigParser

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

Основной парсер конфигурации. Если задано 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*() в объекте парсера и прокси-объектах раздела.

Можно прочитать несколько конфигураций в один экземпляр ConfigParser, где последняя добавленная конфигурация имеет наивысший приоритет. Любые конфликтующие ключи берутся из более поздней конфигурации, а ранее существовавшие ключи сохраняются. В примере ниже читается файл override.ini, который переопределит любые конфликтующие ключи из файла example.ini.

[DEFAULT]
ServerAliveInterval = -1

>>> config_override = configparser.ConfigParser()
>>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}
>>> with open('override.ini', 'w') as configfile:
...     config_override.write(configfile)
...
>>> config_override = configparser.ConfigParser()
>>> config_override.read(['example.ini', 'override.ini'])
['example.ini', 'override.ini']
>>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
-1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

items(raw=False, vars=None)

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

Если section не указан, возвращает список пар 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().

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. Если передано имя default section, возникает исключение ValueError.

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

set(section, option, value)

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

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

Исключения

exception configparser.Error

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

exception configparser.NoSectionError

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

exception configparser.DuplicateSectionError

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

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

exception configparser.DuplicateOptionError

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

exception configparser.NoOptionError

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

exception configparser.InterpolationError

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

exception configparser.InterpolationDepthError

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

exception configparser.InterpolationMissingOptionError

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

exception configparser.InterpolationSyntaxError

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

exception configparser.MissingSectionHeaderError

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

exception configparser.ParsingError

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

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

Примечания