1
=== modified file 'ChangeLog'
2
--- ChangeLog	2009-10-12 06:50:00 +0000
3
+++ ChangeLog	2010-07-28 20:35:51 +0000
4
@@ -1,3 +1,134 @@
5
1
2010-05-17  Federico Di Gregorio  <fog@initd.org>
6
2
7
3
	* Release 2.2.1.
8
4
9
5
	* Builds again on Windows.
10
6
11
7
2010-05-16  Federico Di Gregorio  <fog@initd.org>
12
8
13
9
	* Release 2.2.0.
14
10
15
11
2010-05-15  Federico Di Gregorio  <fog@initd.org>
16
12
17
13
	* typecast.c: Fixed problem related to receiving None from Python
18
14
	when a string was expected.
19
15
20
16
2010-05-07  Daniele Varrazzo  <daniele.varrazzo@gmail.com>
21
17
22
18
	* psycopg/adapter_datetime.c: Fixed TimestampFromTicks for second
23
19
	values > 59.5.
24
20
25
21
	Bug reported and fixed by Jozsef Szalay on 2010-05-06 at 14:11:59.999920.
26
22
27
23
	* psycopg/adapter_datetime.c: Fixed same bug for TimeFromTicks.
28
24
29
25
2010-05-04  Daniele Varrazzo  <daniele.varrazzo@gmail.com>
30
26
31
27
	* Added typecasters for arrays of specific MX/Py time-related types.
32
28
33
29
	* psycopg/adapter_[mx]datetime.c: Explicit cast of the SQL representation
34
30
	of time-related objects.
35
31
36
32
2010-05-03  Daniele Varrazzo  <daniele.varrazzo@gmail.com>
37
33
38
34
	* psycopg/adapter_binary.c: Adapt buffer objects using an explicit cast on
39
35
	the string literal (bug reported by Peter Eisentraut)
40
36
41
37
2010-04-20  Daniele Varrazzo  <daniele.varrazzo@gmail.com>
42
38
43
39
	* lib/pqpath.c: Fixed reference leak in notify reception.
44
40
45
41
	* Notifies are collected if available after every query execution.
46
42
47
43
2010-04-13  Daniele Varrazzo  <daniele.varrazzo@gmail.com>
48
44
49
45
	* lib/extensions.py: DECIMAL typecaster imported from _psycopg.
50
46
51
47
	* lib/extensions.py: PY* and MX* time typecaster imported from _psycopg.
52
48
53
49
2010-04-11  Daniele Varrazzo  <daniele.varrazzo@gmail.com>
54
50
55
51
	* psycopg/connection_type.c: Correctly parse keywords in connect().
56
52
57
53
2010-04-07  Daniele Varrazzo  <daniele.varrazzo@gmail.com>
58
54
59
55
	* psycopg/pqpath.c: Ensure running COPY in blocking mode.
60
56
61
57
	* psycopg/pqpath.c: Free the GIL in blocking operations in V2 COPY FROM.
62
58
63
59
	* psycopg/pqpath.c: Evaluate Python objects only once outside the COPY I/O
64
60
	loops.
65
61
66
62
2010-04-05  Federico Di Gregorio  <fog@initd.org>
67
63
68
64
	* Fixed problem with asynchronous NOTIFYs.
69
65
70
66
	* Integrated async pacthes from Jan's git tree.
71
67
72
68
2010-03-13  Federico Di Gregorio  <fog@initd.org>
73
69
74
70
	* Release 2.0.14.
75
71
76
72
2010-03-11  Federico Di Gregorio  <fog@initd.org>
77
73
78
74
	* setup.py: one-liner from Devrim GÜNDÜZ to build with PostgreSQL
79
75
	alpha.
80
76
81
77
2010-02-28  Federico Di Gregorio  <fog@initd.org>
82
78
83
79
	* psycopg/adapt_decimal.c: Python 2.4 decimal type does not support
84
80
	.isfinite() and two different calls to ._isinfinity() and ._isnan() are
85
81
	required. This fixes both a test failure and a segfault.
86
82
87
83
2010-02-15  Federico Di Gregorio  <fog@initd.org>
88
84
89
85
	* Added new Decimal adapter that correctly converts NaN and infinity
90
86
	to PostgreSQL NaN numeric values. Also added tests.
91
87
92
88
2010-02-15  Daniele Varrazzo  <daniele.varrazzo@gmail.com>
93
89
94
90
	* lib/errorcodes.py: Updated to PostgreSQL 8.4; added lookup() function.
95
91
96
92
2010-02-12  Daniele Varrazzo  <daniele.varrazzo@gmail.com>
97
93
98
94
	* Stop the loop variable used to create __all__ leaking in the module.
99
95
100
96
	* Fixed Inet constructor.
101
97
102
98
	* Fixed docstring for 'QueryCanceledError' exception.
103
99
104
100
2010-02-10  Federico Di Gregorio  <fog@initd.org>
105
101
106
102
	* lib/extensions.py: Binary was not imported from _psycopg; now it is
107
103
108
104
	* lib/__init__: SQL_IN adapter is now automatically registered.
109
105
110
106
	* ZPsycopgDA/db.py: removed logging debug calls; psycopg does
111
107
	not depend on the logger module.
112
108
113
109
2010-02-12  Federico Di Gregorio  <fog@initd.org>
114
110
115
111
	* License migration: psycopg2 is now LGPL3 + OpenSSL exception.
116
112
117
113
	* TODO file was never updated so lets remove it.
118
114
119
115
2010-02-10  Federico Di Gregorio  <fog@initd.org>
120
116
121
117
	* lib/extras.py: fixed register_tstz_w_secs() error as reported by
122
118
	Karsten Hilbert.
123
119
124
120
2009-11-25  Federico Di Gregorio  <fog@initd.org>
125
121
126
122
	* psycopg/microprotocols.c: "can't adapt" message now includes full
127
123
	type information (adapted patch from Eric Chamberlain).
128
124
129
125
	* tests/types_basic.py: fixed test broken by float precision fix.
130
126
131
127
2009-11-09  Federico Di Gregorio  <fog@initd.org>
132
128
133
129
	* psycopg/adapter_pfloat.c: applied patch from Remy Blankto fix float
134
130
	loss of precision.
135
131
136
1
2009-10-04  Federico Di Gregorio  <fog@initd.org>
132
2009-10-04  Federico Di Gregorio  <fog@initd.org>
137
2
133
138
3
	* Release 2.0.13.
134
	* Release 2.0.13.
139
4
135
140
=== modified file 'LICENSE'
141
--- LICENSE	2006-08-09 10:28:30 +0000
142
+++ LICENSE	2010-07-28 20:35:51 +0000
143
@@ -1,24 +1,32 @@
165
1
psycopg and the GPL
1
psycopg2 and the LGPL
166
2
===================
2
=====================
167
3
3
168
4
psycopg is free software; you can redistribute it and/or modify
4
psycopg2 is free software: you can redistribute it and/or modify it
169
5
it under the terms of the GNU General Public License as published by
5
under the terms of the GNU Lesser General Public License as published
170
6
the Free Software Foundation; either version 2 of the License, or
6
by the Free Software Foundation, either version 3 of the License, or
171
7
(at your option) any later version. See file COPYING for details.
7
(at your option) any later version.
172
8
8
173
9
As a special exception, specific permission is granted for the GPLed
9
psycopg2 is distributed in the hope that it will be useful, but WITHOUT
174
10
code in this distribition to be linked to OpenSSL and PostgreSQL libpq
10
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
175
11
without invoking GPL clause 2(b).
11
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
176
12
12
License for more details.
177
13
Note that the GPL was chosen to avoid proprietary adapters based on
13
178
14
psycopg code. Using psycopg in a proprietary product (even bundling
14
In addition, as a special exception, the copyright holders give
179
15
psycopg with the proprietary product) is fine as long as:
15
permission to link this program with the OpenSSL library (or with
180
16
16
modified versions of OpenSSL that use the same license as OpenSSL),
181
17
 1. psycopg is called from Python only using only the provided API
17
and distribute linked combinations including the two.
182
18
    (i.e., no linking with C code and no C modules based on it); and
