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

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

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

Примечание

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

См. также

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

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

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

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

[bitbucket.org]
User = hg

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

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

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

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

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

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

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

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

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

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

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

>>> topsecret.getboolean('ForwardX11')
False
>>> config['bitbucket.org'].getboolean('ForwardX11')
True
>>> config.getboolean('bitbucket.org', 'Compression')
True

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

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

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

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

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

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

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

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

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

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

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

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

Файлы конфигурации могут содержать комментарии, начинающиеся с определённых символов (# и ; по умолчанию 1). Комментарии могут стоять сами по себе на пустой строке, возможно, с отступом. 1

Например:

[Simple Values]
key=value
spaces in keys=allowed
spaces in values=allowed as well
spaces around the delimiter = obviously
you can also use : to delimit keys from values

[All Values Are Strings]
values like this: 1000000
or this: 3.14159265359
are they treated as numbers? : no
integers, floats and booleans are held as: strings
can use the API to get converted values directly: true

[Multiline Values]
chorus: I'm a lumberjack, and I'm okay
    I sleep all night and I work all day

[No Values]
key_without_value
empty string value here =

[You can use comments]
# like this
; or this

# By default only in an empty line.
# Inline comments can be harmful because they prevent users
# from using the delimiting characters as parts of values.
# That being said, this can be customized.

    [Sections Can Be Indented]
        can_values_be_as_well = True
        does_that_mean_anything_special = False
        purpose = formatting for readability
        multiline_values = are
            handled just fine as
            long as they are indented
            deeper than the first line
            of a value
        # Did I mention we can indent comments, too?

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

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

class configparser.BasicInterpolation

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

Например:

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

[Escape]
gain: 80%%  # use a %% to escape the % sign (% is the only character that needs to be escaped)

В примере выше, ConfigParser с интерполяцией, установленной в 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]
cost: $$80  # use a $$ to escape the $ sign ($ is the only character that needs to be escaped)

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

[Common]
home_dir: /Users
library_dir: /Library
system_dir: /System
macports_dir: /opt/local

[Frameworks]
Python: 3.2
path: ${Common:system_dir}/Library/Frameworks/

[Arthur]
nickname: Two Sheds
last_name: Jackson
my_dir: ${Common:home_dir}/twosheds
my_pictures: ${my_dir}/Pictures
python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}

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

Новое в версии 3.2.

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

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

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

По умолчанию все ключи в разделах доступны в регистронезависимом режиме 1. Например, for option in parser["section"] возвращает только optionxform ключи опций. Это означает, что ключи по умолчанию в нижнем регистре. В то же время, для раздела, содержащего ключ 'a', оба выражения возвращают True:
```
"a" in parser["section"]
"A" in parser["section"]
```
Все разделы также включают значения DEFAULTSECT, что означает, что удаление .clear() в разделе может не сделать его видимым пустым. Это потому, что значения по умолчанию нельзя удалить из раздела (потому что технически их там нет). Если они переопределены в разделе, удаление приводит к повторному отображению значения по умолчанию. Попытка удалить значение по умолчанию вызывает KeyError.
DEFAULTSECT нельзя удалить из анализатора:
- попытка удалить его вызывает ValueError,
- parser.clear() оставляет его неизменным,
- parser.popitem() никогда не возвращает его.
parser.get(section, option, **kwargs) - второй аргумент не является значением по умолчанию. Однако, методы get() на уровне раздела совместимы как с протоколом отображения, так и с классическим API configparser.
parser.items() совместим с протоколом отображения (возвращает список пар имя_раздела, прокси_раздела, включая DEFAULTSECT). Однако этот метод также может быть вызван с аргументами: parser.items(section, raw, vars). Последний вызов возвращает список пар опция, значение для указанного section, со всеми интерполяциями, расширенными (если не указано raw=True).

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

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

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

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

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

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

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

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

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

Обратите внимание: есть способы добавить набор пар ключ-значение в одной операции. При использовании обычного словаря в этих операциях порядок ключей будет упорядочен, поскольку словарь сохраняет порядок с Python 3.7. Например:
```
>>> parser = configparser.ConfigParser()
>>> parser.read_dict({'section1': {'key1': 'value1',
...                                'key2': 'value2',
...                                'key3': 'value3'},
...                   'section2': {'keyA': 'valueA',
...                                'keyB': 'valueB',
...                                'keyC': 'valueC'},
...                   'section3': {'foo': 'x',
...                                'bar': 'y',
...                                'baz': 'z'}
... })
>>> parser.sections()
['section1', 'section2', 'section3']
>>> [option for option in parser['section3']]
['foo', 'bar', 'baz']
```

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

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

>>> import configparser

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

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

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

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

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

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

