ConfigParser — Парсер файла конфигурации

Note

The ConfigParser module has been renamed to configparser in Python 3. The 2to3 tool will automatically adapt imports when converting your sources to Python 3.

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

Note

В данном переводе “секция” то же, что и “раздел”.

Note

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

See also

Модуль shlex

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

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

Модуль json

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

исопльзовать для той же цели.

Конфигурационный файл сосотоит из разделов, начинающихся с заголовка [section], за которым идут записи вида имя: значение с продолжениями в стиле RFC 822 (см раздел 3.1.1, “LONG HEADER FIELDS”); кроме того можно использовать вид name=value. Имейте ввиду, что пробелы в начале значения удаляются. Опциональные значения могут содержать строки формата, которые ссылаются на другие значения в этом же разделе или значения в специальном разделе DEFAULT. Дополнительные значения по умолчанию могут быть предоставлены для инициализации и восстановления. Строки, начинающиеся с '#' или ';' игнорируются и могут быть использованы как комментарии.

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

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

DEFAULT. Дополнительные значения по умолчанию могут быть предоставлены при инициализации.

Например:

[My Section]
foodir: %(dir)s/whatever
dir=frob
long: это значение продолжается
   на следующей строке

разрешит %(dir)s в значение dir (frob в этом примере). Все такие разрешения происходят по запросу.

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

Разделы обычно хранятся как встроенные словари. Альтернативный тип словаря может быть передан конструктору ConfigParser. Например, если переданный тип словаря сортирует свои ключи, то разделы будут отсортированы при обратной записи, как и ключи в каждом разделе.

class ConfigParser.RawConfigParser([defaults[, dict_type[, allow_no_value]]])

Базовый объект конфигурации. Когда передан defaults, то его значения используются для задания значений по умолчанию. Если задан dict_type, то он будет использоваться для создания объекта словаря для списка разделов, для опций в разделах и для значений по умолчанию. Если allow_no_value=True (по умолчанию: False), то опции могут не содержать значений; в таком случае значением будет None.

Этот класс не поддерживает “волшебной” интерполяции.

Все имена опций передаётся через метод optionxform(). Его реализация по умолчанию преобразует все имена в нижний регистр.

New in version 2.3.

Changed in version 2.6: добавлен dict_type.

Changed in version 2.7: dict_type по умолчанию - collections.OrderedDict. добавлено allow_no_value.

class ConfigParser.ConfigParser([defaults[, dict_type[, allow_no_value]]])

Класс-наследник от RawConfigParser, который реализует “волшебную” интерполяцию и добавляет опциональные аргументы в методы get() и items(). Значения в defaults должны подходить для интерполяции строк при помощи %()s. Обратите внимание, что __name__ неизменяем по умолчанию; его значением является имя раздела и оно будет переопределять любые значения находящиеся в defaults.

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

New in version 2.3.

Changed in version 2.6: добавлен dict_type.

Changed in version 2.7: dict_type по умолчанию - collections.OrderedDict. добавлено allow_no_value.

class ConfigParser.SafeConfigParser([defaults[, dict_type[, allow_no_value]]])

Наследник класса ConfigParser, который реализует более вменяемый варинат “волшебной” интерполяции. Эта реализация также более предсказуема. Новые приложения должны выбирать эту версию, если им не нужна совместимость с более старыми версиями Python.

New in version 2.3.

Changed in version 2.6: добавлен dict_type.

Changed in version 2.7: dict_type по умолчанию - collections.OrderedDict. добавлено allow_no_value.

exception ConfigParser.Error

Базовый класс для всех исключений модуля.

exception ConfigParser.NoSectionError

Исключение, возбуждаемое, когда определённый раздел не найден.

exception ConfigParser.DuplicateSectionError

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

exception ConfigParser.NoOptionError

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

exception ConfigParser.InterpolationError

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

exception ConfigParser.InterpolationDepthError

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

exception ConfigParser.InterpolationMissingOptionError

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

New in version 2.3.

exception ConfigParser.InterpolationSyntaxError

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

New in version 2.3.

exception ConfigParser.MissingSectionHeaderError

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

exception ConfigParser.ParsingError

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

ConfigParser.MAX_INTERPOLATION_DEPTH

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

See also

Модуль shlex

Поддержка шелл-подобных мини-языков Unix, которые можно использовать как альтернативный

формат для файлов конфигурации.

RawConfigParser Objects

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

RawConfigParser.defaults()

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

RawConfigParser.sections()

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

RawConfigParser.add_section(section)

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

RawConfigParser.has_section(section)

Сообщает, присутствует ли переданный раздел в конфигурации. Раздел DEFAULT не распознаётся.

RawConfigParser.options(section)

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

RawConfigParser.has_option(section, option)

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

New in version 1.6.

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')])

Changed in version 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)

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

RawConfigParser.items(section)

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

RawConfigParser.set(section, option, value)

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

New in version 1.6.

RawConfigParser.write(fileobject)

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

New in version 1.6.

RawConfigParser.remove_option(section, option)

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

New in version 1.6.

RawConfigParser.remove_section(section)

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

RawConfigParser.optionxform(option)

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

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

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

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

ConfigParser Objects

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

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

Получает значение опции option из раздела section. Если передан vars, то он должен быть словарём. Опция option последовательно ищется в vars (если есть), section, и затем в defaults.

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

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

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

New in version 2.3.

Объекты SafeConfigParser

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

SafeConfigParser.set(section, option, value)

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

New in version 2.4.

Примеры

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

import ConfigParser

config = ConfigParser.RawConfigParser()

# Когда добавляем разделы или элементы, добавляйте их в обратном порядке от того,
# как Вы хотите, чтобы они отображались в итоговом файле.
# Кроме того, обратите внимание, что используя RawConfigParser's и "сырой" режим
# функции 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')

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

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

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

import ConfigParser

# Новый экземпляр со значениями по умолчанию 'bar' и 'baz' равными 'Life' и 'hard'
config = ConfigParser.SafeConfigParser({'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!"

Функция 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, переданный в конструктор, может быть использован для обозначения того, что эти опции тоже должны учитываться: