"sqlite3" --- DB-API 2.0 interface for SQLite databases
*******************************************************

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

El módulo "sqlite3" fue escrito por Gerhard Häring. Proporciona una
interfaz SQL compatible con la especificación DB-API 2.0 descrita por
**PEP 249** y requiere SQLite 3.7.15 o posterior.

Esta documentación contiene cuatro secciones principales:

* Tutorial enseña como usar el módulo "sqlite3" module.

* Referencia describe las clases y funciones que se definen en este
  módulo.

* Guías prácticas detalla como manipular tareas específicas.

* Explicación proporciona en profundidad información sobre el control
  transaccional.

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.


Tutorial
========

En este tutorial, será creada una base de datos de películas Monty
Python usando funcionalidades básicas de "sqlite3". Se asume un
entendimiento fundamental de conceptos de bases de dados, como cursors
y transactions.

First, we need to create a new database and open a database connection
to allow "sqlite3" to work with it. Call "sqlite3.connect()" to create
a connection to the database "tutorial.db" in the current working
directory, implicitly creating it if it does not exist:

   import sqlite3
   con = sqlite3.connect("tutorial.db")

El retorno será un objecto de la clase "Connection" representado en
"con" como una base de datos local.

Con el fin de ejecutar sentencias SQL y obtener resultados de
consultas SQL, necesitaremos usar un cursor para la base de datos.
Llamando "con.cursor()" se creará el "Cursor":

   cur = con.cursor()

Ahora que hemos configurado una conexión y un cursor, podemos crear
una tabla "movie" con las columnas *title*, *release year*, y *review
score*. Para simplificar, podemos solamente usar nombres de columnas
en la declaración de la tabla -- gracias al recurso de flexible typing
SQLite, especificar los tipos de datos es opcional. Ejecuta la
sentencia "CREATE TABLE" llamando "cur.execute(...)":

   cur.execute("CREATE TABLE movie(title, year, score)")

Podemos verificar que una nueva tabla ha sido creada consultando la
tabla "sqlite_master" incorporada en SQLite, la cual ahora debería
contener una entrada para la tabla "movie" (consulte The Schema Table
para más información). Ejecute esa consulta llamando a
"cur.execute(...)", asigne el resultado a "res" y llame a
"res.fetchone()" para obtener la fila resultante:

   >>> res = cur.execute("SELECT name FROM sqlite_master")
   >>> res.fetchone()
   ('movie',)

We can see that the table has been created, as the query returns a
"tuple" containing the table's name. If we query "sqlite_master" for a
non-existent table "spam", "res.fetchone()" will return "None":

   >>> res = cur.execute("SELECT name FROM sqlite_master WHERE name='spam'")
   >>> res.fetchone() is None
   True

Ahora, agrega dos filas de datos proporcionados como SQL literales,
ejecutando la sentencia "INSERT", una vez más llamando a
"cur.execute(...)":

   cur.execute("""
       INSERT INTO movie VALUES
           ('Monty Python and the Holy Grail', 1975, 8.2),
           ('And Now for Something Completely Different', 1971, 7.5)
   """)

La sentencia "INSERT" implícitamente abre una transacción, la cual
necesita ser confirmada antes que los cambios sean guardados en la
base de datos (consulte Control transaccional para más información).
Llamando a "con.commit()" sobre el objeto de la conexión, se
confirmará la transacción:

   con.commit()

Podemos verificar que la información fue introducida correctamente
ejecutando la consulta "SELECT". Ejecute el ahora conocido
"cur.execute(...)" para asignar el resultado a "res", y luego llame a
"res.fetchall()" para obtener todas las filas como resultado:

   >>> res = cur.execute("SELECT score FROM movie")
   >>> res.fetchall()
   [(8.2,), (7.5,)]

El resultado es una "list" de dos "tuple"s, una por fila, cada una
conteniendo el valor del "score" de esa fila.

Ahora, introduzca tres filas más llamando "cur.executemany(...)":

   data = [
       ("Monty Python Live at the Hollywood Bowl", 1982, 7.9),
       ("Monty Python's The Meaning of Life", 1983, 7.5),
       ("Monty Python's Life of Brian", 1979, 8.0),
   ]
   cur.executemany("INSERT INTO movie VALUES(?, ?, ?)", data)
   con.commit()  # Remember to commit the transaction after executing INSERT.

Note que los marcadores de posición "?" son usados para enlazar "data"
a la consulta. SIempre use marcadores de posición en lugar de string
formatting para unir valores Python a sentencias SQL, y así evitará
SQL injection attacks (consulte Cómo usar marcadores de posición para
vincular valores en consultas SQL para más información).

Podemos verificar que las nuevas filas fueron introducidas ejecutando
una consulta "SELECT", esta vez iterando sobre los resultados de la
consulta:

   >>> for row in cur.execute("SELECT year, title FROM movie ORDER BY year"):
   ...     print(row)
   (1971, 'And Now for Something Completely Different')
   (1975, 'Monty Python and the Holy Grail')
   (1979, "Monty Python's Life of Brian")
   (1982, 'Monty Python Live at the Hollywood Bowl')
   (1983, "Monty Python's The Meaning of Life")

Cada fila es una "tuple" de dos items con "(year, title)", donde las
columnas seleccionadas coinciden con la consulta.

Finalmente, se puede verificar que la base de datos ha sido escrita en
disco, llamando "con.close()" para cerrar la conexión existente,
abriendo una nueva, creando un nuevo cursor y luego consultando la
base de datos:

   >>> con.close()
   >>> new_con = sqlite3.connect("tutorial.db")
   >>> new_cur = new_con.cursor()
   >>> res = new_cur.execute("SELECT title, year FROM movie ORDER BY score DESC")
   >>> title, year = res.fetchone()
   >>> print(f'The highest scoring Monty Python movie is {title!r}, released in {year}')
   The highest scoring Monty Python movie is 'Monty Python and the Holy Grail', released in 1975
   >>> new_con.close()

Ahora ha creado una base de datos SQLite usando el módulo "sqlite3",
insertado datos y recuperado valores de varias maneras.

Ver también:

  * Guías prácticas para lecturas de interés:

    * Cómo usar marcadores de posición para vincular valores en
      consultas SQL

    * Cómo adaptar tipos de Python personalizados a valores de SQLite

    * Como convertir valores SQLite a tipos de Python personalizados

    * Como usar la conexión con un administrador de contexto

    * How to create and use row factories

  * Explicación para obtener información detallada sobre el control de
    transacciones..


Referencia
==========


Funciones del módulo
--------------------

sqlite3.connect(database, timeout=5.0, detect_types=0, isolation_level='DEFERRED', check_same_thread=True, factory=sqlite3.Connection, cached_statements=128, uri=False, *, autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL)

   Abre una conexión con una base de datos SQLite.

   Parámetros:
      * **database** (*path-like object*) -- The path to the database
        file to be opened. You can pass "":memory:"" to create an
        SQLite database existing only in memory, and open a connection
        to it.

      * **timeout** (*float*) -- How many seconds the connection
        should wait before raising an "OperationalError" when a table
        is locked. If another connection opens a transaction to modify
        a table, that table will be locked until the transaction is
        committed. Default five seconds.

      * **detect_types** (*int*) -- Control whether and how data types
        not natively supported by SQLite are looked up to be converted
        to Python types, using the converters registered with
        "register_converter()". Set it to any combination (using "|",
        bitwise or) of "PARSE_DECLTYPES" and "PARSE_COLNAMES" to
        enable this. Column names takes precedence over declared types
        if both flags are set. By default ("0"), type detection is
        disabled.

      * **isolation_level** (*str** | **None*) -- Control legacy
        transaction handling behaviour. See
        "Connection.isolation_level" and Transaction control via the
        isolation_level attribute for more information. Can be
        ""DEFERRED"" (default), ""EXCLUSIVE"" or ""IMMEDIATE""; or
        "None" to disable opening transactions implicitly. Has no
        effect unless "Connection.autocommit" is set to
        "LEGACY_TRANSACTION_CONTROL" (the default).

      * **check_same_thread** (*bool*) -- If "True" (default),
        "ProgrammingError" will be raised if the database connection
        is used by a thread other than the one that created it. If
        "False", the connection may be accessed in multiple threads;
        write operations may need to be serialized by the user to
        avoid data corruption. See "threadsafety" for more
        information.

      * **factory** (*Connection*) -- Una subclase personalizada de
        "Connection" con la que crear la conexión, sino la
        "Connection" será la predeterminada.

      * **cached_statements** (*int*) -- El número de instrucciones
        que "sqlite3" debe almacenar internamente en caché para esta
        conexión, para evitar la sobrecarga de análisis. El valor
        predeterminada, son 128 instrucciones.

      * **uri** (*bool*) -- Si se establece en "True", *database* es
        interpretada como una URI (Uniform Resource Identifier) con la
        ruta de un archivo y una consulta de cadena de caracteres de
        modo opcional. La parte del esquema *debe* ser ""file:"", y la
        ruta puede ser relativa o absoluta. La consulta permite pasar
        parámetros a SQLite, habilitando varias Como trabajar con URIs
        SQLite.

      * **autocommit** (*bool*) -- Control **PEP 249** transaction
        handling behaviour. See "Connection.autocommit" and
        Transaction control via the autocommit attribute for more
        information. *autocommit* currently defaults to
        "LEGACY_TRANSACTION_CONTROL". The default will change to
        "False" in a future Python release.

   Tipo del valor devuelto:
      *Connection*

   Lanza un auditing event "sqlite3.connect" con el argumento
   "database".

   Lanza un auditing event "sqlite3.connect/handle" con el argumento
   "connection_handle".

   Distinto en la versión 3.4: Added the *uri* parameter.

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

   Distinto en la versión 3.10: Added the "sqlite3.connect/handle"
   auditing event.

   Distinto en la versión 3.12: Added the *autocommit* parameter.

