"dbm" --- Interfaces to Unix "databases"
****************************************

**Código-fonte:** Lib/dbm/__init__.py

======================================================================

"dbm" é uma interface genérica para variantes do banco de dados DBM
--- "dbm.gnu" ou "dbm.ndbm". Se nenhum desses módulos estiver
instalado, a implementação lenta, mas simples, no módulo "dbm.dumb"
será usada. Há uma interface de terceiros para o Oracle Berkeley DB.

exception dbm.error

   Uma tupla contendo as exceções que podem ser levantadas por cada um
   dos módulos suportados, com a única exceção também chamada
   "dbm.error" como o primeiro item --- o último é usado quando
   "dbm.error" é levantada.

dbm.whichdb(filename)

   Esta função tenta adivinhar qual dos vários módulos de banco de
   dados simples disponíveis --- "dbm.gnu", "dbm.ndbm" ou "dbm.dumb"
   --- deve ser usado para abrir o arquivo fornecido.

   Retorna um dos seguintes valores:

   * "None" se o arquivo não puder ser aberto porque está ilegível ou
     não existe

   * a string vazia ("''") se o formato do arquivo não puder ser
     adivinhado

   * uma string contendo o nome do módulo necessário, tal como
     "'dbm.ndbm'" ou "'dbm.gnu'"

   Alterado na versão 3.11: *filename* aceita um *objeto caminho ou
   similar*.

dbm.open(file, flag='r', mode=0o666)

   Abre um banco de dados e retorna o objeto banco de dados
   correspondendo.

   Parâmetros:
      * **file** (*path-like object*) -- O arquivo de banco de dados
        para abrir. Se o arquivo de banco de dados já existe, a função
        "whichdb()" é usada para determinar seu tipo e o módulo
        apropriado é usado; se ele não existir, o primeiro submódulo
        listado acima que pode ser importado é usado.

      * **flag** (*str*) --

        * "'r'" (padrão): Open existing database for reading only.

        * "'w'": Open existing database for reading and writing.

        * "'c'": Open database for reading and writing, creating it if
          it doesn't exist.

        * "'n'": Always create a new, empty database, open for reading
          and writing.

      * **mode** (*int*) -- The Unix file access mode of the file
        (default: octal "0o666"), used only when the database has to
        be created.

   Alterado na versão 3.11: *file* aceita um *objeto caminho ou
   similar*.

O objeto retornado por "open()" oferece suporte à mesma funcionalidade
básica que um "dict"; chaves e seus valores correspondentes podem ser
armazenados, obtidos e excluídos, e o operador "in" e o método
"keys()" estão disponíveis, bem como métodos "get()" e "setdefault()".

Chaves e valores são sempre armazenados como "bytes". Isso significa
que quando strings são usadas, elas são implicitamente convertidas
para a codificação padrão antes de serem armazenadas.

Estes objetos também oferecem suporte a serem usados em uma instrução
"with", que vai fechá-los automaticamente quando estiver concluída.

Alterado na versão 3.2: O métodos "get()" e "setdefault()" estão agora
disponíveis para todos os backends do "dbm".

Alterado na versão 3.4: Adicionado suporte nativo para o protocolo de
gerenciamento de contexto para os objetos retornados por "open()".

Alterado na versão 3.8: Excluir uma chave de um banco de dados somente
leitura levanta uma exceção de banco de dados específica do módulo em
vez de "KeyError".

Os seguintes exemplos registram alguns hostnames e um título
correspondente, e então exibe o conteúdo do banco de dados:

   import dbm

   # Open database, creating it if necessary.
   with dbm.open('cache', 'c') as db:

       # Record some values
       db[b'hello'] = b'there'
       db['www.python.org'] = 'Python Website'
       db['www.cnn.com'] = 'Cable News Network'

       # Note that the keys are considered bytes now.
       assert db[b'www.python.org'] == b'Python Website'
       # Notice how the value is now in bytes.
       assert db['www.cnn.com'] == b'Cable News Network'

       # Often-used methods of the dict interface work too.
       print(db.get('python.org', b'not present'))

       # Storing a non-string key or value will raise an exception (most
       # likely a TypeError).
       db['www.yahoo.com'] = 4

   # db is automatically closed when leaving the with statement.

Ver também:

  Módulo "shelve"
     Módulo persistente que armazena dados não-string.

