configparser
— Parser para archivos de configuración¶
Código fuente: Lib/configparser.py
Este módulo provee la clase ConfigParser
, la cual implementa un lenguaje básico de configuración que proporciona una estructura similar a la encontrada en los archivos INI de Microsoft Windows. Puedes utilizarla para escribir programas Python que los usuarios finales puedan personalizar con facilidad.
Nota
Esta biblioteca no interpreta o escribe los prefijos valor-tipo usados en la versión extendida de la sintaxis INI, utilizada en el registro de Windows.
Ver también
- Módulo
shlex
Soporta la creación de un mini-lenguaje parecido a shell de Unix, que puede utilizarse como formato alternativo para archivos de configuración de aplicaciones.
- Módulo
json
El módulo json implementa un subconjunto de la sintaxis de Javascript, que también puede utilizarse para este propósito.
Inicio Rápido¶
Tomemos un archivo de configuración muy básico, el cual luce así:
[DEFAULT]
ServerAliveInterval = 45
Compression = yes
CompressionLevel = 9
ForwardX11 = yes
[bitbucket.org]
User = hg
[topsecret.server.com]
Port = 50022
ForwardX11 = no
La estructura de los archivos INI es descrita en la siguiente sección. En esencia, el archivo consiste de secciones, cada una de las cuales contiene claves con valores. Las clases configparser
pueden leer y escribir dichos archivos. Comencemos creando el anterior archivo de configuración de forma programática.
>>> import configparser
>>> config = configparser.ConfigParser()
>>> config['DEFAULT'] = {'ServerAliveInterval': '45',
... 'Compression': 'yes',
... 'CompressionLevel': '9'}
>>> config['bitbucket.org'] = {}
>>> config['bitbucket.org']['User'] = 'hg'
>>> config['topsecret.server.com'] = {}
>>> topsecret = config['topsecret.server.com']
>>> 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)
...
Como puedes ver, podemos tratar al config parser como a un diccionario. Existen diferencias, descritas posteriormente, pero su comportamiento es muy parecido al que esperarías de un diccionario.
Ahora que hemos creado y guardado el archivo de configuración, vamos a releerlo y analizar los datos que contiene.
>>> config = configparser.ConfigParser()
>>> config.sections()
[]
>>> config.read('example.ini')
['example.ini']
>>> config.sections()
['bitbucket.org', 'topsecret.server.com']
>>> 'bitbucket.org' in config
True
>>> 'bytebong.com' in config
False
>>> config['bitbucket.org']['User']
'hg'
>>> config['DEFAULT']['Compression']
'yes'
>>> topsecret = config['topsecret.server.com']
>>> topsecret['ForwardX11']
'no'
>>> topsecret['Port']
'50022'
>>> for key in config['bitbucket.org']:
... print(key)
user
compressionlevel
serveraliveinterval
compression
forwardx11
>>> config['bitbucket.org']['ForwardX11']
'yes'
Como podemos apreciar, la API es muy clara. La única “porción de magia” está en la sección DEFAULT
, la cual proporciona los valores por defecto para todas las demás secciones 1. Observe también que las claves de las secciones son insensibles a mayúsculas y minúsculas, pero se almacenan en minúscula 1.
Tipos de Datos Soportados¶
Los config parsers no especulan respecto a los tipos de datos de los valores en los archivos de configuración, siempre los almacenan internamente como cadenas de caracteres. Esto significa que si necesitas otros tipos de datos, deberás hacer la conversión por ti mismo:
>>> int(topsecret['Port'])
50022
>>> float(topsecret['CompressionLevel'])
9.0
Dado que esta tarea es muy común, los config parsers proporcionan una amplia variedad de útiles métodos de lectura (getter) que manejan enteros, números de punto flotante y booleanos. Este último es el más interesante, porque puede no ser correcto pasar simplemente el valor a bool()
, ya que bool('False')
resultará en True
. Por esta razón los config parsers proporcionan también el método getboolean()
. Este método es insensible a mayúsculas y minúsculas, y reconoce como valores booleanos a los valores 'yes'
/'no'
, 'on'
/'off'
, 'true'
/'false'
and '1'
/'0'
1. Por ejemplo:
>>> topsecret.getboolean('ForwardX11')
False
>>> config['bitbucket.org'].getboolean('ForwardX11')
True
>>> config.getboolean('bitbucket.org', 'Compression')
True
Además de getboolean()
, los config parsers también proporcionan los métodos equivalentes getint()
y getfloat()
. Puedes registrar tus propios conversores, y personalizar los que se proporcionan. 1
Valores de contingencia¶
Similar a un diccionario, puedes utilizar el método get()
de una sección para especificar valores de contingencia (fallback values):
>>> topsecret.get('Port')
'50022'
>>> topsecret.get('CompressionLevel')
'9'
>>> topsecret.get('Cipher')
>>> topsecret.get('Cipher', '3des-cbc')
'3des-cbc'
Por favor, fíjate que los valores por defecto tienen prioridad sobre los valores de contingencia (fallback). Así, en nuestro ejemplo, la clave 'CompressionLevel'
sólo fue especificada en la sección 'DEFAULT'
. Si tratamos de obtener su valor de la sección 'topsecret.server.com'
, obtendremos siempre el valor por defecto, incluso si especificamos un valor de contingencia:
>>> topsecret.get('CompressionLevel', '3')
'9'
Otra cuestión que hay que tener en cuenta, es que el método a nivel analizador (parser) get()
proporciona una interfaz personalizada, más compleja, que se mantiene por compatibilidad con versiones anteriores. Cuando se utiliza este método, se puede proporcionar un valor de contingencia mediante el argumento de sólo-palabra clave (keyword-only) fallback
:
>>> config.get('bitbucket.org', 'monster',
... fallback='No such things as monsters')
'No such things as monsters'
El mismo argumento fallback
puede utilizarse con los métodos getint()
, getfloat()
y getboolean()
, por ejemplo:
>>> 'BatchMode' in topsecret
False
>>> topsecret.getboolean('BatchMode', fallback=True)
True
>>> config['DEFAULT']['BatchMode'] = 'no'
>>> topsecret.getboolean('BatchMode', fallback=True)
False
Estructura Soportada para el Archivo INI¶
Un archivo de configuración consiste de secciones, cada una iniciada por una cabecera [section]
, seguida por registros clave-valor, separados por una cadena de caracteres específica (=
ó :
por defecto 1). De forma predeterminada, los nombres de sección son sensibles a mayúsculas y minúsculas pero las claves no 1. Los espacios al inicio y final de las claves y valores son eliminados. Los valores pueden ser omitidos, en cuyo caso el delimitador del dato clave-valor puede ser omitido también. Los valores pueden ocupar varias líneas, siempre y cuando las líneas tengan una indentación mayor que la primera. Dependiendo del modo del parser, las líneas en blanco pueden tratarse como parte de un valor multilínea o ser ignoradas.
Los archivos de configuración pueden incluir comentarios, con caracteres específicos como prefijos (#
y ;
por defecto 1). Los comentarios pueden ocupar su propia línea, posiblemente indentada. 1
Por ejemplo:
[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?
Interpolación de valores¶
En el nivel superior de su funcionalidad central, ConfigParser
soporta la interpolación. Esto significa que los valores pueden ser preprocesados, antes de ser retornados por los llamados a get()
.
-
class
configparser.
BasicInterpolation
¶ Es la implementación por defecto que utiliza
ConfigParser
. Permite valores que contengan cadenas de formato, que hacen referencia a otros valores en la misma sección o a valores presentes en la sección especial default 1. Valores por defecto adicionales pueden ser proporcionados en la inicialización.Por ejemplo:
[Paths] home_dir: /Users my_dir: %(home_dir)s/lumberjack my_pictures: %(my_dir)s/Pictures [Escape] gain: 80%% # use a %% to escape the % sign (% is the only character that needs to be escaped)
En el ejemplo anterior,
ConfigParser
con la interpolación establecida aBasicInterpolation()
puede resolver%(home_dir)s
al valorhome_dir
(/Users
en este caso). En efecto,%(my_dir)s
podría resolverse como/Users/lumberjack
. Todas las interpolaciones son realizadas bajo demanda, de modo que las claves utilizadas en la cadena de referencias no requieren un orden específico en el archivo de configuración.Con
interpolation
establecida al valorNone
, el parser retornará simplemente%(my_dir)s/Pictures
como el valor demy_pictures
y%(home_dir)s/lumberjack
como el valor demy_dir
.
-
class
configparser.
ExtendedInterpolation
¶ Es un gestor alternativo para la interpolación, que implementa una sintaxis más avanzada; es utilizado, por ejemplo, en
zc.buildout
. La interpolación es extendida al utilizar${section:option}
, a fin de especificar un valor que proviene de una sección externa. La interpolación puede cubrir múltiples niveles. Por conveniencia, si la partesection:
es omitida, la interpolación utilizará la sección actual (y posiblemente los valores por defecto establecidos en la sección especial).Por ejemplo, la configuración indicada anteriormente, con interpolación básica, luciría de la siguiente manera utilizando interpolación extendida:
[Paths] home_dir: /Users my_dir: ${home_dir}/lumberjack my_pictures: ${my_dir}/Pictures [Escape] cost: $$80 # use a $$ to escape the $ sign ($ is the only character that needs to be escaped)
También pueden buscarse valores en otras secciones:
[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}
Acceso por Protocolo de Mapeo¶
Nuevo en la versión 3.2.
El acceso por protocolo de mapeo es un nombre genérico asignado a la funcionalidad que permite el uso de objetos personalizados como si fuesen diccionarios. En el caso de configparser
, la implementación de la interfaz de mapeo utiliza la notación parser['section']['option']
.
En particular, parser['section']
retorna un proxy para los datos de la sección en el parser. Esto significa que los valores no son copiados, sino que son tomados del parser original sobre la marcha.
Los objetos de configparser
se comportan de forma tan similar a un diccionario como se puede. La interfaz de mapeo es completa y se ciñe a la MutableMapping
ABC. Sin embargo, existen unas pequeñas diferencias que deben tomarse en cuenta:
Por defecto, todas las claves de las secciones se pueden acceder de una forma insensible a mayúsculas y minúsculas 1. Ej.
for option in parser["section"]
entrega solamente nombres de claves de opción que han pasado poroptionxform
. Esto significa, claves en minúscula por defecto. A la vez, para una sección que contiene la clave'a'
, ambas expresiones retornanTrue
:"a" in parser["section"] "A" in parser["section"]
Todas las secciones también incluyen valores
DEFAULTSECT
, lo que significa que.clear()
en una sección puede no significar que esta quede vacía de forma visible. Ello debido a que los valores por defecto no pueden ser borrados de la sección (ya que técnicamente no están allí). Si fueron redefinidas en la sección, su borrado ocasiona que los valores por defecto sean visibles de nuevo. Cualquier intento de borrar un valor por defecto ocasiona una excepciónKeyError
.DEFAULTSECT
no puede ser eliminado del parser:el intento de borrarlo lanza una excepción
ValueError
,parser.clear()
lo deja intacto,parser.popitem()
nunca lo retorna.
parser.get(section, option, **kwargs)
- el segundo argumento no es un valor de contingencia. Observe, sin embargo, que los métodosget()
a nivel de sección son compatibles tanto con el protocolo de mapeo como con la API clásica de configparser.parser.items()
es compatible con el protocolo de mapeo (retorna una lista de pares section_name, section_proxy que estén incluidos en DEFAULTSECT). Sin embargo, este método también puede ser invocado con los argumentos:parser.items(section, raw, vars)
. Esta última llamada retorna una lista de pares option, value para unasection
específica, con todas las interpolaciones expandidas (a menos que se especifiqueraw=True
).
El protocolo de mapeo se implementa en el nivel superior de la actual API heredada, de modo que esas subclases que sobre-escriben la interfaz original aún deberían hacer funcionar el mapeo como se esperaría.
Personalizando el Comportamiento del Parser¶
Existen casi tantas variantes del formato INI como aplicaciones que lo usen. configparser
llega muy lejos al proporcionar soporte al mayor conjunto sensible de estilos de INI disponibles. La funcionalidad predeterminada es impuesta principalmente por antecedentes históricos y es muy probable que quieras personalizar algunas de las funcionalidades.
La forma más común para modificar cómo funciona un config parser específico consiste en el uso de las opciones de __init__()
:
defaults, valor por defecto:
None
Esta opción acepta un diccionario de pares clave-valor, que debe ser colocado inicialmente en la sección
DEFAULT
. De este modo se obtiene una manera elegante de apoyar los archivos de configuración concisos, que no especifican valores que sean los mismos documentados por defecto.Consejo: si quieres especificar valores por defecto para una sección específica, usa
read_dict()
antes de leer el archivo real.dict_type, valor por defecto:
dict
Esta opción tiene un gran impacto en cómo funcionará el protocolo de mapeo, y cómo lucirán los archivos de configuración a escribir. Con el diccionario estándar, cada sección se almacena en el orden en que se añadieron al parser. Lo mismo ocurre con las opciones dentro de las secciones.
Un tipo alternativo de diccionario puede ser utilizado, por ejemplo, para ordenar las secciones y opciones en un modo a posteriori (write-back).
Por favor, tome en cuenta que: existen formas de agregar un par clave-valor en una sola operación. Cuando se utiliza un diccionario común en tales operaciones, el orden de las claves será el empleado en la creación. Por ejemplo:
>>> 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, valor por defecto:
False
Se sabe que algunos archivos de configuración incluyen elementos sin indicar un valor, aunque cumplan con la sintaxis soportada por
configparser
en todo lo demás. El parámetro allow_no_value le indica al constructor que tales valores deben ser aceptados:>>> 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'
delimiters, valor por defecto:
('=', ':')
Los delimiters son cadenas de caracteres que separan las claves de los valores dentro de una sección. La primera ocurrencia de una cadena de separación en una línea se considera como un separador. Esto significa que los valores pueden contener separadores, no así las claves.
Vea también el argumento space_around_delimiters de
ConfigParser.write()
.comment_prefixes, valor por defecto:
('#', ';')
inline_comment_prefixes, valor por defecto:
None
Los prefijos de comentario son cadenas de caracteres que indican el inicio de un comentario válido dentro de un archivo de configuración. Los comment_prefixes son utilizados solamente en lo que serían líneas en blanco (opcionalmente indentadas), mientras que inline_comment_prefixes pueden ser utilizados después de cada valor válido (ej. nombres de sección, opciones y también líneas en blanco). De forma predeterminada, los comentarios en la misma línea están deshabilitados, y tanto
'#'
como';'
se utilizan como prefijos para comentarios que ocupan toda la línea.Distinto en la versión 3.2: En versiones previas de
configparser
el comportamiento correspondía acomment_prefixes=('#',';')
einline_comment_prefixes=(';',)
.Por favor, observe que los config parsers no soportan el escapado de los prefijos de comentarios, de modo que la utilización de los inline_comment_prefixes puede impedir que los usuarios especifiquen valores de opciones que incluyan caracteres empleados como prefijos de comentarios. Ante la duda, evite especificar los inline_comment_prefixes. En cualquier circunstancia, la única forma de almacenar caracteres prefijos de comentario al inicio de una línea, en valores multilínea, es mediante la interpolación del prefijo, por ejemplo:
>>> 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
strict, valor por defecto:
True
Cuando tiene el valor
True
, el parser no permitirá duplicados en ninguna sección u opción, al efectuar la lectura desde una sola fuente (utilizandoread_file()
,read_string()
óread_dict()
). Se recomienda el uso de strict parsers en las aplicaciones nuevas.Distinto en la versión 3.2: En versiones previas de
configparser
el comportamiento correspondía astrict=False
.empty_lines_in_values, valor por defecto:
True
En los config parsers, los valores pueden abarcar varias líneas, siempre y cuando estén indentadas a un nivel superior al de la clave que las contiene. De forma predeterminada, los parsers permiten que las líneas en blanco formen parte de los valores. Igualmente, las claves pueden estar indentadas a sí mismas de forma arbitraria, a fin de mejorar la legibilidad. Por lo tanto, cuando los archivos de configuración se vuelven grandes y complejos, es fácil para el usuario el perder la pista de la estructura del archivo. Tomemos como ejemplo:
[Section] key = multiline value with a gotcha this = is still a part of the multiline value of 'key'
Esto puede ser especialmente problemático de observar por parte del usuario, en caso que se esté utilizando un tipo de fuente proporcional para editar el archivo. Y es por ello que, cuando tu aplicación no necesite valores con líneas en blanco, debes considerar invalidarlas. Esto ocasionaría que las líneas en blanco sirvan para dividir a las claves, siempre. En el ejemplo anterior, produciría dos claves:
key
ythis
.default_section, valor por defecto:
configparser.DEFAULTSECT
(es decir:"DEFAULT"
)El convenio de permitir una sección especial con valores por defecto para otras secciones, o con propósito de interpolación, es un concepto poderoso de esta librería, el cual permite a los usuarios crear configuraciones declarativas complejas. Esta sección se suele denominar
"DEFAULT"
, pero puede personalizarse para corresponder a cualquier otro nombre de sección. Algunas valores comunes son:"general"
ó"common"
. El nombre proporcionado es utilizado para reconocer las secciones por defecto al momento de realizar la lectura desde cualquier fuente, y es utilizado ante cualquier escritura al archivo de configuración. Su valor actual puede obtenerse utilizando el atributoparser_instance.default_section
y puede ser modificado en tiempo de ejecución (es decir, para convertir archivos de un formato a otro).interpolation, valor por defecto:
configparser.BasicInterpolation
El comportamiento de la interpolación puede ser personalizado al proporcionar un gestor personalizado mediante el argumento interpolation. El valor
None
se utiliza para desactivar la interpolación por completo, mientras queExtendedInterpolation()
proporciona una variante más avanzada, inspirada porzc.buildout
. Más información al respecto en la sección dedicada de la documentación. ElRawConfigParser
tiene un valor por defecto deNone
.converters, valor por defecto: no definido
Los config parsers proporcionan métodos para lectura (getters) de valores de opciones, que llevan a cabo la conversión de tipo. Están implementados los métodos
getint()
,getfloat()
, ygetboolean()
, de forma predeterminada. Si se desean otros métodos de lectura (getters), los usuarios pueden definirlos en una subclase o pasar un diccionario donde cada clave sea el nombre del conversor y cada valor es un invocable (callable) que implemente la conversión requerida. Por ejemplo, al pasar{'decimal': decimal.Decimal}
se agregaríagetdecimal()
tanto en el objeto parser como en todas las secciones proxies. En otras palabras, sería posible escribir tantoparser_instance.getdecimal('section', 'key', fallback=0)
comoparser_instance['section'].getdecimal('key', 0)
.Si el conversor necesita acceder al estado del parser, este puede ser implementado como un método en una subclase del config parser. Si el nombre de este método comienza con
get
, estará disponible en todas las secciones proxy, en su forma compatible con diccionarios (vea el ejemplo anterior degetdecimal()
).
Una personalización más avanzada puede conseguirse al sustituir los valores por defecto de estos atributos del parser. Los valores por defecto son definidos en las clases, de modo que pueden ser sustituidos por las subclases o mediante la asignación de atributos.
-
ConfigParser.
BOOLEAN_STATES
¶ Por defecto, al utilizar el método
getboolean()
, los config parsers consideran a los siguientes valores comoTrue
:'1'
,'yes'
,'true'
,'on'
y a los siguientes valores comoFalse
:'0'
,'no'
,'false'
,'off'
. Puedes cambiar ello proporcionando un diccionario personalizado de cadenas de caracteres, con sus correspondientes valores booleanos. Por ejemplo:>>> 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
Otros pares booleanos comunes incluyen
accept
/reject
óenabled
/disabled
.
-
ConfigParser.
optionxform
(option) Este método realiza la transformación de los nombres de opciones para cada operación de lectura, obtención o asignación. Por defecto convierte los nombres a minúsculas. Esto significa que, cuando un archivo de configuración es escrito, todas las claves son convertidas a minúsculas. Sobre-escribe este método si tal comportamiento no es adecuado. Por ejemplo:
>>> 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']
Nota
La función optionxform transforma los nombres de opción a una forma canónica. Esta debería ser una función idempotente: si el nombre ya está en su forma canónica, debería retornarse sin cambios.
-
ConfigParser.
SECTCRE
¶ Es una expresión regular compilada que se utiliza para parsear cabeceras de sección. Por defecto hace corresponder
[section]
con el nombre"section"
. Los espacios en blanco son considerados parte del nombre de sección, por lo que[ larch ]
será leído como la sección de nombre" larch "
. Sobre-escribe este atributo si tal comportamiento no es adecuado. Por ejemplo:>>> 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']
Nota
Mientras que los objectos ConfigParser también utilizan un atributo
OPTCRE
para reconocer las líneas de opciones, no se recomienda su sobre-escritura porque puede interferir con las opciones allow_no_value y delimiters del constructor.
Ejemplos de la API heredada¶
configparser
proporciona también una API heredada con métodos get
/set
explícitos; ello, principalmente debido a asuntos de compatibilidad con versiones anteriores. Aunque existen casos de uso válidos para los métodos descritos a continuación, se prefiere el acceso por protocolo de mapeo para los proyectos nuevos. La API heredada es al mismo tiempo más avanzada, de bajo nivel y sumamente contradictoria.
Un ejemplo de escritura a un archivo de configuración:
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)
Un ejemplo de lectura de un archivo de configuración, nuevamente:
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'))
Para obtener la interpolación, utilice 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
Los valores por defecto están disponibles en ambos tipos de ConfigParsers. Ellos son utilizados en la interpolación cuando una opción utilizada no está definida en otro lugar.
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!"
Objetos 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={})¶ La config parser principal. Si se proporciona defaults, su valor es inicializado en el diccionario de valores por defecto intrínsecos. Si se proporciona dict_type, se utiliza para crear el diccionario de objetos para la lista de secciones, las opciones dentro de una sección, y los valores por defecto.
Si se proporciona delimiters, se utiliza como un conjunto de cadenas de caracteres que dividen las claves de los valores. Si se proporciona comment_prefixes, se utiliza como un conjunto de cadenas de caracteres que preceden a los comentarios, en líneas que estarían, de otro modo, vacías. Los comentarios pueden estar indentados. Si se proporciona inline_comment_prefixes, se utiliza como un conjunto de cadenas de caracteres que preceden a los comentarios en líneas que no están vacías.
Cuando strict es
True
(por defecto), el parser no permitirá duplicados en ninguna sección u opción, al realizar la lectura de una sola fuente (archivo, cadena de caracteres o diccionario), generando una excepciónDuplicateSectionError
óDuplicateOptionError
. Cuando empty_lines_in_values esFalse
(valor por defecto:True
), cada línea en blanco indica el fin de una opción. De otro modo, las líneas en blanco de una opción multilínea son tratadas como parte del valor de esta. Cuando allow_no_value esTrue
(valor por defecto:False
), se aceptan opciones sin valores; el valor que toman esas opciones esNone
y serán serializadas sin el delimitador final.Cuando se proporciona default_section, se define el nombre de la sección especial que contiene valores por defecto para otras secciones y con propósito de interpolación (habitualmente denominada
"DEFAULT"
). Este valor puede obtenerse y modificarse en tiempo de ejecución utilizando el atributo de instanciadefault_section
.La interpolación puede personalizarse al proporcionar un gestor personalizado, mediante el argumento interpolation. El valor
None
se utiliza para desactivar la interpolación completamente,ExtendedInterpolation()
proporciona una variante avanzada, inspirada enzc.buildout
. Más al respecto puede encontrarse en la correspondiente sección de la documentación.Todos los nombres de opción que se utilizan en la interpolación pasarán por el método
optionxform()
, igual que cualquier otra referencia a un nombre de opción. Por lo tanto, si se utiliza la implementación por defecto deoptionxform()
(la cual convierte los nombres de opción a minúsculas), los valoresfoo %(bar)s
yfoo %(BAR)s
son equivalentes.Cuando se proporciona converters, este debe ser un diccionario, donde cada clave representa el nombre de un conversor, y cada valor un invocable que implementa la conversión de la cadena de caracteres al tipo de datos deseado. Cada conversor recibe su método
get*()
correspondiente en el objeto parser y los proxies de sección.Distinto en la versión 3.1: El valor por defecto de dict_type es
collections.OrderedDict
.Distinto en la versión 3.2: se agregaron los argumentos allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_section y interpolation.
Distinto en la versión 3.5: Se agregó el argumento converters.
Distinto en la versión 3.7: El argumento defaults es leído con
read_dict()
, proporcionando un comportamiento consistente en el parser: las claves y valores que no sean cadenas de caracteres son convertidas a tales.Distinto en la versión 3.8: El valor por defecto para dict_type es
dict
, dado que este ahora preserva el orden de inserción.-
defaults
()¶ Retorna un diccionario que contiene los valores por defecto para toda la instancia.
-
sections
()¶ Retorna una lista de las secciones disponibles; default section no se incluye en la lista.
-
add_section
(section)¶ Agrega una sección llamada section a la instancia. Si ya existe una sección con el nombre proporcionado, se genera la excepción
DuplicateSectionError
. Si se suministra el nombre default section, se genera la excepciónValueError
. El nombre de la sección debe ser una cadena de caracteres, de lo contrario, se genera la excepciónTypeError
.Distinto en la versión 3.2: Nombres de sección que no sean del tipo cadena de caracteres generan la excepción
TypeError
.
-
has_section
(section)¶ Indica si la sección de nombre section existe en la configuración. No se permite default section.
-
options
(section)¶ Retorna una lista de opciones disponibles en la sección especificada.
-
has_option
(section, option)¶ Si la sección indicada existe, y esta contiene las opción proporcionada, retorna
True
; de lo contrario, retornaFalse
. Si la sección especificada esNone
o una cadena de caracteres vacía, se asume DEFAULT.
-
read
(filenames, encoding=None)¶ Intenta leer y analizar sintácticamente (parse) un iterable de nombres de archivos, retornando una lista de nombres de archivos que han sido analizados (parsed) con éxito.
Si filenames es una cadena de caracteres, un objeto
bytes
o un path-like object, es tratado como un simple nombre de archivo. Si un archivo mencionado en filenames no puede ser abierto, será ignorado. Está diseñado de forma que puedas especificar un iterable de potenciales ubicaciones para archivos de configuración (por ejemplo, el directorio actual, el directorio home del usuario, o algún directorio del sistema), y todos los archivos de configuración existentes serán leídos.Si no existe ninguno de los archivos mencionados, la instancia de
ConfigParser
contendrá un conjunto de datos vacío. Una aplicación que requiera valores iniciales, que sean cargados desde un archivo, deberá cargar el(los) archivo(s) requerido(s) utilizandoread_file()
antes de llamar aread()
para cualquier otro archivo opcional:import configparser, os config = configparser.ConfigParser() config.read_file(open('defaults.cfg')) config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')], encoding='cp1250')
Nuevo en la versión 3.2: El parámetro encoding. Anteriormente, todos los archivos eran leídos utilizando la codificación por defecto de la la función
open()
.Nuevo en la versión 3.6.1: El parámetro filenames acepta un path-like object.
Nuevo en la versión 3.7: El parámetro filenames acepta un objeto
bytes
.
-
read_file
(f, source=None)¶ Leer y analizar (parse) los datos de configuración de f, el cual debe ser un iterable que retorne cadenas de caracteres Unicode (por ejemplo, archivos abiertos en modo texto).
El argumento opcional source especifica el nombre del archivo que se está leyendo. Si no se proporciona y f tiene un atributo
name
, este es utilizado como source; el valor por defecto es'<???>'
.Nuevo en la versión 3.2: Reemplaza a
readfp()
.
-
read_string
(string, source='<string>')¶ Analiza (parse) los datos de configuración desde una cadena de caracteres.
El argumento opcional source especifica un nombre para la cadena de caracteres proporcionada, relativo al contexto. Si no se proporciona, se utiliza
'<string>'
. Esto, por lo general, debería ser una ruta de archivo o una URL.Nuevo en la versión 3.2.
-
read_dict
(dictionary, source='<dict>')¶ Carga la configuración a partir de cualquier objeto que proporcione un método
items()
, similar a un diccionario. Las claves son nombres de secciones, los valores son diccionarios con claves y valores que deben estar presentes en la sección. Si el tipo de diccionario utilizado preserva el orden, las secciones y sus claves serán agregados en orden. Los valores son convertidos a cadenas de caracteres de forma automática.El argumento opcional source especifica un nombre para el diccionario proporcionado, relativo al contexto. Si no se proporciona, se utiliza
<dict>
.Este método puede utilizarse para copiar el estado entre parsers.
Nuevo en la versión 3.2.
-
get
(section, option, *, raw=False, vars=None[, fallback])¶ Obtiene el valor de una option para la sección indicada. Si se proporciona vars, tiene que ser un diccionario. El valor de option será buscado en vars (si se proporciona), en section y en DEFAULTSECT, en ese orden. Si la clave no se encuentra, y se ha proporcionado fallback, este es utilizado como un valor de contingencia. Se puede utilizar
None
como valor de contingencia (fallback).Todas las interpolaciones
'%'
son expandidas en el valor retornado, a menos que el argumento raw sea true. Los valores para la interpolación de las claves son buscados de la misma forma que para la opción.Distinto en la versión 3.2: Los argumentos raw, vars y fallback son argumentos nombrados solamente, a fin de proteger a los usuarios de los intentos de emplear el tercer argumento como el valor de contingencia de fallback (especialmente cuando se utiliza el protocolo de mapeo).
-
getint
(section, option, *, raw=False, vars=None[, fallback])¶ Un cómodo método para forzar a entero el valor de la opción de la sección indicada. Revise
get()
para una explicación acerca de raw, vars y fallback.
-
getfloat
(section, option, *, raw=False, vars=None[, fallback])¶ Un cómodo método para forzar a número de punto flotante el valor de la opción de la sección indicada. Revise
get()
para una explicación acerca de raw, vars y fallback.
-
getboolean
(section, option, *, raw=False, vars=None[, fallback])¶ Un cómodo método para forzar a booleano el valor de la opción de la sección indicada. Tome nota que los valores aceptados para la opción son
'1'
,'yes'
,'true'
, and'on'
, para que el método retorneTrue
, y'0'
,'no'
,'false'
, y'off'
para que el método retorneFalse
. Esos valores de cadenas de caracteres son revisados sin diferenciar mayúsculas de minúsculas. Cualquier otro valor ocasionará que se genere la excepciónValueError
. Reviseget()
para una explicación acerca de raw, vars y fallback.
-
items
(raw=False, vars=None)¶ -
items
(section, raw=False, vars=None) Cuando no se proporciona el argumento section, retorna una lista de pares section_name, section_proxy, incluyendo DEFAULTSECT.
De lo contrario, retorna una lista de pares name, value para las opciones de la sección especificada. Los argumentos opcionales tienen el mismo significado que en el método
get()
.Distinto en la versión 3.8: Los elementos que estén en vars no aparecen en el resultado. El comportamiento previo mezcla las opciones actuales del parser con las variables proporcionadas para la interpolación.
-
set
(section, option, value)¶ Si la sección indicada existe, asigna el valor especificado a la opción indicada; en caso contrario, genera la excepción
NoSectionError
. option y value deben ser cadenas de caracteres; de lo contrario, se genera la excepciónTypeError
.
-
write
(fileobject, space_around_delimiters=True)¶ Escribe una representación de la configuración al file object especificado, el cual debe ser abierto en modo texto (aceptando cadenas de caracteres). Esta representación puede ser analizada (parsed) por una posterior llamada a
read()
. Si space_around_delimiters es true, los delimitadores entre claves y valores son rodeados por espacios.
-
remove_option
(section, option)¶ Elimina la opción especificada de la sección indicada. Si la sección no existe, se genera una excepción
NoSectionError
. Si la opción existía antes de la eliminación, retornaTrue
; de lo contrario retornaFalse
.
-
remove_section
(section)¶ Elimina la sección especificada de la configuración. Si la sección existía, retorna
True
. De lo contrario, retornaFalse
.
-
optionxform
(option)¶ Transforma el nombre de opción option de la forma en que se encontraba en el archivo de entrada o como fue pasada por el código del cliente, a la forma en que debe ser utilizada en las estructuras internas. La implementación por defecto retorna una versión en minúsculas de option; las subclases pueden sobre-escribirla o el código del cliente puede asignar un atributo de su nombre en las instancias, para afectar su comportamiento.
No necesitas crear una subclase del parser para utilizar este método, ya que también puedes asignarlo en una instancia a una función, la cual reciba una cadena de caracteres como argumento y retorne otra. Por ejemplo, estableciéndola a
str
, se hará que los nombres de opciones sean sensibles a mayúsculas y minúsculas:cfgparser = ConfigParser() cfgparser.optionxform = str
Tome en cuenta que cuando se leen archivos de configuración, los espacios en blanco alrededor de los nombres de opción son eliminados antes de llamar a
optionxform()
.
-
readfp
(fp, filename=None)¶ Obsoleto desde la versión 3.2: Utilice
read_file()
en su lugar.Distinto en la versión 3.2: Ahora,
readfp()
itera sobre fp, en lugar de llamar afp.readline()
.Para el código existente, que llama a
readfp()
sin argumentos que soporten la iteración, el siguiente generador puede utilizarse como un envoltorio (wrapper) para el objeto semejante a archivo:def readline_generator(fp): line = fp.readline() while line: yield line line = fp.readline()
Utilice
parser.read_file(readline_generator(fp))
en lugar deparser.readfp(fp)
.
-
-
configparser.
MAX_INTERPOLATION_DEPTH
¶ La profundidad máxima de interpolación para
get()
cuando el parámetro raw es false. Esto es de importancia solamente cuando la interpolación por defecto es empleada.
Objetos 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])¶ Variante heredada de
ConfigParser
. Tiene la interpolación deshabilitada por defecto y permite nombres de sección que no sean cadenas de caracteres, nombres de opciones, y valores a través de sus métodos insegurosadd_section
yset
, así como el manejo heredado del argumento nombradodefaults=
.Distinto en la versión 3.8: El valor por defecto para dict_type es
dict
, dado que este ahora preserva el orden de inserción.Nota
Considere el uso de
ConfigParser
en su lugar, el cual verifica los tipos de datos de los valores que se almacenarán internamente. Si no quieres la interpolación, puedes utilizarConfigParser(interpolation=None)
.-
add_section
(section)¶ Agrega a la instancia una sección de nombre section. Si ya existe una sección con el nombre proporcionado, se genera la excepción
DuplicateSectionError
. Si se suministra el nombre default section, se genera la excepciónValueError
.No se comprueba el tipo de datos de section, con lo cual se permite que los usuarios creen secciones con nombres que no sean cadenas de caracteres. Este comportamiento no está soportado y puede ocasionar errores internos.
-
set
(section, option, value)¶ Si existe la sección indicada, asigna el valor especificado a la sección indicada; de lo contrario, genera la excepción
NoSectionError
. Aunque es posible utilizarRawConfigParser
(óConfigParser
con parámetros raw con valor true) como almacenamiento interno para valores que no sean cadenas de caracteres, el funcionamiento completo (incluyendo la interpolación y escritura en archivos) sólo puede lograrse utilizando valores del tipo cadena de caracteres.Este método permite que los usuarios asignen valores que no sean cadenas de caracteres a las claves, internamente. Este comportamiento no está soportado y causará errores cuando se intente escribir en un archivo o cuando se intente obtenerlo en un modo no raw. Utilice la API del protocolo de mapeo, la cual no permite ese tipo de asignaciones.
-
Excepciones¶
-
exception
configparser.
Error
¶ Clase base para todas las otras excepciones
configparser
.
-
exception
configparser.
NoSectionError
¶ Excepción generada cuando no se encuentra una sección especificada.
-
exception
configparser.
DuplicateSectionError
¶ Excepción generada si el método
add_section()
es llamado proporcionando el nombre de una sección que ya existe, o, en caso de parsers estrictos, si una sección se encuentra más de una vez en un solo archivo de entrada, cadena de caracteres o diccionario.Nuevo en la versión 3.2: Al método
__init__()
se agregaron los atributos y argumentos opcionalessource
ylineno
.
-
exception
configparser.
DuplicateOptionError
¶ Excepción generada por parsers estrictos si una sola opción aparece dos veces durante la lectura de un solo archivo, cadena de caracteres o diccionario. Captura errores de escritura o relacionados con el uso de mayúsculas y minúsculas, ej. un diccionario podría tener dos claves que representan la misma clave de configuración bajo un esquema insensible a mayúsculas y minúsculas.
-
exception
configparser.
NoOptionError
¶ Excepción generada cuando una opción especificada no se encuentra en una sección indicada.
-
exception
configparser.
InterpolationError
¶ Clase base para excepciones generadas por problemas que ocurren al realizar la interpolación de cadenas de caracteres.
-
exception
configparser.
InterpolationDepthError
¶ Excepción generada cuando la interpolación de cadenas de caracteres no puede completarse, debido a que el número de iteraciones excede a
MAX_INTERPOLATION_DEPTH
. Subclase deInterpolationError
.
-
exception
configparser.
InterpolationMissingOptionError
¶ Excepción generada cuando no existe una opción referida por un valor. Subclase de
InterpolationError
.
-
exception
configparser.
InterpolationSyntaxError
¶ Excepción generada cuando el texto fuente, donde se realizan las sustituciones, no se ajusta a la sintaxis requerida. Subclase de
InterpolationError
.
-
exception
configparser.
MissingSectionHeaderError
¶ Excepción generada cuando se intenta analizar (parse) un archivo que no tiene encabezados de sección.
-
exception
configparser.
ParsingError
¶ Excepción generada cuando ocurren errores intentando analizar (parse) un archivo.
Distinto en la versión 3.2: El atributo
filename
y el argumento__init__()
fueron renombrados asource
por consistencia.
Notas al pie