sqlite3.complete_statement(statement)

   Retorna "True" si la cadena de caracteres *statement* pareciera
   contener uno o más sentencias SQL completas. No se realiza ninguna
   verificación o análisis sintáctico de ningún tipo, aparte de
   comprobar que no hay cadena de caracteres literales sin cerrar y
   que la sentencia se termine con un punto y coma.

   Por ejemplo:

      >>> sqlite3.complete_statement("SELECT foo FROM bar;")
      True
      >>> sqlite3.complete_statement("SELECT foo")
      False

   Esta función puede ser útil con entradas de línea de comando para
   determinar si los textos introducidos parecen formar una sentencia
   completa SQL, o si una entrada adicional se necesita antes de
   llamar a "execute()".

   See "runsource()" in Lib/sqlite3/__main__.py for real-world use.

sqlite3.enable_callback_tracebacks(flag, /)

   Habilita o deshabilita seguimiento de retrollamadas. Por defecto no
   se obtendrá ningún *tracebacks* en funciones *aggregates*,
   *converters*, autorizador de *callbacks* etc, definidas por el
   usuario. Si quieres depurarlas, se puede llamar esta función con
   *flag* establecida como "True". Después se obtendrán *tracebacks*
   de los *callbacks* en "sys.stderr". Usar "False" para deshabilitar
   la característica de nuevo.

   Nota:

     Errors in user-defined function callbacks are logged as
     unraisable exceptions. Use an "unraisable hook handler" for
     introspection of the failed callback.

sqlite3.register_adapter(type, adapter, /)

   Register an *adapter* *callable* to adapt the Python type *type*
   into an SQLite type. The adapter is called with a Python object of
   type *type* as its sole argument, and must return a value of a type
   that SQLite natively understands.

sqlite3.register_converter(typename, converter, /)

   Register the *converter* *callable* to convert SQLite objects of
   type *typename* into a Python object of a specific type. The
   converter is invoked for all SQLite values of type *typename*; it
   is passed a "bytes" object and should return an object of the
   desired Python type. Consult the parameter *detect_types* of
   "connect()" for information regarding how type detection works.

   Nota: *typename* y el nombre del tipo en tu consulta coinciden sin
   distinción entre mayúsculas y minúsculas.


Constantes del módulo
---------------------

sqlite3.LEGACY_TRANSACTION_CONTROL

   Set "autocommit" to this constant to select old style (pre-Python
   3.12) transaction control behaviour. See Transaction control via
   the isolation_level attribute for more information.

sqlite3.PARSE_DECLTYPES

   Pasa este valor de flag como parámetro *detect_types* de la
   "connect()" para buscar una función *converter* usando los tipos
   declarados para cada columna. Los tipos son declarados cuando la
   tabla de la base de datos se creó. "sqlite3" buscará una función
   *converter* usando la primera palabra del tipo declarado como la
   llave del diccionario conversor. Por ejemplo:

      CREATE TABLE test(
         i integer primary key,  ! will look up a converter named "integer"
         p point,                ! will look up a converter named "point"
         n number(10)            ! will look up a converter named "number"
       )

   Esta puede ser combinada con "PARSE_COLNAMES" usando el operador
   "|" (*bitwise or*).

   Nota:

     Generated fields (for example "MAX(p)") are returned as "str".
     Use "PARSE_COLNAMES" to enforce types for such queries.

