dblite.api Namespace Reference

Classes
class	Database
	Database instance. More...
class	Queryable
	Abstract base for Database and Transaction. More...
class	Rollback
class	Transaction
	Transaction context manager, breakable by raising Rollback. More...

Functions
def	close (commit=None)
	Closes the default database connection, if any. More...
def	delete (table, where=(), **kwargs)
	Convenience wrapper for database DELETE, returns affected row count. More...
def	execute (sql, args=())
	Executes the SQL statement and returns database cursor. More...
def	executemany (sql, args)
	Executes the SQL statement against all parameter sequences. More...
def	executescript (sql)
	Executes the SQL as script of any number of statements. More...
def	fetchall (table, cols="*", where=(), group=(), order=(), limit=(), **kwargs)
	Convenience wrapper for database SELECT and fetch all. More...
def	fetchone (table, cols="*", where=(), group=(), order=(), limit=(), **kwargs)
	Convenience wrapper for database SELECT and fetch one. More...
def	init (opts=None, engine=None, **kwargs)
	Returns a Database object. More...
def	insert (table, values=(), **kwargs)
	Convenience wrapper for database INSERT, returns inserted row ID. More...
def	insertmany (table, rows=(), **kwargs)
	Convenience wrapper for database multiple INSERTs, returns list of inserted row IDs. More...
def	register_adapter (transformer, typeclasses, engine=None)
	Registers function to auto-adapt given Python types to database types in query parameters. More...
def	register_converter (transformer, typenames, engine=None)
	Registers function to auto-convert given database types to Python in query results. More...
def	register_row_factory (row_factory, engine=None)
	Registers function to produce query results as custom type. More...
def	select (table, cols="*", where=(), group=(), order=(), limit=(), **kwargs)
	Convenience wrapper for database SELECT, returns database cursor. More...
def	transaction (commit=True, exclusive=None, **kwargs)
	Returns a transaction context manager. More...
def	update (table, values, where=(), **kwargs)
	Convenience wrapper for database UPDATE, returns affected row count. More...

Function Documentation

close()

def dblite.api.close

(

commit = None

)

Closes the default database connection, if any.

Parameters

commit

`True` for explicit commit on open transactions, `False` for explicit rollback on open transactions, `None` defaults to `commit` flag from transaction creations

Definition at line 173 of file api.py.

delete()

def dblite.api.delete	(		table,
			where = (),
		**	kwargs
	)

Convenience wrapper for database DELETE, returns affected row count.

Arguments have the same meaning as in select().

Definition at line 131 of file api.py.

execute()

def dblite.api.execute	(		sql,
			args = ()
	)

Executes the SQL statement and returns database cursor.

Parameters

sql	SQL statement to execute, with engine-specific parameter bindings, if any
args	query parameters, as tuple or dictionary

Definition at line 141 of file api.py.

executemany()

def dblite.api.executemany	(		sql,
			args
	)

Executes the SQL statement against all parameter sequences.

Parameters

sql	SQL statement to execute, with engine-specific parameter bindings
args	iterable of query parameters, as dictionaries for named placeholders or sequences for positional placeholders

Definition at line 151 of file api.py.

executescript()

def dblite.api.executescript

(

sql

)

Executes the SQL as script of any number of statements.

Note that in SQLite, the statements are executed outside of transaction, and any pending transaction will be committed first.

Parameters

sql	script with one or more SQL statements

Definition at line 163 of file api.py.

fetchall()

def dblite.api.fetchall	(		table,
			cols = "*",
			where = (),
			group = (),
			order = (),
			limit = (),
		**	kwargs
	)

Convenience wrapper for database SELECT and fetch all.

Arguments have the same meaning as in select().

Definition at line 52 of file api.py.

fetchone()

def dblite.api.fetchone	(		table,
			cols = "*",
			where = (),
			group = (),
			order = (),
			limit = (),
		**	kwargs
	)

Convenience wrapper for database SELECT and fetch one.

Arguments have the same meaning as in select().

Definition at line 60 of file api.py.

init()

def dblite.api.init	(		opts = None,
			engine = None,
		**	kwargs
	)

Returns a Database object.

If opts is `None`, returns the default database - the very first created. Module level functions use the default database.

Parameters

