Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
199 lines (126 sloc) 5.91 KB

Reference

Contexts

Contexts wrap a notional database connection. They're returned by the :py:func:`dbkit.connect` function. Methods are for the internal use of dbkit only though it does expose a method for closing the database connection when you're done with it and contains references for each of the exceptions exposed by the connection's database driver. For a list of these exceptions, see PEP-0249.

Exceptions

Transactions

Statement execution

These functions allow you to execute SQL statements within the current database context.

Stored procedures

These functions allow you to execute stored procedures within the current database context, if the DBMS supports stored procedures.

Result generators

Result generators are generator functions that are used internally by dbkit to take the results from a database cursor and turn them into a form that's easier to deal with programmatically, such a sequence of tuples or a sequence of dictionaries, where each tuple or dictionary represents a row of the result set. By default, :py:func:`dbkit.tuple_set` is used as the result generator, but you can change this by assigning another, such as :py:func:`dbkit.dict_set` to :py:attr:`dbkit.Context.default_factory` function.

Some query functions allow you to specify the result generator to be used for the result, which is passed in using the factory parameter.

Loggers

Loggers are functions that you can assign to :py:attr:`dbkit.Context.logger` to have dbkit log any SQL statements ran or stored procedures called to some sink. dbkit comes with a number of simple loggers listed below. To create your own logger, simply create a function that takes two arguments, the first of which is the SQL statement or stored procedure name, and the second is a sequence of arguments that were passed with it.

Utilities

Connection pools

Note

Connection pool support is currently considered pre-alpha.

Connection pooling is a way to share a common set of database connections over a set of contexts, each of which can be executing in different threads. Connection pooling can increase efficiency as it mitigates much of the cost involved in connecting and disconnecting from databases. It also can help lower the number of database connections an application needs to keep open with a database server concurrently, thus helping to lower server low.

As with contexts, pools have a copy of the driver module's exceptions. For a list of these exceptions, see PEP-0249.

The acquire and release methods are for internal use only.

Connection mediators

Connection mediators are used internally within contexts to mediate connection acquisition and release between a context and a (notional) connection pool. They're an advanced feature that you as a developer will only need to understand and use if writing your own connection pool. All connection mediator instances are context managers.

Note

You might find the naming a bit odd. After all, wouldn't calling something like this a 'manager' be just as appropriate and less... odd? Not really. Calling something a 'manager' presupposes a degree of control over the resource in question. A 'mediator', on the other hand, simply acts as a middle man which both parties know. Introducing the mediator means that contexts don't need to know where their connections come from and pools don't need to care how they're used. The mediator takes care of all that.