"sqlite3" --- DB-API 2.0 interfaz para bases de datos SQLite
************************************************************

**Código fuente:** Lib/sqlite3/

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

SQLite es una biblioteca de C que provee una base de datos ligera
basada en disco que no requiere un proceso de servidor separado y
permite acceder a la base de datos usando una variación no estándar
del lenguaje de consulta SQL. Algunas aplicaciones pueden usar SQLite
para almacenamiento interno. También es posible prototipar una
aplicación usando SQLite y luego transferir el código a una base de
datos más grande como PostgreSQL u Oracle.

The sqlite3 module was written by Gerhard Häring.  It provides an SQL
interface compliant with the DB-API 2.0 specification described by
**PEP 249**.

To use the module, start by creating a "Connection" object that
represents the database.  Here the data will be stored in the
"example.db" file:

   import sqlite3
   con = sqlite3.connect('example.db')

The special path name ":memory:" can be provided to create a temporary
database in RAM.

Once a "Connection" has been established, create a "Cursor" object and
call its "execute()" method to perform SQL commands:

   cur = con.cursor()

   # Create table
   cur.execute('''CREATE TABLE stocks
                  (date text, trans text, symbol text, qty real, price real)''')

   # Insert a row of data
   cur.execute("INSERT INTO stocks VALUES ('2006-01-05','BUY','RHAT',100,35.14)")

   # Save (commit) the changes
   con.commit()

   # We can also close the connection if we are done with it.
   # Just be sure any changes have been committed or they will be lost.
   con.close()

The saved data is persistent: it can be reloaded in a subsequent
session even after restarting the Python interpreter:

   import sqlite3
   con = sqlite3.connect('example.db')
   cur = con.cursor()

To retrieve data after executing a SELECT statement, either treat the
cursor as an *iterator*, call the cursor's "fetchone()" method to
retrieve a single matching row, or call "fetchall()" to get a list of
the matching rows.

Este ejemplo usa la forma con el iterador:

   >>> for row in cur.execute('SELECT * FROM stocks ORDER BY price'):
           print(row)

   ('2006-01-05', 'BUY', 'RHAT', 100, 35.14)
   ('2006-03-28', 'BUY', 'IBM', 1000, 45.0)
   ('2006-04-06', 'SELL', 'IBM', 500, 53.0)
   ('2006-04-05', 'BUY', 'MSFT', 1000, 72.0)

SQL operations usually need to use values from Python variables.
However, beware of using Python's string operations to assemble
queries, as they are vulnerable to SQL injection attacks (see the xkcd
webcomic for a humorous example of what can go wrong):

   # Never do this -- insecure!
   symbol = 'RHAT'
   cur.execute("SELECT * FROM stocks WHERE symbol = '%s'" % symbol)

Instead, use the DB-API's parameter substitution. To insert a variable
into a query string, use a placeholder in the string, and substitute
the actual values into the query by providing them as a "tuple" of
values to the second argument of the cursor's "execute()" method. An
SQL statement may use one of two kinds of placeholders: question marks
(qmark style) or named placeholders (named style). For the qmark
style, "parameters" must be a *sequence*. For the named style, it can
be either a *sequence* or "dict" instance. The length of the
*sequence* must match the number of placeholders, or a
"ProgrammingError" is raised. If a "dict" is given, it must contain
keys for all named parameters. Any extra items are ignored. Here's an
example of both styles:

   import sqlite3

   con = sqlite3.connect(":memory:")
   cur = con.cursor()
   cur.execute("create table lang (name, first_appeared)")

   # This is the qmark style:
   cur.execute("insert into lang values (?, ?)", ("C", 1972))

   # The qmark style used with executemany():
   lang_list = [
       ("Fortran", 1957),
       ("Python", 1991),
       ("Go", 2009),
   ]
   cur.executemany("insert into lang values (?, ?)", lang_list)

   # And this is the named style:
   cur.execute("select * from lang where first_appeared=:year", {"year": 1972})
   print(cur.fetchall())

   con.close()

Ver también:

  https://www.sqlite.org
     La página web SQLite; la documentación describe la sintaxis y los
     tipos de datos disponibles para el lenguaje SQL soportado.

  https://www.w3schools.com/sql/
     Tutorial, referencia y ejemplos para aprender sintaxis SQL.

  **PEP 249** - Especificación de la API 2.0 de base de datos
     PEP escrito por Marc-André Lemburg.


Funciones y constantes del módulo
=================================

sqlite3.apilevel

   String constant stating the supported DB-API level. Required by the
   DB-API. Hard-coded to ""2.0"".

sqlite3.paramstyle

   String constant stating the type of parameter marker formatting
   expected by the "sqlite3" module. Required by the DB-API. Hard-
   coded to ""qmark"".

   Nota:

     The "sqlite3" module supports both "qmark" and "numeric" DB-API
     parameter styles, because that is what the underlying SQLite
     library supports. However, the DB-API does not allow multiple
     values for the "paramstyle" attribute.

sqlite3.version

   El número de versión de este módulo, como una cadena de caracteres.
   Este no es la versión de la librería SQLite.

sqlite3.version_info

   El número de versión de este módulo, como una tupla de enteros.
   Este no es la versión de la librería SQLite.

sqlite3.sqlite_version

   El número de versión de la librería SQLite en tiempo de ejecución,
   como una cadena de caracteres.

sqlite3.sqlite_version_info

   El número de versión de la librería SQLite en tiempo de ejecución,
   como una tupla de enteros.

sqlite3.threadsafety

   Integer constant required by the DB-API, stating the level of
   thread safety the "sqlite3" module supports. Currently hard-coded
   to "1", meaning *"Threads may share the module, but not
   connections."* However, this may not always be true. You can check
   the underlying SQLite library's compile-time threaded mode using
   the following query:

      import sqlite3
      con = sqlite3.connect(":memory:")
      con.execute("""
          select * from pragma_compile_options
          where compile_options like 'THREADSAFE=%'
      """).fetchall()

   Note that the SQLITE_THREADSAFE levels do not match the DB-API 2.0
   "threadsafety" levels.

sqlite3.PARSE_DECLTYPES

   Esta constante se usa con el parámetro *detect_types* de la función
   "connect()".

   Configurarla hace que el módulo "sqlite3" analice el tipo declarado
   para cada columna que retorna. Este convertirá la primera palabra
   del tipo declarado, i. e. para *"integer primary key"*, será
   convertido a *"integer"*, o para "*number(10)*" será convertido a
   "*number*". Entonces para esa columna, revisará el diccionario de
   conversiones y usará la función de conversión registrada para ese
   tipo.