opts	database connection options, engine-specific; SQLite takes a file path or path-like object or `":memory:"`, Postgres takes a Postgres URI scheme like `"postgresql://user@localhost/mydb"` or a Postgres keyword=value format string like `"host=localhost username=user dbname=mydb"` or a dictionary of connection options like `dict(host="localhost", dbname=..)`
engine	database engine if not auto-detecting from connection options, `"sqlite"` for SQLite3 and `"postgres"` for PostgreSQL (case-insensitive)
kwargs	additional arguments given to engine constructor, e.g. `detect_types=sqlite3.PARSE_COLNAMES` for SQLite, or `minconn=1, maxconn=4` for Postgres connection pool

Definition at line 43 of file api.py.

insert()

def dblite.api.insert	(		table,
			values = (),
		**	kwargs
	)

Convenience wrapper for database INSERT, returns inserted row ID.

Keyword arguments are added to VALUES. `table` argument has the same meaning as in select(). Column names can be data-class properies as in select().

Parameters

values

column values to insert, as dict or a sequence of key-value tuples or a data object

Definition at line 72 of file api.py.

insertmany()

def dblite.api.insertmany	(		table,
			rows = (),
		**	kwargs
	)

Convenience wrapper for database multiple INSERTs, returns list of inserted row IDs.

Keyword arguments are added to VALUES of every single row, overriding individual row values. `table` argument has the same meaning as in select(). Column names can be data-class properies as in select().

Parameters

rows	list of row values to insert, as list of dicts or sequences of key-value tuples or data objects

Definition at line 84 of file api.py.

register_adapter()

def dblite.api.register_adapter	(		transformer,
			typeclasses,
			engine = None
	)

Registers function to auto-adapt given Python types to database types in query parameters.

Registration is global per engine.

Parameters

transformer	function(Python value) returning adapted value
typeclasses	one or more Python classes to adapt
engine	database engine to adapt for, defaults to first initialized

Definition at line 203 of file api.py.

register_converter()

def dblite.api.register_converter	(		transformer,
			typenames,
			engine = None
	)

Registers function to auto-convert given database types to Python in query results.

Registration is global per engine.

Parameters

transformer	function(raw database value) returning Python value
typenames	one or more database column types to adapt
engine	database engine to convert for, defaults to first initialized

Definition at line 217 of file api.py.

register_row_factory()

def dblite.api.register_row_factory	(		row_factory,
			engine = None
	)

Registers function to produce query results as custom type.

Registration is global per engine; affects future connections and the current default database.

Parameters

row_factory	function(cursor, row tuple) returning row as desired type or `None` to reset to default. `cursor.description` is a sequence of 7-element tuples, as `(column name, ..engine-specific elements..)`.
engine	database engine to register for, defaults to first initialized

Definition at line 232 of file api.py.

select()

def dblite.api.select	(		table,
			cols = "*",
			where = (),
			group = (),
			order = (),
			limit = (),
		**	kwargs
	)

Convenience wrapper for database SELECT, returns database cursor.

Column names in `where/cols/group/order` arguments can be data-class properties, like `order=MyClass.my_attribute`.

Parameters

table	table/view name or expression to select from, or a data class with `__name__` used for table name
where	columns or expressions to select by, as dict or a sequence of key-value tuples or a data object; value can specify operator e.g. `{"mycolumn": ("IN", [1, 2, 3])}`
cols	columns to select if not all, as string or a sequence of stringables or a dict with stringable keys
group	columns to GROUP BY, as string or a sequence of stringables or a dict with stringable keys
order	columns to ORDER BY, as string, a sequence of stringables, or a combination of column names and direction flags, or a dict with column name keys and direction flag values. Direction flag can be string like `"ASC"`, or truthy/falsy for ascending/descending.
limit	LIMIT .. OFFSET.. values, as integer or a sequence of integers; None or -1 disables LIMIT or OFFSET
kwargs	additional arguments added to WHERE clause

Definition at line 112 of file api.py.

transaction()

def dblite.api.transaction	(		commit = True,
			exclusive = None,
		**	kwargs
	)

Returns a transaction context manager.

Context is breakable by raising Rollback.

Note that parameter `exclusive` defaults to `True` when using SQLite.

Parameters

commit	whether transaction commits automatically at exiting with-block
exclusive	whether entering a with-block is exclusive over other Transaction instances on this Database; `None` stands for engine default
kwargs	engine-specific arguments, like `schema="other", lazy=True` for Postgres

Definition at line 190 of file api.py.

update()

def dblite.api.update	(		table,
			values,
			where = (),
		**	kwargs
	)

Convenience wrapper for database UPDATE, returns affected row count.

Arguments have the same meaning as in select(). Column names can be data-class properies as in select().

Parameters

values

column values to set, as dict or a sequence of key-value tuples or a data object

Definition at line 123 of file api.py.