"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, com uma estrutura semelhante à
encontrada nos arquivos INI do Microsoft Windows. Você pode usar isso
para escrever programas em 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 da sintaxe INI do Registro do
  Windows.

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

   [forge.example]
   User = hg

   [topsecret.server.example]
   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['forge.example'] = {}
   >>> config['forge.example']['User'] = 'hg'
   >>> config['topsecret.server.example'] = {}
   >>> topsecret = config['topsecret.server.example']
   >>> topsecret['Port'] = '50022'     # mutates the parser
   >>> topsecret['ForwardX11'] = 'no'  # same here
   >>> config['DEFAULT']['ForwardX11'] = 'yes'
   >>> with open('example.ini', 'w') as configfile:
   ...   config.write(configfile)
   ...

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()
   ['forge.example', 'topsecret.server.example']
   >>> 'forge.example' in config
   True
   >>> 'python.org' in config
   False
   >>> config['forge.example']['User']
   'hg'
   >>> config['DEFAULT']['Compression']
   'yes'
   >>> topsecret = config['topsecret.server.example']
   >>> topsecret['ForwardX11']
   'no'
   >>> topsecret['Port']
   '50022'
   >>> for key in config['forge.example']:  
   ...     print(key)
   user
   compressionlevel
   serveraliveinterval
   compression
   forwardx11
   >>> config['forge.example']['ForwardX11']
   'yes'

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

It is possible to read several configurations into a single
"ConfigParser", where the most recently added configuration has the
highest priority. Any conflicting keys are taken from the more recent
configuration while the previously existing keys are retained.

   >>> another_config = configparser.ConfigParser()
   >>> another_config.read('example.ini')
   ['example.ini']
   >>> another_config['topsecret.server.example']['Port']
   '50022'
   >>> another_config.read_string("[topsecret.server.example]\nPort=48484")
   >>> another_config['topsecret.server.example']['Port']
   '48484'
   >>> another_config.read_dict({"topsecret.server.example": {"Port": 21212}})
   >>> another_config['topsecret.server.example']['Port']
   '21212'
   >>> another_config['topsecret.server.example']['ForwardX11']
   'no'

Este comportamento é equivalente a uma chamada "ConfigParser.read()"
com vários arquivos passados para o parâmetro *filenames*.


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['forge.example'].getboolean('ForwardX11')
   True
   >>> config.getboolean('forge.example', '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'

Observe que os valores padrão têm precedência sobre os valores
substitutos. Por exemplo, em nosso exemplo a chave
"'CompressionLevel'" foi especificada apenas na seção "'DEFAULT'". Se
tentarmos obtê-lo na seção "'topsecret.server.example'", sempre
obteremos o padrão, mesmo se especificarmos um substituto:

   >>> 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('forge.example', '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] Os analisadores sintáticos de configuração permitem muitas
    personalizações. 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.