Os submódulos individuais são descritos nas seções a seguir.


"dbm.gnu" --- Gerenciador de banco de dados do GNU
==================================================

**Código-fonte:** Lib/dbm/gnu.py

======================================================================

O módulo "dbm.gnu" fornece uma interface para a biblioteca GDBM (GNU
dbm), semelhante ao módulo "dbm.ndbm", mas com funcionalidades
adicionais, como tolerância a falhas.

Nota:

  Os formatos de arquivo criados por "dbm.gnu" e "dbm.ndbm" são
  incompatíveis e não podem ser usados de forma intercambiável.

exception dbm.gnu.error

   Levantada em erros específicos do "dbm.gnu", como erros de E/S.
   "KeyError" é levantada para erros gerais de mapeamento, como
   especificar uma chave incorreta.

dbm.gnu.open(filename, flag='r', mode=0o666, /)

   Abre um banco de dados GDBM e retorna um objeto "gdbm".

   Parâmetros:
      * **filename** (*path-like object*) -- O arquivo de banco de
        dados para abrir.

      * **flag** (*str*) --

        * "'r'" (padrão): Open existing database for reading only.

        * "'w'": Open existing database for reading and writing.

        * "'c'": Open database for reading and writing, creating it if
          it doesn't exist.

        * "'n'": Always create a new, empty database, open for reading
          and writing.

        Os seguintes caracteres adicionais podem ser acrescentados
        para controlar como o banco de dados é aberto:

        * "'f'": Abre o banco de dados em modo rápido. As gravações no
          banco de dados não serão sincronizadas.

        * "'s'": Modo sincronizado. Alterações no banco de dados serão
          gravadas imediatamente no arquivo.

        * "'u'": Não trava o banco de dados.

        Nem todos os sinalizadores são válidos para todas as versões
        do GDBM. Veja o membro "open_flags" para uma lista de
        caracteres de sinalizadores suportados.

      * **mode** (*int*) -- The Unix file access mode of the file
        (default: octal "0o666"), used only when the database has to
        be created.

   Levanta:
      **error** -- Se um argumento *flag* inválido for passado.

   Alterado na versão 3.11: *filename* aceita um *objeto caminho ou
   similar*.

   dbm.gnu.open_flags

      Uma sequência de caracteres que o parâmetro *flag* de "open()"
      suporta.

   Os objetos "gdbm" se comportam de forma semelhante a *mapeamentos*,
   mas os métodos "items()" e "values()" não são suportados. Os
   seguintes métodos também são fornecidos:

   gdbm.firstkey()

      É possível fazer um laço em cada chave no banco de dados usando
      este método e o método "nextkey()". A travessia é ordenada pelos
      valores de hash internos do GDBM e não será classificada pelos
      valores de chave. Este método retorna a chave inicial.

   gdbm.nextkey(key)

      Retorna a chave que segue *key* na travessia. O código a seguir
      imprime cada chave no banco de dados "db", sem precisar criar
      uma lista na memória que contenha todas elas:

         k = db.firstkey()
         while k is not None:
             print(k)
             k = db.nextkey(k)

   gdbm.reorganize()

      Se você realizou muitas exclusões e gostaria de reduzir o espaço
      usado pelo arquivo GDBM, esta rotina reorganizará o banco de
      dados. Objetos "gdbm" não reduzirão o tamanho de um arquivo de
      banco de dados, exceto usando esta reorganização; caso
      contrário, o espaço de arquivo excluído será mantido e
      reutilizado à medida que novos pares (chave, valor) forem
      adicionados.

   gdbm.sync()

      Quando o banco de dados é aberto no modo rápido, esse método
      força a gravação de todos os dados não gravados no disco.

   gdbm.close()

      Fecha o banco de dados GDBM.


"dbm.ndbm" --- New Database Manager
===================================

**Código-fonte:** Lib/dbm/ndbm.py

======================================================================

O módulo "dbm.ndbm" fornece uma interface para a biblioteca NDBM (New
Database Manager). Este módulo pode ser usado com a interface NDBM
"clássica" ou a interface de compatibilidade GDBM (GNU dbm).

Nota:

  Os formatos de arquivo criados por "dbm.gnu" e "dbm.ndbm" são
  incompatíveis e não podem ser usados de forma intercambiável.