sqlite3.PARSE_COLNAMES

   Esta constante se usa con el parámetro *detect_types* de la función
   "connect()".

   Setting this makes the SQLite interface parse the column name for
   each column it returns.  It will look for a string formed [mytype]
   in there, and then decide that 'mytype' is the type of the column.
   It will try to find an entry of 'mytype' in the converters
   dictionary and then use the converter function found there to
   return the value. The column name found in "Cursor.description"
   does not include the type, i. e. if you use something like "'as
   "Expiration date [datetime]"'" in your SQL, then we will parse out
   everything until the first "'['" for the column name and strip the
   preceding space: the column name would simply be "Expiration date".

sqlite3.connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri])

   Abre una conexión al archivo de base de datos SQLite *database*.
   Por defecto retorna un objeto "Connection", a menos que se indique
   un *factory* personalizado.

   *database* es un *path-like object* indicando el nombre de ruta
   (absoluta o relativa al directorio de trabajo actual) del archivo
   de base de datos abierto. Se puede usar "":memory:"" para abrir una
   conexión de base de datos a una base de datos que reside en memoria
   RAM en lugar que disco.

   Cuando una base de datos es accedida por múltiples conexiones, y
   uno de los procesos modifica la base de datos, la base de datos
   SQLite se bloquea hasta que la transacción se confirme. El
   parámetro *timeout* especifica que tanto debe esperar la conexión
   para que el bloqueo desaparezca antes de lanzar una excepción. Por
   defecto el parámetro *timeout* es de 5.0 (cinco segundos).

   Para el parámetro *isolation_level*, por favor ver la propiedad
   "isolation_level" del objeto "Connection".

   De forma nativa SQLite soporta solo los tipos *TEXT*,
   *INTEGER*,*REAL*,*BLOB* y *NULL*. Si se quiere usar otros tipos,
   debe soportarlos usted mismo. El parámetro *detect_types* y el uso
   de **converters** personalizados registrados con la función a nivel
   del módulo "register_converter()" permite hacerlo fácilmente.

   *detect_types* por defecto es 0 (es decir, desactivado, sin
   detección de tipo), puede configurarlo en cualquier combinación de
   "PARSE_DECLTYPES" y "PARSE_COLNAMES" para activar la detección de
   tipo. Debido al comportamiento de SQLite, los tipos no se pueden
   detectar para los campos generados (por ejemplo, "max(data)"),
   incluso cuando se establece el parámetro *detect_types*. En tal
   caso, el tipo devuelto es "str".

   Por defecto, *check_same_thread* es "True" y únicamente el hilo
   creado puede utilizar la conexión. Si se configura "False", la
   conexión retornada podrá ser compartida con múltiples hilos. Cuando
   se utilizan múltiples hilos con la misma conexión, las operaciones
   de escritura deberán ser serializadas por el usuario para evitar
   corrupción de datos.

   Por defecto el módulo "sqlite3" utiliza su propia clase
   "Connection" para la llamada de conexión. Sin embargo se puede
   crear una subclase de "Connection" y hacer que "connect()" use su
   clase en lugar de proveer la suya en el parámetro *factory*.

   Consulte la sección SQLite y tipos de Python de este manual para
   más detalles.

   El módulo "sqlite3" internamente usa cache de declaraciones para
   evitar un análisis SQL costoso. Si se desea especificar el número
   de sentencias que estarán en memoria caché para la conexión, se
   puede configurar el parámetro *cached_statements*. Por defecto
   están configurado para 100 sentencias en memoria caché.

   If *uri* is "True", *database* is interpreted as a URI (Uniform
   Resource Identifier) with a file path and an optional query string.
   The scheme part *must* be ""file:"".  The path can be a relative or
   absolute file path.  The query string allows us to pass parameters
   to SQLite. Some useful URI tricks include:

      # Open a database in read-only mode.
      con = sqlite3.connect("file:template.db?mode=ro", uri=True)

      # Don't implicitly create a new database file if it does not already exist.
      # Will raise sqlite3.OperationalError if unable to open a database file.
      con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)

      # Create a shared named in-memory database.
      con1 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
      con2 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
      con1.executescript("create table t(t); insert into t values(28);")
      rows = con2.execute("select * from t").fetchall()

   More information about this feature, including a list of recognized
   parameters, can be found in the SQLite URI documentation.

   Lanza un evento de auditoría "sqlite3.connect" con argumento
   "database".

   Distinto en la versión 3.4: Agregado el parámetro *uri*.

   Distinto en la versión 3.7: *database* ahora también puede ser un
   *path-like object*, no solo una cadena de caracteres.

sqlite3.register_converter(typename, callable)

   Registra un invocable para convertir un *bytestring* de la base de
   datos en un tipo Python personalizado. El invocable será invocado
   por todos los valores de la base de datos que son del tipo
   *typename*. Conceder el parámetro *detect_types* de la función
   "connect()" para el funcionamiento de la detección de tipo. Se debe
   notar que *typename* y el nombre del tipo en la consulta son
   comparados insensiblemente a mayúsculas y minúsculas.

sqlite3.register_adapter(type, callable)

   Registra un invocable para convertir el tipo Python personalizado
   *type* a uno de los tipos soportados por SQLite's. El invocable
   *callable* acepta un único parámetro de valor Python, y debe
   retornar un valor de los siguientes tipos: *int*, *float*, *str* or
   *bytes*.

sqlite3.complete_statement(sql)

   Retorna "True" si la cadena *sql* contiene una o más sentencias SQL
   completas terminadas con punto y coma. No se verifica que la
   sentencia SQL sea sintácticamente correcta, solo que no existan
   literales de cadenas no cerradas y que la sentencia termine por un
   punto y coma.

   Esto puede ser usado para construir un *shell* para SQLite, como en
   el siguiente ejemplo:

      # A minimal SQLite shell for experiments

      import sqlite3

      con = sqlite3.connect(":memory:")
      con.isolation_level = None
      cur = con.cursor()

      buffer = ""

      print("Enter your SQL commands to execute in sqlite3.")
      print("Enter a blank line to exit.")

      while True:
          line = input()
          if line == "":
              break
          buffer += line
          if sqlite3.complete_statement(buffer):
              try:
                  buffer = buffer.strip()
                  cur.execute(buffer)

                  if buffer.lstrip().upper().startswith("SELECT"):
                      print(cur.fetchall())
              except sqlite3.Error as e:
                  print("An error occurred:", e.args[0])
              buffer = ""

      con.close()

