~james-w/ubuntu/lucid/psycopg2/precise-backport

« back to all changes in this revision

Viewing changes to doc/html/cursor.html

  • Committer: Bazaar Package Importer
  • Author(s): Fabio Tranchitella, Jakub Wilk, Fabio Tranchitella
  • Date: 2011-06-19 18:25:53 UTC
  • mfrom: (5.1.10 sid)
  • Revision ID: james.westby@ubuntu.com-20110619182553-uye7z0g5ewab98px
Tags: 2.4.2-1
[ Jakub Wilk ]
* Add Debian Python Modules Team to Uploaders.

[ Fabio Tranchitella ]
* New upstream release.
* debian/watch: updated, use pypi.
* debian/control, debian/rules: switched to dh_python2.
* debian/control: bumped Standard-Version to 3.9.2, no changes required.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
 
 
2
 
1
3
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
4
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
5
 
5
7
  <head>
6
8
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
7
9
    
8
 
    <title>The cursor class &mdash; Psycopg v2.2.1 documentation</title>
 
10
    <title>The cursor class &mdash; Psycopg v2.4.2 documentation</title>
9
11
    <link rel="stylesheet" href="_static/psycopg.css" type="text/css" />
10
12
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
11
13
    <script type="text/javascript">
12
14
      var DOCUMENTATION_OPTIONS = {
13
 
        URL_ROOT:    '#',
14
 
        VERSION:     '2.2.1',
15
 
        COLLAPSE_MODINDEX: false,
 
15
        URL_ROOT:    '',
 
16
        VERSION:     '2.4.2',
 
17
        COLLAPSE_INDEX: false,
16
18
        FILE_SUFFIX: '.html',
17
19
        HAS_SOURCE:  true
18
20
      };
19
21
    </script>
20
22
    <script type="text/javascript" src="_static/jquery.js"></script>
 
23
    <script type="text/javascript" src="_static/underscore.js"></script>
21
24
    <script type="text/javascript" src="_static/doctools.js"></script>
22
 
    <link rel="top" title="Psycopg v2.2.1 documentation" href="index.html" />
 
25
    <link rel="top" title="Psycopg v2.4.2 documentation" href="index.html" />
23
26
    <link rel="next" title="More advanced topics" href="advanced.html" />
24
27
    <link rel="prev" title="The connection class" href="connection.html" /> 
25
28
  </head>
31
34
          <a href="genindex.html" title="General Index"
32
35
             accesskey="I">index</a></li>
33
36
        <li class="right" >
34
 
          <a href="modindex.html" title="Global Module Index"
35
 
             accesskey="M">modules</a> |</li>
 
37
          <a href="py-modindex.html" title="Python Module Index"
 
38
             >modules</a> |</li>
36
39
        <li class="right" >
37
40
          <a href="advanced.html" title="More advanced topics"
38
41
             accesskey="N">next</a> |</li>
39
42
        <li class="right" >
40
43
          <a href="connection.html" title="The connection class"
41
44
             accesskey="P">previous</a> |</li>
42
 
        <li><a href="index.html">Psycopg v2.2.1 documentation</a> &raquo;</li> 
 
45
        <li><a href="index.html">Psycopg v2.4.2 documentation</a> &raquo;</li> 
43
46
      </ul>
44
47
    </div>  
45
48
 
54
57
<dt id="cursor">
55
58
<em class="property">class </em><tt class="descname">cursor</tt><a class="headerlink" href="#cursor" title="Permalink to this definition">¶</a></dt>
56
59
<dd><p>Allows Python code to execute PostgreSQL command in a database session.
57
 
Cursors are created by the <a title="connection.cursor" class="reference external" href="connection.html#connection.cursor"><tt class="xref docutils literal"><span class="pre">connection.cursor()</span></tt></a> method: they are
 
60
Cursors are created by the <a class="reference internal" href="connection.html#connection.cursor" title="connection.cursor"><tt class="xref py py-obj docutils literal"><span class="pre">connection.cursor()</span></tt></a> method: they are
58
61
bound to the connection for the entire lifetime and all the commands are
59
62
executed in the context of the database session wrapped by the connection.</p>
60
63
<p>Cursors created from the same connection are not isolated, i.e., any
61
64
changes done to the database by a cursor are immediately visible by the
62
65
other cursors. Cursors created from different connections can or can not
63
 
be isolated, depending on the connections&#8217; <a class="reference external" href="usage.html#transactions-control"><em>isolation level</em></a>. See also <a title="connection.rollback" class="reference external" href="connection.html#connection.rollback"><tt class="xref docutils literal"><span class="pre">rollback()</span></tt></a> and
64
 
<a title="connection.commit" class="reference external" href="connection.html#connection.commit"><tt class="xref docutils literal"><span class="pre">commit()</span></tt></a> methods.</p>
 
66
be isolated, depending on the connections&#8217; <a class="reference internal" href="usage.html#transactions-control"><em>isolation level</em></a>. See also <a class="reference internal" href="connection.html#connection.rollback" title="connection.rollback"><tt class="xref py py-obj docutils literal"><span class="pre">rollback()</span></tt></a> and
 
67
<a class="reference internal" href="connection.html#connection.commit" title="connection.commit"><tt class="xref py py-obj docutils literal"><span class="pre">commit()</span></tt></a> methods.</p>
65
68
<p>Cursors are <em>not</em> thread safe: a multithread application can create
66
69
many cursors from the same connection and should use each cursor from
67
 
a single thread. See <a class="reference external" href="usage.html#thread-safety"><em>Thread safety</em></a> for details.</p>
 
70
a single thread. See <a class="reference internal" href="usage.html#thread-safety"><em>Thread and process safety</em></a> for details.</p>
68
71
<dl class="attribute">
69
72
<dt id="cursor.description">
70
73
<tt class="descname">description</tt><a class="headerlink" href="#cursor.description" title="Permalink to this definition">¶</a></dt>
71
74
<dd><p>This read-only attribute is a sequence of 7-item sequences.</p>
72
 
<p>Each of these sequences contains information describing one result
73
 
column:</p>
74
 
<ul class="simple">
75
 
<li><tt class="docutils literal"><span class="pre">name</span></tt></li>
76
 
<li><tt class="docutils literal"><span class="pre">type_code</span></tt></li>
77
 
<li><tt class="docutils literal"><span class="pre">display_size</span></tt></li>
78
 
<li><tt class="docutils literal"><span class="pre">internal_size</span></tt></li>
79
 
<li><tt class="docutils literal"><span class="pre">precision</span></tt></li>
80
 
<li><tt class="docutils literal"><span class="pre">scale</span></tt></li>
81
 
<li><tt class="docutils literal"><span class="pre">null_ok</span></tt></li>
82
 
</ul>
83
 
<p>The first two items (<tt class="docutils literal"><span class="pre">name</span></tt> and <tt class="docutils literal"><span class="pre">type_code</span></tt>) are always specified,
84
 
the other five are optional and are set to <tt class="xref docutils literal"><span class="pre">None</span></tt> if no meaningful
85
 
values can be provided.</p>
86
 
<p>This attribute will be <tt class="xref docutils literal"><span class="pre">None</span></tt> for operations that do not return rows
 
75
<p>Each of these sequences is a named tuple (a regular tuple if
 
76
<a class="reference external" href="http://docs.python.org/3.2/library/collections.html#collections.namedtuple" title="(in Python v3.2)"><tt class="xref py py-func docutils literal"><span class="pre">collections.namedtuple()</span></tt></a> is not available) containing information
 
77
describing one result column:</p>
 
78
<ol class="arabic simple" start="0">
 
79
<li><tt class="xref py py-obj docutils literal"><span class="pre">name</span></tt>: the name of the column returned.</li>
 
80
<li><tt class="xref py py-obj docutils literal"><span class="pre">type_code</span></tt>: the PostgreSQL OID of the column. You can use the
 
81
<a class="reference external" href="http://www.postgresql.org/docs/9.0/static/catalog-pg-type.html"><tt class="sql docutils literal"><span class="pre">pg_type</span></tt></a> system table to get more informations about the type.
 
82
This is the value used by Psycopg to decide what Python type use
 
83
to represent the value.  See also
 