18
183
19
19
You must obey the GNU Lesser General Public License in all respects for
184
20
 2. all the other points of the GPL are respected (you offer a copy
20
all of the code used other than OpenSSL. If you modify file(s) with this
185
21
    of psycopg's source code, and so on.)
21
exception, you may extend this exception to your version of the file(s),
186
22
but you are not obligated to do so. If you do not wish to do so, delete
187
23
this exception statement from your version. If you delete this exception
188
24
statement from all source files in the program, then also delete it here.
189
25
190
26
You should have received a copy of the GNU Lesser General Public License
191
27
along with psycopg2 (see the doc/ directory.)
192
28
If not, see <http://www.gnu.org/licenses/>.
193
29
194
22
30
195
23
Alternative licenses
31
Alternative licenses
196
24
====================
32
====================
197
@@ -44,17 +52,3 @@
198
44
    be misrepresented as being the original software.
52
    be misrepresented as being the original software.
199
45
 
53
 
200
46
 3. This notice may not be removed or altered from any source distribution.
54
 3. This notice may not be removed or altered from any source distribution.
201
47
202
48
psycopg is distributed in the hope that it will be useful,
203
49
but WITHOUT ANY WARRANTY; without even the implied warranty of
204
50
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
205
51
GNU General Public License for more details.
206
52
207
53
Proprietary licenses
208
54
====================
209
55
210
56
A non-exclusive license is available for companies that want to include
211
57
psycopg in their proprietary products without respecting the spirit of the
212
58
GPL. The price of the license is one day of development done by the author,
213
59
at the consulting fee he applies to his usual customers at the day of the
214
60
request.
215
61
55
216
=== modified file 'MANIFEST'
217
--- MANIFEST	2009-10-12 06:50:00 +0000
218
+++ MANIFEST	2010-07-28 20:35:51 +0000
219
@@ -4,6 +4,8 @@
220
4
LICENSE
4
LICENSE
221
5
MANIFEST
5
MANIFEST
222
6
MANIFEST.in
6
MANIFEST.in
223
7
NEWS-2.0
224
8
NEWS-2.2
225
7
README
9
README
226
8
setup.cfg
10
setup.cfg
227
9
setup.py
11
setup.py
228
@@ -37,13 +39,73 @@
229
37
debian/rules
39
debian/rules
230
38
debian/watch
40
debian/watch
231
39
debian/zope-psycopgda2.dzproduct
41
debian/zope-psycopgda2.dzproduct
232
42
doc/COPYING
233
43
doc/COPYING.LESSER
234
40
doc/ChangeLog-1.x
44
doc/ChangeLog-1.x
235
41
doc/HACKING
45
doc/HACKING
236
46
doc/Makefile
237
47
doc/README
238
42
doc/SUCCESS
48
doc/SUCCESS
243
43
doc/TODO
49
doc/pep-0249.txt
244
44
doc/api-screen.css
50
doc/psycopg2.txt
245
45
doc/async.txt
51
doc/html/.buildinfo
246
46
doc/extensions.rst
52
doc/html/advanced.html
247
53
doc/html/connection.html
248
54
doc/html/cursor.html
249
55
doc/html/errorcodes.html
250
56
doc/html/extensions.html
251
57
doc/html/extras.html
252
58
doc/html/faq.html
253
59
doc/html/genindex.html
254
60
doc/html/index.html
255
61
doc/html/modindex.html
256
62
doc/html/module.html
257
63
doc/html/objects.inv
258
64
doc/html/pool.html
259
65
doc/html/search.html
260
66
doc/html/searchindex.js
261
67
doc/html/tz.html
262
68
doc/html/usage.html
263
69
doc/html/_sources/advanced.txt
264
70
doc/html/_sources/connection.txt
265
71
doc/html/_sources/cursor.txt
266
72
doc/html/_sources/errorcodes.txt
267
73
doc/html/_sources/extensions.txt
268
74
doc/html/_sources/extras.txt
269
75
doc/html/_sources/faq.txt
270
76
doc/html/_sources/index.txt
271
77
doc/html/_sources/module.txt
272
78
doc/html/_sources/pool.txt
273
79
doc/html/_sources/tz.txt
274
80
doc/html/_sources/usage.txt
275
81
doc/html/_static/basic.css
276
82
doc/html/_static/default.css
277
83
doc/html/_static/doctools.js
278
84
doc/html/_static/file.png
279
85
doc/html/_static/jquery.js
280
86
doc/html/_static/minus.png
281
87
doc/html/_static/plus.png
282
88
doc/html/_static/psycopg.css
283
89
doc/html/_static/pygments.css
284
90
doc/html/_static/searchtools.js
285
91
doc/src/Makefile
286
92
doc/src/advanced.rst
287
93
doc/src/conf.py
288
94
doc/src/connection.rst
289
95
doc/src/cursor.rst
290
96
doc/src/errorcodes.rst
291
97
doc/src/extensions.rst
292
98
doc/src/extras.rst
293
99
doc/src/faq.rst
294
100
doc/src/index.rst
295
101
doc/src/module.rst
296
102
doc/src/pool.rst
297
103
doc/src/tz.rst
298
104
doc/src/usage.rst
299
105
doc/src/_static/psycopg.css
300
106
doc/src/tools/stitch_text.py
301
107
doc/src/tools/lib/dbapi_extension.py
302
108
doc/src/tools/lib/sql_role.py
303
47
examples/binary.py
109
examples/binary.py
304
48
examples/copy_from.py
110
examples/copy_from.py
305
49
examples/copy_to.py
111
examples/copy_to.py
306
@@ -84,6 +146,8 @@
307
84
psycopg/adapter_mxdatetime.h
146
psycopg/adapter_mxdatetime.h
308
85
psycopg/adapter_pboolean.c
147
psycopg/adapter_pboolean.c
309
86
psycopg/adapter_pboolean.h
148
psycopg/adapter_pboolean.h
310
149
psycopg/adapter_pdecimal.c
311
150
psycopg/adapter_pdecimal.h
312
87
psycopg/adapter_pfloat.c
151
psycopg/adapter_pfloat.c
313
88
psycopg/adapter_pfloat.h
152
psycopg/adapter_pfloat.h
314
89
psycopg/adapter_qstring.c
153
psycopg/adapter_qstring.c
315
@@ -95,6 +159,8 @@
316
95
psycopg/cursor.h
159
psycopg/cursor.h
317
96
psycopg/cursor_int.c
160
psycopg/cursor_int.c
318
97
psycopg/cursor_type.c
161
psycopg/cursor_type.c
319
162
psycopg/green.c
320
163
psycopg/green.h
321
98
psycopg/lobject.h
164
psycopg/lobject.h
322
99
psycopg/lobject_int.c
165
psycopg/lobject_int.c
323
100
psycopg/lobject_type.c
166
psycopg/lobject_type.c
324
@@ -129,16 +195,20 @@
325
129
psycopg2da/psycopg2da-configure.zcml
195
psycopg2da/psycopg2da-configure.zcml
326
130
psycopg2da/tests.py
196
psycopg2da/tests.py
327
131
scripts/buildtypes.py
197
scripts/buildtypes.py
330
132
scripts/ext2html.py
198
scripts/make_errorcodes.py
329
133
scripts/makedocs.py
331
134
scripts/maketypes.sh
199
scripts/maketypes.sh
332
135
tests/__init__.py
200
tests/__init__.py
333
136
tests/bugX000.py
201
tests/bugX000.py
334
202
tests/bug_gc.py
335
137
tests/dbapi20.py
203
tests/dbapi20.py
336
138
tests/extras_dictcursor.py
204
tests/extras_dictcursor.py
337
205
tests/test_async.py
338
139
tests/test_connection.py
206
tests/test_connection.py
339
207
tests/test_copy.py
340
140
tests/test_dates.py
208
tests/test_dates.py
341
209
tests/test_green.py
342
141
tests/test_lobject.py
210
tests/test_lobject.py
343
211
tests/test_notify.py
344
142
tests/test_psycopg2_dbapi20.py
212
tests/test_psycopg2_dbapi20.py
345
143
tests/test_quote.py
213
tests/test_quote.py
346
144
tests/test_transaction.py
214
tests/test_transaction.py
347
145
215
348
=== modified file 'MANIFEST.in'
349
--- MANIFEST.in	2007-06-18 22:44:12 +0000
350
+++ MANIFEST.in	2010-07-28 20:35:51 +0000
351
@@ -5,9 +5,12 @@
352
5
recursive-include psycopg2da * 
5
recursive-include psycopg2da * 
353
6
recursive-include examples *.py somehackers.jpg whereareyou.jpg
6
recursive-include examples *.py somehackers.jpg whereareyou.jpg
354
7
recursive-include debian *
7
recursive-include debian *
357
8
recursive-include doc TODO HACKING SUCCESS ChangeLog-1.x async.txt
8
recursive-include doc README TODO HACKING SUCCESS COPYING* ChangeLog-1.x pep-0249.txt 
358
9
recursive-include doc *.rst *.css *.html
9
recursive-include doc *.txt *.html *.css *.js Makefile
359
10
recursive-include doc/src *.rst *.py *.css Makefile
360
11
recursive-include doc/html *
361
12
prune doc/src/_build
362
10
recursive-include scripts *.py *.sh
13
recursive-include scripts *.py *.sh
363
11
include scripts/maketypes.sh scripts/buildtypes.py
14
include scripts/maketypes.sh scripts/buildtypes.py
365
12
include AUTHORS README INSTALL LICENSE ChangeLog 
15
include AUTHORS README INSTALL LICENSE NEWS-2.0 NEWS-2.2 ChangeLog 
366
13
include PKG-INFO MANIFEST.in MANIFEST setup.py setup.cfg
16
include PKG-INFO MANIFEST.in MANIFEST setup.py setup.cfg
367
14
17
368
=== added file 'NEWS-2.0'
369
--- NEWS-2.0	1970-01-01 00:00:00 +0000
370
+++ NEWS-2.0	2010-07-28 20:35:51 +0000
371
@@ -0,0 +1,586 @@
372
1
What's new in psycopg 2.0.14
373
2
----------------------------
374
3
375
4
* New features:
376
5
  - Support for adapting tuples to PostgreSQL arrays is now enabled by
377
6
    default and does not require importing psycopg2.extensions anymore.
378
7
  - "can't adapt" error message now includes full type information.
379
8
  - Thank to Daniele Varrazzo (piro) psycopg2's source package now includes
380
9
    full documentation in HTML and plain text format.
381
10
382
11
* Bug fixes:
383
12
  - No loss of precision when using floats anymore.
384
13
  - decimal.Decimal "nan" and "infinity" correctly converted to PostgreSQL
385
14
    numeric NaN values (note that PostgreSQL numeric type does not support
386
15
    infinity but just NaNs.)
387
16
  - psycopg2.extensions now includes Binary.
388
17
389
18
* It seems we're good citizens of the free software ecosystem and that big
390
19
  big big companies and people ranting on the pgsql-hackers mailing list
391
20
  we'll now not dislike us. *g* (See LICENSE file for the details.)
392
21
393
22
394
23
What's new in psycopg 2.0.13
395
24
----------------------------
396
25
397
26
* New features:
398
27
  - Support for UUID arrays.
399
28
  - It is now possible to build psycopg linking to a static libpq
400
29
    library.
401
30
402
31
* Bug fixes:
403
32
  - Fixed a deadlock related to using the same connection with
404
33
    multiple cursors from different threads.
405
34
  - Builds again with MSVC.
406
35
407
36
408
37
What's new in psycopg 2.0.12
409
38
----------------------------
410
39
411
40
* New features:
412
41
  - The connection object now has a reset() method that can be used to
413
42
    reset the connection to its default state.
414
43
415
44
* Bug fixes:
416
45
  - copy_to() and copy_from() now accept a much larger number of columns.
417
46
  - Fixed PostgreSQL version detection.
418
47
  - Fixed ZPsycopgDA version check.
419
48
  - Fixed regression in ZPsycopgDA that made it behave wrongly when
420
49
    receiving serialization errors: now the query is re-issued as it
421
50
    should be by propagating the correct exception to Zope.
422
51
  - Writing "large" large objects should now work.
423
52
424
53
425
54
What's new in psycopg 2.0.11
426
55
----------------------------
427
56
428
57
* New features:
429
58
  - DictRow and RealDictRow now use less memory. If you inherit on them
430
59
    remember to set __slots__ for your new attributes or be prepare to
431
60
    go back to old memory usage.
432
61
433
62
* Bug fixes:
434
63
  - Fixed exeception in setup.py.
435
64
  - More robust detection of PostgreSQL development versions.
436
65
  - Fixed exception in RealDictCursor, introduced in 2.0.10.
437
66
438
67
439
68
What's new in psycopg 2.0.10
440
69
----------------------------
441
70
442
71
* New features:
443
72
  - A specialized type-caster that can parse time zones with seconds is
444
73
    now available. Note that after enabling it (see extras.py) "wrong"
445
74
    time zones will be parsed without raising an exception but the
446
75
    result will be rounded.
447
76
  - DictCursor can be used as a named cursor.
448
77
  - DictRow now implements more dict methods.
449
78
  - The connection object now expose PostgreSQL server version as the
450
79
    .server_version attribute and the protocol version used as
451
80
    .protocol_version.
452
81
  - The connection object has a .get_parameter_status() methods that
453
82
    can be used to obtain useful information from the server.
454
83
455
84
* Bug fixes:
456
85
  - None is now correctly always adapted to NULL.
457
86
  - Two double memory free errors provoked by multithreading and
458
87
    garbage collection are now fixed.
459
88
  - Fixed usage of internal Python code in the notice processor; this
460
89
    should fix segfaults when receiving a lot of notices in
461
90
    multithreaded programs.
462
91
  - Should build again on MSVC and Solaris.
463
92
  - Should build with development versions of PostgreSQL (ones with
464
93
    -devel version string.)
465
94
  - Fixed some tests that failed even when psycopg was right.
466
95
467
96
468
97
What's new in psycopg 2.0.9
469
98
---------------------------
470
99
471
100
* New features:
472
101
  - "import psycopg2.extras" to get some support for handling times
473
102
    and timestamps with seconds in the time zone offset.
474
103
  - DictCursors can now be used as named cursors.
475
104
  
476
105
* Bug fixes:
477
106
  - register_type() now accept an explicit None as its second parameter.
478
107
  - psycopg2 should build again on MSVC and Solaris.
479
108
480
109
481
110
What's new in psycopg 2.0.9
482
111
---------------------------
483
112
484
113
* New features:
485
114
  - COPY TO/COPY FROM queries now can be of any size and psycopg will
486
115
    correctly quote separators.
487
116
  - float values Inf and NaN are now correctly handled and can
488
117
    round-trip to the database.
489
118
  - executemany() now return the numer of total INSERTed or UPDATEd
490
119
    rows. Note that, as it has always been, executemany() should not
491
120
    be used to execute multiple SELECT statements and while it will
492
121
    execute the statements without any problem, it will return the
493
122
    wrong value.
494
123
  - copy_from() and copy_to() can now use quoted separators.
495
124
  - "import psycopg2.extras" to get UUID support.
496
125
  
497
126
* Bug fixes:
498
127
  - register_type() now works on connection and cursor subclasses.
499
128
  - fixed a memory leak when using lobjects.
500
129
  
501
130
502
131
What's new in psycopg 2.0.8
503
132
---------------------------
504
133
505
134
* New features:
506
135
  - The connection object now has a get_backend_pid() method that
507
136
    returns the current PostgreSQL connection backend process PID.
508
137
  - The PostgreSQL large object API has been exposed through the
509
138
    Cursor.lobject() method.
510
139
511
140
* Bug fixes:
512
141
  - Some fixes to ZPsycopgDA have been merged from the Debian package.
513
142
  - A memory leak was fixed in Cursor.executemany().
514
143
  - A double free was fixed in pq_complete_error(), that caused crashes
515
144
    under some error conditions.
516
145
517
146
What's new in psycopg 2.0.7
518
147
---------------------------
519
148
520
149
* Improved error handling:
521
150
  - All instances of psycopg2.Error subclasses now have pgerror,
522
151
    pgcode and cursor attributes.  They will be set to None if no
523
152
    value is available.
524
153
  - Exception classes are now chosen based on the SQLSTATE value from
525
154
    the result.  (#184)
526
155
  - The commit() and rollback() methods now set the pgerror and pgcode
527
156
    attributes on exceptions. (#152)
528
157
  - errors from commit() and rollback() are no longer considered
529
158
    fatal. (#194)
530
159
  - If a disconnect is detected during execute(), an exception will be
531
160
    raised at that point rather than resulting in "ProgrammingError:
532
161
    no results to fetch" later on. (#186)
533
162
534
163
* Better PostgreSQL compatibility:
535
164
  - If the server uses standard_conforming_strings, perform
536
165
    appropriate quoting.
537
166
  - BC dates are now handled if psycopg is compiled with mxDateTime
538
167
    support.  If using datetime, an appropriate ValueError is
539
168
    raised. (#203)
540
169
541
170
* Other bug fixes:
542
171
  - If multiple sub-interpreters are in use, do not share the Decimal
543
172
    type between them. (#192)
544
173
  - Buffer objects obtained from psycopg are now accepted by psycopg
545
174
    too, without segfaulting. (#209)
546
175
  - A few small changes were made to improve DB-API compatibility.
547
176
    All the dbapi20 tests now pass.
548
177
549
178
* Miscellaneous:
550
179
  - The PSYCOPG_DISPLAY_SIZE option is now off by default.  This means
551
180
    that display size will always be set to "None" in
552
181
    cursor.description.  Calculating the display size was expensive,
553
182
    and infrequently used so this should improve performance.
554
183
  - New QueryCanceledError and TransactionRollbackError exceptions
555
184
    have been added to the psycopg2.extensions module.  They can be
556
185
    used to detect statement timeouts and deadlocks respectively.
557
186
  - Cursor objects now have a "closed" attribute. (#164)
558
187
  - If psycopg has been built with debug support, it is now necessary
559
188
    to set the PSYCOPG_DEBUG environment variable to turn on debug
560
189
    spew.
561
190
562
191
What's new in psycopg 2.0.6
563
192
---------------------------
564
193
565
194
* Better support for PostgreSQL, Python and win32:
566
195
  - full support for PostgreSQL 8.2, including NULLs in arrays
567
196
  - support for almost all existing PostgreSQL encodings
568
197
  - full list of PostgreSQL error codes available by importing the
569
198
    psycopg2.errorcodes module
570
199
  - full support for Python 2.5 and 64 bit architectures
571
200
  - better build support on win32 platform
572
201
573
202
* Support for per-connection type-casters (used by ZPsycopgDA too, this
574
203
  fixes a long standing bug that made different connections use a random
575
204
  set of date/time type-casters instead of the configured one.)
576
205
577
206
* Better management of times and dates both from Python and in Zope.
578
207
579
208
* copy_to and copy_from now take an extra "columns" parameter.
580
209
581
210
* Python tuples are now adapted to SQL sequences that can be used with
582
211
  the "IN" operator by default if the psycopg2.extensions module is
583
212
  imported (i.e., the SQL_IN adapter was moved from extras to extensions.)
584
213
585
214
* Fixed some small buglets and build glitches:
586
215
  - removed double mutex destroy
587
216
  - removed all non-constant initializers
588
217
  - fixed PyObject_HEAD declarations to avoid memory corruption
589
218
    on 64 bit architectures
590
219
  - fixed several Python API calls to work on 64 bit architectures
591
220
  - applied compatibility macros from PEP 353
592
221
  - now using more than one argument format raise an error instead of
593
222
    a segfault
594
223
595
224
What's new in psycopg 2.0.5.1
596
225
----------------------------
597
226
598
227
* Now it really, really builds on MSVC and older gcc versions.
599
228
600
229
What's new in psycopg 2.0.5
601
230
--------------------------
602
231
603
232
* Fixed various buglets such as:
604
233
  - segfault when passing an empty string to Binary()
605
234
  - segfault on null queries
606
235
  - segfault and bad keyword naming in .executemany()
607
236
  - OperationalError in connection objects was always None
608
237
609
238
* Various changes to ZPsycopgDA to make it more zope2.9-ish.
610
239
611
240
* connect() now accept both integers and strings as port parameter
612
241
613
242
What's new in psycopg 2.0.4
614
243
---------------------------
615
244
616
245
* Fixed float conversion bug introduced in 2.0.3.
617
246
618
247
What's new in psycopg 2.0.3
619
248
---------------------------
620
249
621
250
* Fixed various buglets and a memory leak (see ChangeLog for details)
622
251
623
252
What's new in psycopg 2.0.2
624
253
---------------------------
625
254
626
255
* Fixed a bug in array typecasting that sometimes made psycopg forget about
627
256
  the last element in the array.
628
257
629
258
* Fixed some minor buglets in string memory allocations.
630
259
631
260
* Builds again with compilers different from gcc (#warning about PostgreSQL
632
261
  version is issued only if __GCC__ is defined.)
633
262
634
263
What's new in psycopg 2.0.1
635
264
---------------------------
636
265
637
266
* ZPsycopgDA now actually loads.
638
267
639
268
What's new in psycopg 2.0
640
269
-------------------------
641
270
642
271
* Fixed handle leak on win32.
643
272
644
273
* If available the new "safe" encoding functions of libpq are used.
645
274
646
275
* django and tinyerp people, please switch to psycopg 2 _without_
647
276
  using a psycopg 1 compatibility layer (this release was anticipated
648
277
  so that you all stop grumbling about psycopg 2 is still in beta.. :)
649
278
650
279
What's new in psycopg 2.0 beta 7
651
280
--------------------------------
652
281
653
282
* Ironed out last problems with times and date (should be quite solid now.)
654
283
655
284
* Fixed problems with some arrays.
656
285
657
286
* Slightly better ZPsycopgDA (no more double connection objects in the menu
658
287
  and other minor fixes.)
659
288
  
660
289
* ProgrammingError exceptions now have three extra attributes: .cursor
661
290
  (it is possible to access the query that caused the exception using
662
291
  error.cursor.query), .pgerror and .pgcode (PostgreSQL original error
663
292
  text and code.)
664
293
  
665
294
* The build system uses pg_config when available.
666
295
   
667
296
* Documentation in the doc/ directory! (With many kudos to piro.)
668
297
669
298
What's new in psycopg 2.0 beta 6
670
299
--------------------------------
671
300
672
301
* Support for named cursors (see examples/fetch.py).
673
302
674
303
* Safer parsing of time intervals.
675
304
676
305
* Better parsing of times and dates, no more locale problems.
677
306
678
307
* Should now play well with py2exe and similar tools.
679
308
680
309
* The "decimal" module is now used if available under Python 2.3.
681
310
682
311
What's new in psycopg 2.0 beta 5
683
312
--------------------------------
684
313
685
314
* Fixed all known bugs.
686
315
687
316
* The initial isolation level is now read from the server and
688
317
  .set_isolation_level() now takes values defined in psycopg2.extensions.
689
318
  
690
319
* .callproc() implemented as a SELECT of the given procedure.
691
320
692
321
* Better docstrings for a few functions/methods.
693
322
694
323
* Some time-related functions like psycopg2.TimeFromTicks() now take the
695
324
  local timezone into account. Also a tzinfo object (as per datetime module
696
325
  specifications) can be passed to the psycopg2.Time and psycopg2.Datetime
697
326
  constructors.
698
327
  
699
328
* All classes have been renamed to exist in the psycopg2._psycopg module,
700
329
  to fix problems with automatic documentation generators like epydoc.
701
330
  
702
331
* NOTIFY is correctly trapped (see examples/notify.py for example code.)
703
332
704
333
What's new in psycopg 2.0 beta 4
705
334
--------------------------------
706
335
707
336
* psycopg module is now named psycopg2.
708
337
709
338
* No more segfaults when a UNICODE query can't be converted to the
710
339
  backend encoding.
711
340
  
712
341
* No more segfaults on empty queries.
713
342
714
343
* psycopg2.connect() now takes an integer for the port keyword parameter.
715
344
716
345
* "python setup.py bdist_rpm" now works.
717
346
718
347
* Fixed lots of small bugs, see ChangeLog for details.
719
348
720
349
What's new in psycopg 2.0 beta 3
721
350
--------------------------------
722
351
723
352
* ZPsycopgDA now works (except table browsing.)
724
353
725
354
* psycopg build again on Python 2.2.
726
355
727
356
What's new in psycopg 2.0 beta 2
728
357
--------------------------------
729
358
730
359
* Fixed ZPsycopgDA version check (ZPsycopgDA can now be imported in
731
360
  Zope.)
732
361
733
362
* psycopg.extras.DictRow works even after a new query on the generating
734
363
  cursor.
735
364
736
365
* Better setup.py for win32 (should build with MSCV or mingw.)
737
366
738
367
* Generic fixed and memory leaks plugs.
739
368
740
369
What's new in psycopg 2.0 beta 1
741
370
--------------------------------
742
371
743
372
* Officially in beta (i.e., no new features will be added.)
744
373
745
374
* Array support: list objects can be passed as bound variables and are
746
375
  correctly returned for array columns.
747
376
748
377
* Added the psycopg.psycopg1 compatibility module (if you want instant
749
378
  psycopg 1 compatibility just "from psycopg import psycopg1 as psycopg".)
750
379
751
380
* Complete support for BYTEA columns and buffer objects.
752
381
753
382
* Added error codes to error messages.
754
383
755
384
* The AsIs adapter is now exported by default (also Decimal objects are
756
385
  adapted using the AsIs adapter (when str() is called on them they
757
386
  already format themselves using the right precision and scale.)
758
387
759
388
* The connect() function now takes "connection_factory" instead of
760
389
  "factory" as keyword argument.
761
390
762
391
* New setup.py code to build on win32 using mingw and better error
763
392
  messages on missing datetime headers,
764
393
765
394
* Internal changes that allow much better user-defined type casters.
766
395
767
396
* A lot of bugfixes (binary, datetime, 64 bit arches, GIL, .executemany())
768
397
 
769
398
What's new in psycopg 1.99.13
770
399
-----------------------------
771
400
772
401
* Added missing .executemany() method.
773
402
774
403
* Optimized type cast from PostgreSQL to Python (psycopg should be even
775
404
  faster than before.)
776
405
777
406
What's new in psycopg 1.99.12
778
407
-----------------------------
779
408
780
409
* .rowcount should be ok and in sync with psycopg 1.
781
410
782
411
* Implemented the new COPY FROM/COPY TO code when connection to the
783
412
  backend using libpq protocol 3 (this also removes all asprintf calls:
784
413
  build on win32 works again.) A protocol 3-enabled psycopg *can*
785
414
  connect to an old protocol 2 database and will detect it and use the
786
415
  right code.
787
416
788
417
* getquoted() called for real by the mogrification code.
789
418
790
419
What's new in psycopg 1.99.11
791
420
-----------------------------
792
421
793
422
* 'cursor' argument in .cursor() connection method renamed to 
794
423
  'cursor_factory'.
795
424
796
425
* changed 'tuple_factory' cursor attribute name to 'row_factory'.
797
426
798
427
* the .cursor attribute is gone and connections and cursors are propely
799
428
  gc-managed.
800
429
801
430
* fixes to the async core.
802
431
803
432
What's new in psycopg 1.99.10
804
433
-----------------------------
805
434
806
435
* The adapt() function now fully supports the adaptation protocol
807
436
  described in PEP 246. Note that the adapters registry now is indexed
808
437
  by (type, protocol) and not by type alone. Change your adapters
809
438
  accordingly.
810
439
811
440
* More configuration options moved from setup.py to setup.cfg.
812
441
813
442
* Fixed two memory leaks: one in cursor deallocation and one in row
814
443
  fetching (.fetchXXX() methods.)
815
444
816
445
What's new in psycopg 1.99.9
817
446
----------------------------
818
447
819
448
* Added simple pooling code (psycopg.pool module); see the reworked
820
449
  examples/threads.py for example code.
821
450
822
451
* Added DECIMAL typecaster to convert postgresql DECIMAL and NUMERIC
823
452
  types (i.e, all types with an OID of NUMERICOID.) Note that the
824
453
  DECIMAL typecaster does not set scale and precision on the created
825
454
  objects but uses Python defaults.
826
455
827
456
* ZPsycopgDA back in and working using the new pooling code.
828
457
829
458
* Isn't that enough? :)
830
459
831
460
What's new in psycopg 1.99.8
832
461
----------------------------
833
462
834
463
* added support for UNICODE queries.
835
464
836
465
* added UNICODE typecaster; to activate it just do:
837
466
    
838
467
    psycopg.extensions.register_type(psycopg.extensions.UNICODE)
839
468
  
840
469
  Note that the UNICODE typecaster override the STRING one, so it is
841
470
  not activated by default.
842
471
843
472
* cursors now really support the iterator protocol.
844
473
845
474
* solved the rounding errors in time conversions.
846
475
847
476
* now cursors support .fileno() and .isready() methods, to be used in
848
477
  select() calls.
849
478
850
479
* .copy_from() and .copy_in() methods are back in (still using the old
851
480
  protocol, will be updated to use new one in next releasae.)
852
481
853
482
* fixed memory corruption bug reported on win32 platform.
854
483
855
484
What's new in psycopg 1.99.7
856
485
----------------------------
857
486
858
487
* added support for tuple factories in cursor objects (removed factory
859
488
  argument in favor of a .tuple_factory attribute on the cursor object);
860
489
  see the new module psycopg.extras for a cursor (DictCursor) that
861
490
  return rows as objects that support indexing both by position and
862
491
  column name.
863
492
864
493
* added support for tzinfo objects in datetime.timestamp objects: the
865
494
  PostgreSQL type "timestamp with time zone" is converted to 
866
495
  datetime.timestamp with a FixedOffsetTimezone initialized as necessary.
867
496
868
497
What's new in psycopg 1.99.6
869
498
----------------------------
870
499
871
500
* sslmode parameter from 1.1.x
872
501
873
502
* various datetime conversion improvements.
874
503
875
504
* now psycopg should compile without mx or without native datetime
876
505
  (not both, obviously.)
877
506
878
507
* included various win32/MSVC fixes (pthread.h changes, winsock2
879
508
  library, include path in setup.py, etc.)
880
509
881
510
* ported interval fixes from 1.1.14/1.1.15.
882
511
883
512
* the last query executed by a cursor is now available in the
884
513
  .query attribute.
885
514
886
515
* conversion of unicode strings to backend encoding now uses a table
887
516
  (that still need to be filled.)
888
517
889
518
* cursors now have a .mogrify() method that return the query string
890
519
  instead of executing it.
891
520
892
521
* connection objects now have a .dsn read-only attribute that holds the
893
522
  connection string.
894
523
895
524
* moved psycopg C module to _psycopg and made psycopg a python module:
896
525
  this allows for a neat separation of DBAPI-2.0 functionality and psycopg
897
526
  extensions; the psycopg namespace will be also used to provide
898
527
  python-only extensions (like the pooling code, some ZPsycopgDA support
899
528
  functions and the like.)
900
529
901
530
What's new in psycopg 1.99.3
902
531
----------------------------
903
532
904
533
* added support for python 2.3 datetime types (both ways) and made datetime
905
534
  the default set of typecasters when available.
906
535
907
536
* added example: dt.py.
908
537
909
538
What's new in psycopg 1.99.3
910
539
----------------------------
911
540
912
541
* initial working support for unicode bound variables: UTF-8 and latin-1
913
542
  backend encodings are natively supported (and the encoding.py example even
914
543
  works!)
915
544
916
545
* added .set_client_encoding() method on the connection object.
917
546
918
547
* added examples: encoding.py, binary.py, lastrowid.py.
919
548
920
549
What's new in psycopg 1.99.2
921
550
----------------------------
922
551
923
552
* better typecasting:
924
553
  - DateTimeDelta used for postgresql TIME (merge from 1.1)
925
554
  - BYTEA now is converted to a real buffer object, not to a string
926
555
927
556
* buffer objects are now adapted into Binary objects automatically.
928
557
929
558
* ported scroll method from 1.1 (DBAPI-2.0 extension for cursors)
930
559
931
560
* initial support for some DBAPI-2.0 extensions:
932
561
  - .rownumber attribute for cursors
933
562
  - .connection attribute for cursors
934
563
  - .next() and .__iter__() methods to have cursors support the iterator
935
564
    protocol
936
565
  - all exception objects are exported to the connection object
937
566
938
567
What's new in psycopg 1.99.1
939
568
----------------------------
940
569
941
570
* implemented microprotocols to adapt arbitrary types to the interface used by
942
571
  psycopg to bind variables in execute;
943
572
944
573
* moved qstring, pboolean and mxdatetime to the new adapter layout (binary is
945
574
  still missing; python 2.3 datetime needs to be written).
946
575
947
576
948
577
What's new in psycopg 1.99.0
949
578
----------------------------
950
579
951
580
* reorganized the whole source tree;
952
581
953
582
* async core is in place;
954
583
955
584
* splitted QuotedString objects from mx stuff;
956
585
957
586
* dropped autotools and moved to pythonic setup.py (needs work.)
958
0
587
959
=== added file 'NEWS-2.2'
960
--- NEWS-2.2	1970-01-01 00:00:00 +0000
961
+++ NEWS-2.2	2010-07-28 20:35:51 +0000
962
@@ -0,0 +1,39 @@
963
1
What's new in psycopg 2.2.1
964
2
---------------------------
965
3
966
4
* Bux fixes:
967
5
  - psycopg now builds again on MS Windows.
968
6
969
7
970
8
What's new in psycopg 2.2.0
971
9
---------------------------
972
10
973
11
This is the first release of the new 2.2 series, supporting not just one but
974
12
two different ways of executing asynchronous queries, thanks to Jan and Daniele
975
13
(with a little help from me and others, but they did 99% of the work so they
976
14
deserve their names here in the news.)
977
15
978
16
psycopg now supports both classic select() loops and "green" coroutine
979
17
libraries. It is all in the documentation, so just point your browser to
980
18
doc/html/advanced.html.
981
19
982
20
* Other new features:
983
21
  - truncate() method for lobjects.
984
22
  - COPY functions are now a little bit faster.
985
23
  - All builtin PostgreSQL to Python typecasters are now available from the
986
24
    psycopg2.extensions module.
987
25
  - Notifications from the backend are now available right after the execute()
988
26
    call (before client code needed to call isbusy() to ensure NOTIFY
989
27
    reception.)
990
28
  - Better timezone support.
991
29
  - Lots of documentation updates.
992
30
993
31
* Bug fixes:
994
32
  - Fixed some gc/refcounting problems.
995
33
  - Fixed reference leak in NOTIFY reception.
996
34
  - Fixed problem with PostgreSQL not casting string literals to the correct
997
35
    types in some situations: psycopg now add an explicit cast to dates, times
998
36
    and bytea representations.
999
37
  - Fixed TimestampFromTicks() and TimeFromTicks() for seconds >= 59.5.
1000
38
  - Fixed spurious exception raised when calling C typecasters from Python
1001
39
    ones.
1002
0
40
1003
=== modified file 'PKG-INFO'
1004
--- PKG-INFO	2009-10-12 06:50:00 +0000
1005
+++ PKG-INFO	2010-07-28 20:35:51 +0000
1006
@@ -1,6 +1,6 @@
1007
1
Metadata-Version: 1.0
1
Metadata-Version: 1.0
1008
2
Name: psycopg2
2
Name: psycopg2
1010
3
Version: 2.0.13
3
Version: 2.2.1
1011
4
Summary: Python-PostgreSQL Database Adapter
4
Summary: Python-PostgreSQL Database Adapter
1012
5
Home-page: http://initd.org/tracker/psycopg
5
Home-page: http://initd.org/tracker/psycopg
1013
6
Author: Federico Di Gregorio
6
Author: Federico Di Gregorio
1014
@@ -20,9 +20,9 @@
1015
20
        brave programmer.
20
        brave programmer.
1016
21
        
21
        
1017
22
Platform: any
22
Platform: any
1019
23
Classifier: Development Status :: 4 - Beta
23
Classifier: Development Status :: 5 - Production/Stable
1020
24
Classifier: Intended Audience :: Developers
24
Classifier: Intended Audience :: Developers
1022
25
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
25
Classifier: License :: OSI Approved :: GNU Lesser General Public License (LGPL)
1023
26
Classifier: License :: OSI Approved :: Zope Public License
26
Classifier: License :: OSI Approved :: Zope Public License
1024
27
Classifier: Programming Language :: Python
27
Classifier: Programming Language :: Python
1025
28
Classifier: Programming Language :: C
28
Classifier: Programming Language :: C
1026
29
29
1027
=== modified file 'README'
1028
--- README	2006-08-09 10:28:30 +0000
1029
+++ README	2010-07-28 20:35:51 +0000
1030
@@ -1,28 +1,32 @@
1032
1
psycopg - Python-PostgreSQL Database Adapter
1
psycopg2 - Python-PostgreSQL Database Adapter
1033
2
********************************************
2
********************************************
1034
3
3
1036
4
psycopg is a PostgreSQL database adapter for the Python programming
4
psycopg2 is a PostgreSQL database adapter for the Python programming
1037
5
language. This is version 2, a complete rewrite of the original code to
5
language. This is version 2, a complete rewrite of the original code to
1038
6
provide new-style classes for connection and cursor objects and other
6
provide new-style classes for connection and cursor objects and other
1040
7
sweet candies. Like the original, psycopg 2 was written with the aim of
7
sweet candies. Like the original, psycopg2 was written with the aim of
1041
8
being very small and fast, and stable as a rock.
8
being very small and fast, and stable as a rock.
1042
9
9
1044
10
psycopg is different from the other database adapter because it was
10
psycopg2 is different from the other database adapter because it was
1045
11
designed for heavily multi-threaded applications that create and destroy
11
designed for heavily multi-threaded applications that create and destroy
1046
12
lots of cursors and make a conspicuous number of concurrent INSERTs or
12
lots of cursors and make a conspicuous number of concurrent INSERTs or
1048
13
UPDATEs. psycopg 2 also provide full asycronous operations for the really
13
UPDATEs. psycopg2 also provide full asycronous operations for the really
1049
14
brave programmer.
14
brave programmer.
1050
15
15
1051
16
There are confirmed reports of psycopg 1.x compiling and running on Linux
16
There are confirmed reports of psycopg 1.x compiling and running on Linux
1053
17
and FreeBSD on i386, Solaris, MacOS X and win32 architectures. psycopg 2
17
and FreeBSD on i386, Solaris, MacOS X and win32 architectures. psycopg2
1054
18
does not introduce build-wise incompatible changes so it should be able to
18
does not introduce build-wise incompatible changes so it should be able to
1055
19
compile on all architectures just as its predecessor did.
19
compile on all architectures just as its predecessor did.
1056
20
20
1058
21
Now go read the INSTALL file. More information about psycopg extensions to
21
Now go read the INSTALL file. More information about psycopg2 extensions to
1059
22
the DBAPI-2.0 is available in the files located in the doc/ direcory.
22
the DBAPI-2.0 is available in the files located in the doc/ direcory.
1060
23
Example code can be found in the examples/ directory. If you make any changes
1061
24
to the code make sure to run the unit tests localed in tests/.
1062
23
25
1065
24
psycopg is free software ("free as in freedom" but I like beer too.)
26
psycopg2 is free software ("free as in freedom" but I like beer too.)
1066
25
Licensing information is available in the LICENSE file.
27
It is licensed under the GNU Lesser General Public License, version 3 or
1067
28
later plus an exception to allow OpenSSL (libpq) linking; see LICENSE for
1068
29
more details.
1069
26
30
1070
27
31
1071
28
Contributors
32
Contributors
1072
29
33
1073
=== modified file 'ZPsycopgDA/DA.py'
1074
--- ZPsycopgDA/DA.py	2009-10-12 06:50:00 +0000
1075
+++ ZPsycopgDA/DA.py	2010-07-28 20:35:51 +0000
1076
@@ -1,24 +1,22 @@
1077
1
# ZPsycopgDA/DA.py - ZPsycopgDA Zope product: Database Connection
1
# ZPsycopgDA/DA.py - ZPsycopgDA Zope product: Database Connection
1078
2
#
2
#
1098
3
# Copyright (C) 2004 Federico Di Gregorio <fog@initd.org>
3
# Copyright (C) 2004-2010 Federico Di Gregorio  <fog@debian.org>
1099
4
#
4
#
1100
5
# This program is free software; you can redistribute it and/or modify
5
# psycopg2 is free software: you can redistribute it and/or modify it
1101
6
# it under the terms of the GNU General Public License as published by the
6
# under the terms of the GNU Lesser General Public License as published
1102
7
# Free Software Foundation; either version 2, or (at your option) any later
7
# by the Free Software Foundation, either version 3 of the License, or
1103
8
# version.
8
# (at your option) any later version.
1104
9
#
9
#
1105
10
# Or, at your option this program (ZPsycopgDA) can be distributed under the
10
# psycopg2 is distributed in the hope that it will be useful, but WITHOUT
1106
11
# Zope Public License (ZPL) Version 1.0, as published on the Zope web site,
11
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1107
12
# http://www.zope.org/Resources/ZPL.
12
# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
1108
13
#
13
# License for more details.
1109
14
# This program is distributed in the hope that it will be useful, but
14
1110
15
# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
15
# Import modules needed by _psycopg to allow tools like py2exe to do
1111
16
# or FITNESS FOR A PARTICULAR PURPOSE.
16
# their work without bothering about the module dependencies.
1112
17
#
17
1113
18
# See the LICENSE file for details.
18
1114
19
19
ALLOWED_PSYCOPG_VERSIONS = ('2.2.0','2.2.1')
1096
20
1097
21
ALLOWED_PSYCOPG_VERSIONS = ('2.0.7','2.0.8','2.0.9','2.0.10', '2.0.11', '2.0.12', '2.0.13')
1115
22
20
1116
23
import sys
21
import sys
1117
24
import time
22
import time
1118
25
23
1119
=== modified file 'ZPsycopgDA/__init__.py'
1120
--- ZPsycopgDA/__init__.py	2006-08-09 10:28:30 +0000
1121
+++ ZPsycopgDA/__init__.py	2010-07-28 20:35:51 +0000
1122
@@ -1,21 +1,19 @@
1123
1
# ZPsycopgDA/__init__.py - ZPsycopgDA Zope product
1
# ZPsycopgDA/__init__.py - ZPsycopgDA Zope product
1124
2
#
2
#
1141
3
# Copyright (C) 2004 Federico Di Gregorio <fog@initd.org>
3
# Copyright (C) 2004-2010 Federico Di Gregorio  <fog@debian.org>
1142
4
#
4
#
1143
5
# This program is free software; you can redistribute it and/or modify
5
# psycopg2 is free software: you can redistribute it and/or modify it
1144
6
# it under the terms of the GNU General Public License as published by the
6
# under the terms of the GNU Lesser General Public License as published
1145
7
# Free Software Foundation; either version 2, or (at your option) any later
7
# by the Free Software Foundation, either version 3 of the License, or
1146
8
# version.
8
# (at your option) any later version.
1147
9
#
9
#
1148
10
# Or, at your option this program (ZPsycopgDA) can be distributed under the
10
# psycopg2 is distributed in the hope that it will be useful, but WITHOUT
1149
11
# Zope Public License (ZPL) Version 1.0, as published on the Zope web site,
11
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1150
12
# http://www.zope.org/Resources/ZPL.
12
# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
1151
13
#
13
# License for more details.
1152
14
# This program is distributed in the hope that it will be useful, but
14
1153
15
# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
15
# Import modules needed by _psycopg to allow tools like py2exe to do
1154
16
# or FITNESS FOR A PARTICULAR PURPOSE.
16
# their work without bothering about the module dependencies.
1139
17
#
1140
18
# See the LICENSE file for details.
1155
19
17
1156
20
__doc__ = "ZPsycopg Database Adapter Registration." 
18
__doc__ = "ZPsycopg Database Adapter Registration." 
1157
21
__version__ = '2.0'
19
__version__ = '2.0'
1158
22
20
1159
=== modified file 'ZPsycopgDA/db.py'
1160
--- ZPsycopgDA/db.py	2009-08-27 18:05:48 +0000
1161
+++ ZPsycopgDA/db.py	2010-07-28 20:35:51 +0000
1162
@@ -1,21 +1,19 @@
1163
1
# ZPsycopgDA/db.py - query execution
1
# ZPsycopgDA/db.py - query execution
1164
2
#
2
#
1181
3
# Copyright (C) 2004 Federico Di Gregorio <fog@initd.org>
3
# Copyright (C) 2004-2010 Federico Di Gregorio  <fog@debian.org>
1182
4
#
4
#
1183
5
# This program is free software; you can redistribute it and/or modify
5
# psycopg2 is free software: you can redistribute it and/or modify it
1184
6
# it under the terms of the GNU General Public License as published by the
6
# under the terms of the GNU Lesser General Public License as published
1185
7
# Free Software Foundation; either version 2, or (at your option) any later
7
# by the Free Software Foundation, either version 3 of the License, or
1186
8
# version.
8
# (at your option) any later version.
1187
9
#
9
#
1188
10
# Or, at your option this program (ZPsycopgDA) can be distributed under the
10
# psycopg2 is distributed in the hope that it will be useful, but WITHOUT
1189
11
# Zope Public License (ZPL) Version 1.0, as published on the Zope web site,
11
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1190
12
# http://www.zope.org/Resources/ZPL.
12
# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
1191
13
#
13
# License for more details.
1192
14
# This program is distributed in the hope that it will be useful, but
14
1193
15
# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
15
# Import modules needed by _psycopg to allow tools like py2exe to do
1194
16
# or FITNESS FOR A PARTICULAR PURPOSE.
16
# their work without bothering about the module dependencies.
1179
17
#
1180
18
# See the LICENSE file for details.
1195
19
17
1196
20
from Shared.DC.ZRDB.TM import TM
18
from Shared.DC.ZRDB.TM import TM
1197
21
from Shared.DC.ZRDB import dbi_db
19
from Shared.DC.ZRDB import dbi_db
1198
@@ -171,15 +169,15 @@
1199
171
                        c.execute(qs)
169
                        c.execute(qs)
1200
172
                except TransactionRollbackError:
170
                except TransactionRollbackError:
1201
173
                    # Ha, here we have to look like we are the ZODB raising conflict errrors, raising ZPublisher.Publish.Retry just doesn't work
171
                    # Ha, here we have to look like we are the ZODB raising conflict errrors, raising ZPublisher.Publish.Retry just doesn't work
1203
174
                    logging.debug("Serialization Error, retrying transaction", exc_info=True)
172
                    #logging.debug("Serialization Error, retrying transaction", exc_info=True)
1204
175
                    raise ConflictError("TransactionRollbackError from psycopg2")
173
                    raise ConflictError("TransactionRollbackError from psycopg2")
1205
176
                except psycopg2.OperationalError:
174
                except psycopg2.OperationalError:
1207
177
                    logging.exception("Operational error on connection, closing it.")
175
                    #logging.exception("Operational error on connection, closing it.")
1208
178
                    try:
176
                    try:
1209
179
                        # Only close our connection
177
                        # Only close our connection
1210
180
                        self.putconn(True)
178
                        self.putconn(True)
1211
181
                    except:
179
                    except:
1213
182
                        logging.debug("Something went wrong when we tried to close the pool", exc_info=True)
180
                        #logging.debug("Something went wrong when we tried to close the pool", exc_info=True)
1214
183
                        pass
181
                        pass
1215
184
                if c.description is not None:
182
                if c.description is not None:
1216
185
                    nselects += 1
183
                    nselects += 1
1217
186
184
1218
=== modified file 'ZPsycopgDA/pool.py'
1219
--- ZPsycopgDA/pool.py	2006-08-09 10:28:30 +0000
1220
+++ ZPsycopgDA/pool.py	2010-07-28 20:35:51 +0000
1221
@@ -1,24 +1,22 @@
1222
1
# ZPsycopgDA/pool.py - ZPsycopgDA Zope product: connection pooling
1
# ZPsycopgDA/pool.py - ZPsycopgDA Zope product: connection pooling
1223
2
#
2
#
1243
3
# Copyright (C) 2004 Federico Di Gregorio <fog@initd.org>
3
# Copyright (C) 2004-2010 Federico Di Gregorio  <fog@debian.org>
1244
4
#
4
#
1245
5
# This program is free software; you can redistribute it and/or modify
5
# psycopg2 is free software: you can redistribute it and/or modify it
1246
6
# it under the terms of the GNU General Public License as published by the
6
# under the terms of the GNU Lesser General Public License as published
1247
7
# Free Software Foundation; either version 2, or (at your option) any later
7
# by the Free Software Foundation, either version 3 of the License, or
1248
8
# version.
8
# (at your option) any later version.
1249
9
#
9
#
1250
10
# Or, at your option this program (ZPsycopgDA) can be distributed under the
10
# psycopg2 is distributed in the hope that it will be useful, but WITHOUT
1251
11
# Zope Public License (ZPL) Version 1.0, as published on the Zope web site,
11
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1252
12
# http://www.zope.org/Resources/ZPL.
12
# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
1253
13
#
13
# License for more details.
1254
14
# This program is distributed in the hope that it will be useful, but
14
1255
15
# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
15
# Import modules needed by _psycopg to allow tools like py2exe to do
1256
16
# or FITNESS FOR A PARTICULAR PURPOSE.
16
# their work without bothering about the module dependencies.
1257
17
#
17
1258
18
# See the LICENSE file for details.
18
# All the connections are held in a pool of pools, directly accessible by the
1259
19
19
# ZPsycopgDA code in db.py.
1241
20
# all the connections are held in a pool of pools, directly accessible by the
1242
21
# ZPsycopgDA code in db.py
1260
22
20
1261
23
import threading
21
import threading
1262
24
import psycopg2.pool
22
import psycopg2.pool
1263
25
23
1264
=== modified file 'debian/changelog'
1265
--- debian/changelog	2010-04-16 10:05:03 +0000
1266
+++ debian/changelog	2010-07-28 20:35:51 +0000
1267
@@ -1,3 +1,26 @@
1268
1
psycopg2 (2.2.1-1ubuntu1) maverick; urgency=low
1269
2
1270
3
  * Merge from Debian (LP: #611040). Remaining changes:
1271
4
    debian/control, debian/rules: Install a seperate testsuite package.
1272
5
1273
6
 -- Mikhail Turov <groldster@gmail.com>  Wed, 28 Jul 2010 21:20:45 +0100
1274
7
1275
8
psycopg2 (2.2.1-1) unstable; urgency=low
1276
9
1277
10
  * New upstream release. (Closes: #582823)
1278
11
  * debian/control:
1279
12
    - bumped Standards-Version to 3.9.0, no changes required.
1280
13
    - removed the zope-psycopg2da binary package. (Closes: #583293)
1281
14
1282
15
 -- Fabio Tranchitella <kobold@debian.org>  Fri, 02 Jul 2010 15:04:19 +0200
1283
16
1284
17
psycopg2 (2.0.14-1) unstable; urgency=low
1285
18
1286
19
  * New upstream release.
1287
20
  * debian/control: bumped Standards-Version to 3.8.5, no changes required.
1288
21
1289
22
 -- Fabio Tranchitella <kobold@debian.org>  Sat, 10 Apr 2010 10:32:45 +0200
1290
23
1291
1
psycopg2 (2.0.13-2ubuntu2) lucid; urgency=low
24
psycopg2 (2.0.13-2ubuntu2) lucid; urgency=low
1292
2
25
1293
3
  * Drop the zope2 package as we have no zope2 in lucid.
26
  * Drop the zope2 package as we have no zope2 in lucid.
1294
@@ -388,13 +411,6 @@
1295
388
411
1296
389
 -- Federico Di Gregorio <fog@debian.org>  Fri,  1 Aug 2003 11:50:57 +0200
412
 -- Federico Di Gregorio <fog@debian.org>  Fri,  1 Aug 2003 11:50:57 +0200
1297
390
413
1298
391
psycopg (1.1.5.1-1.1) unstable; urgency=low
1299
392
1300
393
  * NMU
1301
394
  * Update for python2.3 as the default python version (closes: #205746).
1302
395
1303
396
 -- Matthias Klose <doko@debian.org>  Fri, 22 Aug 2003 00:02:25 +0200
1304
397
1305
398
psycopg (1.1.7-1) unstable; urgency=low
414
psycopg (1.1.7-1) unstable; urgency=low
1306
399
415
1307
400
  * New upstream release.
416
  * New upstream release.
1308
@@ -408,6 +424,13 @@
1309
408
  
424
  
1310
409
 -- Federico Di Gregorio <fog@initd.org>  Sun, 13 Jul 2003 23:36:04 +0200
425
 -- Federico Di Gregorio <fog@initd.org>  Sun, 13 Jul 2003 23:36:04 +0200
1311
410
426
1312
427
psycopg (1.1.5.1-1.1) unstable; urgency=low
1313
428
1314
429
  * NMU
1315
430
  * Update for python2.3 as the default python version (closes: #205746).
1316
431
1317
432
 -- Matthias Klose <doko@debian.org>  Fri, 22 Aug 2003 00:02:25 +0200
1318
433
1319
411
psycopg (1.1.5.1-1) unstable; urgency=low
434
psycopg (1.1.5.1-1) unstable; urgency=low
1320
412
435
1321
413
  * New upstream release.
436
  * New upstream release.
1322
414
437
1323
=== modified file 'debian/control'
1324
--- debian/control	2010-04-16 10:05:03 +0000
1325
+++ debian/control	2010-07-28 20:35:51 +0000
1326
@@ -4,7 +4,7 @@
1327
4
Build-Depends: debhelper (>= 5.0.37.2), python-all-dev, python-all-dbg, python-central (>= 0.5.0), python (>= 2.3.5-7), python-egenix-mx-base-dev, autoconf, libpq-dev
4
Build-Depends: debhelper (>= 5.0.37.2), python-all-dev, python-all-dbg, python-central (>= 0.5.0), python (>= 2.3.5-7), python-egenix-mx-base-dev, autoconf, libpq-dev
1328
5
Maintainer: Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>
5
Maintainer: Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>
1329
6
XSBC-Original-Maintainer: Fabio Tranchitella <kobold@debian.org>
6
XSBC-Original-Maintainer: Fabio Tranchitella <kobold@debian.org>
1331
7
Standards-Version: 3.8.3
7
Standards-Version: 3.9.0
1332
8
XS-Python-Version: all
8
XS-Python-Version: all
1333
9
Vcs-Svn: svn://svn.debian.org/python-modules/packages/psycopg2/trunk/
9
Vcs-Svn: svn://svn.debian.org/python-modules/packages/psycopg2/trunk/
1334
10
Vcs-Browser: http://svn.debian.org/viewsvn/python-modules/packages/psycopg2/trunk/
10
Vcs-Browser: http://svn.debian.org/viewsvn/python-modules/packages/psycopg2/trunk/
1335
@@ -13,7 +13,7 @@
1336
13
Package: python-psycopg2
13
Package: python-psycopg2
1337
14
Architecture: any
14
Architecture: any
1338
15
Section: python
15
Section: python
1340
16
Depends: ${python:Depends}, ${shlibs:Depends}, python-egenix-mxdatetime
16
Depends: python-egenix-mxdatetime, ${python:Depends}, ${shlibs:Depends}, ${misc:Depends}
1341
17
Provides: ${python:Provides}
17
Provides: ${python:Provides}
1342
18
XB-Python-Version: ${python:Versions}
18
XB-Python-Version: ${python:Versions}
1343
19
Description: Python module for PostgreSQL
19
Description: Python module for PostgreSQL
1344
@@ -37,7 +37,7 @@
1345
37
Priority: extra
37
Priority: extra
1346
38
Architecture: any
38
Architecture: any
1347
39
Section: debug
39
Section: debug
1349
40
Depends: python-psycopg2 (= ${binary:Version}), python-dbg, ${shlibs:Depends}
40
Depends: python-psycopg2 (= ${binary:Version}), python-dbg, ${shlibs:Depends}, ${misc:Depends}
1350
41
XB-Python-Version: ${python:Versions}
41
XB-Python-Version: ${python:Versions}
1351
42
Description: Python module for PostgreSQL (debug extension)
42
Description: Python module for PostgreSQL (debug extension)
1352
43
 psycopg is a PostgreSQL database adapter for the Python programming language
43
 psycopg is a PostgreSQL database adapter for the Python programming language
1353
@@ -48,15 +48,6 @@
1354
48
 .
48
 .
1355
49
 This package contains the extensions built for the Python debug interpreter.
49
 This package contains the extensions built for the Python debug interpreter.
1356
50
50
1357
51
#Package: zope-psycopgda2
1358
52
#Architecture: all
1359
53
#Section: zope
1360
54
#Depends: ${zope:Depends}, python-psycopg2 (>= ${source:Version})
1361
55
#XB-Python-Version: ${python:Versions}
1362
56
#Description: Zope database adapter based on python-psycopg2
1363
57
# The package contains the PostgreSQL database adapter for Zope 2.7, 2.8 and
1364
58
# 2.9 based on the psycopg2 Python module.
1365
59
1366
60
Package: python-psycopg2-testsuite
51
Package: python-psycopg2-testsuite
1367
61
Architecture: any
52
Architecture: any
1368
62
Section: python
53
Section: python
1369
63
54
1370
=== modified file 'debian/rules'
1371
--- debian/rules	2010-04-16 10:05:03 +0000
1372
+++ debian/rules	2010-07-28 20:35:51 +0000
1373
@@ -59,8 +59,6 @@
1374
59
	find debian/python-*-dbg -depth -empty -exec rmdir {} \;
59
	find debian/python-*-dbg -depth -empty -exec rmdir {} \;
1375
60
60
1376
61
install-indep: build
61
install-indep: build
1377
62
	# Zope package
1378
63
	#dh_installzope -p zope-psycopgda2 ZPsycopgDA
1379
64
62
1380
65
# Build architecture-independent files here.
63
# Build architecture-independent files here.
1381
66
binary-indep: build install-indep
64
binary-indep: build install-indep
1382
67
65
1383
=== added directory 'debian/source'
1384
=== added file 'debian/source/format'
1385
--- debian/source/format	1970-01-01 00:00:00 +0000
1386
+++ debian/source/format	2010-07-28 20:35:51 +0000
1387
@@ -0,0 +1,1 @@
1388
1
1.0
1389
0
2
1390
=== added file 'doc/COPYING'
1391
--- doc/COPYING	1970-01-01 00:00:00 +0000
1392
+++ doc/COPYING	2010-07-28 20:35:51 +0000
1393
@@ -0,0 +1,676 @@
1394
1
1395
2
		    GNU GENERAL PUBLIC LICENSE
1396
3
		       Version 3, 29 June 2007
1397
4
1398
5
 Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
1399
6
 Everyone is permitted to copy and distribute verbatim copies
1400
7
 of this license document, but changing it is not allowed.
1401
8
1402
9
			    Preamble
1403
10
1404
11
  The GNU General Public License is a free, copyleft license for
1405
12
software and other kinds of works.
1406
13
1407
14
  The licenses for most software and other practical works are designed
1408
15
to take away your freedom to share and change the works.  By contrast,
1409
16
the GNU General Public License is intended to guarantee your freedom to
1410
17
share and change all versions of a program--to make sure it remains free
1411
18
software for all its users.  We, the Free Software Foundation, use the
1412
19
GNU General Public License for most of our software; it applies also to
1413
20
any other work released this way by its authors.  You can apply it to
1414
21
your programs, too.
1415
22
1416
23
  When we speak of free software, we are referring to freedom, not
1417
24
price.  Our General Public Licenses are designed to make sure that you
1418
25
have the freedom to distribute copies of free software (and charge for
1419
26
them if you wish), that you receive source code or can get it if you
1420
27
want it, that you can change the software or use pieces of it in new
1421
28
free programs, and that you know you can do these things.
1422
29
1423
30
  To protect your rights, we need to prevent others from denying you
1424
31
these rights or asking you to surrender the rights.  Therefore, you have
1425
32
certain responsibilities if you distribute copies of the software, or if
1426
33
you modify it: responsibilities to respect the freedom of others.
1427
34
1428
35
  For example, if you distribute copies of such a program, whether
1429
36
gratis or for a fee, you must pass on to the recipients the same
1430
37
freedoms that you received.  You must make sure that they, too, receive
1431
38
or can get the source code.  And you must show them these terms so they
1432
39
know their rights.
1433
40
1434
41
  Developers that use the GNU GPL protect your rights with two steps:
1435
42
(1) assert copyright on the software, and (2) offer you this License
1436
43
giving you legal permission to copy, distribute and/or modify it.
1437
44
1438
45
  For the developers' and authors' protection, the GPL clearly explains
1439
46
that there is no warranty for this free software.  For both users' and
1440
47
authors' sake, the GPL requires that modified versions be marked as
1441
48
changed, so that their problems will not be attributed erroneously to
1442
49
authors of previous versions.
1443
50
1444
51
  Some devices are designed to deny users access to install or run
1445
52
modified versions of the software inside them, although the manufacturer
1446
53
can do so.  This is fundamentally incompatible with the aim of
1447
54
protecting users' freedom to change the software.  The systematic
1448
55
pattern of such abuse occurs in the area of products for individuals to
1449
56
use, which is precisely where it is most unacceptable.  Therefore, we
1450
57
have designed this version of the GPL to prohibit the practice for those
1451
58
products.  If such problems arise substantially in other domains, we
1452
59
stand ready to extend this provision to those domains in future versions
1453
60
of the GPL, as needed to protect the freedom of users.
1454
61
1455
62
  Finally, every program is threatened constantly by software patents.
1456
63
States should not allow patents to restrict development and use of
1457
64
software on general-purpose computers, but in those that do, we wish to
1458
65
avoid the special danger that patents applied to a free program could
1459
66
make it effectively proprietary.  To prevent this, the GPL assures that
1460
67
patents cannot be used to render the program non-free.
1461
68
1462
69
  The precise terms and conditions for copying, distribution and
1463
70
modification follow.
1464
71
1465
72
		       TERMS AND CONDITIONS
1466
73
1467
74
  0. Definitions.
1468
75
1469
76
  "This License" refers to version 3 of the GNU General Public License.
1470
77
1471
78
  "Copyright" also means copyright-like laws that apply to other kinds of
1472
79
works, such as semiconductor masks.
1473
80
 
1474
81
  "The Program" refers to any copyrightable work licensed under this
1475
82
License.  Each licensee is addressed as "you".  "Licensees" and
1476
83
"recipients" may be individuals or organizations.
1477
84
1478
85
  To "modify" a work means to copy from or adapt all or part of the work
1479
86
in a fashion requiring copyright permission, other than the making of an
1480
87
exact copy.  The resulting work is called a "modified version" of the
1481
88
earlier work or a work "based on" the earlier work.
1482
89
1483
90
  A "covered work" means either the unmodified Program or a work based
1484
91
on the Program.
1485
92
1486
93
  To "propagate" a work means to do anything with it that, without
1487
94
permission, would make you directly or secondarily liable for
1488
95
infringement under applicable copyright law, except executing it on a
1489
96
computer or modifying a private copy.  Propagation includes copying,
1490
97
distribution (with or without modification), making available to the
1491
98
public, and in some countries other activities as well.
1492
99
1493
100
  To "convey" a work means any kind of propagation that enables other
1494
101
parties to make or receive copies.  Mere interaction with a user through
1495
102
a computer network, with no transfer of a copy, is not conveying.
1496
103
1497
104
  An interactive user interface displays "Appropriate Legal Notices"
1498
105
to the extent that it includes a convenient and prominently visible
1499
106
feature that (1) displays an appropriate copyright notice, and (2)
1500
107
tells the user that there is no warranty for the work (except to the
1501
108
extent that warranties are provided), that licensees may convey the
1502
109
work under this License, and how to view a copy of this License.  If
1503
110
the interface presents a list of user commands or options, such as a
1504
111
menu, a prominent item in the list meets this criterion.
1505
112
1506
113
  1. Source Code.
1507
114
1508
115
  The "source code" for a work means the preferred form of the work
1509
116
for making modifications to it.  "Object code" means any non-source
1510
117
form of a work.
1511
118
1512
119
  A "Standard Interface" means an interface that either is an official
1513
120
standard defined by a recognized standards body, or, in the case of
1514
121
interfaces specified for a particular programming language, one that
1515
122
is widely used among developers working in that language.
1516
123
1517
124
  The "System Libraries" of an executable work include anything, other
1518
125
than the work as a whole, that (a) is included in the normal form of
1519
126
packaging a Major Component, but which is not part of that Major
1520
127
Component, and (b) serves only to enable use of the work with that
1521
128
Major Component, or to implement a Standard Interface for which an
1522
129
implementation is available to the public in source code form.  A
1523
130
"Major Component", in this context, means a major essential component
1524
131
(kernel, window system, and so on) of the specific operating system
1525
132
(if any) on which the executable work runs, or a compiler used to
1526
133
produce the work, or an object code interpreter used to run it.
1527
134
1528
135
  The "Corresponding Source" for a work in object code form means all
1529
136
the source code needed to generate, install, and (for an executable
1530
137
work) run the object code and to modify the work, including scripts to
1531
138
control those activities.  However, it does not include the work's
1532
139
System Libraries, or general-purpose tools or generally available free
1533
140
programs which are used unmodified in performing those activities but
1534
141
which are not part of the work.  For example, Corresponding Source
1535
142
includes interface definition files associated with source files for
1536
143
the work, and the source code for shared libraries and dynamically
1537
144
linked subprograms that the work is specifically designed to require,
1538
145
such as by intimate data communication or control flow between those
1539
146
subprograms and other parts of the work.
1540
147
1541
148
  The Corresponding Source need not include anything that users
1542
149
can regenerate automatically from other parts of the Corresponding
1543
150
Source.
1544
151
1545
152
  The Corresponding Source for a work in source code form is that
1546
153
same work.
1547
154
1548
155
  2. Basic Permissions.
1549
156
1550
157
  All rights granted under this License are granted for the term of
1551
158
copyright on the Program, and are irrevocable provided the stated
1552
159
conditions are met.  This License explicitly affirms your unlimited
1553
160
permission to run the unmodified Program.  The output from running a
1554
161
covered work is covered by this License only if the output, given its
1555
162
content, constitutes a covered work.  This License acknowledges your
1556
163
rights of fair use or other equivalent, as provided by copyright law.
1557
164
1558
165
  You may make, run and propagate covered works that you do not
1559
166
convey, without conditions so long as your license otherwise remains
1560
167
in force.  You may convey covered works to others for the sole purpose
1561
168
of having them make modifications exclusively for you, or provide you
1562
169
with facilities for running those works, provided that you comply with
1563
170
the terms of this License in conveying all material for which you do
1564
171
not control copyright.  Those thus making or running the covered works
1565
172
for you must do so exclusively on your behalf, under your direction
1566
173
and control, on terms that prohibit them from making any copies of
1567
174
your copyrighted material outside their relationship with you.
1568
175
1569
176
  Conveying under any other circumstances is permitted solely under
1570
177
the conditions stated below.  Sublicensing is not allowed; section 10
1571
178
makes it unnecessary.
1572
179
1573
180
  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
1574
181
1575
182
  No covered work shall be deemed part of an effective technological
1576
183
measure under any applicable law fulfilling obligations under article
1577
184
11 of the WIPO copyright treaty adopted on 20 December 1996, or
1578
185
similar laws prohibiting or restricting circumvention of such
1579
186
measures.
1580
187
1581
188
  When you convey a covered work, you waive any legal power to forbid
1582
189
circumvention of technological measures to the extent such circumvention
1583
190
is effected by exercising rights under this License with respect to
1584
191
the covered work, and you disclaim any intention to limit operation or
1585
192
modification of the work as a means of enforcing, against the work's
1586
193
users, your or third parties' legal rights to forbid circumvention of
1587
194
technological measures.
1588
195
1589
196
  4. Conveying Verbatim Copies.
1590
197
1591
198
  You may convey verbatim copies of the Program's source code as you
1592
199
receive it, in any medium, provided that you conspicuously and
1593
200
appropriately publish on each copy an appropriate copyright notice;
1594
201
keep intact all notices stating that this License and any
1595
202
non-permissive terms added in accord with section 7 apply to the code;
1596
203
keep intact all notices of the absence of any warranty; and give all
1597
204
recipients a copy of this License along with the Program.
1598
205
1599
206
  You may charge any price or no price for each copy that you convey,
1600
207
and you may offer support or warranty protection for a fee.
1601
208
1602
209
  5. Conveying Modified Source Versions.
1603
210
1604
211
  You may convey a work based on the Program, or the modifications to
1605
212
produce it from the Program, in the form of source code under the
1606
213
terms of section 4, provided that you also meet all of these conditions:
1607
214
1608
215
    a) The work must carry prominent notices stating that you modified
1609
216
    it, and giving a relevant date.
1610
217
1611
218
    b) The work must carry prominent notices stating that it is
1612
219
    released under this License and any conditions added under section
1613
220
    7.  This requirement modifies the requirement in section 4 to
1614
221
    "keep intact all notices".
1615
222
1616
223
    c) You must license the entire work, as a whole, under this
1617
224
    License to anyone who comes into possession of a copy.  This
1618
225
    License will therefore apply, along with any applicable section 7
1619
226
    additional terms, to the whole of the work, and all its parts,
1620
227
    regardless of how they are packaged.  This License gives no
1621
228
    permission to license the work in any other way, but it does not
1622
229
    invalidate such permission if you have separately received it.
1623
230
1624
231
    d) If the work has interactive user interfaces, each must display
1625
232
    Appropriate Legal Notices; however, if the Program has interactive
1626
233
    interfaces that do not display Appropriate Legal Notices, your
1627
234
    work need not make them do so.
1628
235
1629
236
  A compilation of a covered work with other separate and independent
1630
237
works, which are not by their nature extensions of the covered work,
1631
238
and which are not combined with it such as to form a larger program,
1632
239
in or on a volume of a storage or distribution medium, is called an
1633
240
"aggregate" if the compilation and its resulting copyright are not
1634
241
used to limit the access or legal rights of the compilation's users
1635
242
beyond what the individual works permit.  Inclusion of a covered work
1636
243
in an aggregate does not cause this License to apply to the other
1637
244
parts of the aggregate.
1638
245
1639
246
  6. Conveying Non-Source Forms.
1640
247
1641
248
  You may convey a covered work in object code form under the terms
1642
249
of sections 4 and 5, provided that you also convey the
1643
250
machine-readable Corresponding Source under the terms of this License,
1644
251
in one of these ways:
1645
252
1646
253
    a) Convey the object code in, or embodied in, a physical product
1647
254
    (including a physical distribution medium), accompanied by the
1648
255
    Corresponding Source fixed on a durable physical medium
1649
256
    customarily used for software interchange.
1650
257
1651
258
    b) Convey the object code in, or embodied in, a physical product
1652
259
    (including a physical distribution medium), accompanied by a
1653
260
    written offer, valid for at least three years and valid for as
1654
261
    long as you offer spare parts or customer support for that product
1655
262
    model, to give anyone who possesses the object code either (1) a
1656
263
    copy of the Corresponding Source for all the software in the
1657
264
    product that is covered by this License, on a durable physical
1658
265
    medium customarily used for software interchange, for a price no
1659
266
    more than your reasonable cost of physically performing this
1660
267
    conveying of source, or (2) access to copy the
1661
268
    Corresponding Source from a network server at no charge.
1662
269
1663
270
    c) Convey individual copies of the object code with a copy of the
1664
271
    written offer to provide the Corresponding Source.  This
1665
272
    alternative is allowed only occasionally and noncommercially, and
1666
273
    only if you received the object code with such an offer, in accord
1667
274
    with subsection 6b.
1668
275
1669
276
    d) Convey the object code by offering access from a designated
1670
277
    place (gratis or for a charge), and offer equivalent access to the
1671
278
    Corresponding Source in the same way through the same place at no
1672
279
    further charge.  You need not require recipients to copy the
1673
280
    Corresponding Source along with the object code.  If the place to
1674
281
    copy the object code is a network server, the Corresponding Source
1675
282
    may be on a different server (operated by you or a third party)
1676
283
    that supports equivalent copying facilities, provided you maintain
1677
284
    clear directions next to the object code saying where to find the
1678
285
    Corresponding Source.  Regardless of what server hosts the
1679
286
    Corresponding Source, you remain obligated to ensure that it is
1680
287
    available for as long as needed to satisfy these requirements.
1681
288
1682
289
    e) Convey the object code using peer-to-peer transmission, provided
1683
290
    you inform other peers where the object code and Corresponding
1684
291
    Source of the work are being offered to the general public at no
1685
292
    charge under subsection 6d.
1686
293
1687
294
  A separable portion of the object code, whose source code is excluded
1688
295
from the Corresponding Source as a System Library, need not be
1689
296
included in conveying the object code work.
1690
297
1691
298
  A "User Product" is either (1) a "consumer product", which means any
1692
299
tangible personal property which is normally used for personal, family,
1693
300
or household purposes, or (2) anything designed or sold for incorporation
1694
301
into a dwelling.  In determining whether a product is a consumer product,
1695
302
doubtful cases shall be resolved in favor of coverage.  For a particular
1696
303
product received by a particular user, "normally used" refers to a
1697
304
typical or common use of that class of product, regardless of the status
1698
305
of the particular user or of the way in which the particular user
1699
306
actually uses, or expects or is expected to use, the product.  A product
1700
307
is a consumer product regardless of whether the product has substantial
1701
308
commercial, industrial or non-consumer uses, unless such uses represent
1702
309
the only significant mode of use of the product.
1703
310
1704
311
  "Installation Information" for a User Product means any methods,
1705
312
procedures, authorization keys, or other information required to install
1706
313
and execute modified versions of a covered work in that User Product from
1707
314
a modified version of its Corresponding Source.  The information must
1708
315
suffice to ensure that the continued functioning of the modified object
1709
316
code is in no case prevented or interfered with solely because
1710
317
modification has been made.
1711
318
1712
319
  If you convey an object code work under this section in, or with, or
1713
320
specifically for use in, a User Product, and the conveying occurs as
1714
321
part of a transaction in which the right of possession and use of the
1715
322
User Product is transferred to the recipient in perpetuity or for a
1716
323
fixed term (regardless of how the transaction is characterized), the
1717
324
Corresponding Source conveyed under this section must be accompanied
1718
325
by the Installation Information.  But this requirement does not apply
1719
326
if neither you nor any third party retains the ability to install
1720
327
modified object code on the User Product (for example, the work has
1721
328
been installed in ROM).
1722
329
1723
330
  The requirement to provide Installation Information does not include a
1724
331
requirement to continue to provide support service, warranty, or updates
1725
332
for a work that has been modified or installed by the recipient, or for
1726
333
the User Product in which it has been modified or installed.  Access to a
1727
334
network may be denied when the modification itself materially and
1728
335
adversely affects the operation of the network or violates the rules and
1729
336
protocols for communication across the network.
1730
337
1731
338
  Corresponding Source conveyed, and Installation Information provided,
1732
339
in accord with this section must be in a format that is publicly
1733
340
documented (and with an implementation available to the public in
1734
341
source code form), and must require no special password or key for
1735
342
unpacking, reading or copying.
1736
343
1737
344
  7. Additional Terms.
1738
345
1739
346
  "Additional permissions" are terms that supplement the terms of this
1740
347
License by making exceptions from one or more of its conditions.
1741
348
Additional permissions that are applicable to the entire Program shall
1742
349
be treated as though they were included in this License, to the extent
1743
350
that they are valid under applicable law.  If additional permissions
1744
351
apply only to part of the Program, that part may be used separately
1745
352
under those permissions, but the entire Program remains governed by
1746
353
this License without regard to the additional permissions.
1747
354
1748
355
  When you convey a copy of a covered work, you may at your option
1749
356
remove any additional permissions from that copy, or from any part of
1750
357
it.  (Additional permissions may be written to require their own
1751
358
removal in certain cases when you modify the work.)  You may place
1752
359
additional permissions on material, added by you to a covered work,
1753
360
for which you have or can give appropriate copyright permission.
1754
361
1755
362
  Notwithstanding any other provision of this License, for material you
1756
363
add to a covered work, you may (if authorized by the copyright holders of
1757
364
that material) supplement the terms of this License with terms:
1758
365
1759
366
    a) Disclaiming warranty or limiting liability differently from the
1760
367
    terms of sections 15 and 16 of this License; or
1761
368
1762
369
    b) Requiring preservation of specified reasonable legal notices or
1763
370
    author attributions in that material or in the Appropriate Legal
1764
371
    Notices displayed by works containing it; or
1765
372
1766
373
    c) Prohibiting misrepresentation of the origin of that material, or
1767
374
    requiring that modified versions of such material be marked in
1768
375
    reasonable ways as different from the original version; or
1769
376
1770
377
    d) Limiting the use for publicity purposes of names of licensors or
1771
378
    authors of the material; or
1772
379
1773
380
    e) Declining to grant rights under trademark law for use of some