sqlite3.PARSE_COLNAMES

   Pass this flag value to the *detect_types* parameter of "connect()"
   to look up a converter function by using the type name, parsed from
   the query column name, as the converter dictionary key. The query
   column name must be wrapped in double quotes (""") and the type
   name must be wrapped in square brackets ("[]").

      SELECT MAX(p) as "p [point]" FROM test;  ! will look up converter "point"

   Esta flag puede ser combinada con "PARSE_DECLTYPES" usando el
   operador "|" (*bitwise or*) .

sqlite3.SQLITE_OK
sqlite3.SQLITE_DENY
sqlite3.SQLITE_IGNORE

   Flags that should be returned by the *authorizer_callback*
   *callable* passed to "Connection.set_authorizer()", to indicate
   whether:

   * Acceso es permitido ("SQLITE_OK"),

   * La sentencia SQL debería ser abortada con un error
     ("SQLITE_DENY")

   * La columna debería ser tratada como un valor "NULL"
     ("SQLITE_IGNORE")

sqlite3.apilevel

   Cadena de caracteres constante que indica el nivel DB-API
   soportado. Requerido por DB-API. Codificado de forma rígida en
   ""2.0"".

sqlite3.paramstyle

   Cadena de caracteres que indica el tipo de formato del marcador de
   parámetros esperado por el módulo "sqlite3". Requerido por DB-API.
   Codificado de forma rígida en ""qmark"".

   Nota:

     The "named" DB-API parameter style is also supported.

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

   Constante de tipo entero requerida por la DB-API 2.0, la cual
   indica el nivel de seguridad de subproceso que "sqlite3" soporta.
   Este atributo se establece basándose en el modo de subprocesamiento
   por defecto con el que la biblioteca SQLite se compila. Los modos
   de subprocesamiento de SQLite son:

   1. **Single-thread**: En este modo, todos los *mutexes* son
      deshabilitados y no es seguro usar SQLite en más de un solo hilo
      a la vez.

   2. **Multi-thread**: En este modo, es seguro usar SQLite desde
      varios hilos dado que que ninguna conexión de base de datos sea
      usada simultáneamente en dos o más hilos.

   3. **Serialized**: En el modo serializado, es seguro usar SQLite
      por varios hilos sin restricción.

   Las asignaciones de los modos de subprocesos SQLite a los niveles
   de seguridad de subprocesos de DB-API 2.0 son las siguientes:

   +--------------------+------------------------+------------------------+---------------------------------+
   | Modo de            | **threadsafety**       | SQLITE_THREADSAFE      | Significado de DB-API 2.0       |
   | subprocesamiento   |                        |                        |                                 |
   | SQLite             |                        |                        |                                 |
   |====================|========================|========================|=================================|
   | single-thread      | 0                      | 0                      | Hilos no pueden compartir el    |
   |                    |                        |                        | módulo                          |
   +--------------------+------------------------+------------------------+---------------------------------+
   | multi-thread       | 1                      | 2                      | Hilos pueden compartir el       |
   |                    |                        |                        | módulo, pero no conexiones      |
   +--------------------+------------------------+------------------------+---------------------------------+
   | serialized         | 3                      | 1                      | Hilos pueden compartir el       |
   |                    |                        |                        | módulo, conexiones y cursores   |
   +--------------------+------------------------+------------------------+---------------------------------+

   Distinto en la versión 3.11: Establece *threadsafety* dinámicamente
   en vez de codificarlo rígidamente a "1".

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.

   Deprecated since version 3.12, will be removed in version 3.14:
   This constant used to reflect the version number of the "pysqlite"
   package, a third-party library which used to upstream changes to
   "sqlite3". Today, it carries no meaning or practical value.

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.

   Deprecated since version 3.12, will be removed in version 3.14:
   This constant used to reflect the version number of the "pysqlite"
   package, a third-party library which used to upstream changes to
   "sqlite3". Today, it carries no meaning or practical value.

sqlite3.SQLITE_DBCONFIG_DEFENSIVE
sqlite3.SQLITE_DBCONFIG_DQS_DDL
sqlite3.SQLITE_DBCONFIG_DQS_DML
sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY
sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER
sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION
sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG
sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER
sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW
sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE
sqlite3.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT
sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE
sqlite3.SQLITE_DBCONFIG_RESET_DATABASE
sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP
sqlite3.SQLITE_DBCONFIG_TRUSTED_SCHEMA
sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA

   These constants are used for the "Connection.setconfig()" and
   "getconfig()" methods.

   The availability of these constants varies depending on the version
   of SQLite Python was compiled with.

   Added in version 3.12.

   Ver también:

     https://www.sqlite.org/c3ref/c_dbconfig_defensive.html
        SQLite docs: Database Connection Configuration Options


Objetos de conexión
-------------------

class sqlite3.Connection

   Cada base de datos SQLite abierta es representada por un objeto
   "Connection", el cual se crea usando "sqlite3.connect()". Su
   objetivo principal es crear objetos "Cursor", y Control
   transaccional.

   Ver también:

     * Cómo utilizar los métodos de acceso directo de conexión

     * Como usar la conexión con un administrador de contexto

   Una conexión a una base de datos SQLite tiene los siguientes
   atributos y métodos:

   cursor(factory=Cursor)

      Create and return a "Cursor" object. The cursor method accepts a
      single optional parameter *factory*. If supplied, this must be a
      *callable* returning an instance of "Cursor" or its subclasses.

   blobopen(table, column, row, /, *, readonly=False, name='main')

      Abre una "Blob" para manejar un BLOB (Binary Large OBject)
      existente.

      Parámetros:
         * **table** (*str*) -- El nombre de la tabla donde el *blob*
           está ubicado.

         * **column** (*str*) -- El nombre de la columna donde el
           *blob* está ubicado.

         * **row** (*str*) -- El nombre de la fila donde el *blob*
           está ubicado.

         * **readonly** (*bool*) -- Se define como "True" si el *blob*
           deberá ser abierto sin permisos de escritura. El valor por
           defecto es "False".

         * **name** (*str*) -- El nombre de la base de datos donde el
           *blob* está ubicado. El valor por defecto es ""main"".

      Muestra:
         **OperationalError** -- Cuando se intenta abrir un *blob* en
         una tabla "WITHOUT ROWID".

      Tipo del valor devuelto:
         Blob

      Nota:

        El tamaño de un *blob* no puede ser cambiado usando la clase
        "Blob". Usa la función de SQL "zeroblob" para crear un *blob*
        con un tamaño fijo.

      Added in version 3.11.

   commit()

      Commit any pending transaction to the database. If "autocommit"
      is "True", or there is no open transaction, this method does
      nothing. If "autocommit" is "False", a new transaction is
      implicitly opened if a pending transaction was committed by this
      method.

   rollback()

      Roll back to the start of any pending transaction. If
      "autocommit" is "True", or there is no open transaction, this
      method does nothing. If "autocommit" is "False", a new
      transaction is implicitly opened if a pending transaction was
      rolled back by this method.

   close()

      Close the database connection. If "autocommit" is "False", any
      pending transaction is implicitly rolled back. If "autocommit"
      is "True" or "LEGACY_TRANSACTION_CONTROL", no implicit
      transaction control is executed. Make sure to "commit()" before
      closing to avoid losing pending changes.

   execute(sql, parameters=(), /)

      Crea un nuevo objeto "Cursor" y llama "execute()" con los
      parámetros y el SQL dados. Retorna el nuevo objeto cursor.

   executemany(sql, parameters, /)

      Crea una nueva "Cursor" object and call "executemany()" con los
      parámetros y el SQL dados. Retorna el nuevo objeto cursor.

   executescript(sql_script, /)

      Crea una nueva "Cursor" object and call "executescript()" con el
      *sql_script* dado. Retorna el nuevo objeto cursor.

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

      Crea o elimina una función SQL definida por el usuario.

      Parámetros:
         * **name** (*str*) -- El nombre de la función SQL.

         * **narg** (*int*) -- El número de argumentos que la función
           SQL puede aceptar. Si es "-1", podrá entonces recibir
           cualquier cantidad de argumentos.

         * **func** (*callback* | None) -- A *callable* that is called
           when the SQL function is invoked. The callable must return
           a type natively supported by SQLite. Set to "None" to
           remove an existing SQL function.

         * **deterministic** (*bool*) -- Si se establece "True", la
           función SQL creada se marcará como determinista, lo cual
           permite a SQLite realizar optimizaciones adicionales.

      Muestra:
         **NotSupportedError** -- Si *deterministic* se usa con
         versiones anteriores a SQLite 3.8.3.

      Distinto en la versión 3.8: Added the *deterministic* parameter.

      Ejemplo:

         >>> import hashlib
         >>> def md5sum(t):
         ...     return hashlib.md5(t).hexdigest()
         >>> con = sqlite3.connect(":memory:")
         >>> con.create_function("md5", 1, md5sum)
         >>> for row in con.execute("SELECT md5(?)", (b"foo",)):
         ...     print(row)
         ('acbd18db4cc2f85cedef654fccc4a4d8',)
         >>> con.close()

   create_aggregate(name, n_arg, aggregate_class)

      Crea o elimina una función agregada SQL definida por el usuario.

      Parámetros:
         * **name** (*str*) -- El nombre de la función agregada SQL.

         * **n_arg** (*int*) -- El número de argumentos que la función
           agregada SQL puede aceptar. Si es "-1", podrá entonces
           recibir cualquier cantidad de argumentos.

         * **aggregate_class** (*class* | None) -- Una clase debe
           implementar los siguientes métodos: * "step()": Adiciona
           una fila al *aggregate*. * "finalize()": Retorna el
           resultado final del *aggregate* como un tipo soportado
           nativamente por SQLite. La cantidad de argumentos que el
           método "step()" puede aceptar, es controlado por *n_arg*.
           Establece "None" para eliminar una función agregada SQL
           existente.

      Ejemplo:

         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.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_window_function(name, num_params, aggregate_class, /)

      Crea o elimina una función agregada de ventana definida por el
      usuario.

      Parámetros:
         * **name** (*str*) -- El nombre de la función agregada de
           ventana a ser creada o eliminada.

         * **num_params** (*int*) -- La cantidad de argumentos que la
           función agregada de ventana SQL acepta. Si es "-1", podrá
           entonces recibir cualquier cantidad de argumentos.

         * **aggregate_class** (*class* | None) -- Una clase debe
           implementar los siguientes métodos:  * "step()": Agrega una
           fila a la ventana actual. * "value()": Retorna el valor
           actual del *aggregate* . * "inverse()": Elimina una fila de
           la ventana actual. * "finalize()": Retorna el resultado
           final del *aggregate* como una un tipo soportado
           nativamente por SQLite. La cantidad de argumentos que los
           métodos "step()" y "value()" pueden aceptar son controlados
           por *num_params*. Establece "None" para eliminar una
           función agregada de ventana SQL.

      Muestra:
         **NotSupportedError** -- Si es usado con una versión de
         SQLite inferior a 3.25.0, la cual no soporte funciones
         agregadas de ventana.

      Added in version 3.11.

      Ejemplo:

         # Example taken from https://www.sqlite.org/windowfunctions.html#udfwinfunc
         class WindowSumInt:
             def __init__(self):
                 self.count = 0

             def step(self, value):
                 """Add a row to the current window."""
                 self.count += value

             def value(self):
                 """Return the current value of the aggregate."""
                 return self.count

             def inverse(self, value):
                 """Remove a row from the current window."""
                 self.count -= value

             def finalize(self):
                 """Return the final value of the aggregate.

                 Any clean-up actions should be placed here.
                 """
                 return self.count


         con = sqlite3.connect(":memory:")
         cur = con.execute("CREATE TABLE test(x, y)")
         values = [
             ("a", 4),
             ("b", 5),
             ("c", 3),
             ("d", 8),
             ("e", 1),
         ]
         cur.executemany("INSERT INTO test VALUES(?, ?)", values)
         con.create_window_function("sumint", 1, WindowSumInt)
         cur.execute("""
             SELECT x, sumint(y) OVER (
                 ORDER BY x ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING
             ) AS sum_y
             FROM test ORDER BY x
         """)
         print(cur.fetchall())
         con.close()

   create_collation(name, callable, /)

      Crea una colación nombrada *name* usando la función *collating*
      *callable*. A *callable* se le pasan dos argumentos "string", y
      este debería retornar un "entero":

      * "1" si el primero es ordenado más alto que el segundo

      * "-1" si el primero es ordenado más pequeño que el segundo

      * "0" si están ordenados de manera igual

      El siguiente ejemplo muestra una ordenación de colación inversa:

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

      Elimina una función de colación al establecer el *callable* como
      "None".

      Distinto en la versión 3.11: El nombre de la colación puede
      contener cualquier caracter Unicode. Anteriormente, solamente
      caracteres ASCII eran permitidos.

   interrupt()

      Call this method from a different thread to abort any queries
      that might be executing on the connection. Aborted queries will
      raise an "OperationalError".

   set_authorizer(authorizer_callback)

      Register *callable* *authorizer_callback* to be invoked for each
      attempt to access a column of a table in the database. The
      callback should return one of "SQLITE_OK", "SQLITE_DENY", or
      "SQLITE_IGNORE" to signal how access to the column should be
      handled by the underlying SQLite library.

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

      Pasando "None" como *authorizer_callback* deshabilitará el
      autorizador.

      Distinto en la versión 3.11: Agregado soporte para deshabilitar
      el autorizador usando "None".

   set_progress_handler(progress_handler, n)

      Register *callable* *progress_handler* to be invoked for every
      *n* instructions of the SQLite virtual machine. This is useful
      if you want to get called from SQLite during long-running
      operations, for example to update a GUI.

      Si se desea limpiar cualquier *progress_handler* instalado
      anteriormente, llame el método con "None" para
      *progress_handler*.

      Returning a non-zero value from the handler function will
      terminate the currently executing query and cause it to raise a
      "DatabaseError" exception.

   set_trace_callback(trace_callback)

      Register *callable* *trace_callback* to be invoked for each SQL
      statement that is actually executed by the SQLite backend.

      El único argumento pasado a la retrollamada es la declaración
      (como "str") que se está ejecutando. El valor de retorno de la
      retrollamada es ignorado. Tenga en cuenta que el backend no solo
      ejecuta declaraciones pasadas a los métodos "Cursor.execute()".
      Otras fuentes incluyen el transaction management del módulo
      "sqlite3" y la ejecución de disparadores definidos en la base de
      datos actual.

      Pasando "None" como *trace_callback* deshabilitará el *trace
      callback*.

      Nota:

        Las excepciones que se producen en la llamada de retorno no se
        propagan. Como ayuda para el desarrollo y la depuración,
        utilice "enable_callback_tracebacks()" para habilitar la
        impresión de *tracebacks* de las excepciones que se producen
        en la llamada de retorno.

      Added in version 3.3.

   enable_load_extension(enabled, /)

      Habilita el motor de SQLite para cargar extensiones SQLite de
      bibliotecas compartidas si *enabled* se establece como "True";
      sino deshabilitará la carga de extensiones SQLite. Las
      extensiones SQLite pueden definir implementaciones de nuevas
      funciones, agregaciones, o tablas virtuales enteras. Una
      extensión bien conocida es *fulltext-search* distribuida con
      SQLite.

      Nota:

        El módulo "sqlite3" no está construido con soporte de
        extensión cargable de forma predeterminada, porque algunas
        plataformas (especialmente macOS) tienen bibliotecas SQLite
        que se compilan sin esta función. Para obtener soporte para
        extensiones cargables, debe pasar la opción "--enable-
        loadable-sqlite-extensions" a **configure**.

      Lanza un auditing event "sqlite3.enable_load_extension" con los
      argumentos "connection", "enabled".

      Added in version 3.2.

      Distinto en la versión 3.10: Agregado el evento de auditoría
      "sqlite3.enable_load_extension".

         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)

   load_extension(path, /, *, entrypoint=None)

      Load an SQLite extension from a shared library. Enable extension
      loading with "enable_load_extension()" before calling this
      method.

      Parámetros:
         * **path** (*str*) -- The path to the SQLite extension.

         * **entrypoint** (*str** | **None*) -- Entry point name. If
           "None" (the default), SQLite will come up with an entry
           point name of its own; see the SQLite docs Loading an
           Extension for details.

      Lanza un auditing event "sqlite3.load_extension" con argumentos
      "connection", "path".

      Added in version 3.2.

      Distinto en la versión 3.10: Agregado el evento de auditoría
      "sqlite3.load_extension".

      Distinto en la versión 3.12: Added the *entrypoint* parameter.

   iterdump()

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

      Ejemplo:

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

      Ver también: How to handle non-UTF-8 text encodings

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

      Crea una copia de seguridad de la base de datos SQLite.

      Funciona incluso si la base de datos está siendo accedida por
      otros clientes al mismo tiempo sobre la misma conexión.

      Parámetros:
         * **target** (*Connection*) -- La conexión de la base de
           datos para guardar la copia de seguridad.

         * **pages** (*int*) -- Cantidad de páginas que serán copiadas
           cada vez. Si es menor o igual a "0", toda la base de datos
           será copiada en un solo paso. El valor por defecto es "-1".

         * **progress** (*callback* | None) -- If set to a *callable*,
           it is invoked with three integer arguments for every backup
           iteration: the *status* of the last iteration, the
           *remaining* number of pages still to be copied, and the
           *total* number of pages. Defaults to "None".

         * **name** (*str*) -- El nombre de la base de datos a ser
           guardada. O bien sea ""main"" (valor por defecto) para la
           base de datos *main*, ""temp"" para la base de datos
           temporal, o el nombre de una base de datos personalizada
           adjuntada usando la sentencia "ATTACH DATABASE".

         * **sleep** (*float*) -- Número de segundos a dormir entre
           sucesivos intentos para respaldar páginas restantes.

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

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

         src = sqlite3.connect('example.db')
         dst = sqlite3.connect('backup.db')
         with dst:
             src.backup(dst, pages=1, progress=progress)
         dst.close()
         src.close()

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

         src = sqlite3.connect('example.db')
         dst = sqlite3.connect(':memory:')
         src.backup(dst)
         dst.close()
         src.close()

      Added in version 3.7.

      Ver también: How to handle non-UTF-8 text encodings

   getlimit(category, /)

      Obtiene el límite de tiempo de ejecución de una conexión.

      Parámetros:
         **category** (*int*) -- La SQLite limit category a ser
         consultada.

      Tipo del valor devuelto:
         int

      Muestra:
         **ProgrammingError** -- Si *category* no se reconoce por las
         capas inferiores de la biblioteca SQLite.

      Ejemplo, consulta el tamaño máximo de una sentencia SQL para la
      "Connection" "con" (el valor por defecto es 1000000000):

         >>> con.getlimit(sqlite3.SQLITE_LIMIT_SQL_LENGTH)
         1000000000

      Added in version 3.11.

   setlimit(category, limit, /)

      Set a connection runtime limit. Attempts to increase a limit
      above its hard upper bound are silently truncated to the hard
      upper bound. Regardless of whether or not the limit was changed,
      the prior value of the limit is returned.

      Parámetros:
         * **category** (*int*) -- La SQLite limit category a ser
           establecido.

         * **limit** (*int*) -- El valor del nuevo límite. Si es
           negativo, el límite actual no cambia.

      Tipo del valor devuelto:
         int

      Muestra:
         **ProgrammingError** -- Si *category* no se reconoce por las
         capas inferiores de la biblioteca SQLite.

      Por ejemplo, limite el número de bases de datos adjuntas a 1
      para la "Connection" "con" (el valor por defecto es 10):

         >>> con.setlimit(sqlite3.SQLITE_LIMIT_ATTACHED, 1)
         10
         >>> con.getlimit(sqlite3.SQLITE_LIMIT_ATTACHED)
         1

      Added in version 3.11.

   getconfig(op, /)

      Query a boolean connection configuration option.

      Parámetros:
         **op** (*int*) -- A SQLITE_DBCONFIG code.

      Tipo del valor devuelto:
         bool

      Added in version 3.12.

   setconfig(op, enable=True, /)

      Set a boolean connection configuration option.

      Parámetros:
         * **op** (*int*) -- A SQLITE_DBCONFIG code.

         * **enable** (*bool*) -- "True" if the configuration option
           should be enabled (default); "False" if it should be
           disabled.

      Added in version 3.12.

   serialize(*, name='main')

      Serializa la base de datos en un objeto "bytes". Para un archivo
      ordinario de base de datos en disco, la serialización es solo
      una copia del archivo de disco. Para el caso de una base de
      datos en memoria o una base de datos "temp", la serialización es
      la misma secuencia de bytes que se escribiría en el disco si se
      hiciera una copia de seguridad de esa base de datos en el disco.

      Parámetros:
         **name** (*str*) -- El nombre de la base de datos a ser
         serializada. El valor por defecto es ""main"".

      Tipo del valor devuelto:
         bytes

      Nota:

        Este método solo está disponible si las capas internas de la
        biblioteca SQLite tienen la API *serialise*.

      Added in version 3.11.

   deserialize(data, /, *, name='main')

      Deserializa una base de datos "serializsda" en una clase
      "Connection". Este método hace que la conexión de base de datos
      se desconecte de la base de datos *name*, y la abre nuevamente
      como una base de datos en memoria, basada en la serialización
      contenida en *data*.

      Parámetros:
         * **data** (*bytes*) -- Una base de datos serializada.

         * **name** (*str*) -- El nombre de la base de datos a ser
           deserializada. El valor por defecto es ""main"".

      Muestra:
         * **OperationalError** -- Si la conexión con la base de datos
           está actualmente involucrada en una transacción de lectura
           o una operación de copia de seguridad.

         * **DatabaseError** -- Si *data* no contiene una base de
           datos SQLite válida.

         * **OverflowError** -- Si "len(data)" es más grande que
           "2**63 - 1".

      Nota:

        Este método solo está disponible si las capas internas de la
        biblioteca SQLite tienen la API *deserialize*.

      Added in version 3.11.

   autocommit

      This attribute controls **PEP 249**-compliant transaction
      behaviour. "autocommit" has three allowed values:

      * "False": Select **PEP 249**-compliant transaction behaviour,
        implying that "sqlite3" ensures a transaction is always open.
        Use "commit()" and "rollback()" to close transactions.

        This is the recommended value of "autocommit".

      * "True": Use SQLite's autocommit mode. "commit()" and
        "rollback()" have no effect in this mode.

      * "LEGACY_TRANSACTION_CONTROL": Pre-Python 3.12 (non-**PEP
        249**-compliant) transaction control. See "isolation_level"
        for more details.

        This is currently the default value of "autocommit".

      Changing "autocommit" to "False" will open a new transaction,
      and changing it to "True" will commit any pending transaction.

      See Transaction control via the autocommit attribute for more
      details.

      Nota:

        The "isolation_level" attribute has no effect unless
        "autocommit" is "LEGACY_TRANSACTION_CONTROL".

      Added in version 3.12.

   in_transaction

      Este atributo de solo lectura corresponde al autocommit mode de
      SQLite de bajo nivel.

      "True" si una transacción está activa (existen cambios sin
      confirmar),``False`` en caso contrario.

      Added in version 3.2.

   isolation_level

      Controls the legacy transaction handling mode of "sqlite3". If
      set to "None", transactions are never implicitly opened. If set
      to one of ""DEFERRED"", ""IMMEDIATE"", or ""EXCLUSIVE"",
      corresponding to the underlying SQLite transaction behaviour,
      implicit transaction management is performed.

      Si no se sobreescribe por el parámetro *isolation_level* de
      "connect()", el valor predeterminado es """", que es un alias
      para ""DEFERRED"".

      Nota:

        Using "autocommit" to control transaction handling is
        recommended over using "isolation_level". "isolation_level"
        has no effect unless "autocommit" is set to
        "LEGACY_TRANSACTION_CONTROL" (the default).

   row_factory

      The initial "row_factory" for "Cursor" objects created from this
      connection. Assigning to this attribute does not affect the
      "row_factory" of existing cursors belonging to this connection,
      only new ones. Is "None" by default, meaning each row is
      returned as a "tuple".

      See How to create and use row factories for more details.

   text_factory

      A *callable* that accepts a "bytes" parameter and returns a text
      representation of it. The callable is invoked for SQLite values
      with the "TEXT" data type. By default, this attribute is set to
      "str".

      See How to handle non-UTF-8 text encodings for more details.

   total_changes

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


Objetos cursor
--------------

   Un objeto "Cursor" representa un database cursor que se utiliza
   para ejecutar sentencias SQL y administrar el contexto de una
   operación de búsqueda. Los cursores son creados usando
   "Connection.cursor()", o por usar alguno de los connection shortcut
   methods.

   Los objetos cursores son *iterators*, lo que significa que si
   "execute()" una consulta "SELECT", simplemente podrás iterar sobre
   el cursor para obtener las filas resultantes:

      for row in cur.execute("SELECT t FROM data"):
          print(row)

class sqlite3.Cursor

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

   execute(sql, parameters=(), /)

      Execute a single SQL statement, optionally binding Python values
      using placeholders.

      Parámetros:
         * **sql** (*str*) -- A single SQL statement.

         * **parameters** ("dict" | *sequence*) -- Python values to
           bind to placeholders in *sql*. A "dict" if named
           placeholders are used. A *sequence* if unnamed placeholders
           are used. See Cómo usar marcadores de posición para
           vincular valores en consultas SQL.

      Muestra:
         **ProgrammingError** -- If *sql* contains more than one SQL
         statement.

      If "autocommit" is "LEGACY_TRANSACTION_CONTROL",
      "isolation_level" is not "None", *sql* is an "INSERT", "UPDATE",
      "DELETE", or "REPLACE" statement, and there is no open
      transaction, a transaction is implicitly opened before executing
      *sql*.

      Deprecated since version 3.12, will be removed in version 3.14:
      "DeprecationWarning" is emitted if named placeholders are used
      and *parameters* is a sequence instead of a "dict". Starting
      with Python 3.14, "ProgrammingError" will be raised instead.

      Use "executescript()" to execute multiple SQL statements.

   executemany(sql, parameters, /)

      For every item in *parameters*, repeatedly execute the
      parameterized DML (Data Manipulation Language) SQL statement
      *sql*.

      Uses the same implicit transaction handling as "execute()".

      Parámetros:
         * **sql** (*str*) -- A single SQL DML statement.

         * **parameters** (*iterable*) -- An *iterable* of parameters
           to bind with the placeholders in *sql*. See Cómo usar
           marcadores de posición para vincular valores en consultas
           SQL.

      Muestra:
         **ProgrammingError** -- If *sql* contains more than one SQL
         statement, or is not a DML statement.

      Ejemplo:

         rows = [
             ("row1",),
             ("row2",),
         ]
         # cur is an sqlite3.Cursor object
         cur.executemany("INSERT INTO data VALUES(?)", rows)

      Nota:

        Any resulting rows are discarded, including DML statements
        with RETURNING clauses.

      Deprecated since version 3.12, will be removed in version 3.14:
      "DeprecationWarning" is emitted if named placeholders are used
      and the items in *parameters* are sequences instead of "dict"s.
      Starting with Python 3.14, "ProgrammingError" will be raised
      instead.

   executescript(sql_script, /)

      Execute the SQL statements in *sql_script*. If the "autocommit"
      is "LEGACY_TRANSACTION_CONTROL" and there is a pending
      transaction, an implicit "COMMIT" statement is executed first.
      No other implicit transaction control is performed; any
      transaction control must be added to *sql_script*.

      *sql_script* debe ser una instancia de "string".

      Ejemplo:

         # cur is an sqlite3.Cursor object
         cur.executescript("""
             BEGIN;
             CREATE TABLE person(firstname, lastname, age);
             CREATE TABLE book(title, author, published);
             CREATE TABLE publisher(name, address);
             COMMIT;
         """)

   fetchone()

      If "row_factory" is "None", return the next row query result set
      as a "tuple". Else, pass it to the row factory and return its
      result. Return "None" if no more data is available.

   fetchmany(size=cursor.arraysize)

      Retorna el siguiente conjunto de filas del resultado de una
      consulta como una "list". Una lista vacía será retornada cuando
      no hay más filas disponibles.

      El número de filas que se van a obtener por llamada se
      especifica mediante el parámetro *size*. Si *size* no es
      informado, entonces "arraysize" determinará el número de filas
      que se van a recuperar. Si hay menos filas *size* disponibles,
      se retornan tantas filas como estén disponibles.

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

      Retorna todas las filas (restantes) de un resultado de consulta
      como "list". Retorna una lista vacía si no hay filas
      disponibles. Tenga en cuenta que el atributo "arraysize" puede
      afectar al rendimiento de esta operación.

   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, /)

      Requerido por la DB-API. No hace nada en "sqlite3".

   setoutputsize(size, column=None, /)

      Requerido por la DB-API. No hace nada en "sqlite3".

   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.

   connection

      Este atributo de solo lectura que provee la "Connection" de la
      base de datos SQLite pertenece al cursor. Un objeto "Cursor"
      creado llamando a "con.cursor()" tendrá un atributo "connection"
      que hace referencia a *con*:

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

   description

      Este atributo de solo lectura provee el nombre de las columnas
      de la última consulta. Para seguir siendo compatible con la API
      de base de datos de Python, retornará una tupla de 7 elementos
      para cada columna donde los últimos seis elementos de cada tupla
      son "Ninguno".

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

   lastrowid

      Atributo de solo lectura que proporciona el identificador de
      fila de la última insertada. Solo se actualiza después de que
      las sentencias "INSERT" o "REPLACE" hayan sido exitosas usando
      el método "execute()". Para otras instrucciones, después de
      "executemany()" o "executescript()", o si se produjo un error en
      la inserción, el valor de "lastrowid" se deja sin cambios. El
      valor inicial de "lastrowid" es "None".

      Nota:

        Las inserciones en tablas "WITHOUT ROWID" no se registran.

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

   rowcount

      Read-only attribute that provides the number of modified rows
      for "INSERT", "UPDATE", "DELETE", and "REPLACE" statements; is
      "-1" for other statements, including CTE (Common Table
      Expression) queries. It is only updated by the "execute()" and
      "executemany()" methods, after the statement has run to
      completion. This means that any resulting rows must be fetched
      in order for "rowcount" to be updated.

   row_factory

      Control how a row fetched from this "Cursor" is represented. If
      "None", a row is represented as a "tuple". Can be set to the
      included "sqlite3.Row"; or a *callable* that accepts two
      arguments, a "Cursor" object and the "tuple" of row values, and
      returns a custom object representing an SQLite row.

      Defaults to what "Connection.row_factory" was set to when the
      "Cursor" was created. Assigning to this attribute does not
      affect "Connection.row_factory" of the parent connection.

      See How to create and use row factories for more details.


