cpython-lru_cache-weakref: Doc/library/sqlite3.rst annotate

annotate Doc/library/sqlite3.rst @ 79675:c0a2294de787 2.7

Issue #16199: Backport 2to3 typo fix from 3.2.

author	Chris Jerdonek <chris.jerdonek@gmail.com>
date	Thu, 11 Oct 2012 16:15:46 -0700
parents	bf8f92580c54
children	315949b1842e

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 :mod:`sqlite3` --- DB-API 2.0 interface for SQLite databases
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 ============================================================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 .. module:: sqlite3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 :synopsis: A DB-API 2.0 implementation using SQLite 3.x.
75360 d2cf730de195 sqlite3: Port relevant documentation changes from 3.2 Petri Lehtinen <petri@digip.org> parents: 74988 diff changeset	6 .. sectionauthor:: Gerhard Häring <gh@ghaering.de>
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9 .. versionadded:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 SQLite is a C library that provides a lightweight disk-based database that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 doesn't require a separate server process and allows accessing the database
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 using a nonstandard variant of the SQL query language. Some applications can use
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 SQLite for internal data storage. It's also possible to prototype an
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 application using SQLite and then port the code to a larger database such as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 PostgreSQL or Oracle.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17
76479 90aa4daf42d3 Minor fixups. Raymond Hettinger <python@rcn.com> parents: 76387 diff changeset	18 The sqlite3 module was written by Gerhard Häring. It provides a SQL interface
90aa4daf42d3 Minor fixups. Raymond Hettinger <python@rcn.com> parents: 76387 diff changeset	19 compliant with the DB-API 2.0 specification described by :pep:`249`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 To use the module, you must first create a :class:`Connection` object that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 represents the database. Here the data will be stored in the
76479 90aa4daf42d3 Minor fixups. Raymond Hettinger <python@rcn.com> parents: 76387 diff changeset	23 :file:`example.db` file::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24
74717 3a5c0f599aca Show the import in the sqlite3 example Raymond Hettinger <python@rcn.com> parents: 74320 diff changeset	25 import sqlite3
76387 d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	26 conn = sqlite3.connect('example.db')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 You can also supply the special name ``:memory:`` to create a database in RAM.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 Once you have a :class:`Connection`, you can create a :class:`Cursor` object
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	31 and call its :meth:`~Cursor.execute` method to perform SQL commands::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33 c = conn.cursor()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 # Create table
76387 d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	36 c.execute('''CREATE TABLE stocks
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	37 (date text, trans text, symbol text, qty real, price real)''')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 # Insert a row of data
76387 d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	40 c.execute("INSERT INTO stocks VALUES ('2006-01-05','BUY','RHAT',100,35.14)")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 # Save (commit) the changes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 conn.commit()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44
79190 1b8e66ea3f89 Show how to close a connection Raymond Hettinger <python@rcn.com> parents: 78681 diff changeset	45 # We can also close the connection if we are done with it.
1b8e66ea3f89 Show how to close a connection Raymond Hettinger <python@rcn.com> parents: 78681 diff changeset	46 # Just be sure any changes have been committed or they will be lost.
1b8e66ea3f89 Show how to close a connection Raymond Hettinger <python@rcn.com> parents: 78681 diff changeset	47 conn.close()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48
76386 f45605e5c037 Clarify that a new connection needs to be made after the close. Raymond Hettinger <python@rcn.com> parents: 75360 diff changeset	49 The data you've saved is persistent and is available in subsequent sessions::
f45605e5c037 Clarify that a new connection needs to be made after the close. Raymond Hettinger <python@rcn.com> parents: 75360 diff changeset	50
f45605e5c037 Clarify that a new connection needs to be made after the close. Raymond Hettinger <python@rcn.com> parents: 75360 diff changeset	51 import sqlite3
76387 d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	52 conn = sqlite3.connect('example.db')
76386 f45605e5c037 Clarify that a new connection needs to be made after the close. Raymond Hettinger <python@rcn.com> parents: 75360 diff changeset	53 c = conn.cursor()
f45605e5c037 Clarify that a new connection needs to be made after the close. Raymond Hettinger <python@rcn.com> parents: 75360 diff changeset	54
76387 d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	55 Usually your SQL operations will need to use values from Python variables. You
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	56 shouldn't assemble your query using Python's string operations because doing so
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	57 is insecure; it makes your program vulnerable to an SQL injection attack
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	58 (see http://xkcd.com/327/ for humorous example of what can go wrong).
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	59
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 Instead, use the DB-API's parameter substitution. Put ``?`` as a placeholder
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61 wherever you want to use a value, and then provide a tuple of values as the
54350 acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	62 second argument to the cursor's :meth:`~Cursor.execute` method. (Other database
acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	63 modules may use a different placeholder, such as ``%s`` or ``:1``.) For
acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	64 example::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 # Never do this -- insecure!
76387 d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	67 symbol = 'RHAT'
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	68 c.execute("SELECT * FROM stocks WHERE symbol = '%s'" % symbol)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 # Do this instead
78681 857c9e1fdd1e #15742: clarify sqlite parameter substitution example. R David Murray <rdmurray@bitdance.com> parents: 76479 diff changeset	71 t = ('RHAT',)
76387 d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	72 c.execute('SELECT * FROM stocks WHERE symbol=?', t)
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	73 print c.fetchone()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74
76387 d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	75 # Larger example that inserts many records at a time
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	76 purchases = [('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	77 ('2006-04-05', 'BUY', 'MSFT', 1000, 72.00),
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	78 ('2006-04-06', 'SELL', 'IBM', 500, 53.00),
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	79 ]
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	80 c.executemany('INSERT INTO stocks VALUES (?,?,?,?,?)', purchases)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81
43630 6df985744d96 Add :term:s for iterator. Georg Brandl <georg@python.org> parents: 43629 diff changeset	82 To retrieve data after executing a SELECT statement, you can either treat the
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	83 cursor as an :term:`iterator`, call the cursor's :meth:`~Cursor.fetchone` method to
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	84 retrieve a single matching row, or call :meth:`~Cursor.fetchall` to get a list of the
43630 6df985744d96 Add :term:s for iterator. Georg Brandl <georg@python.org> parents: 43629 diff changeset	85 matching rows.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 This example uses the iterator form::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88
76387 d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	89 >>> for row in c.execute('SELECT * FROM stocks ORDER BY price'):
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	90 print row
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	91
57428 337ebb829b8c Fix some documentation examples involving the repr of a float. Mark Dickinson <dickinsm@gmail.com> parents: 55449 diff changeset	92 (u'2006-01-05', u'BUY', u'RHAT', 100, 35.14)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 (u'2006-03-28', u'BUY', u'IBM', 1000, 45.0)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 (u'2006-04-06', u'SELL', u'IBM', 500, 53.0)
74320 068ce5d7f7e7 Fix stock symbol for Microsoft Raymond Hettinger <python@rcn.com> parents: 72984 diff changeset	95 (u'2006-04-05', u'BUY', u'MSFT', 1000, 72.0)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 .. seealso::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99
61489 e7629efc55d0 Merged revisions 78581 via svnmerge from Georg Brandl <georg@python.org> parents: 58894 diff changeset	100 http://code.google.com/p/pysqlite/
54350 acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	101 The pysqlite web page -- sqlite3 is developed externally under the name
acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	102 "pysqlite".
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 http://www.sqlite.org
54350 acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	105 The SQLite web page; the documentation describes the syntax and the
acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	106 available data types for the supported SQL dialect.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107
76387 d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	108 http://www.w3schools.com/sql/
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	109 Tutorial, reference and examples for learning SQL syntax.
d229032dc213 Clean-up the SQLite introduction. Raymond Hettinger <python@rcn.com> parents: 76386 diff changeset	110
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 :pep:`249` - Database API Specification 2.0
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 PEP written by Marc-André Lemburg.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 .. _sqlite3-module-contents:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 Module functions and constants
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 ------------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 .. data:: PARSE_DECLTYPES
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 This constant is meant to be used with the detect_types parameter of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 :func:`connect` function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 Setting it makes the :mod:`sqlite3` module parse the declared type for each
46659 28b099ac4cd8 Implemented feature request 2157: Converter names are cut off at '(' Gerhard Häring <gh@ghaering.de> parents: 46198 diff changeset	127 column it returns. It will parse out the first word of the declared type,
28b099ac4cd8 Implemented feature request 2157: Converter names are cut off at '(' Gerhard Häring <gh@ghaering.de> parents: 46198 diff changeset	128 i. e. for "integer primary key", it will parse out "integer", or for
28b099ac4cd8 Implemented feature request 2157: Converter names are cut off at '(' Gerhard Häring <gh@ghaering.de> parents: 46198 diff changeset	129 "number(10)" it will parse out "number". Then for that column, it will look
28b099ac4cd8 Implemented feature request 2157: Converter names are cut off at '(' Gerhard Häring <gh@ghaering.de> parents: 46198 diff changeset	130 into the converters dictionary and use the converter function registered for
28b099ac4cd8 Implemented feature request 2157: Converter names are cut off at '(' Gerhard Häring <gh@ghaering.de> parents: 46198 diff changeset	131 that type there.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 .. data:: PARSE_COLNAMES
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 This constant is meant to be used with the detect_types parameter of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137 :func:`connect` function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 Setting this makes the SQLite interface parse the column name for each column it
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 returns. It will look for a string formed [mytype] in there, and then decide
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 that 'mytype' is the type of the column. It will try to find an entry of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 'mytype' in the converters dictionary and then use the converter function found
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	143 there to return the value. The column name found in :attr:`Cursor.description`
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 is only the first word of the column name, i. e. if you use something like
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 ``'as "x [datetime]"'`` in your SQL, then we will parse out everything until the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 first blank for the column name: the column name would simply be "x".
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148
65126 64989b03398c Merged revisions 82757-82758,82760-82764 via svnmerge from Georg Brandl <georg@python.org> parents: 63762 diff changeset	149 .. function:: connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151 Opens a connection to the SQLite database file database. You can use
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 ``":memory:"`` to open a database connection to a database that resides in RAM
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 instead of on disk.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 When a database is accessed by multiple connections, and one of the processes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156 modifies the database, the SQLite database is locked until that transaction is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 committed. The timeout parameter specifies how long the connection should wait
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158 for the lock to go away until raising an exception. The default for the timeout
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159 parameter is 5.0 (five seconds).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 For the isolation_level parameter, please see the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 :attr:`Connection.isolation_level` property of :class:`Connection` objects.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164 SQLite natively supports only the types TEXT, INTEGER, FLOAT, BLOB and NULL. If
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165 you want to use other types you must add support for them yourself. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166 detect_types parameter and the using custom converters registered with the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 module-level :func:`register_converter` function allow you to easily do that.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 detect_types defaults to 0 (i. e. off, no type detection), you can set it to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170 any combination of :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES` to turn
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 type detection on.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173 By default, the :mod:`sqlite3` module uses its :class:`Connection` class for the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174 connect call. You can, however, subclass the :class:`Connection` class and make
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175 :func:`connect` use your class instead by providing your class for the factory
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176 parameter.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178 Consult the section :ref:`sqlite3-types` of this manual for details.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180 The :mod:`sqlite3` module internally uses a statement cache to avoid SQL parsing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181 overhead. If you want to explicitly set the number of statements that are cached
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182 for the connection, you can set the cached_statements parameter. The currently
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 implemented default is to cache 100 statements.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 .. function:: register_converter(typename, callable)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 Registers a callable to convert a bytestring from the database into a custom
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 Python type. The callable will be invoked for all database values that are of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190 the type typename. Confer the parameter detect_types of the :func:`connect`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191 function for how the type detection works. Note that the case of typename and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192 the name of the type in your query must match!
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195 .. function:: register_adapter(type, callable)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 Registers a callable to convert the custom Python type type into one of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198 SQLite's supported types. The callable callable accepts as single parameter
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 the Python value, and must return a value of the following types: int, long,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 float, str (UTF-8 encoded), unicode or buffer.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 .. function:: complete_statement(sql)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 Returns :const:`True` if the string sql contains one or more complete SQL
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206 statements terminated by semicolons. It does not verify that the SQL is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 syntactically correct, only that there are no unclosed string literals and the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 statement is terminated by a semicolon.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 This can be used to build a shell for SQLite, as in the following example:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213 .. literalinclude:: ../includes/sqlite3/complete_statement.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216 .. function:: enable_callback_tracebacks(flag)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 By default you will not get any tracebacks in user-defined functions,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 aggregates, converters, authorizer callbacks etc. If you want to debug them, you
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 can call this function with flag as True. Afterwards, you will get tracebacks
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221 from callbacks on ``sys.stderr``. Use :const:`False` to disable the feature
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222 again.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 .. _sqlite3-connection-objects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227 Connection Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 ------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	230 .. class:: Connection
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	231
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	232 A SQLite database connection has the following attributes and methods:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	234 .. attribute:: isolation_level
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	236 Get or set the current isolation level. :const:`None` for autocommit mode or
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	237 one of "DEFERRED", "IMMEDIATE" or "EXCLUSIVE". See section
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	238 :ref:`sqlite3-controlling-transactions` for a more detailed explanation.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	241 .. method:: cursor([cursorClass])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	243 The cursor method accepts a single optional parameter cursorClass. If
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	244 supplied, this must be a custom cursor class that extends
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	245 :class:`sqlite3.Cursor`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	247 .. method:: commit()
46180 0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	248
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	249 This method commits the current transaction. If you don't call this method,
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	250 anything you did since the last call to ``commit()`` is not visible from
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	251 other database connections. If you wonder why you don't see the data you've
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	252 written to the database, please check you didn't forget to call this method.
46180 0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	253
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	254 .. method:: rollback()
46180 0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	255
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	256 This method rolls back any changes to the database since the last call to
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	257 :meth:`commit`.
46180 0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	258
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	259 .. method:: close()
46180 0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	260
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	261 This closes the database connection. Note that this does not automatically
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	262 call :meth:`commit`. If you just close your database connection without
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	263 calling :meth:`commit` first, your changes will be lost!
46180 0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	264
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	265 .. method:: execute(sql, [parameters])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	267 This is a nonstandard shortcut that creates an intermediate cursor object by
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	268 calling the cursor method, then calls the cursor's :meth:`execute
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	269 <Cursor.execute>` method with the parameters given.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	272 .. method:: executemany(sql, [parameters])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	274 This is a nonstandard shortcut that creates an intermediate cursor object by
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	275 calling the cursor method, then calls the cursor's :meth:`executemany
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	276 <Cursor.executemany>` method with the parameters given.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	278 .. method:: executescript(sql_script)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	280 This is a nonstandard shortcut that creates an intermediate cursor object by
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	281 calling the cursor method, then calls the cursor's :meth:`executescript
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	282 <Cursor.executescript>` method with the parameters given.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	285 .. method:: create_function(name, num_params, func)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	287 Creates a user-defined function that you can later use from within SQL
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	288 statements under the function name name. num_params is the number of
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	289 parameters the function accepts, and func is a Python callable that is called
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	290 as the SQL function.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	292 The function can return any of the types supported by SQLite: unicode, str, int,
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	293 long, float, buffer and None.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	295 Example:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	297 .. literalinclude:: ../includes/sqlite3/md5func.py
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	300 .. method:: create_aggregate(name, num_params, aggregate_class)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	302 Creates a user-defined aggregate function.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	304 The aggregate class must implement a ``step`` method, which accepts the number
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	305 of parameters num_params, and a ``finalize`` method which will return the
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	306 final result of the aggregate.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	308 The ``finalize`` method can return any of the types supported by SQLite:
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	309 unicode, str, int, long, float, buffer and None.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	311 Example:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	313 .. literalinclude:: ../includes/sqlite3/mysumaggr.py
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	316 .. method:: create_collation(name, callable)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	318 Creates a collation with the specified name and callable. The callable will
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	319 be passed two string arguments. It should return -1 if the first is ordered
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	320 lower than the second, 0 if they are ordered equal and 1 if the first is ordered
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	321 higher than the second. Note that this controls sorting (ORDER BY in SQL) so
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	322 your comparisons don't affect other SQL operations.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	324 Note that the callable will get its parameters as Python bytestrings, which will
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	325 normally be encoded in UTF-8.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	327 The following example shows a custom collation that sorts "the wrong way":
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	329 .. literalinclude:: ../includes/sqlite3/collation_reverse.py
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	331 To remove a collation, call ``create_collation`` with None as callable::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	333 con.create_collation("reverse", None)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	336 .. method:: interrupt()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	338 You can call this method from a different thread to abort any queries that might
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	339 be executing on the connection. The query will then abort and the caller will
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	340 get an exception.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	343 .. method:: set_authorizer(authorizer_callback)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	345 This routine registers a callback. The callback is invoked for each attempt to
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	346 access a column of a table in the database. The callback should return
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	347 :const:`SQLITE_OK` if access is allowed, :const:`SQLITE_DENY` if the entire SQL
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	348 statement should be aborted with an error and :const:`SQLITE_IGNORE` if the
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	349 column should be treated as a NULL value. These constants are available in the
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	350 :mod:`sqlite3` module.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	351
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	352 The first argument to the callback signifies what kind of operation is to be
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	353 authorized. The second and third argument will be arguments or :const:`None`
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	354 depending on the first argument. The 4th argument is the name of the database
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	355 ("main", "temp", etc.) if applicable. The 5th argument is the name of the
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	356 inner-most trigger or view that is responsible for the access attempt or
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	357 :const:`None` if this access attempt is directly from input SQL code.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	359 Please consult the SQLite documentation about the possible values for the first
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	360 argument and the meaning of the second and third argument depending on the first
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	361 one. All necessary constants are available in the :mod:`sqlite3` module.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	364 .. method:: set_progress_handler(handler, n)
46180 0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	365
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	366 This routine registers a callback. The callback is invoked for every n
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	367 instructions of the SQLite virtual machine. This is useful if you want to
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	368 get called from SQLite during long-running operations, for example to update
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	369 a GUI.
46180 0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	370
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	371 If you want to clear any previously installed progress handler, call the
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	372 method with :const:`None` for handler.
46180 0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	373
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	374 .. versionadded:: 2.6
75360 d2cf730de195 sqlite3: Port relevant documentation changes from 3.2 Petri Lehtinen <petri@digip.org> parents: 74988 diff changeset	375
46180 0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	376
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	377 .. method:: enable_load_extension(enabled)
59362 04d3ae52ff73 Merged code from pysqlite 2.6.0. Gerhard Häring <gh@ghaering.de> parents: 59262 diff changeset	378
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	379 This routine allows/disallows the SQLite engine to load SQLite extensions
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	380 from shared libraries. SQLite extensions can define new functions,
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	381 aggregates or whole new virtual table implementations. One well-known
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	382 extension is the fulltext-search extension distributed with SQLite.
59362 04d3ae52ff73 Merged code from pysqlite 2.6.0. Gerhard Häring <gh@ghaering.de> parents: 59262 diff changeset	383
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	384 Loadable extensions are disabled by default. See [#f1]_.
75360 d2cf730de195 sqlite3: Port relevant documentation changes from 3.2 Petri Lehtinen <petri@digip.org> parents: 74988 diff changeset	385
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	386 .. versionadded:: 2.7
75360 d2cf730de195 sqlite3: Port relevant documentation changes from 3.2 Petri Lehtinen <petri@digip.org> parents: 74988 diff changeset	387
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	388 .. literalinclude:: ../includes/sqlite3/load_extension.py
59362 04d3ae52ff73 Merged code from pysqlite 2.6.0. Gerhard Häring <gh@ghaering.de> parents: 59262 diff changeset	389
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	390 .. method:: load_extension(path)
59362 04d3ae52ff73 Merged code from pysqlite 2.6.0. Gerhard Häring <gh@ghaering.de> parents: 59262 diff changeset	391
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	392 This routine loads a SQLite extension from a shared library. You have to
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	393 enable extension loading with :meth:`enable_load_extension` before you can
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	394 use this routine.
59362 04d3ae52ff73 Merged code from pysqlite 2.6.0. Gerhard Häring <gh@ghaering.de> parents: 59262 diff changeset	395
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	396 Loadable extensions are disabled by default. See [#f1]_.
75360 d2cf730de195 sqlite3: Port relevant documentation changes from 3.2 Petri Lehtinen <petri@digip.org> parents: 74988 diff changeset	397
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	398 .. versionadded:: 2.7
70986 804a60029091 Fix Issue10020 - Doc update to sqlite3 module in 2.7 branch. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	399
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	400 .. attribute:: row_factory
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	402 You can change this attribute to a callable that accepts the cursor and the
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	403 original row as a tuple and will return the real result row. This way, you can
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	404 implement more advanced ways of returning results, such as returning an object
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	405 that can also access columns by name.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	407 Example:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	409 .. literalinclude:: ../includes/sqlite3/row_factory.py
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	411 If returning a tuple doesn't suffice and you want name-based access to
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	412 columns, you should consider setting :attr:`row_factory` to the
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	413 highly-optimized :class:`sqlite3.Row` type. :class:`Row` provides both
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	414 index-based and case-insensitive name-based access to columns with almost no
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	415 memory overhead. It will probably be better than your own custom
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	416 dictionary-based approach or even a db_row based solution.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	418 .. XXX what's a db_row-based solution?
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	421 .. attribute:: text_factory
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	423 Using this attribute you can control what objects are returned for the ``TEXT``
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	424 data type. By default, this attribute is set to :class:`unicode` and the
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	425 :mod:`sqlite3` module will return Unicode objects for ``TEXT``. If you want to
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	426 return bytestrings instead, you can set it to :class:`str`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	428 For efficiency reasons, there's also a way to return Unicode objects only for
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	429 non-ASCII data, and bytestrings otherwise. To activate it, set this attribute to
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	430 :const:`sqlite3.OptimizedUnicode`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	432 You can also set it to any other callable that accepts a single bytestring
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	433 parameter and returns the resulting object.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	435 See the following example code for illustration:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	436
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	437 .. literalinclude:: ../includes/sqlite3/text_factory.py
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	440 .. attribute:: total_changes
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	442 Returns the total number of database rows that have been modified, inserted, or
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	443 deleted since the database connection was opened.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	446 .. attribute:: iterdump
46159 f9a629f41656 Accept patch issue2426 by Paul Kippes (kippesp). Gregory P. Smith <greg@mad-scientist.com> parents: 44791 diff changeset	447
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	448 Returns an iterator to dump the database in an SQL text format. Useful when
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	449 saving an in-memory database for later restoration. This function provides
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	450 the same capabilities as the :kbd:`.dump` command in the :program:`sqlite3`
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	451 shell.
46159 f9a629f41656 Accept patch issue2426 by Paul Kippes (kippesp). Gregory P. Smith <greg@mad-scientist.com> parents: 44791 diff changeset	452
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	453 .. versionadded:: 2.6
46159 f9a629f41656 Accept patch issue2426 by Paul Kippes (kippesp). Gregory P. Smith <greg@mad-scientist.com> parents: 44791 diff changeset	454
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	455 Example::
46159 f9a629f41656 Accept patch issue2426 by Paul Kippes (kippesp). Gregory P. Smith <greg@mad-scientist.com> parents: 44791 diff changeset	456
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	457 # Convert file existing_db.db to SQL dump file dump.sql
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	458 import sqlite3, os
46159 f9a629f41656 Accept patch issue2426 by Paul Kippes (kippesp). Gregory P. Smith <greg@mad-scientist.com> parents: 44791 diff changeset	459
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	460 con = sqlite3.connect('existing_db.db')
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	461 with open('dump.sql', 'w') as f:
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	462 for line in con.iterdump():
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	463 f.write('%s\n' % line)
46159 f9a629f41656 Accept patch issue2426 by Paul Kippes (kippesp). Gregory P. Smith <greg@mad-scientist.com> parents: 44791 diff changeset	464
f9a629f41656 Accept patch issue2426 by Paul Kippes (kippesp). Gregory P. Smith <greg@mad-scientist.com> parents: 44791 diff changeset	465
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466 .. _sqlite3-cursor-objects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468 Cursor Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469 --------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	470
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	471 .. class:: Cursor
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472
66456 77771b085eca Merged revisions 85548,85572-85573,85606,85609-85612,85614-85616 via svnmerge from Georg Brandl <georg@python.org> parents: 65126 diff changeset	473 A :class:`Cursor` instance has the following attributes and methods.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	475 .. method:: execute(sql, [parameters])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	476
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	477 Executes an SQL statement. The SQL statement may be parameterized (i. e.
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	478 placeholders instead of SQL literals). The :mod:`sqlite3` module supports two
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	479 kinds of placeholders: question marks (qmark style) and named placeholders
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	480 (named style).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	482 Here's an example of both styles:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	484 .. literalinclude:: ../includes/sqlite3/execute_1.py
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	486 :meth:`execute` will only execute a single SQL statement. If you try to execute
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	487 more than one statement with it, it will raise a Warning. Use
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	488 :meth:`executescript` if you want to execute multiple SQL statements with one
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	489 call.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	492 .. method:: executemany(sql, seq_of_parameters)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	494 Executes an SQL command against all parameter sequences or mappings found in
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	495 the sequence sql. The :mod:`sqlite3` module also allows using an
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	496 :term:`iterator` yielding parameters instead of a sequence.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	498 .. literalinclude:: ../includes/sqlite3/executemany_1.py
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	500 Here's a shorter example using a :term:`generator`:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	501
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	502 .. literalinclude:: ../includes/sqlite3/executemany_2.py
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	505 .. method:: executescript(sql_script)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	507 This is a nonstandard convenience method for executing multiple SQL statements
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	508 at once. It issues a ``COMMIT`` statement first, then executes the SQL script it
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	509 gets as a parameter.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	511 sql_script can be a bytestring or a Unicode string.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	513 Example:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	515 .. literalinclude:: ../includes/sqlite3/executescript.py
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	518 .. method:: fetchone()
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50004 diff changeset	519
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	520 Fetches the next row of a query result set, returning a single sequence,
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	521 or :const:`None` when no more data is available.
44791 15536865198a #1509: fix sqlite3 docstrings and docs w.r.t. cursor.fetchXXX methods. Georg Brandl <georg@python.org> parents: 44383 diff changeset	522
15536865198a #1509: fix sqlite3 docstrings and docs w.r.t. cursor.fetchXXX methods. Georg Brandl <georg@python.org> parents: 44383 diff changeset	523
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	524 .. method:: fetchmany([size=cursor.arraysize])
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50004 diff changeset	525
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	526 Fetches the next set of rows of a query result, returning a list. An empty
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	527 list is returned when no more rows are available.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50004 diff changeset	528
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	529 The number of rows to fetch per call is specified by the size parameter.
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	530 If it is not given, the cursor's arraysize determines the number of rows
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	531 to be fetched. The method should try to fetch as many rows as indicated by
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	532 the size parameter. If this is not possible due to the specified number of
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	533 rows not being available, fewer rows may be returned.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50004 diff changeset	534
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	535 Note there are performance considerations involved with the size parameter.
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	536 For optimal performance, it is usually best to use the arraysize attribute.
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	537 If the size parameter is used, then it is best for it to retain the same
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	538 value from one :meth:`fetchmany` call to the next.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50004 diff changeset	539
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	540 .. method:: fetchall()
44791 15536865198a #1509: fix sqlite3 docstrings and docs w.r.t. cursor.fetchXXX methods. Georg Brandl <georg@python.org> parents: 44383 diff changeset	541
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	542 Fetches all (remaining) rows of a query result, returning a list. Note that
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	543 the cursor's arraysize attribute can affect the performance of this operation.
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	544 An empty list is returned when no rows are available.
44791 15536865198a #1509: fix sqlite3 docstrings and docs w.r.t. cursor.fetchXXX methods. Georg Brandl <georg@python.org> parents: 44383 diff changeset	545
15536865198a #1509: fix sqlite3 docstrings and docs w.r.t. cursor.fetchXXX methods. Georg Brandl <georg@python.org> parents: 44383 diff changeset	546
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	547 .. attribute:: rowcount
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	549 Although the :class:`Cursor` class of the :mod:`sqlite3` module implements this
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	550 attribute, the database engine's own support for the determination of "rows
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	551 affected"/"rows selected" is quirky.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	552
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	553 For :meth:`executemany` statements, the number of modifications are summed up
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	554 into :attr:`rowcount`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	555
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	556 As required by the Python DB API Spec, the :attr:`rowcount` attribute "is -1 in
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	557 case no ``executeXX()`` has been performed on the cursor or the rowcount of the
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	558 last operation is not determinable by the interface". This includes ``SELECT``
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	559 statements because we cannot determine the number of rows a query produced
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	560 until all rows were fetched.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	561
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	562 With SQLite versions before 3.6.5, :attr:`rowcount` is set to 0 if
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	563 you make a ``DELETE FROM table`` without any condition.
42775 d7517c306791 Merged revisions 57221-57391 via svnmerge from Guido van Rossum <guido@python.org> parents: 42604 diff changeset	564
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	565 .. attribute:: lastrowid
46198 e4486c343f7f Documented the lastrowid attribute. Gerhard Häring <gh@ghaering.de> parents: 46180 diff changeset	566
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	567 This read-only attribute provides the rowid of the last modified row. It is
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	568 only set if you issued a ``INSERT`` statement using the :meth:`execute`
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	569 method. For operations other than ``INSERT`` or when :meth:`executemany` is
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	570 called, :attr:`lastrowid` is set to :const:`None`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	571
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	572 .. attribute:: description
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	573
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	574 This read-only attribute provides the column names of the last query. To
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	575 remain compatible with the Python DB API, it returns a 7-tuple for each
bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	576 column where the last six items of each tuple are :const:`None`.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50004 diff changeset	577
79356 bf8f92580c54 Fix sqlite3 class markup. R David Murray <rdmurray@bitdance.com> parents: 79190 diff changeset	578 It is set for ``SELECT`` statements without any matching rows as well.
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	579
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	580 .. _sqlite3-row-objects:
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	581
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	582 Row Objects
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	583 -----------
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	584
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	585 .. class:: Row
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	586
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	587 A :class:`Row` instance serves as a highly optimized
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50004 diff changeset	588 :attr:`~Connection.row_factory` for :class:`Connection` objects.
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	589 It tries to mimic a tuple in most of its features.
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	590
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	591 It supports mapping access by column name and index, iteration,
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	592 representation, equality testing and :func:`len`.
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	593
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	594 If two :class:`Row` objects have exactly the same columns and their
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	595 members are equal, they compare equal.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50004 diff changeset	596
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	597 .. versionchanged:: 2.6
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	598 Added iteration and equality (hashability).
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	599
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	600 .. method:: keys
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	601
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	602 This method returns a tuple of column names. Immediately after a query,
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	603 it is the first member of each tuple in :attr:`Cursor.description`.
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	604
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	605 .. versionadded:: 2.6
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	606
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	607 Let's assume we initialize a table as in the example given above::
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	608
71145 08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	609 conn = sqlite3.connect(":memory:")
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	610 c = conn.cursor()
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	611 c.execute('''create table stocks
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	612 (date text, trans text, symbol text,
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	613 qty real, price real)''')
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	614 c.execute("""insert into stocks
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	615 values ('2006-01-05','BUY','RHAT',100,35.14)""")
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	616 conn.commit()
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	617 c.close()
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	618
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	619 Now we plug :class:`Row` in::
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	620
71145 08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	621 >>> conn.row_factory = sqlite3.Row
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	622 >>> c = conn.cursor()
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	623 >>> c.execute('select * from stocks')
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	624 <sqlite3.Cursor object at 0x7f4e7dd8fa80>
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	625 >>> r = c.fetchone()
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	626 >>> type(r)
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	627 <type 'sqlite3.Row'>
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	628 >>> r
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	629 (u'2006-01-05', u'BUY', u'RHAT', 100.0, 35.14)
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	630 >>> len(r)
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	631 5
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	632 >>> r[2]
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	633 u'RHAT'
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	634 >>> r.keys()
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	635 ['date', 'trans', 'symbol', 'qty', 'price']
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	636 >>> r['qty']
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	637 100.0
75360 d2cf730de195 sqlite3: Port relevant documentation changes from 3.2 Petri Lehtinen <petri@digip.org> parents: 74988 diff changeset	638 >>> for member in r:
d2cf730de195 sqlite3: Port relevant documentation changes from 3.2 Petri Lehtinen <petri@digip.org> parents: 74988 diff changeset	639 ... print member
71145 08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	640 ...
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	641 2006-01-05
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	642 BUY
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	643 RHAT
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	644 100.0
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	645 35.14
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	646
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	647
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	648 .. _sqlite3-types:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	649
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	650 SQLite and Python types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	651 -----------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	652
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	654 Introduction
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	655 ^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	657 SQLite natively supports the following types: ``NULL``, ``INTEGER``,
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	658 ``REAL``, ``TEXT``, ``BLOB``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	659
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	660 The following Python types can thus be sent to SQLite without any problem:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	661
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	662 +-----------------------------+-------------+
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	663 \| Python type \| SQLite type \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	664 +=============================+=============+
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	665 \| :const:`None` \| ``NULL`` \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	666 +-----------------------------+-------------+
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	667 \| :class:`int` \| ``INTEGER`` \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	668 +-----------------------------+-------------+
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	669 \| :class:`long` \| ``INTEGER`` \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	670 +-----------------------------+-------------+
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	671 \| :class:`float` \| ``REAL`` \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	672 +-----------------------------+-------------+
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	673 \| :class:`str` (UTF8-encoded) \| ``TEXT`` \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	674 +-----------------------------+-------------+
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	675 \| :class:`unicode` \| ``TEXT`` \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	676 +-----------------------------+-------------+
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	677 \| :class:`buffer` \| ``BLOB`` \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	678 +-----------------------------+-------------+
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	680 This is how SQLite types are converted to Python types by default:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	681
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	682 +-------------+----------------------------------------------+
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	683 \| SQLite type \| Python type \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	684 +=============+==============================================+
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	685 \| ``NULL`` \| :const:`None` \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	686 +-------------+----------------------------------------------+
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	687 \| ``INTEGER`` \| :class:`int` or :class:`long`, \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	688 \| \| depending on size \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	689 +-------------+----------------------------------------------+
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	690 \| ``REAL`` \| :class:`float` \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	691 +-------------+----------------------------------------------+
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	692 \| ``TEXT`` \| depends on :attr:`~Connection.text_factory`, \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	693 \| \| :class:`unicode` by default \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	694 +-------------+----------------------------------------------+
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	695 \| ``BLOB`` \| :class:`buffer` \|
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	696 +-------------+----------------------------------------------+
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	697
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698 The type system of the :mod:`sqlite3` module is extensible in two ways: you can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	699 store additional Python types in a SQLite database via object adaptation, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700 you can let the :mod:`sqlite3` module convert SQLite types to different Python
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701 types via converters.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	703
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704 Using adapters to store additional Python types in SQLite databases
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	706
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	707 As described before, SQLite supports only a limited set of types natively. To
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	708 use other Python types with SQLite, you must adapt them to one of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	709 sqlite3 module's supported types for SQLite: one of NoneType, int, long, float,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	710 str, unicode, buffer.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	711
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	712 The :mod:`sqlite3` module uses Python object adaptation, as described in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	713 :pep:`246` for this. The protocol to use is :class:`PrepareProtocol`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	714
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	715 There are two ways to enable the :mod:`sqlite3` module to adapt a custom Python
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	716 type to one of the supported ones.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	718
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719 Letting your object adapt itself
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	720 """"""""""""""""""""""""""""""""
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	721
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	722 This is a good approach if you write the class yourself. Let's suppose you have
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723 a class like this::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725 class Point(object):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	726 def __init__(self, x, y):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727 self.x, self.y = x, y
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	728
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	729 Now you want to store the point in a single SQLite column. First you'll have to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730 choose one of the supported types first to be used for representing the point.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731 Let's just use str and separate the coordinates using a semicolon. Then you need
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732 to give your class a method ``__conform__(self, protocol)`` which must return
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733 the converted value. The parameter protocol will be :class:`PrepareProtocol`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	735 .. literalinclude:: ../includes/sqlite3/adapter_point_1.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	736
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738 Registering an adapter callable
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	739 """""""""""""""""""""""""""""""
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	740
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	741 The other possibility is to create a function that converts the type to the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	742 string representation and register the function with :meth:`register_adapter`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744 .. note::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745
43631 03056365a1b6 Add :term:s for "new-style class". Georg Brandl <georg@python.org> parents: 43630 diff changeset	746 The type/class to adapt must be a :term:`new-style class`, i. e. it must have
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747 :class:`object` as one of its bases.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749 .. literalinclude:: ../includes/sqlite3/adapter_point_2.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	750
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751 The :mod:`sqlite3` module has two default adapters for Python's built-in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752 :class:`datetime.date` and :class:`datetime.datetime` types. Now let's suppose
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753 we want to store :class:`datetime.datetime` objects not in ISO representation,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754 but as a Unix timestamp.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	755
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756 .. literalinclude:: ../includes/sqlite3/adapter_datetime.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	757
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	758
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	759 Converting SQLite values to custom Python types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	760 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	761
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	762 Writing an adapter lets you send custom Python types to SQLite. But to make it
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	763 really useful we need to make the Python to SQLite to Python roundtrip work.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	764
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765 Enter converters.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	766
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767 Let's go back to the :class:`Point` class. We stored the x and y coordinates
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768 separated via semicolons as strings in SQLite.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	770 First, we'll define a converter function that accepts the string as a parameter
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771 and constructs a :class:`Point` object from it.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773 .. note::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	775 Converter functions always get called with a string, no matter under which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	776 data type you sent the value to SQLite.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	778 ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	779
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	780 def convert_point(s):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	781 x, y = map(float, s.split(";"))
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782 return Point(x, y)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	783
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784 Now you need to make the :mod:`sqlite3` module know that what you select from
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	785 the database is actually a point. There are two ways of doing this:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	786
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787 * Implicitly via the declared type
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	788
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	789 * Explicitly via the column name
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	790
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	791 Both ways are described in section :ref:`sqlite3-module-contents`, in the entries
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	792 for the constants :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	793
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	794 The following example illustrates both approaches.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	795
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	796 .. literalinclude:: ../includes/sqlite3/converter_point.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	798
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	799 Default adapters and converters
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	800 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	801
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	802 There are default adapters for the date and datetime types in the datetime
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	803 module. They will be sent as ISO dates/ISO timestamps to SQLite.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	804
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	805 The default converters are registered under the name "date" for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	806 :class:`datetime.date` and under the name "timestamp" for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	807 :class:`datetime.datetime`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	808
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	809 This way, you can use date/timestamps from Python without any additional
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	810 fiddling in most cases. The format of the adapters is also compatible with the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	811 experimental SQLite date/time functions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	812
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	813 The following example demonstrates this.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	814
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	815 .. literalinclude:: ../includes/sqlite3/pysqlite_datetime.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	816
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	817
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	818 .. _sqlite3-controlling-transactions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	819
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	820 Controlling Transactions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	821 ------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	822
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	823 By default, the :mod:`sqlite3` module opens transactions implicitly before a
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50004 diff changeset	824 Data Modification Language (DML) statement (i.e.
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	825 ``INSERT``/``UPDATE``/``DELETE``/``REPLACE``), and commits transactions
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	826 implicitly before a non-DML, non-query statement (i. e.
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	827 anything other than ``SELECT`` or the aforementioned).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	828
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	829 So if you are within a transaction and issue a command like ``CREATE TABLE
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	830 ...``, ``VACUUM``, ``PRAGMA``, the :mod:`sqlite3` module will commit implicitly
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	831 before executing that command. There are two reasons for doing that. The first
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	832 is that some of these commands don't work within transactions. The other reason
54350 acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	833 is that sqlite3 needs to keep track of the transaction state (if a transaction
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	834 is active or not).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	835
54350 acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	836 You can control which kind of ``BEGIN`` statements sqlite3 implicitly executes
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	837 (or none at all) via the isolation_level parameter to the :func:`connect`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	838 call, or via the :attr:`isolation_level` property of connections.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	839
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	840 If you want autocommit mode, then set :attr:`isolation_level` to None.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	841
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	842 Otherwise leave it at its default, which will result in a plain "BEGIN"
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	843 statement, or set it to one of SQLite's supported isolation levels: "DEFERRED",
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	844 "IMMEDIATE" or "EXCLUSIVE".
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	845
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	846
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	847
54350 acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	848 Using :mod:`sqlite3` efficiently
acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	849 --------------------------------
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	850
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	851
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	852 Using shortcut methods
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	853 ^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	854
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	855 Using the nonstandard :meth:`execute`, :meth:`executemany` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	856 :meth:`executescript` methods of the :class:`Connection` object, your code can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	857 be written more concisely because you don't have to create the (often
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	858 superfluous) :class:`Cursor` objects explicitly. Instead, the :class:`Cursor`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	859 objects are created implicitly and these shortcut methods return the cursor
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49052 diff changeset	860 objects. This way, you can execute a ``SELECT`` statement and iterate over it
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	861 directly using only a single call on the :class:`Connection` object.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	862
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	863 .. literalinclude:: ../includes/sqlite3/shortcut_methods.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	864
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	865
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	866 Accessing columns by name instead of by index
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	867 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	868
56818 3e15a07a32fa Merged revisions 74209 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	869 One useful feature of the :mod:`sqlite3` module is the built-in
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	870 :class:`sqlite3.Row` class designed to be used as a row factory.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	871
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	872 Rows wrapped with this class can be accessed both by index (like tuples) and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	873 case-insensitively by name:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	874
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	875 .. literalinclude:: ../includes/sqlite3/rowclass.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	876
46180 0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	877
0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	878 Using the connection as a context manager
0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	879 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	880
0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	881 .. versionadded:: 2.6
0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	882
0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	883 Connection objects can be used as context managers
0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	884 that automatically commit or rollback transactions. In the event of an
0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	885 exception, the transaction is rolled back; otherwise, the transaction is
0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	886 committed:
0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	887
0ea5c055ab54 Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which Gerhard Häring <gh@ghaering.de> parents: 46159 diff changeset	888 .. literalinclude:: ../includes/sqlite3/ctx_manager.py
63762 fcb7e35924e6 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 59362 diff changeset	889
fcb7e35924e6 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 59362 diff changeset	890
fcb7e35924e6 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 59362 diff changeset	891 Common issues
fcb7e35924e6 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 59362 diff changeset	892 -------------
fcb7e35924e6 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 59362 diff changeset	893
fcb7e35924e6 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 59362 diff changeset	894 Multithreading
fcb7e35924e6 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 59362 diff changeset	895 ^^^^^^^^^^^^^^
fcb7e35924e6 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 59362 diff changeset	896
fcb7e35924e6 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 59362 diff changeset	897 Older SQLite versions had issues with sharing connections between threads.
fcb7e35924e6 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 59362 diff changeset	898 That's why the Python module disallows sharing connections and cursors between
fcb7e35924e6 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 59362 diff changeset	899 threads. If you still try to do so, you will get an exception at runtime.
fcb7e35924e6 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 59362 diff changeset	900
fcb7e35924e6 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 59362 diff changeset	901 The only exception is calling the :meth:`~Connection.interrupt` method, which
fcb7e35924e6 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 59362 diff changeset	902 only makes sense to call from a different thread.
70986 804a60029091 Fix Issue10020 - Doc update to sqlite3 module in 2.7 branch. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	903
804a60029091 Fix Issue10020 - Doc update to sqlite3 module in 2.7 branch. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	904 .. rubric:: Footnotes
804a60029091 Fix Issue10020 - Doc update to sqlite3 module in 2.7 branch. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	905
804a60029091 Fix Issue10020 - Doc update to sqlite3 module in 2.7 branch. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	906 .. [#f1] The sqlite3 module is not built with loadable extension support by
71145 08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	907 default, because some platforms (notably Mac OS X) have SQLite libraries
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	908 which are compiled without this feature. To get loadable extension support,
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	909 you must modify setup.py and remove the line that sets
08400969067e reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 70986 diff changeset	910 SQLITE_OMIT_LOAD_EXTENSION.
70986 804a60029091 Fix Issue10020 - Doc update to sqlite3 module in 2.7 branch. Senthil Kumaran <senthil@uthcode.com> parents: 68256 diff changeset	911

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/sqlite3.rst @ 79675:c0a2294de787 2.7