source: branches/4.x/docs/contents/pgdb/cursor.rst @ 695

Last change on this file since 695 was 695, checked in by cito, 4 years ago

Reorganize and improve the Sphinx docs

The Sphinx HTML docs can now also serve as home page for the project.
They can be built with the mkdocs script and can then be found in the
docs/_build/html directory (this needs sphinx and the cloud_sptheme).

The "actual" core docs can be found in docs/contents. The layout has
been modified to only show these pages with the typical documentation
relbars; the other pages of the homepage use a simpler layout. The
pg and pgdb documentation has been cut in chunks and can now be found
in docs/contents/pg and docs/contents/pgdb.

File size: 7.5 KB
Line 
1pgdbCursor -- The cursor object
2===============================
3
4.. class:: pgdbCursor
5
6These objects represent a database cursor, which is used to manage the context
7of a fetch operation. Cursors created from the same connection are not
8isolated, i.e., any changes done to the database by a cursor are immediately
9visible by the other cursors. Cursors created from different connections can
10or can not be isolated, depending on the level of transaction isolation.
11The default PostgreSQL transaction isolation level is "read committed".
12
13Cursor objects respond to the following methods and attributes.
14
15Note that ``pgdbCursor`` objects also implement both the iterator and the
16context manager protocol, i.e. you can iterate over them and you can use them
17in a ``with`` statement.
18
19description -- details regarding the result columns
20---------------------------------------------------
21
22.. attribute:: pgdbCursor.description
23
24    This read-only attribute is a sequence of 7-item tuples.
25
26    Each of these tuples contains information describing one result column:
27
28    - *name*
29    - *type_code*
30    - *display_size*
31    - *internal_size*
32    - *precision*
33    - *scale*
34    - *null_ok*
35
36    Note that *display_size*, *precision*, *scale* and *null_ok*
37    are not implemented.
38
39    This attribute will be ``None`` for operations that do not return rows
40    or if the cursor has not had an operation invoked via the
41    :meth:`pgdbCursor.execute` or :meth:`pgdbCursor.executemany` method yet.
42
43rowcount -- number of rows of the result
44----------------------------------------
45
46.. attribute:: pgdbCursor.rowcount
47
48    This read-only attribute specifies the number of rows that the last
49    :meth:`pgdbCursor.execute` or :meth:`pgdbCursor.executemany` call produced
50    (for DQL statements like SELECT) or affected (for DML statements like
51    UPDATE or INSERT). The attribute is -1 in case no such method call has
52    been performed on the cursor or the rowcount of the last operation
53    cannot be determined by the interface.
54
55close -- close the cursor
56-------------------------
57
58.. method:: pgdbCursor.close()
59
60    Close the cursor now (rather than whenever it is deleted)
61
62    :rtype: None
63
64The cursor will be unusable from this point forward; an :exc:`Error`
65(or subclass) exception will be raised if any operation is attempted
66with the cursor.
67
68execute -- execute a database operation
69---------------------------------------
70
71.. method:: pgdbCursor.execute(operation, [parameters])
72
73    Prepare and execute a database operation (query or command)
74
75    :param str operation: the database operation
76    :param parameters: a sequence or mapping of parameters
77    :returns: the cursor, so you can chain commands
78
79Parameters may be provided as sequence or mapping and will be bound to
80variables in the operation. Variables are specified using Python extended
81format codes, e.g. ``" ... WHERE name=%(name)s"``.
82
83A reference to the operation will be retained by the cursor. If the same
84operation object is passed in again, then the cursor can optimize its behavior.
85This is most effective for algorithms where the same operation is used,
86but different parameters are bound to it (many times).
87
88The parameters may also be specified as list of tuples to e.g. insert multiple
89rows in a single operation, but this kind of usage is deprecated:
90:meth:`pgdbCursor.executemany` should be used instead.
91
92executemany -- execute many similar database operations
93-------------------------------------------------------
94
95.. method:: pgdbCursor.executemany(operation, [seq_of_parameters])
96
97    Prepare and execute many similar database operations (queries or commands)
98
99    :param str operation: the database operation
100    :param seq_of_parameters: a sequence or mapping of parameter tuples or mappings
101    :returns: the cursor, so you can chain commands
102
103Prepare a database operation (query or command) and then execute it against
104all parameter tuples or mappings found in the sequence *seq_of_parameters*.
105
106Parameters are bounded to the query using Python extended format codes,
107e.g. ``" ... WHERE name=%(name)s"``.
108
109fetchone -- fetch next row of the query result
110----------------------------------------------
111
112.. method:: pgdbCursor.fetchone()
113
114    Fetch the next row of a query result set
115
116    :returns: the next row of the query result set
117    :rtype: list or None
118
119Fetch the next row of a query result set, returning a single list,
120or ``None`` when no more data is available.
121
122An :exc:`Error` (or subclass) exception is raised if the previous call to
123:meth:`pgdbCursor.execute` or :meth:`pgdbCursor.executemany` did not produce
124any result set or no call was issued yet.
125
126fetchmany -- fetch next set of rows of the query result
127-------------------------------------------------------
128
129.. method:: pgdbCursor.fetchmany([size=None], [keep=False])
130
131    Fetch the next set of rows of a query result
132
133    :param size: the number of rows to be fetched
134    :type size: int or None
135    :param keep: if set to true, will keep the passed arraysize
136    :tpye keep: bool
137    :returns: the next set of rows of the query result
138    :rtype: list of lists
139
140Fetch the next set of rows of a query result, returning a list of lists.
141An empty sequence is returned when no more rows are available.
142
143The number of rows to fetch per call is specified by the *size* parameter.
144If it is not given, the cursor's :attr:`arraysize` determines the number of
145rows to be fetched. If you set the *keep* parameter to True, this is kept as
146new :attr:`arraysize`.
147
148The method tries to fetch as many rows as indicated by the *size* parameter.
149If this is not possible due to the specified number of rows not being
150available, fewer rows may be returned.
151
152An :exc:`Error` (or subclass) exception is raised if the previous call to
153:meth:`pgdbCursor.execute` or :meth:`pgdbCursor.executemany` did not produce
154any result set or no call was issued yet.
155
156Note there are performance considerations involved with the *size* parameter.
157For optimal performance, it is usually best to use the :attr:`arraysize`
158attribute. If the *size* parameter is used, then it is best for it to retain
159the same value from one :meth:`pgdbCursor.fetchmany` call to the next.
160
161fetchall -- fetch all rows of the query result
162----------------------------------------------
163
164.. method:: pgdbCursor.fetchall()
165
166    Fetch all (remaining) rows of a query result
167
168    :returns: the set of all rows of the query result
169    :rtype: list of list
170
171Fetch all (remaining) rows of a query result, returning them as list of lists.
172Note that the cursor's :attr:`arraysize` attribute can affect the performance
173of this operation.
174
175row_factory -- process a row of the query result
176------------------------------------------------
177
178.. method:: pgdbCursor.row_factory(row)
179
180    Process rows before they are returned
181
182    :param list row: the currently processed row of the result set
183    :returns: the transformed row that the cursor methods shall return
184
185.. note::
186
187    This method is not part of the DB-API 2 standard.
188
189You can overwrite this method with a custom row factory, e.g.
190if you want to return rows as dicts instead of lists::
191
192    class DictCursor(pgdb.pgdbCursor):
193
194        def row_factory(self, row):
195            return dict((d[0], v) for d, v in zip(self.description, row))
196
197    cur = DictCursor(con)
198
199arraysize - the number of rows to fetch at a time
200-------------------------------------------------
201
202.. attribute:: pgdbCursor.arraysize
203
204    The number of rows to fetch at a time
205
206This read/write attribute specifies the number of rows to fetch at a time with
207:meth:`pgdbCursor.fetchmany`. It defaults to 1 meaning to fetch a single row
208at a time.
Note: See TracBrowser for help on using the repository browser.