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