sqlite3.enable_callback_tracebacks(flag)

   Por defecto no se obtendrá ningún *tracebacks* en funciones
   definidas por el usuario, agregaciones, *converters*, autorizador
   de *callbacks* etc. si se quiere depurarlas, se puede llamar esta
   función con *flag* configurado a "True". Después se obtendrán
   *tracebacks* de los *callbacks* en "sys.stderr". Usar "False" para
   deshabilitar la característica de nuevo.


Objetos de conexión
===================

class sqlite3.Connection

   An SQLite database connection has the following attributes and
   methods:

   isolation_level

      Obtener o configurar el actual nivel de insolación. "None" para
      modo *autocommit* o uno de "DEFERRED", "IMMEDIATE" o
      "EXCLUSIVO". Ver sección Controlando Transacciones para una
      explicación detallada.

   in_transaction

      "True" si una transacción está activa (existen cambios
      *uncommitted*), "False" en sentido contrario. Atributo de solo
      lectura.

      Nuevo en la versión 3.2.

   cursor(factory=Cursor)

      El método cursor acepta un único parámetro opcional *factory*.
      Si es agregado, éste debe ser un invocable que retorna una
      instancia de "Cursor" o sus subclases.

   commit()

      Este método asigna la transacción actual. Si no se llama este
      método, cualquier cosa hecha desde la última llamada de
      "commit()" no es visible para otras conexiones de bases de
      datos. Si se pregunta el porqué no se ven los datos que
      escribiste, por favor verifica que no olvidaste llamar este
      método.

   rollback()

      Este método retrocede cualquier cambio en la base de datos desde
      la llamada del último "commit()".

   close()

      Este método cierra la conexión a la base de datos. Nótese que
      éste no llama automáticamente "commit()". Si se cierra la
      conexión a la base de datos sin llamar primero "commit()", los
      cambios se perderán!

   execute(sql[, parameters])

      Create a new "Cursor" object and call "execute()" on it with the
      given *sql* and *parameters*. Return the new cursor object.

   executemany(sql[, parameters])

      Create a new "Cursor" object and call "executemany()" on it with
      the given *sql* and *parameters*. Return the new cursor object.

   executescript(sql_script)

      Create a new "Cursor" object and call "executescript()" on it
      with the given *sql_script*. Return the new cursor object.

   create_function(name, num_params, func, *, deterministic=False)

      Crea un función definida de usuario que se puede usar después
      desde declaraciones SQL con el nombre de función *name*.
      *num_params* es el número de parámetros que la función acepta
      (si *num_params* is -1, la función puede tomar cualquier número
      de argumentos), y *func* es un invocable de Python que es
      llamado como la función SQL. Si *deterministic* es verdadero, la
      función creada es marcada como deterministic, lo cual permite a
      SQLite hacer optimizaciones adicionales. Esta marca es soportada
      por SQLite 3.8.3 o superior, será lanzado "NotSupportedError" si
      se usa con versiones antiguas.

      La función puede retornar cualquier tipo soportado por SQLite:
      bytes, str, int, float y "None".

      Distinto en la versión 3.8: El parámetro *deterministic* fue
      agregado.

      Ejemplo:

         import sqlite3
         import hashlib

         def md5sum(t):
             return hashlib.md5(t).hexdigest()

         con = sqlite3.connect(":memory:")
         con.create_function("md5", 1, md5sum)
         cur = con.cursor()
         cur.execute("select md5(?)", (b"foo",))
         print(cur.fetchone()[0])

         con.close()

   create_aggregate(name, num_params, aggregate_class)

      Crea una función agregada definida por el usuario.

      La clase agregada debe implementar un método "step", el cual
      acepta el número de parámetros *num_params* (si *num_params* es
      -1, la función puede tomar cualquier número de argumentos), y un
      método "finalize" el cual retornará el resultado final del
      agregado.

      El método "finalize" puede retornar cualquiera de los tipos
      soportados por SQLite: bytes, str, int, float and "None".

      Ejemplo:

         import sqlite3

         class MySum:
             def __init__(self):
                 self.count = 0

             def step(self, value):
                 self.count += value

             def finalize(self):
                 return self.count

         con = sqlite3.connect(":memory:")
         con.create_aggregate("mysum", 1, MySum)
         cur = con.cursor()
         cur.execute("create table test(i)")
         cur.execute("insert into test(i) values (1)")
         cur.execute("insert into test(i) values (2)")
         cur.execute("select mysum(i) from test")
         print(cur.fetchone()[0])

         con.close()

   create_collation(name, callable)

      Crea una collation con el *name* y *callable* especificado. El
      invocable será pasado con dos cadenas de texto como argumentos.
      Se retornará -1 si el primero esta ordenado menor que el
      segundo, 0 si están ordenados igual y 1 si el primero está
      ordenado mayor que el segundo. Nótese que esto controla la
      ordenación (ORDER BY en SQL) por lo tanto sus comparaciones no
      afectan otras comparaciones SQL.

      Note que el invocable obtiene sus parámetros como Python
      bytestrings, lo cual normalmente será codificado en UTF-8.

      El siguiente ejemplo muestra una *collation* personalizada que
      ordena "La forma incorrecta":

         import sqlite3

         def collate_reverse(string1, string2):
             if string1 == string2:
                 return 0
             elif string1 < string2:
                 return 1
             else:
                 return -1

         con = sqlite3.connect(":memory:")
         con.create_collation("reverse", collate_reverse)

         cur = con.cursor()
         cur.execute("create table test(x)")
         cur.executemany("insert into test(x) values (?)", [("a",), ("b",)])
         cur.execute("select x from test order by x collate reverse")
         for row in cur:
             print(row)
         con.close()

      Para remover una collation, llama "create_collation" con "None"
      como invocable:

         con.create_collation("reverse", None)

   interrupt()

      Se puede llamar este método desde un hilo diferente para abortar
      cualquier consulta que pueda estar ejecutándose en la conexión.
      La consulta será abortada y quien realiza la llamada obtendrá
      una excepción.

   set_authorizer(authorizer_callback)

      Esta rutina registra un callback. El callback es invocado para
      cada intento de acceso a un columna de una tabla en la base de
      datos. El callback deberá retornar "SQLITE_OK" si el acceso esta
      permitido, "SQLITE_DENY" si la completa declaración SQL deberá
      ser abortada con un error y "SQLITE_IGNORE" si la columna deberá
      ser tratada como un valor NULL. Estas constantes están
      disponibles en el módulo "sqlite3".

      El primer argumento del callback significa que tipo de operación
      será autorizada. El segundo y tercer argumento serán argumentos
      o "None" dependiendo del primer argumento. El cuarto argumento
      es el nombre de la base de datos ("main", "temp", etc.) si
      aplica. El quinto argumento es el nombre del disparador más
      interno o vista que es responsable por los intentos de acceso o
      "None" si este intento de acceso es directo desde el código SQL
      de entrada.

      Por favor consulte la documentación de SQLite sobre los posibles
      valores para el primer argumento y el significado del segundo y
      tercer argumento dependiendo del primero. Todas las constantes
      necesarias están disponibles en el módulo "sqlite3".

   set_progress_handler(handler, n)

      Esta rutina registra un *callback*. El *callback* es invocado
      para cada *n* instrucciones de la máquina virtual SQLite. Esto
      es útil si se quiere tener llamado a SQLite durante operaciones
      de larga duración, por ejemplo para actualizar una GUI.

      Si se desea limpiar cualquier *progress handler* instalado
      previamente, llame el método con "None" para *handler*.

      Retornando un valor diferente a 0 de la función gestora
      terminará la actual consulta en ejecución y causará lanzar una
      excepción "OperationalError".

   set_trace_callback(trace_callback)

      Registra *trace_callback* para ser llamado por cada sentencia
      SQL que realmente se ejecute por el *backend* de SQLite.

      The only argument passed to the callback is the statement (as
      "str") that is being executed. The return value of the callback
      is ignored. Note that the backend does not only run statements
      passed to the "Cursor.execute()" methods.  Other sources include
      the transaction management of the sqlite3 module and the
      execution of triggers defined in the current database.

      Pasando "None" como *trace_callback* deshabilitara el *trace
      callback*.

      Nota:

        Exceptions raised in the trace callback are not propagated. As
        a development and debugging aid, use
        "enable_callback_tracebacks()" to enable printing tracebacks
        from exceptions raised in the trace callback.

      Nuevo en la versión 3.3.

   enable_load_extension(enabled)

      Esta rutina habilita/deshabilita el motor de SQLite para cargar
      extensiones SQLite desde bibliotecas compartidas. Las
      extensiones SQLite pueden definir nuevas funciones, agregaciones
      o una completa nueva implementación de tablas virtuales. Una
      bien conocida extensión es *fulltext-search* distribuida con
      SQLite.

      Las extensiones cargables están deshabilitadas por defecto. Ver
      [1].

      Nuevo en la versión 3.2.

         import sqlite3

         con = sqlite3.connect(":memory:")

         # enable extension loading
         con.enable_load_extension(True)

         # Load the fulltext search extension
         con.execute("select load_extension('./fts3.so')")

         # alternatively you can load the extension using an API call:
         # con.load_extension("./fts3.so")

         # disable extension loading again
         con.enable_load_extension(False)

         # example from SQLite wiki
         con.execute("create virtual table recipe using fts3(name, ingredients)")
         con.executescript("""
             insert into recipe (name, ingredients) values ('broccoli stew', 'broccoli peppers cheese tomatoes');
             insert into recipe (name, ingredients) values ('pumpkin stew', 'pumpkin onions garlic celery');
             insert into recipe (name, ingredients) values ('broccoli pie', 'broccoli cheese onions flour');
             insert into recipe (name, ingredients) values ('pumpkin pie', 'pumpkin sugar flour butter');
             """)
         for row in con.execute("select rowid, name, ingredients from recipe where name match 'pie'"):
             print(row)

         con.close()

   load_extension(path)

      This routine loads an SQLite extension from a shared library.
      You have to enable extension loading with
      "enable_load_extension()" before you can use this routine.

      Las extensiones cargables están deshabilitadas por defecto. Ver
      [1].

      Nuevo en la versión 3.2.

   row_factory

      Se puede cambiar este atributo a un invocable que acepta el
      cursor y la fila original como una tupla y retornará la fila con
      el resultado real. De esta forma, se puede implementar más
      avanzadas formas de retornar resultados, tales como retornar un
      objeto que puede también acceder a las columnas por su nombre.

      Ejemplo:

         import sqlite3

         def dict_factory(cursor, row):
             d = {}
             for idx, col in enumerate(cursor.description):
                 d[col[0]] = row[idx]
             return d

         con = sqlite3.connect(":memory:")
         con.row_factory = dict_factory
         cur = con.cursor()
         cur.execute("select 1 as a")
         print(cur.fetchone()["a"])

         con.close()

      Si retornado una tupla no es suficiente y se quiere acceder a
      las columnas basadas en nombre, se debe considerar configurar
      "row_factory" a la altamente optimizada tipo "sqlite3.Row".
      "Row" provee ambos accesos a columnas basada en índice y tipado
      insensible con casi nada de sobrecoste de memoria. Será
      probablemente mejor que tú propio enfoque de basado en
      diccionario personalizado o incluso mejor que una solución
      basada en *db_row*.

   text_factory

      Using this attribute you can control what objects are returned
      for the "TEXT" data type. By default, this attribute is set to
      "str" and the "sqlite3" module will return "str" objects for
      "TEXT". If you want to return "bytes" instead, you can set it to
      "bytes".

      También se puede configurar a cualquier otro *callable* que
      acepte un único parámetro *bytestring* y retorne el objeto
      resultante.

      Ver el siguiente ejemplo de código para ilustración:

         import sqlite3

         con = sqlite3.connect(":memory:")
         cur = con.cursor()

         AUSTRIA = "Österreich"

         # by default, rows are returned as str
         cur.execute("select ?", (AUSTRIA,))
         row = cur.fetchone()
         assert row[0] == AUSTRIA

         # but we can make sqlite3 always return bytestrings ...
         con.text_factory = bytes
         cur.execute("select ?", (AUSTRIA,))
         row = cur.fetchone()
         assert type(row[0]) is bytes
         # the bytestrings will be encoded in UTF-8, unless you stored garbage in the
         # database ...
         assert row[0] == AUSTRIA.encode("utf-8")

         # we can also implement a custom text_factory ...
         # here we implement one that appends "foo" to all strings
         con.text_factory = lambda x: x.decode("utf-8") + "foo"
         cur.execute("select ?", ("bar",))
         row = cur.fetchone()
         assert row[0] == "barfoo"

         con.close()

   total_changes

      Regresa el número total de filas de la base de datos que han
      sido modificadas, insertadas o borradas desde que la conexión a
      la base de datos fue abierta.

   iterdump()

      Regresa un iterador para volcar la base de datos en un texto de
      formato SQL. Es útil cuando guardamos una base de datos en
      memoria para posterior restauración. Esta función provee las
      mismas capacidades que el comando "dump" en el *shell*
      **sqlite3**.

      Ejemplo:

         # Convert file existing_db.db to SQL dump file dump.sql
         import sqlite3

         con = sqlite3.connect('existing_db.db')
         with open('dump.sql', 'w') as f:
             for line in con.iterdump():
                 f.write('%s\n' % line)
         con.close()

   backup(target, *, pages=-1, progress=None, name="main", sleep=0.250)

      This method makes a backup of an SQLite database even while it's
      being accessed by other clients, or concurrently by the same
      connection.  The copy will be written into the mandatory
      argument *target*, that must be another "Connection" instance.

      Por defecto, o cuando *pages* es "0" o un entero negativo, la
      base de datos completa es copiada en un solo paso; de otra forma
      el método realiza un bucle copiando hasta el número de *pages* a
      la vez.

      Si *progress* es especificado, deberá ser "None" o un objeto
      *callable* que será ejecutado en cada iteración con los tres
      argumentos enteros, respectivamente el estado *status* de la
      última iteración, el restante *remaining* numero de páginas
      presentes para ser copiadas y el número total *total* de
      páginas.

      El argumento *name* especifica el nombre de la base de datos que
      será copiada: deberá ser una cadena de texto que contenga el por
      defecto ""main"", que indica la base de datos principal,
      ""temp"" que indica la base de datos temporal o el nombre
      especificado después de la palabra clave "AS" en una sentencia
      "ATTACH DATABASE" para una base de datos adjunta.

      El argumento *sleep* especifica el número de segundos a dormir
      entre sucesivos intentos de respaldar páginas restantes, puede
      ser especificado como un entero o un valor de punto flotante.

      Ejemplo 1, copiar una base de datos existente en otra:

         import sqlite3

         def progress(status, remaining, total):
             print(f'Copied {total-remaining} of {total} pages...')

         con = sqlite3.connect('existing_db.db')
         bck = sqlite3.connect('backup.db')
         with bck:
             con.backup(bck, pages=1, progress=progress)
         bck.close()
         con.close()

      Ejemplo 2: copiar una base de datos existente en una copia
      transitoria:

         import sqlite3

         source = sqlite3.connect('existing_db.db')
         dest = sqlite3.connect(':memory:')
         source.backup(dest)

      Disponibilidad: SQLite 3.6.11 o superior

      Nuevo en la versión 3.7.


