This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

# `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

A configuration file consists of sections, each led by a `[section]` header, followed by key/value entries separated by a specific string (`=` or `:` by default 1). By default, section names are case sensitive but keys are not 1. Leading and trailing whitespace is removed from keys and values. Values can be omitted if the parser is configured to allow it 1, in which case the key/value delimiter may also be left out. Values can also span multiple lines, as long as they are indented deeper than the first line of the value. Depending on the parser’s mode, blank lines may be treated as parts of multiline values or ignored.

By default, a valid section name can be any string that does not contain “\n” or “]”. To change this, see `ConfigParser.SECTCRE`.

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]
      # use a %% to escape the % sign (% is the only character that needs to be escaped):
      gain: 80%%

  En el ejemplo anterior, `ConfigParser` con la interpolación establecida a `BasicInterpolation()` puede resolver `%(home_dir)s` al valor `home_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 valor `None`, el parser retornará simplemente `%(my_dir)s/Pictures` como el valor de `my_pictures` y `%(home_dir)s/lumberjack` como el valor de `my_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 parte `section:` 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]
      # use a $$ to escape the $ sign ($ is the only character that needs to be escaped):
      cost: $$80

  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 por `optionxform`. Esto significa, claves en minúscula por defecto. A la vez, para una sección que contiene la clave `'a'`, ambas expresiones retornan `True`:

      "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ón `KeyError`.

- `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étodos `get()` 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 una `section` específica, con todas las interpolaciones expandidas (a menos que se especifique `raw=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 a `comment_prefixes=('#',';')` e `inline_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 (utilizando `read_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 a `strict=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` y `this`.

- 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 atributo `parser_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 que `ExtendedInterpolation()` proporciona una variante más avanzada, inspirada por `zc.buildout`. Más información al respecto en la sección dedicada de la documentación. El `RawConfigParser` tiene un valor por defecto de `None`.

- 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()`, y `getboolean()`, 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ía `getdecimal()` tanto en el objeto parser como en todas las secciones proxies. En otras palabras, sería posible escribir tanto `parser_instance.getdecimal('section', 'key', fallback=0)` como `parser_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 de `getdecimal()`).

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 como `True`: `'1'`, `'yes'`, `'true'`, `'on'` y a los siguientes valores como `False`: `'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ón `DuplicateSectionError` ó `DuplicateOptionError`. Cuando empty_lines_in_values es `False` (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 es `True` (valor por defecto: `False`), se aceptan opciones sin valores; el valor que toman esas opciones es `None` 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 instancia `default_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 en `zc.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 de `optionxform()` (la cual convierte los nombres de opción a minúsculas), los valores `foo %(bar)s` y `foo %(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ón `ValueError`. El nombre de la sección debe ser una cadena de caracteres, de lo contrario, se genera la excepción `TypeError`.

    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, retorna `False`. Si la sección especificada es `None` 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) utilizando `read_file()` antes de llamar a `read()` 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 retorne `True`, y `'0'`, `'no'`, `'false'`, y `'off'` para que el método retorne `False`. Esos valores de cadenas de caracteres son revisados sin diferenciar mayúsculas de minúsculas. Cualquier otro valor ocasionará que se genere la excepción `ValueError`. Revise `get()` 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ón `TypeError`.

  `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.

  Nota

  Comments in the original configuration file are not preserved when writing the configuration back. What is considered a comment, depends on the given values for comment_prefix and inline_comment_prefix.

  `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, retorna `True`; de lo contrario retorna `False`.

  `remove_section`(section)

    Elimina la sección especificada de la configuración. Si la sección existía, retorna `True`. De lo contrario, retorna `False`.

  `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 a `fp.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 de `parser.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 inseguros `add_section` y `set`, así como el manejo heredado del argumento nombrado `defaults=`.

  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 utilizar `ConfigParser(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ón `ValueError`.

    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 utilizar `RawConfigParser` (ó `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 opcionales `source` y `lineno`.

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 de `InterpolationError`.

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 a `source` por consistencia.

Notas al pie

1(1,2,3,4,5,6,7,8,9,10,11)

  Los config parsers permiten una gran personalización. Si estás interesado en modificar el comportamiento descrito por la referencia de la nota al pie, consulta la sección Customizing Parser Behaviour.