`configparser.md`

566 строк · 28.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/library/configparser.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 13.2. `configparser` – Парсер конфигурационных файлов89Этот модуль определяет класс [`ConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.ConfigParser). Класс [`ConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.ConfigParser) реализует базовый язык разбора конфигурационных файлов, предоставляющий структуру, похожую на INI-файлы Microsoft Windows. Его можно использовать для написания программ на Python, которые легко настраиваются конечными пользователями.1011> **Примечание**12>13> Эта библиотека *не* интерпретирует и не записывает префиксы типов значений, используемые в расширенной версии синтаксиса INI из реестра Windows.1415> **См. также**16>17> **Модуль [`shlex`](https://python-all.ru/3.1/library/shlex.html#module-shlex)**18>19> Поддержка создания мини-языков в стиле оболочки Unix, которые можно использовать в качестве альтернативного формата для файлов конфигурации приложений.20>21> **Модуль [`json`](https://python-all.ru/3.1/library/json.html#module-json)**22>23> Модуль json реализует подмножество синтаксиса JavaScript, которое также можно использовать для этой цели.2425Конфигурационный файл состоит из секций, начинающихся с заголовка `[section]` и за которыми следуют записи вида `name: value`, с продолжениями в стиле [**RFC 822**](https://python-all.ru/3.1/library/configparser.html) (см. раздел 3.1.1, «LONG HEADER FIELDS»); также допускается `name=value`. Обратите внимание: начальные пробелы в значениях удаляются. Необязательные значения могут содержать строки формата, ссылающиеся на другие значения в той же секции или значения в специальной секции `DEFAULT`. Дополнительные умолчания могут быть заданы при инициализации и получении. Строки, начинающиеся с `'#'` или `';'`, игнорируются и могут использоваться для комментариев.2627Файлы конфигурации могут содержать комментарии, помеченные специальными символами (`#` и `;`). Комментарии могут находиться на отдельной пустой строке или вставляться в строки со значениями или именами секций. В последнем случае перед ними должен быть пробельный символ, чтобы распознаваться как комментарий. (Для обратной совместимости только `;` начинает встроенный комментарий, а `#` – нет.)2829Помимо основной функциональности, [`SafeConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.SafeConfigParser) поддерживает интерполяцию. Это означает, что значения могут содержать строки формата, ссылающиеся на другие значения в той же секции или значения в специальной секции `DEFAULT`. Дополнительные умолчания могут быть заданы при инициализации.3031Например:3233```python34[My Section]35foodir: %(dir)s/whatever36dir=frob37long: this value continues38   in the next line39```4041подставит `%(dir)s` значением `dir` (`frob` в данном случае). Все подстановки ссылок выполняются по требованию.4243Значения по умолчанию можно задать, передав их в конструктор [`ConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.ConfigParser) в виде словаря. Дополнительные умолчания могут быть переданы в метод `get()`, который переопределит все остальные.4445Секции обычно хранятся во встроенном словаре. Альтернативный тип словаря можно передать конструктору [`ConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.ConfigParser). Например, если передан тип словаря, который сортирует ключи, то секции будут отсортированы при записи, как и ключи внутри каждой секции.4647#### `class configparser.RawConfigParser(defaults=None, dict_type=collections.OrderedDict)`4849Базовый объект конфигурации. Если указан параметр *defaults*, он инициализируется в словарь внутренних умолчаний. Если указан *dict\_type*, он будет использоваться для создания объектов-словарей для списка секций, для параметров внутри секции и для значений по умолчанию. Данный класс не поддерживает магическое поведение интерполяции.5051Изменено в версии 3.1: Значение по умолчанию *dict\_type* – [`collections.OrderedDict`](https://python-all.ru/3.1/library/collections.html#collections.OrderedDict).5253#### `class configparser.ConfigParser(defaults=None, dict_type=collections.OrderedDict)`5455Производный класс от [`RawConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.RawConfigParser), реализующий магическую интерполяцию и добавляющий необязательные аргументы к методам [`get()`](https://python-all.ru/3.1/library/configparser.html#configparser.ConfigParser.get) и [`items()`](https://python-all.ru/3.1/library/configparser.html#configparser.ConfigParser.items). Значения в *defaults* должны быть подходящими для строковой интерполяции `%()s`. Обратите внимание, что *\_\_name\_\_* является внутренним умолчанием; его значение – имя секции, и оно переопределит любое значение, указанное в *defaults*.5657Все имена параметров, используемые в интерполяции, будут пропущены через метод `optionxform()`, как и любая другая ссылка на имя параметра. Например, при использовании реализации по умолчанию `optionxform()` (которая преобразует имена параметров в нижний регистр) значения `foo %(bar)s` и `foo %(BAR)s` эквивалентны.5859Изменено в версии 3.1: Значение по умолчанию *dict\_type* – [`collections.OrderedDict`](https://python-all.ru/3.1/library/collections.html#collections.OrderedDict).6061#### `class configparser.SafeConfigParser(defaults=None, dict_type=collections.OrderedDict)`6263Производный класс от [`ConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.ConfigParser), реализующий более разумный вариант магической интерполяции. Эта реализация также более предсказуема. Новые приложения должны предпочитать эту версию, если им не нужна совместимость со старыми версиями Python.6465Изменено в версии 3.1: Значение по умолчанию *dict\_type* – [`collections.OrderedDict`](https://python-all.ru/3.1/library/collections.html#collections.OrderedDict).6667#### `exception configparser.Error`6869Базовый класс для всех остальных исключений configparser.7071#### `exception configparser.NoSectionError`7273Исключение, возбуждаемое, когда указанный раздел не найден.7475#### `exception configparser.DuplicateSectionError`7677Исключение возбуждается, если7879`add_section()`8081вызывается с именем секции, которая уже существует.8283#### `exception configparser.NoOptionError`8485Исключение возбуждается, когда указанный параметр не найден в указанной секции.8687#### `exception configparser.InterpolationError`8889Базовый класс для исключений, возбуждаемых при возникновении проблем во время выполнения строковой интерполяции.9091#### `exception configparser.InterpolationDepthError`9293Исключение возбуждается, когда строковая интерполяция не может быть завершена, так как количество итераций превышает9495[`MAX_INTERPOLATION_DEPTH`](https://python-all.ru/3.1/library/configparser.html#configparser.MAX_INTERPOLATION_DEPTH)9697. Подкласс9899[`InterpolationError`](https://python-all.ru/3.1/library/configparser.html#configparser.InterpolationError)100101.102103#### `exception configparser.InterpolationMissingOptionError`104105Исключение возбуждается, когда параметр, на который ссылается значение, не существует. Подкласс106107[`InterpolationError`](https://python-all.ru/3.1/library/configparser.html#configparser.InterpolationError)108109.110111#### `exception configparser.InterpolationSyntaxError`112113Исключение возбуждается, когда исходный текст, в который выполняются подстановки, не соответствует требуемому синтаксису. Подкласс114115[`InterpolationError`](https://python-all.ru/3.1/library/configparser.html#configparser.InterpolationError)116117.118119#### `exception configparser.MissingSectionHeaderError`120121Исключение возбуждается при попытке разобрать файл, не имеющий заголовков секций.122123#### `exception configparser.ParsingError`124125Исключение, возникающее при ошибках во время разбора файла.126127#### `configparser.MAX_INTERPOLATION_DEPTH`128129Максимальная глубина рекурсивной интерполяции для130131`get()`132133, когда параметр134135*raw*136137имеет значение false. Это актуально только для класса138139[`ConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.ConfigParser)140141.142143> **См. также**144>145> **Модуль [`shlex`](https://python-all.ru/3.1/library/shlex.html#module-shlex)**146>147> Поддержка создания мини-языков в стиле оболочки Unix, которые можно использовать как альтернативный формат для конфигурационных файлов приложений.148149## 13.2.1. Объекты RawConfigParser150151Экземпляры [`RawConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.RawConfigParser) имеют следующие методы:152153#### `RawConfigParser.defaults()`154155Возвращает словарь, содержащий значения по умолчанию для экземпляра.156157#### `RawConfigParser.sections()`158159Возвращает список доступных секций;160161`DEFAULT`162163не включается в список.164165#### `RawConfigParser.add_section(section)`166167Add a section named168169*section*170171to the instance. If a section by the given name already exists,172173[`DuplicateSectionError`](https://python-all.ru/3.1/library/configparser.html#configparser.DuplicateSectionError)174175is raised. If the name176177`DEFAULT`178179(or any of it’s case-insensitive variants) is passed,180181[`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError)182183is raised.184185#### `RawConfigParser.has_section(section)`186187Указывает, присутствует ли именованный раздел в конфигурации. Раздел188189`DEFAULT`190191не учитывается.192193#### `RawConfigParser.options(section)`194195Возвращает список опций, доступных в указанном разделе196197*section*198199.200201#### `RawConfigParser.has_option(section, option)`202203Если указанный раздел существует и содержит указанную опцию, возвращает204205[`True`](https://python-all.ru/3.1/library/constants.html#True)206207; в противном случае возвращает208209[`False`](https://python-all.ru/3.1/library/constants.html#False)210211.212213#### `RawConfigParser.read(filenames)`214215Пытается прочитать и разобрать список имён файлов, возвращая список имён файлов, которые были успешно разобраны. Если *filenames* является строкой, она считается единственным именем файла. Если файл, указанный в *filenames*, не может быть открыт, этот файл игнорируется. Это сделано для того, чтобы можно было указать список потенциальных расположений файлов конфигурации (например, текущий каталог, домашний каталог пользователя и общесистемный каталог), и все существующие файлы конфигурации из этого списка будут прочитаны. Если ни одного из указанных файлов не существует, экземпляр [`ConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.ConfigParser) будет содержать пустой набор данных. Приложение, которому требуется загружать начальные значения из файла, должно сначала загрузить необходимый файл или файлы с помощью [`readfp()`](https://python-all.ru/3.1/library/configparser.html#configparser.RawConfigParser.readfp), а затем вызывать [`read()`](https://python-all.ru/3.1/library/configparser.html#configparser.RawConfigParser.read) для любых дополнительных файлов:216217```python218import configparser, os219220config = configparser.ConfigParser()221config.readfp(open('defaults.cfg'))222config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])223```224225#### `RawConfigParser.readfp(fp, filename=None)`226227Читает и разбирает данные конфигурации из файла или файлоподобного объекта *fp* (используется только метод `readline()`). Файлоподобный объект должен работать в текстовом режиме, т.е. возвращать строки из `readline()`.228229Если *filename* опущен и *fp* имеет атрибут `name`, то он используется для *filename*; по умолчанию используется `<???>`.230231#### `RawConfigParser.get(section, option)`232233Получает значение опции234235*option*236237для именованного раздела238239*section*240241.242243#### `RawConfigParser.getint(section, option)`244245Удобный метод, который приводит опцию246247*option*248249в указанном разделе250251*section*252253к целому числу.254255#### `RawConfigParser.getfloat(section, option)`256257Удобный метод, который приводит опцию258259*option*260261в указанном разделе262263*section*264265к числу с плавающей точкой.266267#### `RawConfigParser.getboolean(section, option)`268269A convenience method which coerces the270271*option*272273in the specified274275*section*276277to a Boolean value. Note that the accepted values for the option are278279`"1"`280281,282283`"yes"`284285,286287`"true"`288289, and290291`"on"`292293, which cause this method to return294295`True`296297, and298299`"0"`300301,302303`"no"`304305,306307`"false"`308309, and310311`"off"`312313, which cause it to return314315`False`316317. These string values are checked in a case-insensitive manner. Any other value will cause it to raise318319[`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError)320321.322323#### `RawConfigParser.items(section)`324325Возвращает список пар326327`(name, value)`328329для каждой опции в заданном разделе330331*section*332333.334335#### `RawConfigParser.set(section, option, value)`336337Если указанный раздел существует, устанавливает заданную опцию в указанное значение; в противном случае возбуждает338339[`NoSectionError`](https://python-all.ru/3.1/library/configparser.html#configparser.NoSectionError)340341. Хотя можно использовать342343[`RawConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.RawConfigParser)344345(или346347[`ConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.ConfigParser)348349с параметром350351*raw*352353, установленным в true) для354355*внутреннего*356357хранения значений, не являющихся строками, полная функциональность (включая интерполяцию и вывод в файлы) достигается только при использовании строковых значений.358359#### `RawConfigParser.write(fileobject)`360361Записывает представление конфигурации в указанный362363[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)364365, который должен быть открыт в текстовом режиме (принимающем строки). Это представление может быть разобрано последующим вызовом366367[`read()`](https://python-all.ru/3.1/library/configparser.html#configparser.RawConfigParser.read)368369.370371#### `RawConfigParser.remove_option(section, option)`372373Удаляет указанную опцию374375*option*376377из указанного раздела378379*section*380381. Если раздел не существует, возбуждает382383[`NoSectionError`](https://python-all.ru/3.1/library/configparser.html#configparser.NoSectionError)384385. Если опция существовала и была удалена, возвращает386387[`True`](https://python-all.ru/3.1/library/constants.html#True)388389; в противном случае возвращает390391[`False`](https://python-all.ru/3.1/library/constants.html#False)392393.394395#### `RawConfigParser.remove_section(section)`396397Удаляет указанный раздел398399*section*400401из конфигурации. Если раздел действительно существовал, возвращает402403`True`404405. В противном случае возвращает406407`False`408409.410411#### `RawConfigParser.optionxform(option)`412413Преобразует имя опции *option*, которое встречается во входном файле или передаётся клиентским кодом, в форму, которая должна использоваться во внутренних структурах. Реализация по умолчанию возвращает версию *option* в нижнем регистре; подклассы могут переопределить это, или клиентский код может установить атрибут с таким именем на экземплярах для изменения этого поведения.414415Чтобы использовать этот метод, необязательно создавать подкласс ConfigParser – можно также переопределить его для экземпляра, установив функцию, принимающую строковый аргумент. Если, например, установить значение `str`, имена опций станут чувствительны к регистру:416417```python418cfgparser = ConfigParser()419...420cfgparser.optionxform = str421```422423Обратите внимание: при чтении конфигурационных файлов пробелы вокруг имён опций удаляются перед вызовом [`optionxform()`](https://python-all.ru/3.1/library/configparser.html#configparser.RawConfigParser.optionxform).424425## 13.2.2. Объекты ConfigParser426427Класс [`ConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.ConfigParser) расширяет некоторые методы интерфейса [`RawConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.RawConfigParser), добавляя несколько необязательных аргументов.428429#### `ConfigParser.get(section, option, raw=False, vars=None)`430431Получает значение *опции* для указанного *раздела*. Если *vars* передан, он должен быть словарём. Поиск *опции* выполняется в *vars* (если передан), *разделе* и *значениях по умолчанию* в указанном порядке.432433Все `'%'` подстановки раскрываются в возвращаемых значениях, если только аргумент *raw* не равен true. Значения ключей подстановки ищутся так же, как и опция.434435#### `ConfigParser.items(section, raw=False, vars=None)`436437Возвращает список пар438439`(name, value)`440441для каждой опции в указанном442443*разделе*444445. Необязательные аргументы имеют тот же смысл, что и для метода446447[`get()`](https://python-all.ru/3.1/library/configparser.html#configparser.ConfigParser.get)448449.450451## 13.2.3. Объекты SafeConfigParser452453Класс [`SafeConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.SafeConfigParser) реализует тот же расширенный интерфейс, что и [`ConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.ConfigParser), со следующим дополнением:454455#### `SafeConfigParser.set(section, option, value)`456457Если указанный раздел существует, устанавливает для данной опции заданное значение; в противном случае возбуждает458459[`NoSectionError`](https://python-all.ru/3.1/library/configparser.html#configparser.NoSectionError)460461.462463*значение*464465должен быть строкой; если это не так, возбуждается466467[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)468469.470471## 13.2.4. Примеры472473Пример записи в файл конфигурации:474475```python476import configparser477478config = configparser.RawConfigParser()479480# При добавлении разделов или элементов добавляйте их в обратном порядке481# как они должны отображаться в реальном файле.482# Кроме того, обратите внимание, что использование RawConfigParser и raw483# режима соответствующих функций set ConfigParser позволяет присваивать484# нестроковые значения ключам внутри, но вы получите ошибку485# при попытке записи в файл или при получении в необработанном486# режиме. SafeConfigParser не допускает таких присваиваний.487config.add_section('Section1')488config.set('Section1', 'int', '15')489config.set('Section1', 'bool', 'true')490config.set('Section1', 'float', '3.1415')491config.set('Section1', 'baz', 'fun')492config.set('Section1', 'bar', 'Python')493config.set('Section1', 'foo', '%(bar)s is %(baz)s!')494495# Записываем наш конфигурационный файл в 'example.cfg'496with open('example.cfg', 'w') as configfile:497    config.write(configfile)498```499500Пример повторного чтения файла конфигурации:501502```python503import configparser504505config = configparser.RawConfigParser()506config.read('example.cfg')507508# getfloat() вызывает исключение, если значение не является float.509# getint() и getboolean() делают то же самое для своих типов.510float = config.getfloat('Section1', 'float')511int = config.getint('Section1', 'int')512print(float + int)513514# Обратите внимание, что следующий вывод не интерполирует '%(bar)s' или '%(baz)s'.515# Это потому, что мы используем RawConfigParser().516if config.getboolean('Section1', 'bool'):517    print(config.get('Section1', 'foo'))518```519520Для использования подстановки потребуется [`ConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.ConfigParser) или [`SafeConfigParser`](https://python-all.ru/3.1/library/configparser.html#configparser.SafeConfigParser):521522```python523import configparser524525config = configparser.ConfigParser()526config.read('example.cfg')527528# Установите третий необязательный аргумент get в 1, если вы хотите использовать raw-режим.529print(config.get('Section1', 'foo', 0)) # -> "Python – это весело!"530print(config.get('Section1', 'foo', 1)) # -> "%(bar)s – это %(baz)s!"531532# Необязательный четвертый аргумент – это словарь с элементами, которые будут принимать533# приоритет при интерполяции.534print(config.get('Section1', 'foo', 0, {'bar': 'Documentation',535                                        'baz': 'evil'}))536```537538Значения по умолчанию доступны во всех трёх типах ConfigParser. Они используются в подстановке, если используемая опция не определена в другом месте.539540```python541import configparser542543# Новый экземпляр с 'bar' и 'baz', по умолчанию равными 'Life' и 'hard' соответственно.544config = configparser.SafeConfigParser({'bar': 'Life', 'baz': 'hard'})545config.read('example.cfg')546547print(config.get('Section1', 'foo')) # -> "Python – это весело!"548config.remove_option('Section1', 'bar')549config.remove_option('Section1', 'baz')550print(config.get('Section1', 'foo')) # -> "Жизнь тяжела!"551```552553Функция `opt_move` ниже может использоваться для перемещения опций между разделами:554555```python556def opt_move(config, section1, section2, option):557    try:558        config.set(section2, option, config.get(section1, option, 1))559    except configparser.NoSectionError:560        # Создать несуществующий раздел561        config.add_section(section2)562        opt_move(config, section1, section2, option)563    else:564        config.remove_option(section1, option)565```566