См. также аргумент space_around_delimiters для ConfigParser.write().
comment_prefixes, значение по умолчанию: ('#', ';')
inline_comment_prefixes, значение по умолчанию: None

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

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

Обратите внимание, что анализаторы конфигураций не поддерживают экранирование префиксов комментариев, поэтому использование inline_comment_prefixes может помешать пользователям указывать значения опций с символами, используемыми в качестве префиксов комментариев. При сомнениях следует избегать задания inline_comment_prefixes. В любом случае, единственный способ сохранить символы префиксов комментариев в начале строки в многострочных значениях — интерполировать префикс, например:
```
>>> from configparser import ConfigParser, ExtendedInterpolation
>>> parser = ConfigParser(interpolation=ExtendedInterpolation())
>>> # the default BasicInterpolation could be used as well
>>> parser.read_string("""
... [DEFAULT]
... hash = #
...
... [hashes]
... shebang =
...   ${hash}!/usr/bin/env python
...   ${hash} -*- coding: utf-8 -*-
...
... extensions =
...   enabled_extension
...   another_extension
...   #disabled_by_comment
...   yet_another_extension
...
... interpolation not necessary = if # is not at line start
... even in multiline values = line #1
...   line #2
...   line #3
... """)
>>> print(parser['hashes']['shebang'])

#!/usr/bin/env python
# -*- coding: utf-8 -*-
>>> print(parser['hashes']['extensions'])

enabled_extension
another_extension
yet_another_extension
>>> print(parser['hashes']['interpolation not necessary'])
if # is not at line start
>>> print(parser['hashes']['even in multiline values'])
line #1
line #2
line #3
```
strict, значение по умолчанию: True

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

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

В анализаторах конфигурации значения могут занимать несколько строк, если они отстучены больше, чем ключ, который их содержит. По умолчанию анализаторы также позволяют использовать пустые строки в значениях. В то же время ключи могут быть произвольно отстучены для повышения читаемости. В результате, когда конфигурационные файлы становятся большими и сложными, пользователю легко потерять ориентацию в структуре файла. Например:
```
[Section]
key = multiline
  value with a gotcha

 this = is still a part of the multiline value of 'key'
```
Это может быть особенно проблематично для пользователя, если он использует пропорциональный шрифт для редактирования файла. Поэтому, если вашему приложению не нужны значения с пустыми строками, следует рассмотреть возможность их запрета. Это приведет к тому, что пустые строки будут разделять ключи каждый раз. В приведенном выше примере это приведет к двум ключам: key и this.
default_section, значение по умолчанию: configparser.DEFAULTSECT (т.е. "DEFAULT")

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

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

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

Если преобразователю необходимо получить доступ к состоянию анализатора, его можно реализовать как метод в подклассе анализатора конфигурации. Если имя этого метода начинается с get, оно будет доступно во всех прокси-объектах разделов в формате совместимом со словарями (см. пример 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

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

import configparser

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

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

Объекты ConfigParser

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

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

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

Если параметр strict установлен в True (значение по умолчанию), парсер не будет допускать дубликатов секций или опций при чтении из одного источника (файла, строки или словаря), вызывая исключение DuplicateSectionError или DuplicateOptionError. Если параметр empty_lines_in_values установлен в False (по умолчанию: True), каждая пустая строка отмечает конец опции. В противном случае внутренние пустые строки многострочной опции сохраняются как часть значения.

Если allow_no_value установлен в True (по умолчанию: False), допускаются опции без значений; значение, хранящееся для них, равно None, и они сериализуются без заключительного разделителя.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Новое в версии 3.2.

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

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

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

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

Новое в версии 3.2.

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

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

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

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

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

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

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

items(raw=False, vars=None)

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

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

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

set(section, option, value): Если заданный раздел существует, установить заданный параметр в указанное значение; в противном случае выбросить NoSectionError. параметр и значение должны быть строками; если нет, возбуждается TypeError.

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

remove_option(section, option): Удалить указанный параметр из указанного раздела. Если раздел не существует, выбросить NoSectionError. Если параметр существовал и был удалён, вернуть True; в противном случае вернуть False.

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

optionxform(option)

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

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

cfgparser = ConfigParser()
cfgparser.optionxform = str

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

readfp(fp, filename=None)

Устарело начиная с версии 3.2: Используйте read_file() вместо этого.

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

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

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

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

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

Объекты RawConfigParser

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

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

Примечание

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

add_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: Дополнительные атрибуты source и lineno и аргументы для __init__() были добавлены.

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

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

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

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

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

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

exception configparser.MissingSectionHeaderError: Исключение, генерируемое при попытке анализа файла, у которого нет заголовков секций.

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

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

Примечания

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

© 2001–2020 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.7/library/configparser.html