84
<a class="reference internal" href="advanced.html#type-casting-from-sql-to-python"><em>Type casting of SQL types into Python objects</em></a>.</li>
 
85
<li><tt class="xref py py-obj docutils literal"><span class="pre">display_size</span></tt>: the actual length of the column in bytes.
 
86
Obtaining this value is computationally intensive, so it is
 
87
always <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> unless the <span class="target" id="index-0"></span><tt class="xref std std-envvar docutils literal"><span class="pre">PSYCOPG_DISPLAY_SIZE</span></tt> parameter
 
88
is set at compile time. See also <a class="reference external" href="http://www.postgresql.org/docs/9.0/static/libpq-exec.html#LIBPQ-PQGETLENGTH">PQgetlength</a>.</li>
 
89
<li><tt class="xref py py-obj docutils literal"><span class="pre">internal_size</span></tt>: the size in bytes of the column associated to
 
90
this column on the server. Set to a negative value for
 
91
variable-size types See also <a class="reference external" href="http://www.postgresql.org/docs/9.0/static/libpq-exec.html#LIBPQ-PQFSIZE">PQfsize</a>.</li>
 
92
<li><tt class="xref py py-obj docutils literal"><span class="pre">precision</span></tt>: total number of significant digits in columns of
 
93
type <a class="reference external" href="http://www.postgresql.org/docs/9.0/static/datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL"><tt class="sql docutils literal"><span class="pre">NUMERIC</span></tt></a>. <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> for other types.</li>
 
94
<li><tt class="xref py py-obj docutils literal"><span class="pre">scale</span></tt>: count of decimal digits in the fractional part in
 
95
columns of type <tt class="sql docutils literal"><span class="pre">NUMERIC</span></tt>. <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> for other types.</li>
 
96
<li><tt class="xref py py-obj docutils literal"><span class="pre">null_ok</span></tt>: always <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> as not easy to retrieve from the libpq.</li>
 
97
</ol>
 
98
<p>This attribute will be <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> for operations that do not return rows
87
99
or if the cursor has not had an operation invoked via the
88
 
<a class="reference internal" href="#execute"><tt class="xref docutils literal"><span class="pre">execute*()</span></tt></a> methods yet.</p>
89
 
<p>The <tt class="docutils literal"><span class="pre">type_code</span></tt> can be interpreted by comparing it to the Type
90
 
Objects specified in the section <a class="reference external" href="module.html#type-objects-and-constructors"><em>Type Objects and Constructors</em></a>.
91
 
It is also used to register typecasters to convert PostgreSQL types to
92
 
Python objects: see <a class="reference external" href="advanced.html#type-casting-from-sql-to-python"><em>Type casting of SQL types into Python objects</em></a>.</p>
 
100
<a class="reference internal" href="#execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute*()</span></tt></a> methods yet.</p>
 
101
<p class="versionchanged">
 
102
<span class="versionmodified">Changed in version 2.4: </span>if possible, columns descriptions are named tuple instead of
 
103
regular tuples.</p>
93
104
</dd></dl>
94
105
 
95
106
<dl class="method">
96
107
<dt id="cursor.close">
97
108
<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#cursor.close" title="Permalink to this definition">¶</a></dt>
98
 
<dd>Close the cursor now (rather than whenever <tt class="xref docutils literal"><span class="pre">__del__()</span></tt> is
99
 
called).  The cursor will be unusable from this point forward; an
100
 
<a title="psycopg2.InterfaceError" class="reference external" href="module.html#psycopg2.InterfaceError"><tt class="xref docutils literal"><span class="pre">InterfaceError</span></tt></a> will be raised if any operation is
101
 
attempted with the cursor.</dd></dl>
 
109
<dd><p>Close the cursor now (rather than whenever <tt class="xref py py-obj docutils literal"><span class="pre">del</span></tt> is executed).
 
110
The cursor will be unusable from this point forward; an
 
111
<a class="reference internal" href="module.html#psycopg2.InterfaceError" title="psycopg2.InterfaceError"><tt class="xref py py-obj docutils literal"><span class="pre">InterfaceError</span></tt></a> will be raised if any operation is
 
112
attempted with the cursor.</p>
 
113
</dd></dl>
102
114
 
103
115
<dl class="attribute">
104
116
<dt id="cursor.closed">
105
117
<tt class="descname">closed</tt><a class="headerlink" href="#cursor.closed" title="Permalink to this definition">¶</a></dt>
106
118
<dd><p>Read-only boolean attribute: specifies if the cursor is closed
107
 
(<tt class="xref docutils literal"><span class="pre">True</span></tt>) or not (<tt class="xref docutils literal"><span class="pre">False</span></tt>).</p>
 
119
(<tt class="xref py py-obj xref docutils literal"><span class="pre">True</span></tt>) or not (<tt class="xref py py-obj xref docutils literal"><span class="pre">False</span></tt>).</p>
108
120
<div class="admonition-db-api-extension dbapi-extension admonition ">
109
121
<p class="first admonition-title">DB API extension</p>
110
 
<p class="last">The <a title="cursor.closed" class="reference internal" href="#cursor.closed"><tt class="xref docutils literal"><span class="pre">closed</span></tt></a> attribute is a Psycopg extension to the
 
122
<p class="last">The <a class="reference internal" href="#cursor.closed" title="cursor.closed"><tt class="xref py py-obj docutils literal"><span class="pre">closed</span></tt></a> attribute is a Psycopg extension to the
111
123
DB API 2.0.</p>
112
124
</div>
113
 
<p>
 
125
<p class="versionadded">
114
126
<span class="versionmodified">New in version 2.0.7.</span></p>
115
127
</dd></dl>
116
128
 
117
129
<dl class="attribute">
118
130
<dt id="cursor.connection">
119
131
<tt class="descname">connection</tt><a class="headerlink" href="#cursor.connection" title="Permalink to this definition">¶</a></dt>
120
 
<dd>Read-only attribute returning a reference to the <a title="connection" class="reference external" href="connection.html#connection"><tt class="xref docutils literal"><span class="pre">connection</span></tt></a>
121
 
object on which the cursor was created.</dd></dl>
 
132
<dd><p>Read-only attribute returning a reference to the <a class="reference internal" href="connection.html#connection" title="connection"><tt class="xref py py-obj docutils literal"><span class="pre">connection</span></tt></a>
 
133
object on which the cursor was created.</p>
 
134
</dd></dl>
122
135
 
123
136
<dl class="attribute">
124
137
<dt id="cursor.name">
125
138
<tt class="descname">name</tt><a class="headerlink" href="#cursor.name" title="Permalink to this definition">¶</a></dt>
126
139
<dd><p>Read-only attribute containing the name of the cursor if it was
127
 
creates as named cursor by <a title="connection.cursor" class="reference external" href="connection.html#connection.cursor"><tt class="xref docutils literal"><span class="pre">connection.cursor()</span></tt></a>, or <tt class="xref docutils literal"><span class="pre">None</span></tt> if
128
 
it is a client side cursor.  See <a class="reference external" href="usage.html#server-side-cursors"><em>Server side cursors</em></a>.</p>
 
140
creates as named cursor by <a class="reference internal" href="connection.html#connection.cursor" title="connection.cursor"><tt class="xref py py-obj docutils literal"><span class="pre">connection.cursor()</span></tt></a>, or <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> if
 
141
it is a client side cursor.  See <a class="reference internal" href="usage.html#server-side-cursors"><em>Server side cursors</em></a>.</p>
129
142
<div class="admonition-db-api-extension dbapi-extension admonition ">
130
143
<p class="first admonition-title">DB API extension</p>
131
 
<p class="last">The <a title="cursor.name" class="reference internal" href="#cursor.name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a> attribute is a Psycopg extension to the DB API 2.0.</p>
 
144
<p class="last">The <a class="reference internal" href="#cursor.name" title="cursor.name"><tt class="xref py py-obj docutils literal"><span class="pre">name</span></tt></a> attribute is a Psycopg extension to the DB API 2.0.</p>
132
145
</div>
133
146
</dd></dl>
134
147
 
139
152
<dd><p>Prepare and execute a database operation (query or command).</p>
140
153
<p>Parameters may be provided as sequence or mapping and will be bound to
141
154
variables in the operation.  Variables are specified either with
142
 