Objetos Cursor
==============

class sqlite3.Cursor

   Una instancia de "Cursor" tiene los siguientes atributos y métodos.

   execute(sql[, parameters])

      Executes an SQL statement. Values may be bound to the statement
      using placeholders.

      "execute()" solo ejecutará una única sentencia SQL. Si se trata
      de ejecutar más de una sentencia con el, lanzará un "Warning".
      Usar "executescript()" si se quiere ejecutar múltiples
      sentencias SQL con una llamada.

   executemany(sql, seq_of_parameters)

      Executes a parameterized SQL command against all parameter
      sequences or mappings found in the sequence *seq_of_parameters*.
      The "sqlite3" module also allows using an *iterator* yielding
      parameters instead of a sequence.

         import sqlite3

         class IterChars:
             def __init__(self):
                 self.count = ord('a')

             def __iter__(self):
                 return self

             def __next__(self):
                 if self.count > ord('z'):
                     raise StopIteration
                 self.count += 1
                 return (chr(self.count - 1),) # this is a 1-tuple

         con = sqlite3.connect(":memory:")
         cur = con.cursor()
         cur.execute("create table characters(c)")

         theIter = IterChars()
         cur.executemany("insert into characters(c) values (?)", theIter)

         cur.execute("select c from characters")
         print(cur.fetchall())

         con.close()

      Acá un corto ejemplo usando un *generator*:

         import sqlite3
         import string

         def char_generator():
             for c in string.ascii_lowercase:
                 yield (c,)

         con = sqlite3.connect(":memory:")
         cur = con.cursor()
         cur.execute("create table characters(c)")

         cur.executemany("insert into characters(c) values (?)", char_generator())

         cur.execute("select c from characters")
         print(cur.fetchall())

         con.close()

   executescript(sql_script)

      This is a nonstandard convenience method for executing multiple
      SQL statements at once. It issues a "COMMIT" statement first,
      then executes the SQL script it gets as a parameter.  This
      method disregards "isolation_level"; any transaction control
      must be added to *sql_script*.

      *sql_script* puede ser una instancia de "str".

      Ejemplo:

         import sqlite3

         con = sqlite3.connect(":memory:")
         cur = con.cursor()
         cur.executescript("""
             create table person(
                 firstname,
                 lastname,
                 age
             );

             create table book(
                 title,
                 author,
                 published
             );

             insert into book(title, author, published)
             values (
                 'Dirk Gently''s Holistic Detective Agency',
                 'Douglas Adams',
                 1987
             );
             """)
         con.close()

   fetchone()

      Obtiene la siguiente fila de un conjunto resultado, retorna una
      única secuencia, o "None" cuando no hay más datos disponibles.

   fetchmany(size=cursor.arraysize)

      Obtiene el siguiente conjunto de filas del resultado de una
      consulta, retornando una lista. Una lista vacía es retornada
      cuando no hay más filas disponibles.

      El número de filas a obtener por llamado es especificado por el
      parámetro *size*. Si no es suministrado, el arraysize del cursor
      determina el número de filas a obtener. El método debería
      intentar obtener tantas filas como las indicadas por el
      parámetro size. Si esto no es posible debido a que el número
      especificado de filas no está disponible, entonces menos filas
      deberán ser retornadas.

      Nótese que hay consideraciones de desempeño involucradas con el
      parámetro *size*. Para un optimo desempeño, es usualmente mejor
      usar el atributo *arraysize*. Si el parámetro *size* es usado,
      entonces es mejor retener el mismo valor de una llamada
      "fetchmany()" a la siguiente.

   fetchall()

      Obtiene todas las filas (restantes) del resultado de una
      consulta. Nótese que el atributo arraysize del cursor puede
      afectar el desempeño de esta operación. Una lista vacía será
      retornada cuando no hay filas disponibles.

   close()

      Cierra el cursor ahora (en lugar que cuando "__del__" es
      llamado)

      El cursor no será usable de este punto en adelante; una
      excepción "ProgrammingError" será lanzada si se intenta
      cualquier operación con el cursor.

   setinputsizes(sizes)

      Required by the DB-API. Does nothing in "sqlite3".

   setoutputsize(size[, column])

      Required by the DB-API. Does nothing in "sqlite3".

   rowcount

      A pesar de que la clase "Cursor" del módulo "sqlite3" implementa
      este atributo, el propio soporte del motor de base de datos para
      la determinación de "filas afectadas"/"filas seleccionadas" es
      raro.

      Para sentencias "executemany()", el número de modificaciones se
      resumen en "rowcount".

      Cómo lo requiere la especificación Python DB API, el atributo
      "rowcount" "es -1 en caso de que "executeXX()" no haya sido
      ejecutada en el cursor o en el *rowcount* de la última operación
      no haya sido determinada por la interface". Esto incluye
      sentencias "SELECT" porque no podemos determinar el número de
      filas que una consulta produce hasta que todas las filas sean
      obtenidas.

      Con versiones de SQLite anteriores a 3.6.5, "rowcount" es
      configurado a 0 si se hace un "DELETE FROM table" sin ninguna
      condición.

   lastrowid

      This read-only attribute provides the row id of the last
      inserted row. It is only updated after successful "INSERT" or
      "REPLACE" statements using the "execute()" method.  For other
      statements, after "executemany()" or "executescript()", or if
      the insertion failed, the value of "lastrowid" is left
      unchanged.  The initial value of "lastrowid" is "None".

      Nota:

        Inserts into "WITHOUT ROWID" tables are not recorded.

      Distinto en la versión 3.6: Se agregó soporte para sentencias
      "REPLACE".

   arraysize

      Atributo de lectura/escritura que controla el número de filas
      retornadas por "fetchmany()". El valor por defecto es 1, lo cual
      significa que una única fila será obtenida por llamada.

   description

      Este atributo de solo lectura provee el nombre de las columnas
      de la última consulta. Para ser compatible con Python DB API,
      retorna una 7-tupla para cada columna en donde los últimos seis
      ítems de cada tupla son "None".

      También es configurado para sentencias "SELECT" sin ninguna fila
      coincidente.

   connection

      Este atributo de solo lectura provee la "Connection" de la base
      de datos SQLite usada por el objeto "Cursor". Un objeto "Cursor"
      creado por la llamada de "con.cursor()" tendrá un atributo
      "connection" que se refiere a *con*:

         >>> con = sqlite3.connect(":memory:")
         >>> cur = con.cursor()
         >>> cur.connection == con
         True


