Traducción al buen español del Módulo SQLite3 para Python – sin usar Google translater-

"IMPORTANTE. Si copias esta traducción, reconoce mi trabajo e incluye mis datos en los créditos, esto es importante para que los demás sepan donde encontrar trabajos así y me motivaría a hacer más traducciones. Gracias!"

Traductor: Christian Rios Guevara

E-mail: xnrios@gmail.com

Versión de traducción: 0.0.2

Original: https://docs.python.org/2/library/sqlite3.html#module-sqlite3

Notas del traductor:

1. Falta continuar, revisar y arreglar.
2. No usé Google translater.
3. Cualquier ayuda, duda o sugerencia sobre la traducción pueden enviarme un e-mail.

11.13. sqlite3 — DB-API 2.0 interfase para la base de datos SQLite.

Nuevo en la versión 2.5.

SQLite es una librería que nos ofrece una base de datos ligera, que no requiere un servidor de proceso por separado y permite acceder a la base de datos usando una variante no estandarizada de consulta en el lenguaje SQL. Algunas aplicaciones pueden usar SQLite para almacenar datos internos. También es posible probar una aplicación usando SQLite y luego usar el código en otras bases de datos más amplias como PostgreSQL o Oracle.

El modulo SQLite3 fue escrito por Gerhard Häring. Esto ofrece una interfase SQL que es compatible con la BD-API 2.0 acorde a la especificación escrita en la PEP 249.

Al usar el modulo, usted debe crear primero un objeto connection <conexión> que representa la base de datos. Aquí los datos serán guardados en el archivo ejemplo.db:

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

Usted puede usar el nombre especial :memory: para crear una base de datos en la RAM.

Una vez usted tenga la connection <conexión>, puede crear un objeto cursor y llamar al método execute() que interactúa con los comandos SQL:

c = conn.cursor()

# Crear una tabla
c.execute('''CREATE TABLE stocks
             (date text, trans text, symbol text, qty real, price real)''')

# Insertar una fila de datos
c.execute("INSERT INTO stocks VALUES ('2006-01-05','BUY','RHAT',100,35.14)")

# Salvar/guardar (commit) los cambios
conn.commit()

# Podemos cerrar la conexión si acabamos nuestro trabajo.
# Verifica que todos los cambios fueron realizados o se perderán
conn.close()

Los datos guardados son constantes y están disponibles en las subsecuentes sesiones:

import sqlite3
conn = sqlite3.connect('example.db')
c = conn.cursor()