positional (<tt class="docutils literal"><span class="pre">%s</span></tt>) or named (<tt class="docutils literal"><span class="pre">%(</span><em><span class="pre">name</span></em><span class="pre">)s</span></tt>) placeholders. See
143
 
<a class="reference external" href="usage.html#query-parameters"><em>Passing parameters to SQL queries</em></a>.</p>
144
 
<p>The method returns <tt class="xref xref docutils literal"><span class="pre">None</span></tt>. If a query was executed, the returned
145
 
values can be retrieved using <a class="reference internal" href="#fetch"><tt class="xref docutils literal"><span class="pre">fetch*()</span></tt></a> methods.</p>
146
 
</dd></dl>
147
 
 
148
 
<dl class="method">
149
 
<dt id="cursor.mogrify">
150
 
<tt class="descname">mogrify</tt><big>(</big><em>operation</em><span class="optional">[</span>, <em>parameters</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#cursor.mogrify" title="Permalink to this definition">¶</a></dt>
151
 
<dd><p>Return a query string after arguments binding. The string returned is
152
 
exactly the one that would be sent to the database running the
153
 
<a title="cursor.execute" class="reference internal" href="#cursor.execute"><tt class="xref docutils literal"><span class="pre">execute()</span></tt></a> method or similar.</p>
154
 
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">mogrify</span><span class="p">(</span><span class="s">&quot;INSERT INTO test (num, data) VALUES (</span><span class="si">%s</span><span class="s">, </span><span class="si">%s</span><span class="s">)&quot;</span><span class="p">,</span> <span class="p">(</span><span class="mi">42</span><span class="p">,</span> <span class="s">&#39;bar&#39;</span><span class="p">))</span>
155
 
<span class="go">&quot;INSERT INTO test (num, data) VALUES (42, E&#39;bar&#39;)&quot;</span>
156
 
</pre></div>
157
 
</div>
158
 
<div class="admonition-db-api-extension dbapi-extension admonition ">
159
 
<p class="first admonition-title">DB API extension</p>
160
 
<p class="last">The <a title="cursor.mogrify" class="reference internal" href="#cursor.mogrify"><tt class="xref docutils literal"><span class="pre">mogrify()</span></tt></a> method is a Psycopg extension to the DB API 2.0.</p>
161
 
</div>
 
155
positional (<tt class="docutils literal"><span class="pre">%s</span></tt>) or named (<tt class="samp docutils literal"><span class="pre">%(</span><em><span class="pre">name</span></em><span class="pre">)s</span></tt>) placeholders. See
 
156
<a class="reference internal" href="usage.html#query-parameters"><em>Passing parameters to SQL queries</em></a>.</p>
 
157
<p>The method returns <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt>. If a query was executed, the returned
 
158
values can be retrieved using <a class="reference internal" href="#fetch"><tt class="xref py py-obj docutils literal"><span class="pre">fetch*()</span></tt></a> methods.</p>
162
159
</dd></dl>
163
160
 
164
161
<dl class="method">
166
163
<tt class="descname">executemany</tt><big>(</big><em>operation</em>, <em>seq_of_parameters</em><big>)</big><a class="headerlink" href="#cursor.executemany" title="Permalink to this definition">¶</a></dt>
167
164
<dd><p>Prepare a database operation (query or command) and then execute it
168
165
against all parameter tuples or mappings found in the sequence
169
 
<tt class="xref docutils literal"><span class="pre">seq_of_parameters</span></tt>.</p>
 
166
<tt class="xref py py-obj docutils literal"><span class="pre">seq_of_parameters</span></tt>.</p>
170
167
<p>The function is mostly useful for commands that update the database:
171
168
any result set returned by the query is discarded.</p>
172
169
<p>Parameters are bounded to the query using the same rules described in
173
 
the <a title="cursor.execute" class="reference internal" href="#cursor.execute"><tt class="xref docutils literal"><span class="pre">execute()</span></tt></a> method.</p>
 
170
the <a class="reference internal" href="#cursor.execute" title="cursor.execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute()</span></tt></a> method.</p>
174
171
</dd></dl>
175
172
 
176
173
<dl class="method">
182
179
input sequence. Input parameters are left untouched, output and
183
180
input/output parameters replaced with possibly new values.</p>
184
181
<p>The procedure may also provide a result set as output. This must then
185
 
be made available through the standard <a class="reference internal" href="#fetch"><tt class="xref docutils literal"><span class="pre">fetch*()</span></tt></a> methods.</p>
 
182
be made available through the standard <a class="reference internal" href="#fetch"><tt class="xref py py-obj docutils literal"><span class="pre">fetch*()</span></tt></a> methods.</p>
 
183
</dd></dl>
 
184
 
 
185
<dl class="method">
 
186
<dt id="cursor.mogrify">
 
187
<tt class="descname">mogrify</tt><big>(</big><em>operation</em><span class="optional">[</span>, <em>parameters</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#cursor.mogrify" title="Permalink to this definition">¶</a></dt>
 
188
<dd><p>Return a query string after arguments binding. The string returned is
 
189
exactly the one that would be sent to the database running the
 
190
<a class="reference internal" href="#cursor.execute" title="cursor.execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute()</span></tt></a> method or similar.</p>
 
191
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">mogrify</span><span class="p">(</span><span class="s">&quot;INSERT INTO test (num, data) VALUES (</span><span class="si">%s</span><span class="s">, </span><span class="si">%s</span><span class="s">)&quot;</span><span class="p">,</span> <span class="p">(</span><span class="mi">42</span><span class="p">,</span> <span class="s">&#39;bar&#39;</span><span class="p">))</span>
 
192
<span class="go">&quot;INSERT INTO test (num, data) VALUES (42, E&#39;bar&#39;)&quot;</span>
 
193
</pre></div>
 
194
</div>
 
195
<div class="admonition-db-api-extension dbapi-extension admonition ">
 
196
<p class="first admonition-title">DB API extension</p>
 
197
<p class="last">The <a class="reference internal" href="#cursor.mogrify" title="cursor.mogrify"><tt class="xref py py-obj docutils literal"><span class="pre">mogrify()</span></tt></a> method is a Psycopg extension to the DB API 2.0.</p>
 
198
</div>
186
199
</dd></dl>
187
200
 
188
201
<dl class="method">
189
202
<dt id="cursor.setinputsizes">
190
203
<tt class="descname">setinputsizes</tt><big>(</big><em>sizes</em><big>)</big><a class="headerlink" href="#cursor.setinputsizes" title="Permalink to this definition">¶</a></dt>
191
 
<dd>This method is exposed in compliance with the DB API 2.0. It currently
192
 
does nothing but it is safe to call it.</dd></dl>
 
204
<dd><p>This method is exposed in compliance with the DB API 2.0. It currently
 
205
does nothing but it is safe to call it.</p>
 
206
</dd></dl>
193
207
 
194
208
<p class="rubric" id="fetch">Results retrieval methods</p>
195
209
<p>The following methods are used to read data from the database after an
196
 
<a title="cursor.execute" class="reference internal" href="#cursor.execute"><tt class="xref docutils literal"><span class="pre">execute()</span></tt></a> call.</p>
 
210
<a class="reference internal" href="#cursor.execute" title="cursor.execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute()</span></tt></a> call.</p>
197
211
<div class="admonition note" id="cursor-iterable">
198
212
<p class="first admonition-title">Note</p>
199
 
<p><a title="cursor" class="reference internal" href="#cursor"><tt class="xref docutils literal"><span class="pre">cursor</span></tt></a> objects are iterable, so, instead of calling
200
 
explicitly <a title="cursor.fetchone" class="reference internal" href="#cursor.fetchone"><tt class="xref docutils literal"><span class="pre">fetchone()</span></tt></a> in a loop, the object itself can
 
213
<p><a class="reference internal" href="#cursor" title="cursor"><tt class="xref py py-obj docutils literal"><span class="pre">cursor</span></tt></a> objects are iterable, so, instead of calling
 
214
explicitly <a class="reference internal" href="#cursor.fetchone" title="cursor.fetchone"><tt class="xref py py-obj docutils literal"><span class="pre">fetchone()</span></tt></a> in a loop, the object itself can
201
215
be used:</p>
202
 
<div class="last highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">&quot;SELECT * FROM test;&quot;</span><span class="p">)</span>
 
216
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">&quot;SELECT * FROM test;&quot;</span><span class="p">)</span>
203
217
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">record</span> <span class="ow">in</span> <span class="n">cur</span><span class="p">:</span>
204
218
<span class="gp">... </span>    <span class="k">print</span> <span class="n">record</span>
205
219
<span class="gp">...</span>
208
222
<span class="go">(3, 42, &#39;bar&#39;)</span>
209
223
</pre></div>
210
224
</div>
 
225
<p class="last versionchanged">
 
226
<span class="versionmodified">Changed in version 2.4: </span>iterating over a <a class="reference internal" href="usage.html#server-side-cursors"><em>named cursor</em></a>
 
227
fetches <a class="reference internal" href="#cursor.itersize" title="cursor.itersize"><tt class="xref py py-obj docutils literal"><span class="pre">itersize</span></tt></a> records at time from the backend.
 
228
Previously only one record was fetched per roundtrip, resulting
 
229
in a large overhead.</p>
211
230
</div>
212
231
<dl class="method">
213
232
<dt id="cursor.fetchone">
214
233
<tt class="descname">fetchone</tt><big>(</big><big>)</big><a class="headerlink" href="#cursor.fetchone" title="Permalink to this definition">¶</a></dt>
215
234
<dd><p>Fetch the next row of a query result set, returning a single tuple,
216
 
or <tt class="xref docutils literal"><span class="pre">None</span></tt> when no more data is available:</p>
 
235
or <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> when no more data is available:</p>
217
236
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">&quot;SELECT * FROM test WHERE id = </span><span class="si">%s</span><span class="s">&quot;</span><span class="p">,</span> <span class="p">(</span><span class="mi">3</span><span class="p">,))</span>
218
237
<span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">fetchone</span><span class="p">()</span>
219
238
<span class="go">(3, 42, &#39;bar&#39;)</span>
220
239
</pre></div>
221
240
</div>
222
 
<p>A <a title="psycopg2.ProgrammingError" class="reference external" href="module.html#psycopg2.ProgrammingError"><tt class="xref docutils literal"><span class="pre">ProgrammingError</span></tt></a> is raised if the previous call
223
 
to <a class="reference internal" href="#execute"><tt class="xref docutils literal"><span class="pre">execute*()</span></tt></a> did not produce any result set or no call was issued
 
241
<p>A <a class="reference internal" href="module.html#psycopg2.ProgrammingError" title="psycopg2.ProgrammingError"><tt class="xref py py-obj docutils literal"><span class="pre">ProgrammingError</span></tt></a> is raised if the previous call
 
242
to <a class="reference internal" href="#execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute*()</span></tt></a> did not produce any result set or no call was issued
224
243
yet.</p>
225
244
</dd></dl>
226
245
 
230
249
<dd><p>Fetch the next set of rows of a query result, returning a list of
231
250
tuples. An empty list is returned when no more rows are available.</p>
232
251
<p>The number of rows to fetch per call is specified by the parameter.
233
 
If it is not given, the cursor&#8217;s <a title="cursor.arraysize" class="reference internal" href="#cursor.arraysize"><tt class="xref docutils literal"><span class="pre">arraysize</span></tt></a> determines
 
252
If it is not given, the cursor&#8217;s <a class="reference internal" href="#cursor.arraysize" title="cursor.arraysize"><tt class="xref py py-obj docutils literal"><span class="pre">arraysize</span></tt></a> determines
234
253
the number of rows to be fetched. The method should try to fetch as
235
254
many rows as indicated by the size parameter. If this is not possible
236
255
due to the specified number of rows not being available, fewer rows
244
263
<span class="go">[]</span>
245
264
</pre></div>
246
265
</div>
247
 
<p>A <a title="psycopg2.ProgrammingError" class="reference external" href="module.html#psycopg2.ProgrammingError"><tt class="xref docutils literal"><span class="pre">ProgrammingError</span></tt></a> is raised if the previous call to
248
 
<a class="reference internal" href="#execute"><tt class="xref docutils literal"><span class="pre">execute*()</span></tt></a> did not produce any result set or no call was issued yet.</p>
 
266
<p>A <a class="reference internal" href="module.html#psycopg2.ProgrammingError" title="psycopg2.ProgrammingError"><tt class="xref py py-obj docutils literal"><span class="pre">ProgrammingError</span></tt></a> is raised if the previous call to
 
267
<a class="reference internal" href="#execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute*()</span></tt></a> did not produce any result set or no call was issued yet.</p>
249
268
<p>Note there are performance considerations involved with the size
250
269
parameter.  For optimal performance, it is usually best to use the
251
 
<a title="cursor.arraysize" class="reference internal" href="#cursor.arraysize"><tt class="xref docutils literal"><span class="pre">arraysize</span></tt></a> attribute.  If the size parameter is used,
 
270
<a class="reference internal" href="#cursor.arraysize" title="cursor.arraysize"><tt class="xref py py-obj docutils literal"><span class="pre">arraysize</span></tt></a> attribute.  If the size parameter is used,
252
271
then it is best for it to retain the same value from one
253
 
<a title="cursor.fetchmany" class="reference internal" href="#cursor.fetchmany"><tt class="xref docutils literal"><span class="pre">fetchmany()</span></tt></a> call to the next.</p>
 
272
<a class="reference internal" href="#cursor.fetchmany" title="cursor.fetchmany"><tt class="xref py py-obj docutils literal"><span class="pre">fetchmany()</span></tt></a> call to the next.</p>
254
273
</dd></dl>
255
274
 
256
275
<dl class="method">
264
283
<span class="go">[(1, 100, &quot;abc&#39;def&quot;), (2, None, &#39;dada&#39;), (3, 42, &#39;bar&#39;)]</span>
265
284
</pre></div>
266
285
</div>
267
 
<p>A <a title="psycopg2.ProgrammingError" class="reference external" href="module.html#psycopg2.ProgrammingError"><tt class="xref docutils literal"><span class="pre">ProgrammingError</span></tt></a> is raised if the previous call to
268
 
<a class="reference internal" href="#execute"><tt class="xref docutils literal"><span class="pre">execute*()</span></tt></a> did not produce any result set or no call was issued yet.</p>
 
286
<p>A <a class="reference internal" href="module.html#psycopg2.ProgrammingError" title="psycopg2.ProgrammingError"><tt class="xref py py-obj docutils literal"><span class="pre">ProgrammingError</span></tt></a> is raised if the previous call to
 
287
<a class="reference internal" href="#execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute*()</span></tt></a> did not produce any result set or no call was issued yet.</p>
269
288
</dd></dl>
270
289
 
271
290
<dl class="method">
273
292
<tt class="descname">scroll</tt><big>(</big><em>value</em><span class="optional">[</span>, <em>mode='relative'</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#cursor.scroll" title="Permalink to this definition">¶</a></dt>
274
293
<dd><p>Scroll the cursor in the result set to a new position according
275
294
to mode.</p>
276
 
<p>If <tt class="xref docutils literal"><span class="pre">mode</span></tt> is <tt class="docutils literal"><span class="pre">relative</span></tt> (default), value is taken as offset to
 
295
<p>If <tt class="xref py py-obj docutils literal"><span class="pre">mode</span></tt> is <tt class="docutils literal"><span class="pre">relative</span></tt> (default), value is taken as offset to
277
296
the current position in the result set, if set to <tt class="docutils literal"><span class="pre">absolute</span></tt>,
278
297
value states an absolute target position.</p>
279
298
<p>If the scroll operation would leave the result set, a
280
 
<a title="psycopg2.ProgrammingError" class="reference external" href="module.html#psycopg2.ProgrammingError"><tt class="xref docutils literal"><span class="pre">ProgrammingError</span></tt></a> is raised and the cursor position is
 
299
<a class="reference internal" href="module.html#psycopg2.ProgrammingError" title="psycopg2.ProgrammingError"><tt class="xref py py-obj docutils literal"><span class="pre">ProgrammingError</span></tt></a> is raised and the cursor position is
281
300
not changed.</p>
282
301
<p>The method can be used both for client-side cursors and
283
 
<a class="reference external" href="usage.html#server-side-cursors"><em>server-side cursors</em></a>.</p>
 
302
<a class="reference internal" href="usage.html#server-side-cursors"><em>server-side cursors</em></a>.</p>
284
303
<div class="admonition note">
285
304
<p class="first admonition-title">Note</p>
286
305
<p>According to the <a class="reference external" href="http://www.python.org/dev/peps/pep-0249/">DB API 2.0</a>, the exception raised for a cursor out
287
 
of bound should have been <tt class="xref docutils literal"><span class="pre">IndexError</span></tt>.  The best option is
 
306
of bound should have been <tt class="xref py py-obj docutils literal"><span class="pre">IndexError</span></tt>.  The best option is
288
307
probably to catch both exceptions in your code:</p>
289
308
<div class="last highlight-python"><div class="highlight"><pre><span class="k">try</span><span class="p">:</span>
290
309
    <span class="n">cur</span><span class="o">.</span><span class="n">scroll</span><span class="p">(</span><span class="mi">1000</span> <span class="o">*</span> <span class="mi">1000</span><span class="p">)</span>
298
317
<dl class="attribute">
299
318
<dt id="cursor.arraysize">
300
319
<tt class="descname">arraysize</tt><a class="headerlink" href="#cursor.arraysize" title="Permalink to this definition">¶</a></dt>
301
 
<dd>This read/write attribute specifies the number of rows to fetch at a
302
 
time with <a title="cursor.fetchmany" class="reference internal" href="#cursor.fetchmany"><tt class="xref docutils literal"><span class="pre">fetchmany()</span></tt></a>. It defaults to 1 meaning to fetch
303
 
a single row at a time.</dd></dl>
 
320
<dd><p>This read/write attribute specifies the number of rows to fetch at a
 
321
time with <a class="reference internal" href="#cursor.fetchmany" title="cursor.fetchmany"><tt class="xref py py-obj docutils literal"><span class="pre">fetchmany()</span></tt></a>. It defaults to 1 meaning to fetch
 
322
a single row at a time.</p>
 
323
</dd></dl>
 
324
 
 
325
<dl class="attribute">
 
326
<dt id="cursor.itersize">
 
327
<tt class="descname">itersize</tt><a class="headerlink" href="#cursor.itersize" title="Permalink to this definition">¶</a></dt>
 
328
<dd><p>Read/write attribute specifying the number of rows to fetch from the
 
329
backend at each network roundtrip during <a class="reference internal" href="#cursor-iterable"><em>iteration</em></a> on a <a class="reference internal" href="usage.html#server-side-cursors"><em>named cursor</em></a>. The
 
330
default is 2000.</p>
 
331
<p class="versionadded">
 
332
<span class="versionmodified">New in version 2.4.</span></p>
 
333
<div class="admonition-db-api-extension dbapi-extension admonition ">
 
334
<p class="first admonition-title">DB API extension</p>
 
335
<p class="last">The <a class="reference internal" href="#cursor.itersize" title="cursor.itersize"><tt class="xref py py-obj docutils literal"><span class="pre">itersize</span></tt></a> attribute is a Psycopg extension to the DB API 2.0.</p>
 
336
</div>
 
337
</dd></dl>
304
338
 
305
339
<dl class="attribute">
306
340
<dt id="cursor.rowcount">
307
341
<tt class="descname">rowcount</tt><a class="headerlink" href="#cursor.rowcount" title="Permalink to this definition">¶</a></dt>
308
342
<dd><p>This read-only attribute specifies the number of rows that the last
309
 
<a class="reference internal" href="#execute"><tt class="xref docutils literal"><span class="pre">execute*()</span></tt></a> produced (for <abbr title="Data Query Language">DQL</abbr> statements
 
343
<a class="reference internal" href="#execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute*()</span></tt></a> produced (for <abbr title="Data Query Language">DQL</abbr> statements
310
344
like <tt class="sql docutils literal"><span class="pre">SELECT</span></tt>) or affected (for
311
345
<abbr title="Data Manipulation Language">DML</abbr> statements like <tt class="sql docutils literal"><span class="pre">UPDATE</span></tt>
312
346
or <tt class="sql docutils literal"><span class="pre">INSERT</span></tt>).</p>
313
 
<p>The attribute is -1 in case no <tt class="xref docutils literal"><span class="pre">execute*()</span></tt> has been performed on
 
347
<p>The attribute is -1 in case no <tt class="xref py py-obj docutils literal"><span class="pre">execute*()</span></tt> has been performed on
314
348
the cursor or the row count of the last operation if it can&#8217;t be
315
349
determined by the interface.</p>
316
350
<div class="admonition note">
317
351
<p class="first admonition-title">Note</p>
318
352
<p class="last">The <a class="reference external" href="http://www.python.org/dev/peps/pep-0249/">DB API 2.0</a> interface reserves to redefine the latter case to
319
 
have the object return <tt class="xref docutils literal"><span class="pre">None</span></tt> instead of -1 in future versions
 
353
have the object return <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> instead of -1 in future versions
320
354
of the specification.</p>
321
355
</div>
322
356
</dd></dl>
325
359
<dt id="cursor.rownumber">
326
360
<tt class="descname">rownumber</tt><a class="headerlink" href="#cursor.rownumber" title="Permalink to this definition">¶</a></dt>
327
361
<dd><p>This read-only attribute provides the current 0-based index of the
328
 
cursor in the result set or <tt class="xref docutils literal"><span class="pre">None</span></tt> if the index cannot be
 
362
cursor in the result set or <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> if the index cannot be
329
363
determined.</p>
330
364
<p>The index can be seen as index of the cursor in a sequence (the result
331
365
set). The next fetch operation will fetch the row indexed by
332
 
<a title="cursor.rownumber" class="reference internal" href="#cursor.rownumber"><tt class="xref docutils literal"><span class="pre">rownumber</span></tt></a> in that sequence.</p>
 
366
<a class="reference internal" href="#cursor.rownumber" title="cursor.rownumber"><tt class="xref py py-obj docutils literal"><span class="pre">rownumber</span></tt></a> in that sequence.</p>
333
367
</dd></dl>
334
368
 
335
 
<span class="target" id="index-349"></span><dl class="attribute">
 
369
<span class="target" id="index-1"></span><dl class="attribute">
336
370
<dt id="cursor.lastrowid">
337
371
<tt class="descname">lastrowid</tt><a class="headerlink" href="#cursor.lastrowid" title="Permalink to this definition">¶</a></dt>
338
372
<dd><p>This read-only attribute provides the OID of the last row inserted
339
373
by the cursor. If the table wasn&#8217;t created with OID support or the
340
374
last operation is not a single record insert, the attribute is set to
341
 
<tt class="xref docutils literal"><span class="pre">None</span></tt>.</p>
342
 
<p>PostgreSQL currently advices to not create OIDs on the tables and the
343
 
default for <a class="reference external" href="http://www.postgresql.org/docs/8.4/static/sql-createtable.html"><tt class="sql docutils literal"><span class="pre">CREATE</span> <span class="pre">TABLE</span></tt></a> is to not support them. The
344
 
<a class="reference external" href="http://www.postgresql.org/docs/8.4/static/sql-insert.html"><tt class="sql docutils literal"><span class="pre">INSERT</span> <span class="pre">...</span> <span class="pre">RETURNING</span></tt></a> syntax available from PostgreSQL 8.3 allows more
345
 
flexibility.</p>
 
375
<tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt>.</p>
 
376
<div class="admonition note">
 
377
<p class="first admonition-title">Note</p>
 
378
<p class="last">PostgreSQL currently advices to not create OIDs on the tables and
 
379
the default for <a class="reference external" href="http://www.postgresql.org/docs/9.0/static/sql-createtable.html"><tt class="sql docutils literal"><span class="pre">CREATE</span> <span class="pre">TABLE</span></tt></a> is to not support them. The
 
380
<a class="reference external" href="http://www.postgresql.org/docs/9.0/static/sql-insert.html"><tt class="sql docutils literal"><span class="pre">INSERT</span> <span class="pre">...</span> <span class="pre">RETURNING</span></tt></a> syntax available from PostgreSQL 8.3 allows
 
381
more flexibility.</p>
 
382
</div>
346
383
</dd></dl>
347
384
 
348
 
<dl class="method">
349
 
<dt id="cursor.nextset">
350
 
<tt class="descname">nextset</tt><big>(</big><big>)</big><a class="headerlink" href="#cursor.nextset" title="Permalink to this definition">¶</a></dt>
351
 
<dd>This method is not supported (PostgreSQL does not have multiple data
352
 
sets) and will raise a <a title="psycopg2.NotSupportedError" class="reference external" href="module.html#psycopg2.NotSupportedError"><tt class="xref docutils literal"><span class="pre">NotSupportedError</span></tt></a> exception.</dd></dl>
353
 
 
354
 
<dl class="method">
355
 
<dt id="cursor.setoutputsize">
356
 
<tt class="descname">setoutputsize</tt><big>(</big><em>size</em><span class="optional">[</span>, <em>column</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#cursor.setoutputsize" title="Permalink to this definition">¶</a></dt>
357
 
<dd>This method is exposed in compliance with the DB API 2.0. It currently
358
 
does nothing but it is safe to call it.</dd></dl>
359
 
 
360
385
<dl class="attribute">
361
386
<dt id="cursor.query">
362
387
<tt class="descname">query</tt><a class="headerlink" href="#cursor.query" title="Permalink to this definition">¶</a></dt>
363
388
<dd><p>Read-only attribute containing the body of the last query sent to the
364
 
backend (including bound arguments). <tt class="xref docutils literal"><span class="pre">None</span></tt> if no query has been
 
389
backend (including bound arguments). <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> if no query has been
365
390
executed yet:</p>
366
391
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">&quot;INSERT INTO test (num, data) VALUES (</span><span class="si">%s</span><span class="s">, </span><span class="si">%s</span><span class="s">)&quot;</span><span class="p">,</span> <span class="p">(</span><span class="mi">42</span><span class="p">,</span> <span class="s">&#39;bar&#39;</span><span class="p">))</span>
367
392
<span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">query</span>
370
395
</div>
371
396
<div class="admonition-db-api-extension dbapi-extension admonition ">
372
397
<p class="first admonition-title">DB API extension</p>
373
 
<p class="last">The <a title="cursor.query" class="reference internal" href="#cursor.query"><tt class="xref docutils literal"><span class="pre">query</span></tt></a> attribute is a Psycopg extension to the DB API 2.0.</p>
 
398
<p class="last">The <a class="reference internal" href="#cursor.query" title="cursor.query"><tt class="xref py py-obj docutils literal"><span class="pre">query</span></tt></a> attribute is a Psycopg extension to the DB API 2.0.</p>
374
399
</div>
375
400
</dd></dl>
376
401
 
386
411
</div>
387
412
<div class="admonition-db-api-extension dbapi-extension admonition ">
388
413
<p class="first admonition-title">DB API extension</p>
389
 
<p class="last">The <a title="cursor.statusmessage" class="reference internal" href="#cursor.statusmessage"><tt class="xref docutils literal"><span class="pre">statusmessage</span></tt></a> attribute is a Psycopg extension to the
 
414
<p class="last">The <a class="reference internal" href="#cursor.statusmessage" title="cursor.statusmessage"><tt class="xref py py-obj docutils literal"><span class="pre">statusmessage</span></tt></a> attribute is a Psycopg extension to the
390
415
DB API 2.0.</p>
391
416
</div>
392
417
</dd></dl>
393
418
 
 
419
<dl class="method">
 
420
<dt id="cursor.cast">
 
421
<tt class="descname">cast</tt><big>(</big><em>oid</em>, <em>s</em><big>)</big><a class="headerlink" href="#cursor.cast" title="Permalink to this definition">¶</a></dt>
 
422
<dd><p>Convert a value from the PostgreSQL string representation to a Python
 
423
object.</p>
 
424
<p>Use the most specific of the typecasters registered by
 
425
<a class="reference internal" href="extensions.html#psycopg2.extensions.register_type" title="psycopg2.extensions.register_type"><tt class="xref py py-obj docutils literal"><span class="pre">register_type()</span></tt></a>.</p>
 
426
<p class="versionadded">
 
427
<span class="versionmodified">New in version 2.4.</span></p>
 
428
<div class="admonition-db-api-extension dbapi-extension admonition ">
 
429
<p class="first admonition-title">DB API extension</p>
 
430
<p class="last">The <a class="reference internal" href="#cursor.cast" title="cursor.cast"><tt class="xref py py-obj docutils literal"><span class="pre">cast()</span></tt></a> method is a Psycopg extension to the DB API 2.0.</p>
 
431
</div>
 
432
</dd></dl>
 
433
 
394
434
<dl class="attribute">
395
435
<dt id="cursor.tzinfo_factory">
396
436
<tt class="descname">tzinfo_factory</tt><a class="headerlink" href="#cursor.tzinfo_factory" title="Permalink to this definition">¶</a></dt>
397
 
<dd>The time zone factory used to handle data types such as
398
 
<tt class="sql docutils literal"><span class="pre">TIMESTAMP</span> <span class="pre">WITH</span> <span class="pre">TIME</span> <span class="pre">ZONE</span></tt>.  It should be a <a class="reference external" href="http://docs.python.org/library/datetime.html#tzinfo-objects"><tt class="xref docutils literal"><span class="pre">tzinfo</span></tt></a> object.
399
 
See also the <a title="" class="reference external" href="tz.html#module-psycopg2.tz"><tt class="xref docutils literal"><span class="pre">psycopg2.tz</span></tt></a> module.</dd></dl>
 
437
<dd><p>The time zone factory used to handle data types such as
 
438
<tt class="sql docutils literal"><span class="pre">TIMESTAMP</span> <span class="pre">WITH</span> <span class="pre">TIME</span> <span class="pre">ZONE</span></tt>.  It should be a <a class="reference external" href="http://docs.python.org/3.2/library/datetime.html#datetime.tzinfo" title="(in Python v3.2)"><tt class="xref py py-obj docutils literal"><span class="pre">tzinfo</span></tt></a>
 
439
object.  A few implementations are available in the <a class="reference internal" href="tz.html#module-psycopg2.tz" title="psycopg2.tz"><tt class="xref py py-obj docutils literal"><span class="pre">psycopg2.tz</span></tt></a>
 
440
module.</p>
 
441
</dd></dl>
 
442
 
 
443
<dl class="method">
 
444
<dt id="cursor.nextset">
 
445
<tt class="descname">nextset</tt><big>(</big><big>)</big><a class="headerlink" href="#cursor.nextset" title="Permalink to this definition">¶</a></dt>
 
446
<dd><p>This method is not supported (PostgreSQL does not have multiple data
 
447
sets) and will raise a <a class="reference internal" href="module.html#psycopg2.NotSupportedError" title="psycopg2.NotSupportedError"><tt class="xref py py-obj docutils literal"><span class="pre">NotSupportedError</span></tt></a> exception.</p>
 
448
</dd></dl>
 
449
 
 
450
<dl class="method">
 
451
<dt id="cursor.setoutputsize">
 
452
<tt class="descname">setoutputsize</tt><big>(</big><em>size</em><span class="optional">[</span>, <em>column</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#cursor.setoutputsize" title="Permalink to this definition">¶</a></dt>
 
453
<dd><p>This method is exposed in compliance with the DB API 2.0. It currently
 
454
does nothing but it is safe to call it.</p>
 
455
</dd></dl>
400
456
 
401
457
<p class="rubric">COPY-related methods</p>
402
458
<div class="admonition-db-api-extension dbapi-extension admonition ">
406
462
</div>
407
463
<dl class="method">
408
464
<dt id="cursor.copy_from">
409
 
<tt class="descname">copy_from</tt><big>(</big><em>file</em>, <em>table</em>, <em>sep='\t'</em>, <em>null='\N'</em>, <em>columns=None</em><big>)</big><a class="headerlink" href="#cursor.copy_from" title="Permalink to this definition">¶</a></dt>
410
 
<dd><p>Read data <em>from</em> the file-like object <tt class="xref docutils literal"><span class="pre">file</span></tt> appending them to
411
 
the table named <tt class="xref docutils literal"><span class="pre">table</span></tt>.  <tt class="xref docutils literal"><span class="pre">file</span></tt> must have both
412
 
<tt class="xref docutils literal"><span class="pre">read()</span></tt> and <tt class="xref docutils literal"><span class="pre">readline()</span></tt> method.  See <a class="reference external" href="usage.html#copy"><em>Using COPY TO and COPY FROM</em></a> for an
413
 
overview.</p>
414
 
<p>The optional argument <tt class="xref docutils literal"><span class="pre">sep</span></tt> is the columns separator and
415
 
<tt class="xref docutils literal"><span class="pre">null</span></tt> represents <tt class="sql docutils literal"><span class="pre">NULL</span></tt> values in the file.</p>
416
 
<p>The <tt class="xref docutils literal"><span class="pre">columns</span></tt> argument is a sequence containing the name of the
417
 
fields where the read data will be entered.  Its length and column
418
 
type should match the content of the read file.  If not specifies, it
419
 
is assumed that the entire table matches the file structure.</p>
 
465
<tt class="descname">copy_from</tt><big>(</big><em>file</em>, <em>table</em>, <em>sep='\t'</em>, <em>null='\N'</em>, <em>size=8192</em>, <em>columns=None</em><big>)</big><a class="headerlink" href="#cursor.copy_from" title="Permalink to this definition">¶</a></dt>
 
466
<dd><p>Read data <em>from</em> the file-like object <em>file</em> appending them to
 
467
the table named <em>table</em>.  See <a class="reference internal" href="usage.html#copy"><em>Using COPY TO and COPY FROM</em></a> for an overview.</p>
 
468
<table class="docutils field-list" frame="void" rules="none">
 
469
<col class="field-name" />
 
470
<col class="field-body" />
 
471
<tbody valign="top">
 
472
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
473
<li><strong>file</strong> &#8211; file-like object to read data from.  It must have both
 
474
<tt class="xref py py-obj docutils literal"><span class="pre">read()</span></tt> and <tt class="xref py py-obj docutils literal"><span class="pre">readline()</span></tt> methods.</li>
 
475
<li><strong>table</strong> &#8211; name of the table to copy data into.</li>
 
476
<li><strong>sep</strong> &#8211; columns separator expected in the file. Defaults to a tab.</li>
 
477
<li><strong>null</strong> &#8211; textual representation of <tt class="sql docutils literal"><span class="pre">NULL</span></tt> in the file.</li>
 
478
<li><strong>size</strong> &#8211; size of the buffer used to read from the file.</li>
 
479
<li><strong>columns</strong> &#8211; iterable with name of the columns to import.
 
480
The length and types should match the content of the file to read.
 
481
If not specified, it is assumed that the entire table matches the
 
482
file structure.</li>
 
483
</ul>
 
484
</td>
 
485
</tr>
 
486
</tbody>
 
487
</table>
 
488
<p>Example:</p>
420
489
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">StringIO</span><span class="p">(</span><span class="s">&quot;42</span><span class="se">\t</span><span class="s">foo</span><span class="se">\n</span><span class="s">74</span><span class="se">\t</span><span class="s">bar</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">)</span>
421
490
<span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">copy_from</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="s">&#39;test&#39;</span><span class="p">,</span> <span class="n">columns</span><span class="o">=</span><span class="p">(</span><span class="s">&#39;num&#39;</span><span class="p">,</span> <span class="s">&#39;data&#39;</span><span class="p">))</span>
422
491
<span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">&quot;select * from test where id &gt; 5;&quot;</span><span class="p">)</span>
424
493
<span class="go">[(6, 42, &#39;foo&#39;), (7, 74, &#39;bar&#39;)]</span>
425
494
</pre></div>
426
495
</div>
427
 
<p>
428
 
<span class="versionmodified">Changed in version 2.0.6: </span>added the <tt class="xref docutils literal"><span class="pre">columns</span></tt> parameter.</p>
 
496
<p class="versionchanged">
 
497
<span class="versionmodified">Changed in version 2.0.6: </span>added the <em>columns</em> parameter.</p>
 
498
<p class="versionchanged">
 
499
<span class="versionmodified">Changed in version 2.4: </span>data read from files implementing the <a class="reference external" href="http://docs.python.org/3.2/library/io.html#io.TextIOBase" title="(in Python v3.2)"><tt class="xref py py-obj docutils literal"><span class="pre">io.TextIOBase</span></tt></a> interface
 
500
are encoded in the connection <a class="reference internal" href="connection.html#connection.encoding" title="connection.encoding"><tt class="xref py py-obj docutils literal"><span class="pre">encoding</span></tt></a> when sent to
 
501
the backend.</p>
429
502
</dd></dl>
430
503
 
431
504
<dl class="method">
432
505
<dt id="cursor.copy_to">
433
506
<tt class="descname">copy_to</tt><big>(</big><em>file</em>, <em>table</em>, <em>sep='\t'</em>, <em>null='\N'</em>, <em>columns=None</em><big>)</big><a class="headerlink" href="#cursor.copy_to" title="Permalink to this definition">¶</a></dt>
434
 
<dd><p>Write the content of the table named <tt class="xref docutils literal"><span class="pre">table</span></tt> <em>to</em> the file-like
435
 
object <tt class="xref docutils literal"><span class="pre">file</span></tt>.  <tt class="xref docutils literal"><span class="pre">file</span></tt> must have a <tt class="xref docutils literal"><span class="pre">write()</span></tt> method.
436
 
See <a class="reference external" href="usage.html#copy"><em>Using COPY TO and COPY FROM</em></a> for an overview.</p>
437
 
<p>The optional argument <tt class="xref docutils literal"><span class="pre">sep</span></tt> is the columns separator and
438
 
<tt class="xref docutils literal"><span class="pre">null</span></tt> represents <tt class="sql docutils literal"><span class="pre">NULL</span></tt> values in the file.</p>
439
 
<p>The <tt class="xref docutils literal"><span class="pre">columns</span></tt> argument is a sequence of field names: if not
440
 
<tt class="xref docutils literal"><span class="pre">None</span></tt> only the specified fields will be included in the dump.</p>
 
507
<dd><p>Write the content of the table named <em>table</em> <em>to</em> the file-like
 
508
object <em>file</em>.  See <a class="reference internal" href="usage.html#copy"><em>Using COPY TO and COPY FROM</em></a> for an overview.</p>
 
509
<table class="docutils field-list" frame="void" rules="none">
 
510
<col class="field-name" />
 
511
<col class="field-body" />
 
512
<tbody valign="top">
 
513
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
514
<li><strong>file</strong> &#8211; file-like object to write data into.  It must have a
 
515
<tt class="xref py py-obj docutils literal"><span class="pre">write()</span></tt> method.</li>
 
516
<li><strong>table</strong> &#8211; name of the table to copy data from.</li>
 
517
<li><strong>sep</strong> &#8211; columns separator expected in the file. Defaults to a tab.</li>
 
518
<li><strong>null</strong> &#8211; textual representation of <tt class="sql docutils literal"><span class="pre">NULL</span></tt> in the file.</li>
 
519
<li><strong>columns</strong> &#8211; iterable with name of the columns to export.
 
520
If not specified, export all the columns.</li>
 
521
</ul>
 
522
</td>
 
523
</tr>
 
524
</tbody>
 
525
</table>
 
526
<p>Example:</p>
441
527
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">copy_to</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="p">,</span> <span class="s">&#39;test&#39;</span><span class="p">,</span> <span class="n">sep</span><span class="o">=</span><span class="s">&quot;|&quot;</span><span class="p">)</span>
442
528
<span class="go">1|100|abc&#39;def</span>
443
529
<span class="go">2|\N|dada</span>
444
530
<span class="gp">...</span>
445
531
</pre></div>
446
532
</div>
447
 
<p>
448
 
<span class="versionmodified">Changed in version 2.0.6: </span>added the <tt class="xref docutils literal"><span class="pre">columns</span></tt> parameter.</p>
 
533
<p class="versionchanged">
 
534
<span class="versionmodified">Changed in version 2.0.6: </span>added the <em>columns</em> parameter.</p>
 
535
<p class="versionchanged">
 
536
<span class="versionmodified">Changed in version 2.4: </span>data sent to files implementing the <a class="reference external" href="http://docs.python.org/3.2/library/io.html#io.TextIOBase" title="(in Python v3.2)"><tt class="xref py py-obj docutils literal"><span class="pre">io.TextIOBase</span></tt></a> interface
 
537
are decoded in the connection <a class="reference internal" href="connection.html#connection.encoding" title="connection.encoding"><tt class="xref py py-obj docutils literal"><span class="pre">encoding</span></tt></a> when read
 
538
from the backend.</p>
449
539
</dd></dl>
450
540
 
451
541
<dl class="method">
452
542
<dt id="cursor.copy_expert">
453
 
<tt class="descname">copy_expert</tt><big>(</big><em>sql</em>, <em>file</em><span class="optional">[</span>, <em>size</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#cursor.copy_expert" title="Permalink to this definition">¶</a></dt>
 
543
<tt class="descname">copy_expert</tt><big>(</big><em>sql</em>, <em>file</em>, <em>size=8192</em><big>)</big><a class="headerlink" href="#cursor.copy_expert" title="Permalink to this definition">¶</a></dt>
454
544
<dd><p>Submit a user-composed <tt class="sql docutils literal"><span class="pre">COPY</span></tt> statement. The method is useful to
455
545
handle all the parameters that PostgreSQL makes available (see
456
 
<a class="reference external" href="http://www.postgresql.org/docs/8.4/static/sql-copy.html"><tt class="sql docutils literal"><span class="pre">COPY</span></tt></a> command documentation).</p>
457
 
<p><tt class="xref docutils literal"><span class="pre">file</span></tt> must be an open, readable file for <tt class="sql docutils literal"><span class="pre">COPY</span> <span class="pre">FROM</span></tt> or an
458
 
open, writeable file for <tt class="sql docutils literal"><span class="pre">COPY</span> <span class="pre">TO</span></tt>. The optional <tt class="xref docutils literal"><span class="pre">size</span></tt>
459
 
argument, when specified for a <tt class="sql docutils literal"><span class="pre">COPY</span> <span class="pre">FROM</span></tt> statement, will be
460
 
passed to <tt class="xref docutils literal"><span class="pre">file</span></tt>&#8216;s read method to control the read buffer
461
 
size.</p>
 
546
<a class="reference external" href="http://www.postgresql.org/docs/9.0/static/sql-copy.html"><tt class="sql docutils literal"><span class="pre">COPY</span></tt></a> command documentation).</p>
 
547
<table class="docutils field-list" frame="void" rules="none">
 
548
<col class="field-name" />
 
549
<col class="field-body" />
 
550
<tbody valign="top">
 
551
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
552
<li><strong>sql</strong> &#8211; the <tt class="sql docutils literal"><span class="pre">COPY</span></tt> statement to execute.</li>
 
553
<li><strong>file</strong> &#8211; a file-like object; must be a readable file for
 
554
<tt class="sql docutils literal"><span class="pre">COPY</span> <span class="pre">FROM</span></tt> or an writeable file for <tt class="sql docutils literal"><span class="pre">COPY</span> <span class="pre">TO</span></tt>.</li>
 
555
<li><strong>size</strong> &#8211; size of the read buffer to be used in <tt class="sql docutils literal"><span class="pre">COPY</span> <span class="pre">FROM</span></tt>.</li>
 
556
</ul>
 
557
</td>
 
558
</tr>
 
559
</tbody>
 
560
</table>
 
561
<p>Example:</p>
462
562
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">copy_expert</span><span class="p">(</span><span class="s">&quot;COPY test TO STDOUT WITH CSV HEADER&quot;</span><span class="p">,</span> <span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="p">)</span>
463
563
<span class="go">id,num,data</span>
464
564
<span class="go">1,100,abc&#39;def</span>
466
566
<span class="gp">...</span>
467
567
</pre></div>
468
568
</div>
469
 
<p>
 
569
<p class="versionadded">
470
570
<span class="versionmodified">New in version 2.0.6.</span></p>
 
571
<p class="versionchanged">
 
572
<span class="versionmodified">Changed in version 2.4: </span>files implementing the <a class="reference external" href="http://docs.python.org/3.2/library/io.html#io.TextIOBase" title="(in Python v3.2)"><tt class="xref py py-obj docutils literal"><span class="pre">io.TextIOBase</span></tt></a> interface are dealt with
 
573
using Unicode data instead of bytes.</p>
471
574
</dd></dl>
472
575
 
473
576
</dd></dl>
480
583
      </div>
481
584
      <div class="sphinxsidebar">
482
585
        <div class="sphinxsidebarwrapper">
483
 
            <h4>Previous topic</h4>
484
 
            <p class="topless"><a href="connection.html"
485
 
                                  title="previous chapter">The <tt class="docutils literal docutils literal"><span class="pre">connection</span></tt> class</a></p>
486
 
            <h4>Next topic</h4>
487
 
            <p class="topless"><a href="advanced.html"
488
 
                                  title="next chapter">More advanced topics</a></p>
489
 
            <h3>This Page</h3>
490
 
            <ul class="this-page-menu">
491
 
              <li><a href="_sources/cursor.txt"
492
 
                     rel="nofollow">Show Source</a></li>
493
 
            </ul>
494
 
          <div id="searchbox" style="display: none">
495
 
            <h3>Quick search</h3>
496
 
              <form class="search" action="search.html" method="get">
497
 
                <input type="text" name="q" size="18" />
498
 
                <input type="submit" value="Go" />
499
 
                <input type="hidden" name="check_keywords" value="yes" />
500
 
                <input type="hidden" name="area" value="default" />
501
 
              </form>
502
 
              <p class="searchtip" style="font-size: 90%">
503
 
              Enter search terms or a module, class or function name.
504
 
              </p>
505
 
          </div>
506
 
          <script type="text/javascript">$('#searchbox').show(0);</script>
 
586
  <h4>Previous topic</h4>
 
587
  <p class="topless"><a href="connection.html"
 
588
                        title="previous chapter">The <tt class="docutils literal docutils literal"><span class="pre">connection</span></tt> class</a></p>
 
589
  <h4>Next topic</h4>
 
590
  <p class="topless"><a href="advanced.html"
 
591
                        title="next chapter">More advanced topics</a></p>
 
592
  <h3>This Page</h3>
 
593
  <ul class="this-page-menu">
 
594
    <li><a href="_sources/cursor.txt"
 
595
           rel="nofollow">Show Source</a></li>
 
596
  </ul>
 
597
<div id="searchbox" style="display: none">
 
598
  <h3>Quick search</h3>
 
599
    <form class="search" action="search.html" method="get">
 
600
      <input type="text" name="q" size="18" />
 
601
      <input type="submit" value="Go" />
 
602
      <input type="hidden" name="check_keywords" value="yes" />
 
603
      <input type="hidden" name="area" value="default" />
 
604
    </form>
 
605
    <p class="searchtip" style="font-size: 90%">
 
606
    Enter search terms or a module, class or function name.
 
607
    </p>
 
608
</div>
 
609
<script type="text/javascript">$('#searchbox').show(0);</script>
507
610
        </div>
508
611
      </div>
509
612
      <div class="clearer"></div>
515
618
          <a href="genindex.html" title="General Index"
516
619
             >index</a></li>
517
620
        <li class="right" >
518
 
          <a href="modindex.html" title="Global Module Index"
 
621
          <a href="py-modindex.html" title="Python Module Index"
519
622
             >modules</a> |</li>
520
623
        <li class="right" >
521
624
          <a href="advanced.html" title="More advanced topics"
523
626
        <li class="right" >
524
627
          <a href="connection.html" title="The connection class"
525
628
             >previous</a> |</li>
526
 
        <li><a href="index.html">Psycopg v2.2.1 documentation</a> &raquo;</li> 
 
629
        <li><a href="index.html">Psycopg v2.4.2 documentation</a> &raquo;</li> 
527
630
      </ul>
528
631
    </div>
529
632
    <div class="footer">
530
 
      &copy; Copyright 2001-2010, Federico Di Gregorio. Documentation by Daniele Varrazzo.
531
 
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.5.
 
633
        &copy; Copyright 2001-2011, Federico Di Gregorio. Documentation by Daniele Varrazzo.
 
634
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
532
635
    </div>
533
636
  </body>
534
637
</html>
 
 
b'\\ No newline at end of file'