From eb2e1926acdf803b8416724e5321df07b2798b2a Mon Sep 17 00:00:00 2001 From: =?utf8?q?Gerhard=20H=C3=A4ring?= Date: Sat, 29 Apr 2006 23:12:41 +0000 Subject: [PATCH] This is the start of documentation for the sqlite3 module. Please feel free to find a better place for the link to it than alongside bsddb & friends. --- Doc/Makefile.deps | 3 +- Doc/lib/lib.tex | 1 + Doc/lib/libsqlite3.tex | 105 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 108 insertions(+), 1 deletion(-) create mode 100644 Doc/lib/libsqlite3.tex diff --git a/Doc/Makefile.deps b/Doc/Makefile.deps index 53562949a8..e26d99b4c9 100644 --- a/Doc/Makefile.deps +++ b/Doc/Makefile.deps @@ -350,7 +350,8 @@ LIBFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \ lib/libturtle.tex \ lib/libtarfile.tex \ lib/libcsv.tex \ - lib/libcfgparser.tex + lib/libcfgparser.tex \ + lib/libsqlite3.tex # LaTeX source files for Macintosh Library Modules. MACFILES= $(HOWTOSTYLES) $(INDEXSTYLES) $(COMMONTEX) \ diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 67aab8fd89..6172f364e7 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -224,6 +224,7 @@ and how to embed it in other applications. \input{libdbhash} \input{libbsddb} \input{libdumbdbm} +\input{libsqlite3} % ============= diff --git a/Doc/lib/libsqlite3.tex b/Doc/lib/libsqlite3.tex new file mode 100644 index 0000000000..63f7d98eed --- /dev/null +++ b/Doc/lib/libsqlite3.tex @@ -0,0 +1,105 @@ +\section{\module{sqlite3} --- + DB-API 2.0 interface for SQLite databases} + +\declaremodule{builtin}{sqlite3} +\modulesynopsis{A DB-API 2.0 interface based on SQLite 3.x.} + + + +The module defines the following: + +\begin{datadesc}{PARSE_DECLTYPES} +This constant is meant to be used with the detect_types parameter of the connect function. + +Setting it makes the sqlite3 module parse the declared type for each column it +returns. It will parse out the first word of the declared type, i. e. for +"integer primary key", it will parse out "integer". Then for that column, it +will look into pysqlite's converters dictionary and use the converter function +registered for that type there. Converter names are case-sensitive! +\end{datadesc} + + +\begin{datadesc}{PARSE_COLNAMES} + +Setting this makes pysqlite parse the column name for each column it returns. +It will look for a string formed [mytype] in there, and then decide that +'mytype' is the type of the column. It will try to find an entry of 'mytype' in +the converters dictionary and then use the converter function found there to +return the value. The column name found in cursor.description is only the first +word of the column name, i. e. if you use something like 'as "x [datetime]"' +in your SQL, then pysqlite will parse out everything until the first blank for +the column name: the column name would simply be "x". +\end{datadesc} + +\begin{funcdesc}{connect}{database\optional{, timeout, isolation_level, detect_types, check_same_thread, factory}} +Opens a connection to the SQLite database file \var{database}. You can use +\code{":memory:"} to open a database connection to a database that resides in +RAM instead of on disk. + +When a database is accessed by multiple connections, and one of the processes +modifies the database, the SQLite database is locked until that transaction is +committed. The \var{timeout} parameter specifies how long the connection should +wait for the lock to go away until raising an exception. The default for the +timeout parameter is 5.0 (five seconds). + +For the \var{isolation_level} parameter, please see TODO: link property of +Connection objects. + +SQLite natively supports only the types TEXT, INTEGER, FLOAT, BLOB and NULL. If +you want to use other types, like you have to add support for them yourself. +The \var{detect_types} parameter and the using custom *converters* registered with +the module-level *register_converter* function allow you to easily do that. + +\var{detect_types} defaults to 0 (i. e. off, no type detection), you can set it +to any combination of *PARSE_DECLTYPES* and *PARSE_COLNAMES* to turn type +detection on. + +By default, the sqlite3 module uses its Connection class for the connect call. +You can, however, subclass the Connection class and make .connect() use your +class instead by providing your class for the \var{factory} parameter. + +Consult the section `4. SQLite and Python types`_ of this manual for details. + +The sqlite3 module internally uses a statement cache to avoid SQL parsing +overhead. If you want to explicitly set the number of statements that are +cached for the connection, you can set the \var{cached_statements} parameter. +The currently implemented default is to cache 100 statements. +\end{funcdesc} + +\begin{funcdesc}{register_converter}{typename, callable} + +Registers a callable to convert a bytestring from the database into a custom +Python type. The callable will be invoked for all database values that are of +the type \var{typename}. Confer the parameter **detect_types** of the +**connect** method for how the type detection works. Note that the case of +\var{typename} and the name of the type in your query must match! +\end{funcdesc} + +\begin{funcdesc}{register_adapter}{type, callable} +Registers a callable to convert the custom Python type \var{type} into one of +SQLite's supported types. The callable \var{callable} accepts as single +parameter the Python value, and must return a value of the following types: +int, long, float, str (UTF-8 encoded), unicode or buffer. +\end{funcdesc} + + + + + + +\subsection{Connection Objects \label{Connection-Objects}} + +A \class{Connection} instance has the following attributes and methods: + +\member{isolation_level} + Get or set the current isolation level. None for autocommit mode or one + of "DEFERRED", "IMMEDIATE" or "EXLUSIVE". See `5. Controlling + Transactions`_ for a more detailed explanation. + +\begin{methoddesc}{cursor}{\optional{cursorClass}} + The cursor method accepts a single optional parameter \var{cursorClass}. + This is a custom cursor class which must extend sqlite3.Cursor. +\end{methoddesc} + +TODO: execute* + -- 2.40.0