Usualmente tus operaciones SQL necesitaran usar valores de las variables hechas en Python. Usted no debe enlazar su consulta usando cadenas de operación de Python porque es inseguro; esto hace que su programa sea más vulnerable a un ataque con inyección SQL (para más información visite: http://xkcd.com/327/ ).

Mejor, use los parámetros de sustitución de la DB-API. Ponga el símbolo ? como un marcador de posición donde quiera usar un valor, y entonces ofrezca una tupla de valores como un segundo argumento al método execute() del cursor. (Otros módulos de base de datos podrían usar un diferente marcador, como %s o :1) Por ejemplo:

# Nunca haga esto -- Es inseguro!
symbol = 'RHAT'
c.execute("SELECT * FROM stocks WHERE symbol = '%s'" % symbol)

# Mejor haz esto
t = ('RHAT',)
c.execute('SELECT * FROM stocks WHERE symbol=?', t)
print c.fetchone()

#  Amplio ejemplo de como realizar varias inserciones a la vez
purchases = [('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
             ('2006-04-05', 'BUY', 'MSFT', 1000, 72.00),
             ('2006-04-06', 'SELL', 'IBM', 500, 53.00),
            ]
c.executemany('INSERT INTO stocks VALUES (?,?,?,?,?)', purchases)

Para recuperar los datos después de ejecutar un declaración SELECT, usted puede tratar el cursor como un iterator <itinerador>. Llame al método fetchone() del cursor para recuperar un registro único vinculado, o llamar al método fetchall() para obtener una lista de filas vinculadas.

Este ejemplo usa la forma de itinerante:

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

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

11.13.1. Módulo de funciones y constantes

sqlite3.version

El número de versión de este módulo, devuelve un string (cadena). Esta no es la versión de la libreria SQLite.

sqlite3.version_info

El número de versión de este módulo, devuelve una tupla de números enteros. Esta no es la versión de la libreria SQLite.

sqlite3.sqlite_version

El número de versión del run-time de la librería SQLite, devuelve un string (cadena).

sqlite3.sqlite_version_info

El número de versión del run-time de la librería SQLite, devuelve una tupla (números enteros).

sqlite3.PARSE_DECLTYPES

Esta constante esta destinado a ser usado con el parámetro detectar_tipo_dato de la función connect().

Configurándolo hace que el módulo sqlite3 analice el tipo de declaración de cada columna que retorna. Determinará la primera palabra del tipo declarado, por ejemplo: para “interger primary key”, será determinado como 'integer' (número entero), o por 'number(10)' será analizado como “numero”.

Entonces para esa columna, se evaluarán los diccionarios convertidores y usará la función de convertidor registrado para aquel tipo de dato.

sqlite3.PARSE_COLNAMES

Esta constante requiere ser usado con los parámetros detectar_tipo_dato de la función connect().

Configurando hace que la interface de SQLite determine el nombre de la columna por cada columna que retorne. Se buscará una cadena formada [mitipodato] dentro y luego decide que 'mitipodato' es el tipo de dato de la columna. Se tratará de encontrar una entrada 'mitipodato' en los convertidores de diccionario y luego usa la función del convertidor encontrado ahí para retornan el valor. La nombre de la columna encontrada en cursor.description es solo la primera palabra del nombre de la columna, por ejemplo: Si usara algo como 'as “x [datatime]” ' en su SQL, entonces estaremos determinando todo hasta el primer espacio en blanco para el nombre de la columna: el nombre de la columna sería simplemente “x”.

sqlite3.connect (basedatos[, tiempo_espera, detectar_tipo_dato, nivel_aislamiento, chequear_mismo_hilo, fábrica, declaraciones_cache])

Abre la conexión al archivo de base de datos SQL. Puedes usar la “:memory:” para abrir una conexión de base datos que resida en la RAM en vez del disco duro.

Cuando la base datos es accesada por muchas conexiones, y un de los procesos modifica la base de datos, la base de datos de SQLite está cerrada hasta que la transacción sea entregada. El parámetro tiempo_espera especifica cuanto tiempo la conexión debe esperar para el cierre para retirarse hasta lanzar una excepción. Por defecto el parámetro tiempo de espera es de 5.0 (cinco segundos).

Para el parámetro de nivel_aislamiento por favor, vea la propiedad connection.isolation_level de los objetos que contiene connection.

Nativamente SQLite soporta solo los tipos TEXT, INTEGER, REAL, BLOB y NULL. Si desea usar otro tipo de dato debe agregar soporte por usted mismo. El parámetro detectar_tipodato y el uso de converters<convertidores> registrados con la función módulo-nivel register_converter() le permiten hacerlo fácilmente.

detectar_tipo_dato viene determinado con el valor 0 (Por ejemplo: off, ninguna detección de tipo de dato), usted puede configurarlo a cualquier conbinación de PARSE_DECLTYPES y PARSE_COLNAMES para habilitar la detección de tipo de datos.

Por defecto, el módulo sqlite3 usa su propia clase connection <conexión> para llamar a la conexión. Usted puede, si desea, crear una subclase la clase Connection y hacer que connect() use la clase creada por usted en vez de proporcionar su propia clase para el parametro fabrica.

Consulte la sección SQLite y tipos de datos Python de este manual para detalles.

El módulo sqlite3 internamente usa una declaración de cache para evitar una evaluación elevada del SQL. Si desea explícitamente colocar el número de declaraciones que son puestos en el cache para la conexión, usted puede colocarlos en el parametro declaraciones_cache <cached>. El valor por defecto implementado actualmente es de cache de 100 declaraciones.

sqlite3.register_converter(typename, callable)

Registra un rescate para convertir un bytestring de la base de datos a un tipo de dato personalizado de python. El rescate sera invocado para todos los valores de la base de datos que son del tipo typename. Consulta el parámetro dectectar_tipodatos de la función connect() de cómo funciona la detección de tipo dato. ¡Notese que el caso de tiponombre y el nombre del tipo de dato en tu consulta debe encajar!

sqlite3.register_adapter(type, callable)

Registra un rescate para convertir un tipo de dato de python a uno que sea soportado por los tipos de datos de SQLite. El rescate <callable> acepta como un solo parámetro el valor de Python, y debe retornar un valor de los siguientes tipos de datos: int, long, float, str (UTF-8 encoded), unicode o buffer.

sqlite3.complete_statement(sql)

Retorna true si la cadena de letras sql contiene una o más declaraciones SQL terminadas con un punto y coma < ;>. Esto no verifica que el SQL está escrito sintácticamente bien, solo verifica si no hay strings literales sin cerrar y si la declaración termina en punto y coma.

Esto puede usarse para construir una shell para SQLite, como en el siguiente ejemplo se detalla:

# Un pequeño shell sqlite para experimentar

import sqlite3

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

buffer = ""

print "Ingrese los comandos SQL para ejecutarlo en sqlite3."
print "Ingrese un espacio en blanco para salir."

while True:
    line = raw_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 "Un error ocurrió:", e.args[0]
        buffer = ""

con.close()

sqlite3.enable_callback_traceback(flag)

Por defecto no obtendrás ninguna rastreo en la función usuario-definido, agregados, convertidores, devoluciones de llamadas de autorización, etc. Si quiere depurarlos puede llamar a esta función con flag, debe estar en true. Luego usted obtendrá un rastreo desde las devoluciones en sys.stderr. Use false para desactivar la pantalla una vez más.

11.13.2. Objetos de conexión

clase sqlite3.Connection

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

isolation_level

Obtiene o configura el nivel de aislamiento personalizado. None por el modo de confirmación automática o “DEFERRED”, “IMMEDIATE” o “EXCLUSIVE”. Mire la sección Controlando las transacciones para mayor informacion.

cursor([cursorClass])

El método cursor acepta un solo parámetro opcional cursorClass. Si se suministra, esto debe de ser una actual clase cursor que extendiende sqlite3.cursor .

commit()

Este método compromete la actual transacción. Si usted no llama a este método, nada hecho por usted desde el ultimo llamado a commit() está visible desde la otra conexión de base de datos. Si quiere saber por qué no puede ver los datos que ha escrito en la base de datos, por favor chequeé que no haya olvidado llamar a este método.

rollback()

Este método vuelve atrás cualquier cambio a la base de datos desde la ultima llamada a commit() .

close()

Se utiliza para cerrar conexión de la base de datos. Note que esto no llama automáticamente a commit(). Si desea cerrar la conexión de la base de datos sin llamar a commit() primero, sus cambios desaparecerán!

execute(sql[,parametros])

Esto es un atajo no estandarizado que permite crear un objeto cursor intermedio solo llamando al método cursor, luego invoca al método execute del cursor con los parámetros otorgados.

executemany(sql[, parametros])

Esto es un atajo no estandarizado que permite crear un objeto cursor intermedio solo llamando al método cursor, luego invoca al método executemany del cursor con los parámetros otorgados.

executescript(sql_script)

Esto es un atajo no estandarizado que permite crear un objeto cursor intermedio solo llamando al método cursor, luego invoca al método executescript del cursor con los parámetros otorgados.

create_function(name, num_params, func)

Crea una función de usuario definido que usted puede usar luego conjuntamente con declaraciones SQL bajo la función name. num_params es el numero de los parametros que la función acepta, y func es una declaración de rescate que es llamado como una función SQL.

La función puede retornar cualquier de los tipos de datos soportados por SQLite: unicode, str, int, long, float, buffer, y None.

Ejemplo:

import sqlite3
import md5

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

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

create_aggregate(name, num_params, aggregate_class)

Crea una función de usuario definido agregado.

La clase aggregate debe implementar un método step <paso>, el cual acepta el número de parámetros num_params, y un método finalize el cual retornará un resultado final de el aggregate <agregado>.

El método finalize puede retornar cualquiera de los tipos de datos soportados por SQL: unicode, str, int, long, float, buffer y 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]

create_collation(name, callable)
Compara el name <nombre> especifico y callable <llamada>. La llamada se pasara en dos argumentos tipo cadena. Retornará -1 si el primero es ordenada menos que el segundo, 0 si están ordenados igual y 1 si e primero está ordenado mas alto que el segundo. Note que este control de orden (ORDER BY en SQL) así que sus comparaciones no tienen afectan a otras operaciones SQL.

Note que la llamada obtendrá sus parámetros como bytestrings <pedazos de cadenas> de Python, los cuales estarán normalmente codificados en UFT-8.

El siguiente ejemplo muestra una comparación que ordena "el mal camino".

import sqlite3

def collate_reverse(string1, string2):
    return -cmp(string1, string2)

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/eliminar una cotejación/comparación , llame a create_collation con None como llamada.

con.create_collation("reverse", None)

Puede llamar a este método desde un proceso diferente para abortar cualquier consulta que puede estarse ejecutando en la conexión. La consulta será abortada y el caller <llamador/consultante> obtendrá una excepción.

set_authorizer(authorizer_callback)

Esta rutina registra una devolución de una llamada. La devolución de una llamada es invocada por cada intento para acceder a la columna de una tabla en la base de datos.

La devolución de la llamada debe retornar SQULITE_OK  si el acceso fue permitido, SQLITE_DENY si toda la declaración SQL estaría abortada con un error y SQLITE_IGNORE si la columna sería compuesta de un valor NULL. Estas constantes son permitidas en el módulo sqlite3. 

El primer argumento para la devolución de llamada <callback> significa qué tipo de operación está autorizada. El segundo y el 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 es aplicable. El quinto argumento es el nombre de la las profundo activador o visión que es responsable del intento de acceso  o None si este intento de acceso es directamente desde el código de ingreso SQL.

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

set_progress_handle(handler, n)
Esta rutina registra la devolución de la llamada <callback>. La devoluciones  de la llamada es invocada para cada instrucción n de la máquina virtual de SQLite. esto es muy util si deseas que se llame desde SQLite durante largas ejecuciones de operaciones, por ejemplo  para actualizar una GUI (Graphic Unit interface).

Si deseas eliminar cualquier progreso instalado manualmente, utiliza el método con None en lugar de handler.

Nuevo en versión 2.6.

enable_load_extension(enabled)
Esta rutina permite y evita que el motor de SQLite cargue extensiones SQLite desde las librerias compartidas. Las extensiones SQLite puede definir nuevas funciones, agregados o implementar tablas completamente virtuales. Uno de las extensiones más conocidas es el fulltext-search <busqueda de texto completo> distribuido con SQLite.

Las extensiones que se puede cargar estan incapacitados por defecto. Mire [1].

Nuevo en la versión 2.7

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 laoding 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)
Esta rutina carga una extension SQLite desde la libreria compartida. Usted tiene habilitar una extensión usando enable_load_extension() antes de que pueda usar esta rutina.

