Сообщить об ошибке.

Методы объекта ConfigParser в Python

Доступные операции с файлами конфигураций

Класс синтаксического анализатора INI-файлов ConfigParserparser.ConfigParser() представляет следующие методы своего экземпляра.

В примерах будем использовать такой INI-файл:

# defaults.cfg
[DEFAULT]
AliveInterval = 45
Compres = yes
CompresLevel = 9
ForwardX11 = yes

[one]
User = hg

[two]
Port = 50022
ForwardX11 = no

Содержание:

ConfigParser.defaults():

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

>>> import configparser
>>> cfg = configparser.ConfigParser()
>>> with open('defaults.cfg') as fp:
...     cfg.read_file(fp)
>>> cfg.defaults()
# OrderedDict([('aliveinterval', '45'), 
# ('compres', 'yes'), 
# ('compreslevel', '9'), 
# ('forwardx11', 'yes')])

ConfigParser.sections():

Метод ConfigParser.sections() возвращает список доступных разделов. Раздел по умолчанию DEFAULT не включен в список.

>>> import configparser
>>> cfg = configparser.ConfigParser()
>>> with open('defaults.cfg') as fp:
...     cfg.read_file(fp)
>>> cfg.sections()
# ['one', 'two']

ConfigParser.add_section(section):

Метод ConfigParser.add_section() добавляет раздел с именем section к объекту ConfigParserParser.

Если раздел с данным именем уже существует, вызывается исключение DuplicateSectionError. Если передано имя раздела по умолчанию DEFAULT, то вызывается исключение ValueError. Название раздела должно быть строкой. Если передан другой тип, то вызывается исключение TypeError.

>>> import configparser
>>> cfg = configparser.ConfigParser()
>>> with open('defaults.cfg') as fp:
...     cfg.read_file(fp)
>>> cfg.sections()
# ['one', 'two']
>>> cfg.add_section('three')
>>> cfg.sections()
# ['one', 'two', 'three']

ConfigParser.has_section(section):

Метод ConfigParser.has_section() указывает, присутствует ли указанный секция section в конфигурации. Раздел по умолчанию DEFAULT не проверяется.

>>> import configparser
>>> cfg = configparser.ConfigParser()
>>> with open('defaults.cfg') as fp:
...     cfg.read_file(fp)
>>> cfg.has_section('three')
# True

ConfigParser.options(section):

Метод ConfigParser.options() возвращает список опций, доступных в указанной секции section.

>>> import configparser
>>> cfg = configparser.ConfigParser()
>>> with open('defaults.cfg') as fp:
...     cfg.read_file(fp)
>>> cfg.options('two')
# ['port', 'forwardx11', 'aliveinterval', 
# 'compres', 'compreslevel']

ConfigParser.has_option(section, option):

Метод ConfigParser.has_option() проверяет, если данный раздел section существует и содержит данную опцию option, то возвращает True. В противном случае вернет False. Если указанным разделом является None или пустая строка, предполагается значение из DEFAULT.

>>> import configparser
>>> cfg = configparser.ConfigParser()
>>> with open('defaults.cfg') as fp:
...     cfg.read_file(fp)
>>> cfg.has_option('one', 'user')
# True
>>> cfg.has_option('one', 'compres')
# True
>>> cfg.has_option('one', 'port')
# False

ConfigParser.read(filenames, encoding=None):

Метод ConfigParser.read() попытайтесь прочитать и проанализировать итерацию имен файлов filenames, возвращая список имен файлов, которые были успешно проанализированы.

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

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

import configparser, os

config = configparser.ConfigParser()
with open('defaults.cfg') as fp:
    cfg.read_file(fp)     
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],
            encoding='cp1250')

ConfigParser.read_file(f, source=None):

Метод ConfigParser.read_file() читает и анализирует данные конфигурации из объекта f, который должен быть итерируемым и выдавать строки Unicode. Аргументом f например может быть файл, открытый в текстовом режиме.

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

>>> import configparser, os
>>> cfg = configparser.ConfigParser()
>>> with open('defaults.cfg') as fp:
...     cfg.read_file(fp)
...
>>> cfg.sections()
# ['one', 'two']

ConfigParser.read_string(string, source='<string>'):

Метод ConfigParser.read_string() разбирает данные конфигурации из строки.

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

>>> import configparser, os
>>> cfg = configparser.ConfigParser()
>>> with open('defaults.cfg') as fp:
...     data = fp.read()
...
>>> cfg.read_string(data)
>>> cfg.sections()
# ['one', 'two']

