configparser
— Парсер конфигурационных файлов¶
Источник: Lib/configparser.py
Этот модуль предоставляет класс ConfigParser
, который реализует базовый язык конфигурации, обеспечивающий структуру, подобную той, что присутствует в INI-файлах Microsoft Windows. Вы можете использовать его для написания программ на Python, которые могут быть легко настроены конечными пользователями.
Примечание
Эта библиотека не интерпретирует и не записывает префиксы типов значений, используемые в расширенной версии синтаксиса INI реестра Windows.
См.также
- Модуль
tomllib
TOML - это хорошо специфицированный формат для файлов конфигурации приложений. Он специально разработан как улучшенная версия INI.
- Модуль
shlex
Поддержка создания Unix shell-подобных мини-языков, которые также могут быть использованы для конфигурационных файлов приложений.
- Модуль
json
Модуль
json
реализует подмножество синтаксиса JavaScript, которое иногда используется для настройки, но не поддерживает комментарии.
Быстрый старт¶
Возьмем базовый файл конфигурации, который выглядит следующим образом:
[DEFAULT]
ServerAliveInterval = 45
Compression = yes
CompressionLevel = 9
ForwardX11 = yes
[forge.example]
User = hg
[topsecret.server.example]
Port = 50022
ForwardX11 = no
Структура INI-файлов описана in the following section. По сути, файл состоит из секций, каждая из которых содержит ключи со значениями. Классы configparser
могут читать и записывать такие файлы. Начнем с того, что создадим приведенный выше конфигурационный файл программно.
>>> import configparser
>>> config = configparser.ConfigParser()
>>> config['DEFAULT'] = {'ServerAliveInterval': '45',
... 'Compression': 'yes',
... 'CompressionLevel': '9'}
>>> config['forge.example'] = {}
>>> config['forge.example']['User'] = 'hg'
>>> config['topsecret.server.example'] = {}
>>> topsecret = config['topsecret.server.example']
>>> topsecret['Port'] = '50022' # mutates the parser
>>> topsecret['ForwardX11'] = 'no' # same here
>>> config['DEFAULT']['ForwardX11'] = 'yes'
>>> with open('example.ini', 'w') as configfile:
... config.write(configfile)
...
Как видите, мы можем обращаться с парсером конфигурации примерно так же, как со словарем. Есть различия, outlined later, но поведение очень близко к тому, что вы ожидаете от словаря.
Теперь, когда мы создали и сохранили файл конфигурации, давайте прочитаем его и изучим содержащиеся в нем данные.
>>> config = configparser.ConfigParser()
>>> config.sections()
[]
>>> config.read('example.ini')
['example.ini']
>>> config.sections()
['forge.example', 'topsecret.server.example']
>>> 'forge.example' in config
True
>>> 'python.org' in config
False
>>> config['forge.example']['User']
'hg'
>>> config['DEFAULT']['Compression']
'yes'
>>> topsecret = config['topsecret.server.example']
>>> topsecret['ForwardX11']
'no'
>>> topsecret['Port']
'50022'
>>> for key in config['forge.example']:
... print(key)
user
compressionlevel
serveraliveinterval
compression
forwardx11
>>> config['forge.example']['ForwardX11']
'yes'
Как мы видим, API довольно прост. Единственный кусочек магии связан с секцией DEFAULT
, которая предоставляет значения по умолчанию для всех остальных секций [1]. Обратите внимание, что ключи в секциях не чувствительны к регистру и хранятся в нижнем регистре [1].
Можно считывать несколько конфигураций в один ConfigParser
, при этом самая последняя добавленная конфигурация имеет наивысший приоритет. Все конфликтующие ключи берутся из последней конфигурации, а ранее существовавшие ключи сохраняются.
>>> another_config = configparser.ConfigParser()
>>> another_config.read('example.ini')
['example.ini']
>>> another_config['topsecret.server.example']['Port']
'50022'
>>> another_config.read_string("[topsecret.server.example]\nPort=48484")
>>> another_config['topsecret.server.example']['Port']
'48484'
>>> another_config.read_dict({"topsecret.server.example": {"Port": 21212}})
>>> another_config['topsecret.server.example']['Port']
'21212'
>>> another_config['topsecret.server.example']['ForwardX11']
'no'
Такое поведение эквивалентно вызову ConfigParser.read()
с несколькими файлами, переданными в параметре filenames.
Поддерживаемые типы данных¶
Парсеры конфигураций не угадывают типы данных значений в конфигурационных файлах, всегда сохраняя их внутри как строки. Это означает, что если вам нужны другие типы данных, вы должны преобразовать их самостоятельно:
>>> int(topsecret['Port'])
50022
>>> float(topsecret['CompressionLevel'])
9.0
Поскольку эта задача встречается так часто, парсеры конфигураций предоставляют ряд удобных методов getter для работы с целыми числами, плавающими числами и булевыми числами. Последний метод наиболее интересен, поскольку простая передача значения в bool()
не принесет пользы, так как bool('False')
все равно будет True
. Поэтому парсеры конфигураций также предоставляют getboolean()
. Этот метод не зависит от регистра и распознает булевы значения из 'yes'
/'no'
, 'on'
/'off'
, 'true'
/'false'
и '1'
/'0'
[1]. Например:
>>> topsecret.getboolean('ForwardX11')
False
>>> config['forge.example'].getboolean('ForwardX11')
True
>>> config.getboolean('forge.example', 'Compression')
True
Помимо getboolean()
, парсеры конфигураций также предоставляют эквивалентные методы getint()
и getfloat()
. Вы можете зарегистрировать свои собственные конвертеры и настроить предоставленные. [1]
Значения резервного копирования¶
Как и в случае со словарем, вы можете использовать метод get()
секции для предоставления резервных значений:
>>> topsecret.get('Port')
'50022'
>>> topsecret.get('CompressionLevel')
'9'
>>> topsecret.get('Cipher')
>>> topsecret.get('Cipher', '3des-cbc')
'3des-cbc'
Обратите внимание, что значения по умолчанию имеют приоритет над запасными значениями. Например, в нашем примере ключ 'CompressionLevel'
был указан только в разделе 'DEFAULT'
. Если мы попытаемся получить его из секции 'topsecret.server.example'
, мы всегда получим значение по умолчанию, даже если укажем запасной вариант:
>>> topsecret.get('CompressionLevel', '3')
'9'
Еще один момент, о котором следует знать: метод get()
на уровне парсера предоставляет собственный, более сложный интерфейс, поддерживаемый для обратной совместимости. При использовании этого метода можно указать запасное значение через аргумент fallback
, содержащий только ключевое слово:
>>> config.get('forge.example', 'monster',
... fallback='No such things as monsters')
'No such things as monsters'
Один и тот же аргумент fallback
может использоваться, например, в методах getint()
, getfloat()
и getboolean()
:
>>> 'BatchMode' in topsecret
False
>>> topsecret.getboolean('BatchMode', fallback=True)
True
>>> config['DEFAULT']['BatchMode'] = 'no'
>>> topsecret.getboolean('BatchMode', fallback=True)
False
Поддерживаемая структура файлов INI¶
Конфигурационный файл состоит из секций, каждая из которых начинается с заголовка [section]
, за которым следуют записи ключей/значений, разделенные определенной строкой (=
или :
, по умолчанию [1]). По умолчанию имена секций чувствительны к регистру, а ключи - нет [1]. Ведущие и последующие пробельные символы удаляются из ключей и значений. Значения могут быть опущены, если парсер настроен на это [1], в этом случае разделитель ключ/значение также может быть опущен. Значения также могут занимать несколько строк, при условии, что они отступают глубже, чем первая строка значения. В зависимости от режима работы парсера пустые строки могут рассматриваться как части многострочных значений или игнорироваться.
По умолчанию именем секции может быть любая строка, не содержащая „\n“. Чтобы изменить это, смотрите ConfigParser.SECTCRE
.
Имя первой секции может быть опущено, если парсер настроен на разрешение безымянной секции верхнего уровня с помощью allow_unnamed_section=True
. В этом случае ключи/значения могут быть получены по UNNAMED_SECTION
, как в config[UNNAMED_SECTION]
.
Файлы конфигурации могут содержать комментарии, префикс которых состоит из определенных символов (#
и ;
, по умолчанию [1]). Комментарии могут появляться сами по себе на пустой строке, возможно, с отступом. [1]
Например:
[Simple Values]
key=value
spaces in keys=allowed
spaces in values=allowed as well
spaces around the delimiter = obviously
you can also use : to delimit keys from values
[All Values Are Strings]
values like this: 1000000
or this: 3.14159265359
are they treated as numbers? : no
integers, floats and booleans are held as: strings
can use the API to get converted values directly: true
[Multiline Values]
chorus: I'm a lumberjack, and I'm okay
I sleep all night and I work all day
[No Values]
key_without_value
empty string value here =
[You can use comments]
# like this
; or this
# By default only in an empty line.
# Inline comments can be harmful because they prevent users
# from using the delimiting characters as parts of values.
# That being said, this can be customized.
[Sections Can Be Indented]
can_values_be_as_well = True
does_that_mean_anything_special = False
purpose = formatting for readability
multiline_values = are
handled just fine as
long as they are indented
deeper than the first line
of a value
# Did I mention we can indent comments, too?
Безымянные участки¶
Имя первой секции (или уникальной) может быть опущено, а значения получены с помощью атрибута UNNAMED_SECTION
.
>>> config = """
... option = value
...
... [ Section 2 ]
... another = val
... """
>>> unnamed = configparser.ConfigParser(allow_unnamed_section=True)
>>> unnamed.read_string(config)
>>> unnamed.get(configparser.UNNAMED_SECTION, 'option')
'value'
Интерполяция значений¶
В дополнение к основной функциональности ConfigParser
поддерживает интерполяцию. Это означает, что значения могут быть предварительно обработаны перед возвратом из вызовов get()
.
- class configparser.BasicInterpolation¶
Реализация по умолчанию, используемая в
ConfigParser
. Она позволяет значениям содержать строки формата, которые ссылаются на другие значения в той же секции или на значения в специальной секции по умолчанию [1]. Дополнительные значения по умолчанию могут быть заданы при инициализации.Например:
[Paths] home_dir: /Users my_dir: %(home_dir)s/lumberjack my_pictures: %(my_dir)s/Pictures [Escape] # use a %% to escape the % sign (% is the only character that needs to be escaped): gain: 80%%
В приведенном выше примере
ConfigParser
с интерполяцией, установленной наBasicInterpolation()
, преобразует%(home_dir)s
в значениеhome_dir
(/Users
в данном случае). В результате%(my_dir)s
будет преобразовано в/Users/lumberjack
. Все интерполяции выполняются по требованию, поэтому ключи, используемые в цепочке ссылок, не обязательно указывать в конфигурационном файле в каком-то определенном порядке.Если установить
interpolation
вNone
, синтаксический анализатор просто вернет%(my_dir)s/Pictures
в качестве значенияmy_pictures
и%(home_dir)s/lumberjack
в качестве значенияmy_dir
.
- class configparser.ExtendedInterpolation¶
Альтернативный обработчик интерполяции, реализующий более продвинутый синтаксис, используемый, например, в
zc.buildout
. Расширенная интерполяция - это использование${section:option}
для обозначения значения из внешней секции. Интерполяция может охватывать несколько уровней. Для удобства, если частьsection:
опущена, интерполяция по умолчанию принимает текущий раздел (и, возможно, значения по умолчанию из специального раздела).Например, конфигурация, указанная выше с базовой интерполяцией, будет выглядеть следующим образом с расширенной интерполяцией:
[Paths] home_dir: /Users my_dir: ${home_dir}/lumberjack my_pictures: ${my_dir}/Pictures [Escape] # use a $$ to escape the $ sign ($ is the only character that needs to be escaped): cost: $$80
Значения из других разделов также могут быть получены:
[Common] home_dir: /Users library_dir: /Library system_dir: /System macports_dir: /opt/local [Frameworks] Python: 3.2 path: ${Common:system_dir}/Library/Frameworks/ [Arthur] nickname: Two Sheds last_name: Jackson my_dir: ${Common:home_dir}/twosheds my_pictures: ${my_dir}/Pictures python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}
Картографический протокол доступа¶
Added in version 3.2.
Доступ по протоколу отображения - это общее название для функциональности, позволяющей использовать пользовательские объекты так, как если бы они были словарями. В случае configparser
реализация интерфейса отображения использует нотацию parser['section']['option']
.
parser['section']
, в частности, возвращает прокси для данных секции в парсере. Это означает, что значения не копируются, а берутся из исходного парсера по требованию. Что еще более важно, так это то, что когда значения изменяются в прокси секции, они фактически изменяются в исходном парсере.
Объекты configparser
ведут себя настолько близко к реальным словарям, насколько это возможно. Интерфейс отображения является полным и придерживается MutableMapping
. ABC. Однако есть несколько отличий, которые следует принять во внимание:
По умолчанию все ключи в секциях доступны без учета регистра [1]. Например, при указании
for option in parser["section"]
будут доступны только имена клавишoptionxform
. Это означает, что по умолчанию клавиши в нижнем регистре. В то же время для секции, содержащей ключ'a'
, оба выражения возвращаютTrue
:"a" in parser["section"] "A" in parser["section"]
Все секции включают в себя также значения
DEFAULTSECT
, что означает, что.clear()
в секции может не оставлять ее пустой. Это происходит потому, что значения по умолчанию не могут быть удалены из секции (потому что технически их там нет). Если они переопределены в разделе, удаление приведет к тому, что значение по умолчанию снова станет видимым. Попытка удалить значение по умолчанию приводит к ошибкеKeyError
.DEFAULTSECT
не может быть удален из парсера:при попытке удалить его возникает ошибка
ValueError
,parser.clear()
оставляет его нетронутым,parser.popitem()
никогда не возвращает его.
parser.get(section, option, **kwargs)
- второй аргумент не является запасным значением. Однако обратите внимание, что методыget()
на уровне секций совместимы как с протоколом отображения, так и с классическим API configparser.parser.items()
совместим с протоколом отображения (возвращает список пар section_name, section_proxy, включая DEFAULTSECT). Однако этот метод может быть вызван и с аргументами:parser.items(section, raw, vars)
. Последний вызов возвращает список пар option, value для указанногоsection
, со всеми интерполяциями (если не указанraw=True
).
Протокол отображения реализован поверх существующего унаследованного API, так что подклассы, переопределяющие оригинальный интерфейс, по-прежнему должны иметь отображения, работающие как ожидалось.
Настройка поведения парсера¶
Существует почти столько же вариантов формата INI, сколько приложений, использующих его. configparser
в значительной степени обеспечивает поддержку наибольшего разумного набора стилей INI. Функциональность по умолчанию в основном продиктована историческими причинами, и вполне вероятно, что вы захотите настроить некоторые функции.
Самый распространенный способ изменить работу конкретного парсера конфигурации - использовать опции __init__()
:
defaults, значение по умолчанию:
None
Эта опция принимает словарь пар ключ-значение, которые первоначально будут помещены в секцию
DEFAULT
. Это элегантный способ поддержки кратких конфигурационных файлов, в которых не указываются значения, совпадающие с документированным значением по умолчанию.Подсказка: если вы хотите задать значения по умолчанию для определенного раздела, используйте
read_dict()
перед чтением фактического файла.dict_type, значение по умолчанию:
dict
Этот параметр оказывает существенное влияние на поведение протокола отображения и внешний вид записанных конфигурационных файлов. При использовании стандартного словаря каждая секция хранится в том порядке, в котором она была добавлена в парсер. То же самое относится и к опциям внутри секций.
Альтернативный тип словаря можно использовать, например, для сортировки секций и опций при обратной записи.
Обратите внимание: существуют способы добавления набора пар ключ-значение за одну операцию. Когда вы используете обычный словарь в этих операциях, порядок ключей будет упорядочен. Например:
>>> parser = configparser.ConfigParser() >>> parser.read_dict({'section1': {'key1': 'value1', ... 'key2': 'value2', ... 'key3': 'value3'}, ... 'section2': {'keyA': 'valueA', ... 'keyB': 'valueB', ... 'keyC': 'valueC'}, ... 'section3': {'foo': 'x', ... 'bar': 'y', ... 'baz': 'z'} ... }) >>> parser.sections() ['section1', 'section2', 'section3'] >>> [option for option in parser['section3']] ['foo', 'bar', 'baz']
allow_no_value, значение по умолчанию:
False
Известно, что некоторые конфигурационные файлы содержат параметры без значений, но в остальном соответствуют синтаксису, поддерживаемому
configparser
. Параметр allow_no_value конструктора может быть использован для указания того, что такие значения должны приниматься:>>> import configparser >>> sample_config = """ ... [mysqld] ... user = mysql ... pid-file = /var/run/mysqld/mysqld.pid ... skip-external-locking ... old_passwords = 1 ... skip-bdb ... # we don't need ACID today ... skip-innodb ... """ >>> config = configparser.ConfigParser(allow_no_value=True) >>> config.read_string(sample_config) >>> # Settings with values are treated as before: >>> config["mysqld"]["user"] 'mysql' >>> # Settings without values provide None: >>> config["mysqld"]["skip-bdb"] >>> # Settings which aren't specified still raise an error: >>> config["mysqld"]["does-not-exist"] Traceback (most recent call last): ... KeyError: 'does-not-exist'
разделители, значение по умолчанию:
('=', ':')
Разделители - это подстроки, которые отделяют ключи от значений внутри раздела. Первое появление разграничивающей подстроки в строке считается разделителем. Это означает, что значения (но не ключи) могут содержать разделители.
См. также аргумент space_around_delimiters к
ConfigParser.write()
.comment_prefixes, значение по умолчанию:
('#', ';')
inline_comment_prefixes, значение по умолчанию:
None
Префиксы комментариев - это строки, указывающие на начало допустимого комментария в файле конфигурации. Префиксы comment_prefixes используются только в пустых строках (по желанию с отступом), в то время как префиксы inline_comment_prefixes могут использоваться после каждого допустимого значения (например, названия секций, опций и пустых строк). По умолчанию строчные комментарии отключены, а
'#'
и';'
используются в качестве префиксов для комментариев на всю строку.Изменено в версии 3.2: В предыдущих версиях поведение
configparser
соответствовалоcomment_prefixes=('#',';')
иinline_comment_prefixes=(';',)
.Обратите внимание, что парсеры конфигурации не поддерживают экранирование префиксов комментариев, поэтому использование inline_comment_prefixes может помешать пользователям указывать значения опций с символами, используемыми в качестве префиксов комментариев. Если есть сомнения, избегайте установки inline_comment_prefixes. В любых обстоятельствах единственным способом хранения символов префикса комментария в начале строки в многострочных значениях является интерполяция префикса, например:
>>> from configparser import ConfigParser, ExtendedInterpolation >>> parser = ConfigParser(interpolation=ExtendedInterpolation()) >>> # the default BasicInterpolation could be used as well >>> parser.read_string(""" ... [DEFAULT] ... hash = # ... ... [hashes] ... shebang = ... ${hash}!/usr/bin/env python ... ${hash} -*- coding: utf-8 -*- ... ... extensions = ... enabled_extension ... another_extension ... #disabled_by_comment ... yet_another_extension ... ... interpolation not necessary = if # is not at line start ... even in multiline values = line #1 ... line #2 ... line #3 ... """) >>> print(parser['hashes']['shebang']) #!/usr/bin/env python # -*- coding: utf-8 -*- >>> print(parser['hashes']['extensions']) enabled_extension another_extension yet_another_extension >>> print(parser['hashes']['interpolation not necessary']) if # is not at line start >>> print(parser['hashes']['even in multiline values']) line #1 line #2 line #3
строго, значение по умолчанию:
True
Если установлено значение
True
, парсер не допустит дублирования секций или опций при чтении из одного источника (с использованиемread_file()
,read_string()
илиread_dict()
). Рекомендуется использовать строгий парсер в новых приложениях.Изменено в версии 3.2: В предыдущих версиях поведение
configparser
соответствовалоstrict=False
.пустые_строки_в_значениях, значение по умолчанию:
True
В парсерах конфигурации значения могут занимать несколько строк, если отступ от них больше, чем от ключа, который их содержит. По умолчанию парсеры также позволяют пустым строкам быть частью значений. В то же время для улучшения читабельности ключи могут иметь произвольный отступ. В результате, когда конфигурационные файлы становятся большими и сложными, пользователь может легко потерять представление о структуре файла. Например:
[Section] key = multiline value with a gotcha this = is still a part of the multiline value of 'key'
Это может быть особенно проблематично для пользователя, если он использует пропорциональный шрифт для редактирования файла. Поэтому, если вашему приложению не нужны значения с пустыми строками, стоит подумать о том, чтобы запретить их. Это заставит пустые строки каждый раз разделять клавиши. В приведенном выше примере это приведет к появлению двух клавиш,
key
иthis
.default_section, значение по умолчанию:
configparser.DEFAULTSECT
(то есть:"DEFAULT"
)Соглашение о том, что специальная секция может содержать значения по умолчанию для других секций или интерполяции, является мощной концепцией этой библиотеки, позволяющей пользователям создавать сложные декларативные конфигурации. Обычно эта секция называется
"DEFAULT"
, но ее можно настроить так, чтобы она указывала на любое другое допустимое имя секции. Некоторые типичные значения включают:"general"
или"common"
. Указанное имя используется для распознавания секций по умолчанию при чтении из любого источника и используется при записи конфигурации в файл. Его текущее значение может быть получено с помощью атрибутаparser_instance.default_section
и может быть изменено во время выполнения (например, для преобразования файлов из одного формата в другой).интерполяция, значение по умолчанию:
configparser.BasicInterpolation
Поведение интерполяции может быть настроено путем предоставления пользовательского обработчика через аргумент interpolation.
None
может быть использован для полного отключения интерполяции,ExtendedInterpolation()
предоставляет более продвинутый вариант, вдохновленныйzc.buildout
. Подробнее об этом в dedicated documentation section.RawConfigParser
имеет значение по умолчаниюNone
.конвертеры, значение по умолчанию: не установлено
Парсеры конфигурации предоставляют геттеры значений опций, которые выполняют преобразование типов. По умолчанию реализованы
getint()
,getfloat()
иgetboolean()
. Если нужны другие геттеры, пользователи могут определить их в подклассе или передать словарь, где каждый ключ - это имя конвертера, а каждое значение - вызываемый модуль, реализующий это преобразование. Например, передача{'decimal': decimal.Decimal}
добавитgetdecimal()
как объекту парсера, так и всем прокси-секциям. Другими словами, можно будет написать иparser_instance.getdecimal('section', 'key', fallback=0)
, иparser_instance['section'].getdecimal('key', 0)
.Если конвертеру нужно получить доступ к состоянию парсера, его можно реализовать в виде метода подкласса парсера config. Если имя этого метода начинается с
get
, он будет доступен для всех прокси секций в dict-совместимой форме (см. примерgetdecimal()
выше).
Более глубокая настройка может быть достигнута путем переопределения значений по умолчанию этих атрибутов парсера. Значения по умолчанию определяются в классах, поэтому они могут быть переопределены подклассами или назначением атрибутов.
- ConfigParser.BOOLEAN_STATES¶
По умолчанию при использовании
getboolean()
парсеры конфигурации учитывают следующие значенияTrue
:'1'
,'yes'
,'true'
,'on'
и следующие значенияFalse
:'0'
,'no'
,'false'
,'off'
. Вы можете переопределить это, указав пользовательский словарь строк и их булевых результатов. Например:>>> custom = configparser.ConfigParser() >>> custom['section1'] = {'funky': 'nope'} >>> custom['section1'].getboolean('funky') Traceback (most recent call last): ... ValueError: Not a boolean: nope >>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False} >>> custom['section1'].getboolean('funky') False
Другие типичные булевы пары включают
accept
/reject
илиenabled
/disabled
.
- ConfigParser.optionxform(option)
Этот метод преобразует имена опций при каждой операции чтения, получения или установки. По умолчанию имя преобразуется в нижний регистр. Это также означает, что при записи конфигурационного файла все ключи будут в нижнем регистре. Переопределите этот метод, если это не подходит. Например:
>>> config = """ ... [Section1] ... Key = Value ... ... [Section2] ... AnotherKey = Value ... """ >>> typical = configparser.ConfigParser() >>> typical.read_string(config) >>> list(typical['Section1'].keys()) ['key'] >>> list(typical['Section2'].keys()) ['anotherkey'] >>> custom = configparser.RawConfigParser() >>> custom.optionxform = lambda option: option >>> custom.read_string(config) >>> list(custom['Section1'].keys()) ['Key'] >>> list(custom['Section2'].keys()) ['AnotherKey']
Примечание
Функция optionxform преобразует имена опций к канонической форме. Это должна быть идемпотентная функция: если имя уже находится в канонической форме, оно должно быть возвращено без изменений.
- ConfigParser.SECTCRE¶
Скомпилированное регулярное выражение, используемое для разбора заголовков секций. По умолчанию соответствует
[section]
имени"section"
. Пробелы считаются частью имени секции, поэтому[ larch ]
будет прочитан как секция с именем" larch "
. Если это не подходит, переопределите этот атрибут. Например:>>> import re >>> config = """ ... [Section 1] ... option = value ... ... [ Section 2 ] ... another = val ... """ >>> typical = configparser.ConfigParser() >>> typical.read_string(config) >>> typical.sections() ['Section 1', ' Section 2 '] >>> custom = configparser.ConfigParser() >>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]") >>> custom.read_string(config) >>> custom.sections() ['Section 1', 'Section 2']
Примечание
Хотя объекты ConfigParser также используют атрибут
OPTCRE
для распознавания строк опций, переопределять его не рекомендуется, поскольку это может помешать опциям конструктора allow_no_value и delimiters.
Примеры устаревших API¶
В основном из-за соображений обратной совместимости, configparser
также предоставляет унаследованный API с явными методами get
/set
. Несмотря на то, что методы, описанные ниже, могут быть использованы по назначению, для новых проектов предпочтительнее использовать доступ по протоколу отображения. Унаследованный API порой более продвинутый, низкоуровневый и откровенно неинтуитивный.
Пример записи в файл конфигурации:
import configparser
config = configparser.RawConfigParser()
# Please note that using RawConfigParser's 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. Setting
# values using the mapping protocol or ConfigParser's set() 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', 'w') 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
:
import configparser
cfg = configparser.ConfigParser()
cfg.read('example.cfg')
# Set the optional *raw* argument of get() to True if you wish to disable
# interpolation in a single get operation.
print(cfg.get('Section1', 'foo', raw=False)) # -> "Python is fun!"
print(cfg.get('Section1', 'foo', raw=True)) # -> "%(bar)s is %(baz)s!"
# The optional *vars* argument is a dict with members that will take
# precedence in interpolation.
print(cfg.get('Section1', 'foo', vars={'bar': 'Documentation',
'baz': 'evil'}))
# The optional *fallback* argument can be used to provide a fallback value
print(cfg.get('Section1', 'foo'))
# -> "Python is fun!"
print(cfg.get('Section1', 'foo', fallback='Monty is not.'))
# -> "Python is fun!"
print(cfg.get('Section1', 'monster', fallback='No such things as monsters.'))
# -> "No such things as monsters."
# A bare print(cfg.get('Section1', 'monster')) would raise NoOptionError
# but we can also use:
print(cfg.get('Section1', 'monster', fallback=None))
# -> None
Значения по умолчанию доступны в обоих типах ConfigParsers. Они используются при интерполяции, если используемый параметр не определен в другом месте.
import configparser
# New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each
config = configparser.ConfigParser({'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!"
Объекты ConfigParser¶
- class configparser.ConfigParser(defaults=None, dict_type=dict, allow_no_value=False, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT, interpolation=BasicInterpolation(), converters={})¶
Основной парсер конфигурации. При указании defaults инициализируется в словарь внутренних значений по умолчанию. Если задан dict_type, то он будет использоваться для создания объектов словаря для списка секций, для опций внутри секции и для значений по умолчанию.
При указании delimiters используется как набор подстрок, разделяющих ключи и значения. Если задано comment_prefixes, оно будет использоваться как набор подстрок, которые префиксируют комментарии в иначе пустых строках. Комментарии могут быть с отступом. Если задано inline_comment_prefixes, оно будет использоваться как набор подстрок, которые префиксируют комментарии в непустых строках.
Когда strict равно
True
(по умолчанию), парсер не допустит дублирования секций или опций при чтении из одного источника (файла, строки или словаря), повышая значениеDuplicateSectionError
илиDuplicateOptionError
. Когда empty_lines_in_values имеет значениеFalse
(по умолчанию:True
), каждая пустая строка отмечает конец опции. В противном случае внутренние пустые строки многострочной опции сохраняются как часть значения. Если allow_no_value имеет значениеTrue
(по умолчанию:False
), принимаются опции без значений; для них сохраняется значениеNone
, и они сериализуются без концевого разделителя.При указании default_section задается имя специальной секции, содержащей значения по умолчанию для других секций и целей интерполяции (обычно она называется
"DEFAULT"
). Это значение может быть получено и изменено во время выполнения с помощью атрибута экземпляраdefault_section
. Это значение не будет повторно оценивать уже разобранный файл конфигурации, но будет использоваться при записи разобранных настроек в новый файл конфигурации.Поведение интерполяции может быть настроено путем предоставления пользовательского обработчика через аргумент interpolation.
None
может быть использован для полного отключения интерполяции,ExtendedInterpolation()
предоставляет более продвинутый вариант, вдохновленныйzc.buildout
. Подробнее об этом в dedicated documentation section.Все имена опций, используемые в интерполяции, будут передаваться через метод
optionxform()
, как и любая другая ссылка на имя опции. Например, при использовании стандартной реализацииoptionxform()
(которая преобразует имена опций в нижний регистр) значенияfoo %(bar)s
иfoo %(BAR)s
эквивалентны.Когда задается converters, это должен быть словарь, где каждый ключ представляет собой имя конвертера типов, а каждое значение - вызываемый объект, реализующий преобразование из строки в нужный тип данных. Каждый конвертер получает свой соответствующий метод
get*()
на объекте парсера и прокси секции.Изменено в версии 3.1: По умолчанию dict_type равен
collections.OrderedDict
.Изменено в версии 3.2: Были добавлены allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_section и interpolation.
Изменено в версии 3.5: Добавлен аргумент конвертеры.
Изменено в версии 3.7: Аргумент defaults считывается с
read_dict()
, что обеспечивает согласованное поведение парсера: нестроковые ключи и значения неявно преобразуются в строки.Изменено в версии 3.8: По умолчанию dict_type -
dict
, поскольку теперь сохраняется порядок вставки.Изменено в версии 3.13: Вызывает
MultilineContinuationError
, если allow_no_value равноTrue
, и ключ без значения продолжается с отступом от строки.- defaults()¶
Возвращает словарь, содержащий значения по умолчанию для всего экземпляра.
- sections()¶
Возвращает список доступных секций; секция по умолчанию в список не включается.
- add_section(section)¶
Добавляет в экземпляр секцию с именем section. Если секция с заданным именем уже существует, то вызывается сообщение
DuplicateSectionError
. Если передано имя секции по умолчанию, то будет выдано сообщениеValueError
. Имя секции должно быть строкой; в противном случае выдается сообщениеTypeError
.Изменено в версии 3.2: Названия секций, не являющиеся строками, повышают
TypeError
.
- has_section(section)¶
Указывает, присутствует ли названный раздел в конфигурации. Раздел по умолчанию не подтверждается.
- options(section)¶
Возвращает список опций, доступных в указанном разделе.
- has_option(section, option)¶
Если указанный раздел существует и содержит указанную опцию, возвращается
True
; в противном случае возвращаетсяFalse
. Если указанный раздел равенNone
или является пустой строкой, то предполагается DEFAULT.
- read(filenames, encoding=None)¶
Попытка прочитать и разобрать итерабельную таблицу имен файлов, возвращая список имен файлов, которые были успешно разобраны.
Если filenames является строкой, объектом
bytes
или path-like object, то оно рассматривается как одно имя файла. Если файл, указанный в filenames, не может быть открыт, он будет проигнорирован. Это сделано для того, чтобы вы могли указать итерацию потенциальных мест расположения конфигурационных файлов (например, текущий каталог, домашний каталог пользователя и некоторый общесистемный каталог), и все существующие конфигурационные файлы в этой итерации будут прочитаны.Если ни один из именованных файлов не существует, экземпляр
ConfigParser
будет содержать пустой набор данных. Приложение, требующее загрузки начальных значений из файла, должно загрузить необходимый файл или файлы с помощьюread_file()
перед вызовомread()
для любых дополнительных файлов:import configparser, os config = configparser.ConfigParser() config.read_file(open('defaults.cfg')) config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')], encoding='cp1250')
Изменено в версии 3.2: Добавлен параметр encoding. Ранее все файлы читались с использованием кодировки по умолчанию для
open()
.Изменено в версии 3.6.1: Параметр filenames принимает значение path-like object.
Изменено в версии 3.7: Параметр filenames принимает объект
bytes
.
- read_file(f, source=None)¶
Считывание и разбор конфигурационных данных из f, который должен быть итерируемым, содержащим строки Unicode (например, файлы, открытые в текстовом режиме).
Необязательный аргумент source задает имя считываемого файла. Если он не указан и f имеет атрибут
name
, он используется для source; по умолчанию используется'<???>'
.Added in version 3.2: Заменяет
readfp()
.
- read_string(string, source='<string>')¶
Разбор данных конфигурации из строки.
Необязательный аргумент source задает контекстно-зависимое имя передаваемой строки. Если оно не задано, используется
'<string>'
. Обычно это должен быть путь к файловой системе или URL.Added in version 3.2.
- read_dict(dictionary, source='<dict>')¶
Загрузка конфигурации из любого объекта, предоставляющего диктоподобный метод
items()
. Ключи - имена секций, значения - словари с ключами и значениями, которые должны присутствовать в секции. Если используемый тип словаря сохраняет порядок, то секции и их ключи будут добавлены по порядку. Значения автоматически преобразуются в строки.Необязательный аргумент source задает контекстно-зависимое имя передаваемого словаря. Если он не указан, используется
<dict>
.Этот метод можно использовать для копирования состояния между парсерами.
Added in version 3.2.
- get(section, option, *, raw=False, vars=None[, fallback])¶
Получает значение option для именованного раздела. Если указано vars, то это должен быть словарь. Значение option ищется в vars (если предоставлено), section и в DEFAULTSECT в этом порядке. Если ключ не найден и указано fallback, он используется в качестве запасного значения. В качестве значения fallback можно указать
None
.Все интерполяции
'%'
раскрываются в возвращаемых значениях, если только аргумент raw не равен true. Значения для ключей интерполяции ищутся так же, как и для опции.Изменено в версии 3.2: Аргументы raw, vars и fallback являются ключевыми словами только для того, чтобы защитить пользователей от попыток использовать третий аргумент в качестве fallback (особенно при использовании протокола отображения).
- getint(section, option, *, raw=False, vars=None[, fallback])¶
Удобный метод, который преобразует опцию в указанной секции в целое число. См.
get()
для объяснения raw, vars и fallback.
- getfloat(section, option, *, raw=False, vars=None[, fallback])¶
Удобный метод, который преобразует опцию в указанной секции в число с плавающей точкой. См.
get()
для объяснения raw, vars и fallback.
- getboolean(section, option, *, raw=False, vars=None[, fallback])¶
Удобный метод, который приводит опцию в указанной секции к булевому значению. Обратите внимание, что допустимыми значениями опции являются
'1'
,'yes'
,'true'
и'on'
, при которых метод возвращаетTrue
, и'0'
,'no'
,'false'
и'off'
, при которых он возвращаетFalse
. Эти строковые значения проверяются без учета регистра. Любое другое значение приведет к возвратуValueError
. См.get()
для объяснения raw, vars и fallback.
- items(raw=False, vars=None)¶
- items(section, raw=False, vars=None)
Если секция не задана, возвращается список пар имя_секции, секция_прокси, включая DEFAULTSECT.
В противном случае возвращается список пар имя, значение для опций в данной секции. Необязательные аргументы имеют то же значение, что и для метода
get()
.Изменено в версии 3.8: Элементы, присутствующие в vars, больше не появляются в результате. Предыдущее поведение смешивало фактические параметры парсера с переменными, предоставленными для интерполяции.
- set(section, option, value)¶
Если данный раздел существует, установите заданную опцию в указанное значение; в противном случае вызовите сообщение
NoSectionError
. option и value должны быть строками; если это не так, вызывается сообщениеTypeError
.
- write(fileobject, space_around_delimiters=True)¶
Запишите представление конфигурации в указанный file object, который должен быть открыт в текстовом режиме (принимает строки). Это представление может быть разобрано будущим вызовом
read()
. Если space_around_delimiters равен true, разделители между ключами и значениями будут окружены пробелами.
Примечание
Комментарии в исходном конфигурационном файле не сохраняются при записи конфигурации обратно. Что считать комментарием, зависит от заданных значений comment_prefix и inline_comment_prefix.
- remove_option(section, option)¶
Удаляет указанную опцию из указанного раздела. Если раздел не существует, возвращается
NoSectionError
. Если опция существовала и должна быть удалена, возвращаетсяTrue
; в противном случае возвращаетсяFalse
.
- remove_section(section)¶
Удаляет указанный раздел из конфигурации. Если раздел действительно существовал, возвращается
True
. В противном случае возвращаетсяFalse
.
- optionxform(option)¶
Преобразует имя опции option, найденное во входном файле или переданное клиентским кодом, в форму, которая должна использоваться во внутренних структурах. Реализация по умолчанию возвращает версию option в нижнем регистре; подклассы могут переопределить это или клиентский код может установить атрибут с этим именем для экземпляров, чтобы повлиять на это поведение.
Чтобы использовать этот метод, не обязательно создавать подкласс парсера, его можно задать и для экземпляра, в функции, которая принимает строковый аргумент и возвращает строку. Например, если установить значение
str
, имена опций будут чувствительны к регистру:cfgparser = ConfigParser() cfgparser.optionxform = str
Обратите внимание, что при чтении конфигурационных файлов пробельные символы вокруг имен опций удаляются перед вызовом
optionxform()
.
- configparser.UNNAMED_SECTION¶
Специальный объект, представляющий имя секции, используемый для ссылки на неименованную секцию (см. Безымянные участки).
Объекты RawConfigParser¶
- class configparser.RawConfigParser(defaults=None, dict_type=dict, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT[, interpolation])¶
Унаследованный вариант
ConfigParser
. По умолчанию в нем отключена интерполяция, и он позволяет использовать нестроковые имена секций, имена опций и значения через свои небезопасные методыadd_section
иset
, а также старую версиюdefaults=
для обработки аргументов ключевых слов.Изменено в версии 3.8: По умолчанию dict_type -
dict
, поскольку теперь сохраняется порядок вставки.Примечание
Вместо этого можно использовать
ConfigParser
, который проверяет типы значений для внутреннего хранения. Если вам не нужна интерполяция, вы можете использоватьConfigParser(interpolation=None)
.- add_section(section)¶
Добавляет в экземпляр секцию с именем section. Если секция с заданным именем уже существует, то вызывается сообщение
DuplicateSectionError
. Если передано имя секции по умолчанию, то возникает сообщениеValueError
.Тип раздела не проверяется, что позволяет пользователям создавать разделы без строковых имен. Такое поведение не поддерживается и может привести к внутренним ошибкам.
- set(section, option, value)¶
Если данная секция существует, установите указанный параметр в указанное значение; в противном случае вызовите
NoSectionError
. Хотя можно использоватьRawConfigParser
(илиConfigParser
с параметрами raw, установленными в true) для внутреннего хранения нестроковых значений, полная функциональность (включая интерполяцию и вывод в файлы) может быть достигнута только при использовании строковых значений.Этот метод позволяет пользователям внутренне присваивать ключам нестроковые значения. Такое поведение не поддерживается и приведет к ошибкам при попытке записи в файл или получения его в несырьевом режиме. Используйте API протокола отображения, который не позволяет выполнять такие присваивания.
Исключения¶
- exception configparser.Error¶
Базовый класс для всех остальных
configparser
исключений.
- exception configparser.NoSectionError¶
Исключение, возникающее, когда указанный раздел не найден.
- exception configparser.DuplicateSectionError¶
Исключение, возникающее при вызове
add_section()
с именем секции, которая уже присутствует, или в строгих парсерах, когда секция встречается более одного раза в одном входном файле, строке или словаре.Изменено в версии 3.2: В
__init__()
добавлены необязательные атрибуты и параметры source и lineno.
- exception configparser.DuplicateOptionError¶
Исключение, поднимаемое строгими парсерами, если одна опция встречается дважды при чтении из одного файла, строки или словаря. Это позволяет отлавливать опечатки и ошибки, связанные с чувствительностью к регистру, например, в словаре может быть два ключа, представляющих один и тот же ключ конфигурации, не чувствительный к регистру.
- exception configparser.NoOptionError¶
Исключение, возникающее, когда указанная опция не найдена в указанном разделе.
- exception configparser.InterpolationError¶
Базовый класс для исключений, возникающих при проблемах с интерполяцией строк.
- exception configparser.InterpolationDepthError¶
Исключение, возникающее, когда интерполяция строк не может быть завершена, поскольку количество итераций превышает
MAX_INTERPOLATION_DEPTH
. ПодклассInterpolationError
.
- exception configparser.InterpolationMissingOptionError¶
Исключение, возникающее, когда опция, на которую ссылается значение, не существует. Подкласс
InterpolationError
.
- exception configparser.InterpolationSyntaxError¶
Исключение, возникающее, когда исходный текст, в который производятся замены, не соответствует требуемому синтаксису. Подкласс
InterpolationError
.
- exception configparser.MissingSectionHeaderError¶
Исключение, возникающее при попытке разобрать файл, в котором нет заголовков секций.
- exception configparser.ParsingError¶
Исключение, возникающее при ошибках при попытке разобрать файл.
Изменено в версии 3.12: Атрибут
filename
и аргумент конструктора__init__()
были удалены. С версии 3.2 они доступны под именемsource
.
- exception configparser.MultilineContinuationError¶
Исключение, возникающее, когда ключ без соответствующего значения продолжается с отступом от строки.
Added in version 3.13.
Сноски