Las extensiones que puedes cargarse están deshabilitadas por defecto. Mire [1].

Nuevo en la versión 2.7.

row_factory
Usted puede cambiar este atributo desde la llamada que acepte el cursor y la fila original como una tupla y retornada el resultado real de la fila. De esta manera, usted puede implementar formas mas avanzadas de retornar resultados, tales como retornar un objeto que puede acceder a 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"]

Si retornando la tupla no basta y usted desea un ingreso basado en el nombre para acceder a las columnas, considere  configurar row_factory a un tipo mas optimizado de sqlite3.Row. Row ofrece nombres de accesos basados en indices y basados en insensibilidad a  las minusculas/mayusculas para columnas sin casi memoria elevada. Probablemente será mejor que su propio enfoque basado en diccionario personalizado o incluso una solución basada db_row.


text_factoryUsando este atributo usted puede controlar qué objetos son retornados para el tipo de dato TEXTO. Por defecto, este atributo está configurado en UNICODE y el modulo de sqlite3 retornará objetos unicode para el TEXTO, Si deseas retornar bytestrings, puedes configurarlo a str.

Por razones de eficiencia,tambien hay una forma de retornar los objetos en Unicode solo para datos que no son ASCII o de lo contrario bytestrings. Para activarlo, configure este atributo a sqlite3.OptimizedUnicode.