Objetos Fila (*Row*)
====================

class sqlite3.Row

   Una instancia "Row" sirve como una altamente optimizada
   "row_factory" para objetos "Connection". Esta trata de imitar una
   tupla en su mayoría de características.

   Soporta acceso mapeado por nombre de columna e índice, iteración,
   representación, pruebas de igualdad y "len()".

   Si dos objetos "Row" tienen exactamente las mismas columnas y sus
   miembros son iguales, entonces se comparan a igual.

   keys()

      Este método retorna una lista con los nombre de columnas.
      Inmediatamente después de una consulta, es el primer miembro de
      cada tupla en "Cursor.description".

   Distinto en la versión 3.5: Agrega soporte de segmentación.

Vamos a asumir que se inicializa una tabla como en el ejemplo dado:

   con = sqlite3.connect(":memory:")
   cur = con.cursor()
   cur.execute('''create table stocks
   (date text, trans text, symbol text,
    qty real, price real)''')
   cur.execute("""insert into stocks
               values ('2006-01-05','BUY','RHAT',100,35.14)""")
   con.commit()
   cur.close()

Ahora conectamos "Row" en:

   >>> con.row_factory = sqlite3.Row
   >>> cur = con.cursor()
   >>> cur.execute('select * from stocks')
   <sqlite3.Cursor object at 0x7f4e7dd8fa80>
   >>> r = cur.fetchone()
   >>> type(r)
   <class 'sqlite3.Row'>
   >>> tuple(r)
   ('2006-01-05', 'BUY', 'RHAT', 100.0, 35.14)
   >>> len(r)
   5
   >>> r[2]
   'RHAT'
   >>> r.keys()
   ['date', 'trans', 'symbol', 'qty', 'price']
   >>> r['qty']
   100.0
   >>> for member in r:
   ...     print(member)
   ...
   2006-01-05
   BUY
   RHAT
   100.0
   35.14


