Esta documentação é de uma versão antiga do Python que não é mais atualizada. Você deveria atualizar e ler a Documentação do Python para versão estável atual.

# `configparser` — Configuration file parser

Código-fonte: Lib/configparser.py

Este módulo fornece a classe `ConfigParser` que implementa uma linguagem de configuração básica que fornece uma estrutura semelhante à encontrada nos arquivos INI do Microsoft Windows. Você pode usar isso para escrever programas Python que podem ser facilmente personalizados pelos usuários finais.

Nota

Esta biblioteca não interpreta nem escreve os prefixos de tipo de valor usados na versão estendida do Registro do Windows da sintaxe INI.

Ver também

Módulo `shlex`

  Support for creating Unix shell-like mini-languages which can be used as an alternate format for application configuration files.

Módulo `json`

  The json module implements a subset of JavaScript syntax which can also be used for this purpose.

## Início rápido

Vamos pegar um arquivo de configuração bem básico parecido com este:

    [DEFAULT]
    ServerAliveInterval = 45
    Compression = yes
    CompressionLevel = 9
    ForwardX11 = yes

    [bitbucket.org]
    User = hg

    [topsecret.server.com]
    Port = 50022
    ForwardX11 = no

A estrutura dos arquivos INI é descrita na seção seguinte. Essencialmente, o arquivo consiste em seções, cada uma contendo chaves com valores. As classes `configparser` podem ler e escrever tais arquivos. Vamos começar criando o arquivo de configuração acima programaticamente.

    >>> 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 você pode ver, podemos tratar um analisador sintático de configuração como um dicionário. Existem diferenças, descritas posteriormente, mas o comportamento é muito próximo do que você esperaria de um dicionário.

Agora que criamos e salvamos um arquivo de configuração, vamos lê-lo e explorar os dados que ele contém.

    >>> 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 ver acima, a API é bastante simples. A única mágica envolve a seção `DEFAULT` que fornece valores padrão para todas as outras seções 1. Observe também que as chaves nas seções não diferenciam maiúsculas de minúsculas e são armazenadas em letras minúsculas 1.

## Tipos de dados suportados

Os analisadores sintáticos de configuração não adivinham os tipos de dados dos valores nos arquivos de configuração, sempre os armazenando internamente como strings. Isso significa que se você precisar de outros tipos de dados, deverá converter por conta própria:

    >>> int(topsecret['Port'])
    50022
    >>> float(topsecret['CompressionLevel'])
    9.0

Como essa tarefa é tão comum, os analisadores sintáticos de configuração fornecem uma variedade de métodos getter úteis para manipular com números inteiros, pontos flutuantes e booleanos. O último é o mais interessante porque simplesmente passar o valor para `bool()` não adiantaria nada já que `bool('False')` ainda é `True`. É por isso que os analisadores sintáticos de configuração também fornecem `getboolean()`. Este método não diferencia maiúsculas de minúsculas e reconhece valores booleanos de `'yes'`/`'no'`, `'on'`/`'off'`, `'true'` /`'false'` e `'1'`/`'0'` 1. Por exemplo:

    >>> topsecret.getboolean('ForwardX11')
    False
    >>> config['bitbucket.org'].getboolean('ForwardX11')
    True
    >>> config.getboolean('bitbucket.org', 'Compression')
    True

Além de `getboolean()`, os analisadores sintáticos de configuração também fornecem métodos `getint()` e `getfloat()` equivalentes. Você pode registrar seus próprios conversores e personalizar os fornecidos. 1

## Valores reservas

As with a dictionary, you can use a section’s `get()` method to provide fallback values:

    >>> topsecret.get('Port')
    '50022'
    >>> topsecret.get('CompressionLevel')
    '9'
    >>> topsecret.get('Cipher')
    >>> topsecret.get('Cipher', '3des-cbc')
    '3des-cbc'

Please note that default values have precedence over fallback values. For instance, in our example the `'CompressionLevel'` key was specified only in the `'DEFAULT'` section. If we try to get it from the section `'topsecret.server.com'`, we will always get the default, even if we specify a fallback:

    >>> topsecret.get('CompressionLevel', '3')
    '9'

One more thing to be aware of is that the parser-level `get()` method provides a custom, more complex interface, maintained for backwards compatibility. When using this method, a fallback value can be provided via the `fallback` keyword-only argument:

    >>> config.get('bitbucket.org', 'monster',
    ...            fallback='No such things as monsters')
    'No such things as monsters'