Aviso:

  A biblioteca NDBM enviada como parte do macOS tem uma limitação não
  documentada no tamanho dos valores, o que pode resultar em arquivos
  de banco de dados corrompidos ao armazenar valores maiores que esse
  limite. Ler esses arquivos corrompidos pode resultar em uma falha
  grave (falha de segmentação).

exception dbm.ndbm.error

   Levantada em erros específicos de "dbm.ndbm", como erros de E/S.
   "KeyError" é levantada para erros gerais de mapeamento, como
   especificar uma chave incorreta.

dbm.ndbm.library

   Nome da biblioteca de implementação NDBM usada.

dbm.ndbm.open(filename, flag='r', mode=0o666, /)

   Abre um banco de dados NDBM e retorna um objeto "ndbm".

   Parâmetros:
      * **filename** (*path-like object*) -- O nome base do arquivo de
        banco de dados (sem as extensões ".dir" ou ".pag").

      * **flag** (*str*) --

        * "'r'" (padrão): Open existing database for reading only.

        * "'w'": Open existing database for reading and writing.

        * "'c'": Open database for reading and writing, creating it if
          it doesn't exist.

        * "'n'": Always create a new, empty database, open for reading
          and writing.

      * **mode** (*int*) -- The Unix file access mode of the file
        (default: octal "0o666"), used only when the database has to
        be created.

   Os objetos "ndbm" se comportam de forma semelhante a *mapeamentos*,
   mas os métodos "items()" e "values()" não são suportados. Os
   seguintes métodos também são fornecidos:

   Alterado na versão 3.11: Aceita um *objeto caminho ou similar* como
   nome de arquivo.

   ndbm.close()

      Fecha o banco de dados NDBM.


"dbm.dumb" --- Implementação portátil do DBM
============================================

**Código-fonte:** Lib/dbm/dumb.py

Nota:

  O módulo "dbm.dumb" é pensado como um último recurso alternativo
  para o módulo "dbm" quando um módulo mais robusto não está
  disponível. O módulo "dbm.dumb" não é escrito para velocidade e não
  é tão usado quanto os outros módulos de banco de dados.

======================================================================

O módulo "dbm.dumb" fornece uma interface persistente do tipo "dict"
que é escrita inteiramente em Python. Ao contrário de outros backends
"dbm", como "dbm.gnu", nenhuma biblioteca externa é necessária.

O módulo "dbm.dumb" define o seguinte:

exception dbm.dumb.error

   Levantada em erros específicos de "dbm.dumb", como erros de E/S.
   "KeyError" é levantada para erros gerais de mapeamento, como
   especificar uma chave incorreta.

dbm.dumb.open(filename, flag='c', mode=0o666)

   Abre um banco de dados "dbm.dumb". O objeto banco de dados
   retornado se comporta de forma semelhante a um *mapeamento*, além
   de fornecer os métodos "sync()" e "close()".

   Parâmetros:
      * **filename** -- O nome base do arquivo do banco de dados (sem
        extensões). Um novo banco de dados cria os seguintes arquivos:
        - "*filename*.dat" - "*filename*.dir"

      * **flag** (*str*) --

        * "'r'": Open existing database for reading only.

        * "'w'": Open existing database for reading and writing.

        * "'c'" (padrão): Open database for reading and writing,
          creating it if it doesn't exist.

        * "'n'": Always create a new, empty database, open for reading
          and writing.

      * **mode** (*int*) -- The Unix file access mode of the file
        (default: octal "0o666"), used only when the database has to
        be created.

   Aviso:

     É possível travar o interpretador Python ao carregar um banco de
     dados com uma entrada suficientemente grande/complexa devido a
     limitações de profundidade de pilha no compilador AST do Python.

   Alterado na versão 3.5: "open()" sempre cria um novo banco de dados
   quando *flag* é "'n'".

   Alterado na versão 3.8: Um banco de dados aberto somente leitura se
   *flag* for "'r'". Um banco de dados não é criado se não existir se
   *flag* for "'r'" ou "'w'".

   Alterado na versão 3.11: *filename* aceita um *objeto caminho ou
   similar*.

   Além dos métodos fornecidos pela classe
   "collections.abc.MutableMapping", os seguintes métodos são
   fornecidos:

   dumbdbm.sync()

      Synchronize the on-disk directory and data files.  This method
      is called by the "Shelve.sync()" method.

   dumbdbm.close()

      Fecha o banco de dados.
