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

Источник: Lib/configparser.py

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

Примечание

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

См.также

Модуль tomllib

TOML - это хорошо специфицированный формат для файлов конфигурации приложений. Он специально разработан как улучшенная версия INI.

Модуль shlex

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

Модуль json

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

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

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

[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

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

Имя первой секции может быть опущено, если парсер настроен на разрешение безымянной секции верхнего уровня с помощью allow_unnamed_section=True. В этом случае ключи/значения могут быть получены по UNNAMED_SECTION, как в config[UNNAMED_SECTION].

Файлы конфигурации могут содержать комментарии, префикс которых состоит из определенных символов (# и ;, по умолчанию [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?

Безымянные участки

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

>>> config = """
... option = value
...
... [  Section 2  ]
... another = val
... """
>>> unnamed = configparser.ConfigParser(allow_unnamed_section=True)
>>> unnamed.read_string(config)
>>> unnamed.get(configparser.UNNAMED_SECTION, 'option')
'value'

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

В дополнение к основной функциональности 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}

Картографический протокол доступа

Added in version 3.2.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    >>> import configparser

>>> sample_config = """
... [mysqld]
...   user = mysql
...   pid-file = /var/run/mysqld/mysqld.pid
...   skip-external-locking
...   old_passwords = 1
...   skip-bdb
...   # we don't need ACID today
...   skip-innodb
... """
>>> config = configparser.ConfigParser(allow_no_value=True)
>>> config.read_string(sample_config)

>>> # Settings with values are treated as before:
>>> config["mysqld"]["user"]
'mysql'

>>> # Settings without values provide None:
>>> config["mysqld"]["skip-bdb"]

>>> # Settings which aren't specified still raise an error:
>>> config["mysqld"]["does-not-exist"]
Traceback (most recent call last):
  ...
KeyError: 'does-not-exist'

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

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

    См. также аргумент 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

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

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

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

  • пустые_строки_в_значениях, значение по умолчанию: 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. Если имя этого метода начинается с 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

Значения по умолчанию доступны в обоих типах 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. Подробнее об этом в dedicated documentation section.

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

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

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

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

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

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

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

Изменено в версии 3.13: Вызывает MultilineContinuationError, если allow_no_value равно True, и ключ без значения продолжается с отступом от строки.

defaults()

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

sections()

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

add_section(section)

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

Изменено в версии 3.2: Названия секций, не являющиеся строками, повышают TypeError.

has_section(section)

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

options(section)

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

has_option(section, option)

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

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, который должен быть итерируемым, содержащим строки Unicode (например, файлы, открытые в текстовом режиме).

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

Added in version 3.2: Заменяет readfp().

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

Разбор данных конфигурации из строки.

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

Added in version 3.2.

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

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

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

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

Added in version 3.2.

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

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

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

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

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

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

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

set(section, option, value)

Если данный раздел существует, установите заданную опцию в указанное значение; в противном случае вызовите сообщение NoSectionError. option и value должны быть строками; если это не так, вызывается сообщение 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().

configparser.UNNAMED_SECTION

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

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.

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

set(section, option, value)

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

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

Исключения

exception configparser.Error

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

exception configparser.NoSectionError

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

exception configparser.DuplicateSectionError

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

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

exception configparser.DuplicateOptionError

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

exception configparser.NoOptionError

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

exception configparser.InterpolationError

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

exception configparser.InterpolationDepthError

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

exception configparser.InterpolationMissingOptionError

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

exception configparser.InterpolationSyntaxError

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

exception configparser.MissingSectionHeaderError

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

exception configparser.ParsingError

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

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

exception configparser.MultilineContinuationError

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

Added in version 3.13.

Сноски