1774
381
    trade names, trademarks, or service marks; or
1775
382
1776
383
    f) Requiring indemnification of licensors and authors of that
1777
384
    material by anyone who conveys the material (or modified versions of
1778
385
    it) with contractual assumptions of liability to the recipient, for
1779
386
    any liability that these contractual assumptions directly impose on
1780
387
    those licensors and authors.
1781
388
1782
389
  All other non-permissive additional terms are considered "further
1783
390
restrictions" within the meaning of section 10.  If the Program as you
1784
391
received it, or any part of it, contains a notice stating that it is
1785
392
governed by this License along with a term that is a further
1786
393
restriction, you may remove that term.  If a license document contains
1787
394
a further restriction but permits relicensing or conveying under this
1788
395
License, you may add to a covered work material governed by the terms
1789
396
of that license document, provided that the further restriction does
1790
397
not survive such relicensing or conveying.
1791
398
1792
399
  If you add terms to a covered work in accord with this section, you
1793
400
must place, in the relevant source files, a statement of the
1794
401
additional terms that apply to those files, or a notice indicating
1795
402
where to find the applicable terms.
1796
403
1797
404
  Additional terms, permissive or non-permissive, may be stated in the
1798
405
form of a separately written license, or stated as exceptions;
1799
406
the above requirements apply either way.
1800
407
1801
408
  8. Termination.
1802
409
1803
410
  You may not propagate or modify a covered work except as expressly
