`configparser.md`

596 строк · 26.2 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/library/configparser.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `configparser` – Парсер конфигурационных файлов89Этот модуль определяет класс [`ConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser). Класс [`ConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser) реализует базовый язык разбора конфигурационных файлов, предоставляющий структуру, похожую на INI-файлы Microsoft Windows. Его можно использовать для написания программ на Python, которые легко настраиваются конечными пользователями.1011> **Предупреждение**12>13> Эта библиотека *не* интерпретирует и не записывает префиксы типа значения, используемые в расширенной версии синтаксиса INI для реестра Windows.1415Конфигурационный файл состоит из секций, начинающихся с заголовка `[section]` и за которыми следуют записи вида `name: value`, с продолжениями в стиле [**RFC 822**](https://python-all.ru/3.0/library/configparser.html) (см. раздел 3.1.1, «LONG HEADER FIELDS»); также допускается `name=value`. Обратите внимание: начальные пробелы в значениях удаляются. Необязательные значения могут содержать строки формата, ссылающиеся на другие значения в той же секции или значения в специальной секции `DEFAULT`. Дополнительные умолчания могут быть заданы при инициализации и получении. Строки, начинающиеся с `'#'` или `';'`, игнорируются и могут использоваться для комментариев.1617Например:1819```python20[My Section]21foodir: %(dir)s/whatever22dir=frob23long: this value continues24   in the next line25```2627подставит `%(dir)s` значением `dir` (`frob` в данном случае). Все подстановки ссылок выполняются по требованию.2829Значения по умолчанию можно задать, передав их в конструктор [`ConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser) в виде словаря. Дополнительные умолчания могут быть переданы в метод `get()`, который переопределит все остальные.3031Разделы обычно хранятся во встроенном словаре. Альтернативный тип словаря можно передать конструктору [`ConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser). Например, если передать тип словаря, сортирующий ключи, то при записи разделы будут отсортированы, как и ключи внутри каждого раздела.3233#### `[configparser.RawConfigParser]class configparser.RawConfigParser([defaults[, dict_type]])`3435Базовый объект конфигурации. Если указан параметр3637*defaults*3839, он инициализируется в словарь внутренних умолчаний. Если указан4041*dict\_type*4243, он будет использоваться для создания объектов-словарей для списка секций, для параметров внутри секции и для значений по умолчанию. Данный класс не поддерживает магическое поведение интерполяции.4445#### `[configparser.ConfigParser]class configparser.ConfigParser([defaults])`4647Производный класс от [`RawConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.RawConfigParser), реализующий магическую интерполяцию и добавляющий необязательные аргументы к методам [`get()`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser.get) и [`items()`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser.items). Значения в *defaults* должны быть подходящими для строковой интерполяции `%()s`. Обратите внимание, что *\_\_name\_\_* является внутренним умолчанием; его значение – имя секции, и оно переопределит любое значение, указанное в *defaults*.4849Все имена параметров, используемые в интерполяции, будут пропущены через метод `optionxform()`, как и любая другая ссылка на имя параметра. Например, при использовании реализации по умолчанию `optionxform()` (которая преобразует имена параметров в нижний регистр) значения `foo %(bar)s` и `foo %(BAR)s` эквивалентны.5051#### `[configparser.SafeConfigParser]class configparser.SafeConfigParser([defaults])`5253Производный класс от5455[`ConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser)5657, реализующий более разумный вариант магической интерполяции. Эта реализация также более предсказуема. Новые приложения должны предпочитать эту версию, если им не нужна совместимость со старыми версиями Python.5859#### `[configparser.NoSectionError]exception configparser.NoSectionError`6061Исключение, возбуждаемое, когда указанный раздел не найден.6263#### `[configparser.DuplicateSectionError]exception configparser.DuplicateSectionError`6465Исключение возбуждается, если6667`add_section()`6869вызывается с именем секции, которая уже существует.7071#### `[configparser.NoOptionError]exception configparser.NoOptionError`7273Исключение возбуждается, когда указанный параметр не найден в указанной секции.7475#### `[configparser.InterpolationError]exception configparser.InterpolationError`7677Базовый класс для исключений, возбуждаемых при возникновении проблем во время выполнения строковой интерполяции.7879#### `[configparser.InterpolationDepthError]exception configparser.InterpolationDepthError`8081Исключение возбуждается, когда строковая интерполяция не может быть завершена, так как количество итераций превышает8283[`MAX_INTERPOLATION_DEPTH`](https://python-all.ru/3.0/library/configparser.html#configparser.MAX_INTERPOLATION_DEPTH)8485. Подкласс8687[`InterpolationError`](https://python-all.ru/3.0/library/configparser.html#configparser.InterpolationError)8889.9091#### `[configparser.InterpolationMissingOptionError]exception configparser.InterpolationMissingOptionError`9293Исключение возбуждается, когда параметр, на который ссылается значение, не существует. Подкласс9495[`InterpolationError`](https://python-all.ru/3.0/library/configparser.html#configparser.InterpolationError)9697.9899#### `[configparser.InterpolationSyntaxError]exception configparser.InterpolationSyntaxError`100101Исключение возбуждается, когда исходный текст, в который выполняются подстановки, не соответствует требуемому синтаксису. Подкласс102103[`InterpolationError`](https://python-all.ru/3.0/library/configparser.html#configparser.InterpolationError)104105.106107#### `[configparser.MissingSectionHeaderError]exception configparser.MissingSectionHeaderError`108109Исключение возбуждается при попытке разобрать файл, не имеющий заголовков секций.110111#### `[configparser.ParsingError]exception configparser.ParsingError`112113Исключение, возникающее при ошибках во время разбора файла.114115#### `[configparser.MAX_INTERPOLATION_DEPTH]configparser.MAX_INTERPOLATION_DEPTH`116117Максимальная глубина рекурсивной интерполяции для118119`get()`120121, когда параметр122123*raw*124125имеет значение false. Это актуально только для класса126127[`ConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser)128129.130131> **См. также**132>133> **Модуль [`shlex`](https://python-all.ru/3.0/library/shlex.html#module-shlex)**134>135> Поддержка создания мини-языков в стиле оболочки Unix, которые можно использовать как альтернативный формат для конфигурационных файлов приложений.136137## Объекты RawConfigParser138139Экземпляры [`RawConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.RawConfigParser) имеют следующие методы:140141#### `[configparser.RawConfigParser.defaults]RawConfigParser.defaults()`142143Возвращает словарь, содержащий значения по умолчанию для экземпляра.144145#### `[configparser.RawConfigParser.sections]RawConfigParser.sections()`146147Возвращает список доступных секций;148149`DEFAULT`150151не включается в список.152153#### `[configparser.RawConfigParser.add_section]RawConfigParser.add_section(section)`154155Add a section named156157*section*158159to the instance. If a section by the given name already exists,160161[`DuplicateSectionError`](https://python-all.ru/3.0/library/configparser.html#configparser.DuplicateSectionError)162163is raised. If the name164165`DEFAULT`166167(or any of it’s case-insensitive variants) is passed,168169[`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError)170171is raised.172173#### `[configparser.RawConfigParser.has_section]RawConfigParser.has_section(section)`174175Указывает, присутствует ли именованный раздел в конфигурации. Раздел176177`DEFAULT`178179не учитывается.180181#### `[configparser.RawConfigParser.options]RawConfigParser.options(section)`182183Возвращает список опций, доступных в указанном разделе184185*section*186187.188189#### `[configparser.RawConfigParser.has_option]RawConfigParser.has_option(section, option)`190191Если указанный раздел существует и содержит указанную опцию, возвращает192193[`True`](https://python-all.ru/3.0/library/constants.html#True)194195; в противном случае возвращает196197[`False`](https://python-all.ru/3.0/library/constants.html#False)198199.200201#### `[configparser.RawConfigParser.read]RawConfigParser.read(filenames)`202203Пытается прочитать и разобрать список имён файлов, возвращая список имён файлов, которые были успешно разобраны. Если *filenames* является строкой, она считается единственным именем файла. Если файл, указанный в *filenames*, не может быть открыт, этот файл игнорируется. Это сделано для того, чтобы можно было указать список потенциальных расположений файлов конфигурации (например, текущий каталог, домашний каталог пользователя и общесистемный каталог), и все существующие файлы конфигурации из этого списка будут прочитаны. Если ни одного из указанных файлов не существует, экземпляр [`ConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser) будет содержать пустой набор данных. Приложение, которому требуется загружать начальные значения из файла, должно сначала загрузить необходимый файл или файлы с помощью [`readfp()`](https://python-all.ru/3.0/library/configparser.html#configparser.RawConfigParser.readfp), а затем вызывать [`read()`](https://python-all.ru/3.0/library/configparser.html#configparser.RawConfigParser.read) для любых дополнительных файлов:204205```python206import configparser, os207208config = configparser.ConfigParser()209config.readfp(open('defaults.cfg'))210config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])211```212213#### `[configparser.RawConfigParser.readfp]RawConfigParser.readfp(fp[, filename])`214215Читает и разбирает конфигурационные данные из файла или файлоподобного объекта216217*fp*218219(используется только метод220221`readline()`222223). Если параметр224225*filename*226227не указан, а228229*fp*230231имеет атрибут232233`name`234235, то он используется как236237*filename*238239; по умолчанию –240241`<???>`242243.244245#### `[configparser.RawConfigParser.get]RawConfigParser.get(section, option)`246247Получает значение опции248249*option*250251для именованного раздела252253*section*254255.256257#### `[configparser.RawConfigParser.getint]RawConfigParser.getint(section, option)`258259Удобный метод, который приводит опцию260261*option*262263в указанном разделе264265*section*266267к целому числу.268269#### `[configparser.RawConfigParser.getfloat]RawConfigParser.getfloat(section, option)`270271Удобный метод, который приводит опцию272273*option*274275в указанном разделе276277*section*278279к числу с плавающей точкой.280281#### `[configparser.RawConfigParser.getboolean]RawConfigParser.getboolean(section, option)`282283A convenience method which coerces the284285*option*286287in the specified288289*section*290291to a Boolean value. Note that the accepted values for the option are292293`"1"`294295,296297`"yes"`298299,300301`"true"`302303, and304305`"on"`306307, which cause this method to return308309`True`310311, and312313`"0"`314315,316317`"no"`318319,320321`"false"`322323, and324325`"off"`326327, which cause it to return328329`False`330331. These string values are checked in a case-insensitive manner. Any other value will cause it to raise332333[`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError)334335.336337#### `[configparser.RawConfigParser.items]RawConfigParser.items(section)`338339Возвращает список пар340341`(name, value)`342343для каждой опции в заданном разделе344345*section*346347.348349#### `[configparser.RawConfigParser.set]RawConfigParser.set(section, option, value)`350351Если указанный раздел существует, устанавливает заданную опцию в указанное значение; в противном случае возбуждает352353[`NoSectionError`](https://python-all.ru/3.0/library/configparser.html#configparser.NoSectionError)354355. Хотя можно использовать356357[`RawConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.RawConfigParser)358359(или360361[`ConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser)362363с параметром364365*raw*366367, установленным в true) для368369*внутреннего*370371хранения значений, не являющихся строками, полная функциональность (включая интерполяцию и вывод в файлы) достигается только при использовании строковых значений.372373#### `[configparser.RawConfigParser.write]RawConfigParser.write(fileobject)`374375Записывает представление конфигурации в указанный файловый объект. Это представление может быть разобрано последующим вызовом376377[`read()`](https://python-all.ru/3.0/library/configparser.html#configparser.RawConfigParser.read)378379.380381#### `[configparser.RawConfigParser.remove_option]RawConfigParser.remove_option(section, option)`382383Удаляет указанную опцию384385*option*386387из указанного раздела388389*section*390391. Если раздел не существует, возбуждает392393[`NoSectionError`](https://python-all.ru/3.0/library/configparser.html#configparser.NoSectionError)394395. Если опция существовала и была удалена, возвращает396397[`True`](https://python-all.ru/3.0/library/constants.html#True)398399; в противном случае возвращает400401[`False`](https://python-all.ru/3.0/library/constants.html#False)402403.404405#### `[configparser.RawConfigParser.remove_section]RawConfigParser.remove_section(section)`406407Удаляет указанный раздел408409*section*410411из конфигурации. Если раздел действительно существовал, возвращает412413`True`414415. В противном случае возвращает416417`False`418419.420421#### `[configparser.RawConfigParser.optionxform]RawConfigParser.optionxform(option)`422423Преобразует имя опции424425*option*426427, как оно встречается во входном файле или передаётся клиентским кодом, в форму, которая должна использоваться во внутренних структурах. Реализация по умолчанию возвращает строчную версию428429*option*430431; подклассы могут переопределить это, или клиентский код может установить атрибут с таким именем на экземплярах, чтобы повлиять на это поведение. Установка этого значения в432433[`str()`](https://python-all.ru/3.0/library/functions.html#str)434435, например, сделает имена опций чувствительными к регистру.436437## Объекты ConfigParser438439Класс [`ConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser) расширяет некоторые методы интерфейса [`RawConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.RawConfigParser), добавляя несколько необязательных аргументов.440441#### `[configparser.ConfigParser.get]ConfigParser.get(section, option[, raw[, vars]])`442443Получает значение444445*option*446447для указанной448449*section*450451. Все452453`'%'`454455подстановки раскрываются в возвращаемых значениях на основе значений по умолчанию, переданных в конструктор, а также предоставленных опций456457*vars*458459, если аргумент460461*raw*462463не равен true.464465#### `[configparser.ConfigParser.items]ConfigParser.items(section[, raw[, vars]])`466467Возвращает список пар468469`(name, value)`470471для каждой опции в указанном472473*разделе*474475. Необязательные аргументы имеют тот же смысл, что и для метода476477[`get()`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser.get)478479.480481## Объекты SafeConfigParser482483Класс [`SafeConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.SafeConfigParser) реализует тот же расширенный интерфейс, что и [`ConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser), со следующим дополнением:484485#### `[configparser.SafeConfigParser.set]SafeConfigParser.set(section, option, value)`486487Если указанный раздел существует, устанавливает для данной опции заданное значение; в противном случае возбуждает488489[`NoSectionError`](https://python-all.ru/3.0/library/configparser.html#configparser.NoSectionError)490491.492493*значение*494495должен быть строкой; если это не так, возбуждается496497[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)498499.500501## Примеры502503Пример записи в файл конфигурации:504505```python506import configparser507508config = configparser.RawConfigParser()509510# При добавлении разделов или элементов добавляйте их в обратном порядке511# как они должны отображаться в реальном файле.512# Кроме того, обратите внимание, что использование RawConfigParser и raw513# режима соответствующих функций set ConfigParser позволяет присваивать514# нестроковые значения ключам внутри, но вы получите ошибку515# при попытке записи в файл или при получении в необработанном516# режиме. SafeConfigParser не допускает таких присваиваний.517config.add_section('Section1')518config.set('Section1', 'int', '15')519config.set('Section1', 'bool', 'true')520config.set('Section1', 'float', '3.1415')521config.set('Section1', 'baz', 'fun')522config.set('Section1', 'bar', 'Python')523config.set('Section1', 'foo', '%(bar)s is %(baz)s!')524525# Записываем наш конфигурационный файл в 'example.cfg'526with open('example.cfg', 'wb') as configfile:527    config.write(configfile)528```529530Пример повторного чтения файла конфигурации:531532```python533import configparser534535config = configparser.RawConfigParser()536config.read('example.cfg')537538# getfloat() вызывает исключение, если значение не является float.539# getint() и getboolean() делают то же самое для своих типов.540float = config.getfloat('Section1', 'float')541int = config.getint('Section1', 'int')542print(float + int)543544# Обратите внимание, что следующий вывод не интерполирует '%(bar)s' или '%(baz)s'.545# Это потому, что мы используем RawConfigParser().546if config.getboolean('Section1', 'bool'):547    print(config.get('Section1', 'foo'))548```549550Для использования подстановки потребуется [`ConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser) или [`SafeConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.SafeConfigParser):551552```python553import configparser554555config = configparser.ConfigParser()556config.read('example.cfg')557558# Установите третий необязательный аргумент get в 1, если вы хотите использовать raw-режим.559print(config.get('Section1', 'foo', 0)) # -> "Python – это весело!"560print(config.get('Section1', 'foo', 1)) # -> "%(bar)s – это %(baz)s!"561562# Необязательный четвертый аргумент – это словарь с элементами, которые будут принимать563# приоритет при интерполяции.564print(config.get('Section1', 'foo', 0, {'bar': 'Documentation',565                                        'baz': 'evil'}))566```567568Значения по умолчанию доступны во всех трёх типах ConfigParser. Они используются в подстановке, если используемая опция не определена в другом месте.569570```python571import configparser572573# Новый экземпляр с 'bar' и 'baz', по умолчанию равными 'Life' и 'hard' соответственно.574config = configparser.SafeConfigParser({'bar': 'Life', 'baz': 'hard'})575config.read('example.cfg')576577print(config.get('Section1', 'foo')) # -> "Python – это весело!"578config.remove_option('Section1', 'bar')579config.remove_option('Section1', 'baz')580print(config.get('Section1', 'foo')) # -> "Жизнь тяжела!"581```582583Функция `opt_move` ниже может использоваться для перемещения опций между разделами:584585```python586def opt_move(config, section1, section2, option):587    try:588        config.set(section2, option, config.get(section1, option, 1))589    except configparser.NoSectionError:590        # Создать несуществующий раздел591        config.add_section(section2)592        opt_move(config, section1, section2, option)593    else:594        config.remove_option(section1, option)595```596