Excepciones
===========

exception sqlite3.Warning

   Una subclase de "Exception".

exception sqlite3.Error

   La clase base de otras excepciones en este módulo. Es una subclase
   de "Exception".

exception sqlite3.DatabaseError

   Excepción lanzada para errores que están relacionados con la base
   de datos.

exception sqlite3.IntegrityError

   Excepción lanzada cuando la integridad de la base de datos es
   afectada, por ejemplo la comprobación de una llave foránea falla.
   Es una subclase de "DatabaseError".

exception sqlite3.ProgrammingError

   Excepción lanzada por errores de programación, e.g. tabla no
   encontrada o ya existente, error de sintaxis en la sentencia SQL,
   número equivocado de parámetros especificados, etc. Es una subclase
   de "DatabaseError".

exception sqlite3.OperationalError

   Excepción lanzada por errores relacionados por la operación de la
   base de datos y no necesariamente bajo el control del programador,
   por ejemplo ocurre una desconexión inesperada, el nombre de la
   fuente de datos no es encontrado, una transacción no pudo ser
   procesada, etc. Es una subclase de "DatabaseError".

exception sqlite3.NotSupportedError

   Excepción lanzada en caso de que un método o API de base de datos
   fuera usada en una base de datos que no la soporta, e.g. llamando
   el método "rollback()" en una conexión que no soporta la
   transacción o tiene deshabilitada las transacciones. Es una
   subclase de "DatabaseError".


SQLite y tipos de Python
========================


Introducción
------------

SQLite soporta de forma nativa los siguientes tipos: "NULL",
"INTEGER", "REAL", "TEXT", "BLOB".

Los siguientes tipos de Python se pueden enviar a SQLite sin problema
alguno:

+---------------------------------+---------------+
| Tipo de Python                  | Tipo de       |
|                                 | SQLite        |
|=================================|===============|
| "None"                          | "NULL"        |
+---------------------------------+---------------+
| "int"                           | "INTEGER"     |
+---------------------------------+---------------+
| "float"                         | "REAL"        |
+---------------------------------+---------------+
| "str"                           | "TEXT"        |
+---------------------------------+---------------+
| "bytes"                         | "BLOB"        |
+---------------------------------+---------------+

