13.2. ConfigParser – Парсер конфигурационных файлов¶ConfigParser – Configuration file parser

13.2.1. Объекты RawConfigParser¶RawConfigParser Objects

Экземпляры RawConfigParser имеют следующие методы:

RawConfigParser.defaults()¶

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

RawConfigParser.sections()¶

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

RawConfigParser.add_section(section)¶

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

RawConfigParser.has_section(section)¶

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

RawConfigParser.options(section)¶

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

RawConfigParser.has_option(section, option)¶

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

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

RawConfigParser.read(filenames)¶

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

import ConfigParser, os

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

Изменено в версии 2.4: Возвращает список успешно разобранных имён файлов.

RawConfigParser.readfp(fp[, filename])¶

Читает и разбирает данные конфигурации из файла или файлоподобного объекта, переданного в fp (используется только метод readline()). Если filename опущен и fp имеет атрибут name, он используется для filename; по умолчанию <???>.

RawConfigParser.get(section, option)¶

Получает значение опции option для именованного раздела section.

RawConfigParser.getint(section, option)¶

Удобный метод, который приводит опцию option в указанном разделе section к целому числу.

RawConfigParser.getfloat(section, option)¶

Удобный метод, который приводит опцию option в указанном разделе section к числу с плавающей точкой.

RawConfigParser.getboolean(section, option)¶

Удобный метод, который преобразует параметр в указанном разделе в логическое значение. Обратите внимание, что допустимыми значениями параметра являются "1", "yes", "true" и "on", которые заставляют этот метод возвращать True, а также "0", "no", "false" и "off" – которые заставляют его возвращать False. Эти строковые значения проверяются без учёта регистра. Любое другое значение приведёт к возбуждению ValueError.

RawConfigParser.items(section)¶

Возвращает список пар (name, value) для каждого параметра в указанном разделе.

RawConfigParser.set(section, option, value)¶

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

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

RawConfigParser.write(fileobject)¶

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

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

RawConfigParser.remove_option(section, option)¶

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

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

RawConfigParser.remove_section(section)¶

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

RawConfigParser.optionxform(option)¶

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

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

cfgparser = ConfigParser()
...
cfgparser.optionxform = str

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

13.2.2. Объекты ConfigParser¶ConfigParser Objects

Класс ConfigParser расширяет некоторые методы интерфейса RawConfigParser, добавляя несколько необязательных аргументов.

ConfigParser.get(section, option[, raw[, vars]])¶

Получает значение опции для указанного раздела. Если vars передан, он должен быть словарём. Поиск опции выполняется в vars (если передан), разделе и значениях по умолчанию в указанном порядке.

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

ConfigParser.items(section[, raw[, vars]])¶

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

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

13.2.3. Объекты SafeConfigParser¶SafeConfigParser Objects

Класс SafeConfigParser реализует тот же расширенный интерфейс, что и ConfigParser, со следующим дополнением:

SafeConfigParser.set(section, option, value)¶

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

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

13.2.4. Примеры¶Examples

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

import ConfigParser

config = ConfigParser.RawConfigParser()

# При добавлении разделов или элементов добавляйте их в обратном порядке
# как они должны отображаться в реальном файле.
# Кроме того, обратите внимание, что использование RawConfigParser и raw
# режима соответствующих функций set ConfigParser позволяет присваивать
# нестроковые значения ключам внутри, но вы получите ошибку
# при попытке записи в файл или при получении в необработанном
# режиме. SafeConfigParser не допускает таких присваиваний.
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!')

# Записываем наш конфигурационный файл в 'example.cfg'
with open('example.cfg', 'wb') as configfile:
    config.write(configfile)

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

import ConfigParser

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

# getfloat() вызывает исключение, если значение не является float.
# getint() и getboolean() делают то же самое для своих типов.
a_float = config.getfloat('Section1', 'a_float')
an_int = config.getint('Section1', 'an_int')
print a_float + an_int

# Обратите внимание, что следующий вывод не интерполирует '%(bar)s' или '%(baz)s'.
# Это потому, что мы используем RawConfigParser().
if config.getboolean('Section1', 'a_bool'):
    print config.get('Section1', 'foo')

Для получения интерполяции необходимо использовать ConfigParser или SafeConfigParser:

import ConfigParser

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

# Установите третий необязательный аргумент get в 1, если вы хотите использовать raw-режим.
print config.get('Section1', 'foo', 0)  # -> "Python – это весело!"
print config.get('Section1', 'foo', 1)  # -> "%(bar)s – это %(baz)s!"

# Необязательный четвертый аргумент – это словарь с элементами, которые будут принимать
# приоритет при интерполяции.
print config.get('Section1', 'foo', 0, {'bar': 'Documentation',
                                        'baz': 'evil'})

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

import ConfigParser

# Новый экземпляр с 'bar' и 'baz', по умолчанию равными 'Life' и 'hard' соответственно.
config = ConfigParser.SafeConfigParser({'bar': 'Life', 'baz': 'hard'})
config.read('example.cfg')

print config.get('Section1', 'foo')  # -> "Python – это весело!"
config.remove_option('Section1', 'bar')
config.remove_option('Section1', 'baz')
print config.get('Section1', 'foo')  # -> "Жизнь тяжела!"

Функция opt_move ниже позволяет перемещать опции между секциями:

def opt_move(config, section1, section2, option):
    try:
        config.set(section2, option, config.get(section1, option, 1))
    except ConfigParser.NoSectionError:
        # Создать несуществующий раздел
        config.add_section(section2)
        opt_move(config, section1, section2, option)
    else:
        config.remove_option(section1, option)

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

>>> import ConfigParser
>>> import io

>>> sample_config = """
... [mysqld]
... user = mysql
... pid-file = /var/run/mysqld/mysqld.pid
... skip-external-locking
... old_passwords = 1
... skip-bdb
... skip-innodb
... """
>>> config = ConfigParser.RawConfigParser(allow_no_value=True)
>>> config.readfp(io.BytesIO(sample_config))

>>> # Настройки со значениями обрабатываются как и раньше:
>>> config.get("mysqld", "user")
'mysql'

>>> # Настройки без значений дают None:
>>> config.get("mysqld", "skip-bdb")

>>> # Настройки, которые не указаны, по-прежнему вызывают ошибку:
>>> config.get("mysqld", "does-not-exist")
Traceback (most recent call last):
  ...
ConfigParser.NoOptionError: No option 'does-not-exist' in section: 'mysqld'