dbm — Interfaces para «bases de datos» de Unix

Código fuente: Lib/dbm/__init__.py

---

dbm es una interfaz genérica para variantes de la base de datos DBM — dbm.gnu o dbm.ndbm. Si ninguno de estos módulos son instalados, se utilizará la implementación lenta pero sencilla en el módulo dbm.dumb. Existe una interfaz de terceros para la Oracle Berkeley DB.

exception dbm.error

Una tupla que contiene las excepciones que pueden ser lanzadas por cada uno de los módulos soportados, con una excepción única también denominada dbm.error como el primer elemento — el último se usa cuando se genera dbm.error.

dbm.whichdb(filename)

Esta función intenta adivinar cuál de los varios módulos de base de datos simples disponibles — dbm.gnu, dbm.ndbm o dbm.dumb — deberán usarse para abrir un archivo.

Retorna uno de los siguientes valores: None si el archivo no se puede abrir porque no se puede leer o no existe; la cadena de caracteres vacía ('') si no se puede adivinar el formato del archivo; o una cadena de caracteres que contenga el nombre del módulo requerido, como 'dbm.ndbm' o 'dbm.gnu'.

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

Abre el archivo file de la base de datos y retorna un objeto correspondiente.

Si el archivo de la base de datos existe, la función whichdb() es usada para determinar su tipo y el módulo apropiado se utiliza; sino existe, se utiliza el primer módulo listado anteriormente que se puede importar.

El argumento opcional flag puede ser:

Valor	Significado
'r'	Abre la base de datos existente solo para lectura (predeterminado)
'w'	Abre la base de datos existente para leer y escribir
'c'	Abre la base de datos para lectura y escritura, creándola si no existe
'n'	Siempre cree una base de datos nueva, vacía, abierta para lectura y escritura

El argumento opcional mode es el modo Unix del archivo, usado solamente cuando la base de datos tiene que ser creada. Su valor predeterminado es octal 0o666 (y será modificado por el umask vigente).

El objeto retornado por open() admite la misma funcionalidad básica que los diccionarios; las claves y sus valores correspondientes se pueden almacenar, recuperar y eliminar, y el operador in y el método keys() están disponibles, así como get() y setdefault().

Distinto en la versión 3.2: get() y setdefault() ya están disponibles en todos los módulos de base de datos.

Distinto en la versión 3.8: Al eliminar una clave de una base de datos de solo lectura lanza un error específico del módulo de la base de datos en lugar de KeyError.

La clave y los valores siempre se almacenan como bytes. Esto significa que cuando se utilizan cadenas de caracteres, se convierten implícitamente a la codificación predeterminada antes de almacenarse.

Estos objetos también admiten el uso en una instrucción with, que los cerrará automáticamente cuando termine.

Distinto en la versión 3.4: Se agregó soporte nativo para el protocolo de administración de contexto a los objetos retornados por open().

El siguiente ejemplo registra algunos nombres de host y un título correspondiente, y luego imprime el contenido de la base de datos:

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 también

Módulo shelve

Módulo de persistencia que almacena datos que no son cadenas de caracteres.

Los submódulos individuales se describen en las siguientes secciones.

dbm.gnu — La reinterpretación de GNU de dbm

Código fuente: Lib/dbm/gnu.py

---

Este módulo es bastante similar al módulo dbm, pero usa la biblioteca GNU gdbm en su lugar para proporcionar alguna funcionalidad adicional. Tenga en cuenta que los formatos de archivo creados por dbm.gnu y dbm.ndbm son incompatibles.

El módulo dbm.gnu proporciona una interfaz a la biblioteca GNU DBM. Los objetos dbm.gnu.gdbm se comportan como asignaciones (diccionarios), excepto que las claves y los valores siempre se convierten a bytes antes de almacenarlos. La impresión de un objeto gdbm no imprime las llaves y los valores, y los métodos items() y values() no son compatibles.

exception dbm.gnu.error

Se lanza en errores específicos dbm.gnu, como errores de E/S. KeyError se genera para errores generales de asignación, como especificar una clave incorrecta.

dbm.gnu.open(filename[, flag[, mode]])

Abre una base de datos gdbm y retorna un objeto gdbm. El argumento filename es el nombre del archivo de la base de datos.

El argumento opcional flag puede ser:

Valor	Significado
'r'	Abre la base de datos existente solo para lectura (predeterminado)
'w'	Abre la base de datos existente para leer y escribir
'c'	Abre la base de datos para lectura y escritura, creándola si no existe
'n'	Siempre cree una base de datos nueva, vacía, abierta para lectura y escritura

Los siguientes caracteres adicionales se pueden agregar al flag para controlar cómo se abre la base de datos:

Valor	Significado
'f'	Abre la base de datos en modo rápido. Las escrituras en la base de datos no se sincronizarán.
's'	Modo sincronizado. Esto hará que los cambios en la base de datos se escriban inmediatamente en el archivo.
'u'	No bloquea la base de datos.

No todos los flags son válidas para todas las versiones de gdbm. La constante del módulo open_flags es una cadena de caracteres de flags soportadas. La excepción error se lanza si se especifica un flag no válido.

El argumento opcional mode es el modo Unix del archivo, usado solo cuando la base de datos tiene que ser creada. Su valor predeterminado es octal 0o666.

Además de los métodos similares a los diccionarios, los objetos gdbm tienen los siguientes métodos:

gdbm.firstkey()

Es posible recorrer cada clave en la base de datos usando este método y el método nextkey(). El recorrido está ordenado por los valores hash internos de gdbm y no se ordenará por los valores clave. Este método retorna la clave de inicio.

gdbm.nextkey(key)

Retorna la clave que sigue a key en el recorrido. El siguiente código imprime todas las claves en la base de datos db, sin tener que crear una lista en la memoria que las contenga todas:

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

gdbm.reorganize()

Si ha realizado muchas eliminaciones y desea reducir el espacio utilizado por el archivo gdbm, esta rutina reorganizará la base de datos. Los objetos gdbm no acortarán la longitud de un archivo de base de datos excepto al usar esta reorganización; de lo contrario, el espacio de archivo eliminado se conservará y reutilizará cuando se agreguen nuevos pares (clave, valor).

gdbm.sync()

Cuando la base de datos se ha abierto en modo rápido, este método obliga a que los datos no escritos se escriban en el disco.

gdbm.close()

Cierra la base de datos gdbm.

dbm.ndbm — Interfaz basada en ndbm

Código fuente: Lib/dbm/ndbm.py

---

El módulo dbm.ndbm proporciona una interfaz a la biblioteca «(n)dbm» de Unix. Los objetos DBM se comportan como asignaciones (diccionarios), excepto que las claves y los valores siempre se almacenan como bytes. La impresión de un objeto dbm no imprime las claves y los valores, y los métodos items() y values() no son compatibles.

Este módulo se puede utilizar con la interfaz ndbm «clásica» o la interfaz de compatibilidad GNU GDBM. En Unix, el código configure intentará localizar el archivo de encabezado apropiado para simplificar la construcción de este módulo.

exception dbm.ndbm.error

Se lanza en errores específicos bm.ndbm, como errores de E/S. KeyError lanza para errores generales de asignación, como especificar una clave incorrecta.

dbm.ndbm.library

Nombre de la biblioteca de implementación ndbm utilizada.

dbm.ndbm.open(filename[, flag[, mode]])

Abre una base de datos dbm y retorna un objeto ndbm. El argumento filename es el nombre de la base de datos (sin las extensiones .dir y .pag).

El argumento flag opcional debe ser uno de estos valores:

Valor	Significado
'r'	Abre la base de datos existente solo para lectura (predeterminado)
'w'	Abre la base de datos existente para leer y escribir
'c'	Abre la base de datos para lectura y escritura, creándola si no existe
'n'	Siempre cree una base de datos nueva, vacía, abierta para lectura y escritura

El argumento opcional mode es el modo Unix del archivo, usado solamente cuando la base de datos tiene que ser creada. Su valor predeterminado es octal 0o666 (y será modificado por el umask vigente).

Además de los métodos similares a los de un diccionario, los objetos ndbm proporcionan el siguiente método:

ndbm.close()

Cierra la base de datos ndbm.

dbm.dumb — Implementación de DBM portátil

Código fuente: Lib/dbm/dumb.py

Nota

El módulo dbm.dumb está pensado como último recurso para el módulo dbm cuando no hay disponible un módulo más robusto. El módulo dbm.dymb no está escrito para velocidad y no se usa tanto como los otros módulos de base de datos.

---

El módulo dbm.dumb proporciona una interfaz persistente similar a un diccionario que está escrita completamente en Python. A diferencia de otros módulos como dbm.gnu, no se requiere una biblioteca externa. Al igual que con otras asignaciones persistentes, las claves y los valores siempre se almacenan como bytes.

El módulo define lo siguiente:

exception dbm.dumb.error

Se lanza en errores específicos dbm.dumb, como errores de E/S. KeyError se lanza para errores de mapeo generales como especificar una clave incorrecta.

dbm.dumb.open(filename[, flag[, mode]])

Abre una base de datos dumbdbm y retorna un objeto dumbdbm. El argumento del filename es el nombre base del archivo de la base de datos (sin extensiones específicas). Cuando una base de datos dumbdbm se crea, archivos con la extensión .dat y .dir se crean.

El argumento opcional flag puede ser:

Valor	Significado
'r'	Abre la base de datos existente solo para lectura (predeterminado)
'w'	Abre la base de datos existente para leer y escribir
'c'	Abre la base de datos para lectura y escritura, creándola si no existe
'n'	Siempre cree una base de datos nueva, vacía, abierta para lectura y escritura

El argumento opcional mode es el modo Unix del archivo, usado solamente cuando la base de datos tiene que ser creada. Su valor predeterminado es octal 0o666 (y será modificado por el umask vigente).

Advertencia

Es posible bloquear el intérprete de Python cuando se carga una base de datos con una entrada suficientemente grande/compleja debido a las limitaciones de profundidad de la pila en el compilador AST de Python.

Distinto en la versión 3.5: open() siempre crea una nueva base de datos cuando el flag tiene valor de 'n'.

Distinto en la versión 3.8: Una base de datos abierta con flags 'r' ahora es de solo lectura. Abrir con los flags 'r' y 'w' ya no crea una base de datos si no existe.

Además de los métodos proporcionados por la clase collections.abc.MutableMapping, los objetos dumbdbm proporcionan los siguientes métodos:

dumbdbm.sync()

Sincroniza el directorio en disco y los archivos de datos. Este método es llamado por el método Shelve.sync().

dumbdbm.close()

Cierra la base de datos dumbdbm.