Objetos fila (*Row*)
--------------------

class sqlite3.Row

   Una instancia de "Row" sirve como una instancia "row_factory"
   altamente optimizada para objetos "Connection". Admite iteración,
   pruebas de igualdad, acceso a "len()" y *mapping* por nombre de
   columna e índice.

   Two "Row" objects compare equal if they have identical column names
   and values.

   See How to create and use row factories for more details.

   keys()

      Este método retorna una "list" con los nombre de columnas como
      "strings". 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 para segmentación.


Objetos fila (*Row*)
--------------------

class sqlite3.Blob

   Added in version 3.11.

   Una instancia "Blob" es un *file-like object* que puede leer y
   escribir datos en un SQLite BLOB (Binary Large OBject). Llame a
   "len(blob)" para obtener el tamaño (número de bytes) del blob. Use
   índices y *slices* para obtener acceso directo a los datos del
   blob.

   Use "Blob" como *context manager* para asegurarse de que el
   identificador de blob se cierra después de su uso.

      con = sqlite3.connect(":memory:")
      con.execute("CREATE TABLE test(blob_col blob)")
      con.execute("INSERT INTO test(blob_col) VALUES(zeroblob(13))")

      # Write to our blob, using two write operations:
      with con.blobopen("test", "blob_col", 1) as blob:
          blob.write(b"hello, ")
          blob.write(b"world.")
          # Modify the first and last bytes of our blob
          blob[0] = ord("H")
          blob[-1] = ord("!")

      # Read the contents of our blob
      with con.blobopen("test", "blob_col", 1) as blob:
          greeting = blob.read()

      print(greeting)  # outputs "b'Hello, world!'"
      con.close()

   close()

      Cierra el *blob*.

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

   read(length=-1, /)

      Leer bytes *length* de datos del blob en la posición de
      desplazamiento actual. Si se alcanza el final del blob, se
      devolverán los datos hasta EOF (End of File). Cuando *length* no
      se especifica, o es negativo, "read()" se leerá hasta el final
      del blob.

   write(data, /)

      Escriba *data* en el blob en el desplazamiento actual. Esta
      función no puede cambiar la longitud del blob. Escribir más allá
      del final del blob generará un "ValueError".

   tell()

      Devolver la posición de acceso actual del blob.

   seek(offset, origin=os.SEEK_SET, /)

      Set the current access position of the blob to *offset*.  The
      *origin* argument defaults to "os.SEEK_SET" (absolute blob
      positioning). Other values for *origin* are "os.SEEK_CUR" (seek
      relative to the current position) and "os.SEEK_END" (seek
      relative to the blob’s end).