ConfigParser.read_dict(dictionary, source='<dict>'):

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

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

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

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

Метод ConfigParser.get() получает значение параметра для указанной секции section. Если указан vars, то это должен быть словарь. Опция option ищется в vars (если есть), section и в DEFAULTSECT в этом порядке. Если ключ не найден и предусмотрен аргумент fallback, то он используется в качестве запасного значения. Значение None не может быть предоставлено в качестве запасного значения.

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

Примеры использования метода ConfigParser.get() смотрите в разделе "Значения ключей DEFAULT модуля ConfigParserparser в Python".

ConfigParser.getint(section, option, *, raw=False, vars=None[, fallback]):

Метод ConfigParser.getint() приводит параметр в указанной секции section к целому числу.

Для объяснения аргументов raw, vars и fallback смотрите метод ConfigParser.get.

Примеры использования метода ConfigParser.getint() смотрите в разделе "Типы данных поддерживаемые модулем ConfigParserparser".

ConfigParser.getfloat(section, option, *, raw=False, vars=None[, fallback]):

Метод ConfigParser.getfloat() приводит параметр в указанной секции section к числу с плавающей запятой.

Для объяснения аргументов raw, vars и fallback смотрите метод ConfigParser.get.

Примеры использования метода ConfigParser.getint() смотрите в разделе "Типы данных поддерживаемые модулем ConfigParserparser".

ConfigParser.getboolean(section, option, *, raw=False, vars=None[, fallback]):

Метод ConfigParser.getboolean() приводит параметр в указанной секции section к логическому значению.

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

Для объяснения аргументов raw, vars и fallback смотрите метод ConfigParser.get.

Примеры использования метода ConfigParser.getint() смотрите в разделе "Типы данных поддерживаемые модулем ConfigParserparser".

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

Метод ConfigParser.items() возвращает список пар (section_name, section_proxy) включая DEFAULTSECT, если секция section не указана .

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

>>> import configparser
>>> cfg = configparser.ConfigParser()
>>> with open('defaults.cfg') as fp:
...     cfg.read_file(fp)
>>> cfg.items('two')
# [('aliveinterval', '45'), 
# ('compres', 'yes'),
# ('compreslevel', '9'), 
# ('forwardx11', 'no'), 
# ('port', '50022')]

ConfigParser.set(section, option, value):

Метод ConfigParser.set() устанавливает для указанной опции option указанное значение value если указанная секция section существует. В противном случае вызывается исключение NoSectionError. Опция и значение должны быть строками, если нет, то вызывается исключение TypeError.

>>> import configparser
>>> cfg = configparser.ConfigParser()
>>> with open('defaults.cfg') as fp:
...     cfg.read_file(fp)
>>> cfg.set('one', 'init', '150')
>>> cfg.has_option('one', 'init')
# True

ConfigParser.write(fileobject, space_around_delimiters=True):

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

>>> import configparser
>>> cfg = configparser.ConfigParser()
>>> with open('defaults.cfg') as fp:
...     cfg.read_file(fp)
# код настройки INI-файла
... 
... 
... 
# сохранение конфигурации
>>> with open('defaults.cfg', '') as fp:
...     cfg.write(fp)

ConfigParser.remove_option(section, option):

Метод ConfigParser.remove_option() удаляет указанную опцию option из указанной секции section.

  • Если секция section не существует, то вызывается исключение NoSectionError.
  • Если опция option существует для удаления, то возвращает True, в противном случае возвращает False.
>>> import configparser
>>> cfg = configparser.ConfigParser()
>>> with open('defaults.cfg') as fp:
...     cfg.read_file(fp)
>>> cfg.remove_option('one', 'init')
# True
>>> cfg.has_option('one', 'init')
# False

ConfigParser.remove_section(section):

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

>>> import configparser
>>> cfg = configparser.ConfigParser()
>>> with open('defaults.cfg') as fp:
...     cfg.read_file(fp)
>>> cfg.remove_section('three')
# True
>>> cfg.has_section('three')
# False

ConfigParser.optionxform(option):

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

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

>>> import configparser
>>> cfg = configparser.ConfigParser()
>>> cfg.optionxform = str

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

ConfigParser.readfp(fp, filename=None):

Метод ConfigParser.readfp() считается устаревшим с версии Python-3.2.

Вместо ConfigParser.readfp(fp) используйте метод ConfigParser.read_file() и функцию readline_generator(fp), код которой приводится ниже.

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