1804
411
provided under this License.  Any attempt otherwise to propagate or
1805
412
modify it is void, and will automatically terminate your rights under
1806
413
this License (including any patent licenses granted under the third
1807
414
paragraph of section 11).
1808
415
1809
416
  However, if you cease all violation of this License, then your
1810
417
license from a particular copyright holder is reinstated (a)
1811
418
provisionally, unless and until the copyright holder explicitly and
1812
419
finally terminates your license, and (b) permanently, if the copyright
1813
420
holder fails to notify you of the violation by some reasonable means
1814
421
prior to 60 days after the cessation.
1815
422
1816
423
  Moreover, your license from a particular copyright holder is
1817
424
reinstated permanently if the copyright holder notifies you of the
1818
425
violation by some reasonable means, this is the first time you have
1819
426
received notice of violation of this License (for any work) from that
1820
427
copyright holder, and you cure the violation prior to 30 days after
1821
428
your receipt of the notice.
1822
429
1823
430
  Termination of your rights under this section does not terminate the
1824
431
licenses of parties who have received copies or rights from you under
1825
432
this License.  If your rights have been terminated and not permanently
1826
433
reinstated, you do not qualify to receive new licenses for the same
1827
434
material under section 10.
1828
435
1829
436
  9. Acceptance Not Required for Having Copies.
1830
437
1831
438
  You are not required to accept this License in order to receive or
1832
439
run a copy of the Program.  Ancillary propagation of a covered work
1833
440
occurring solely as a consequence of using peer-to-peer transmission
1834
441
to receive a copy likewise does not require acceptance.  However,
1835
442
nothing other than this License grants you permission to propagate or
1836
443
modify any covered work.  These actions infringe copyright if you do
1837
444
not accept this License.  Therefore, by modifying or propagating a
1838
445
covered work, you indicate your acceptance of this License to do so.
1839
446
1840
447
  10. Automatic Licensing of Downstream Recipients.
1841
448
1842
449
  Each time you convey a covered work, the recipient automatically
1843
450
receives a license from the original licensors, to run, modify and
1844
451
propagate that work, subject to this License.  You are not responsible
1845
452
for enforcing compliance by third parties with this License.
1846
453
1847
454
  An "entity transaction" is a transaction transferring control of an
1848
455
organization, or substantially all assets of one, or subdividing an
1849
456
organization, or merging organizations.  If propagation of a covered
1850
457
work results from an entity transaction, each party to that
1851
458
transaction who receives a copy of the work also receives whatever
1852
459
licenses to the work the party's predecessor in interest had or could
1853
460
give under the previous paragraph, plus a right to possession of the
1854
461
Corresponding Source of the work from the predecessor in interest, if
1855
462
the predecessor has it or can get it with reasonable efforts.
1856
463
1857
464
  You may not impose any further restrictions on the exercise of the
1858
465
rights granted or affirmed under this License.  For example, you may
1859
466
not impose a license fee, royalty, or other charge for exercise of
1860
467
rights granted under this License, and you may not initiate litigation
1861
468
(including a cross-claim or counterclaim in a lawsuit) alleging that
1862
469
any patent claim is infringed by making, using, selling, offering for
1863
470
sale, or importing the Program or any portion of it.
1864
471
1865
472
  11. Patents.
1866
473
1867
474
  A "contributor" is a copyright holder who authorizes use under this
1868
475
License of the Program or a work on which the Program is based.  The
1869
476
work thus licensed is called the contributor's "contributor version".
1870
477
1871
478
  A contributor's "essential patent claims" are all patent claims
1872
479
owned or controlled by the contributor, whether already acquired or
1873
480
hereafter acquired, that would be infringed by some manner, permitted
1874
481
by this License, of making, using, or selling its contributor version,
1875
482
but do not include claims that would be infringed only as a
1876
483
consequence of further modification of the contributor version.  For
1877
484
purposes of this definition, "control" includes the right to grant
1878
485
patent sublicenses in a manner consistent with the requirements of
1879
486
this License.
1880
487
1881
488
  Each contributor grants you a non-exclusive, worldwide, royalty-free
1882
489
patent license under the contributor's essential patent claims, to
1883
490
make, use, sell, offer for sale, import and otherwise run, modify and
1884
491
propagate the contents of its contributor version.
1885
492
1886
493
  In the following three paragraphs, a "patent license" is any express
1887
494
agreement or commitment, however denominated, not to enforce a patent
1888
495
(such as an express permission to practice a patent or covenant not to
1889
496
sue for patent infringement).  To "grant" such a patent license to a
1890
497
party means to make such an agreement or commitment not to enforce a
1891
498
patent against the party.
1892
499
1893
500
  If you convey a covered work, knowingly relying on a patent license,
1894
501
and the Corresponding Source of the work is not available for anyone
1895
502
to copy, free of charge and under the terms of this License, through a
1896
503
publicly available network server or other readily accessible means,
1897
504
then you must either (1) cause the Corresponding Source to be so
1898
505
available, or (2) arrange to deprive yourself of the benefit of the
1899
506
patent license for this particular work, or (3) arrange, in a manner
1900
507
consistent with the requirements of this License, to extend the patent
1901
508
license to downstream recipients.  "Knowingly relying" means you have
1902
509
actual knowledge that, but for the patent license, your conveying the
1903
510
covered work in a country, or your recipient's use of the covered work
1904
511
in a country, would infringe one or more identifiable patents in that
1905
512
country that you have reason to believe are valid.
1906
513
  
1907
514
  If, pursuant to or in connection with a single transaction or
1908
515
arrangement, you convey, or propagate by procuring conveyance of, a
1909
516
covered work, and grant a patent license to some of the parties
1910
517
receiving the covered work authorizing them to use, propagate, modify
1911
518
or convey a specific copy of the covered work, then the patent license
1912
519
you grant is automatically extended to all recipients of the covered
1913
520
work and works based on it.
1914
521
1915
522
  A patent license is "discriminatory" if it does not include within
1916
523
the scope of its coverage, prohibits the exercise of, or is
1917
524
conditioned on the non-exercise of one or more of the rights that are
1918
525
specifically granted under this License.  You may not convey a covered
1919
526
work if you are a party to an arrangement with a third party that is
1920
527
in the business of distributing software, under which you make payment
1921
528
to the third party based on the extent of your activity of conveying
1922
529
the work, and under which the third party grants, to any of the
1923
530
parties who would receive the covered work from you, a discriminatory
1924
531
patent license (a) in connection with copies of the covered work
1925
532
conveyed by you (or copies made from those copies), or (b) primarily
1926
533
for and in connection with specific products or compilations that
1927
534
contain the covered work, unless you entered into that arrangement,
1928
535
or that patent license was granted, prior to 28 March 2007.
1929
536
1930
537
  Nothing in this License shall be construed as excluding or limiting
1931
538
any implied license or other defenses to infringement that may
1932
539
otherwise be available to you under applicable patent law.
1933
540
1934
541
  12. No Surrender of Others' Freedom.
1935
542
1936
543
  If conditions are imposed on you (whether by court order, agreement or
1937
544
otherwise) that contradict the conditions of this License, they do not
1938
545
excuse you from the conditions of this License.  If you cannot convey a
1939
546
covered work so as to satisfy simultaneously your obligations under this
1940
547
License and any other pertinent obligations, then as a consequence you may
1941
548
not convey it at all.  For example, if you agree to terms that obligate you
1942
549
to collect a royalty for further conveying from those to whom you convey
1943
550
the Program, the only way you could satisfy both those terms and this
1944
551
License would be to refrain entirely from conveying the Program.
1945
552
1946
553
  13. Use with the GNU Affero General Public License.
1947
554
1948
555
  Notwithstanding any other provision of this License, you have
1949
556
permission to link or combine any covered work with a work licensed
1950
557
under version 3 of the GNU Affero General Public License into a single
1951
558
combined work, and to convey the resulting work.  The terms of this
1952
559
License will continue to apply to the part which is the covered work,
1953
560
but the special requirements of the GNU Affero General Public License,
1954
561
section 13, concerning interaction through a network will apply to the
1955
562
combination as such.
1956
563
1957
564
  14. Revised Versions of this License.
1958
565
1959
566
  The Free Software Foundation may publish revised and/or new versions of
1960
567
the GNU General Public License from time to time.  Such new versions will
1961
568
be similar in spirit to the present version, but may differ in detail to
1962
569
address new problems or concerns.
1963
570
1964
571
  Each version is given a distinguishing version number.  If the
1965
572
Program specifies that a certain numbered version of the GNU General
1966
573
Public License "or any later version" applies to it, you have the
1967
574
option of following the terms and conditions either of that numbered
1968
575
version or of any later version published by the Free Software
1969
576
Foundation.  If the Program does not specify a version number of the
1970
577
GNU General Public License, you may choose any version ever published
1971
578
by the Free Software Foundation.
1972
579
1973
580
  If the Program specifies that a proxy can decide which future
1974
581
versions of the GNU General Public License can be used, that proxy's
1975
582
public statement of acceptance of a version permanently authorizes you
1976
583
to choose that version for the Program.
1977
584
1978
585
  Later license versions may give you additional or different
1979
586
permissions.  However, no additional obligations are imposed on any
1980
587
author or copyright holder as a result of your choosing to follow a
1981
588
later version.
1982
589
1983
590
  15. Disclaimer of Warranty.
1984
591
1985
592
  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
1986
593
APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
1987
594
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
1988
595
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
1989
596
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
1990
597
PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
1991
598
IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
1992
599
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
1993
600
1994
601
  16. Limitation of Liability.
1995
602
1996
603
  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
1997
604
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
1998
605
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
1999
606
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
2000
607
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
2001
608
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
2002
609
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
2003
610
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
2004
611
SUCH DAMAGES.
2005
612
2006
613
  17. Interpretation of Sections 15 and 16.
2007
614
2008
615
  If the disclaimer of warranty and limitation of liability provided
2009
616
above cannot be given local legal effect according to their terms,
2010
617
reviewing courts shall apply local law that most closely approximates
2011
618
an absolute waiver of all civil liability in connection with the
2012
619
Program, unless a warranty or assumption of liability accompanies a
2013
620
copy of the Program in return for a fee.
2014
621
2015
622
		     END OF TERMS AND CONDITIONS
2016
623
2017
624
	    How to Apply These Terms to Your New Programs
2018
625
2019
626
  If you develop a new program, and you want it to be of the greatest
2020
627
possible use to the public, the best way to achieve this is to make it
2021
628
free software which everyone can redistribute and change under these terms.
2022
629
2023
630
  To do so, attach the following notices to the program.  It is safest
2024
631
to attach them to the start of each source file to most effectively
2025
632
state the exclusion of warranty; and each file should have at least
2026
633
the "copyright" line and a pointer to where the full notice is found.
2027
634
2028
635
    <one line to give the program's name and a brief idea of what it does.>
2029
636
    Copyright (C) <year>  <name of author>
2030
637
2031
638
    This program is free software: you can redistribute it and/or modify
2032
639
    it under the terms of the GNU General Public License as published by
2033
640
    the Free Software Foundation, either version 3 of the License, or
2034
641
    (at your option) any later version.
2035
642
2036
643
    This program is distributed in the hope that it will be useful,
2037
644
    but WITHOUT ANY WARRANTY; without even the implied warranty of
2038
645
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
2039
646
    GNU General Public License for more details.
2040
647
2041
648
    You should have received a copy of the GNU General Public License
2042
649
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
2043
650
2044
651
Also add information on how to contact you by electronic and paper mail.
2045
652
2046
653
  If the program does terminal interaction, make it output a short
2047
654
notice like this when it starts in an interactive mode:
2048
655
2049
656
    <program>  Copyright (C) <year>  <name of author>
2050
657
    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
2051
658
    This is free software, and you are welcome to redistribute it
2052
659
    under certain conditions; type `show c' for details.
2053
660
2054
661
The hypothetical commands `show w' and `show c' should show the appropriate
2055
662
parts of the General Public License.  Of course, your program's commands
2056
663
might be different; for a GUI interface, you would use an "about box".
2057
664
2058
665
  You should also get your employer (if you work as a programmer) or school,
2059
666
if any, to sign a "copyright disclaimer" for the program, if necessary.
2060
667
For more information on this, and how to apply and follow the GNU GPL, see
2061
668
<http://www.gnu.org/licenses/>.
2062
669
2063
670
  The GNU General Public License does not permit incorporating your program
2064
671
into proprietary programs.  If your program is a subroutine library, you
2065
672
may consider it more useful to permit linking proprietary applications with
2066
673
the library.  If this is what you want to do, use the GNU Lesser General
2067
674
Public License instead of this License.  But first, please read
2068
675
<http://www.gnu.org/philosophy/why-not-lgpl.html>.
2069
676
2070
0
677
2071
=== added file 'doc/COPYING.LESSER'
2072
--- doc/COPYING.LESSER	1970-01-01 00:00:00 +0000
2073
+++ doc/COPYING.LESSER	2010-07-28 20:35:51 +0000
2074
@@ -0,0 +1,165 @@
2075
1
		   GNU LESSER GENERAL PUBLIC LICENSE
2076
2
                       Version 3, 29 June 2007
2077
3
2078
4
 Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
2079
5
 Everyone is permitted to copy and distribute verbatim copies
2080
6
 of this license document, but changing it is not allowed.
2081
7
2082
8
2083
9
  This version of the GNU Lesser General Public License incorporates
2084
10
the terms and conditions of version 3 of the GNU General Public
2085
11
License, supplemented by the additional permissions listed below.
2086
12
2087
13
  0. Additional Definitions. 
2088
14
2089
15
  As used herein, "this License" refers to version 3 of the GNU Lesser
2090
16
General Public License, and the "GNU GPL" refers to version 3 of the GNU
2091
17
General Public License.
2092
18
2093
19
  "The Library" refers to a covered work governed by this License,
2094
20
other than an Application or a Combined Work as defined below.
2095
21
2096
22
  An "Application" is any work that makes use of an interface provided
2097
23
by the Library, but which is not otherwise based on the Library.
2098
24
Defining a subclass of a class defined by the Library is deemed a mode
2099
25
of using an interface provided by the Library.
2100
26
2101
27
  A "Combined Work" is a work produced by combining or linking an
2102
28
Application with the Library.  The particular version of the Library
2103
29
with which the Combined Work was made is also called the "Linked
2104
30
Version".
2105
31
2106
32
  The "Minimal Corresponding Source" for a Combined Work means the
2107
33
Corresponding Source for the Combined Work, excluding any source code
2108
34
for portions of the Combined Work that, considered in isolation, are
2109
35
based on the Application, and not on the Linked Version.
2110
36
2111
37
  The "Corresponding Application Code" for a Combined Work means the
2112
38
object code and/or source code for the Application, including any data
2113
39
and utility programs needed for reproducing the Combined Work from the
2114
40
Application, but excluding the System Libraries of the Combined Work.
2115
41
2116
42
  1. Exception to Section 3 of the GNU GPL.
2117
43
2118
44
  You may convey a covered work under sections 3 and 4 of this License
2119
45
without being bound by section 3 of the GNU GPL.
2120
46
2121
47
  2. Conveying Modified Versions.
2122
48
2123
49
  If you modify a copy of the Library, and, in your modifications, a
2124
50
facility refers to a function or data to be supplied by an Application
2125
51
that uses the facility (other than as an argument passed when the
2126
52
facility is invoked), then you may convey a copy of the modified
2127
53
version:
2128
54
2129
55
   a) under this License, provided that you make a good faith effort to
2130
56
   ensure that, in the event an Application does not supply the
2131
57
   function or data, the facility still operates, and performs
2132
58
   whatever part of its purpose remains meaningful, or
2133
59
2134
60
   b) under the GNU GPL, with none of the additional permissions of
2135
61
   this License applicable to that copy.
2136
62
2137
63
  3. Object Code Incorporating Material from Library Header Files.
2138
64
2139
65
  The object code form of an Application may incorporate material from
2140
66
a header file that is part of the Library.  You may convey such object
2141
67
code under terms of your choice, provided that, if the incorporated
2142
68
material is not limited to numerical parameters, data structure
2143
69
layouts and accessors, or small macros, inline functions and templates
2144
70
(ten or fewer lines in length), you do both of the following:
2145
71
2146
72
   a) Give prominent notice with each copy of the object code that the
2147
73
   Library is used in it and that the Library and its use are
2148
74
   covered by this License.
2149
75
2150
76
   b) Accompany the object code with a copy of the GNU GPL and this license
2151
77
   document.
2152
78
2153
79
  4. Combined Works.
2154
80
2155
81
  You may convey a Combined Work under terms of your choice that,
2156
82
taken together, effectively do not restrict modification of the
2157
83
portions of the Library contained in the Combined Work and reverse
2158
84
engineering for debugging such modifications, if you also do each of
2159
85
the following:
2160
86
2161
87
   a) Give prominent notice with each copy of the Combined Work that
2162
88
   the Library is used in it and that the Library and its use are
2163
89
   covered by this License.
2164
90
2165
91
   b) Accompany the Combined Work with a copy of the GNU GPL and this license
2166
92
   document.
2167
93
2168
94
   c) For a Combined Work that displays copyright notices during
2169
95
   execution, include the copyright notice for the Library among
2170
96
   these notices, as well as a reference directing the user to the
2171
97
   copies of the GNU GPL and this license document.
2172
98
2173
99
   d) Do one of the following:
2174
100
2175
101
       0) Convey the Minimal Corresponding Source under the terms of this
2176
102
       License, and the Corresponding Application Code in a form
2177
103
       suitable for, and under terms that permit, the user to
2178
104
       recombine or relink the Application with a modified version of
2179
105
       the Linked Version to produce a modified Combined Work, in the
2180
106
       manner specified by section 6 of the GNU GPL for conveying
2181
107
       Corresponding Source.
2182
108
2183
109
       1) Use a suitable shared library mechanism for linking with the
2184
110
       Library.  A suitable mechanism is one that (a) uses at run time
2185
111
       a copy of the Library already present on the user's computer
2186
112
       system, and (b) will operate properly with a modified version
2187
113
       of the Library that is interface-compatible with the Linked
2188
114
       Version. 
2189
115
2190
116
   e) Provide Installation Information, but only if you would otherwise
2191
117
   be required to provide such information under section 6 of the
2192
118
   GNU GPL, and only to the extent that such information is
2193
119
   necessary to install and execute a modified version of the
2194
120
   Combined Work produced by recombining or relinking the
2195
121
   Application with a modified version of the Linked Version. (If
2196
122
   you use option 4d0, the Installation Information must accompany
2197
123
   the Minimal Corresponding Source and Corresponding Application
2198
124
   Code. If you use option 4d1, you must provide the Installation
2199
125
   Information in the manner specified by section 6 of the GNU GPL
2200
126
   for conveying Corresponding Source.)
2201
127
2202
128
  5. Combined Libraries.
2203
129
2204
130
  You may place library facilities that are a work based on the
2205
131
Library side by side in a single library together with other library
2206
132
facilities that are not Applications and are not covered by this
2207
133
License, and convey such a combined library under terms of your
2208
134
choice, if you do both of the following:
2209
135
2210
136
   a) Accompany the combined library with a copy of the same work based
2211
137
   on the Library, uncombined with any other library facilities,
2212
138
   conveyed under the terms of this License.
2213
139
2214
140
   b) Give prominent notice with the combined library that part of it
2215
141
   is a work based on the Library, and explaining where to find the
2216
142
   accompanying uncombined form of the same work.
2217
143
2218
144
  6. Revised Versions of the GNU Lesser General Public License.
2219
145
2220
146
  The Free Software Foundation may publish revised and/or new versions
2221
147
of the GNU Lesser General Public License from time to time. Such new
2222
148
versions will be similar in spirit to the present version, but may
2223
149
differ in detail to address new problems or concerns.
2224
150
2225
151
  Each version is given a distinguishing version number. If the
2226
152
Library as you received it specifies that a certain numbered version
2227
153
of the GNU Lesser General Public License "or any later version"
2228
154
applies to it, you have the option of following the terms and
2229
155
conditions either of that published version or of any later version
2230
156
published by the Free Software Foundation. If the Library as you
2231
157
received it does not specify a version number of the GNU Lesser
2232
158
General Public License, you may choose any version of the GNU Lesser
2233
159
General Public License ever published by the Free Software Foundation.
2234
160
2235
161
  If the Library as you received it specifies that a proxy can decide
2236
162
whether future versions of the GNU Lesser General Public License shall
2237
163
apply, that proxy's public statement of acceptance of any version is
2238
164
permanent authorization for you to choose that version for the
2239
165
Library.
2240
0
166
2241
=== added file 'doc/Makefile'
2242
--- doc/Makefile	1970-01-01 00:00:00 +0000
2243
+++ doc/Makefile	2010-07-28 20:35:51 +0000
2244
@@ -0,0 +1,23 @@
2245
1
.PHONY: help clean html text doctest
2246
2
2247
3
docs: html text
2248
4
2249
5
check: doctest
2250
6
2251
7
help:
2252
8
	cd src && $(MAKE) $@
2253
9
2254
10
html:
2255
11
	cd src && $(MAKE) $@
2256
12
	cp -r src/_build/html .
2257
13
2258
14
text:
2259
15
	cd src && $(MAKE) $@
2260
16
	cd src && tools/stitch_text.py index.rst _build/text > ../psycopg2.txt
2261
17
2262
18
doctest:
2263
19
	cd src && $(MAKE) $@
2264
20
2265
21
clean:
2266
22
	cd src && $(MAKE) $@
2267
23
	rm -rf html psycopg2.txt
2268
0
24
2269
=== added file 'doc/README'
2270
--- doc/README	1970-01-01 00:00:00 +0000
2271
+++ doc/README	2010-07-28 20:35:51 +0000
2272
@@ -0,0 +1,42 @@
2273
1
How to build psycopg documentation
2274
2
----------------------------------
2275
3
2276
4
- Install Sphinx, maybe in a virtualenv. Tested with Sphinx 0.6.4::
2277
5
2278
6
    ~$ virtualenv pd
2279
7
    New python executable in pd/bin/python
2280
8
    Installing setuptools............done.
2281
9
    ~$ cd pd
2282
10
    ~/pd$ source bin/activate
2283
11
    (pd)~/pd$ 
2284
12
2285
13
- Install Sphinx in the env::
2286
14
2287
15
    (pd)~/pd$ easy_install sphinx
2288
16
    Searching for sphinx
2289
17
    Reading http://pypi.python.org/simple/sphinx/
2290
18
    Reading http://sphinx.pocoo.org/
2291
19
    Best match: Sphinx 0.6.4
2292
20
    ...
2293
21
    Finished processing dependencies for sphinx
2294
22
2295
23
- Build psycopg2 and ensure the package can be imported (it will be used for
2296
24
  reading the version number, autodocs etc.)::
2297
25
2298
26
    (pd)~/pd/psycopg2$ python setup.py build
2299
27
    (pd)~/pd/psycopg2$ python setup.py install
2300
28
    running install
2301
29
    ...
2302
30
    creating ~/pd/lib/python2.6/site-packages/psycopg2
2303
31
    ...
2304
32
2305
33
- Move to the ``doc`` dir and run ``make`` from there::
2306
34
2307
35
    (pd)~/pd/psycopg2$ cd doc/
2308
36
    (pd)~/pd/psycopg2/doc$ make
2309
37
    Running Sphinx v0.6.4
2310
38
    ...
2311
39
2312
40
You should have the rendered documentation in ``./html`` and the text file
2313
41
``psycopg2.txt`` now.
2314
42
2315
0
43
2316
=== removed file 'doc/TODO'
2317
--- doc/TODO	2006-08-09 10:28:30 +0000
2318
+++ doc/TODO	1970-01-01 00:00:00 +0000
2319
@@ -1,33 +0,0 @@
2320
1
TODO list for psycopg 2 or later
2321
2
********************************
2322
3
2323
4
Move items to the DONE section only after writing a test for the
2324
5
implementation. Also add a note on how the item was resolved.
2325
6
(Obviously I was joking about the test..)
2326
7
2327
8
* Find a better way to compile the type-casting code instead of including it
2328
9
   in typecast.c directy. (Including is not that bad, but the need to touch
2329
10
   psycopg/typecast.c every time is bad bad bad.)
2330
11
2331
12
* executemany() should _not_ take the async flag, remove it and force multiple
2332
13
   queries to be synchronous.
2333
14
2334
15
* Fix all the docstrings.
2335
16
2336
17
* Support the protocols API fully.
2337
18
2338
19
* Unify the common code in typecast_datetime.c and typecast_mxdatetime.c.
2339
20
2340
21
* Port typecasters to new-style classes.
2341
22
2342
23
* Write a complete postgresql<->python encodings table.
2343
24
2344
25
* Implement binary typecasters (should be easy, but it will take time.)
2345
26
2346
27
DONE
2347
28
====
2348
29
2349
30
* Convert type-casters to new-style types in Python 2.2+.
2350
31
2351
32
* callproc() never worked, fix it or remove it and raise right exception.
2352
33
   [Removed callproc code, now an exception is raised.]
