dbm — Interfaces para “banco de dados” Unix

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

dbm é uma interface genérica para variantes do banco de dados DBM:

If none of these modules are installed, the slow-but-simple implementation in module dbm.dumb will be used. There is a third party interface to the Oracle Berkeley DB.

Nota

None of the underlying modules will automatically shrink the disk space used by the database file. However, dbm.sqlite3, dbm.gnu and dbm.dumb provide a reorganize() method that can be used for this purpose.

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.sqlite3, 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

# Abre o banco de dados, criando-o se necessário.
with dbm.open('cache', 'c') as db:

    # Registra alguns valores
    db[b'hello'] = b'there'
    db['www.python.org'] = 'Python Website'
    db['www.cnn.com'] = 'Cable News Network'

    # Note que as chaves são consideradas bytes agora.
    assert db[b'www.python.org'] == b'Python Website'
    # Observe como o valor é agora em bytes.
    assert db['www.cnn.com'] == b'Cable News Network'

    # Métodos geralmente usados da interface dict funcionam também.
    print(db.get('python.org', b'not present'))

    # Armazenar uma chave não-string ou valor  vai levantar uma exceção
    # (provavelmente uma TypeError).
    db['www.yahoo.com'] = 4

# db é automaticamente fechado a sair da instrução with.

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.sqlite3 — Backend de SQLite para dbm

Adicionado na versão 3.13.

Código-fonte: Lib/dbm/sqlite3.py

Este módulo usa o módulo da biblioteca padrão sqlite3 para fornecer um backend de SQLite para o módulo dbm. Os arquivos criados por dbm.sqlite3 podem então ser abertos por sqlite3 ou quaisquer outros navegadores de SQLite, incluindo CLI do SQLite.

Disponibilidade: not WASI.

Este módulo não funciona ou não está disponível em WebAssembly. Veja Plataformas WebAssembly para mais informações.

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

Abre um banco de dados de SQLite. O objeto retornado se comporta como um mapeamento, implementa um método close() e oferece suporte um gerenciador de contexto de “fechamento” via a palavra reservada with.

Parâmetros:

  • filename (path-like object) – O caminho para o banco de dados a ser aberta.

  • 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 – O modo de acesso a arquivos do Unix do arquivo (padrão: octal 0o666), usado apenas quando o banco de dados tem que ser criado.

sqlite3.reorganize()

If you have carried out a lot of deletions and would like to shrink the space used on disk, this method will reorganize the database; otherwise, deleted file space will be kept and reused as new (key, value) pairs are added.

Nota

While reorganizing, as much as two times the size of the original database is required in free disk space. However, be aware that this factor changes for each dbm submodule.

Adicionado na versão 3.15.0a0 (unreleased).

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

Disponibilidade: not Android, not iOS, not WASI.

Este módulo não tem suporte em plataformas móveis ou plataformas WebAssembly.

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.

    • 'm': Do not use mmap(2). This may harm performance, but improve crash tolerance. .. versionadded:: next

    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.

Nota

While reorganizing, as much as one time the size of the original database is required in free disk space. However, be aware that this factor changes for each dbm submodule.

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.

gdbm.clear()

Remove todos os itens do banco de dados GDBM.

Adicionado na versão 3.13.

dbm.ndbm — New Database Manager

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

O módulo dbm.ndbm fornece uma interface para a biblioteca NDBM. Este módulo pode ser usado com a interface NDBM “clássica” ou a interface de compatibilidade GDBM.

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

Disponibilidade: not Android, not iOS, not WASI.

Este módulo não tem suporte em plataformas móveis ou plataformas WebAssembly.

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.

ndbm.clear()

Remove todos os itens do banco de dados NDBM.

Adicionado na versão 3.13.

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.

Aviso

dbm.dumb does not support concurrent read/write access. (Multiple simultaneous read accesses are safe.) When a program has the database open for writing, no other program should have it open for reading or writing.

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

Sincroniza o diretório no disco e os arquivos de dados. Este método é chamado pelo método shelve.Shelf.sync().

dumbdbm.close()

Fecha o banco de dados.

dumbdbm.reorganize()

If you have carried out a lot of deletions and would like to shrink the space used on disk, this method will reorganize the database; otherwise, deleted file space will not be reused.

Nota

While reorganizing, no additional free disk space is required. However, be aware that this factor changes for each dbm submodule.

Adicionado na versão 3.15.0a0 (unreleased).