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

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

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

RawConfigParser.defaults()¶

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

RawConfigParser.sections()¶

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

RawConfigParser.add_section(section)¶

Add a section named section to the instance. If a section by the given name already exists, DuplicateSectionError is raised. If the name DEFAULT (or any of it’s case-insensitive variants) is passed, ValueError is raised.

RawConfigParser.has_section(section)¶

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

RawConfigParser.options(section)¶

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

RawConfigParser.has_option(section, option)¶

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

RawConfigParser.read(filenames)¶

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

import configparser, os

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

RawConfigParser.readfp(fp, filename=None)¶

Читает и разбирает данные конфигурации из файла или файлоподобного объекта fp (используется только метод readline()). Файлоподобный объект должен работать в текстовом режиме, т.е. возвращать строки из 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)¶

A convenience method which coerces the option in the specified section to a Boolean value. Note that the accepted values for the option are "1", "yes", "true", and "on", which cause this method to return True, and "0", "no", "false", and "off", which cause it to return False. These string values are checked in a case-insensitive manner. Any other value will cause it to raise ValueError.

RawConfigParser.items(section)¶

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

RawConfigParser.set(section, option, value)¶

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

RawConfigParser.write(fileobject)¶

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

RawConfigParser.remove_option(section, option)¶

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

RawConfigParser.remove_section(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=False, vars=None)¶

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

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

ConfigParser.items(section, raw=False, vars=None)¶

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

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

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

SafeConfigParser.set(section, option, value)¶

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

13.2.4. Примеры¶Examples

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

import configparser

config = configparser.RawConfigParser()

# При добавлении разделов или элементов добавляйте их в обратном порядке
# как они должны отображаться в реальном файле.
# Кроме того, обратите внимание, что использование RawConfigParser и raw
# режима соответствующих функций set ConfigParser позволяет присваивать
# нестроковые значения ключам внутри, но вы получите ошибку
# при попытке записи в файл или при получении в необработанном
# режиме. SafeConfigParser не допускает таких присваиваний.
config.add_section('Section1')
config.set('Section1', 'int', '15')
config.set('Section1', 'bool', 'true')
config.set('Section1', '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', 'w') as configfile:
    config.write(configfile)

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

import configparser

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

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

# Обратите внимание, что следующий вывод не интерполирует '%(bar)s' или '%(baz)s'.
# Это потому, что мы используем RawConfigParser().
if config.getboolean('Section1', '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)