`configparser.md`

398 строк · 32.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.7/library/configparser.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 13.2. [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#module-ConfigParser) – Парсер конфигурационных файлов89> **Примечание**10>11> Модуль [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#module-ConfigParser) переименован в `configparser` в Python 3. Инструмент [2to3](https://python-all.ru/2.7/glossary.html#term-2to3) автоматически адаптирует импорты при преобразовании исходного кода в Python 3.1213Этот модуль определяет класс [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser). Класс [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser) реализует базовый язык парсинга файлов конфигурации, который предоставляет структуру, похожую на ту, что встречается в INI-файлах Microsoft Windows. Его можно использовать для написания программ на Python, которые легко настраиваются конечными пользователями.1415> **Примечание**16>17> Эта библиотека *не* интерпретирует и не записывает префиксы типов значений, используемые в расширенной версии синтаксиса INI из реестра Windows.1819> **См. также**20>21> **Модуль [`shlex`](https://python-all.ru/2.7/library/shlex.html#module-shlex)**22>23> Поддержка создания мини-языков, подобных командным оболочкам Unix, которые можно использовать в качестве альтернативного формата для файлов конфигурации приложений.24>25> **Модуль [`json`](https://python-all.ru/2.7/library/json.html#module-json)**26>27> Модуль json реализует подмножество синтаксиса JavaScript, которое также можно использовать для этой цели.2829Файл конфигурации состоит из секций, возглавляемых заголовком `[section]`, за которыми следуют записи `name: value`, с продолжениями в стиле [**RFC 822**](https://python-all.ru/2.7/library/configparser.html) (см. раздел 3.1.1, «LONG HEADER FIELDS»); также принимается `name=value`. Обратите внимание, что начальные пробелы удаляются из значений. Необязательные значения могут содержать строки форматирования, которые ссылаются на другие значения в той же секции или значения в специальной секции `DEFAULT`. Дополнительные значения по умолчанию можно задать при инициализации и получении. Строки, начинающиеся с `'#'` или `';'`, игнорируются и могут использоваться для комментариев.3031Файлы конфигурации могут содержать комментарии, помеченные специальными символами (`#` и `;`). Комментарии могут находиться на отдельной пустой строке или вставляться в строки со значениями или именами секций. В последнем случае перед ними должен быть пробельный символ, чтобы распознаваться как комментарий. (Для обратной совместимости только `;` начинает встроенный комментарий, а `#` – нет.)3233В дополнение к основной функциональности, [`SafeConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.SafeConfigParser) поддерживает интерполяцию. Это означает, что значения могут содержать строки форматирования, которые ссылаются на другие значения в той же секции или значения в специальной секции `DEFAULT`. Дополнительные значения по умолчанию можно задать при инициализации.3435Например:3637```python38[My Section]39foodir: %(dir)s/whatever40dir=frob41long: this value continues42   in the next line43```4445разрешает `%(dir)s` в значение `dir` (в данном случае `frob`). Все раскрытия ссылок выполняются по требованию.4647Значения по умолчанию можно задать, передав их в конструктор [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser) в виде словаря. Дополнительные значения по умолчанию можно передать в метод `get()`, который переопределит все остальные.4849Секции обычно хранятся во встроенном словаре. Альтернативный тип словаря можно передать конструктору [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser). Например, если передан тип словаря, сортирующий ключи, секции будут отсортированы при записи, как и ключи внутри каждой секции.5051#### `class ConfigParser.RawConfigParser([defaults[, dict_type[, allow_no_value]]])`5253Базовый объект конфигурации. Когда задан *defaults*, он инициализируется в словарь внутренних значений по умолчанию. Когда задан *dict\_type*, он будет использоваться для создания объектов-словарей для списка секций, для параметров внутри секции и для значений по умолчанию. Когда *allow\_no\_value* имеет значение true (по умолчанию: `False`), параметры без значений принимаются; значение, предоставляемое для них, равно `None`.5455Этот класс не поддерживает магическое поведение интерполяции.5657Все имена параметров передаются через метод [`optionxform()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser.optionxform). Его реализация по умолчанию преобразует имена параметров в нижний регистр.5859Новое в версии 2.3.6061Изменено в версии 2.6: добавлен *dict\_type*.6263Изменено в версии 2.7: Значением по умолчанию для *dict\_type* является [`collections.OrderedDict`](https://python-all.ru/2.7/library/collections.html#collections.OrderedDict). Добавлен *allow\_no\_value*.6465#### `class ConfigParser.ConfigParser([defaults[, dict_type[, allow_no_value]]])`6667Производный класс от [`RawConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser), реализующий магическую интерполяцию и добавляющий необязательные аргументы к методам [`get()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser.get) и [`items()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser.items). Значения в *defaults* должны быть подходящими для строковой интерполяции `%()s`. Обратите внимание, что *\_\_name\_\_* является внутренним значением по умолчанию; его значением является имя секции, и оно переопределит любое значение, предоставленное в *defaults*.6869Все имена параметров, используемые при интерполяции, будут передаваться через метод `optionxform()`, как и любая другая ссылка на имя параметра. При использовании реализации по умолчанию `optionxform()` значения `foo %(bar)s` и `foo %(BAR)s` эквивалентны.7071Новое в версии 2.3.7273Изменено в версии 2.6: добавлен *dict\_type*.7475Изменено в версии 2.7: Значением по умолчанию для *dict\_type* является [`collections.OrderedDict`](https://python-all.ru/2.7/library/collections.html#collections.OrderedDict). Добавлен *allow\_no\_value*.7677#### `class ConfigParser.SafeConfigParser([defaults[, dict_type[, allow_no_value]]])`7879Производный класс от [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser), реализующий более разумный вариант магической интерполяции. Эта реализация также более предсказуема. Новым приложениям следует предпочитать эту версию, если им не нужна совместимость со старыми версиями Python.8081Новое в версии 2.3.8283Изменено в версии 2.6: добавлен *dict\_type*.8485Изменено в версии 2.7: Значением по умолчанию для *dict\_type* является [`collections.OrderedDict`](https://python-all.ru/2.7/library/collections.html#collections.OrderedDict). Добавлен *allow\_no\_value*.8687#### `exception ConfigParser.Error`8889Базовый класс для всех остальных исключений configparser.9091#### `exception ConfigParser.NoSectionError`9293Исключение, возбуждаемое, когда указанный раздел не найден.9495#### `exception ConfigParser.DuplicateSectionError`9697Исключение возникает, если `add_section()` вызывается с именем секции, которая уже существует.9899#### `exception ConfigParser.NoOptionError`100101Исключение возбуждается, когда указанный параметр не найден в указанной секции.102103#### `exception ConfigParser.InterpolationError`104105Базовый класс для исключений, возбуждаемых при возникновении проблем во время выполнения строковой интерполяции.106107#### `exception ConfigParser.InterpolationDepthError`108109Исключение возникает, когда строковую интерполяцию не удаётся завершить, потому что количество итераций превышает [`MAX_INTERPOLATION_DEPTH`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.MAX_INTERPOLATION_DEPTH). Подкласс [`InterpolationError`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.InterpolationError).110111#### `exception ConfigParser.InterpolationMissingOptionError`112113Исключение возникает, когда параметр, на который ссылается значение, не существует. Подкласс [`InterpolationError`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.InterpolationError).114115Новое в версии 2.3.116117#### `exception ConfigParser.InterpolationSyntaxError`118119Исключение возникает, когда исходный текст, в который выполняются подстановки, не соответствует требуемому синтаксису. Подкласс [`InterpolationError`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.InterpolationError).120121Новое в версии 2.3.122123#### `exception ConfigParser.MissingSectionHeaderError`124125Исключение возбуждается при попытке разобрать файл, не имеющий заголовков секций.126127#### `exception ConfigParser.ParsingError`128129Исключение, возникающее при ошибках во время разбора файла.130131#### `ConfigParser.MAX_INTERPOLATION_DEPTH`132133Максимальная глубина рекурсивной интерполяции для `get()`, когда параметр *raw* имеет значение false. Это актуально только для класса [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser).134135> **См. также**136>137> **Модуль [`shlex`](https://python-all.ru/2.7/library/shlex.html#module-shlex)**138>139> Поддержка создания мини-языков в стиле оболочки Unix, которые можно использовать как альтернативный формат для конфигурационных файлов приложений.140141## 13.2.1. Объекты RawConfigParser142143Экземпляры [`RawConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser) имеют следующие методы:144145#### `RawConfigParser.defaults()`146147Возвращает словарь, содержащий значения по умолчанию для экземпляра.148149#### `RawConfigParser.sections()`150151Возвращает список доступных секций; `DEFAULT` не включается в список.152153#### `RawConfigParser.add_section(section)`154155Добавляет секцию с именем *section* в экземпляр. Если секция с указанным именем уже существует, возбуждается [`DuplicateSectionError`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.DuplicateSectionError). Если передано имя `DEFAULT` (или любой из его вариантов без учёта регистра), возбуждается [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError).156157#### `RawConfigParser.has_section(section)`158159Указывает, присутствует ли именованный раздел в конфигурации. Раздел `DEFAULT` не распознан.160161#### `RawConfigParser.options(section)`162163Возвращает список опций, доступных в указанном разделе *section*.164165#### `RawConfigParser.has_option(section, option)`166167Если указанный раздел существует и содержит указанный параметр, вернуть [`True`](https://python-all.ru/2.7/library/constants.html#True); в противном случае вернуть [`False`](https://python-all.ru/2.7/library/constants.html#False).168169Новое в версии 1.6.170171#### `RawConfigParser.read(filenames)`172173Пытается прочитать и разобрать список имён файлов, возвращая список имён файлов, которые были успешно разобраны. Если *имена файлов* представляет собой строку или строку Unicode, она считается именем одного файла. Если файл, указанный в *имена файлов*, не удаётся открыть, этот файл игнорируется. Это сделано для того, чтобы можно было указать список возможных мест расположения конфигурационных файлов (например, текущий каталог, домашний каталог пользователя и какой-либо общесистемный каталог), и все существующие конфигурационные файлы из списка будут прочитаны. Если ни один из указанных файлов не существует, экземпляр [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser) будет содержать пустой набор данных. Приложение, которому требуется загрузить начальные значения из файла, должно загрузить необходимый файл или файлы с помощью [`readfp()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser.readfp) перед вызовом [`read()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser.read) для любых необязательных файлов:174175```python176import ConfigParser, os177178config = ConfigParser.ConfigParser()179config.readfp(open('defaults.cfg'))180config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])181```182183Изменено в версии 2.4: Возвращает список успешно разобранных имён файлов.184185#### `RawConfigParser.readfp(fp[, filename])`186187Читает и разбирает данные конфигурации из файла или файлоподобного объекта, переданного в *fp* (используется только метод [`readline()`](https://python-all.ru/2.7/library/readline.html#module-readline)). Если *filename* опущен и *fp* имеет атрибут `name`, он используется для *filename*; по умолчанию `<???>`.188189#### `RawConfigParser.get(section, option)`190191Получает значение опции *option* для именованного раздела *section*.192193#### `RawConfigParser.getint(section, option)`194195Удобный метод, который приводит опцию *option* в указанном разделе *section* к целому числу.196197#### `RawConfigParser.getfloat(section, option)`198199Удобный метод, который приводит опцию *option* в указанном разделе *section* к числу с плавающей точкой.200201#### `RawConfigParser.getboolean(section, option)`202203Удобный метод, который преобразует *параметр* в указанном *разделе* в логическое значение. Обратите внимание, что допустимыми значениями параметра являются `"1"`, `"yes"`, `"true"` и `"on"`, которые заставляют этот метод возвращать `True`, а также `"0"`, `"no"`, `"false"` и `"off"` – которые заставляют его возвращать `False`. Эти строковые значения проверяются без учёта регистра. Любое другое значение приведёт к возбуждению [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError).204205#### `RawConfigParser.items(section)`206207Возвращает список пар `(name, value)` для каждого параметра в указанном *разделе*.208209#### `RawConfigParser.set(section, option, value)`210211Если указанный раздел существует, устанавливает указанный параметр в заданное значение; в противном случае возбуждает [`NoSectionError`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.NoSectionError). Хотя для *внутреннего* хранения нестроковых значений можно использовать [`RawConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser) (или [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser) с параметром *raw*, установленным в true), полная функциональность (включая интерполяцию и вывод в файлы) достигается только при использовании строковых значений.212213Новое в версии 1.6.214215#### `RawConfigParser.write(fileobject)`216217Записывает представление конфигурации в указанный файловый объект. Это представление может быть разобрано при будущем вызове [`read()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser.read).218219Новое в версии 1.6.220221#### `RawConfigParser.remove_option(section, option)`222223Удаляет указанный *параметр* из указанного *раздела*. Если раздел не существует, возбуждает [`NoSectionError`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.NoSectionError). Если параметр существовал и был удалён, возвращает [`True`](https://python-all.ru/2.7/library/constants.html#True); в противном случае возвращает [`False`](https://python-all.ru/2.7/library/constants.html#False).224225Новое в версии 1.6.226227#### `RawConfigParser.remove_section(section)`228229Удаляет указанный *раздел* из конфигурации. Если раздел на самом деле существовал, возвращает `True`. В противном случае возвращает `False`.230231#### `RawConfigParser.optionxform(option)`232233Преобразует имя опции *option*, которое встречается во входном файле или передаётся клиентским кодом, в форму, которая должна использоваться во внутренних структурах. Реализация по умолчанию возвращает версию *option* в нижнем регистре; подклассы могут переопределить это, или клиентский код может установить атрибут с таким именем на экземплярах для изменения этого поведения.234235Для использования этого метода не обязательно наследовать ConfigParser; можно также переустановить его в экземпляре, передав функцию, принимающую строковый аргумент. Например, установка его в `str` сделает имена параметров чувствительными к регистру:236237```python238cfgparser = ConfigParser()239...240cfgparser.optionxform = str241```242243Обратите внимание, что при чтении конфигурационных файлов пробельные символы вокруг имён параметров удаляются перед вызовом [`optionxform()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser.optionxform).244245## 13.2.2. Объекты ConfigParser246247Класс [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser) расширяет некоторые методы интерфейса [`RawConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser), добавляя несколько необязательных аргументов.248249#### `ConfigParser.get(section, option[, raw[, vars]])`250251Получает значение *опции* для указанного *раздела*. Если *vars* передан, он должен быть словарём. Поиск *опции* выполняется в *vars* (если передан), *разделе* и *значениях по умолчанию* в указанном порядке.252253Все `'%'` подстановки раскрываются в возвращаемых значениях, если только аргумент *raw* не равен true. Значения ключей подстановки ищутся так же, как и опция.254255#### `ConfigParser.items(section[, raw[, vars]])`256257Возвращает список пар `(name, value)` для каждого параметра в указанном *разделе*. Необязательные аргументы имеют тот же смысл, что и для метода [`get()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser.get).258259Новое в версии 2.3.260261## 13.2.3. Объекты SafeConfigParser262263Класс [`SafeConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.SafeConfigParser) реализует тот же расширенный интерфейс, что и [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser), со следующим дополнением:264265#### `SafeConfigParser.set(section, option, value)`266267Если указанная секция существует, устанавливает заданную опцию в указанное значение; в противном случае вызывается [`NoSectionError`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.NoSectionError). *значение* должно быть строкой ([`str`](https://python-all.ru/2.7/library/functions.html#str) или [`unicode`](https://python-all.ru/2.7/library/functions.html#unicode)); если нет, вызывается [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError).268269Новое в версии 2.4.270271## 13.2.4. Примеры272273Пример записи в файл конфигурации:274275```python276import ConfigParser277278config = ConfigParser.RawConfigParser()279280# При добавлении разделов или элементов добавляйте их в обратном порядке281# как они должны отображаться в реальном файле.282# Кроме того, обратите внимание, что использование RawConfigParser и raw283# режима соответствующих функций set ConfigParser позволяет присваивать284# нестроковые значения ключам внутри, но вы получите ошибку285# при попытке записи в файл или при получении в необработанном286# режиме. SafeConfigParser не допускает таких присваиваний.287config.add_section('Section1')288config.set('Section1', 'an_int', '15')289config.set('Section1', 'a_bool', 'true')290config.set('Section1', 'a_float', '3.1415')291config.set('Section1', 'baz', 'fun')292config.set('Section1', 'bar', 'Python')293config.set('Section1', 'foo', '%(bar)s is %(baz)s!')294295# Записываем наш конфигурационный файл в 'example.cfg'296with open('example.cfg', 'wb') as configfile:297    config.write(configfile)298```299300Пример повторного чтения файла конфигурации:301302```python303import ConfigParser304305config = ConfigParser.RawConfigParser()306config.read('example.cfg')307308# getfloat() вызывает исключение, если значение не является float.309# getint() и getboolean() делают то же самое для своих типов.310a_float = config.getfloat('Section1', 'a_float')311an_int = config.getint('Section1', 'an_int')312print a_float + an_int313314# Обратите внимание, что следующий вывод не интерполирует '%(bar)s' или '%(baz)s'.315# Это потому, что мы используем RawConfigParser().316if config.getboolean('Section1', 'a_bool'):317    print config.get('Section1', 'foo')318```319320Для получения интерполяции необходимо использовать [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser) или [`SafeConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.SafeConfigParser):321322```python323import ConfigParser324325config = ConfigParser.ConfigParser()326config.read('example.cfg')327328# Установите третий необязательный аргумент get в 1, если вы хотите использовать raw-режим.329print config.get('Section1', 'foo', 0)  # -> "Python – это весело!"330print config.get('Section1', 'foo', 1)  # -> "%(bar)s – это %(baz)s!"331332# Необязательный четвертый аргумент – это словарь с элементами, которые будут принимать333# приоритет при интерполяции.334print config.get('Section1', 'foo', 0, {'bar': 'Documentation',335                                        'baz': 'evil'})336```337338Значения по умолчанию доступны во всех трёх типах ConfigParser. Они используются в подстановке, если используемая опция не определена в другом месте.339340```python341import ConfigParser342343# Новый экземпляр с 'bar' и 'baz', по умолчанию равными 'Life' и 'hard' соответственно.344config = ConfigParser.SafeConfigParser({'bar': 'Life', 'baz': 'hard'})345config.read('example.cfg')346347print config.get('Section1', 'foo')  # -> "Python – это весело!"348config.remove_option('Section1', 'bar')349config.remove_option('Section1', 'baz')350print config.get('Section1', 'foo')  # -> "Жизнь тяжела!"351```352353Функция `opt_move` ниже позволяет перемещать опции между секциями:354355```python356def opt_move(config, section1, section2, option):357    try:358        config.set(section2, option, config.get(section1, option, 1))359    except ConfigParser.NoSectionError:360        # Создать несуществующий раздел361        config.add_section(section2)362        opt_move(config, section1, section2, option)363    else:364        config.remove_option(section1, option)365```366367Известно, что некоторые конфигурационные файлы содержат настройки без значений, но в остальном соответствуют синтаксису, поддерживаемому [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#module-ConfigParser). Параметр *allow\_no\_value* конструктора можно использовать, чтобы указать, что такие значения следует принимать:368369```pycon370>>> import ConfigParser371>>> import io372373>>> sample_config = """374... [mysqld]375... user = mysql376... pid-file = /var/run/mysqld/mysqld.pid377... skip-external-locking378... old_passwords = 1379... skip-bdb380... skip-innodb381... """382>>> config = ConfigParser.RawConfigParser(allow_no_value=True)383>>> config.readfp(io.BytesIO(sample_config))384385>>> # Настройки со значениями обрабатываются как и раньше:386>>> config.get("mysqld", "user")387'mysql'388389>>> # Настройки без значений дают None:390>>> config.get("mysqld", "skip-bdb")391392>>> # Настройки, которые не указаны, по-прежнему вызывают ошибку:393>>> config.get("mysqld", "does-not-exist")394Traceback (most recent call last):395  ...396ConfigParser.NoOptionError: No option 'does-not-exist' in section: 'mysqld'397```398