|
0
|
1 """MySQLdb Cursors
|
|
|
2
|
|
|
3 This module implements Cursors of various types for MySQLdb. By
|
|
|
4 default, MySQLdb uses the Cursor class.
|
|
|
5
|
|
|
6 """
|
|
|
7
|
|
|
8 import re
|
|
5
|
9 insert_values = re.compile(r"\svalues\s*(\(((?<!\\)'.*?\).*(?<!\\)?'|.)+?\))", re.IGNORECASE)
|
|
0
|
10 from _mysql_exceptions import Warning, Error, InterfaceError, DataError, \
|
|
|
11 DatabaseError, OperationalError, IntegrityError, InternalError, \
|
|
|
12 NotSupportedError, ProgrammingError
|
|
|
13
|
|
|
14
|
|
|
15 class BaseCursor(object):
|
|
|
16
|
|
|
17 """A base for Cursor classes. Useful attributes:
|
|
|
18
|
|
|
19 description
|
|
|
20 A tuple of DB API 7-tuples describing the columns in
|
|
|
21 the last executed query; see PEP-249 for details.
|
|
|
22
|
|
|
23 description_flags
|
|
|
24 Tuple of column flags for last query, one entry per column
|
|
|
25 in the result set. Values correspond to those in
|
|
|
26 MySQLdb.constants.FLAG. See MySQL documentation (C API)
|
|
|
27 for more information. Non-standard extension.
|
|
|
28
|
|
|
29 arraysize
|
|
|
30 default number of rows fetchmany() will fetch
|
|
|
31
|
|
|
32 """
|
|
|
33
|
|
|
34 from _mysql_exceptions import MySQLError, Warning, Error, InterfaceError, \
|
|
|
35 DatabaseError, DataError, OperationalError, IntegrityError, \
|
|
|
36 InternalError, ProgrammingError, NotSupportedError
|
|
4
|
37
|
|
|
38 _defer_warnings = False
|
|
|
39
|
|
0
|
40 def __init__(self, connection):
|
|
|
41 from weakref import proxy
|
|
|
42
|
|
|
43 self.connection = proxy(connection)
|
|
|
44 self.description = None
|
|
|
45 self.description_flags = None
|
|
|
46 self.rowcount = -1
|
|
|
47 self.arraysize = 1
|
|
|
48 self._executed = None
|
|
|
49 self.lastrowid = None
|
|
|
50 self.messages = []
|
|
|
51 self.errorhandler = connection.errorhandler
|
|
|
52 self._result = None
|
|
|
53 self._warnings = 0
|
|
|
54 self._info = None
|
|
|
55 self.rownumber = None
|
|
|
56
|
|
|
57 def __del__(self):
|
|
|
58 self.close()
|
|
|
59 self.errorhandler = None
|
|
|
60 self._result = None
|
|
|
61
|
|
|
62 def close(self):
|
|
|
63 """Close the cursor. No further queries will be possible."""
|
|
|
64 if not self.connection: return
|
|
|
65 while self.nextset(): pass
|
|
|
66 self.connection = None
|
|
|
67
|
|
|
68 def _check_executed(self):
|
|
|
69 if not self._executed:
|
|
|
70 self.errorhandler(self, ProgrammingError, "execute() first")
|
|
|
71
|
|
|
72 def _warning_check(self):
|
|
|
73 from warnings import warn
|
|
|
74 if self._warnings:
|
|
|
75 warnings = self._get_db().show_warnings()
|
|
|
76 if warnings:
|
|
|
77 # This is done in two loops in case
|
|
|
78 # Warnings are set to raise exceptions.
|
|
|
79 for w in warnings:
|
|
|
80 self.messages.append((self.Warning, w))
|
|
|
81 for w in warnings:
|
|
|
82 warn(w[-1], self.Warning, 3)
|
|
|
83 elif self._info:
|
|
|
84 self.messages.append((self.Warning, self._info))
|
|
|
85 warn(self._info, self.Warning, 3)
|
|
|
86
|
|
|
87 def nextset(self):
|
|
|
88 """Advance to the next result set.
|
|
|
89
|
|
|
90 Returns None if there are no more result sets.
|
|
|
91 """
|
|
|
92 if self._executed:
|
|
|
93 self.fetchall()
|
|
|
94 del self.messages[:]
|
|
|
95
|
|
|
96 db = self._get_db()
|
|
|
97 nr = db.next_result()
|
|
|
98 if nr == -1:
|
|
|
99 return None
|
|
|
100 self._do_get_result()
|
|
|
101 self._post_get_result()
|
|
|
102 self._warning_check()
|
|
|
103 return 1
|
|
|
104
|
|
|
105 def _post_get_result(self): pass
|
|
|
106
|
|
|
107 def _do_get_result(self):
|
|
|
108 db = self._get_db()
|
|
|
109 self._result = self._get_result()
|
|
|
110 self.rowcount = db.affected_rows()
|
|
|
111 self.rownumber = 0
|
|
|
112 self.description = self._result and self._result.describe() or None
|
|
|
113 self.description_flags = self._result and self._result.field_flags() or None
|
|
|
114 self.lastrowid = db.insert_id()
|
|
|
115 self._warnings = db.warning_count()
|
|
|
116 self._info = db.info()
|
|
|
117
|
|
|
118 def setinputsizes(self, *args):
|
|
|
119 """Does nothing, required by DB API."""
|
|
|
120
|
|
|
121 def setoutputsizes(self, *args):
|
|
|
122 """Does nothing, required by DB API."""
|
|
|
123
|
|
|
124 def _get_db(self):
|
|
|
125 if not self.connection:
|
|
|
126 self.errorhandler(self, ProgrammingError, "cursor closed")
|
|
|
127 return self.connection
|
|
|
128
|
|
|
129 def execute(self, query, args=None):
|
|
|
130
|
|
|
131 """Execute a query.
|
|
|
132
|
|
|
133 query -- string, query to execute on server
|
|
|
134 args -- optional sequence or mapping, parameters to use with query.
|
|
|
135
|
|
|
136 Note: If args is a sequence, then %s must be used as the
|
|
|
137 parameter placeholder in the query. If a mapping is used,
|
|
|
138 %(key)s must be used as the placeholder.
|
|
|
139
|
|
|
140 Returns long integer rows affected, if any
|
|
|
141
|
|
|
142 """
|
|
|
143 from types import ListType, TupleType
|
|
|
144 from sys import exc_info
|
|
|
145 del self.messages[:]
|
|
|
146 db = self._get_db()
|
|
|
147 charset = db.character_set_name()
|
|
4
|
148 if isinstance(query, unicode):
|
|
|
149 query = query.encode(charset)
|
|
0
|
150 if args is not None:
|
|
|
151 query = query % db.literal(args)
|
|
|
152 try:
|
|
|
153 r = self._query(query)
|
|
|
154 except TypeError, m:
|
|
|
155 if m.args[0] in ("not enough arguments for format string",
|
|
|
156 "not all arguments converted"):
|
|
|
157 self.messages.append((ProgrammingError, m.args[0]))
|
|
|
158 self.errorhandler(self, ProgrammingError, m.args[0])
|
|
|
159 else:
|
|
|
160 self.messages.append((TypeError, m))
|
|
|
161 self.errorhandler(self, TypeError, m)
|
|
|
162 except:
|
|
|
163 exc, value, tb = exc_info()
|
|
|
164 del tb
|
|
|
165 self.messages.append((exc, value))
|
|
|
166 self.errorhandler(self, exc, value)
|
|
|
167 self._executed = query
|
|
4
|
168 if not self._defer_warnings: self._warning_check()
|
|
0
|
169 return r
|
|
|
170
|
|
|
171 def executemany(self, query, args):
|
|
|
172
|
|
|
173 """Execute a multi-row query.
|
|
|
174
|
|
|
175 query -- string, query to execute on server
|
|
|
176
|
|
|
177 args
|
|
|
178
|
|
|
179 Sequence of sequences or mappings, parameters to use with
|
|
|
180 query.
|
|
|
181
|
|
|
182 Returns long integer rows affected, if any.
|
|
|
183
|
|
|
184 This method improves performance on multiple-row INSERT and
|
|
|
185 REPLACE. Otherwise it is equivalent to looping over args with
|
|
|
186 execute().
|
|
|
187
|
|
|
188 """
|
|
|
189 del self.messages[:]
|
|
|
190 db = self._get_db()
|
|
|
191 if not args: return
|
|
5
|
192 charset = db.character_set_name()
|
|
|
193 if isinstance(query, unicode): query = query.encode(charset)
|
|
0
|
194 m = insert_values.search(query)
|
|
|
195 if not m:
|
|
|
196 r = 0
|
|
|
197 for a in args:
|
|
|
198 r = r + self.execute(query, a)
|
|
|
199 return r
|
|
|
200 p = m.start(1)
|
|
5
|
201 e = m.end(1)
|
|
|
202 qv = m.group(1)
|
|
0
|
203 qargs = db.literal(args)
|
|
|
204 try:
|
|
5
|
205 q = [ qv % a for a in qargs ]
|
|
0
|
206 except TypeError, msg:
|
|
|
207 if msg.args[0] in ("not enough arguments for format string",
|
|
|
208 "not all arguments converted"):
|
|
|
209 self.messages.append((ProgrammingError, msg.args[0]))
|
|
|
210 self.errorhandler(self, ProgrammingError, msg.args[0])
|
|
|
211 else:
|
|
|
212 self.messages.append((TypeError, msg))
|
|
|
213 self.errorhandler(self, TypeError, msg)
|
|
|
214 except:
|
|
|
215 from sys import exc_info
|
|
|
216 exc, value, tb = exc_info()
|
|
|
217 del tb
|
|
|
218 self.errorhandler(self, exc, value)
|
|
5
|
219 r = self._query('\n'.join([query[:p], ',\n'.join(q), query[e:]]))
|
|
4
|
220 if not self._defer_warnings: self._warning_check()
|
|
0
|
221 return r
|
|
|
222
|
|
|
223 def callproc(self, procname, args=()):
|
|
|
224
|
|
|
225 """Execute stored procedure procname with args
|
|
|
226
|
|
|
227 procname -- string, name of procedure to execute on server
|
|
|
228
|
|
|
229 args -- Sequence of parameters to use with procedure
|
|
|
230
|
|
|
231 Returns the original args.
|
|
|
232
|
|
|
233 Compatibility warning: PEP-249 specifies that any modified
|
|
|
234 parameters must be returned. This is currently impossible
|
|
|
235 as they are only available by storing them in a server
|
|
|
236 variable and then retrieved by a query. Since stored
|
|
|
237 procedures return zero or more result sets, there is no
|
|
|
238 reliable way to get at OUT or INOUT parameters via callproc.
|
|
|
239 The server variables are named @_procname_n, where procname
|
|
|
240 is the parameter above and n is the position of the parameter
|
|
|
241 (from zero). Once all result sets generated by the procedure
|
|
|
242 have been fetched, you can issue a SELECT @_procname_0, ...
|
|
|
243 query using .execute() to get any OUT or INOUT values.
|
|
|
244
|
|
|
245 Compatibility warning: The act of calling a stored procedure
|
|
|
246 itself creates an empty result set. This appears after any
|
|
|
247 result sets generated by the procedure. This is non-standard
|
|
|
248 behavior with respect to the DB-API. Be sure to use nextset()
|
|
|
249 to advance through all result sets; otherwise you may get
|
|
|
250 disconnected.
|
|
|
251 """
|
|
|
252
|
|
|
253 from types import UnicodeType
|
|
|
254 db = self._get_db()
|
|
|
255 charset = db.character_set_name()
|
|
|
256 for index, arg in enumerate(args):
|
|
|
257 q = "SET @_%s_%d=%s" % (procname, index,
|
|
|
258 db.literal(arg))
|
|
4
|
259 if isinstance(q, unicode):
|
|
0
|
260 q = q.encode(charset)
|
|
|
261 self._query(q)
|
|
|
262 self.nextset()
|
|
|
263
|
|
|
264 q = "CALL %s(%s)" % (procname,
|
|
|
265 ','.join(['@_%s_%d' % (procname, i)
|
|
|
266 for i in range(len(args))]))
|
|
|
267 if type(q) is UnicodeType:
|
|
|
268 q = q.encode(charset)
|
|
|
269 self._query(q)
|
|
4
|
270 self._executed = q
|
|
|
271 if not self._defer_warnings: self._warning_check()
|
|
0
|
272 return args
|
|
|
273
|
|
|
274 def _do_query(self, q):
|
|
|
275 db = self._get_db()
|
|
|
276 self._last_executed = q
|
|
|
277 db.query(q)
|
|
|
278 self._do_get_result()
|
|
|
279 return self.rowcount
|
|
|
280
|
|
|
281 def _query(self, q): return self._do_query(q)
|
|
|
282
|
|
|
283 def _fetch_row(self, size=1):
|
|
|
284 if not self._result:
|
|
|
285 return ()
|
|
|
286 return self._result.fetch_row(size, self._fetch_type)
|
|
|
287
|
|
|
288 def __iter__(self):
|
|
|
289 return iter(self.fetchone, None)
|
|
|
290
|
|
|
291 Warning = Warning
|
|
|
292 Error = Error
|
|
|
293 InterfaceError = InterfaceError
|
|
|
294 DatabaseError = DatabaseError
|
|
|
295 DataError = DataError
|
|
|
296 OperationalError = OperationalError
|
|
|
297 IntegrityError = IntegrityError
|
|
|
298 InternalError = InternalError
|
|
|
299 ProgrammingError = ProgrammingError
|
|
|
300 NotSupportedError = NotSupportedError
|
|
|
301
|
|
|
302
|
|
|
303 class CursorStoreResultMixIn(object):
|
|
|
304
|
|
|
305 """This is a MixIn class which causes the entire result set to be
|
|
|
306 stored on the client side, i.e. it uses mysql_store_result(). If the
|
|
|
307 result set can be very large, consider adding a LIMIT clause to your
|
|
|
308 query, or using CursorUseResultMixIn instead."""
|
|
|
309
|
|
|
310 def _get_result(self): return self._get_db().store_result()
|
|
|
311
|
|
|
312 def _query(self, q):
|
|
|
313 rowcount = self._do_query(q)
|
|
|
314 self._post_get_result()
|
|
|
315 return rowcount
|
|
|
316
|
|
|
317 def _post_get_result(self):
|
|
|
318 self._rows = self._fetch_row(0)
|
|
|
319 self._result = None
|
|
|
320
|
|
|
321 def fetchone(self):
|
|
|
322 """Fetches a single row from the cursor. None indicates that
|
|
|
323 no more rows are available."""
|
|
|
324 self._check_executed()
|
|
|
325 if self.rownumber >= len(self._rows): return None
|
|
|
326 result = self._rows[self.rownumber]
|
|
|
327 self.rownumber = self.rownumber+1
|
|
|
328 return result
|
|
|
329
|
|
|
330 def fetchmany(self, size=None):
|
|
|
331 """Fetch up to size rows from the cursor. Result set may be smaller
|
|
|
332 than size. If size is not defined, cursor.arraysize is used."""
|
|
|
333 self._check_executed()
|
|
|
334 end = self.rownumber + (size or self.arraysize)
|
|
|
335 result = self._rows[self.rownumber:end]
|
|
|
336 self.rownumber = min(end, len(self._rows))
|
|
|
337 return result
|
|
|
338
|
|
|
339 def fetchall(self):
|
|
|
340 """Fetchs all available rows from the cursor."""
|
|
|
341 self._check_executed()
|
|
|
342 if self.rownumber:
|
|
|
343 result = self._rows[self.rownumber:]
|
|
|
344 else:
|
|
|
345 result = self._rows
|
|
|
346 self.rownumber = len(self._rows)
|
|
|
347 return result
|
|
|
348
|
|
|
349 def scroll(self, value, mode='relative'):
|
|
|
350 """Scroll the cursor in the result set to a new position according
|
|
|
351 to mode.
|
|
|
352
|
|
|
353 If mode is 'relative' (default), value is taken as offset to
|
|
|
354 the current position in the result set, if set to 'absolute',
|
|
|
355 value states an absolute target position."""
|
|
|
356 self._check_executed()
|
|
|
357 if mode == 'relative':
|
|
|
358 r = self.rownumber + value
|
|
|
359 elif mode == 'absolute':
|
|
|
360 r = value
|
|
|
361 else:
|
|
|
362 self.errorhandler(self, ProgrammingError,
|
|
|
363 "unknown scroll mode %s" % `mode`)
|
|
|
364 if r < 0 or r >= len(self._rows):
|
|
|
365 self.errorhandler(self, IndexError, "out of range")
|
|
|
366 self.rownumber = r
|
|
|
367
|
|
|
368 def __iter__(self):
|
|
|
369 self._check_executed()
|
|
|
370 result = self.rownumber and self._rows[self.rownumber:] or self._rows
|
|
|
371 return iter(result)
|
|
|
372
|
|
|
373
|
|
|
374 class CursorUseResultMixIn(object):
|
|
|
375
|
|
|
376 """This is a MixIn class which causes the result set to be stored
|
|
|
377 in the server and sent row-by-row to client side, i.e. it uses
|
|
|
378 mysql_use_result(). You MUST retrieve the entire result set and
|
|
|
379 close() the cursor before additional queries can be peformed on
|
|
|
380 the connection."""
|
|
|
381
|
|
4
|
382 _defer_warnings = True
|
|
|
383
|
|
0
|
384 def _get_result(self): return self._get_db().use_result()
|
|
|
385
|
|
|
386 def fetchone(self):
|
|
|
387 """Fetches a single row from the cursor."""
|
|
|
388 self._check_executed()
|
|
|
389 r = self._fetch_row(1)
|
|
4
|
390 if not r:
|
|
|
391 self._warning_check()
|
|
|
392 return None
|
|
0
|
393 self.rownumber = self.rownumber + 1
|
|
|
394 return r[0]
|
|
|
395
|
|
|
396 def fetchmany(self, size=None):
|
|
|
397 """Fetch up to size rows from the cursor. Result set may be smaller
|
|
|
398 than size. If size is not defined, cursor.arraysize is used."""
|
|
|
399 self._check_executed()
|
|
|
400 r = self._fetch_row(size or self.arraysize)
|
|
|
401 self.rownumber = self.rownumber + len(r)
|
|
4
|
402 if not r:
|
|
|
403 self._warning_check()
|
|
0
|
404 return r
|
|
|
405
|
|
|
406 def fetchall(self):
|
|
|
407 """Fetchs all available rows from the cursor."""
|
|
|
408 self._check_executed()
|
|
|
409 r = self._fetch_row(0)
|
|
|
410 self.rownumber = self.rownumber + len(r)
|
|
4
|
411 self._warning_check()
|
|
0
|
412 return r
|
|
|
413
|
|
|
414 def __iter__(self):
|
|
|
415 return self
|
|
|
416
|
|
|
417 def next(self):
|
|
|
418 row = self.fetchone()
|
|
|
419 if row is None:
|
|
|
420 raise StopIteration
|
|
|
421 return row
|
|
|
422
|
|
|
423
|
|
|
424 class CursorTupleRowsMixIn(object):
|
|
|
425
|
|
|
426 """This is a MixIn class that causes all rows to be returned as tuples,
|
|
|
427 which is the standard form required by DB API."""
|
|
|
428
|
|
|
429 _fetch_type = 0
|
|
|
430
|
|
|
431
|
|
|
432 class CursorDictRowsMixIn(object):
|
|
|
433
|
|
|
434 """This is a MixIn class that causes all rows to be returned as
|
|
|
435 dictionaries. This is a non-standard feature."""
|
|
|
436
|
|
|
437 _fetch_type = 1
|
|
|
438
|
|
|
439 def fetchoneDict(self):
|
|
|
440 """Fetch a single row as a dictionary. Deprecated:
|
|
|
441 Use fetchone() instead. Will be removed in 1.3."""
|
|
|
442 from warnings import warn
|
|
|
443 warn("fetchoneDict() is non-standard and will be removed in 1.3",
|
|
|
444 DeprecationWarning, 2)
|
|
|
445 return self.fetchone()
|
|
|
446
|
|
|
447 def fetchmanyDict(self, size=None):
|
|
|
448 """Fetch several rows as a list of dictionaries. Deprecated:
|
|
|
449 Use fetchmany() instead. Will be removed in 1.3."""
|
|
|
450 from warnings import warn
|
|
|
451 warn("fetchmanyDict() is non-standard and will be removed in 1.3",
|
|
|
452 DeprecationWarning, 2)
|
|
|
453 return self.fetchmany(size)
|
|
|
454
|
|
|
455 def fetchallDict(self):
|
|
|
456 """Fetch all available rows as a list of dictionaries. Deprecated:
|
|
|
457 Use fetchall() instead. Will be removed in 1.3."""
|
|
|
458 from warnings import warn
|
|
|
459 warn("fetchallDict() is non-standard and will be removed in 1.3",
|
|
|
460 DeprecationWarning, 2)
|
|
|
461 return self.fetchall()
|
|
|
462
|
|
|
463
|
|
|
464 class CursorOldDictRowsMixIn(CursorDictRowsMixIn):
|
|
|
465
|
|
|
466 """This is a MixIn class that returns rows as dictionaries with
|
|
|
467 the same key convention as the old Mysqldb (MySQLmodule). Don't
|
|
|
468 use this."""
|
|
|
469
|
|
|
470 _fetch_type = 2
|
|
|
471
|
|
|
472
|
|
|
473 class Cursor(CursorStoreResultMixIn, CursorTupleRowsMixIn,
|
|
|
474 BaseCursor):
|
|
|
475
|
|
|
476 """This is the standard Cursor class that returns rows as tuples
|
|
|
477 and stores the result set in the client."""
|
|
|
478
|
|
|
479
|
|
|
480 class DictCursor(CursorStoreResultMixIn, CursorDictRowsMixIn,
|
|
|
481 BaseCursor):
|
|
|
482
|
|
|
483 """This is a Cursor class that returns rows as dictionaries and
|
|
|
484 stores the result set in the client."""
|
|
|
485
|
|
|
486
|
|
|
487 class SSCursor(CursorUseResultMixIn, CursorTupleRowsMixIn,
|
|
|
488 BaseCursor):
|
|
|
489
|
|
|
490 """This is a Cursor class that returns rows as tuples and stores
|
|
|
491 the result set in the server."""
|
|
|
492
|
|
|
493
|
|
|
494 class SSDictCursor(CursorUseResultMixIn, CursorDictRowsMixIn,
|
|
|
495 BaseCursor):
|
|
|
496
|
|
|
497 """This is a Cursor class that returns rows as dictionaries and
|
|
|
498 stores the result set in the server."""
|
|
|
499
|
|
|
500
|
