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

annotate Doc/library/sqlite3.rst @ 78069:a8aa77458e12 3.2

Add c_size_t and c_ssize_t to the ctypes summary table.

author	Antoine Pitrou <solipsis@pitrou.net>
date	Thu, 12 Jul 2012 20:31:50 +0200
parents	d13fdd97cc8e
children	80b15cf2611e 2293eba03348

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.
75361 5f492397ccb8 sqlite3: Port documentation changes from the 2.7 branch Petri Lehtinen <petri@digip.org> parents: 74987 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 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	10 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	11 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	12 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	13 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	14 PostgreSQL or Oracle.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15
54339 699da6c467dc Merged revisions 72661,72675-72677,72679,72712,72801,72820 via svnmerge from Georg Brandl <georg@python.org> parents: 50574 diff changeset	16 sqlite3 was written by Gerhard Häring and provides a SQL interface compliant
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 with the DB-API 2.0 specification described by :pep:`249`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 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	20 represents the database. Here the data will be stored in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 :file:`/tmp/example` file::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22
75361 5f492397ccb8 sqlite3: Port documentation changes from the 2.7 branch Petri Lehtinen <petri@digip.org> parents: 74987 diff changeset	23 import sqlite3
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 conn = sqlite3.connect('/tmp/example')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 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	27
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 Once you have a :class:`Connection`, you can create a :class:`Cursor` object
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	29 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	30
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 c = conn.cursor()
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 # Create table
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 c.execute('''create table stocks
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 (date text, trans text, symbol text,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 qty real, price real)''')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 # Insert a row of data
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 c.execute("""insert into stocks
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 values ('2006-01-05','BUY','RHAT',100,35.14)""")
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 # We can also close the cursor if we are done with it
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 c.close()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 Usually your SQL operations will need to use values from Python variables. You
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49 shouldn't assemble your query using Python's string operations because doing so
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 is insecure; it makes your program vulnerable to an SQL injection attack.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 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	53 wherever you want to use a value, and then provide a tuple of values as the
54339 699da6c467dc Merged revisions 72661,72675-72677,72679,72712,72801,72820 via svnmerge from Georg Brandl <georg@python.org> parents: 50574 diff changeset	54 second argument to the cursor's :meth:`~Cursor.execute` method. (Other database
699da6c467dc Merged revisions 72661,72675-72677,72679,72712,72801,72820 via svnmerge from Georg Brandl <georg@python.org> parents: 50574 diff changeset	55 modules may use a different placeholder, such as ``%s`` or ``:1``.) For
699da6c467dc Merged revisions 72661,72675-72677,72679,72712,72801,72820 via svnmerge from Georg Brandl <georg@python.org> parents: 50574 diff changeset	56 example::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 # Never do this -- insecure!
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59 symbol = 'IBM'
75361 5f492397ccb8 sqlite3: Port documentation changes from the 2.7 branch Petri Lehtinen <petri@digip.org> parents: 74987 diff changeset	60 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	61
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 # Do this instead
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 t = (symbol,)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64 c.execute('select * from stocks where symbol=?', t)
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 # Larger example
49679 1f7f41f20ac5 Merged revisions 67117-67119,67123-67124,67143 via svnmerge from Georg Brandl <georg@python.org> parents: 49493 diff changeset	67 for t in [('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
75361 5f492397ccb8 sqlite3: Port documentation changes from the 2.7 branch Petri Lehtinen <petri@digip.org> parents: 74987 diff changeset	68 ('2006-04-05', 'BUY', 'MSFT', 1000, 72.00),
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 ('2006-04-06', 'SELL', 'IBM', 500, 53.00),
49679 1f7f41f20ac5 Merged revisions 67117-67119,67123-67124,67143 via svnmerge from Georg Brandl <georg@python.org> parents: 49493 diff changeset	70 ]:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 c.execute('insert into stocks values (?,?,?,?,?)', t)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43219 diff changeset	73 To retrieve data after executing a SELECT statement, you can either treat the
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	74 cursor as an :term:`iterator`, call the cursor's :meth:`~Cursor.fetchone` method to
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	75 retrieve a single matching row, or call :meth:`~Cursor.fetchall` to get a list of the
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43219 diff changeset	76 matching rows.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 This example uses the iterator form::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 >>> c = conn.cursor()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 >>> c.execute('select * from stocks order by price')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 >>> for row in c:
55933 f3a30083fd96 Merged revisions 74763 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 55580 diff changeset	83 ... print(row)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 ...
55933 f3a30083fd96 Merged revisions 74763 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 55580 diff changeset	85 ('2006-01-05', 'BUY', 'RHAT', 100, 35.14)
f3a30083fd96 Merged revisions 74763 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 55580 diff changeset	86 ('2006-03-28', 'BUY', 'IBM', 1000, 45.0)
f3a30083fd96 Merged revisions 74763 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 55580 diff changeset	87 ('2006-04-06', 'SELL', 'IBM', 500, 53.0)
f3a30083fd96 Merged revisions 74763 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 55580 diff changeset	88 ('2006-04-05', 'BUY', 'MSOFT', 1000, 72.0)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 >>>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 .. seealso::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93
59872 c53f6a3d2d3b Merged revisions 78338,78345-78346,78561-78562,78566,78574,78581,78634,78660,78675 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 59784 diff changeset	94 http://code.google.com/p/pysqlite/
54339 699da6c467dc Merged revisions 72661,72675-72677,72679,72712,72801,72820 via svnmerge from Georg Brandl <georg@python.org> parents: 50574 diff changeset	95 The pysqlite web page -- sqlite3 is developed externally under the name
699da6c467dc Merged revisions 72661,72675-72677,72679,72712,72801,72820 via svnmerge from Georg Brandl <georg@python.org> parents: 50574 diff changeset	96 "pysqlite".
42604 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 http://www.sqlite.org
54339 699da6c467dc Merged revisions 72661,72675-72677,72679,72712,72801,72820 via svnmerge from Georg Brandl <georg@python.org> parents: 50574 diff changeset	99 The SQLite web page; the documentation describes the syntax and the
699da6c467dc Merged revisions 72661,72675-72677,72679,72712,72801,72820 via svnmerge from Georg Brandl <georg@python.org> parents: 50574 diff changeset	100 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	101
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 :pep:`249` - Database API Specification 2.0
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103 PEP written by Marc-André Lemburg.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 .. _sqlite3-module-contents:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 Module functions and constants
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 ------------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 .. data:: PARSE_DECLTYPES
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 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	115 :func:`connect` function.
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 Setting it makes the :mod:`sqlite3` module parse the declared type for each
46664 031dfe455585 Merged revisions 62425-62429,62434-62436,62441,62444,62446-62448,62450-62455,62463,62465-62466,62469,62474,62476-62478,62480,62485,62492,62497-62498,62500,62507,62513-62514,62516,62521,62531,62535,62545-62546,62548-62551,62553-62559,62569,62574,62577,62593,62595,62604-62606,62608,62616,62626-62627,62636,62638,62644-62645,62647-62648,62651-62653,62656,62661,62663,62680,62686-62687,62696,62699-62703,62711 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 46539 diff changeset	118 column it returns. It will parse out the first word of the declared type,
031dfe455585 Merged revisions 62425-62429,62434-62436,62441,62444,62446-62448,62450-62455,62463,62465-62466,62469,62474,62476-62478,62480,62485,62492,62497-62498,62500,62507,62513-62514,62516,62521,62531,62535,62545-62546,62548-62551,62553-62559,62569,62574,62577,62593,62595,62604-62606,62608,62616,62626-62627,62636,62638,62644-62645,62647-62648,62651-62653,62656,62661,62663,62680,62686-62687,62696,62699-62703,62711 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 46539 diff changeset	119 i. e. for "integer primary key", it will parse out "integer", or for
031dfe455585 Merged revisions 62425-62429,62434-62436,62441,62444,62446-62448,62450-62455,62463,62465-62466,62469,62474,62476-62478,62480,62485,62492,62497-62498,62500,62507,62513-62514,62516,62521,62531,62535,62545-62546,62548-62551,62553-62559,62569,62574,62577,62593,62595,62604-62606,62608,62616,62626-62627,62636,62638,62644-62645,62647-62648,62651-62653,62656,62661,62663,62680,62686-62687,62696,62699-62703,62711 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 46539 diff changeset	120 "number(10)" it will parse out "number". Then for that column, it will look
031dfe455585 Merged revisions 62425-62429,62434-62436,62441,62444,62446-62448,62450-62455,62463,62465-62466,62469,62474,62476-62478,62480,62485,62492,62497-62498,62500,62507,62513-62514,62516,62521,62531,62535,62545-62546,62548-62551,62553-62559,62569,62574,62577,62593,62595,62604-62606,62608,62616,62626-62627,62636,62638,62644-62645,62647-62648,62651-62653,62656,62661,62663,62680,62686-62687,62696,62699-62703,62711 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 46539 diff changeset	121 into the converters dictionary and use the converter function registered for
031dfe455585 Merged revisions 62425-62429,62434-62436,62441,62444,62446-62448,62450-62455,62463,62465-62466,62469,62474,62476-62478,62480,62485,62492,62497-62498,62500,62507,62513-62514,62516,62521,62531,62535,62545-62546,62548-62551,62553-62559,62569,62574,62577,62593,62595,62604-62606,62608,62616,62626-62627,62636,62638,62644-62645,62647-62648,62651-62653,62656,62661,62663,62680,62686-62687,62696,62699-62703,62711 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 46539 diff changeset	122 that type there.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125 .. data:: PARSE_COLNAMES
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127 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	128 :func:`connect` function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 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	131 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	132 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	133 'mytype' in the converters dictionary and then use the converter function found
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	134 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	135 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	136 ``'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	137 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	138
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139
65114 eb8e13784de7 Merged revisions 82629,82632,82724,82757-82758,82760-82763,82798-82799,82801 via svnmerge from Georg Brandl <georg@python.org> parents: 63761 diff changeset	140 .. 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	141
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 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	143 ``":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	144 instead of on disk.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 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	147 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	148 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	149 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	150 parameter is 5.0 (five seconds).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 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	153 :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	154
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 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	156 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	157 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	158 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	159
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 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	161 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	162 type detection on.
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 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	165 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	166 :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	167 parameter.
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 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	170
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 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	172 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	173 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	174 implemented default is to cache 100 statements.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177 .. function:: register_converter(typename, callable)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179 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	180 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	181 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	182 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	183 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	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_adapter(type, 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 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	189 SQLite's supported types. The callable callable accepts as single parameter
44053 f2385d98282a Remove further mentions of long integers. Georg Brandl <georg@python.org> parents: 43737 diff changeset	190 the Python value, and must return a value of the following types: int,
58650 6fd2b8147f2a Fix sqlite3 docs. `buffer` is gone, `bytes` objects are returned for BLOBs instead. Antoine Pitrou <solipsis@pitrou.net> parents: 55933 diff changeset	191 float, str or bytes.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192
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 .. function:: complete_statement(sql)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196 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	197 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	198 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	199 statement is terminated by a semicolon.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201 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	202
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204 .. literalinclude:: ../includes/sqlite3/complete_statement.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 .. function:: enable_callback_tracebacks(flag)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 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	210 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	211 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	212 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	213 again.
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 .. _sqlite3-connection-objects:
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 Connection Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 ------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	221 .. class:: Connection
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	222
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	223 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	224
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 .. attribute:: Connection.isolation_level
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226
49908 ed8adfef26c6 Merged revisions 67348,67355,67359,67362,67364-67365,67367-67368,67398,67423-67424,67432,67440-67441,67444-67445,67454-67455,67457-67458 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49679 diff changeset	227 Get or set the current isolation level. :const:`None` for autocommit mode or
ed8adfef26c6 Merged revisions 67348,67355,67359,67362,67364-67365,67367-67368,67398,67423-67424,67432,67440-67441,67444-67445,67454-67455,67457-67458 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49679 diff changeset	228 one of "DEFERRED", "IMMEDIATE" or "EXCLUSIVE". See section
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 :ref:`sqlite3-controlling-transactions` for a more detailed explanation.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230
62009 62ca540d8b6e #8845: expose sqlite3 inTransaction as RO in_transaction Connection attribute. R. David Murray <rdmurray@bitdance.com> parents: 59872 diff changeset	231 .. attribute:: Connection.in_transaction
62ca540d8b6e #8845: expose sqlite3 inTransaction as RO in_transaction Connection attribute. R. David Murray <rdmurray@bitdance.com> parents: 59872 diff changeset	232
62141 c4d4ddacf9a5 fix typo Benjamin Peterson <benjamin@python.org> parents: 62009 diff changeset	233 :const:`True` if a transaction is active (there are uncommitted changes),
62009 62ca540d8b6e #8845: expose sqlite3 inTransaction as RO in_transaction Connection attribute. R. David Murray <rdmurray@bitdance.com> parents: 59872 diff changeset	234 :const:`False` otherwise. Read-only attribute.
62ca540d8b6e #8845: expose sqlite3 inTransaction as RO in_transaction Connection attribute. R. David Murray <rdmurray@bitdance.com> parents: 59872 diff changeset	235
64112 990a766ff983 Consistency check for versionadded/changed directives. Georg Brandl <georg@python.org> parents: 63760 diff changeset	236 .. versionadded:: 3.2
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238 .. method:: Connection.cursor([cursorClass])
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 The cursor method accepts a single optional parameter cursorClass. If
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 supplied, this must be a custom cursor class that extends
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 :class:`sqlite3.Cursor`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243
46181 09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	244 .. method:: Connection.commit()
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	245
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	246 This method commits the current transaction. If you don't call this method,
72985 e19ccbbe70dd Remove duplication. Ezio Melotti <ezio.melotti@gmail.com> parents: 71147 diff changeset	247 anything you did since the last call to ``commit()`` is not visible from
46181 09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	248 other database connections. If you wonder why you don't see the data you've
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	249 written to the database, please check you didn't forget to call this method.
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	250
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	251 .. method:: Connection.rollback()
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	252
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	253 This method rolls back any changes to the database since the last call to
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	254 :meth:`commit`.
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	255
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	256 .. method:: Connection.close()
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	257
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	258 This closes the database connection. Note that this does not automatically
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	259 call :meth:`commit`. If you just close your database connection without
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	260 calling :meth:`commit` first, your changes will be lost!
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	261
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 .. method:: Connection.execute(sql, [parameters])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 This is a nonstandard shortcut that creates an intermediate cursor object by
66472 a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 66383 diff changeset	265 calling the cursor method, then calls the cursor's :meth:`execute
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 66383 diff changeset	266 <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	267
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269 .. method:: Connection.executemany(sql, [parameters])
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 This is a nonstandard shortcut that creates an intermediate cursor object by
66472 a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 66383 diff changeset	272 calling the cursor method, then calls the cursor's :meth:`executemany
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 66383 diff changeset	273 <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	274
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275 .. method:: Connection.executescript(sql_script)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 This is a nonstandard shortcut that creates an intermediate cursor object by
66472 a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 66383 diff changeset	278 calling the cursor method, then calls the cursor's :meth:`executescript
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 66383 diff changeset	279 <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	280
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282 .. method:: Connection.create_function(name, num_params, func)
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 Creates a user-defined function that you can later use from within SQL
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285 statements under the function name name. num_params is the number of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 parameters the function accepts, and func is a Python callable that is called
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 as the SQL function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
45084 38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44810 diff changeset	289 The function can return any of the types supported by SQLite: bytes, str, int,
58650 6fd2b8147f2a Fix sqlite3 docs. `buffer` is gone, `bytes` objects are returned for BLOBs instead. Antoine Pitrou <solipsis@pitrou.net> parents: 55933 diff changeset	290 float and None.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292 Example:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 .. literalinclude:: ../includes/sqlite3/md5func.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297 .. method:: Connection.create_aggregate(name, num_params, aggregate_class)
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 Creates a user-defined aggregate function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	300
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301 The aggregate class must implement a ``step`` method, which accepts the number
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302 of parameters num_params, and a ``finalize`` method which will return the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303 final result of the aggregate.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305 The ``finalize`` method can return any of the types supported by SQLite:
58650 6fd2b8147f2a Fix sqlite3 docs. `buffer` is gone, `bytes` objects are returned for BLOBs instead. Antoine Pitrou <solipsis@pitrou.net> parents: 55933 diff changeset	306 bytes, str, int, float and None.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308 Example:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 .. literalinclude:: ../includes/sqlite3/mysumaggr.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313 .. method:: Connection.create_collation(name, callable)
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 Creates a collation with the specified name and callable. The callable will
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316 be passed two string arguments. It should return -1 if the first is ordered
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317 lower than the second, 0 if they are ordered equal and 1 if the first is ordered
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 higher than the second. Note that this controls sorting (ORDER BY in SQL) so
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 your comparisons don't affect other SQL operations.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321 Note that the callable will get its parameters as Python bytestrings, which will
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 normally be encoded in UTF-8.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 The following example shows a custom collation that sorts "the wrong way":
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 .. literalinclude:: ../includes/sqlite3/collation_reverse.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 To remove a collation, call ``create_collation`` with None as callable::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330 con.create_collation("reverse", None)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 .. method:: Connection.interrupt()
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 You can call this method from a different thread to abort any queries that might
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 be executing on the connection. The query will then abort and the caller will
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337 get an exception.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340 .. method:: Connection.set_authorizer(authorizer_callback)
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 This routine registers a callback. The callback is invoked for each attempt to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343 access a column of a table in the database. The callback should return
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 :const:`SQLITE_OK` if access is allowed, :const:`SQLITE_DENY` if the entire SQL
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 statement should be aborted with an error and :const:`SQLITE_IGNORE` if the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346 column should be treated as a NULL value. These constants are available in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347 :mod:`sqlite3` module.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349 The first argument to the callback signifies what kind of operation is to be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350 authorized. The second and third argument will be arguments or :const:`None`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	351 depending on the first argument. The 4th argument is the name of the database
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352 ("main", "temp", etc.) if applicable. The 5th argument is the name of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353 inner-most trigger or view that is responsible for the access attempt or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354 :const:`None` if this access attempt is directly from input SQL code.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 Please consult the SQLite documentation about the possible values for the first
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 argument and the meaning of the second and third argument depending on the first
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 one. All necessary constants are available in the :mod:`sqlite3` module.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360
46181 09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	361 .. method:: Connection.set_progress_handler(handler, n)
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	362
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	363 This routine registers a callback. The callback is invoked for every n
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	364 instructions of the SQLite virtual machine. This is useful if you want to
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	365 get called from SQLite during long-running operations, for example to update
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	366 a GUI.
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	367
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	368 If you want to clear any previously installed progress handler, call the
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	369 method with :const:`None` for handler.
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	370
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	371
59372 3003c1656e2a Merged new pysqlite version 2.6.0 from trunk. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	372 .. method:: Connection.enable_load_extension(enabled)
3003c1656e2a Merged new pysqlite version 2.6.0 from trunk. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	373
3003c1656e2a Merged new pysqlite version 2.6.0 from trunk. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	374 This routine allows/disallows the SQLite engine to load SQLite extensions
3003c1656e2a Merged new pysqlite version 2.6.0 from trunk. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	375 from shared libraries. SQLite extensions can define new functions,
65441 3b5ed8490ab2 #8811: small fixes to sqlite3 docs. Georg Brandl <georg@python.org> parents: 65081 diff changeset	376 aggregates or whole new virtual table implementations. One well-known
59372 3003c1656e2a Merged new pysqlite version 2.6.0 from trunk. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	377 extension is the fulltext-search extension distributed with SQLite.
3003c1656e2a Merged new pysqlite version 2.6.0 from trunk. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	378
75361 5f492397ccb8 sqlite3: Port documentation changes from the 2.7 branch Petri Lehtinen <petri@digip.org> parents: 74987 diff changeset	379 Loadable extensions are disabled by default. See [#f1]_.
5f492397ccb8 sqlite3: Port documentation changes from the 2.7 branch Petri Lehtinen <petri@digip.org> parents: 74987 diff changeset	380
64112 990a766ff983 Consistency check for versionadded/changed directives. Georg Brandl <georg@python.org> parents: 63760 diff changeset	381 .. versionadded:: 3.2
990a766ff983 Consistency check for versionadded/changed directives. Georg Brandl <georg@python.org> parents: 63760 diff changeset	382
59372 3003c1656e2a Merged new pysqlite version 2.6.0 from trunk. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	383 .. literalinclude:: ../includes/sqlite3/load_extension.py
3003c1656e2a Merged new pysqlite version 2.6.0 from trunk. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	384
3003c1656e2a Merged new pysqlite version 2.6.0 from trunk. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	385 .. method:: Connection.load_extension(path)
3003c1656e2a Merged new pysqlite version 2.6.0 from trunk. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	386
65441 3b5ed8490ab2 #8811: small fixes to sqlite3 docs. Georg Brandl <georg@python.org> parents: 65081 diff changeset	387 This routine loads a SQLite extension from a shared library. You have to
3b5ed8490ab2 #8811: small fixes to sqlite3 docs. Georg Brandl <georg@python.org> parents: 65081 diff changeset	388 enable extension loading with :meth:`enable_load_extension` before you can
3b5ed8490ab2 #8811: small fixes to sqlite3 docs. Georg Brandl <georg@python.org> parents: 65081 diff changeset	389 use this routine.
59372 3003c1656e2a Merged new pysqlite version 2.6.0 from trunk. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	390
75361 5f492397ccb8 sqlite3: Port documentation changes from the 2.7 branch Petri Lehtinen <petri@digip.org> parents: 74987 diff changeset	391 Loadable extensions are disabled by default. See [#f1]_.
64112 990a766ff983 Consistency check for versionadded/changed directives. Georg Brandl <georg@python.org> parents: 63760 diff changeset	392
75361 5f492397ccb8 sqlite3: Port documentation changes from the 2.7 branch Petri Lehtinen <petri@digip.org> parents: 74987 diff changeset	393 .. versionadded:: 3.2
65081 9eb9e3f66e3a Fixes #10020 Gerhard Häring <gh@ghaering.de> parents: 64112 diff changeset	394
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395 .. attribute:: Connection.row_factory
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397 You can change this attribute to a callable that accepts the cursor and the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398 original row as a tuple and will return the real result row. This way, you can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399 implement more advanced ways of returning results, such as returning an object
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400 that can also access columns by name.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 Example:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 .. literalinclude:: ../includes/sqlite3/row_factory.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406 If returning a tuple doesn't suffice and you want name-based access to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407 columns, you should consider setting :attr:`row_factory` to the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 highly-optimized :class:`sqlite3.Row` type. :class:`Row` provides both
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409 index-based and case-insensitive name-based access to columns with almost no
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410 memory overhead. It will probably be better than your own custom
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 dictionary-based approach or even a db_row based solution.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44053 diff changeset	413 .. 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	414
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 .. attribute:: Connection.text_factory
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	418 Using this attribute you can control what objects are returned for the ``TEXT``
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	419 data type. By default, this attribute is set to :class:`str` and the
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	420 :mod:`sqlite3` module will return Unicode objects for ``TEXT``. If you want to
45084 38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44810 diff changeset	421 return bytestrings instead, you can set it to :class:`bytes`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422
45084 38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44810 diff changeset	423 For efficiency reasons, there's also a way to return :class:`str` objects
38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44810 diff changeset	424 only for non-ASCII data, and :class:`bytes` otherwise. To activate it, set
38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44810 diff changeset	425 this attribute to :const:`sqlite3.OptimizedUnicode`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427 You can also set it to any other callable that accepts a single bytestring
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428 parameter and returns the resulting object.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430 See the following example code for illustration:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432 .. literalinclude:: ../includes/sqlite3/text_factory.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435 .. attribute:: Connection.total_changes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	436
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437 Returns the total number of database rows that have been modified, inserted, or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438 deleted since the database connection was opened.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	440
46161 848160d10780 Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	441 .. attribute:: Connection.iterdump
848160d10780 Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	442
848160d10780 Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	443 Returns an iterator to dump the database in an SQL text format. Useful when
848160d10780 Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	444 saving an in-memory database for later restoration. This function provides
848160d10780 Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	445 the same capabilities as the :kbd:`.dump` command in the :program:`sqlite3`
848160d10780 Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	446 shell.
848160d10780 Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	447
848160d10780 Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	448 Example::
848160d10780 Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	449
848160d10780 Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	450 # Convert file existing_db.db to SQL dump file dump.sql
848160d10780 Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	451 import sqlite3, os
848160d10780 Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	452
848160d10780 Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	453 con = sqlite3.connect('existing_db.db')
49679 1f7f41f20ac5 Merged revisions 67117-67119,67123-67124,67143 via svnmerge from Georg Brandl <georg@python.org> parents: 49493 diff changeset	454 with open('dump.sql', 'w') as f:
1f7f41f20ac5 Merged revisions 67117-67119,67123-67124,67143 via svnmerge from Georg Brandl <georg@python.org> parents: 49493 diff changeset	455 for line in con.iterdump():
1f7f41f20ac5 Merged revisions 67117-67119,67123-67124,67143 via svnmerge from Georg Brandl <georg@python.org> parents: 49493 diff changeset	456 f.write('%s\n' % line)
46161 848160d10780 Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	457
848160d10780 Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45084 diff changeset	458
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459 .. _sqlite3-cursor-objects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461 Cursor Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462 --------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	464 .. class:: Cursor
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	465
66472 a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 66383 diff changeset	466 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	467
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468 .. method:: Cursor.execute(sql, [parameters])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469
44810 fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	470 Executes an SQL statement. The SQL statement may be parametrized (i. e.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471 placeholders instead of SQL literals). The :mod:`sqlite3` module supports two
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472 kinds of placeholders: question marks (qmark style) and named placeholders
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	473 (named style).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474
74959 9eb77d455be1 Issue #13491: Fix many errors in sqlite3 documentation Petri Lehtinen <petri@digip.org> parents: 72985 diff changeset	475 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	476
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477 .. literalinclude:: ../includes/sqlite3/execute_1.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479 :meth:`execute` will only execute a single SQL statement. If you try to execute
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480 more than one statement with it, it will raise a Warning. Use
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481 :meth:`executescript` if you want to execute multiple SQL statements with one
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482 call.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485 .. method:: Cursor.executemany(sql, seq_of_parameters)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486
44810 fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	487 Executes an SQL command against all parameter sequences or mappings found in
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43219 diff changeset	488 the sequence sql. The :mod:`sqlite3` module also allows using an
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43219 diff changeset	489 :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	490
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491 .. literalinclude:: ../includes/sqlite3/executemany_1.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43219 diff changeset	493 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	494
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495 .. literalinclude:: ../includes/sqlite3/executemany_2.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498 .. method:: Cursor.executescript(sql_script)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	500 This is a nonstandard convenience method for executing multiple SQL statements
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	501 at once. It issues a ``COMMIT`` statement first, then executes the SQL script it
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502 gets as a parameter.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503
45084 38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44810 diff changeset	504 sql_script can be an instance of :class:`str` or :class:`bytes`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506 Example:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508 .. literalinclude:: ../includes/sqlite3/executescript.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510
46181 09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	511 .. method:: Cursor.fetchone()
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	512
44810 fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	513 Fetches the next row of a query result set, returning a single sequence,
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	514 or :const:`None` when no more data is available.
44810 fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	515
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	516
77092 d13fdd97cc8e #14804: Remove [] around optional arguments with default values Hynek Schlawack <hs@ox.cx> parents: 75361 diff changeset	517 .. method:: Cursor.fetchmany(size=cursor.arraysize)
46181 09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	518
44810 fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	519 Fetches the next set of rows of a query result, returning a list. An empty
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	520 list is returned when no more rows are available.
46181 09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	521
44810 fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	522 The number of rows to fetch per call is specified by the size parameter.
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	523 If it is not given, the cursor's arraysize determines the number of rows
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	524 to be fetched. The method should try to fetch as many rows as indicated by
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	525 the size parameter. If this is not possible due to the specified number of
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	526 rows not being available, fewer rows may be returned.
46181 09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	527
44810 fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	528 Note there are performance considerations involved with the size parameter.
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	529 For optimal performance, it is usually best to use the arraysize attribute.
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	530 If the size parameter is used, then it is best for it to retain the same
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	531 value from one :meth:`fetchmany` call to the next.
46181 09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	532
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	533 .. method:: Cursor.fetchall()
44810 fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	534
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	535 Fetches all (remaining) rows of a query result, returning a list. Note that
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	536 the cursor's arraysize attribute can affect the performance of this operation.
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	537 An empty list is returned when no rows are available.
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	538
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	539
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540 .. attribute:: Cursor.rowcount
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542 Although the :class:`Cursor` class of the :mod:`sqlite3` module implements this
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543 attribute, the database engine's own support for the determination of "rows
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544 affected"/"rows selected" is quirky.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546 For :meth:`executemany` statements, the number of modifications are summed up
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	547 into :attr:`rowcount`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549 As required by the Python DB API Spec, the :attr:`rowcount` attribute "is -1 in
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	550 case no ``executeXX()`` has been performed on the cursor or the rowcount of the
74987 74b2da95c6be sqlite3: Fix documentation errors concerning Cursor.rowcount Petri Lehtinen <petri@digip.org> parents: 74959 diff changeset	551 last operation is not determinable by the interface". This includes ``SELECT``
74b2da95c6be sqlite3: Fix documentation errors concerning Cursor.rowcount Petri Lehtinen <petri@digip.org> parents: 74959 diff changeset	552 statements because we cannot determine the number of rows a query produced
74b2da95c6be sqlite3: Fix documentation errors concerning Cursor.rowcount Petri Lehtinen <petri@digip.org> parents: 74959 diff changeset	553 until all rows were fetched.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554
74987 74b2da95c6be sqlite3: Fix documentation errors concerning Cursor.rowcount Petri Lehtinen <petri@digip.org> parents: 74959 diff changeset	555 With SQLite versions before 3.6.5, :attr:`rowcount` is set to 0 if
74b2da95c6be sqlite3: Fix documentation errors concerning Cursor.rowcount Petri Lehtinen <petri@digip.org> parents: 74959 diff changeset	556 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	557
46199 ed88f4de496f Documented lastrowid attribute in py3k branch. Gerhard Häring <gh@ghaering.de> parents: 46181 diff changeset	558 .. attribute:: Cursor.lastrowid
ed88f4de496f Documented lastrowid attribute in py3k branch. Gerhard Häring <gh@ghaering.de> parents: 46181 diff changeset	559
ed88f4de496f Documented lastrowid attribute in py3k branch. Gerhard Häring <gh@ghaering.de> parents: 46181 diff changeset	560 This read-only attribute provides the rowid of the last modified row. It is
ed88f4de496f Documented lastrowid attribute in py3k branch. Gerhard Häring <gh@ghaering.de> parents: 46181 diff changeset	561 only set if you issued a ``INSERT`` statement using the :meth:`execute`
ed88f4de496f Documented lastrowid attribute in py3k branch. Gerhard Häring <gh@ghaering.de> parents: 46181 diff changeset	562 method. For operations other than ``INSERT`` or when :meth:`executemany` is
ed88f4de496f Documented lastrowid attribute in py3k branch. Gerhard Häring <gh@ghaering.de> parents: 46181 diff changeset	563 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	564
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	565 .. attribute:: Cursor.description
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	566
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	567 This read-only attribute provides the column names of the last query. To
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	568 remain compatible with the Python DB API, it returns a 7-tuple for each
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49908 diff changeset	569 column where the last six items of each tuple are :const:`None`.
93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49908 diff changeset	570
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	571 It is set for ``SELECT`` statements without any matching rows as well.
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	572
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	573 .. _sqlite3-row-objects:
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	574
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	575 Row Objects
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	576 -----------
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	577
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	578 .. class:: Row
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	579
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	580 A :class:`Row` instance serves as a highly optimized
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49908 diff changeset	581 :attr:`~Connection.row_factory` for :class:`Connection` objects.
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	582 It tries to mimic a tuple in most of its features.
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	583
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	584 It supports mapping access by column name and index, iteration,
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	585 representation, equality testing and :func:`len`.
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	586
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	587 If two :class:`Row` objects have exactly the same columns and their
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	588 members are equal, they compare equal.
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49908 diff changeset	589
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	590 .. method:: keys
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	591
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	592 This method returns a tuple of column names. Immediately after a query,
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	593 it is the first member of each tuple in :attr:`Cursor.description`.
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	594
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	595 Let's assume we initialize a table as in the example given above::
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	596
71147 5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	597 conn = sqlite3.connect(":memory:")
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	598 c = conn.cursor()
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	599 c.execute('''create table stocks
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	600 (date text, trans text, symbol text,
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	601 qty real, price real)''')
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	602 c.execute("""insert into stocks
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	603 values ('2006-01-05','BUY','RHAT',100,35.14)""")
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	604 conn.commit()
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	605 c.close()
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	606
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	607 Now we plug :class:`Row` in::
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	608
71147 5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	609 >>> conn.row_factory = sqlite3.Row
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	610 >>> c = conn.cursor()
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	611 >>> c.execute('select * from stocks')
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	612 <sqlite3.Cursor object at 0x7f4e7dd8fa80>
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	613 >>> r = c.fetchone()
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	614 >>> type(r)
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	615 <class 'sqlite3.Row'>
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	616 >>> tuple(r)
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	617 ('2006-01-05', 'BUY', 'RHAT', 100.0, 35.14)
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	618 >>> len(r)
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	619 5
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	620 >>> r[2]
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	621 'RHAT'
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	622 >>> r.keys()
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	623 ['date', 'trans', 'symbol', 'qty', 'price']
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	624 >>> r['qty']
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	625 100.0
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	626 >>> for member in r:
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	627 ... print(member)
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	628 ...
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	629 2006-01-05
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	630 BUY
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	631 RHAT
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	632 100.0
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	633 35.14
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	634
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	635
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	636 .. _sqlite3-types:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	637
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	638 SQLite and Python types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	639 -----------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	640
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	641
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	642 Introduction
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	643 ^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	644
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	645 SQLite natively supports the following types: ``NULL``, ``INTEGER``,
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	646 ``REAL``, ``TEXT``, ``BLOB``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	647
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	648 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	649
45084 38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44810 diff changeset	650 +-------------------------------+-------------+
38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44810 diff changeset	651 \| Python type \| SQLite type \|
38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44810 diff changeset	652 +===============================+=============+
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	653 \| :const:`None` \| ``NULL`` \|
45084 38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44810 diff changeset	654 +-------------------------------+-------------+
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	655 \| :class:`int` \| ``INTEGER`` \|
45084 38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44810 diff changeset	656 +-------------------------------+-------------+
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	657 \| :class:`float` \| ``REAL`` \|
45084 38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44810 diff changeset	658 +-------------------------------+-------------+
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	659 \| :class:`str` \| ``TEXT`` \|
45084 38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44810 diff changeset	660 +-------------------------------+-------------+
58650 6fd2b8147f2a Fix sqlite3 docs. `buffer` is gone, `bytes` objects are returned for BLOBs instead. Antoine Pitrou <solipsis@pitrou.net> parents: 55933 diff changeset	661 \| :class:`bytes` \| ``BLOB`` \|
45084 38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44810 diff changeset	662 +-------------------------------+-------------+
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	663
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665 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	666
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	667 +-------------+---------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	668 \| SQLite type \| Python type \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	669 +=============+=============================================+
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	670 \| ``NULL`` \| :const:`None` \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671 +-------------+---------------------------------------------+
55933 f3a30083fd96 Merged revisions 74763 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 55580 diff changeset	672 \| ``INTEGER`` \| :class:`int` \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	673 +-------------+---------------------------------------------+
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	674 \| ``REAL`` \| :class:`float` \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675 +-------------+---------------------------------------------+
45084 38604fa2a48f Update docs w.r.t. PEP 3100 changes -- patch for GHOP by Dan Finnie. Georg Brandl <georg@python.org> parents: 44810 diff changeset	676 \| ``TEXT`` \| depends on text_factory, str by default \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	677 +-------------+---------------------------------------------+
58650 6fd2b8147f2a Fix sqlite3 docs. `buffer` is gone, `bytes` objects are returned for BLOBs instead. Antoine Pitrou <solipsis@pitrou.net> parents: 55933 diff changeset	678 \| ``BLOB`` \| :class:`bytes` \|
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	681 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	682 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	683 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	684 types via converters.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	685
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	686
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	687 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	688 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	689
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	690 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	691 use other Python types with SQLite, you must adapt them to one of the
44053 f2385d98282a Remove further mentions of long integers. Georg Brandl <georg@python.org> parents: 43737 diff changeset	692 sqlite3 module's supported types for SQLite: one of NoneType, int, float,
58650 6fd2b8147f2a Fix sqlite3 docs. `buffer` is gone, `bytes` objects are returned for BLOBs instead. Antoine Pitrou <solipsis@pitrou.net> parents: 55933 diff changeset	693 str, bytes.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	694
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	695 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	696 :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	697
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698 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	699 type to one of the supported ones.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702 Letting your object adapt itself
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705 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	706 a class like this::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	707
66383 5382ca95c3f6 Merged revisions 86670 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65117 diff changeset	708 class Point:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	709 def __init__(self, x, y):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	710 self.x, self.y = x, y
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 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	713 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	714 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	715 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	716 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	717
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	718 .. literalinclude:: ../includes/sqlite3/adapter_point_1.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719
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 Registering an adapter callable
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	722 """""""""""""""""""""""""""""""
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724 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	725 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	726
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727 .. literalinclude:: ../includes/sqlite3/adapter_point_2.py
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 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	730 :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	731 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	732 but as a Unix timestamp.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734 .. literalinclude:: ../includes/sqlite3/adapter_datetime.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	735
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 Converting SQLite values to custom Python types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 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	741 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	742
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743 Enter converters.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745 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	746 separated via semicolons as strings in SQLite.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748 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	749 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	750
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751 .. note::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753 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	754 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	755
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756 ::
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 def convert_point(s):
74959 9eb77d455be1 Issue #13491: Fix many errors in sqlite3 documentation Petri Lehtinen <petri@digip.org> parents: 72985 diff changeset	759 x, y = map(float, s.split(b";"))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	760 return Point(x, y)
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 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	763 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	764
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765 * Implicitly via the declared type
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 * Explicitly via the column name
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769 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	770 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	771
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772 The following example illustrates both approaches.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774 .. literalinclude:: ../includes/sqlite3/converter_point.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	775
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	776
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777 Default adapters and converters
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 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	781 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	782
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	783 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	784 :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	785 :class:`datetime.datetime`.
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 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	788 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	789 experimental SQLite date/time functions.
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 The following example demonstrates this.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	792
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	793 .. literalinclude:: ../includes/sqlite3/pysqlite_datetime.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	794
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 .. _sqlite3-controlling-transactions:
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 Controlling Transactions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	799 ------------------------
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 By default, the :mod:`sqlite3` module opens transactions implicitly before a
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49908 diff changeset	802 Data Modification Language (DML) statement (i.e.
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	803 ``INSERT``/``UPDATE``/``DELETE``/``REPLACE``), and commits transactions
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	804 implicitly before a non-DML, non-query statement (i. e.
bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	805 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	806
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	807 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	808 ...``, ``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	809 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	810 is that some of these commands don't work within transactions. The other reason
54339 699da6c467dc Merged revisions 72661,72675-72677,72679,72712,72801,72820 via svnmerge from Georg Brandl <georg@python.org> parents: 50574 diff changeset	811 is that sqlite3 needs to keep track of the transaction state (if a transaction
62009 62ca540d8b6e #8845: expose sqlite3 inTransaction as RO in_transaction Connection attribute. R. David Murray <rdmurray@bitdance.com> parents: 59872 diff changeset	812 is active or not). The current transaction state is exposed through the
62ca540d8b6e #8845: expose sqlite3 inTransaction as RO in_transaction Connection attribute. R. David Murray <rdmurray@bitdance.com> parents: 59872 diff changeset	813 :attr:`Connection.in_transaction` attribute of the connection object.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	814
54339 699da6c467dc Merged revisions 72661,72675-72677,72679,72712,72801,72820 via svnmerge from Georg Brandl <georg@python.org> parents: 50574 diff changeset	815 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	816 (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	817 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	818
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	819 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	820
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	821 Otherwise leave it at its default, which will result in a plain "BEGIN"
49679 1f7f41f20ac5 Merged revisions 67117-67119,67123-67124,67143 via svnmerge from Georg Brandl <georg@python.org> parents: 49493 diff changeset	822 statement, or set it to one of SQLite's supported isolation levels: "DEFERRED",
1f7f41f20ac5 Merged revisions 67117-67119,67123-67124,67143 via svnmerge from Georg Brandl <georg@python.org> parents: 49493 diff changeset	823 "IMMEDIATE" or "EXCLUSIVE".
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	824
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	825
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	826
54339 699da6c467dc Merged revisions 72661,72675-72677,72679,72712,72801,72820 via svnmerge from Georg Brandl <georg@python.org> parents: 50574 diff changeset	827 Using :mod:`sqlite3` efficiently
699da6c467dc Merged revisions 72661,72675-72677,72679,72712,72801,72820 via svnmerge from Georg Brandl <georg@python.org> parents: 50574 diff changeset	828 --------------------------------
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	829
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	830
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	831 Using shortcut methods
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	832 ^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	833
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	834 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	835 :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	836 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	837 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	838 objects are created implicitly and these shortcut methods return the cursor
49493 bdf4da5d04ad merge from trunk Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	839 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	840 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	841
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	842 .. literalinclude:: ../includes/sqlite3/shortcut_methods.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	843
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	844
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	845 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	846 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	847
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54927 diff changeset	848 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	849 :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	850
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	851 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	852 case-insensitively by name:
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 .. literalinclude:: ../includes/sqlite3/rowclass.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	855
46181 09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	856
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	857 Using the connection as a context manager
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	858 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	859
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	860 Connection objects can be used as context managers
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	861 that automatically commit or rollback transactions. In the event of an
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	862 exception, the transaction is rolled back; otherwise, the transaction is
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	863 committed:
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	864
09053a7c1cdf Same documentation for sqlite3 module as in 2.6. Gerhard Häring <gh@ghaering.de> parents: 46161 diff changeset	865 .. literalinclude:: ../includes/sqlite3/ctx_manager.py
63761 a03739af9d38 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	866
a03739af9d38 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	867
a03739af9d38 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	868 Common issues
a03739af9d38 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	869 -------------
a03739af9d38 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	870
a03739af9d38 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	871 Multithreading
a03739af9d38 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	872 ^^^^^^^^^^^^^^
a03739af9d38 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	873
a03739af9d38 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	874 Older SQLite versions had issues with sharing connections between threads.
a03739af9d38 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	875 That's why the Python module disallows sharing connections and cursors between
a03739af9d38 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	876 threads. If you still try to do so, you will get an exception at runtime.
a03739af9d38 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	877
a03739af9d38 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	878 The only exception is calling the :meth:`~Connection.interrupt` method, which
a03739af9d38 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 58895 diff changeset	879 only makes sense to call from a different thread.
63760 29226c08e547 Issue #3854: Documented using the sqlite3 module with multiple threads. Gerhard Häring <gh@ghaering.de> parents: 62918 diff changeset	880
65081 9eb9e3f66e3a Fixes #10020 Gerhard Häring <gh@ghaering.de> parents: 64112 diff changeset	881 .. rubric:: Footnotes
9eb9e3f66e3a Fixes #10020 Gerhard Häring <gh@ghaering.de> parents: 64112 diff changeset	882
9eb9e3f66e3a Fixes #10020 Gerhard Häring <gh@ghaering.de> parents: 64112 diff changeset	883 .. [#f1] The sqlite3 module is not built with loadable extension support by
71147 5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	884 default, because some platforms (notably Mac OS X) have SQLite
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	885 libraries which are compiled without this feature. To get loadable
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	886 extension support, you must pass --enable-loadable-sqlite-extensions to
5d1a2b8f508c reST indentation fix in sqlite3 docs. rst uses 3 space indentation. Senthil Kumaran <senthil@uthcode.com> parents: 68257 diff changeset	887 configure.

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/sqlite3.rst @ 78069:a8aa77458e12 3.2