O mesmo argumento `fallback` pode ser usado com os métodos `getint()`, `getfloat()` e `getboolean()`, por exemplo:

    >>> 'BatchMode' in topsecret
    False
    >>> topsecret.getboolean('BatchMode', fallback=True)
    True
    >>> config['DEFAULT']['BatchMode'] = 'no'
    >>> topsecret.getboolean('BatchMode', fallback=True)
    False

## Estrutura dos arquivos INI

Um arquivo de configuração consiste em seções, cada uma liderada por um cabeçalho `[section]`, seguido por entradas de chave/valor separadas por uma string específica (`=` ou `:` por padrão 1) . Por padrão, os nomes das seções diferenciam maiúsculas de minúsculas, mas as chaves não 1. Os espaços em branco à esquerda e à direita são removidos das chaves e dos valores. Os valores podem ser omitidos se o analisador sintático estiver configurado para permitir 1, caso em que o delimitador chave/valor também pode ser omitido. Os valores também podem abranger várias linhas, desde que sejam indentados de forma mais profunda que a primeira linha do valor. Dependendo do modo do analisador sintático, as linhas em branco podem ser tratadas como partes de valores multilinhas ou ignoradas.

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

Os arquivos de configuração podem incluir comentários, prefixados por caracteres específicos (`#` e `;` por padrão 1). Os comentários podem aparecer sozinhos em uma linha vazia, possivelmente indentados. 1

