configparser — Анализатор конфигурационных файлов¶

быстрый старт¶

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

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

[forge.example]
User = hg

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

Структура INI-файлов описана in the following section. По сути, файл состоит из разделов, каждый из которых содержит ключи со значениями. 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)
...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Как и в случае со словарем, вы можете использовать метод sections 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 с интерполяцией, равной 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 объекты ведут себя настолько близко к реальным словарям, насколько это возможно. Интерфейс отображения завершен и соответствует MutableMapping азбуке. Однако есть несколько отличий, которые следует учитывать:

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

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

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

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

  • при попытке удалить его возникает ValueError,

  • parser.clear() оставляет его нетронутым,

  • parser.popitem() никогда не возвращает его.

• parser.get(section, option, **kwargs) - второй аргумент не является резервным значением. Однако обратите внимание, что методы на уровне раздела get() совместимы как с протоколом сопоставления, так и с классическим API configparser.

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

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

Настройка поведения синтаксического анализатора¶

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

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

• значения по умолчанию, значение по умолчанию: 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'
  

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

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

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

• 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
  

• строгий, значение по умолчанию: 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 и может быть изменено во время выполнения (например, для преобразования файлов из одного формата в другой).

• интерполяция, значение по умолчанию: configparser.BasicInterpolation

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

• преобразователи, значение по умолчанию: не установлено

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

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

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

ConfigParser.BOOLEAN_STATES¶

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

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

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

ConfigParser.optionxform(option)

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

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

Примечание

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

ConfigParser.SECTCRE¶

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

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

Примечание

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

Примеры устаревших API¶

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

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

import configparser

config = configparser.RawConfigParser()

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

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

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

import configparser

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

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

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

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

import configparser

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

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

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

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

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

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

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

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

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

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. Подробнее об этом в разделе dedicated documentation section.

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

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

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

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

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

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

options(section)¶

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

has_option(section, option)¶

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

read(filenames, encoding=None)¶

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

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

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

import configparser, os

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

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

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

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

read_file(f, source=None)¶

Считывает и анализирует данные конфигурации из f, которые должны быть повторяемыми и содержать строки в Юникоде (например, файлы, открытые в текстовом режиме).

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

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

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

Проанализируйте конфигурационные данные из строки.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

set(section, option, value)¶

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

write(fileobject, space_around_delimiters=True)¶

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

Примечание

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

remove_option(section, option)¶

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

remove_section(section)¶

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

optionxform(option)¶

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

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

cfgparser = ConfigParser()
cfgparser.optionxform = str

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

readfp(fp, filename=None)¶

Не рекомендуется, начиная с версии 3.2: Вместо этого используйте read_file().

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

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

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

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

configparser.MAX_INTERPOLATION_DEPTH¶

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

Объекты RawConfigParser¶

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

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

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

Примечание

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

add_section(section)¶

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

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

set(section, option, value)¶

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

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

Исключения¶

exception configparser.Error¶

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

exception configparser.NoSectionError¶

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

exception configparser.DuplicateSectionError¶

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

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

Сноски