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

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

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

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

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

Например:

[My Section]
foodir: %(dir)s/whatever
dir=frob
long: this value continues
   in the next line

разрешит %(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(). Его реализация по умолчанию преобразует имена опций в нижний регистр.

Введено в версии 2.3.

Изменено в версии 2.6: Добавлен dict_type.

Изменено в версии 2.7: По умолчанию dict_type — collections.OrderedDict. Добавлен allow_no_value.

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

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

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

Введено в версии 2.3.

Изменено в версии 2.6: Добавлен dict_type.

Изменено в версии 2.7: По умолчанию dict_type — collections.OrderedDict. Добавлен allow_no_value.

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

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

Введено в версии 2.3.

Изменено в версии 2.6: Добавлен dict_type.

Изменено в версии 2.7: По умолчанию dict_type — collections.OrderedDict. Добавлен allow_no_value.

exception ConfigParser.Error

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

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.

Введено в версии 2.3.

exception ConfigParser.InterpolationSyntaxError

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

Введено в версии 2.3.

exception ConfigParser.MissingSectionHeaderError

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

exception ConfigParser.ParsingError

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

ConfigParser.MAX_INTERPOLATION_DEPTH

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

1. Объекты RawConfigParser

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)

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

Удобный метод, который преобразует опцию option в указанной секции section в булево значение. Обратите внимание, что допустимые значения опции — "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)

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

Добавлен в версии 1.6.

RawConfigParser.remove_section(section)

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

RawConfigParser.optionxform(option)

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

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

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

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

2. Объекты ConfigParser

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

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

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

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

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

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

Добавлен в версии 2.3.

3. Объекты SafeConfigParser

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

SafeConfigParser.set(section, option, value)

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

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

4. Примеры

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

import ConfigParser

config = ConfigParser.RawConfigParser()

# When adding sections or items, add them in the reverse order of
# how you want them to be displayed in the actual file.
# In addition, please note that using RawConfigParser's and the raw
# mode of ConfigParser's respective 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. SafeConfigParser 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', 'wb') 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 или SafeConfigParser:

import ConfigParser

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

# Set the third, optional argument of get to 1 if you wish to use raw mode.
print config.get('Section1', 'foo', 0)  # -> "Python is fun!"
print config.get('Section1', 'foo', 1)  # -> "%(bar)s is %(baz)s!"

# The optional fourth argument is a dict with members that will take
# precedence in interpolation.
print config.get('Section1', 'foo', 0, {'bar': 'Documentation',
                                        'baz': 'evil'})

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

import ConfigParser

# New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each
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:
        # Create non-existent section
        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))

>>> # Settings with values are treated as before:
>>> config.get("mysqld", "user")
'mysql'

>>> # Settings without values provide None:
>>> config.get("mysqld", "skip-bdb")

>>> # Settings which aren't specified still raise an error:
>>> config.get("mysqld", "does-not-exist")
Traceback (most recent call last):
  ...
ConfigParser.NoOptionError: No option 'does-not-exist' in section: 'mysqld'