Por exemplo:

    [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?

## Interpolação de valores

Além da funcionalidade principal, `ConfigParser` oferece suporte a interpolação. Isso significa que os valores podem ser pré-processados antes de retorná-los das chamadas `get()`.

class `configparser.``BasicInterpolation`

  A implementação padrão usada por `ConfigParser`. Ele permite que os valores contenham strings de formato que se referem a outros valores na mesma seção ou valores na seção padrão especial 1. Valores padrão adicionais podem ser fornecidos na inicialização.

  Por exemplo:

      [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%%

  No exemplo acima, `ConfigParser` com interpolation definido como `BasicInterpolation()` resolveria `%(home_dir)s` para o valor de `home_dir` (`/Users` neste caso). `%(my_dir)s` na verdade resolveria para `/Users/lumberjack`. Todas as interpolações são feitas sob demanda, portanto as chaves usadas na cadeia de referências não precisam ser especificadas em nenhuma ordem específica no arquivo de configuração.

  Com `interpolation` definido como `None`, o analisador sintático simplesmente retornaria `%(my_dir)s/Pictures` como o valor de `my_pictures` e `%(home_dir)s/lumberjack` como o valor de `my_dir`.

class `configparser.``ExtendedInterpolation`

  Um manipulador alternativo para interpolação que implementa uma sintaxe mais avançada, usada, por exemplo, em `zc.buildout`. A interpolação estendida usa `${section:option}` para denotar um valor de uma seção estrangeira. A interpolação pode abranger vários níveis. Por conveniência, se a parte `section:` for omitida, a interpolação será padronizada para a seção atual (e possivelmente para os valores padrão da seção especial).

  Por exemplo, a configuração especificada acima com interpolação básica ficaria assim com interpolação estendida:

      [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

  Valores de outras seções também podem ser obtidos:

      [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}

## Acesso através do protocolo de mapeamento

Novo na versão 3.2.

Acesso através do protocolo de mapeamento é um nome genérico para funcionalidade que permite usar objetos personalizados como se fossem dicionários. No caso de `configparser`, a implementação da interface de mapeamento está usando a notação `parser['section']['option']`.

`parser['section']` em particular retorna um intermediário para os dados da seção no analisador sintático. Isso significa que os valores não são copiados, mas obtidos do analisador sintático original sob demanda. O que é ainda mais importante é que quando os valores são alterados em um intermediário de seção, eles são, na verdade, modificados no analisador sintático original.

Os objetos `configparser` se comportam o mais próximo possível dos dicionários reais. A interface de mapeamento é completa e segue a ABC `MutableMapping`. No entanto, existem algumas diferenças que devem ser levadas em consideração:

- Por padrão, todas as chaves nas seções são acessíveis sem distinção entre maiúsculas e minúsculas 1. Por exemplo. `for option in parser["section"]` produz apenas nomes de chaves de opção `optionxform`ada. Isso significa chaves em letras minúsculas por padrão. Ao mesmo tempo, para uma seção que contém a chave `'a'`, ambas as expressões retornam `True`:

      "a" in parser["section"]
      "A" in parser["section"]

- Todas as seções também incluem valores `DEFAULTSECT`, o que significa que `.clear()` em uma seção não pode deixá-la visivelmente vazia. Isso ocorre porque os valores padrão não podem ser excluídos da seção (porque tecnicamente eles não estão lá). Se eles forem substituídos na seção, a exclusão fará com que o valor padrão fique visível novamente. Tentar excluir um valor padrão causa um `KeyError`.

- `DEFAULTSECT` não pode ser removido do analisador sintático:

  - tentar excluí-lo levanta `ValueError`,

  - `parser.clear()` deixa-o intacto,

  - `parser.popitem()` nunca o retorna.

- `parser.get(section, option, **kwargs)` - o segundo argumento não é um valor substituto. Observe, entretanto, que os métodos `get()` em nível de seção são compatíveis tanto com o protocolo de mapeamento quanto com a API clássica do configparser.

- `parser.items()` é compatível com o protocolo de mapeamento (retorna uma lista de pares section_name, section_proxy incluindo o DEFAULTSECT). Entretanto, este método também pode ser invocado com argumentos: `parser.items(section, raw, vars)`. A última chamada retorna uma lista de pares option, value para uma `section` especificada, com todas as interpolações expandidas (a menos que `raw=True` seja fornecido).

O protocolo de mapeamento é implementado sobre a API legada existente para que as subclasses que substituem a interface original ainda tenham mapeamentos funcionando conforme o esperado.

## Personalizando o comportamento do analisador sintático

Existem quase tantas variantes de formato INI quanto aplicações que o utilizam. `configparser` percorre um longo caminho para fornecer suporte para o maior conjunto sensato de estilos INI disponíveis. A funcionalidade padrão é determinada principalmente pelo histórico e é muito provável que você queira personalizar alguns dos recursos.

The most common way to change the way a specific config parser works is to use the `__init__()` options:

- defaults, valor padrão: `None`

  Esta opção aceita um dicionário de pares chave-valor que será inicialmente colocado na seção `DEFAULT`. Isso é uma maneira elegante de oferecer suporte a arquivos de configuração concisos que não especificam valores iguais ao padrão documentado.

  Hint: if you want to specify default values for a specific section, use `read_dict()` before you read the actual file.

- dict_type, valor padrão: `dict`

  Esta opção tem um grande impacto no comportamento do protocolo de mapeamento e na aparência dos arquivos de configuração gravados. Com o dicionário padrão, cada seção é armazenada na ordem em que foram adicionadas ao analisador sintático. O mesmo vale para opções dentro das seções.

  Um tipo de dicionário alternativo pode ser usado, por exemplo, para ordenar as seções e opções ao fazer write-back.

  Observação: existem maneiras de adicionar um conjunto de pares de valores-chave em uma única operação. Quando você usa um dicionário regular nessas operações, a classificação das chaves será ordenada. Por exemplo:

      >>> 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 padrão: `False`

  Alguns arquivos de configuração são conhecidos por incluir configurações sem valores, mas que de outra forma estão em conformidade com a sintaxe suportada por `configparser`. O parâmetro allow_no_value para o construtor pode ser usado para indicar que tais valores devem ser aceitos:

      >>> 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 padrão: `('=', ':')`

  Delimitadores são substrings que delimitam chaves de valores dentro de uma seção. A primeira ocorrência de uma substring delimitadora em uma linha é considerada um delimitador. Isso significa que os valores (mas não as chaves) podem conter os delimitadores.

  Veja também o argumento space_around_delimiters para `ConfigParser.write()`.

- comment_prefixes, valor padrão: `('#', ';')`

- inline_comment_prefixes, valor padrão: `None`

  Prefixos de comentários são strings que indicam o início de um comentário válido em um arquivo de configuração. comment_prefixes são usados apenas em linhas vazias (opcionalmente indentadas), enquanto inline_comment_prefixes pode ser usado após cada valor válido (por exemplo, nomes de seções, opções e linhas vazias também). Por padrão, os comentários embutidos estão desabilitados e `'#'` e `';'` são usados como prefixos para comentários de linha inteira.

  Alterado na versão 3.2: Nas versões anteriores do `configparser`, o comportamento correspondia a `comment_prefixes=('#',';')` e `inline_comment_prefixes=(';',)`.

  Observe que os analisadores sintáticos de configuração não oferecem suporte a escape de prefixos de comentários, portanto, usar inline_comment_prefixes pode impedir que os usuários especifiquem valores de opção com caracteres usados como prefixos de comentários. Em caso de dúvida, evite definir inline_comment_prefixes. Em qualquer circunstância, a única maneira de armazenar caracteres de prefixo de comentário no início de uma linha em valores multilinha é interpolar o prefixo, por exemplo:

      >>> 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 padrão: `True`

  When set to `True`, the parser will not allow for any section or option duplicates while reading from a single source (using `read_file()`, `read_string()` or `read_dict()`). It is recommended to use strict parsers in new applications.

  Alterado na versão 3.2: Nas versões anteriores do `configparser`, o comportamento correspondia a `strict=False`.

- empty_lines_in_values, valor padrão: `True`

  Em analisadores sintáticos de configuração, os valores podem abranger várias linhas, desde que sejam mais indentados do que a chave que os contém. Por padrão, os analisadores sintáticos também permitem que linhas vazias façam parte de valores. Ao mesmo tempo, as chaves podem ser indentados arbitrariamente para melhorar a legibilidade. Consequentemente, quando os arquivos de configuração ficam grandes e complexos, é fácil para o usuário perder o controle da estrutura do arquivo. Tomemos por exemplo:

      [Section]
      key = multiline
        value with a gotcha

       this = is still a part of the multiline value of 'key'

  Isso pode ser especialmente problemático para o usuário ver se está usando uma fonte proporcional para editar o arquivo. É por isso que quando sua aplicação não precisa de valores com linhas vazias, você deve considerar proibi-los. Isso fará com que as linhas vazias dividam as chaves sempre. No exemplo acima, seriam produzidas duas chaves, `key` e `this`.

- default_section, valor padrão: `configparser.DEFAULTSECT` (isto é: `"DEFAULT"`)

  A convenção de permitir uma seção especial de valores padrão para outras seções ou fins de interpolação é um conceito poderoso desta biblioteca, permitindo aos usuários criar configurações declarativas complexas. Esta seção normalmente é chamada de `"DEFAULT"`, mas pode ser personalizada para apontar para qualquer outro nome de seção válido. Alguns valores típicos incluem: `"general"` ou `"common"`. O nome fornecido é usado para reconhecer seções padrão ao ler de qualquer fonte e é usado ao gravar a configuração em um arquivo. Seu valor atual pode ser recuperado usando o atributo `parser_instance.default_section` e pode ser modificado em tempo de execução (ou seja, para converter arquivos de um formato para outro).

- interpolation, valor padrão: `configparser.BasicInterpolation`

  O comportamento de interpolação pode ser personalizado fornecendo um manipulador personalizado por meio do argumento interpolation. `None` pode ser usado para desligar completamente a interpolação, `ExtendedInterpolation()` fornece uma variante mais avançada inspirada em `zc.buildout`. Mais sobre o assunto na seção de documentação dedicada. `RawConfigParser` tem um valor padrão de `None`.

- converters, valor padrão: não definido

  Config parsers provide option value getters that perform type conversion. By default `getint()`, `getfloat()`, and `getboolean()` are implemented. Should other getters be desirable, users may define them in a subclass or pass a dictionary where each key is a name of the converter and each value is a callable implementing said conversion. For instance, passing `{'decimal': decimal.Decimal}` would add `getdecimal()` on both the parser object and all section proxies. In other words, it will be possible to write both `parser_instance.getdecimal('section', 'key', fallback=0)` and `parser_instance['section'].getdecimal('key', 0)`.

  Se o conversor precisar acessar o estado do analisador sintático, ele poderá ser implementado como um método em uma subclasse do analisador sintático de configuração. Se o nome deste método começar com `get`, ele estará disponível em todos os intermediários de seção, na forma compatível com dict (veja o exemplo `getdecimal()` acima).

Uma personalização mais avançada pode ser obtida substituindo os valores padrão desses atributos do analisador sintático. Os padrões são definidos nas classes, portanto podem ser substituídos por subclasses ou por atribuição de atributos.

`ConfigParser.``BOOLEAN_STATES`

  Por padrão, ao usar `getboolean()`, os analisadores sintáticos de configuração consideram os seguintes valores `True`: `'1'`, `'yes'`, `'true'`, `'on'` e os seguintes valores `False`: `'0'`, `'no'`, `'false'`, `'off'`. Você pode substituir isso especificando um dicionário personalizado de strings e seus resultados booleanos. Por exemplo:

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

  Outros pares booleanos típicos incluem `accept`/`reject` ou `enabled`/`disabled`.

`ConfigParser.``optionxform`(option)

  Este método transforma nomes de opções em cada operação de leitura, obtenção ou definição. O padrão converte o nome em letras minúsculas. Isso também significa que quando um arquivo de configuração for gravado, todas as chaves estarão em letras minúsculas. Substitua esse método se for inadequado. Por exemplo:

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

  A função optionxform transforma nomes de opções em um formato canônico. Esta deve ser uma função idempotente: se o nome já estiver na forma canônica, deverá ser retornado inalterado.

`ConfigParser.``SECTCRE`

  Uma expressão regular compilada usada para analisar cabeçalhos de seção. O padrão corresponde a `[section]` para o nome `"section"`. O espaço em branco é considerado parte do nome da seção, portanto `[ larch ]` será lido como uma seção de nome `" larch "`. Substitua esse atributo se for inadequado. Por exemplo:

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

  Embora os objetos ConfigParser também usem um atributo `OPTCRE` para reconhecer linhas de opção, não é recomendado substituí-lo porque isso interferiria nas opções do construtor allow_no_value e delimiters.

## Exemplos de APIs legadas

Principalmente por questões de compatibilidade com versões anteriores, `configparser` fornece também uma API legada com métodos `get`/`set` explícitos. Embora existam casos de uso válidos para os métodos descritos abaixo, o acesso ao protocolo de mapeamento é preferido para novos projetos. A API legada é às vezes mais avançada, de baixo nível e totalmente contraintuitiva.

Um exemplo de escrita em um arquivo de configuração:

    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)

Um exemplo de leitura do arquivo de configuração novamente:

    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 obter interpolação, use `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

Os valores padrão estão disponíveis em ambos os tipos de ConfigParsers. Eles são usados em interpolação se uma opção usada não estiver definida em outro 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={})

  O principal analisador sintático de configuração. Quando defaults é fornecido, ele é inicializado no dicionário de padrões intrínsecos. Quando dict_type for fornecido, ele será usado para criar os objetos dicionário para a lista de seções, para as opções dentro de uma seção e para os valores padrão.

  Quando delimiters são fornecidos, eles são usados como o conjunto de substrings que dividem chaves de valores. Quando comment_prefixes for fornecido, ele será usado como o conjunto de substrings que prefixam comentários em linhas vazias. Os comentários podem ser indentados. Quando inline_comment_prefixes for fornecido, ele será usado como o conjunto de substrings que prefixam comentários em linhas não vazias.

  Quando strict for `True` (o padrão), o analisador sintático não permitirá nenhuma seção ou opção duplicada durante a leitura de uma única fonte (arquivo, string ou dicionário), levantando `DuplicateSectionError` ou `DuplicateOptionError`. Quando empty_lines_in_values é `False` (padrão: `True`), cada linha vazia marca o fim de uma opção. Caso contrário, as linhas vazias internas de uma opção multilinha serão mantidas como parte do valor. Quando allow_no_value for `True` (padrão: `False`), opções sem valores serão aceitas; o valor mantido para estes é `None` e eles são serializados sem o delimitador final.

  When default_section is given, it specifies the name for the special section holding default values for other sections and interpolation purposes (normally named `"DEFAULT"`). This value can be retrieved and changed on runtime using the `default_section` instance attribute.

  O comportamento de interpolação pode ser personalizado fornecendo um manipulador personalizado por meio do argumento interpolation. `None` pode ser usado para desligar completamente a interpolação, `ExtendedInterpolation()` fornece uma variante mais avançada inspirada em `zc.buildout`. Mais sobre o assunto na seção de documentação dedicada.

  Todos os nomes de opções usados na interpolação serão passados através do método `optionxform()` assim como qualquer outra referência de nome de opção. Por exemplo, usando a implementação padrão de `optionxform()` (que converte nomes de opções para letras minúsculas), os valores `foo %(bar)s` e `foo %(BAR)s` são equivalentes.

  When converters is given, it should be a dictionary where each key represents the name of a type converter and each value is a callable implementing the conversion from string to the desired datatype. Every converter gets its own corresponding `get*()` method on the parser object and section proxies.

  Alterado na versão 3.1: O padrão dict_type é `collections.OrderedDict`.

  Alterado na versão 3.2: allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_section e interpolation foram adicionados.

  Alterado na versão 3.5: O argumento converters foi adicionado.

  Alterado na versão 3.7: O argumento defaults é lido com `read_dict()`, fornecendo um comportamento consistente em todo o analisador: chaves e valores que não são de string são convertidos implicitamente em strings.

  Alterado na versão 3.8: O dict_type padrão é `dict`, pois agora preserva a ordem de inserção.

  `defaults`()

    Retorna um dicionário contendo os padrões de toda a instância.

  `sections`()

    Retorna uma lista das seções disponíveis; a seção padrão não está incluída na lista.

  `add_section`(section)

    Adiciona uma seção de nome section à instância. Se já existir uma seção com o nome fornecido, `DuplicateSectionError` será levantada. Se o nome da seção padrão for passado, `ValueError` será levantada. O nome da seção deve ser uma string; caso contrário, `TypeError` será levantada.

    Alterado na versão 3.2: Nomes de seções sem string levantam `TypeError`.

  `has_section`(section)

    Indica se a section nomeada está presente na configuração. A seção padrão não é reconhecida.

  `options`(section)

    Retorna uma lista de opções disponíveis na section especificada.

  `has_option`(section, option)

    Se a section fornecida existir e contiver a option fornecida, retorna `True`; caso contrário, retorna `False`. Se a section especificada for `None` ou uma string vazia, DEFAULT será presumido.

  `read`(filenames, encoding=None)

    Tenta ler e analisar um iterável de nomes de arquivos, retornando uma lista de nomes de arquivos que foram analisados com sucesso.

    Se filenames for uma string, um objeto `bytes` ou um objeto caminho ou similar, este parâmetro será tratado como um único nome de arquivo. Se um arquivo nomeado em filenames não puder ser aberto, esse arquivo será ignorado. Isso foi projetado para que você possa especificar um iterável de possíveis locais de arquivo de configuração (por exemplo, o diretório atual, o diretório inicial do usuário e algum diretório de todo o sistema) e todos os arquivos de configuração existentes no iterável serão lidos.

    Se nenhum dos arquivos nomeados existir, a instância `ConfigParser` conterá um conjunto de dados vazio. Uma aplicação que requer que valores iniciais sejam carregados de um arquivo deve carregar o arquivo ou arquivos necessários usando `read_file()` antes de chamar `read()` para quaisquer arquivos opcionais:

        import configparser, os

        config = configparser.ConfigParser()
        config.read_file(open('defaults.cfg'))
        config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],
                    encoding='cp1250')

    Novo na versão 3.2: The encoding parameter. Previously, all files were read using the default encoding for `open()`.

    Novo na versão 3.6.1: O parâmetro filenames aceita um objeto caminho ou similar.

    Novo na versão 3.7: O parâmetro filenames aceita um objeto `bytes`.

  `read_file`(f, source=None)

    Lê e analisa dados de configuração de f que devem ser iteráveis, produzindo strings Unicode (por exemplo, arquivos abertos em modo texto).

    Optional argument source specifies the name of the file being read. If not given and f has a `name` attribute, that is used for source; the default is `'<???>'`.

    Novo na versão 3.2: Substitui `readfp()`.

  `read_string`(string, source='<string>')

    Analisa dados de configuração de uma string.

    O argumento opcional source especifica um nome específico do contexto da string passada. Se não for fornecido, `'<string>'` será usado. Geralmente deve ser um caminho do sistema de arquivos ou uma URL.

    Novo na versão 3.2.

  `read_dict`(dictionary, source='<dict>')

    Carrega a configuração de qualquer objeto que forneça um método `items()` dict ou similar. Chaves são nomes de seções, valores são dicionários com chaves e valores que devem estar presentes na seção. Se o tipo de dicionário usado preservar a ordem, as seções e suas chaves serão adicionadas em ordem. Os valores são convertidos automaticamente em strings.

    O argumento opcional source especifica um nome específico do contexto do dicionário passado. Se não for fornecido, `<dict>` será usado.

    Este método pode ser usado para copiar o estado entre analisadores sintáticos.

    Novo na versão 3.2.

  `get`(section, option, *, raw=False, vars=None[, fallback])

    Obtém um valor de option para a section nomeada. Se vars for fornecido, deverá ser um dicionário. A option é pesquisada em vars (se fornecido), section e em DEFAULTSECT nesta ordem. Se a chave não for encontrada e fallback for fornecido, ele será usado como um valor alternativo. `None` pode ser fornecido como um valor fallback.

    Todas as interpolações `'%'` são expandidas nos valores de retorno, a menos que o argumento raw seja verdadeiro. Os valores das chaves de interpolação são consultados da mesma maneira que a opção.

    Alterado na versão 3.2: Os argumentos raw, vars e fallback são palavras somente-nomeadas para proteger os usuários de tentarem usar o terceiro argumento como substituto fallback (especialmente ao usar o protocolo de mapeamento).

  `getint`(section, option, *, raw=False, vars=None[, fallback])

    Um método de conveniência que força a option na section especificada ser um número inteiro. Veja `get()` para explicação de raw, vars e fallback.

  `getfloat`(section, option, *, raw=False, vars=None[, fallback])

    A convenience method which coerces the option in the specified section to a floating point number. See `get()` for explanation of raw, vars and fallback.

  `getboolean`(section, option, *, raw=False, vars=None[, fallback])

    Um método de conveniência que força a option na section especificada a um valor booleano. Observe que os valores aceitos para a opção são `'1'`, `'yes'`, `'true'`, e `'on'`, o que fazem com que este método retorne `True`, e `'0'`, `'no'`, `'false'`, e `'off'`, o que fazem com que ele retorne `False`. Esses valores de string são verificados sem distinção entre maiúsculas e minúsculas. Qualquer outro valor fará com que ele levante `ValueError`. Veja `get()` para explicação de raw, vars e fallback.

  `items`(raw=False, vars=None)
  `items`(section, raw=False, vars=None)

    Quando section não é fornecido, retorna uma lista de pares section_name, section_proxy, incluindo DEFAULTSECT.

    Caso contrário, retorna uma lista de pares name, value para as opções na section fornecida. Argumentos opcionais têm o mesmo significado do método `get()`.

    Alterado na versão 3.8: Os itens presentes em vars não aparecem mais no resultado. O comportamento anterior misturava opções reais do analisador sintático com variáveis fornecidas para interpolação.

  `set`(section, option, value)

    Se a seção fornecida existir, defina a opção fornecida com o valor especificado; caso contrário, levanta `NoSectionError`. option e value devem ser strings; caso contrário, `TypeError` será levantada.

  `write`(fileobject, space_around_delimiters=True)

    Escreve uma representação da configuração no objeto arquivo especificado, que deve ser aberto em modo texto (aceitando strings). Esta representação pode ser analisada por uma futura chamada `read()`. Se space_around_delimiters for verdadeiro, os delimitadores entre chaves e valores serão envoltos por espaços.

  Nota

  Os comentários no arquivo de configuração original não são preservados ao escrever a configuração. O que é considerado um comentário depende dos valores fornecidos para comment_prefix e inline_comment_prefix.

  `remove_option`(section, option)

    Remove a option especificada da section especificada. Se a seção não existir, levanta `NoSectionError`. Se existisse a opção de ser removida, retorna `True`; caso contrário, retorna `False`.

  `remove_section`(section)

    Remove a section especificada da configuração. Se a seção de fato existiu, retorna `True`. Caso contrário, retorna `False`.

  `optionxform`(option)

    Transforma o nome da opção option conforme encontrado em um arquivo de entrada ou conforme passado pelo código do cliente no formato que deve ser usado nas estruturas internas. A implementação padrão retorna uma versão em minúsculas de option; subclasses podem substituir isso ou o código do cliente pode definir um atributo com esse nome nas instâncias para afetar esse comportamento.

    Você não precisa criar uma subclasse do analisador sintático para usar esse método; você também pode configurá-lo em uma instância, para uma função que recebe um argumento de string e retorna uma string. Definir como `str`, por exemplo, faria com que sejam diferenciadas as letras maiúsculas das minúsculas nos nomes das opções:

        cfgparser = ConfigParser()
        cfgparser.optionxform = str

    Observe que ao ler arquivos de configuração, os espaços em branco ao redor dos nomes das opções são removidos antes de `optionxform()` ser chamado.

  `readfp`(fp, filename=None)

    Obsoleto desde a versão 3.2: Use `read_file()` instead.

    Alterado na versão 3.2: `readfp()` now iterates on fp instead of calling `fp.readline()`.

    For existing code calling `readfp()` with arguments which don’t support iteration, the following generator may be used as a wrapper around the file-like object:

        def readline_generator(fp):
            line = fp.readline()
            while line:
                yield line
                line = fp.readline()

    Instead of `parser.readfp(fp)` use `parser.read_file(readline_generator(fp))`.

`configparser.``MAX_INTERPOLATION_DEPTH`

  The maximum depth for recursive interpolation for `get()` when the raw parameter is false. This is relevant only when the default interpolation is used.

## 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 legada do `ConfigParser`. Ela tem a interpolação desabilitada por padrão e permite nomes de seções não-string, nomes de opções e valores através de seus métodos inseguros `add_section` e `set`, bem como o tratamento de argumentos nomeados legados `defaults=` .

  Alterado na versão 3.8: O dict_type padrão é `dict`, pois agora preserva a ordem de inserção.

  Nota

  Considere usar `ConfigParser`, que verifica os tipos de valores a serem armazenados internamente. Se você não quiser interpolação, você pode usar `ConfigParser(interpolation=None)`.

  `add_section`(section)

    Adiciona uma seção chamada section à instância. Se já existir uma seção com o nome fornecido, `DuplicateSectionError` será levantada. Se o nome da seção padrão for passado, `ValueError` será levantada.

    O tipo da section não está marcado, o que permite aos usuários criar seções nomeadas sem string. Este comportamento não é compatível e pode causar erros internos.

  `set`(section, option, value)

    Se a seção fornecida existir, defina a opção fornecida com o valor especificado; caso contrário, levanta `NoSectionError`. Embora seja possível usar `RawConfigParser` (ou `ConfigParser` com parâmetros raw definidos como verdadeiro) para armazenamento interno de valores não-string, funcionalidade completa (incluindo interpolação e saída para arquivos) só pode ser alcançado usando valores de string.

    Este método permite que os usuários atribuam valores não-string às chaves internamente. Este comportamento não é suportado e causará erros ao tentar escrever em um arquivo ou obtê-lo no modo não bruto. Use a API do protocolo de mapeamento que não permite que tais atribuições ocorram.

## Exceções

exception `configparser.``Error`

  Classe base para todas as outras exceções do `configparser`.

exception `configparser.``NoSectionError`

  Exceção levantada quando uma seção especificada não é encontrada.

exception `configparser.``DuplicateSectionError`

  Exception raised if `add_section()` is called with the name of a section that is already present or in strict parsers when a section if found more than once in a single input file, string or dictionary.

  Novo na versão 3.2: Optional `source` and `lineno` attributes and arguments to `__init__()` were added.

exception `configparser.``DuplicateOptionError`

  Exceção levantada por analisadores sintáticos estritos se uma única opção aparecer duas vezes durante a leitura de um único arquivo, string ou dicionário. Isso detecta erros ortográficos e erros relacionados a diferenciação de letras maiúsculas e minúsculas como, p. ex., um dicionário pode ter duas chaves representando a mesma chave de configuração que não diferencia maiúsculas de minúsculas.

exception `configparser.``NoOptionError`

  Exceção levantada quando uma opção especificada não é encontrada na seção especificada.

exception `configparser.``InterpolationError`

  Classe base para exceções levantadas quando ocorrem problemas ao executar a interpolação de strings.

exception `configparser.``InterpolationDepthError`

  Exceção levantada quando a interpolação de string não pode ser concluída porque o número de iterações excede `MAX_INTERPOLATION_DEPTH`. Subclasse de `InterpolationError`.

exception `configparser.``InterpolationMissingOptionError`

  Exceção levantada quando uma opção referenciada a partir de um valor não existe. Subclasse de `InterpolationError`.

exception `configparser.``InterpolationSyntaxError`

  Exceção levantada quando o texto fonte no qual são feitas as substituições não está em conformidade com a sintaxe exigida. Subclasse de `InterpolationError`.

exception `configparser.``MissingSectionHeaderError`

  Exceção levantada ao tentar analisar um arquivo que não possui cabeçalhos de seção.

exception `configparser.``ParsingError`

  Exceção levantada quando ocorrem erros ao tentar analisar um arquivo.

  Alterado na versão 3.2: The `filename` attribute and `__init__()` argument were renamed to `source` for consistency.

Notas de rodapé

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

  Os analisadores sintáticos de configuração permitem muita personalização. Caso você tenha interesse em alterar o comportamento descrito na referência da nota de rodapé, consulte a seção Personalizando o comportamento do analisador sintático.