Puedes también configurar cualquier otra llamada que acepte un solo parametro bytestring y retornar el objeto resultante.

Mira el siguiente ejemplo:

import sqlite3

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

AUSTRIA = u"\xd6sterreich"

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

# but we can make sqlite3 always return bytestrings ...
con.text_factory = str
cur.execute("select ?", (AUSTRIA,))
row = cur.fetchone()
assert type(row[0]) is str
# 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 will ignore Unicode characters that cannot be
# decoded from UTF-8
con.text_factory = lambda x: unicode(x, "utf-8", "ignore")
cur.execute("select ?", ("this is latin1 and would normally create errors" +
                         u"\xe4\xf6\xfc".encode("latin1"),))
row = cur.fetchone()
assert type(row[0]) is unicode

# sqlite3 offers a built-in optimized text_factory that will return bytestring
# objects, if the data is in ASCII only, and otherwise return unicode objects
con.text_factory = sqlite3.OptimizedUnicode
cur.execute("select ?", (AUSTRIA,))
row = cur.fetchone()
assert type(row[0]) is unicode

cur.execute("select ?", ("Germany",))
row = cur.fetchone()
assert type(row[0]) is str

total_changes
Retorna el numero total de filas de base de datos que han sido modificadas, insertadas o eliminadas desde que la conexión a la base de datos fue abierta.

iterdump
Retorna un itinerador al deshechar la base de datos en un el formato de texto SQL. Util cuando salvas/grabas una base de datos en la memoria para una posterior  restauración. Esta función ofrece las mismas capacidades como el comando .dump en el shell de sqlite3.

Nuevo en la versión 2.6.

Ejemplo:

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

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

11.13.3. Objetos Cursor