De esta forma es como los tipos de SQLite son convertidos a tipos de
Python por defecto:

+---------------+------------------------------------------------+
| Tipo de       | Tipo de Python                                 |
| SQLite        |                                                |
|===============|================================================|
| "NULL"        | "None"                                         |
+---------------+------------------------------------------------+
| "INTEGER"     | "int"                                          |
+---------------+------------------------------------------------+
| "REAL"        | "float"                                        |
+---------------+------------------------------------------------+
| "TEXT"        | depende de "text_factory", "str" por defecto   |
+---------------+------------------------------------------------+
| "BLOB"        | "bytes"                                        |
+---------------+------------------------------------------------+

The type system of the "sqlite3" module is extensible in two ways: you
can store additional Python types in an SQLite database via object
adaptation, and you can let the "sqlite3" module convert SQLite types
to different Python types via converters.


Usando adaptadores para almacenar tipos adicionales de Python en bases de datos SQLite
--------------------------------------------------------------------------------------

Como se describió anteriormente, SQLite soporta solamente un conjunto
limitado de tipos de forma nativa. Para usar otros tipos de Python con
SQLite, se deben **adaptar** a uno de los tipos de datos soportados
por el módulo sqlite3 para SQLite: uno de NoneType, int, float, str,
bytes.

Hay dos formas de habilitar el módulo "sqlite3" para adaptar un tipo
personalizado de Python a alguno de los admitidos.


Permitiéndole al objeto auto adaptarse
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Este es un buen enfoque si uno mismo escribe la clase. Vamos a suponer
que se tiene una clase como esta:

   class Point:
       def __init__(self, x, y):
           self.x, self.y = x, y

Ahora desea almacenar el punto en una sola columna de SQLite. Primero
tendrá que elegir uno de los tipos admitidos que se utilizará para
representar el punto. Usemos str y separemos las coordenadas usando un
punto y coma. Luego, debe darle a su clase un método "__conform
__(self, protocol)" que debe retornar el valor convertido. El
parámetro *protocol* será "PrepareProtocol".

   import sqlite3

   class Point:
       def __init__(self, x, y):
           self.x, self.y = x, y

       def __conform__(self, protocol):
           if protocol is sqlite3.PrepareProtocol:
               return "%f;%f" % (self.x, self.y)

   con = sqlite3.connect(":memory:")
   cur = con.cursor()

   p = Point(4.0, -3.2)
   cur.execute("select ?", (p,))
   print(cur.fetchone()[0])

   con.close()


Registrando un adaptador invocable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

La otra posibilidad es crear una función que convierta el escrito a
representación de cadena de texto y registrar la función con
"register_adapter()".

   import sqlite3

   class Point:
       def __init__(self, x, y):
           self.x, self.y = x, y

   def adapt_point(point):
       return "%f;%f" % (point.x, point.y)

   sqlite3.register_adapter(Point, adapt_point)

   con = sqlite3.connect(":memory:")
   cur = con.cursor()

   p = Point(4.0, -3.2)
   cur.execute("select ?", (p,))
   print(cur.fetchone()[0])

   con.close()

El módulo "sqlite3" tiene dos adaptadores por defecto para las
funciones integradas de Python "datetime.date" y tipos
"datetime.datetime". Ahora vamos a suponer que queremos almacenar
objetos "datetime.datetime" no en representación ISO, sino como una
marca de tiempo Unix.

   import sqlite3
   import datetime
   import time

   def adapt_datetime(ts):
       return time.mktime(ts.timetuple())

   sqlite3.register_adapter(datetime.datetime, adapt_datetime)

   con = sqlite3.connect(":memory:")
   cur = con.cursor()

   now = datetime.datetime.now()
   cur.execute("select ?", (now,))
   print(cur.fetchone()[0])

   con.close()


Convertir valores SQLite a tipos de Python personalizados
---------------------------------------------------------

Escribir un adaptador permite enviar escritos personalizados de Python
a SQLite. Pero para hacer esto realmente útil, tenemos que hace el
flujo Python a SQLite a Python.

Ingresar convertidores.

Regresemos a la clase "Point". Se almacena las coordenadas x e y de
forma separada por punto y coma como una cadena de texto en SQLite.

Primero, se define una función de conversión que acepta la cadena de
texto como un parámetro y construye un objeto "Point" de ahí.

Nota:

  Las funciones de conversión  **siempre** son llamadas con un objeto
  "bytes", no importa bajo qué tipo de dato se envió el valor a
  SQLite.

   def convert_point(s):
       x, y = map(float, s.split(b";"))
       return Point(x, y)

Ahora se necesita hacer que el módulo "sqlite3" conozca que lo que tu
seleccionaste de la base de datos es de hecho un punto. Hay dos formas
de hacer esto:

* Implícitamente vía el tipo declarado

* Explícitamente vía el nombre de la columna

Ambas formas están descritas en la sección Funciones y constantes del
módulo, en las entradas para las constantes "PARSE_DECLTYPES" y
"PARSE_COLNAMES".

El siguiente ejemplo ilustra ambos enfoques.

   import sqlite3

   class Point:
       def __init__(self, x, y):
           self.x, self.y = x, y

       def __repr__(self):
           return "(%f;%f)" % (self.x, self.y)

   def adapt_point(point):
       return ("%f;%f" % (point.x, point.y)).encode('ascii')

   def convert_point(s):
       x, y = list(map(float, s.split(b";")))
       return Point(x, y)

   # Register the adapter
   sqlite3.register_adapter(Point, adapt_point)

   # Register the converter
   sqlite3.register_converter("point", convert_point)

   p = Point(4.0, -3.2)

   #########################
   # 1) Using declared types
   con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
   cur = con.cursor()
   cur.execute("create table test(p point)")

   cur.execute("insert into test(p) values (?)", (p,))
   cur.execute("select p from test")
   print("with declared types:", cur.fetchone()[0])
   cur.close()
   con.close()

   #######################
   # 1) Using column names
   con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
   cur = con.cursor()
   cur.execute("create table test(p)")

   cur.execute("insert into test(p) values (?)", (p,))
   cur.execute('select p as "p [point]" from test')
   print("with column names:", cur.fetchone()[0])
   cur.close()
   con.close()


Adaptadores y convertidores por defecto
---------------------------------------

Hay adaptadores por defecto para los tipos date y datetime en el
módulo datetime. Éstos serán enviados como fechas/marcas de tiempo ISO
a SQLite.

