# `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`.