2353
34
0
2354
=== removed file 'doc/api-screen.css'
2355
--- doc/api-screen.css	2006-08-09 10:28:30 +0000
2356
+++ doc/api-screen.css	1970-01-01 00:00:00 +0000
2357
@@ -1,138 +0,0 @@
2358
1
/* Based on the Epydoc "default.css"
2359
2
** with some missing reST-related classes
2360
3
** and Python syntax support (from SilverCity)
2361
4
*/
2362
5
2363
6
/* Body color */ 
2364
7
body               { background: #ffffff; color: #000000; } 
2365
8
 
2366
9
/* Tables */ 
2367
10
table.summary, table.details, table.index
2368
11
                   { background: #e8f0f8; color: #000000; } 
2369
12
tr.summary, tr.details, tr.index
2370
13
                   { background: #70b0f0; color: #000000;  
2371
14
                     text-align: left; font-size: 120%; } 
2372
15
tr.group           { background: #c0e0f8; color: #000000;
2373
16
                     text-align: left; font-size: 120%;
2374
17
                     font-style: italic; } 
2375
18
2376
19
/* Documentation page titles */
2377
20
h2.module          { margin-top: 0.2em; }
2378
21
h2.class           { margin-top: 0.2em; }
2379
22
 
2380
23
/* Headings */
2381
24
h1.heading         { font-size: +140%; font-style: italic;
2382
25
                     font-weight: bold; }
2383
26
h2.heading         { font-size: +125%; font-style: italic;
2384
27
                     font-weight: bold; }
2385
28
h3.heading         { font-size: +110%; font-style: italic;
2386
29
                     font-weight: normal; }
2387
30
                    
2388
31
/* Base tree */
2389
32
pre.base-tree      { font-size: 80%; margin: 0; }
2390
33
2391
34
/* TOC */
2392
35
p.toc { margin: 0; }
2393
36
2394
37
/* Details Sections */
2395
38
table.func-details { background: #e8f0f8; color: #000000;
2396
39
                     border: 2px groove #c0d0d0;
2397
40
                     padding: 0 1em 0 1em; margin: 0.4em 0 0 0; }
2398
41
h3.func-detail     { background: transparent; color: #000000;
2399
42
                     margin: 0 0 1em 0; }
2400
43
2401
44
table.var-details  { background: #e8f0f8; color: #000000;
2402
45
                     border: 2px groove #c0d0d0;
2403
46
                     padding: 0 1em 0 1em; margin: 0.4em 0 0 0; }
2404
47
h3.var-details     { background: transparent; color: #000000;
2405
48
                     margin: 0 0 1em 0; }
2406
49
2407
50
/* Function signatures */
2408
51
.sig               { background: transparent; color: #000000;
2409
52
                     font-weight: bold; }  
2410
53
.sig-name          { background: transparent; color: #006080; }  
2411
54
.sig-arg, .sig-kwarg, .sig-vararg
2412
55
                   { background: transparent; color: #008060; }  
2413
56
.sig-default       { background: transparent; color: #602000; }  
2414
57
.summary-sig       { background: transparent; color: #000000; }  
2415
58
.summary-sig-name  { background: transparent; color: #204080; }
2416
59
.summary-sig-arg, .summary-sig-kwarg, .summary-sig-vararg
2417
60
                   { background: transparent; color: #008060; }  
2418
61
2419
62
/* Doctest blocks */
2420
63
.py-src            { background: transparent; color: #000000; }
2421
64
.py-prompt         { background: transparent; color: #005050;
2422
65
                     font-weight: bold;}
2423
66
.py-string         { background: transparent; color: #006030; }
2424
67
.py-comment        { background: transparent; color: #003060; }
2425
68
.py-keyword        { background: transparent; color: #600000; }
2426
69
.py-output         { background: transparent; color: #404040; }
2427
70
div.code-block,
2428
71
pre.literal-block,
2429
72
pre.doctestblock   { background: #f4faff; color: #000000; 
2430
73
                     padding: .5em; margin: 1em;
2431
74
                     border: 1px solid #708890; }
2432
75
table pre.doctestblock
2433
76
                   { background: #dce4ec; color: #000000; 
2434
77
                     padding: .5em; margin: 1em;
2435
78
                     border: 1px solid #708890; }
2436
79
div.code-block     { font-family: monospace; }
2437
80
2438
81
/* Variable values */
2439
82
pre.variable       { background: #dce4ec; color: #000000;
2440
83
                     padding: .5em; margin: 0;
2441
84
                     border: 1px solid #708890; }
2442
85
.variable-linewrap { background: transparent; color: #604000; }
2443
86
.variable-ellipsis { background: transparent; color: #604000; }
2444
87
.variable-quote    { background: transparent; color: #604000; }
2445
88
.re                { background: transparent; color: #000000; }
2446
89
.re-char           { background: transparent; color: #006030; }
2447
90
.re-op             { background: transparent; color: #600000; }
2448
91
.re-group          { background: transparent; color: #003060; }
2449
92
.re-ref            { background: transparent; color: #404040; }
2450
93
2451
94
/* Navigation bar */ 
2452
95
table.navbar       { background: #a0c0ff; color: #0000ff;
2453
96
                     border: 2px groove #c0d0d0; }
2454
97
th.navbar          { background: #a0c0ff; color: #0000ff; } 
2455
98
th.navselect       { background: #70b0ff; color: #000000; } 
2456
99
.nomargin          { margin: 0; }
2457
100
2458
101
/* Links */ 
2459
102
a:link             { background: transparent; color: #0000ff; }  
2460
103
a:visited          { background: transparent; color: #204080; }  
2461
104
a.navbar:link      { background: transparent; color: #0000ff; 
2462
105
                     text-decoration: none; }  
2463
106
a.navbar:visited   { background: transparent; color: #204080; 
2464
107
                     text-decoration: none; }  
2465
108
2466
109
/* Admonitions */
2467
110
div.warning,
2468
111
div.note                { background-color: #c0e0f8;
2469
112
                          border: thin solid black;
2470
113
                          padding: 1em;
2471
114
                          margin-left: 1em;
2472
115
                          margin-right: 1em; }
2473
116
div.warning .first,
2474
117
div.note .first      { font-family: sans-serif;
2475
118
                          font-size: 110%;
2476
119
                          margin-right: 0.5em; }
2477
120
2478
121
/* Lists */
2479
122
ul { margin-top: 0; }
2480
123
2481
124
/* Python syntax */
2482
125
.p_character { color: olive; }
2483
126
.p_classname { color: blue; font-weight: bold; }
2484
127
.p_commentblock {color: gray; font-style: italic; }
2485
128
.p_commentline { color: green; font-style: italic; }
2486
129
.p_default {}
2487
130
.p_defname { color: #009999; font-weight: bold; }
2488
131
.p_identifier { color: black; }
2489
132
.p_number { color: #009999; }
2490
133
.p_operator { color: black; }
2491
134
.p_string { color: #7F007F; }
2492
135
.p_stringeol { color: #7F007F; }
2493
136
.p_triple { color: #7F0000; }
2494
137
.p_tripledouble { color: #7F0000; }
2495
138
.p_word { color: navy; font-weight: bold; }
2496
139
0
2497
=== removed file 'doc/async.txt'
2498
--- doc/async.txt	2006-08-09 10:28:30 +0000
2499
+++ doc/async.txt	1970-01-01 00:00:00 +0000
2500
@@ -1,67 +0,0 @@
2501
1
psycopg asynchronous API
2502
2
************************
2503
3
2504
4
** Important: async quaeries are not enabled for 2.0 **
2505
5
2506
6
Program code can initiate an asynchronous query by passing an 'async=1' flag
2507
7
to the .execute() method. A very simple example, from the connection to the
2508
8
query:
2509
9
2510
10
    conn = psycopg.connect(database='test')
2511
11
    curs = conn.cursor()
2512
12
    curs.execute("SEECT * from test WHERE fielda > %s", (1971,), async=1)
2513
13
    
2514
14
From then on any query on other cursors derived from the same connection is
2515
15
doomed to fail (and raise an exception) until the original cursor (the one
2516
16
executing the query) complete the asynchronous operation. This can happen in
2517
17
a number of different ways:
2518
18
2519
19
    1) one of the .fetchXXX() methods is called, effectively blocking untill
2520
20
       data has been sent from the backend to the client, terminating the
2521
21
       query.
2522
22
       
2523
23
    2) .cancel() is called. This method tries to abort the current query and
2524
24
       will block until the query is aborted or fully executed. The return
2525
25
       value is True if the query was successfully aborted or False if it
2526
26
       was executed. Query result are discarded in both cases.
2527
27
       
2528
28
    3) .execute() is called again on the same cursor (.execute() on a
2529
29
       different cursor will simply raise an exception.) This waits for the
2530
30
       complete execution of the current query, discard any data and execute
2531
31
       the new one.
2532
32
2533
33
Note that calling .execute() two times in a row will not abort the former
2534
34
query and will temporarily go to synchronous mode until the first of the two
2535
35
queries is executed.
2536
36
2537
37
Cursors now have some extra methods that make them usefull during
2538
38
asynchronous queries:
2539
39
2540
40
    .fileno()
2541
41
      Returns the file descriptor associated with the current connection and
2542
42
      make possible to use a cursor in a context where a file object would be
2543
43
      expected (like in a select() call.)
2544
44
2545
45
    .isbusy()
2546
46
      Returns True if the backend is still processing the query or false if
2547
47
      data is ready to be fetched (by one of the .fetchXXX() methods.)
2548
48
      
2549
49
A code snippet that shows how to use the cursor object in a select() call:
2550
50
2551
51
    import psycopg
2552
52
    import select
2553
53
        
2554
54
    conn = psycopg.connect(database='test')
2555
55
    curs = conn.cursor()
2556
56
    curs.execute("SEECT * from test WHERE fielda > %s", (1971,), async=1)
2557
57
2558
58
    # wait for input with a maximum timeout of 5 seconds
2559
59
    query_ended = False
2560
60
    while not query_ended:
2561
61
        rread, rwrite, rspec = select([cursor, another_file], [], [], 5)
2562
62
	if not cursor.isbusy():
2563
63
	   query_ended = True
2564
64
	# manage input from other sources like other_file, etc.
2565
65
    print "Query Results:"
2566
66
    for row in cursor:
2567
67
        print row
2568
68
0
2569
=== removed file 'doc/extensions.rst'
2570
--- doc/extensions.rst	2006-08-09 10:28:30 +0000
2571
+++ doc/extensions.rst	1970-01-01 00:00:00 +0000
2572
@@ -1,260 +0,0 @@
2573
1
=======================================
2574
2
 psycopg 2 extensions to the DBAPI 2.0
2575
3
=======================================
2576
4
2577
5
This document is a short summary of the extensions built in psycopg 2.0.x over
2578
6
the standard `Python Database API Specification 2.0`__, usually called simply
2579
7
DBAPI-2.0 or even PEP-249.  Before reading on this document please make sure
2580
8
you already know how to program in Python using a DBAPI-2.0 compliant driver:
2581
9
basic concepts like opening a connection, executing queries and commiting or
2582
10
rolling back a transaction will not be explained but just used.
2583
11
2584
12
.. __: http://www.python.org/peps/pep-0249.html
2585
13
2586
14
Many objects and extension functions are defined in the `psycopg2.extensions`
2587
15
module.
2588
16
2589
17
2590
18
Connection and cursor factories
2591
19
===============================
2592
20
2593
21
psycopg 2 exposes two new-style classes that can be sub-classed and expanded to
2594
22
adapt them to the needs of the programmer: `cursor` and `connection`.  The
2595
23
`connection` class is usually sub-classed only to provide an easy way to create
2596
24
customized cursors but other uses are possible. `cursor` is much more
2597
25
interesting, because it is the class where query building, execution and result
2598
26
type-casting into Python variables happens.
2599
27
2600
28
An example of cursor subclass performing logging is::
2601
29
2602
30
    import psycopg2
2603
31
    import psycopg2.extensions
2604
32
    import logging
2605
33
2606
34
    class LoggingCursor(psycopg2.extensions.cursor):
2607
35
        def execute(self, sql, args=None):
2608
36
            logger = logging.getLogger('sql_debug')
2609
37
            logger.info(self.mogrify(sql, args))
2610
38
2611
39
            try:
2612
40
                psycopg2.extensions.cursor.execute(self, sql, args)
2613
41
            except Exception, exc:
2614
42
                logger.error("%s: %s" % (exc.__class__.__name__, exc))
2615
43
                raise
2616
44
2617
45
    conn = psycopg2.connect(DSN)
2618
46
    curs = conn.cursor(cursor_factory=LoggingCursor)
2619
47
    curs.execute("INSERT INTO mytable VALUES (%s, %s, %s);",
2620
48
                 (10, 20, 30))
2621
49
2622
50
2623
51
Row factories
2624
52
-------------
2625
53
2626
54
tzinfo factories
2627
55
----------------
2628
56
2629
57
2630
58
Setting transaction isolation levels
2631
59
====================================
2632
60
2633
61
psycopg2 connection objects hold informations about the PostgreSQL `transaction
2634
62
isolation level`_.  The current transaction level can be read from the
2635
63
`.isolation_level` attribute.  The default isolation level is ``READ
2636
64
COMMITTED``.  A different isolation level con be set through the
2637
65
`.set_isolation_level()` method.  The level can be set to one of the following
2638
66
constants, defined in `psycopg2.extensions`:
2639
67
2640
68
`ISOLATION_LEVEL_AUTOCOMMIT`
2641
69
    No transaction is started when command are issued and no
2642
70
    `.commit()`/`.rollback()` is required.  Some PostgreSQL command such as
2643
71
    ``CREATE DATABASE`` can't run into a transaction: to run such command use
2644
72
    `.set_isolation_level(ISOLATION_LEVEL_AUTOCOMMIT)`.
2645
73
    
2646
74
`ISOLATION_LEVEL_READ_COMMITTED`
2647
75
    This is the default value.  A new transaction is started at the first
2648
76
    `.execute()` command on a cursor and at each new `.execute()` after a
2649
77
    `.commit()` or a `.rollback()`.  The transaction runs in the PostgreSQL
2650
78
    ``READ COMMITTED`` isolation level.
2651
79
    
2652
80
`ISOLATION_LEVEL_SERIALIZABLE`
2653
81
    Transactions are run at a ``SERIALIZABLE`` isolation level.
2654
82
2655
83
2656
84
.. _transaction isolation level: 
2657
85
   http://www.postgresql.org/docs/8.1/static/transaction-iso.html
2658
86
2659
87
2660
88
Adaptation of Python values to SQL types
2661
89
========================================
2662
90
2663
91
psycopg2 casts Python variables to SQL literals by type.  Standard Python types
2664
92
are already adapted to the proper SQL literal.
2665
93
2666
94
Example: the Python function::
2667
95
2668
96
    curs.execute("""INSERT INTO atable (anint, adate, astring)
2669
97
                     VALUES (%s, %s, %s)""",
2670
98
                 (10, datetime.date(2005, 11, 18), "O'Reilly"))
2671
99
2672
100
is converted into the SQL command::
2673
101
2674
102
    INSERT INTO atable (anint, adate, astring)
2675
103
     VALUES (10, '2005-11-18', 'O''Reilly');
2676
104
2677
105
Named arguments are supported too with ``%(name)s`` placeholders. Notice that:
2678
106
2679
107
  - The Python string operator ``%`` is not used: the `.execute()` function
2680
108
    accepts the values tuple or dictionary as second parameter.
2681
109
2682
110
  - The variables placeholder must always be a ``%s``, even if a different
2683
111
    placeholder (such as a ``%d`` for an integer) may look more appropriate.
2684
112
2685
113
  - For positional variables binding, the second argument must always be a
2686
114
    tuple, even if it contains a single variable.
2687
115
2688
116
  - Only variable values should be bound via this method: it shouldn't be used
2689
117
    to set table or field names. For these elements, ordinary string formatting
2690
118
    should be used before running `.execute()`.
2691
119
2692
120
2693
121
Adapting new types
2694
122
------------------
2695
123
2696
124
Any Python class or type can be adapted to an SQL string.  Adaptation mechanism
2697
125
is similar to the Object Adaptation proposed in the `PEP-246`_ and is exposed
2698
126
by the `adapt()` function.
2699
127
2700
128
psycopg2 `.execute()` method adapts its ``vars`` arguments to the `ISQLQuote`
2701
129
protocol.  Objects that conform to this protocol expose a ``getquoted()`` method
2702
130
returning the SQL representation of the object as a string.
2703
131
2704
132
The easiest way to adapt an object to an SQL string is to register an adapter
2705
133
function via the `register_adapter()` function.  The adapter function must take
2706
134
the value to be adapted as argument and return a conform object.  A convenient
2707
135
object is the `AsIs` wrapper, whose ``getquoted()`` result is simply the
2708
136
``str()``\ ingification of the wrapped object.
2709
137
2710
138
Example: mapping of a ``Point`` class into the ``point`` PostgreSQL geometric
2711
139
type::
2712
140
2713
141
    from psycopg2.extensions import adapt, register_adapter, AsIs
2714
142
    
2715
143
    class Point(object):
2716
144
        def __init__(self, x=0.0, y=0.0):
2717
145
            self.x = x
2718
146
            self.y = y
2719
147
    
2720
148
    def adapt_point(point):
2721
149
        return AsIs("'(%s,%s)'" % (adapt(point.x), adapt(point.y)))
2722
150
        
2723
151
    register_adapter(Point, adapt_point)
2724
152
    
2725
153
    curs.execute("INSERT INTO atable (apoint) VALUES (%s)", 
2726
154
                 (Point(1.23, 4.56),))
2727
155
2728
156
The above function call results in the SQL command::
2729
157
2730
158
    INSERT INTO atable (apoint) VALUES ((1.23, 4.56));
2731
159
2732
160
2733
161
.. _PEP-246: http://www.python.org/peps/pep-0246.html
2734
162
2735
163
2736
164
Type casting of SQL types into Python values
2737
165
============================================
2738
166
2739
167
PostgreSQL objects read from the database can be adapted to Python objects
2740
168
through an user-defined adapting function.  An adapter function takes two
2741
169
argments: the object string representation as returned by PostgreSQL and the
2742
170
cursor currently being read, and should return a new Python object.  For
2743
171
example, the following function parses a PostgreSQL ``point`` into the
2744
172
previously defined ``Point`` class::
2745
173
2746
174
    def cast_point(value, curs):
2747
175
        if value is not None:
2748
176
        	# Convert from (f1, f2) syntax using a regular expression.
2749
177
            m = re.match("\((.*),(.*)\)", value) 
2750
178
            if m:
2751
179
                return Point(float(m.group(1)), float(m.group(2)))
2752
180
                
2753
181
To create a mapping from the PostgreSQL type (either standard or user-defined),
2754
182
its ``oid`` must be known. It can be retrieved either by the second column of
2755
183
the cursor description::
2756
184
2757
185
    curs.execute("SELECT NULL::point")
2758
186
    point_oid = curs.description[0][1]   # usually returns 600
2759
187
2760
188
or by querying the system catalogs for the type name and namespace (the
2761
189
namespace for system objects is ``pg_catalog``)::
2762
190
2763
191
    curs.execute("""
2764
192
        SELECT pg_type.oid
2765
193
          FROM pg_type JOIN pg_namespace
2766
194
                 ON typnamespace = pg_namespace.oid
2767
195
         WHERE typname = %(typename)s
2768
196
           AND nspname = %(namespace)s""",
2769
197
                {'typename': 'point', 'namespace': 'pg_catalog'})
2770
198
        
2771
199
    point_oid = curs.fetchone()[0]
2772
200
2773
201
After you know the object ``oid``, you must can and register the new type::
2774
202
2775
203
    POINT = psycopg2.extensions.new_type((point_oid,), "POINT", cast_point)
2776
204
    psycopg2.extensions.register_type(POINT)
2777
205
2778
206
The `new_type()` function binds the object oids (more than one can be
2779
207
specified) to the adapter function.  `register_type()` completes the spell.
2780
208
Conversion is automatically performed when a column whose type is a registered
2781
209
``oid`` is read::
2782
210
2783
211
    curs.execute("SELECT '(10.2,20.3)'::point")
2784
212
    point = curs.fetchone()[0]
2785
213
    print type(point), point.x, point.y
2786
214
    # Prints: "<class '__main__.Point'> 10.2 20.3"
2787
215
2788
216
2789
217
Working with times and dates
2790
218
============================
2791
219
2792
220
2793
221
Receiving NOTIFYs
2794
222
=================
2795
223
2796
224
2797
225
Using COPY TO and COPY FROM
2798
226
===========================
2799
227
2800
228
psycopg2 `cursor` object provides an interface to the efficient `PostgreSQL
2801
229
COPY command`__ to move data from files to tables and back.
2802
230
2803
231
The `.copy_to(file, table)` method writes the content of the table
2804
232
named ``table`` *to* the file-like object ``file``. ``file`` must have a
2805
233
``write()`` method.
2806
234
2807
235
The `.copy_from(file, table)` reads data *from* the file-like object
2808
236
``file`` appending them to the table named ``table``. ``file`` must have both
2809
237
``read()`` and ``readline()`` method.
2810
238
2811
239
Both methods accept two optional arguments: ``sep`` (defaulting to a tab) is
2812
240
the columns separator and ``null`` (defaulting to ``\N``) represents ``NULL``
2813
241
values in the file.
2814
242
2815
243
.. __: http://www.postgresql.org/docs/8.1/static/sql-copy.html
2816
244
2817
245
2818
246
PostgreSQL status message and executed query
2819
247
============================================
2820
248
2821
249
`cursor` objects have two special fields related to the last executed query:
2822
250
2823
251
  - `.query` is the textual representation (str or unicode, depending on what
2824
252
    was passed to `.execute()` as first argument) of the query *after* argument
2825
253
    binding and mogrification has been applied. To put it another way, `.query`
2826
254
    is the *exact* query that was sent to the PostgreSQL backend.
2827
255
    
2828
256
  - `.statusmessage` is the status message that the backend sent upon query
2829
257
    execution. It usually contains the basic type of the query (SELECT,
2830
258
    INSERT, UPDATE, ...) and some additional information like the number of
2831
259
    rows updated and so on. Refer to the PostgreSQL manual for more
2832
260
    information.
2833
261
0
2834
=== added directory 'doc/html'
2835
=== added file 'doc/html/.buildinfo'
2836
--- doc/html/.buildinfo	1970-01-01 00:00:00 +0000
2837
+++ doc/html/.buildinfo	2010-07-28 20:35:51 +0000
2838
@@ -0,0 +1,4 @@
2839
1
# Sphinx build info version 1
2840
2
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
2841
3
config: 3b2e5d90696feaaf51ed99c8708bfbca
2842
4
tags: fbb0d17656682115ca4d033fb2f83ba1
2843
0
5
2844
=== added directory 'doc/html/_sources'
2845
=== added file 'doc/html/_sources/advanced.txt'
2846
--- doc/html/_sources/advanced.txt	1970-01-01 00:00:00 +0000
2847
+++ doc/html/_sources/advanced.txt	2010-07-28 20:35:51 +0000
2848
@@ -0,0 +1,450 @@
2849
1
More advanced topics
2850
2
====================
2851
3
2852
4
.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
2853
5
2854
6
.. testsetup:: *
2855
7
2856
8
    import re
2857
9
    import select
2858
10
2859
11
    cur.execute("CREATE TABLE atable (apoint point)")
2860
12
    conn.commit()
2861
13
2862
14
    def wait(conn):
2863
15
        while 1:
2864
16
            state = conn.poll()
2865
17
            if state == psycopg2.extensions.POLL_OK:
2866
18
                break
2867
19
            elif state == psycopg2.extensions.POLL_WRITE:
2868
20
                select.select([], [conn.fileno()], [])
2869
21
            elif state == psycopg2.extensions.POLL_READ:
2870
22
                select.select([conn.fileno()], [], [])
2871
23
            else:
2872
24
                raise psycopg2.OperationalError("poll() returned %s" % state)
2873
25
2874
26
    aconn = psycopg2.connect(database='test', async=1)
2875
27
    wait(aconn)
2876
28
    acurs = aconn.cursor()
2877
29
2878
30
.. index::
2879
31
    double: Subclassing; Cursor
2880
32
    double: Subclassing; Connection
2881
33
2882
34
.. _subclassing-connection:
2883
35
.. _subclassing-cursor:
2884
36
2885
37
Connection and cursor factories
2886
38
-------------------------------
2887
39
2888
40
Psycopg exposes two new-style classes that can be sub-classed and expanded to
2889
41
adapt them to the needs of the programmer: `psycopg2.extensions.cursor`
2890
42
and `psycopg2.extensions.connection`.  The `connection` class is
2891
43
usually sub-classed only to provide an easy way to create customized cursors
2892
44
but other uses are possible. `cursor` is much more interesting, because
2893
45
it is the class where query building, execution and result type-casting into
2894
46
Python variables happens.
2895
47
2896
48
.. index::
2897
49
    single: Example; Cursor subclass
2898
50
2899
51
An example of cursor subclass performing logging is::
2900
52
2901
53
    import psycopg2
2902
54
    import psycopg2.extensions
2903
55
    import logging
2904
56
2905
57
    class LoggingCursor(psycopg2.extensions.cursor):
2906
58
        def execute(self, sql, args=None):
2907
59
            logger = logging.getLogger('sql_debug')
2908
60
            logger.info(self.mogrify(sql, args))
2909
61
2910
62
            try:
2911
63
                psycopg2.extensions.cursor.execute(self, sql, args)
2912
64
            except Exception, exc:
2913
65
                logger.error("%s: %s" % (exc.__class__.__name__, exc))
2914
66
                raise
2915
67
2916
68
    conn = psycopg2.connect(DSN)
2917
69
    cur = conn.cursor(cursor_factory=LoggingCursor)
2918
70
    cur.execute("INSERT INTO mytable VALUES (%s, %s, %s);",
2919
71
                 (10, 20, 30))
2920
72
2921
73
2922
74
2923
75
.. index::
2924
76
    single: Objects; Creating new adapters
2925
77
    single: Adaptation; Creating new adapters
2926
78
    single: Data types; Creating new adapters
2927
79
2928
80
.. _adapting-new-types:
2929
81
2930
82
Adapting new Python types to SQL syntax
2931
83
---------------------------------------
2932
84
2933
85
Any Python class or type can be adapted to an SQL string.  Adaptation mechanism
2934
86
is similar to the Object Adaptation proposed in the :pep:`246` and is exposed
2935
87
by the `psycopg2.extensions.adapt()` function.
2936
88
2937
89
The `~cursor.execute()` method adapts its arguments to the
2938
90
`~psycopg2.extensions.ISQLQuote` protocol.  Objects that conform to this
2939
91
protocol expose a `!getquoted()` method returning the SQL representation
2940
92
of the object as a string.
2941
93
2942
94
The easiest way to adapt an object to an SQL string is to register an adapter
2943
95
function via the `~psycopg2.extensions.register_adapter()` function.  The
2944
96
adapter function must take the value to be adapted as argument and return a
2945
97
conform object.  A convenient object is the `~psycopg2.extensions.AsIs`
2946
98
wrapper, whose `!getquoted()` result is simply the `!str()`\ ing
2947
99
conversion of the wrapped object.
2948
100
2949
101
.. index::
2950
102
    single: Example; Types adaptation
2951
103
2952
104
Example: mapping of a `!Point` class into the |point|_ PostgreSQL
2953
105
geometric type:
2954
106
2955
107
.. doctest::
2956
108
2957
109
    >>> from psycopg2.extensions import adapt, register_adapter, AsIs
2958
110
2959
111
    >>> class Point(object):
2960
112
    ...    def __init__(self, x, y):
2961
113
    ...        self.x = x
2962
114
    ...        self.y = y
2963
115
2964
116
    >>> def adapt_point(point):
2965
117
    ...     return AsIs("'(%s, %s)'" % (adapt(point.x), adapt(point.y)))
2966
118
2967
119
    >>> register_adapter(Point, adapt_point)
2968
120
2969
121
    >>> cur.execute("INSERT INTO atable (apoint) VALUES (%s)",
2970
122
    ...             (Point(1.23, 4.56),))
2971
123
2972
124
2973
125
.. |point| replace:: :sql:`point`
2974
126
.. _point: http://www.postgresql.org/docs/8.4/static/datatype-geometric.html#AEN6084
2975
127
2976
128
The above function call results in the SQL command::
2977
129
2978
130
    INSERT INTO atable (apoint) VALUES ((1.23, 4.56));
2979
131
2980
132
2981
133
2982
134
.. index:: Type casting
2983
135
2984
136
.. _type-casting-from-sql-to-python:
2985
137
2986
138
Type casting of SQL types into Python objects
2987
139
---------------------------------------------
2988
140
2989
141
PostgreSQL objects read from the database can be adapted to Python objects
2990
142
through an user-defined adapting function.  An adapter function takes two
2991
143
arguments: the object string representation as returned by PostgreSQL and the
2992
144
cursor currently being read, and should return a new Python object.  For
2993
145
example, the following function parses the PostgreSQL :sql:`point`
2994
146
representation into the previously defined `!Point` class:
2995
147
2996
148
    >>> def cast_point(value, cur):
2997
149
    ...    if value is None:
2998
150
    ...        return None
2999
151
    ...
3000
152
    ...    # Convert from (f1, f2) syntax using a regular expression.
3001
153
    ...    m = re.match(r"\(([^)]+),([^)]+)\)", value)
3002
154
    ...    if m:
3003
155
    ...        return Point(float(m.group(1)), float(m.group(2)))
3004
156
    ...    else:
3005
157
    ...        raise InterfaceError("bad point representation: %r" % value)
3006
158
                
3007
159
3008
160
In order to create a mapping from a PostgreSQL type (either standard or
3009
161
user-defined), its OID must be known. It can be retrieved either by the second
3010
162
column of the `cursor.description`:
3011
163
3012
164
    >>> cur.execute("SELECT NULL::point")
3013
165
    >>> point_oid = cur.description[0][1]
3014
166
    >>> point_oid
3015
167
    600
3016
168
3017
169
or by querying the system catalog for the type name and namespace (the
3018
170
namespace for system objects is :sql:`pg_catalog`):
3019
171
3020
172
    >>> cur.execute("""
3021
173
    ...    SELECT pg_type.oid
3022
174
    ...      FROM pg_type JOIN pg_namespace
3023
175
    ...             ON typnamespace = pg_namespace.oid
3024
176
    ...     WHERE typname = %(typename)s
3025
177
    ...       AND nspname = %(namespace)s""",
3026
178
    ...    {'typename': 'point', 'namespace': 'pg_catalog'})
3027
179
    >>> point_oid = cur.fetchone()[0]
3028
180
    >>> point_oid
3029
181
    600
3030
182
3031
183
After you know the object OID, you can create and register the new type:
3032
184
3033
185
    >>> POINT = psycopg2.extensions.new_type((point_oid,), "POINT", cast_point)
3034
186
    >>> psycopg2.extensions.register_type(POINT)
3035
187
3036
188
The `~psycopg2.extensions.new_type()` function binds the object OIDs
3037
189
(more than one can be specified) to the adapter function.
3038
190
`~psycopg2.extensions.register_type()` completes the spell.  Conversion
3039
191
is automatically performed when a column whose type is a registered OID is
3040
192
read:
3041
193
3042
194
    >>> cur.execute("SELECT '(10.2,20.3)'::point")
3043
195
    >>> point = cur.fetchone()[0]
3044
196
    >>> print type(point), point.x, point.y
3045
197
    <class 'Point'> 10.2 20.3
3046
198
3047
199
3048
200
3049
201
.. index::
3050
202
    pair: Asynchronous; Notifications
3051
203
    pair: LISTEN; SQL command
3052
204
    pair: NOTIFY; SQL command
3053
205
3054
206
.. _async-notify:
3055
207
3056
208
Asynchronous notifications
3057
209
--------------------------
3058
210
3059
211
Psycopg allows asynchronous interaction with other database sessions using the
3060
212
facilities offered by PostgreSQL commands |LISTEN|_ and |NOTIFY|_. Please
3061
213
refer to the PostgreSQL documentation for examples of how to use this form of
3062
214
communications.
3063
215
3064
216
Notifications received are made available in the `connection.notifies`
3065
217
list. Notifications can be sent from Python code simply using a :sql:`NOTIFY`
3066
218
command in an `~cursor.execute()` call.
3067
219
3068
220
Because of the way sessions interact with notifications (see |NOTIFY|_
3069
221
documentation), you should keep the connection in :ref:`autocommit
3070
222
<autocommit>` mode if you wish to receive or send notifications in a timely
3071
223
manner.
3072
224
3073
225
.. |LISTEN| replace:: :sql:`LISTEN`
3074
226
.. _LISTEN: http://www.postgresql.org/docs/8.4/static/sql-listen.html
3075
227
.. |NOTIFY| replace:: :sql:`NOTIFY`
3076
228
.. _NOTIFY: http://www.postgresql.org/docs/8.4/static/sql-notify.html
3077
229
3078
230
Notification are received after every query execution. If the user is interested
3079
231
in receiving notification but not in performing any query, the
3080
232
`~connection.poll()` method can be used to check for notification without
3081
233
wasting resources.
3082
234
3083
235
A simple application could poll the connection from time to time to check if
3084
236
something new has arrived. A better strategy is to use some I/O completion
3085
237
function such as |select()|_ to sleep until awaken from the kernel when there is
3086
238
some data to read on the connection, thereby using no CPU unless there is
3087
239
something to read::
3088
240
3089
241
    import select
3090
242
    import psycopg2
3091
243
    import psycopg2.extensions
3092
244
3093
245
    conn = psycopg2.connect(DSN)
3094
246
    conn.set_isolation_level(psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT)
3095
247
3096
248
    curs = conn.cursor()
3097
249
    curs.execute("LISTEN test;")
3098
250
3099
251
    print "Waiting for 'NOTIFY test'"
3100
252
    while 1:
3101
253
        if select.select([conn],[],[],5) == ([],[],[]):
3102
254
            print "Timeout"
3103
255
        else:
3104
256
            conn.poll()
3105
257
            while conn.notifies:
3106
258
                print "Got NOTIFY:", conn.notifies.pop()
3107
259
3108
260
Running the script and executing the command :sql:`NOTIFY test` in a separate
3109
261
:program:`psql` shell, the output may look similar to::
3110
262
3111
263
    Waiting for 'NOTIFY test'
3112
264
    Timeout
3113
265
    Timeout
3114
266
    Got NOTIFY: (6535, 'test')
3115
267
    Timeout
3116
268
    ...
3117
269
3118
270
3119
271
3120
272
.. index::
3121
273
    double: Asynchronous; Connection
3122
274
3123
275
.. _async-support:
3124
276
3125
277
Asynchronous support
3126
278
--------------------
3127
279
3128
280
.. versionadded:: 2.2.0
3129
281
3130
282
Psycopg can issue asynchronous queries to a PostgreSQL database. An asynchronous
3131
283
communication style is established passing the parameter *async*\=1 to the
3132
284
`~psycopg2.connect()` function: the returned connection will work in
3133
285
*asynchronous mode*.
3134
286
3135
287
In asynchronous mode, a Psycopg connection will rely on the caller to poll the
3136
288
socket file descriptor, checking if it is ready to accept data or if a query
3137
289
result has been transferred and is ready to be read on the client. The caller
3138
290
can use the method `~connection.fileno()` to get the connection file
3139
291
descriptor and `~connection.poll()` to make communication proceed according to
3140
292
the current connection state.
3141
293
3142
294
The following is an example loop using methods `!fileno()` and `!poll()`
3143
295
together with the Python |select()|_ function in order to carry on
3144
296
asynchronous operations with Psycopg::
3145
297
3146
298
    def wait(conn):
3147
299
        while 1:
3148
300
            state = conn.poll()
3149
301
            if state == psycopg2.extensions.POLL_OK:
3150
302
                break
3151
303
            elif state == psycopg2.extensions.POLL_WRITE:
3152
304
                select.select([], [conn.fileno()], [])
3153
305
            elif state == psycopg2.extensions.POLL_READ:
3154
306
                select.select([conn.fileno()], [], [])
3155
307
            else:
3156
308
                raise psycopg2.OperationalError("poll() returned %s" % state)
3157
309
3158
310
.. |select()| replace:: `!select()`
3159
311
.. _select(): http://docs.python.org/library/select.html#select.select
3160
312
3161
313
The above loop of course would block an entire application: in a real
3162
314
asynchronous framework, `!select()` would be called on many file descriptors
3163
315
waiting for any of them to be ready.  Nonetheless the function can be used to
3164
316
connect to a PostgreSQL server only using nonblocking commands and the
3165
317
connection obtained can be used to perform further nonblocking queries.  After
3166
318
`!poll()` has returned `~psycopg2.extensions.POLL_OK`, and thus `!wait()` has
3167
319
returned, the connection can be safely used:
3168
320
3169
321
    >>> aconn = psycopg2.connect(database='test', async=1)
3170
322
    >>> wait(aconn)
3171
323
    >>> acurs = aconn.cursor()
3172
324
3173
325
Notice that there are a few other requirements to be met in order to have a
3174
326
completely non-blocking connection attempt: see the libpq documentation for
3175
327
|PQconnectStart|_.
3176
328
3177
329
.. |PQconnectStart| replace:: `!PQconnectStart()`
3178
330
.. _PQconnectStart: http://www.postgresql.org/docs/8.4/static/libpq-connect.html#AEN33199
3179
331
3180
332
The same loop should be also used to perform nonblocking queries: after
3181
333
sending a query via `~cursor.execute()` or `~cursor.callproc()`, call
3182
334
`!poll()` on the connection available from `cursor.connection` until it
3183
335
returns `!POLL_OK`, at which pont the query has been completely sent to the
3184
336
server and, if it produced data, the results have been transferred to the
3185
337
client and available using the regular cursor methods:
3186
338
3187
339
    >>> acurs.execute("SELECT pg_sleep(5); SELECT 42;")
3188
340
    >>> wait(acurs.connection)
3189
341
    >>> acurs.fetchone()[0]
3190
342
    42
3191
343
3192
344
When an asynchronous query is being executed, `connection.isexecuting()` returns
3193
345
`True`. Two cursors can't execute concurrent queries on the same asynchronous
3194
346
connection.
3195
347
3196
348
There are several limitations in using asynchronous connections: the
3197
349
connection is always in :ref:`autocommit <autocommit>` mode and it is not
3198
350
possible to change it using `~connection.set_isolation_level()`. So a
3199
351
transaction is not implicitly started at the first query and is not possible
3200
352
to use methods `~connection.commit()` and `~connection.rollback()`: you can
3201
353
manually control transactions using `~cursor.execute()` to send database
3202
354
commands such as :sql:`BEGIN`, :sql:`COMMIT` and :sql:`ROLLBACK`.
3203
355
3204
356
With asynchronous connections it is also not possible to use
3205
357
`~connection.set_client_encoding()`, `~cursor.executemany()`, :ref:`large
3206
358
objects <large-objects>`, :ref:`named cursors <server-side-cursors>`.
3207
359
3208
360
:ref:`COPY commands <copy>` are not supported either in asynchronous mode, but
3209
361
this will be probably implemented in a future release.
3210
362
3211
363
3212
364
3213
365
3214
366
.. index::
3215
367
    single: Greenlet, Coroutine, Eventlet, gevent, Wait callback
3216
368
3217
369
.. _green-support:
3218
370
3219
371
Support to coroutine libraries
3220
372
------------------------------
3221
373
3222
374
.. versionadded:: 2.2.0
3223
375
3224
376
Psycopg can be used together with coroutine_\-based libraries, and participate
3225
377
to cooperative multithreading.
3226
378
3227
379
Coroutine-based libraries (such as Eventlet_ or gevent_) can usually patch the
3228
380
Python standard library in order to enable a coroutine switch in the presence of
3229
381
blocking I/O: the process is usually referred as making the system *green*, in
3230
382
reference to the `green threads`_.
3231
383
3232
384
Because Psycopg is a C extension module, it is not possible for coroutine
3233
385
libraries to patch it: Psycopg instead enables cooperative multithreading by
3234
386
allowing the registration of a *wait callback* using the
3235
387
`psycopg2.extensions.set_wait_callback()` function. When a wait callback is
3236
388
registered, Psycopg will use `libpq non-blocking calls`__ instead of the regular
3237
389
blocking ones, and will delegate to the callback the responsibility to wait
3238
390
for the socket to become readable or writable.
3239
391
3240
392
Working this way, the caller does not have the complete freedom to schedule the
3241
393
socket check whenever they want as with an :ref:`asynchronous connection
3242
394
<async-support>`, but has the advantage of maintaining a complete |DBAPI|
3243
395
semantics: from the point of view of the end user, all Psycopg functions and
3244
396
objects will work transparently in the coroutine environment (blocking the
3245
397
calling green thread and giving other green threads the possibility to be
3246
398
scheduled), allowing non modified code and third party libraries (such as
3247
399
SQLAlchemy_) to be used in coroutine-based programs.
3248
400
3249
401
Notice that, while I/O correctly yields control to other coroutines, each
3250
402
connection has a lock allowing a single cursor at a time to communicate with the
3251
403
backend: such lock is not *green*, so blocking against it would block the
3252
404
entire program waiting for data, not the single coroutine. Therefore,
3253
405
programmers are advised to either avoid sharing connections between coroutines
3254
406
or to use a library-friendly lock to synchronize shared connections, e.g. for
3255
407
pooling.
3256
408
3257
409
Coroutine libraries authors should provide a callback implementation (and
3258
410
probably register it) to make Psycopg as green as they want. An example
3259
411
callback (using `!select()` to block) is provided as
3260
412
`psycopg2.extras.wait_select()`: it boils down to something similar to::
3261
413
3262
414
    def wait_select(conn):
3263
415
        while 1:
3264
416
            state = conn.poll()
3265
417
            if state == extensions.POLL_OK:
3266
418
                break
3267
419
            elif state == extensions.POLL_READ:
3268
420
                select.select([conn.fileno()], [], [])
3269
421
            elif state == extensions.POLL_WRITE:
3270
422
                select.select([], [conn.fileno()], [])
3271
423
            else:
3272
424
                raise OperationalError("bad state from poll: %s" % state)
3273
425
3274
426
.. _coroutine: http://en.wikipedia.org/wiki/Coroutine
3275
427
.. _greenlet: http://pypi.python.org/pypi/greenlet
3276
428
.. _green threads: http://en.wikipedia.org/wiki/Green_threads
3277
429
.. _Eventlet: http://eventlet.net/
3278
430
.. _gevent: http://www.gevent.org/
3279
431
.. _SQLAlchemy: http://www.sqlalchemy.org/
3280
432
.. __: http://www.postgresql.org/docs/8.4/static/libpq-async.html
3281
433
3282
434
.. warning::
3283
435
    :ref:`COPY commands <copy>` are currently not supported when a wait callback
3284
436
    is registered, but they will be probably implemented in a future release.
3285
437
3286
438
    :ref:`Large objects <large-objects>` are not supported either: they are
3287
439
    not compatible with asynchronous connections.
3288
440
3289
441
3290
442
.. testcode::
3291
443
    :hide:
3292
444
3293
445
    aconn.close()
3294
446
    conn.rollback()
3295
447
    cur.execute("DROP TABLE atable")
3296
448
    conn.commit()
3297
449
    cur.close()
3298
450
    conn.close()
3299
0
451
3300
=== added file 'doc/html/_sources/connection.txt'
3301
--- doc/html/_sources/connection.txt	1970-01-01 00:00:00 +0000
3302
+++ doc/html/_sources/connection.txt	2010-07-28 20:35:51 +0000
3303
@@ -0,0 +1,365 @@
3304
1
The ``connection`` class
3305
2
========================
3306
3
3307
4
.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
3308
5
3309
6
.. testsetup::
3310
7
3311
8
    from pprint import pprint
3312
9
    import psycopg2.extensions
3313
10
3314
11
    drop_test_table('foo')
3315
12
3316
13
.. class:: connection
3317
14
3318
15
    Handles the connection to a PostgreSQL database instance. It encapsulates
3319
16
    a database session.
3320
17
3321
18
    Connections are created using the factory function
3322
19
    `~psycopg2.connect()`.
3323
20
3324
21
    Connections are thread safe and can be shared among many thread. See
3325
22
    :ref:`thread-safety` for details.
3326
23
3327
24
    .. method:: cursor([name] [, cursor_factory])
3328
25
          
3329
26
        Return a new `cursor` object using the connection.
3330
27
3331
28
        If `name` is specified, the returned cursor will be a *server
3332
29
        side* (or *named*) cursor. Otherwise the cursor will be *client side*.
3333
30
        See :ref:`server-side-cursors` for further details.
3334
31
3335
32
        The `cursor_factory` argument can be used to create non-standard
3336
33
        cursors. The class returned should be a subclass of
3337
34
        `psycopg2.extensions.cursor`. See :ref:`subclassing-cursor` for
3338
35
        details.
3339
36
3340
37
        .. extension::
3341
38
3342
39
            The `name` and `cursor_factory` parameters are Psycopg
3343
40
            extensions to the |DBAPI|.
3344
41
3345
42
3346
43
    .. index::
3347
44
        pair: Transaction; Commit
3348
45
3349
46
    .. method:: commit()
3350
47
          
3351
48
        Commit any pending transaction to the database. Psycopg can be set to
3352
49
        perform automatic commits at each operation, see
3353
50
        `~connection.set_isolation_level()`.
3354
51
        
3355
52
3356
53
    .. index::
3357
54
        pair: Transaction; Rollback
3358
55
3359
56
    .. method:: rollback()
3360
57
3361
58
        Roll back to the start of any pending transaction.  Closing a
3362
59
        connection without committing the changes first will cause an implicit
3363
60
        rollback to be performed.
3364
61
3365
62
3366
63
    .. method:: close()
3367
64
              
3368
65
        Close the connection now (rather than whenever `__del__()` is
3369
66
        called).  The connection will be unusable from this point forward; an
3370
67
        `~psycopg2.InterfaceError` will be raised if any operation is
3371
68
        attempted with the connection.  The same applies to all cursor objects
3372
69
        trying to use the connection.  Note that closing a connection without
3373
70
        committing the changes first will cause an implicit rollback to be
3374
71
        performed (unless a different isolation level has been selected: see
3375
72
        `~connection.set_isolation_level()`).
3376
73
3377
74
3378
75
    .. index::
3379
76
        single: Exceptions; In the connection class
3380
77
3381
78
    .. rubric:: Excetptions as connection class attributes
3382
79
3383
80
    The `!connection` also exposes as attributes the same exceptions
3384
81
    available in the `psycopg2` module.  See :ref:`dbapi-exceptions`.
3385
82
3386
83
3387
84
    .. extension::
3388
85
3389
86
        The above methods are the only ones defined by the |DBAPI| protocol.
3390
87
        The Psycopg connection objects exports the following additional
3391
88
        methods and attributes.
3392
89
3393
90
3394
91
    .. attribute:: closed
3395
92
3396
93
        Read-only attribute reporting whether the database connection is open
3397
94
        (0) or closed (1).
3398
95
3399
96
3400
97
    .. method:: reset
3401
98
3402
99
        Reset the connection to the default.
3403
100
3404
101
        The method rolls back an eventual pending transaction and executes the
3405
102
        PostgreSQL |RESET|_ and |SET SESSION AUTHORIZATION|__ to revert the
3406
103
        session to the default values.
3407
104
3408
105
        .. |RESET| replace:: :sql:`RESET`
3409
106
        .. _RESET: http://www.postgresql.org/docs/8.4/static/sql-reset.html
3410
107
3411
108
        .. |SET SESSION AUTHORIZATION| replace:: :sql:`SET SESSION AUTHORIZATION`
3412
109
        .. __: http://www.postgresql.org/docs/8.4/static/sql-set-session-authorization.html
3413
110
3414
111
        .. versionadded:: 2.0.12
3415
112
3416
113
3417
114
    .. attribute:: dsn
3418
115
3419
116
        Read-only string containing the connection string used by the
3420
117
        connection.
3421
118
3422
119
3423
120
    .. index::
3424
121
        pair: Transaction; Autocommit
3425
122
        pair: Transaction; Isolation level
3426
123
3427
124
    .. _autocommit:
3428
125
3429
126
    .. attribute:: isolation_level
3430
127
    .. method:: set_isolation_level(level)
3431
128
3432
129
        Read or set the `transaction isolation level`_ for the current session.
3433
130
        The level defines the different phenomena that can happen in the
3434
131
        database between concurrent transactions.
3435
132
3436
133
        The value set or read is an integer: symbolic constants are defined in
3437
134
        the module `psycopg2.extensions`: see
3438
135
        :ref:`isolation-level-constants` for the available values.
3439
136
3440
137
        The default level is :sql:`READ COMMITTED`: at this level a
3441
138
        transaction is automatically started the first time a database command
3442
139
        is executed.  If you want an *autocommit* mode, switch to
3443
140
        `~psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT` before
3444
141
        executing any command::
3445
142
3446
143
            >>> conn.set_isolation_level(psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT)
3447
144
3448
145
        See also :ref:`transactions-control`.
3449
146
3450
147
    .. index::
3451
148
        pair: Client; Encoding
3452
149
3453
150
    .. attribute:: encoding
3454
151
    .. method:: set_client_encoding(enc)
3455
152
3456
153
        Read or set the client encoding for the current session. The default
3457
154
        is the encoding defined by the database. It should be one of the
3458
155
        `characters set supported by PostgreSQL`__
3459
156
3460
157
        .. __: http://www.postgresql.org/docs/8.4/static/multibyte.html
3461
158
3462
159
3463
160
    .. index::
3464
161
        pair: Client; Logging
3465
162
3466
163
    .. attribute:: notices
3467
164
3468
165
        A list containing all the database messages sent to the client during
3469
166
        the session.
3470
167
3471
168
        .. doctest::
3472
169
            :options: NORMALIZE_WHITESPACE
3473
170
3474
171
            >>> cur.execute("CREATE TABLE foo (id serial PRIMARY KEY);")
3475
172
            >>> pprint(conn.notices)
3476
173
            ['NOTICE:  CREATE TABLE / PRIMARY KEY will create implicit index "foo_pkey" for table "foo"\n',
3477
174
             'NOTICE:  CREATE TABLE will create implicit sequence "foo_id_seq" for serial column "foo.id"\n']
3478
175
3479
176
        To avoid a leak in case excessive notices are generated, only the last
3480
177
        50 messages are kept.
3481
178
3482
179
        You can configure what messages to receive using `PostgreSQL logging
3483
180
        configuration parameters`__ such as ``log_statement``,
3484
181
        ``client_min_messages``, ``log_min_duration_statement`` etc.
3485
182
        
3486
183
        .. __: http://www.postgresql.org/docs/8.4/static/runtime-config-logging.html
3487
184
3488
185
3489
186
    .. attribute:: notifies
3490
187
3491
188
        List containing asynchronous notifications received by the session.
3492
189
3493
190
        Received notifications have the form of a 2 items tuple
3494
191
        :samp:`({pid},{name})`, where :samp:`{pid}` is the PID of the backend
3495
192
        that sent the notification and :samp:`{name}` is the signal name
3496
193
        specified in the :sql:`NOTIFY` command.
3497
194
3498
195
        For other details see :ref:`async-notify`.
3499
196
3500
197
    .. index::
3501
198
        pair: Backend; PID
3502
199
3503
200
    .. method:: get_backend_pid()
3504
201
3505
202
        Returns the process ID (PID) of the backend server process handling
3506
203
        this connection.
3507
204
3508
205
        Note that the PID belongs to a process executing on the database
3509
206
        server host, not the local host!
3510
207
3511
208
        .. seealso:: libpq docs for `PQbackendPID()`__ for details.
3512
209
3513
210
            .. __: http://www.postgresql.org/docs/8.4/static/libpq-status.html#AEN33590
3514
211
3515
212
        .. versionadded:: 2.0.8
3516
213
3517
214
3518
215
    .. index::
3519
216
        pair: Server; Parameters
3520
217
3521
218
    .. method:: get_parameter_status(parameter)
3522
219
    
3523
220
        Look up a current parameter setting of the server.
3524
221
3525
222
        Potential values for ``parameter`` are: ``server_version``,
3526
223
        ``server_encoding``, ``client_encoding``, ``is_superuser``,
3527
224
        ``session_authorization``, ``DateStyle``, ``TimeZone``,
3528
225
        ``integer_datetimes``, and ``standard_conforming_strings``.
3529
226
3530
227
        If server did not report requested parameter, return ``None``.
3531
228
3532
229
        .. seealso:: libpq docs for `PQparameterStatus()`__ for details.
3533
230
3534
231
            .. __: http://www.postgresql.org/docs/8.4/static/libpq-status.html#AEN33499
3535
232
3536
233
        .. versionadded:: 2.0.12
3537
234
3538
235
3539
236
    .. index::
3540
237
        pair: Transaction; Status
3541
238
3542
239
    .. method:: get_transaction_status()
3543
240
3544
241
        Return the current session transaction status as an integer.  Symbolic
3545
242
        constants for the values are defined in the module
3546
243
        `psycopg2.extensions`: see :ref:`transaction-status-constants`
3547
244
        for the available values.
3548
245
3549
246
        .. seealso:: libpq docs for `PQtransactionStatus()`__ for details.
3550
247
3551
248
            .. __: http://www.postgresql.org/docs/8.4/static/libpq-status.html#AEN33480
3552
249
3553
250
3554
251
    .. index::
3555
252
        pair: Protocol; Version
3556
253
3557
254
    .. attribute:: protocol_version
3558
255
3559
256
        A read-only integer representing frontend/backend protocol being used.
3560
257
        It can be 2 or 3.
3561
258
3562
259
        .. seealso:: libpq docs for `PQprotocolVersion()`__ for details.
3563
260
3564
261
            .. __: http://www.postgresql.org/docs/8.4/static/libpq-status.html#AEN33546
3565
262
3566
263
        .. versionadded:: 2.0.12
3567
264
3568
265
3569
266
    .. index::
3570
267
        pair: Server; Version
3571
268
3572
269
    .. attribute:: server_version
3573
270
3574
271
        A read-only integer representing the backend version.
3575
272
3576
273
        The number is formed by converting the major, minor, and revision
3577
274
        numbers into two-decimal-digit numbers and appending them together.
3578
275
        For example, version 8.1.5 will be returned as ``80105``.
3579
276
        
3580
277
        .. seealso:: libpq docs for `PQserverVersion()`__ for details.
3581
278
3582
279
            .. __: http://www.postgresql.org/docs/8.4/static/libpq-status.html#AEN33556
3583
280
3584
281
        .. versionadded:: 2.0.12
3585
282
3586
283
3587
284
    .. index::
3588
285
        pair: Connection; Status
3589
286
3590
287
    .. attribute:: status
3591
288
3592
289
        A read-only integer representing the status of the connection.
3593
290
        Symbolic constants for the values are defined in the module 
3594
291
        `psycopg2.extensions`: see :ref:`connection-status-constants`
3595
292
        for the available values.
3596
293
3597
294
3598
295
    .. method:: lobject([oid [, mode [, new_oid [, new_file [, lobject_factory]]]]])
3599
296
3600
297
        Return a new database large object. See :ref:`large-objects` for an
3601
298
        overview.
3602
299
3603
300
        :param oid: The OID of the object to read or write. 0 to create
3604
301
            a new large object and and have its OID assigned automatically.
3605
302
        :param mode: Access mode to the object: can be ``r``, ``w``,
3606
303
            ``rw`` or ``n`` (meaning don't open it).
3607
304
        :param new_oid: Create a new object using the specified OID. The
3608
305
            function raises `OperationalError` if the OID is already in
3609
306
            use. Default is 0, meaning assign a new one automatically.
3610
307
        :param new_file: The name of a file to be imported in the the database
3611
308
            (using the |lo_import|_ function)
3612
309
        :param lobject_factory: Subclass of
3613
310
            `~psycopg2.extensions.lobject` to be instantiated.
3614
311
        :rtype: `~psycopg2.extensions.lobject`
3615
312
3616
313
        .. |lo_import| replace:: `!lo_import()`
3617
314
        .. _lo_import: http://www.postgresql.org/docs/8.4/static/lo-interfaces.html#AEN36307
3618
315
3619
316
        .. versionadded:: 2.0.8
3620
317
3621
318
3622
319
3623
320
    .. rubric:: Methods related to asynchronous support.
3624
321
3625
322
    .. versionadded:: 2.2.0
3626
323
3627
324
    .. seealso:: :ref:`async-support` and :ref:`green-support`.
3628
325
3629
326
3630
327
    .. attribute:: async
3631
328
3632
329
        Read only attribute: 1 if the connection is asynchronous, 0 otherwse.
3633
330
3634
331
3635
332
    .. method:: poll()
3636
333
3637
334
        Used during an asynchronous connection attempt, or when a cursor is
3638
335
        executing a query on an asynchronous connection, make communication
3639
336
        proceed if it wouldn't block.
3640
337
3641
338
        Return one of the constants defined in :ref:`poll-constants`. If it
3642
339
        returns `~psycopg2.extensions.POLL_OK` then the connection has been
3643
340
        estabilished or the query results are available on the client.
3644
341
        Otherwise wait until the file descriptor returned by `fileno()` is
3645
342
        ready to read or to write, as explained in :ref:`async-support`.
3646
343
        `poll()` should be also used by the function installed by
3647
344
        `~psycopg2.extensions.set_wait_callback()` as explained in
3648
345
        :ref:`green-support`.
3649
346
3650
347
        `poll()` is also used to receive asynchronous notifications from the
3651
348
        database: see :ref:`async-notify` from further details.
3652
349
3653
350
3654
351
    .. method:: fileno()
3655
352
3656
353
        Return the file descriptor underlying the connection: useful to read
3657
354
        its status during asynchronous communication.
3658
355
3659
356
3660
357
    .. method:: isexecuting()
3661
358
3662
359
        Return `True` if the connection is executing an asynchronous operation.
3663
360
3664
361
3665
362
.. testcode::
3666
363
    :hide:
3667
364
3668
365
    conn.rollback()
3669
0
366
3670
=== added file 'doc/html/_sources/cursor.txt'
3671
--- doc/html/_sources/cursor.txt	1970-01-01 00:00:00 +0000
3672
+++ doc/html/_sources/cursor.txt	2010-07-28 20:35:51 +0000
3673
@@ -0,0 +1,473 @@
3674
1
The ``cursor`` class
3675
2
====================
3676
3
3677
4
.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
3678
5
3679
6
.. testsetup:: *
3680
7
3681
8
    from StringIO import StringIO
3682
9
    import sys
3683
10
3684
11
    create_test_table()
3685
12
3686
13
    # initial data
3687
14
    cur.executemany("INSERT INTO test (num, data) VALUES (%s, %s)",
3688
15
        [(100, "abc'def"), (None, 'dada'), (42, 'bar')])
3689
16
    conn.commit()
3690
17
3691
18
3692
19
.. class:: cursor
3693
20
3694
21
    Allows Python code to execute PostgreSQL command in a database session.
3695
22
    Cursors are created by the `connection.cursor()` method: they are
3696
23
    bound to the connection for the entire lifetime and all the commands are
3697
24
    executed in the context of the database session wrapped by the connection.
3698
25
3699
26
    Cursors created from the same connection are not isolated, i.e., any
3700
27
    changes done to the database by a cursor are immediately visible by the
3701
28
    other cursors. Cursors created from different connections can or can not
3702
29
    be isolated, depending on the connections' :ref:`isolation level
3703
30
    <transactions-control>`. See also `~connection.rollback()` and
3704
31
    `~connection.commit()` methods.
3705
32
3706
33
    Cursors are *not* thread safe: a multithread application can create
3707
34
    many cursors from the same connection and should use each cursor from
3708
35
    a single thread. See :ref:`thread-safety` for details.
3709
36
3710
37
 
3711
38
    .. attribute:: description 
3712
39
3713
40
        This read-only attribute is a sequence of 7-item sequences.  
3714
41
3715
42
        Each of these sequences contains information describing one result
3716
43
        column: 
3717
44
3718
45
        - ``name``
3719
46
        - ``type_code``
3720
47
        - ``display_size``
3721
48
        - ``internal_size``
3722
49
        - ``precision``
3723
50
        - ``scale``
3724
51
        - ``null_ok``
3725
52
3726
53
        The first two items (``name`` and ``type_code``) are always specified,
3727
54
        the other five are optional and are set to ``None`` if no meaningful
3728
55
        values can be provided.
3729
56
3730
57
        This attribute will be ``None`` for operations that do not return rows
3731
58
        or if the cursor has not had an operation invoked via the
3732
59
        |execute*|_ methods yet.
3733
60
        
3734
61
        The ``type_code`` can be interpreted by comparing it to the Type
3735
62
        Objects specified in the section :ref:`type-objects-and-constructors`.
3736
63
        It is also used to register typecasters to convert PostgreSQL types to
3737
64
        Python objects: see :ref:`type-casting-from-sql-to-python`.
3738
65
3739
66
3740
67
    .. method:: close()
3741
68
          
3742
69
        Close the cursor now (rather than whenever `!__del__()` is
3743
70
        called).  The cursor will be unusable from this point forward; an
3744
71
        `~psycopg2.InterfaceError` will be raised if any operation is
3745
72
        attempted with the cursor.
3746
73
            
3747
74
    .. attribute:: closed
3748
75
3749
76
        Read-only boolean attribute: specifies if the cursor is closed
3750
77
        (``True``) or not (``False``).
3751
78
3752
79
        .. extension::
3753
80
3754
81
            The `closed` attribute is a Psycopg extension to the
3755
82
            |DBAPI|.
3756
83
3757
84
        .. versionadded:: 2.0.7
3758
85
3759
86
3760
87
    .. attribute:: connection
3761
88
3762
89
        Read-only attribute returning a reference to the `connection`
3763
90
        object on which the cursor was created.
3764
91
3765
92
3766
93
    .. attribute:: name
3767
94
3768
95
        Read-only attribute containing the name of the cursor if it was
3769
96
        creates as named cursor by `connection.cursor()`, or ``None`` if
3770
97
        it is a client side cursor.  See :ref:`server-side-cursors`.
3771
98
3772
99
        .. extension::
3773
100
3774
101
            The `name` attribute is a Psycopg extension to the |DBAPI|.
3775
102
3776
103
3777
104
    
3778
105
    .. |execute*| replace:: `execute*()`
3779
106
3780
107
    .. _execute*:
3781
108
3782
109
    .. rubric:: Commands execution methods
3783
110
3784
111
3785
112
    .. method:: execute(operation [, parameters])
3786
113
      
3787
114
        Prepare and execute a database operation (query or command).
3788
115
3789
116
        Parameters may be provided as sequence or mapping and will be bound to
3790
117
        variables in the operation.  Variables are specified either with
3791
118
        positional (``%s``) or named (:samp:`%({name})s`) placeholders. See
3792
119
        :ref:`query-parameters`.
3793
120
        
3794
121
        The method returns `None`. If a query was executed, the returned
3795
122
        values can be retrieved using |fetch*|_ methods.
3796
123
3797
124
3798
125
    .. method:: mogrify(operation [, parameters])
3799
126
3800
127
        Return a query string after arguments binding. The string returned is
3801
128
        exactly the one that would be sent to the database running the
3802
129
        `~cursor.execute()` method or similar.
3803
130
3804
131
            >>> cur.mogrify("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
3805
132
            "INSERT INTO test (num, data) VALUES (42, E'bar')"
3806
133
3807
134
        .. extension::
3808
135
3809
136
            The `mogrify()` method is a Psycopg extension to the |DBAPI|.
3810
137
3811
138
        
3812
139
    .. method:: executemany(operation, seq_of_parameters)
3813
140
      
3814
141
        Prepare a database operation (query or command) and then execute it
3815
142
        against all parameter tuples or mappings found in the sequence
3816
143
        `seq_of_parameters`.
3817
144
        
3818
145
        The function is mostly useful for commands that update the database:
3819
146
        any result set returned by the query is discarded.
3820
147
        
3821
148
        Parameters are bounded to the query using the same rules described in
3822
149
        the `~cursor.execute()` method.
3823
150
3824
151
3825
152
    .. method:: callproc(procname [, parameters])
3826
153
            
3827
154
        Call a stored database procedure with the given name. The sequence of
3828
155
        parameters must contain one entry for each argument that the procedure
3829
156
        expects. The result of the call is returned as modified copy of the
3830
157
        input sequence. Input parameters are left untouched, output and
3831
158
        input/output parameters replaced with possibly new values.
3832
159
        
3833
160
        The procedure may also provide a result set as output. This must then
3834
161
        be made available through the standard |fetch*|_ methods.
3835
162
3836
163
3837
164
    .. method:: setinputsizes(sizes)
3838
165
      
3839
166
        This method is exposed in compliance with the |DBAPI|. It currently
3840
167
        does nothing but it is safe to call it.
3841
168
3842
169
3843
170
3844
171
    .. |fetch*| replace:: `!fetch*()`
3845
172
3846
173
    .. _fetch*:
3847
174
3848
175
    .. rubric:: Results retrieval methods
3849
176
3850
177
3851
178
    The following methods are used to read data from the database after an
3852
179
    `~cursor.execute()` call.
3853
180
3854
181
    .. _cursor-iterable:
3855
182
3856
183
    .. note::
3857
184
3858
185
        `cursor` objects are iterable, so, instead of calling
3859
186
        explicitly `~cursor.fetchone()` in a loop, the object itself can
3860
187
        be used:
3861
188
3862
189
            >>> cur.execute("SELECT * FROM test;")
3863
190
            >>> for record in cur:
3864
191
            ...     print record
3865
192
            ...
3866
193
            (1, 100, "abc'def")
3867
194
            (2, None, 'dada')
3868
195
            (3, 42, 'bar')
3869
196
3870
197
3871
198
    .. method:: fetchone()
3872
199
3873
200
        Fetch the next row of a query result set, returning a single tuple,
3874
201
        or ``None`` when no more data is available:
3875
202
3876
203
            >>> cur.execute("SELECT * FROM test WHERE id = %s", (3,))
3877
204
            >>> cur.fetchone()
3878
205
            (3, 42, 'bar')
3879
206
        
3880
207
        A `~psycopg2.ProgrammingError` is raised if the previous call
3881
208
        to |execute*|_ did not produce any result set or no call was issued
3882
209
        yet.
3883
210
3884
211
3885
212
    .. method:: fetchmany([size=cursor.arraysize])
3886
213
      
3887
214
        Fetch the next set of rows of a query result, returning a list of
3888
215
        tuples. An empty list is returned when no more rows are available.
3889
216
        
3890
217
        The number of rows to fetch per call is specified by the parameter.
3891
218
        If it is not given, the cursor's `~cursor.arraysize` determines
3892
219
        the number of rows to be fetched. The method should try to fetch as
3893
220
        many rows as indicated by the size parameter. If this is not possible
3894
221
        due to the specified number of rows not being available, fewer rows
3895
222
        may be returned:
3896
223
3897
224
            >>> cur.execute("SELECT * FROM test;")
3898
225
            >>> cur.fetchmany(2)
3899
226
            [(1, 100, "abc'def"), (2, None, 'dada')]
3900
227
            >>> cur.fetchmany(2)
3901
228
            [(3, 42, 'bar')]
3902
229
            >>> cur.fetchmany(2)
3903
230
            []
3904
231
3905
232
        A `~psycopg2.ProgrammingError` is raised if the previous call to
3906
233
        |execute*|_ did not produce any result set or no call was issued yet.
3907
234
        
3908
235
        Note there are performance considerations involved with the size
3909
236
        parameter.  For optimal performance, it is usually best to use the
3910
237
        `~cursor.arraysize` attribute.  If the size parameter is used,
3911
238
        then it is best for it to retain the same value from one
3912
239
        `fetchmany()` call to the next.
3913
240
3914
241
3915
242
    .. method:: fetchall()
3916
243
3917
244
        Fetch all (remaining) rows of a query result, returning them as a list
3918
245
        of tuples.  An empty list is returned if there is no more record to
3919
246
        fetch.
3920
247
3921
248
            >>> cur.execute("SELECT * FROM test;")
3922
249
            >>> cur.fetchall()
3923
250
            [(1, 100, "abc'def"), (2, None, 'dada'), (3, 42, 'bar')]
3924
251
3925
252
        A `~psycopg2.ProgrammingError` is raised if the previous call to
3926
253
        |execute*|_ did not produce any result set or no call was issued yet.
3927
254
3928
255
3929
256
    .. method:: scroll(value [, mode='relative'])
3930
257
3931
258
        Scroll the cursor in the result set to a new position according
3932
259
        to mode.
3933
260
3934
261
        If `mode` is ``relative`` (default), value is taken as offset to
3935
262
        the current position in the result set, if set to ``absolute``,
3936
263
        value states an absolute target position.
3937
264
3938
265
        If the scroll operation would leave the result set, a
3939
266
        `~psycopg2.ProgrammingError` is raised and the cursor position is
3940
267
        not changed.
3941
268
3942
269
        The method can be used both for client-side cursors and
3943
270
        :ref:`server-side cursors <server-side-cursors>`.
3944
271
3945
272
        .. note:: 
3946
273
3947
274
            According to the |DBAPI|_, the exception raised for a cursor out
3948
275
            of bound should have been `!IndexError`.  The best option is
3949
276
            probably to catch both exceptions in your code::
3950
277
3951
278
                try:
3952
279
                    cur.scroll(1000 * 1000)
3953
280
                except (ProgrammingError, IndexError), exc:
3954
281
                    deal_with_it(exc)
3955
282
3956
283
3957
284
    .. attribute:: arraysize
3958
285
          
3959
286
        This read/write attribute specifies the number of rows to fetch at a
3960
287
        time with `~cursor.fetchmany()`. It defaults to 1 meaning to fetch
3961
288
        a single row at a time.
3962
289
        
3963
290
3964
291
    .. attribute:: rowcount 
3965
292
          
3966
293
        This read-only attribute specifies the number of rows that the last
3967
294
        |execute*|_ produced (for :abbr:`DQL (Data Query Language)` statements
3968
295
        like :sql:`SELECT`) or affected (for 
3969
296
        :abbr:`DML (Data Manipulation Language)` statements like :sql:`UPDATE`
3970
297
        or :sql:`INSERT`).
3971
298
        
3972
299
        The attribute is -1 in case no |execute*| has been performed on
3973
300
        the cursor or the row count of the last operation if it can't be
3974
301
        determined by the interface.
3975
302
3976
303
        .. note::
3977
304
            The |DBAPI|_ interface reserves to redefine the latter case to
3978
305
            have the object return ``None`` instead of -1 in future versions
3979
306
            of the specification.
3980
307
        
3981
308
3982
309
    .. attribute:: rownumber
3983
310
3984
311
        This read-only attribute provides the current 0-based index of the
3985
312
        cursor in the result set or ``None`` if the index cannot be
3986
313
        determined.
3987
314
3988
315
        The index can be seen as index of the cursor in a sequence (the result
3989
316
        set). The next fetch operation will fetch the row indexed by
3990
317
        `rownumber` in that sequence.
3991
318
3992
319
3993
320
    .. index:: oid
3994
321
3995
322
    .. attribute:: lastrowid
3996
323
3997
324
        This read-only attribute provides the OID of the last row inserted
3998
325
        by the cursor. If the table wasn't created with OID support or the
3999
326
        last operation is not a single record insert, the attribute is set to
4000
327
        ``None``.
4001
328
4002
329
        PostgreSQL currently advices to not create OIDs on the tables and the
4003
330
        default for |CREATE-TABLE|__ is to not support them. The
4004
331
        |INSERT-RETURNING|__ syntax available from PostgreSQL 8.3 allows more
4005
332
        flexibility.
4006
333
4007
334
        .. |CREATE-TABLE| replace:: :sql:`CREATE TABLE`
4008
335
        .. __: http://www.postgresql.org/docs/8.4/static/sql-createtable.html
4009
336
4010
337
        .. |INSERT-RETURNING| replace:: :sql:`INSERT ... RETURNING`
4011
338
        .. __: http://www.postgresql.org/docs/8.4/static/sql-insert.html
4012
339
4013
340
4014
341
    .. method:: nextset()
4015
342
    
4016
343
        This method is not supported (PostgreSQL does not have multiple data
4017
344
        sets) and will raise a `~psycopg2.NotSupportedError` exception.
4018
345
4019
346
4020
347
    .. method:: setoutputsize(size [, column])
4021
348
      
4022
349
        This method is exposed in compliance with the |DBAPI|. It currently
4023
350
        does nothing but it is safe to call it.
4024
351
4025
352
4026
353
    .. attribute:: query
4027
354
4028
355
        Read-only attribute containing the body of the last query sent to the
4029
356
        backend (including bound arguments). ``None`` if no query has been
4030
357
        executed yet:
4031
358
4032
359
            >>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
4033
360
            >>> cur.query 
4034
361
            "INSERT INTO test (num, data) VALUES (42, E'bar')"
4035
362
4036
363
        .. extension::
4037
364
4038
365
            The `query` attribute is a Psycopg extension to the |DBAPI|.
4039
366
4040
367
4041
368
    .. attribute:: statusmessage
4042
369
4043
370
        Read-only attribute containing the message returned by the last
4044
371
        command:
4045
372
4046
373
            >>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
4047
374
            >>> cur.statusmessage 
4048
375
            'INSERT 0 1'
4049
376
4050
377
        .. extension::
4051
378
4052
379
            The `statusmessage` attribute is a Psycopg extension to the
4053
380
            |DBAPI|.
4054
381
4055
382
4056
383
    .. attribute:: tzinfo_factory
4057
384
4058
385
        The time zone factory used to handle data types such as
4059
386
        :sql:`TIMESTAMP WITH TIME ZONE`.  It should be a |tzinfo|_ object.
4060
387
        See also the `psycopg2.tz` module.
4061
388
4062
389
        .. |tzinfo| replace:: `!tzinfo`
4063
390
        .. _tzinfo: http://docs.python.org/library/datetime.html#tzinfo-objects
4064
391
4065
392
4066
393
    .. rubric:: COPY-related methods
4067
394
4068
395
    .. extension::
4069
396
4070
397
        The :sql:`COPY` command is a PostgreSQL extension to the SQL standard.
4071
398
        As such, its support is a Psycopg extension to the |DBAPI|.
4072
399
4073
400
    .. method:: copy_from(file, table, sep='\\t', null='\\N', columns=None)
4074
401
 
4075
402
        Read data *from* the file-like object `file` appending them to
4076
403
        the table named `table`.  `file` must have both
4077
404
        `!read()` and `!readline()` method.  See :ref:`copy` for an
4078
405
        overview.
4079
406
4080
407
        The optional argument `sep` is the columns separator and
4081
408
        `null` represents :sql:`NULL` values in the file.
4082
409
4083
410
        The `columns` argument is a sequence containing the name of the
4084
411
        fields where the read data will be entered.  Its length and column
4085
412
        type should match the content of the read file.  If not specifies, it
4086
413
        is assumed that the entire table matches the file structure.
4087
414
4088
415
            >>> f = StringIO("42\tfoo\n74\tbar\n")
4089
416
            >>> cur.copy_from(f, 'test', columns=('num', 'data'))
4090
417
            >>> cur.execute("select * from test where id > 5;")
4091
418
            >>> cur.fetchall()
4092
419
            [(6, 42, 'foo'), (7, 74, 'bar')]
4093
420
4094
421
        .. versionchanged:: 2.0.6
4095
422
            added the `columns` parameter.
4096
423
4097
424
4098
425
    .. method:: copy_to(file, table, sep='\\t', null='\\N', columns=None)
4099
426
4100
427
        Write the content of the table named `table` *to* the file-like
4101
428
        object `file`.  `file` must have a `!write()` method.
4102
429
        See :ref:`copy` for an overview.
4103
430
4104
431
        The optional argument `sep` is the columns separator and
4105
432
        `null` represents :sql:`NULL` values in the file.
4106
433
4107
434
        The `columns` argument is a sequence of field names: if not
4108
435
        ``None`` only the specified fields will be included in the dump.
4109
436
4110
437
            >>> cur.copy_to(sys.stdout, 'test', sep="|")
4111
438
            1|100|abc'def
4112
439
            2|\N|dada
4113
440
            ...
4114
441
4115
442
        .. versionchanged:: 2.0.6
4116
443
            added the `columns` parameter.
4117
444
4118
445
4119
446
    .. method:: copy_expert(sql, file [, size])
4120
447
4121
448
        Submit a user-composed :sql:`COPY` statement. The method is useful to
4122
449
        handle all the parameters that PostgreSQL makes available (see
4123
450
        |COPY|__ command documentation).
4124
451
4125
452
        `file` must be an open, readable file for :sql:`COPY FROM` or an
4126
453
        open, writeable file for :sql:`COPY TO`. The optional `size`
4127
454
        argument, when specified for a :sql:`COPY FROM` statement, will be
4128
455
        passed to `file`\ 's read method to control the read buffer
4129
456
        size.
4130
457
4131
458
            >>> cur.copy_expert("COPY test TO STDOUT WITH CSV HEADER", sys.stdout)
4132
459
            id,num,data
4133
460
            1,100,abc'def
4134
461
            2,,dada
4135
462
            ...
4136
463
4137
464
        .. |COPY| replace:: :sql:`COPY`
4138
465
        .. __: http://www.postgresql.org/docs/8.4/static/sql-copy.html
4139
466
4140
467
        .. versionadded:: 2.0.6
4141
468
4142
469
4143
470
.. testcode::
4144
471
    :hide:
4145
472
4146
473
    conn.rollback()
4147
0
474
4148
=== added file 'doc/html/_sources/errorcodes.txt'
4149
--- doc/html/_sources/errorcodes.txt	1970-01-01 00:00:00 +0000
4150
+++ doc/html/_sources/errorcodes.txt	2010-07-28 20:35:51 +0000
4151
@@ -0,0 +1,76 @@
4152
1
`psycopg2.errorcodes` -- Error codes defined by PostgreSQL
4153
2
===============================================================
4154
3
4155
4
.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
4156
5
4157
6
.. index::
4158
7
    single: Error; Codes
4159
8
4160
9
.. module:: psycopg2.errorcodes
4161
10
4162
11
.. testsetup:: *
4163
12
4164
13
    from psycopg2 import errorcodes
4165
14
4166
15
.. versionadded:: 2.0.6
4167
16
4168
17
This module contains symbolic names for all PostgreSQL error codes and error
4169
18
classes codes.  Subclasses of `~psycopg2.Error` make the PostgreSQL error
4170
19
code available in the `~psycopg2.Error.pgcode` attribute.
4171
20
4172
21
From PostgreSQL documentation:
4173
22
4174
23
    All messages emitted by the PostgreSQL server are assigned five-character
4175
24
    error codes that follow the SQL standard's conventions for :sql:`SQLSTATE`
4176
25
    codes.  Applications that need to know which error condition has occurred
4177
26
    should usually test the error code, rather than looking at the textual
4178
27
    error message.  The error codes are less likely to change across
4179
28
    PostgreSQL releases, and also are not subject to change due to
4180
29
    localization of error messages. Note that some, but not all, of the error
4181
30
    codes produced by PostgreSQL are defined by the SQL standard; some
4182
31
    additional error codes for conditions not defined by the standard have
4183
32
    been invented or borrowed from other databases.
4184
33
4185
34
    According to the standard, the first two characters of an error code
4186
35
    denote a class of errors, while the last three characters indicate a
4187
36
    specific condition within that class. Thus, an application that does not
4188
37
    recognize the specific error code can still be able to infer what to do
4189
38
    from the error class.
4190
39
4191
40
.. seealso:: `PostgreSQL Error Codes table`__
4192
41
4193
42
    .. __: http://www.postgresql.org/docs/8.4/static/errcodes-appendix.html#ERRCODES-TABLE
4194
43
4195
44
4196
45
An example of the available constants defined in the module:
4197
46
4198
47
    >>> errorcodes.CLASS_SYNTAX_ERROR_OR_ACCESS_RULE_VIOLATION
4199
48
    '42'
4200
49
    >>> errorcodes.UNDEFINED_TABLE
4201
50
    '42P01'
4202
51
4203
52
Constants representing all the error values documented by PostgreSQL versions
4204
53
between 8.1 and 8.4 are included in the module.
4205
54
4206
55
4207
56
.. autofunction:: lookup(code)
4208
57
4209
58
    .. doctest::
4210
59
4211
60
        >>> try:
4212
61
        ...     cur.execute("SELECT ouch FROM aargh;")
4213
62
        ... except Exception, e:
4214
63
        ...     pass
4215
64
        ...
4216
65
        >>> errorcodes.lookup(e.pgcode[:2])
4217
66
        'CLASS_SYNTAX_ERROR_OR_ACCESS_RULE_VIOLATION'
4218
67
        >>> errorcodes.lookup(e.pgcode)
4219
68
        'UNDEFINED_TABLE'
4220
69
4221
70
    .. versionadded:: 2.0.14
4222
71
4223
72
4224
73
.. testcode::
4225
74
    :hide:
4226
75
4227
76
    conn.rollback()
4228
0
77
4229
=== added file 'doc/html/_sources/extensions.txt'
4230
--- doc/html/_sources/extensions.txt	1970-01-01 00:00:00 +0000
4231
+++ doc/html/_sources/extensions.txt	2010-07-28 20:35:51 +0000
4232
@@ -0,0 +1,565 @@
4233
1
`psycopg2.extensions` -- Extensions to the DB API
4234
2
======================================================
4235
3
4236
4
.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
4237
5
4238
6
.. module:: psycopg2.extensions
4239
7
4240
8
.. testsetup:: *
4241
9
4242
10
    from psycopg2.extensions import AsIs, Binary, QuotedString, ISOLATION_LEVEL_AUTOCOMMIT
4243
11
4244
12
The module contains a few objects and function extending the minimum set of
4245
13
functionalities defined by the |DBAPI|_.
4246
14
4247
15
4248
16
.. class:: connection
4249
17
4250
18
    Is the class usually returned by the `~psycopg2.connect()` function.
4251
19
    It is exposed by the `extensions` module in order to allow
4252
20
    subclassing to extend its behaviour: the subclass should be passed to the
4253
21
    `!connect()` function using the `connection_factory` parameter.
4254
22
    See also :ref:`subclassing-connection`.
4255
23
4256
24
    Subclasses should have constructor signature :samp:`({dsn}, {async}=0)`.
4257
25
4258
26
    For a complete description of the class, see `connection`.
4259
27
4260
28
.. class:: cursor
4261
29
4262
30
    It is the class usually returnded by the `connection.cursor()`
4263
31
    method. It is exposed by the `extensions` module in order to allow
4264
32
    subclassing to extend its behaviour: the subclass should be passed to the
4265
33
    `!cursor()` method using the `cursor_factory` parameter. See
4266
34
    also :ref:`subclassing-cursor`.
4267
35
4268
36
    For a complete description of the class, see `cursor`.
4269
37
4270
38
.. class:: lobject(conn [, oid [, mode [, new_oid [, new_file ]]]])
4271
39
4272
40
    Wrapper for a PostgreSQL large object. See :ref:`large-objects` for an
4273
41
    overview.
4274
42
4275
43
    The class can be subclassed: see the `connection.lobject()` to know
4276
44
    how to specify a `!lobject` subclass.
4277
45
    
4278
46
    .. versionadded:: 2.0.8
4279
47
4280
48
    .. attribute:: oid
4281
49
4282
50
        Database OID of the object.
4283
51
4284
52
    .. attribute:: mode
4285
53
4286
54
        The mode the database was open (``r``, ``w``, ``rw`` or ``n``).
4287
55
4288
56
    .. method:: read(bytes=-1)
4289
57
4290
58
        Read a chunk of data from the current file position. If -1 (default)
4291
59
        read all the remaining data.
4292
60
4293
61
    .. method:: write(str)
4294
62
4295
63
        Write a string to the large object. Return the number of bytes
4296
64
        written.
4297
65
4298
66
    .. method:: export(file_name)
4299
67
4300
68
        Export the large object content to the file system.
4301
69
        
4302
70
        The method uses the efficient |lo_export|_ libpq function.
4303
71
        
4304
72
        .. |lo_export| replace:: `!lo_export()`
4305
73
        .. _lo_export: http://www.postgresql.org/docs/8.4/static/lo-interfaces.html#AEN36330
4306
74
4307
75
    .. method:: seek(offset, whence=0)
4308
76
4309
77
        Set the lobject current position.
4310
78
4311
79
    .. method:: tell()
4312
80
4313
81
        Return the lobject current position.
4314
82
4315
83
    .. method:: truncate(len=0)
4316
84
4317
85
        .. versionadded:: 2.2.0
4318
86
4319
87
        Truncate the lobject to the given size.
4320
88
4321
89
        The method will only be available if Psycopg has been built against libpq
4322
90
        from PostgreSQL 8.3 or later and can only be used with PostgreSQL servers
4323
91
        running these versions. It uses the |lo_truncate|_ libpq function.
4324
92
4325
93
        .. |lo_truncate| replace:: `!lo_truncate()`
4326
94
        .. _lo_truncate: http://www.postgresql.org/docs/8.4/static/lo-interfaces.html#AEN36420
4327
95
4328
96
    .. method:: close()
4329
97
4330
98
        Close the object.
4331
99
4332
100
    .. attribute:: closed
4333
101
4334
102
        Boolean attribute specifying if the object is closed.
4335
103
4336
104
    .. method:: unlink()
4337
105
4338
106
        Close the object and remove it from the database.
4339
107
4340
108
4341
109
.. autofunction:: set_wait_callback(f)
4342
110
4343
111
    .. versionadded:: 2.2.0
4344
112
4345
113
.. autofunction:: get_wait_callback()
4346
114
4347
115
    .. versionadded:: 2.2.0
4348
116
4349
117
4350
118
.. _sql-adaptation-objects:
4351
119
4352
120
SQL adaptation protocol objects
4353
121
-------------------------------
4354
122
4355
123
Psycopg provides a flexible system to adapt Python objects to the SQL syntax
4356
124
(inspired to the :pep:`246`), allowing serialization in PostgreSQL. See
4357
125
:ref:`adapting-new-types` for a detailed description.  The following objects
4358
126
deal with Python objects adaptation:
4359
127
4360
128
.. function:: adapt(obj)
4361
129
4362
130
    Return the SQL representation of *obj* as a string.  Raise a
4363
131
    `~psycopg2.ProgrammingError` if how to adapt the object is unknown.
4364
132
    In order to allow new objects to be adapted, register a new adapter for it
4365
133
    using the `register_adapter()` function.
4366
134
4367
135
    The function is the entry point of the adaptation mechanism: it can be
4368
136
    used to write adapters for complex objects by recursively calling
4369
137
    `!adapt()` on its components.
4370
138
4371
139
.. function:: register_adapter(class, adapter)
4372
140
4373
141
    Register a new adapter for the objects of class *class*.
4374
142
4375
143
    *adapter* should be a function taking a single argument (the object
4376
144
    to adapt) and returning an object conforming the `ISQLQuote`
4377
145
    protocol (e.g. exposing a `!getquoted()` method).  The `AsIs` is
4378
146
    often useful for this task.
4379
147
4380
148
    Once an object is registered, it can be safely used in SQL queries and by
4381
149
    the `adapt()` function.
4382
150
4383
151
.. class:: ISQLQuote(wrapped_object)
4384
152
4385
153
    Represents the SQL adaptation protocol.  Objects conforming this protocol
4386
154
    should implement a `!getquoted()` method.
4387
155
4388
156
    Adapters may subclass `!ISQLQuote`, but is not necessary: it is
4389
157
    enough to expose a `!getquoted()` method to be conforming.
4390
158
4391
159
    .. attribute:: _wrapped
4392
160
4393
161
        The wrapped object passes to the constructor
4394
162
4395
163
    .. method:: getquoted()
4396
164
4397
165
        Subclasses or other conforming objects should return a valid SQL
4398
166
        string representing the wrapped object. The `!ISQLQuote`
4399
167
        implementation does nothing.
4400
168
4401
169
.. class:: AsIs
4402
170
4403
171
    Adapter conform to the `ISQLQuote` protocol useful for objects
4404
172
    whose string representation is already valid as SQL representation.
4405
173
4406
174
    .. method:: getquoted()
4407
175
4408
176
        Return the `str()` conversion of the wrapped object.
4409
177
4410
178
            >>> AsIs(42).getquoted()
4411
179
            '42'
4412
180
4413
181
.. class:: QuotedString
4414
182
4415
183
    Adapter conform to the `ISQLQuote` protocol for string-like
4416
184
    objects.
4417
185
4418
186
    .. method:: getquoted()
4419
187
4420
188
        Return the string enclosed in single quotes.  Any single quote
4421
189
        appearing in the the string is escaped by doubling it according to SQL
4422
190
        string constants syntax.  Backslashes are escaped too.
4423
191
4424
192
            >>> QuotedString(r"O'Reilly").getquoted()
4425
193
            "'O''Reilly'"
4426
194
4427
195
.. class:: Binary
4428
196
4429
197
    Adapter conform to the `ISQLQuote` protocol for binary objects.
4430
198
4431
199
    .. method:: getquoted()
4432
200
4433
201
        Return the string enclosed in single quotes.  It performs the same
4434
202
        escaping of the `QuotedString` adapter, plus it knows how to
4435
203
        escape non-printable chars.
4436
204
4437
205
            >>> Binary("\x00\x08\x0F").getquoted()
4438
206
            "'\\\\000\\\\010\\\\017'"
4439
207
4440
208
    .. versionchanged:: 2.0.14
4441
209
        previously the adapter was not exposed by the `extensions`
4442
210
        module. In older versions it can be imported from the implementation
4443
211
        module `!psycopg2._psycopg`.
4444
212
4445
213
4446
214
4447
215
.. class:: Boolean
4448
216
           Float
4449
217
           SQL_IN
4450
218
4451
219
        Specialized adapters for builtin objects.
4452
220
4453
221
.. class:: DateFromPy
4454
222
           TimeFromPy
4455
223
           TimestampFromPy
4456
224
           IntervalFromPy
4457
225
4458
226
        Specialized adapters for Python datetime objects.
4459
227
4460
228
.. class:: DateFromMx
4461
229
           TimeFromMx
4462
230
           TimestampFromMx
4463
231
           IntervalFromMx
4464
232
4465
233
        Specialized adapters for `mx.DateTime`_ objects.
4466
234
4467
235
.. data:: adapters
4468
236
4469
237
    Dictionary of the currently registered object adapters.  Use
4470
238
    `register_adapter()` to add an adapter for a new type.
4471
239
4472
240
4473
241
4474
242
Database types casting functions
4475
243
--------------------------------
4476
244
4477
245
These functions are used to manipulate type casters to convert from PostgreSQL
4478
246
types to Python objects.  See :ref:`type-casting-from-sql-to-python` for
4479
247
details.
4480
248
4481
249
.. function:: new_type(oids, name, adapter)
4482
250
4483
251
    Create a new type caster to convert from a PostgreSQL type to a Python
4484
252
    object.  The created object must be registered using
4485
253
    `register_type()` to be used.
4486
254
4487
255
    :param oids: tuple of OIDs of the PostgreSQL type to convert.
4488
256
    :param name: the name of the new type adapter.
4489
257
    :param adapter: the adaptation function.
4490
258
4491
259
    The object OID can be read from the `cursor.description` attribute
4492
260
    or by querying from the PostgreSQL catalog.
4493
261
4494
262
    *adapter* should have signature :samp:`fun({value}, {cur})` where
4495
263
    *value* is the string representation returned by PostgreSQL and
4496
264
    *cur* is the cursor from which data are read. In case of
4497
265
    :sql:`NULL`, *value* will be ``None``. The adapter should return the
4498
266
    converted object.
4499
267
4500
268
    See :ref:`type-casting-from-sql-to-python` for an usage example.
4501
269
4502
270
4503
271
.. function:: register_type(obj [, scope])
4504
272
4505
273
    Register a type caster created using `new_type()`.
4506
274
4507
275
    If *scope* is specified, it should be a `connection` or a
4508
276
    `cursor`: the type caster will be effective only limited to the
4509
277
    specified object.  Otherwise it will be globally registered.
4510
278
4511
279
4512
280
.. data:: string_types
4513
281
4514
282
    The global register of type casters.
4515
283
4516
284
4517
285
.. index::
4518
286
    single: Encoding; Mapping
4519
287
4520
288
.. data:: encodings
4521
289
4522
290
    Mapping from `PostgreSQL encoding`__ names to `Python codec`__ names.
4523
291
    Used by Psycopg when adapting or casting unicode strings. See
4524
292
    :ref:`unicode-handling`.
4525
293
4526
294
    .. __: http://www.postgresql.org/docs/8.4/static/multibyte.html
4527
295
    .. __: http://docs.python.org/library/codecs.html#standard-encodings
4528
296
4529
297
4530
298
4531
299
.. index::
4532
300
    single: Exceptions; Additional
4533
301
4534
302
Additional exceptions
4535
303
---------------------
4536
304
4537
305
The module exports a few exceptions in addition to the :ref:`standard ones
4538
306
<dbapi-exceptions>` defined by the |DBAPI|_.
4539
307
4540
308
.. exception:: QueryCanceledError
4541
309
4542
310
    (subclasses `~psycopg2.OperationalError`)
4543
311
4544
312
    Error related to SQL query cancelation.  It can be trapped specifically to
4545
313
    detect a timeout.
4546
314
4547
315
    .. versionadded:: 2.0.7
4548
316
4549
317
4550
318
.. exception:: TransactionRollbackError
4551
319
4552
320
    (subclasses `~psycopg2.OperationalError`)
4553
321
4554
322
    Error causing transaction rollback (deadlocks, serialisation failures,
4555
323
    etc).  It can be trapped specifically to detect a deadlock.
4556
324
4557
325
    .. versionadded:: 2.0.7
4558
326
4559
327
4560
328
4561
329
.. index::
4562
330
    pair: Isolation level; Constants
4563
331
4564
332
.. _isolation-level-constants:
4565
333
4566
334
Isolation level constants
4567
335
-------------------------
4568
336
4569
337
Psycopg2 `connection` objects hold informations about the PostgreSQL
4570
338
`transaction isolation level`_.  The current transaction level can be read
4571
339
from the `~connection.isolation_level` attribute.  The default isolation
4572
340
level is :sql:`READ COMMITTED`.  A different isolation level con be set
4573
341
through the `~connection.set_isolation_level()` method.  The level can be
4574
342
set to one of the following constants:
4575
343
4576
344
.. data:: ISOLATION_LEVEL_AUTOCOMMIT
4577
345
4578
346
    No transaction is started when command are issued and no
4579
347
    `~connection.commit()` or `~connection.rollback()` is required.
4580
348
    Some PostgreSQL command such as :sql:`CREATE DATABASE` or :sql:`VACUUM`
4581
349
    can't run into a transaction: to run such command use::
4582
350
4583
351
        >>> conn.set_isolation_level(ISOLATION_LEVEL_AUTOCOMMIT)
4584
352
4585
353
    See also :ref:`transactions-control`.
4586
354
4587
355
.. data:: ISOLATION_LEVEL_READ_UNCOMMITTED
4588
356
4589
357
    The :sql:`READ UNCOMMITTED` isolation level is defined in the SQL standard
4590
358
    but not available in the |MVCC| model of PostgreSQL: it is replaced by the
4591
359
    stricter :sql:`READ COMMITTED`.
4592
360
4593
361
.. data:: ISOLATION_LEVEL_READ_COMMITTED
4594
362
4595
363
    This is the default value.  A new transaction is started at the first
4596
364
    `~cursor.execute()` command on a cursor and at each new
4597
365
    `!execute()` after a `~connection.commit()` or a
4598
366
    `~connection.rollback()`.  The transaction runs in the PostgreSQL
4599
367
    :sql:`READ COMMITTED` isolation level.
4600
368
4601
369
.. data:: ISOLATION_LEVEL_REPEATABLE_READ
4602
370
4603
371
    The :sql:`REPEATABLE READ` isolation level is defined in the SQL standard
4604
372
    but not available in the |MVCC| model of PostgreSQL: it is replaced by the
4605
373
    stricter :sql:`SERIALIZABLE`.
4606
374
4607
375
.. data:: ISOLATION_LEVEL_SERIALIZABLE
4608
376
4609
377
    Transactions are run at a :sql:`SERIALIZABLE` isolation level. This is the
4610
378
    strictest transactions isolation level, equivalent to having the
4611
379
    transactions executed serially rather than concurrently. However
4612
380
    applications using this level must be prepared to retry reansactions due
4613
381
    to serialization failures. See `serializable isolation level`_ in
4614
382
    PostgreSQL documentation.
4615
383
4616
384
4617
385
4618
386
.. index::
4619
387
    pair: Transaction status; Constants
4620
388
4621
389
.. _transaction-status-constants:
4622
390
4623
391
Transaction status constants
4624
392
----------------------------
4625
393
4626
394
These values represent the possible status of a transaction: the current value
4627
395
can be read using the `connection.get_transaction_status()` method.
4628
396
4629
397
.. data:: TRANSACTION_STATUS_IDLE
4630
398
4631
399
    The session is idle and there is no current transaction.
4632
400
4633
401
.. data:: TRANSACTION_STATUS_ACTIVE
4634
402
4635
403
    A command is currently in progress.
4636
404
4637
405
.. data:: TRANSACTION_STATUS_INTRANS
4638
406
4639
407
    The session is idle in a valid transaction block.
4640
408
4641
409
.. data:: TRANSACTION_STATUS_INERROR
4642
410
4643
411
    The session is idle in a failed transaction block.
4644
412
4645
413
.. data:: TRANSACTION_STATUS_UNKNOWN
4646
414
4647
415
    Reported if the connection with the server is bad.
4648
416
4649
417
4650
418
4651
419
.. index::
4652
420
    pair: Connection status; Constants
4653
421
4654
422
.. _connection-status-constants:
4655
423
4656
424
Connection status constants
4657
425
---------------------------
4658
426
4659
427
These values represent the possible status of a connection: the current value
4660
428
can be read from the `~connection.status` attribute.
4661
429
4662
430
It is possible to find the connection in other status than the one shown below.
4663
431
Those are the only states in which a working connection is expected to be found
4664
432
during the execution of regular Python client code: other states are for
4665
433
internal usage and Python code should not rely on them.
4666
434
4667
435
.. data:: STATUS_READY
4668
436
4669
437
    Connection established. No transaction in progress.
4670
438
4671
439
.. data:: STATUS_BEGIN
4672
440
4673
441
    Connection established. A transaction is currently in progress.
4674
442
4675
443
.. data:: STATUS_IN_TRANSACTION
4676
444
4677
445
    An alias for `STATUS_BEGIN`
4678
446
4679
447
4680
448
4681
449
.. index::
4682
450
    pair: Poll status; Constants
4683
451
4684
452
.. _poll-constants:
4685
453
4686
454
Poll constants
4687
455
--------------
4688
456
4689
457
.. versionadded:: 2.2.0
4690
458
4691
459
These values can be returned by `connection.poll()` during asynchronous
4692
460
connection and communication.  They match the values in the libpq enum
4693
461
`!PostgresPollingStatusType`.  See :ref:`async-support` and
4694
462
:ref:`green-support`.
4695
463
4696
464
.. data:: POLL_OK
4697
465
4698
466
    The data being read is available, or the file descriptor is ready for
4699
467
    writing: reading or writing will not block.
4700
468
4701
469
.. data:: POLL_READ
4702
470
4703
471
    Some data is being read from the backend, but it is not available yet on
4704
472
    the client and reading would block.  Upon receiving this value, the client
4705
473
    should wait for the connection file descriptor to be ready *for reading*.
4706
474
    For example::
4707
475
4708
476
        select.select([conn.fileno()], [], [])
4709
477
4710
478
.. data:: POLL_WRITE
4711
479
4712
480
    Some data is being sent to the backend but the connection file descriptor
4713
481
    can't currently accept new data.  Upon receiving this value, the client
4714
482
    should wait for the connection file descriptor to be ready *for writing*.
4715
483
    For example::
4716
484
4717
485
        select.select([], [conn.fileno()], [])
4718
486
4719
487
.. data:: POLL_ERROR
4720
488
4721
489
    There was a problem during connection polling. This value should actually
4722
490
    never be returned: in case of poll error usually an exception containing
4723
491
    the relevant details is raised.
4724
492
4725
493
4726
494
4727
495
Additional database types
4728
496
-------------------------
4729
497
4730
498
The `!extensions` module includes typecasters for many standard
4731
499
PostgreSQL types.  These objects allow the conversion of returned data into
4732
500
Python objects.  All the typecasters are automatically registered, except
4733
501
`UNICODE` and `UNICODEARRAY`: you can register them using
4734
502
`register_type()` in order to receive Unicode objects instead of strings
4735
503
from the database.  See :ref:`unicode-handling` for details.
4736
504
4737
505
.. data:: BOOLEAN
4738
506
          DATE
4739
507
          DECIMAL
4740
508
          FLOAT
4741
509
          INTEGER
4742
510
          INTERVAL
4743
511
          LONGINTEGER
4744
512
          TIME
4745
513
          UNICODE
4746
514
4747
515
    Typecasters for basic types. Notice that a few other ones (`~psycopg2.BINARY`,
4748
516
    `~psycopg2.DATETIME`, `~psycopg2.NUMBER`, `~psycopg2.ROWID`,
4749
517
    `~psycopg2.STRING`) are exposed by the `psycopg2` module for |DBAPI|_
4750
518
    compliance.
4751
519
4752
520
.. data:: BINARYARRAY
4753
521
          BOOLEANARRAY
4754
522
          DATEARRAY
4755
523
          DATETIMEARRAY
4756
524
          DECIMALARRAY
4757
525
          FLOATARRAY
4758
526
          INTEGERARRAY
4759
527
          INTERVALARRAY
4760
528
          LONGINTEGERARRAY
4761
529
          ROWIDARRAY
4762
530
          STRINGARRAY
4763
531
          TIMEARRAY
4764
532
          UNICODEARRAY
4765
533
4766
534
    Typecasters to convert arrays of sql types into Python lists.
4767
535
4768
536
.. data:: PYDATE
4769
537
          PYDATETIME
4770
538
          PYINTERVAL
4771
539
          PYTIME
4772
540
          PYDATEARRAY
4773
541
          PYDATETIMEARRAY
4774
542
          PYINTERVALARRAY
4775
543
          PYTIMEARRAY
4776
544
4777
545
    Typecasters to convert time-related data types to Python `!datetime`
4778
546
    objects.
4779
547
4780
548
.. data:: MXDATE
4781
549
          MXDATETIME
4782
550
          MXINTERVAL
4783
551
          MXTIME
4784
552
          MXDATEARRAY
4785
553
          MXDATETIMEARRAY
4786
554
          MXINTERVALARRAY
4787
555
          MXTIMEARRAY
4788
556
4789
557
    Typecasters to convert time-related data types to `mx.DateTime`_ objects.
4790
558
    Only available if Psycopg was compiled with `!mx` support.
4791
559
4792
560
.. versionchanged:: 2.2.0
4793
561
        previously the `DECIMAL` typecaster and the specific time-related
4794
562
        typecasters (`!PY*` and `!MX*`) were not exposed by the `extensions`
4795
563
        module. In older versions they can be imported from the implementation
4796
564
        module `!psycopg2._psycopg`.
4797
565
4798
0
566
4799
=== added file 'doc/html/_sources/extras.txt'
4800
--- doc/html/_sources/extras.txt	1970-01-01 00:00:00 +0000
4801
+++ doc/html/_sources/extras.txt	2010-07-28 20:35:51 +0000
4802
@@ -0,0 +1,165 @@
4803
1
`psycopg2.extras` -- Miscellaneous goodies for Psycopg 2
4804
2
=============================================================
4805
3
4806
4
.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
4807
5
4808
6
.. module:: psycopg2.extras
4809
7
4810
8
.. testsetup::
4811
9
4812
10
    import psycopg2.extras
4813
11
    from psycopg2.extras import Inet
4814
12
4815
13
    create_test_table()
4816
14
4817
15
This module is a generic place used to hold little helper functions and
4818
16
classes until a better place in the distribution is found.
4819
17
4820
18
4821
19
.. index::
4822
20
    pair: Cursor; Dictionary
4823
21
4824
22
.. _dict-cursor:
4825
23
4826
24
Dictionary-like cursor
4827
25
----------------------
4828
26
4829
27
The dict cursors allow to access to the retrieved records using an iterface
4830
28
similar to the Python dictionaries instead of the tuples. You can use it
4831
29
either passing `DictConnection` as `connection_factory` argument
4832
30
to the `~psycopg2.connect()` function or passing `DictCursor` as
4833
31
the `!cursor_factory` argument to the `~connection.cursor()` method
4834
32
of a regular `connection`.
4835
33
4836
34
    >>> dict_cur = conn.cursor(cursor_factory=psycopg2.extras.DictCursor)
4837
35
    >>> dict_cur.execute("INSERT INTO test (num, data) VALUES(%s, %s)",
4838
36
    ...                  (100, "abc'def"))
4839
37
    >>> dict_cur.execute("SELECT * FROM test")
4840
38
    >>> rec = dict_cur.fetchone()
4841
39
    >>> rec['id']
4842
40
    1
4843
41
    >>> rec['num']
4844
42
    100
4845
43
    >>> rec['data']
4846
44
    "abc'def"
4847
45
4848
46
The records still support indexing as the original tuple:
4849
47
4850
48
    >>> rec[2]
4851
49
    "abc'def"
4852
50
4853
51
4854
52
.. autoclass:: DictCursor
4855
53
4856
54
.. autoclass:: DictConnection
4857
55
4858
56
.. autoclass:: DictRow
4859
57
4860
58
4861
59
Real dictionary cursor
4862
60
^^^^^^^^^^^^^^^^^^^^^^
4863
61
4864
62
.. autoclass:: RealDictCursor
4865
63
4866
64
.. autoclass:: RealDictConnection
4867
65
4868
66
.. autoclass:: RealDictRow
4869
67
4870
68
4871
69
4872
70
.. index::
4873
71
    pair: Cursor; Logging
4874
72
4875
73
Logging cursor
4876
74
--------------
4877
75
4878
76
.. autoclass:: LoggingConnection
4879
77
    :members: initialize,filter
4880
78
4881
79
.. autoclass:: LoggingCursor
4882
80
4883
81
4884
82
.. autoclass:: MinTimeLoggingConnection
4885
83
    :members: initialize,filter
4886
84
4887
85
.. autoclass:: MinTimeLoggingCursor
4888
86
4889
87
4890
88
4891
89
.. index::
4892
90
    pair: UUID; Data types
4893
91
4894
92
UUID data type
4895
93
--------------
4896
94
4897
95
.. versionadded:: 2.0.9
4898
96
.. versionchanged:: 2.0.13 added UUID array support.
4899
97
4900
98
.. doctest::
4901
99
4902
100
    >>> psycopg2.extras.register_uuid()
4903
101
    <psycopg2._psycopg.type object at 0x...>
4904
102
4905
103
    >>> # Python UUID can be used in SQL queries
4906
104
    >>> import uuid
4907
105
    >>> my_uuid = uuid.UUID('{12345678-1234-5678-1234-567812345678}')
4908
106
    >>> psycopg2.extensions.adapt(my_uuid).getquoted()
4909
107
    "'12345678-1234-5678-1234-567812345678'::uuid"
4910
108
4911
109
    >>> # PostgreSQL UUID are transformed into Python UUID objects.
4912
110
    >>> cur.execute("SELECT 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11'::uuid")
4913
111
    >>> cur.fetchone()[0]
4914
112
    UUID('a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11')
4915
113
4916
114
4917
115
.. autofunction:: register_uuid
4918
116
4919
117
.. autoclass:: UUID_adapter
4920
118
4921
119
4922
120
4923
121
.. index::
4924
122
    pair: INET; Data types
4925
123
4926
124
:sql:`inet` data type
4927
125
----------------------
4928
126
4929
127
.. versionadded:: 2.0.9
4930
128
4931
129
.. doctest::
4932
130
4933
131
    >>> psycopg2.extras.register_inet()
4934
132
    <psycopg2._psycopg.type object at 0x...>
4935
133
4936
134
    >>> cur.mogrify("SELECT %s", (Inet('127.0.0.1/32'),))
4937
135
    "SELECT E'127.0.0.1/32'::inet"
4938
136
4939
137
    >>> cur.execute("SELECT '192.168.0.1/24'::inet")
4940
138
    >>> cur.fetchone()[0].addr
4941
139
    '192.168.0.1/24'
4942
140
4943
141
4944
142
.. autofunction:: register_inet()
4945
143
4946
144
.. autoclass:: Inet
4947
145
4948
146
4949
147
4950
148
.. index::
4951
149
    single: Time zones; Fractional
4952
150
4953
151
Fractional time zones
4954
152
---------------------
4955
153
4956
154
.. autofunction:: register_tstz_w_secs
4957
155
4958
156
    .. versionadded:: 2.0.9
4959
157
4960
158
.. index::
4961
159
   pair: Example; Coroutine;
4962
160
4963
161
Coroutine support
4964
162
-----------------
4965
163
4966
164
.. autofunction:: wait_select(conn)
4967
165
4968
0
166
4969
=== added file 'doc/html/_sources/faq.txt'
4970
--- doc/html/_sources/faq.txt	1970-01-01 00:00:00 +0000
4971
+++ doc/html/_sources/faq.txt	2010-07-28 20:35:51 +0000
4972
@@ -0,0 +1,139 @@
4973
1
Frequently Asked Questions
4974
2
==========================
4975
3
4976
4
.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
4977
5
4978
6
Here are a few gotchas you may encounter using `psycopg2`.  Feel free to
4979
7
suggest new entries!
4980
8
4981
9
4982
10
Problems with transactions handling
4983
11
-----------------------------------
4984
12
4985
13
.. cssclass:: faq
4986
14
4987
15
Why does `!psycopg2` leave database sessions "idle in transaction"?
4988
16
    Psycopg normally starts a new transaction the first time a query is
4989
17
    executed, e.g. calling `cursor.execute()`, even if the command is a
4990
18
    :sql:`SELECT`.  The transaction is not closed until an explicit
4991
19
    `~connection.commit()` or `~connection.rollback()`.
4992
20
4993
21
    If you are writing a long-living program, you should probably ensure to
4994
22
    call one of the transaction closing methods before leaving the connection
4995
23
    unused for a long time (which may also be a few seconds, depending on the
4996
24
    concurrency level in your database).  Alternatively you can use a
4997
25
    connection in :ref:`autocommit <autocommit>` mode to avoid a new
4998
26
    transaction to be started at the first command.
4999
27
5000
28
I receive the error *current transaction is aborted, commands ignored until end of transaction block* and can't do anything else!
Status:	Merged
Merged at revision:	14
Proposed branch:	lp:~groldster/ubuntu/maverick/psycopg2/merge-611040
Merge into:	lp:ubuntu/maverick/psycopg2
Diff against target:	35827 lines (+30180/-2336) 173 files modified ChangeLog (+131/-0) LICENSE (+29/-35) MANIFEST (+76/-6) MANIFEST.in (+6/-3) NEWS-2.0 (+586/-0) NEWS-2.2 (+39/-0) PKG-INFO (+3/-3) README (+13/-9) ZPsycopgDA/DA.py (+17/-19) ZPsycopgDA/__init__.py (+14/-16) ZPsycopgDA/db.py (+17/-19) ZPsycopgDA/pool.py (+17/-19) debian/changelog (+30/-7) debian/control (+3/-12) debian/rules (+0/-2) debian/source/format (+1/-0) doc/COPYING (+676/-0) doc/COPYING.LESSER (+165/-0) doc/Makefile (+23/-0) doc/README (+42/-0) doc/TODO (+0/-33) doc/api-screen.css (+0/-138) doc/async.txt (+0/-67) doc/extensions.rst (+0/-260) doc/html/.buildinfo (+4/-0) doc/html/_sources/advanced.txt (+450/-0) doc/html/_sources/connection.txt (+365/-0) doc/html/_sources/cursor.txt (+473/-0) doc/html/_sources/errorcodes.txt (+76/-0) doc/html/_sources/extensions.txt (+565/-0) doc/html/_sources/extras.txt (+165/-0) doc/html/_sources/faq.txt (+139/-0) doc/html/_sources/index.txt (+62/-0) doc/html/_sources/module.txt (+316/-0) doc/html/_sources/pool.txt (+62/-0) doc/html/_sources/tz.txt (+16/-0) doc/html/_sources/usage.txt (+510/-0) doc/html/_static/basic.css (+417/-0) doc/html/_static/default.css (+230/-0) doc/html/_static/doctools.js (+232/-0) doc/html/_static/jquery.js (+6240/-0) doc/html/_static/psycopg.css (+28/-0) doc/html/_static/pygments.css (+61/-0) doc/html/_static/searchtools.js (+467/-0) doc/html/advanced.html (+434/-0) doc/html/connection.html (+420/-0) doc/html/cursor.html (+534/-0) doc/html/errorcodes.html (+168/-0) doc/html/extensions.html (+743/-0) doc/html/extras.html (+354/-0) doc/html/faq.html (+231/-0) doc/html/genindex.html (+782/-0) doc/html/index.html (+178/-0) doc/html/modindex.html (+120/-0) doc/html/module.html (+414/-0) doc/html/objects.inv (+217/-0) doc/html/pool.html (+181/-0) doc/html/search.html (+97/-0) doc/html/searchindex.js (+1/-0) doc/html/tz.html (+132/-0) doc/html/usage.html (+506/-0) doc/pep-0249.txt (+1005/-0) doc/psycopg2.txt (+2820/-0) doc/src/Makefile (+99/-0) doc/src/_static/psycopg.css (+28/-0) doc/src/advanced.rst (+450/-0) doc/src/conf.py (+257/-0) doc/src/connection.rst (+365/-0) doc/src/cursor.rst (+473/-0) doc/src/errorcodes.rst (+76/-0) doc/src/extensions.rst (+565/-0) doc/src/extras.rst (+165/-0) doc/src/faq.rst (+139/-0) doc/src/index.rst (+62/-0) doc/src/module.rst (+316/-0) doc/src/pool.rst (+62/-0) doc/src/tools/lib/dbapi_extension.py (+52/-0) doc/src/tools/lib/sql_role.py (+21/-0) doc/src/tools/stitch_text.py (+56/-0) doc/src/tz.rst (+16/-0) doc/src/usage.rst (+510/-0) examples/binary.py (+11/-11) examples/copy_from.py (+0/-1) examples/copy_to.py (+0/-1) examples/cursor.py (+11/-11) examples/dict.py (+11/-11) examples/dt.py (+11/-11) examples/encoding.py (+12/-12) examples/fetch.py (+11/-12) examples/lastrowid.py (+11/-11) examples/mogrify.py (+11/-11) examples/myfirstrecipe.py (+26/-22) examples/notify.py (+15/-14) examples/simple.py (+12/-11) examples/threads.py (+11/-11) examples/typecast.py (+11/-11) examples/tz.py (+11/-11) examples/usercast.py (+11/-11) lib/__init__.py (+28/-13) lib/errorcodes.py (+103/-60) lib/extensions.py (+39/-17) lib/extras.py (+88/-44) lib/pool.py (+21/-13) lib/psycopg1.py (+19/-11) lib/tz.py (+29/-16) psycopg/adapter_asis.c (+19/-15) psycopg/adapter_asis.h (+18/-14) psycopg/adapter_binary.c (+20/-16) psycopg/adapter_binary.h (+18/-14) psycopg/adapter_datetime.c (+45/-21) psycopg/adapter_datetime.h (+18/-14) psycopg/adapter_list.c (+18/-14) psycopg/adapter_list.h (+18/-14) psycopg/adapter_mxdatetime.c (+25/-21) psycopg/adapter_mxdatetime.h (+18/-14) psycopg/adapter_pboolean.c (+18/-14) psycopg/adapter_pboolean.h (+18/-14) psycopg/adapter_pdecimal.c (+268/-0) psycopg/adapter_pdecimal.h (+58/-0) psycopg/adapter_pfloat.c (+19/-15) psycopg/adapter_pfloat.h (+18/-14) psycopg/adapter_qstring.c (+18/-14) psycopg/adapter_qstring.h (+18/-14) psycopg/config.h (+18/-14) psycopg/connection.h (+58/-19) psycopg/connection_int.c (+544/-117) psycopg/connection_type.c (+138/-31) psycopg/cursor.h (+32/-18) psycopg/cursor_int.c (+18/-14) psycopg/cursor_type.c (+46/-126) psycopg/green.c (+198/-0) psycopg/green.h (+75/-0) psycopg/lobject.h (+19/-14) psycopg/lobject_int.c (+52/-20) psycopg/lobject_type.c (+48/-14) psycopg/microprotocols.c (+21/-15) psycopg/microprotocols.h (+18/-14) psycopg/microprotocols_proto.c (+18/-14) psycopg/microprotocols_proto.h (+18/-14) psycopg/pqpath.c (+295/-150) psycopg/pqpath.h (+28/-17) psycopg/psycopg.h (+18/-14) psycopg/psycopgmodule.c (+60/-27) psycopg/python.h (+19/-14) psycopg/typecast.c (+51/-16) psycopg/typecast.h (+18/-14) psycopg/typecast_array.c (+21/-17) psycopg/typecast_basic.c (+29/-19) psycopg/typecast_binary.c (+21/-17) psycopg/typecast_binary.h (+18/-14) psycopg/typecast_datetime.c (+21/-17) psycopg/typecast_mxdatetime.c (+21/-17) psycopg/utils.c (+21/-0) psycopg2da/adapter.py (+18/-25) psycopg2da/tests.py (+19/-13) scripts/ext2html.py (+0/-169) scripts/make_errorcodes.py (+115/-0) scripts/makedocs.py (+0/-15) setup.py (+29/-22) tests/__init__.py (+23/-1) tests/bugX000.py (+1/-0) tests/bug_gc.py (+31/-0) tests/extras_dictcursor.py (+12/-11) tests/test_async.py (+410/-0) tests/test_connection.py (+29/-4) tests/test_copy.py (+104/-0) tests/test_dates.py (+128/-3) tests/test_green.py (+76/-0) tests/test_lobject.py (+68/-0) tests/test_notify.py (+100/-0) tests/test_transaction.py (+2/-0) tests/types_basic.py (+52/-18) tests/types_extras.py (+21/-11)
To merge this branch:	bzr merge lp:~groldster/ubuntu/maverick/psycopg2/merge-611040
Related bugs:	Link a bug report
Reviewer	Review Type	Date Requested	Status
Daniel Holbach (community)		2010-07-28	Approve on 2010-08-02
Review via email: mp+31203@code.launchpad.net