Los convertidores por defecto están registrados bajo el nombre "date"
para "datetime.date" y bajo el mismo nombre para "timestamp" para
"datetime.datetime".

De esta forma, se puede usar date/timestamps para Python sin ajuste
adicional en la mayoría de los casos. El formato de los adaptadores
también es compatible con las funciones experimentales de SQLite
date/time.

El siguiente ejemplo demuestra esto.

   import sqlite3
   import datetime

   con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
   cur = con.cursor()
   cur.execute("create table test(d date, ts timestamp)")

   today = datetime.date.today()
   now = datetime.datetime.now()

   cur.execute("insert into test(d, ts) values (?, ?)", (today, now))
   cur.execute("select d, ts from test")
   row = cur.fetchone()
   print(today, "=>", row[0], type(row[0]))
   print(now, "=>", row[1], type(row[1]))

   cur.execute('select current_date as "d [date]", current_timestamp as "ts [timestamp]"')
   row = cur.fetchone()
   print("current_date", row[0], type(row[0]))
   print("current_timestamp", row[1], type(row[1]))

   con.close()

Si un *timestamp* almacenado en SQLite tiene una parte fraccional
mayor a 6 números, este valor será truncado a precisión de
microsegundos por el convertidor de *timestamp*.

Nota:

  The default "timestamp" converter ignores UTC offsets in the
  database and always returns a naive "datetime.datetime" object. To
  preserve UTC offsets in timestamps, either leave converters
  disabled, or register an offset-aware converter with
  "register_converter()".


Controlando Transacciones
=========================

La librería subyacente "sqlite3" opera en modo "autocommit" por
defecto, pero el módulo de Python "sqlite3" no.

El modo "autocommit" significa que la sentencias que modifican la base
de datos toman efecto de forma inmediata. Una sentencia "BEGIN" o
"SAVEPOINT" deshabilitan el modo "autocommit", y un "COMMIT", un
"ROLLBACK", o un "RELEASE" que terminan la transacción más externa,
habilitan de nuevo el modo "autocommit".

El módulo de Python "sqlite3" emite por defecto una sentencia "BEGIN"
implícita antes de una sentencia tipo Lenguaje Manipulación de Datos
(DML) (es decir "INSERT"/"UPDATE"/"DELETE"/"REPLACE").

Se puede controlar en qué tipo de sentencias "BEGIN" "sqlite3"
implícitamente ejecuta vía el parámetro *insolation_level* a la
función de llamada "connect()", o vía las propiedades de conexión
"isolation_level". Si no se especifica *isolation_level*, se usa un
plano "BEGIN", el cuál es equivalente a especificar "DEFERRED". Otros
posibles valores son "IMMEDIATE" and "EXCLUSIVE".

Se puede deshabilitar la gestión implícita de transacciones del módulo
"sqlite3" con la configuración "isolation_level" a "None". Esto dejará
la subyacente biblioteca operando en modo "autocommit". Se puede
controlar completamente el estado de la transacción emitiendo
explícitamente sentencias "BEGIN", "ROLLBACK", "SAVEPOINT", y
"RELEASE" en el código.

Note that "executescript()" disregards "isolation_level"; any
transaction control must be added explicitly.

Distinto en la versión 3.6: "sqlite3" solía realizar commit en
transacciones implícitamente antes de sentencias DDL. Este ya no es el
caso.


Usando "sqlite3" eficientemente
===============================


Usando métodos atajo
--------------------

Usando los métodos no estándar "execute()", "executemany()" y
"executescript()" del objeto "Connection", el código puede ser escrito
más consistentemente porque no se tienen que crear explícitamente los
(a menudo superfluos) objetos "Cursor". En cambio, los objetos de
"Cursor" son creados implícitamente y estos métodos atajo retornan los
objetos cursor. De esta forma, se puede ejecutar una sentencia
"SELECT" e iterar directamente sobre él, solamente usando una única
llamada al objeto "Connection".

   import sqlite3

   langs = [
       ("C++", 1985),
       ("Objective-C", 1984),
   ]

   con = sqlite3.connect(":memory:")

   # Create the table
   con.execute("create table lang(name, first_appeared)")

   # Fill the table
   con.executemany("insert into lang(name, first_appeared) values (?, ?)", langs)

   # Print the table contents
   for row in con.execute("select name, first_appeared from lang"):
       print(row)

   print("I just deleted", con.execute("delete from lang").rowcount, "rows")

   # close is not a shortcut method and it's not called automatically,
   # so the connection object should be closed manually
   con.close()


Accediendo a las columnas por el nombre en lugar del índice
-----------------------------------------------------------

Una característica útil del módulo "sqlite3" es la clase incluida
"sqlite3.Row" diseñada para ser usada como una fábrica de filas.

Filas envueltas con esta clase pueden ser accedidas tanto por índice
(al igual que tuplas) como por nombre insensible a mayúsculas o
minúsculas:

   import sqlite3

   con = sqlite3.connect(":memory:")
   con.row_factory = sqlite3.Row

   cur = con.cursor()
   cur.execute("select 'John' as name, 42 as age")
   for row in cur:
       assert row[0] == row["name"]
       assert row["name"] == row["nAmE"]
       assert row[1] == row["age"]
       assert row[1] == row["AgE"]

   con.close()


Usando la conexión como un administrador de contexto
----------------------------------------------------

Los objetos de conexión pueden ser usados como administradores de
contexto que automáticamente transacciones commit o rollback. En el
evento de una excepción, la transacción es retrocedida; de otra forma,
la transacción es confirmada:

   import sqlite3

   con = sqlite3.connect(":memory:")
   con.execute("create table lang (id integer primary key, name varchar unique)")

   # Successful, con.commit() is called automatically afterwards
   with con:
       con.execute("insert into lang(name) values (?)", ("Python",))

   # con.rollback() is called after the with block finishes with an exception, the
   # exception is still raised and must be caught
   try:
       with con:
           con.execute("insert into lang(name) values (?)", ("Python",))
   except sqlite3.IntegrityError:
       print("couldn't add Python twice")

   # Connection object used as context manager only commits or rollbacks transactions,
   # so the connection object should be closed manually
   con.close()

-[ Notas al pie ]-

[1] The sqlite3 module is not built with loadable extension support by
    default, because some platforms (notably macOS) have SQLite
    libraries which are compiled without this feature. To get loadable
    extension support, you must pass "--enable-loadable-sqlite-
    extensions" to configure.