Objetos PrepareProtocol
-----------------------

class sqlite3.PrepareProtocol

   El único propósito del tipo *PrepareProtocol* es actuar como un
   protocolo de adaptación de estilo **PEP 246** para objetos que
   pueden adapt themselves a native SQLite types.


Excepciones
-----------

La jerarquía de excepciones está definida por DB-API 2.0 (**PEP
249**).

exception sqlite3.Warning

   Esta excepción no se genera actualmente en el módulo "sqlite3",
   pero puede ser provocada por aplicaciones que usan :mod:!sqlite3`,
   por ejemplo, si una función definida por el usuario trunca datos
   durante la inserción. "Warning" es una subclase de "Exception".

exception sqlite3.Error

   La clase base de las otras excepciones de este módulo. Use esto
   para detectar todos los errores con una sola instrucción
   "except".``Error`` is una subclase de "Exception".

   Si la excepción se originó dentro de la biblioteca SQLite, se
   agregan los siguientes dos atributos a la excepción:

   sqlite_errorcode

      El código de error numérico de SQLite API

      Added in version 3.11.

   sqlite_errorname

      El nombre simbólico del código de error numérico de SQLite API

      Added in version 3.11.

exception sqlite3.InterfaceError

   Excepción lanzada por el uso indebido de la API de SQLite C de bajo
   nivel. En otras palabras, si se lanza esta excepción, probablemente
   indica un error en el módulo "sqlite3". "InterfaceError" es una
   subclase de "Error".

exception sqlite3.DatabaseError

   Excepción lanzada por errores relacionados con la base de datos.
   Esto sirve como excepción base para varios tipos de errores de base
   de datos. Solo se genera implícitamente a través de las subclases
   especializadas. "DatabaseError" es una subclase de "Error".

exception sqlite3.DataError

   Excepción lanzada por errores causados por problemas con los datos
   procesados, como valores numéricos fuera de rango y cadenas de
   caracteres demasiado largas. "DataError" es una subclase de
   "DatabaseError".

exception sqlite3.OperationalError

   Excepción lanzada por errores que están relacionados con el
   funcionamiento de la base de datos y no necesariamente bajo el
   control del programador. Por ejemplo, no se encuentra la ruta de la
   base de datos o no se pudo procesar una transacción.
   "OperationalError" es una subclase de "DatabaseError".

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

   Se genera una excepción cuando SQLite encuentra un error interno.
   Si se genera esto, puede indicar que hay un problema con la
   biblioteca SQLite en tiempo de ejecución. "InternalError" es una
   subclase de "DatabaseError".

exception sqlite3.ProgrammingError

   Excepción lanzada por errores de programación de la API de
   "sqlite3", por ejemplo, proporcionar el número incorrecto de
   enlaces a una consulta, o intentar operar en una "Connection"
   cerrada. "ProgrammingError" es una subclase de "DatabaseError".

exception sqlite3.NotSupportedError

   Excepción lanzada en caso que la biblioteca SQLite subyacente no
   admita un método o una API de base de datos. Por ejemplo,
   establecer *determinista* como "Verdadero" en "create_function()",
   si la biblioteca SQLite subyacente no admite funciones
   *deterministic*. "NotSupportedError" es una subclase de
   "DatabaseError".


SQLite y tipos de Python
------------------------

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

El sistema de tipos del módulo "sqlite3" es extensible en dos formas:
se puede almacenar tipos de Python adicionales en una base de datos
SQLite vía a objetos adaptadores, y se puede permitir que "sqlite3"
convierta tipos SQLite a diferentes tipos de Python vía converters.


Default adapters and converters (deprecated)
--------------------------------------------

Nota:

  The default adapters and converters are deprecated as of Python
  3.12. Instead, use the Ejemplos para adaptadores y convertidores and
  tailor them to your needs.

The deprecated default adapters and converters consist of:

* An adapter for "datetime.date" objects to "strings" in ISO 8601
  format.

* An adapter for "datetime.datetime" objects to strings in ISO 8601
  format.

* A converter for declared "date" types to "datetime.date" objects.

* A converter for declared "timestamp" types to "datetime.datetime"
  objects. Fractional parts will be truncated to 6 digits (microsecond
  precision).

Nota:

  El convertidor por defecto "timestamp" ignora las compensaciones UTC
  en la base de datos y siempre devuelve un objeto "datetime.datetime"
  *naive*. Para conservar las compensaciones UTC en las marcas de
  tiempo, deje los convertidores deshabilitados o registre un
  convertidor que reconozca la compensación con
  "register_converter()".

Obsoleto desde la versión 3.12.


Command-line interface
----------------------

The "sqlite3" module can be invoked as a script, using the
interpreter's "-m" switch, in order to provide a simple SQLite shell.
The argument signature is as follows:

   python -m sqlite3 [-h] [-v] [filename] [sql]

Type ".quit" or CTRL-D to exit the shell.

-h, --help

   Print CLI help.

-v, --version

   Print underlying SQLite library version.

Added in version 3.12.


Guías prácticas
===============


Cómo usar marcadores de posición para vincular valores en consultas SQL
-----------------------------------------------------------------------

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. For example,
an attacker can simply close the single quote and inject "OR TRUE" to
select all rows:

   >>> # Never do this -- insecure!
   >>> symbol = input()
   ' OR TRUE; --
   >>> sql = "SELECT * FROM stocks WHERE symbol = '%s'" % symbol
   >>> print(sql)
   SELECT * FROM stocks WHERE symbol = '' OR TRUE; --'
   >>> cur.execute(sql)

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* whose length must match the
number of placeholders, or a "ProgrammingError" is raised. For the
named style, *parameters* must be an instance of a "dict" (or a
subclass), which must contain keys for all named parameters; any extra
items are ignored. Here's an example of both styles:

   con = sqlite3.connect(":memory:")
   cur = con.execute("CREATE TABLE lang(name, first_appeared)")

   # This is the named style used with executemany():
   data = (
       {"name": "C", "year": 1972},
       {"name": "Fortran", "year": 1957},
       {"name": "Python", "year": 1991},
       {"name": "Go", "year": 2009},
   )
   cur.executemany("INSERT INTO lang VALUES(:name, :year)", data)

   # This is the qmark style used in a SELECT query:
   params = (1972,)
   cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)
   print(cur.fetchall())
   con.close()

Nota:

  **PEP 249** numeric placeholders are *not* supported. If used, they
  will be interpreted as named placeholders.


Cómo adaptar tipos de Python personalizados a valores de SQLite
---------------------------------------------------------------

SQLite solo admite un conjunto limitado de tipos de datos de forma
nativa. Para almacenar tipos personalizados de Python en bases de
datos SQLite, adáptelos a uno de los tipos Python que SQLite entiende
de forma nativa.

Hay dos formas de adaptar los objetos de Python a los tipos de SQLite:
dejar que su objeto se adapte a sí mismo o usar un *adapter callable*.
Este último prevalecerá sobre el primero. Para una biblioteca que
exporta un tipo personalizado, puede tener sentido permitir que ese
tipo se adapte. Como desarrollador de aplicaciones, puede tener más
sentido tomar el control directo registrando funciones de adaptador
personalizadas.


Cómo escribir objetos adaptables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Supongamos que tenemos una clase "Point" que representa un par de
coordenadas, "x" e "y", en un sistema de coordenadas cartesianas. El
par de coordenadas se almacenará como una cadena de texto en la base
de datos, utilizando un punto y coma para separar las coordenadas.
Esto se puede implementar agregando un método "__conform__(self,
protocol)" que retorna el valor adaptado. El objeto pasado a
*protocolo* será de tipo "PrepareProtocol".

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

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

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

   cur.execute("SELECT ?", (Point(4.0, -3.2),))
   print(cur.fetchone()[0])
   con.close()


Como registrar un adaptador invocable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

La otra posibilidad es crear una función que convierta el objeto
Python a un tipo compatible de SQLite. Esta función puede de esta
forma ser registrada usando un "register_adapter()".

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

   def adapt_point(point):
       return f"{point.x};{point.y}"

   sqlite3.register_adapter(Point, adapt_point)

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

   cur.execute("SELECT ?", (Point(1.0, 2.5),))
   print(cur.fetchone()[0])
   con.close()


Como convertir valores SQLite a tipos de Python personalizados
--------------------------------------------------------------

Escribir un adaptador le permite convertir *de* tipos personalizados
de Python *a* valores SQLite. Para poder convertir *de* valores SQLite
*a* tipos personalizados de Python, usamos *convertidores*.

Regresemos a la clase "Point". Almacenamos las coordenadas x y y
separadas por punto y coma como una cadena de caracteres en SQLite.

Primero, se define una función de conversión que acepta la cadena de
texto como un parámetro y construya 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 necesitamos decirle a "sqlite3" cuando debería convertir un
valor dado SQLite. Esto se hace cuando se conecta a una base de datos,
utilizando el parámetro *detect_types* de "connect()". Hay tres
opciones:

* Implícito: establece *detect_types* para que "PARSE_DECLTYPES"

* Explícito: establece *detect_types* para que "PARSE_COLNAMES"

* Ambos: establece *detect_types* para "sqlite3.PARSE_DECLTYPES |
  sqlite3.PARSE_COLNAMES". Los nombres de columna tienen prioridad
  sobre los tipos declarados.

El siguiente ejemplo ilustra ambos enfoques:

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

       def __repr__(self):
           return f"Point({self.x}, {self.y})"

   def adapt_point(point):
       return f"{point.x};{point.y}"

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

   # Register the adapter and converter
   sqlite3.register_adapter(Point, adapt_point)
   sqlite3.register_converter("point", convert_point)

   # 1) Parse using declared types
   p = Point(4.0, -3.2)
   con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
   cur = con.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()

   # 2) Parse using column names
   con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
   cur = con.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()


Ejemplos para adaptadores y convertidores
-----------------------------------------

En esta sección se muestran ejemplos para adaptadores y convertidores
comunes.

   import datetime
   import sqlite3

   def adapt_date_iso(val):
       """Adapt datetime.date to ISO 8601 date."""
       return val.isoformat()

   def adapt_datetime_iso(val):
       """Adapt datetime.datetime to timezone-naive ISO 8601 date."""
       return val.isoformat()

   def adapt_datetime_epoch(val):
       """Adapt datetime.datetime to Unix timestamp."""
       return int(val.timestamp())

   sqlite3.register_adapter(datetime.date, adapt_date_iso)
   sqlite3.register_adapter(datetime.datetime, adapt_datetime_iso)
   sqlite3.register_adapter(datetime.datetime, adapt_datetime_epoch)

   def convert_date(val):
       """Convert ISO 8601 date to datetime.date object."""
       return datetime.date.fromisoformat(val.decode())

   def convert_datetime(val):
       """Convert ISO 8601 datetime to datetime.datetime object."""
       return datetime.datetime.fromisoformat(val.decode())

   def convert_timestamp(val):
       """Convert Unix epoch timestamp to datetime.datetime object."""
       return datetime.datetime.fromtimestamp(int(val))

   sqlite3.register_converter("date", convert_date)
   sqlite3.register_converter("datetime", convert_datetime)
   sqlite3.register_converter("timestamp", convert_timestamp)


Cómo utilizar los métodos de acceso directo de conexión
-------------------------------------------------------

Usando los métodos "execute()", "executemany()", y "executescript()"
de la clase "Connection", su código se puede escribir de manera más
concisa porque no tiene que crear los (a menudo superfluo) objetos
"Cursor" explícitamente. Por el contrario, los objetos "Cursor" son
creados implícitamente y esos métodos de acceso directo retornarán
objetos cursores. De esta forma, se puede ejecutar una sentencia
"SELECT" e iterar sobre ella directamente usando un simple llamado
sobre el objeto de clase "Connection".

   # Create and fill the table.
   con = sqlite3.connect(":memory:")
   con.execute("CREATE TABLE lang(name, first_appeared)")
   data = [
       ("C++", 1985),
       ("Objective-C", 1984),
   ]
   con.executemany("INSERT INTO lang(name, first_appeared) VALUES(?, ?)", data)

   # 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;
   # the connection object should be closed manually
   con.close()


Como usar la conexión con un administrador de contexto
------------------------------------------------------

A "Connection" object can be used as a context manager that
automatically commits or rolls back open transactions when leaving the
body of the context manager. If the body of the "with" statement
finishes without exceptions, the transaction is committed. If this
commit fails, or if the body of the "with" statement raises an
uncaught exception, the transaction is rolled back. If "autocommit" is
"False", a new transaction is implicitly opened after committing or
rolling back.

If there is no open transaction upon leaving the body of the "with"
statement, or if "autocommit" is "True", the context manager does
nothing.

Nota:

  The context manager neither implicitly opens a new transaction nor
  closes the connection. If you need a closing context manager,
  consider using "contextlib.closing()".

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


Como trabajar con URIs SQLite
-----------------------------

Algunos trucos útiles de URI incluyen:

* Abra una base de datos en modo de solo lectura:

   >>> con = sqlite3.connect("file:tutorial.db?mode=ro", uri=True)
   >>> con.execute("CREATE TABLE readonly(data)")
   Traceback (most recent call last):
   OperationalError: attempt to write a readonly database
   >>> con.close()

* No cree implícitamente un nuevo archivo de base de datos si aún no
  existe; esto lanzará un "OperationalError" si no puede crear un
  nuevo archivo:

   >>> con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
   Traceback (most recent call last):
   OperationalError: unable to open database file

* Crea un nombre compartido sobre una base de datos en memoria:

   db = "file:mem1?mode=memory&cache=shared"
   con1 = sqlite3.connect(db, uri=True)
   con2 = sqlite3.connect(db, uri=True)
   with con1:
       con1.execute("CREATE TABLE shared(data)")
       con1.execute("INSERT INTO shared VALUES(28)")
   res = con2.execute("SELECT data FROM shared")
   assert res.fetchone() == (28,)

   con1.close()
   con2.close()

Más información sobre esta característica, incluyendo una lista de
opciones reconocidas, pueden encontrarse en SQLite URI documentation.


How to create and use row factories
-----------------------------------

By default, "sqlite3" represents each row as a "tuple". If a "tuple"
does not suit your needs, you can use the "sqlite3.Row" class or a
custom "row_factory".

While "row_factory" exists as an attribute both on the "Cursor" and
the "Connection", it is recommended to set "Connection.row_factory",
so all cursors created from the connection will use the same row
factory.

"Row" provides indexed and case-insensitive named access to columns,
with minimal memory overhead and performance impact over a "tuple". To
use "Row" as a row factory, assign it to the "row_factory" attribute:

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

Queries now return "Row" objects:

   >>> res = con.execute("SELECT 'Earth' AS name, 6378 AS radius")
   >>> row = res.fetchone()
   >>> row.keys()
   ['name', 'radius']
   >>> row[0]         # Access by index.
   'Earth'
   >>> row["name"]    # Access by name.
   'Earth'
   >>> row["RADIUS"]  # Column names are case-insensitive.
   6378
   >>> con.close()

Nota:

  The "FROM" clause can be omitted in the "SELECT" statement, as in
  the above example. In such cases, SQLite returns a single row with
  columns defined by expressions, e.g. literals, with the given
  aliases "expr AS alias".

You can create a custom "row_factory" that returns each row as a
"dict", with column names mapped to values:

   def dict_factory(cursor, row):
       fields = [column[0] for column in cursor.description]
       return {key: value for key, value in zip(fields, row)}

Using it, queries now return a "dict" instead of a "tuple":

   >>> con = sqlite3.connect(":memory:")
   >>> con.row_factory = dict_factory
   >>> for row in con.execute("SELECT 1 AS a, 2 AS b"):
   ...     print(row)
   {'a': 1, 'b': 2}
   >>> con.close()

The following row factory returns a *named tuple*:

   from collections import namedtuple

   def namedtuple_factory(cursor, row):
       fields = [column[0] for column in cursor.description]
       cls = namedtuple("Row", fields)
       return cls._make(row)

"namedtuple_factory()" can be used as follows:

   >>> con = sqlite3.connect(":memory:")
   >>> con.row_factory = namedtuple_factory
   >>> cur = con.execute("SELECT 1 AS a, 2 AS b")
   >>> row = cur.fetchone()
   >>> row
   Row(a=1, b=2)
   >>> row[0]  # Indexed access.
   1
   >>> row.b   # Attribute access.
   2
   >>> con.close()

With some adjustments, the above recipe can be adapted to use a
"dataclass", or any other custom class, instead of a "namedtuple".


How to handle non-UTF-8 text encodings
--------------------------------------

By default, "sqlite3" uses "str" to adapt SQLite values with the
"TEXT" data type. This works well for UTF-8 encoded text, but it might
fail for other encodings and invalid UTF-8. You can use a custom
"text_factory" to handle such cases.

Because of SQLite's flexible typing, it is not uncommon to encounter
table columns with the "TEXT" data type containing non-UTF-8
encodings, or even arbitrary data. To demonstrate, let's assume we
have a database with ISO-8859-2 (Latin-2) encoded text, for example a
table of Czech-English dictionary entries. Assuming we now have a
"Connection" instance "con" connected to this database, we can decode
the Latin-2 encoded text using this "text_factory":

   con.text_factory = lambda data: str(data, encoding="latin2")

For invalid UTF-8 or arbitrary data in stored in "TEXT" table columns,
you can use the following technique, borrowed from the CÓMO (HOWTO)
Unicode:

   con.text_factory = lambda data: str(data, errors="surrogateescape")

Nota:

  The "sqlite3" module API does not support strings containing
  surrogates.

Ver también: CÓMO (HOWTO) Unicode


Explicación
===========


Control transaccional
---------------------

"sqlite3" offers multiple methods of controlling whether, when and how
database transactions are opened and closed. Transaction control via
the autocommit attribute is recommended, while Transaction control via
the isolation_level attribute retains the pre-Python 3.12 behaviour.


Transaction control via the "autocommit" attribute
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The recommended way of controlling transaction behaviour is through
the "Connection.autocommit" attribute, which should preferably be set
using the *autocommit* parameter of "connect()".

It is suggested to set *autocommit* to "False", which implies **PEP
249**-compliant transaction control. This means:

* "sqlite3" ensures that a transaction is always open, so "connect()",
  "Connection.commit()", and "Connection.rollback()" will implicitly
  open a new transaction (immediately after closing the pending one,
  for the latter two). "sqlite3" uses "BEGIN DEFERRED" statements when
  opening transactions.

* Transactions should be committed explicitly using "commit()".

* Transactions should be rolled back explicitly using "rollback()".

* An implicit rollback is performed if the database is "close()"-ed
  with pending changes.

Set *autocommit* to "True" to enable SQLite's autocommit mode. In this
mode, "Connection.commit()" and "Connection.rollback()" have no
effect. Note that SQLite's autocommit mode is distinct from the **PEP
249**-compliant "Connection.autocommit" attribute; use
"Connection.in_transaction" to query the low-level SQLite autocommit
mode.

Set *autocommit* to "LEGACY_TRANSACTION_CONTROL" to leave transaction
control behaviour to the "Connection.isolation_level" attribute. See
Transaction control via the isolation_level attribute for more
information.


Transaction control via the "isolation_level" attribute
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Nota:

  The recommended way of controlling transactions is via the
  "autocommit" attribute. See Transaction control via the autocommit
  attribute.

If "Connection.autocommit" is set to "LEGACY_TRANSACTION_CONTROL" (the
default), transaction behaviour is controlled using the
"Connection.isolation_level" attribute. Otherwise, "isolation_level"
has no effect.

Si el atributo de conexión "isolation_level" no es "None", las nuevas
transacciones se abrirán implícitamente antes de "execute()" y
"executemany()" ejecutará sentencias "INSERT", "UPDATE", "DELETE" o
"REPLACE"; para otras sentencias, no se realiza ningún manejo de
transacción implícito. Utilice los métodos "commit()" y "rollback()"
para confirmar y deshacer respectivamente las transacciones
pendientes. Puede elegir el SQLite transaction behaviour  subyacente,
es decir, si y qué tipo de declaraciones "BEGIN" "sqlite3" se
ejecutarán implícitamente, a través del atributo "isolation_level".

Si "isolation_level" se establece como "None", no se abre ninguna
transacción implícitamente. Esto deja la biblioteca SQLite subyacente
en autocommit mode, pero también permite que el usuario realice su
propio manejo de transacciones usando declaraciones SQL explícitas. El
modo de confirmación automática de la biblioteca SQLite subyacente se
puede consultar mediante el atributo "in_transaction".

El método "executescript()" guarda implícitamente cualquier
transacción pendiente antes de la ejecución del script SQL dado,
independientemente del valor de "isolation_level".

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.

Distinto en la versión 3.12: The recommended way of controlling
transactions is now via the "autocommit" attribute.
