tools/bin/pythonSrc/PyGreSQL-4.0/docs/pg.html - hawq - Git at Google

 <?xml version="1.0" encoding="utf-8" ?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
 <title>PyGreSQL Programming Information</title>
 <meta content="The classic PyGreSQL interface (pg module)" name="description" />
 <meta content="PyGreSQL, pg, PostGreSQL, Python" name="keywords" />
 <link rel="stylesheet" href="docs.css" type="text/css" />
 </head>
 <body>
 <div class="document" id="pygresql-programming-information">
 <h1 class="title">PyGreSQL Programming Information</h1>
 <h2 class="subtitle" id="the-classic-pygresql-interface-pg-module">The classic PyGreSQL interface (pg module)</h2>
 <div class="contents topic">
 <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
 <ul class="auto-toc simple">
 <li><a class="reference" href="#introduction" id="id5" name="id5">1&nbsp;&nbsp;&nbsp;Introduction</a></li>
 <li><a class="reference" href="#module-functions-and-constants" id="id6" name="id6">2&nbsp;&nbsp;&nbsp;Module functions and constants</a><ul class="auto-toc">
 <li><a class="reference" href="#connect-opens-a-pg-connection" id="id7" name="id7">2.1&nbsp;&nbsp;&nbsp;connect - opens a pg connection</a></li>
 <li><a class="reference" href="#get-defhost-set-defhost-default-server-host-dv" id="id8" name="id8">2.2&nbsp;&nbsp;&nbsp;get_defhost, set_defhost - default server host [DV]</a></li>
 <li><a class="reference" href="#get-defport-set-defport-default-server-port-dv" id="id9" name="id9">2.3&nbsp;&nbsp;&nbsp;get_defport, set_defport - default server port [DV]</a></li>
 <li><a class="reference" href="#get-defopt-set-defopt-default-connection-options-dv" id="id10" name="id10">2.4&nbsp;&nbsp;&nbsp;get_defopt, set_defopt - default connection options [DV]</a></li>
 <li><a class="reference" href="#get-deftty-set-deftty-default-debug-tty-dv" id="id11" name="id11">2.5&nbsp;&nbsp;&nbsp;get_deftty, set_deftty - default debug tty [DV]</a></li>
 <li><a class="reference" href="#get-defbase-set-defbase-default-database-name-dv" id="id12" name="id12">2.6&nbsp;&nbsp;&nbsp;get_defbase, set_defbase - default database name [DV]</a></li>
 <li><a class="reference" href="#escape-string-escape-a-string-for-use-within-sql" id="id13" name="id13">2.7&nbsp;&nbsp;&nbsp;escape_string - escape a string for use within SQL</a></li>
 <li><a class="reference" href="#escape-bytea-escape-binary-data-for-use-within-sql-as-type-bytea" id="id14" name="id14">2.8&nbsp;&nbsp;&nbsp;escape_bytea - escape binary data for use within SQL as type <cite>bytea</cite></a></li>
 <li><a class="reference" href="#unescape-bytea-unescape-bytea-data-that-has-been-retrieved-as-text" id="id15" name="id15">2.9&nbsp;&nbsp;&nbsp;unescape_bytea -- unescape <cite>bytea</cite> data that has been retrieved as text</a></li>
 <li><a class="reference" href="#set-decimal-set-a-decimal-type-to-be-used-for-numeric-values" id="id16" name="id16">2.10&nbsp;&nbsp;&nbsp;set_decimal -- set a decimal type to be used for numeric values</a></li>
 <li><a class="reference" href="#module-constants" id="id17" name="id17">2.11&nbsp;&nbsp;&nbsp;Module constants</a></li>
 </ul>
 </li>
 <li><a class="reference" href="#connection-objects-pgobject" id="id18" name="id18">3&nbsp;&nbsp;&nbsp;Connection objects: pgobject</a><ul class="auto-toc">
 <li><a class="reference" href="#query-executes-a-sql-command-string" id="id19" name="id19">3.1&nbsp;&nbsp;&nbsp;query - executes a SQL command string</a></li>
 <li><a class="reference" href="#reset-resets-the-connection" id="id20" name="id20">3.2&nbsp;&nbsp;&nbsp;reset - resets the connection</a></li>
 <li><a class="reference" href="#cancel-abandon-processing-of-current-sql-command" id="id21" name="id21">3.3&nbsp;&nbsp;&nbsp;cancel - abandon processing of current SQL command</a></li>
 <li><a class="reference" href="#close-close-the-database-connection" id="id22" name="id22">3.4&nbsp;&nbsp;&nbsp;close - close the database connection</a></li>
 <li><a class="reference" href="#fileno-returns-the-socket-used-to-connect-to-the-database" id="id23" name="id23">3.5&nbsp;&nbsp;&nbsp;fileno - returns the socket used to connect to the database</a></li>
 <li><a class="reference" href="#getnotify-gets-the-last-notify-from-the-server" id="id24" name="id24">3.6&nbsp;&nbsp;&nbsp;getnotify - gets the last notify from the server</a></li>
 <li><a class="reference" href="#inserttable-insert-a-list-into-a-table" id="id25" name="id25">3.7&nbsp;&nbsp;&nbsp;inserttable - insert a list into a table</a></li>
 <li><a class="reference" href="#putline-writes-a-line-to-the-server-socket-da" id="id26" name="id26">3.8&nbsp;&nbsp;&nbsp;putline - writes a line to the server socket [DA]</a></li>
 <li><a class="reference" href="#getline-gets-a-line-from-server-socket-da" id="id27" name="id27">3.9&nbsp;&nbsp;&nbsp;getline - gets a line from server socket [DA]</a></li>
 <li><a class="reference" href="#endcopy-synchronizes-client-and-server-da" id="id28" name="id28">3.10&nbsp;&nbsp;&nbsp;endcopy - synchronizes client and server [DA]</a></li>
 <li><a class="reference" href="#locreate-create-a-large-object-in-the-database-lo" id="id29" name="id29">3.11&nbsp;&nbsp;&nbsp;locreate - create a large object in the database [LO]</a></li>
 <li><a class="reference" href="#getlo-build-a-large-object-from-given-oid-lo" id="id30" name="id30">3.12&nbsp;&nbsp;&nbsp;getlo - build a large object from given oid [LO]</a></li>
 <li><a class="reference" href="#loimport-import-a-file-to-a-large-object-lo" id="id31" name="id31">3.13&nbsp;&nbsp;&nbsp;loimport - import a file to a large object [LO]</a></li>
 <li><a class="reference" href="#object-attributes" id="id32" name="id32">3.14&nbsp;&nbsp;&nbsp;Object attributes</a></li>
 </ul>
 </li>
 <li><a class="reference" href="#the-db-wrapper-class" id="id33" name="id33">4&nbsp;&nbsp;&nbsp;The DB wrapper class</a><ul class="auto-toc">
 <li><a class="reference" href="#initialization" id="id34" name="id34">4.1&nbsp;&nbsp;&nbsp;Initialization</a></li>
 <li><a class="reference" href="#pkey-return-the-primary-key-of-a-table" id="id35" name="id35">4.2&nbsp;&nbsp;&nbsp;pkey - return the primary key of a table</a></li>
 <li><a class="reference" href="#get-databases-get-list-of-databases-in-the-system" id="id36" name="id36">4.3&nbsp;&nbsp;&nbsp;get_databases - get list of databases in the system</a></li>
 <li><a class="reference" href="#get-relations-get-list-of-relations-in-connected-database" id="id37" name="id37">4.4&nbsp;&nbsp;&nbsp;get_relations - get list of relations in connected database</a></li>
 <li><a class="reference" href="#get-tables-get-list-of-tables-in-connected-database" id="id38" name="id38">4.5&nbsp;&nbsp;&nbsp;get_tables - get list of tables in connected database</a></li>
 <li><a class="reference" href="#get-attnames-get-the-attribute-names-of-a-table" id="id39" name="id39">4.6&nbsp;&nbsp;&nbsp;get_attnames - get the attribute names of a table</a></li>
 <li><a class="reference" href="#has-table-privilege-check-whether-current-user-has-specified-table-privilege" id="id40" name="id40">4.7&nbsp;&nbsp;&nbsp;has_table_privilege - check whether current user has specified table privilege</a></li>
 <li><a class="reference" href="#get-get-a-row-from-a-database-table-or-view" id="id41" name="id41">4.8&nbsp;&nbsp;&nbsp;get - get a row from a database table or view</a></li>
 <li><a class="reference" href="#insert-insert-a-row-into-a-database-table" id="id42" name="id42">4.9&nbsp;&nbsp;&nbsp;insert - insert a row into a database table</a></li>
 <li><a class="reference" href="#update-update-a-row-in-a-database-table" id="id43" name="id43">4.10&nbsp;&nbsp;&nbsp;update - update a row in a database table</a></li>
 <li><a class="reference" href="#clear-clears-row-values-in-memory" id="id44" name="id44">4.11&nbsp;&nbsp;&nbsp;clear - clears row values in memory</a></li>
 <li><a class="reference" href="#delete-delete-a-row-from-a-database-table" id="id45" name="id45">4.12&nbsp;&nbsp;&nbsp;delete - delete a row from a database table</a></li>
 <li><a class="reference" href="#id1" id="id46" name="id46">4.13&nbsp;&nbsp;&nbsp;escape_string - escape a string for use within SQL</a></li>
 <li><a class="reference" href="#id2" id="id47" name="id47">4.14&nbsp;&nbsp;&nbsp;escape_bytea - escape binary data for use within SQL as type <cite>bytea</cite></a></li>
 <li><a class="reference" href="#id3" id="id48" name="id48">4.15&nbsp;&nbsp;&nbsp;unescape_bytea -- unescape <cite>bytea</cite> data that has been retrieved as text</a></li>
 </ul>
 </li>
 <li><a class="reference" href="#pgqueryobject-methods" id="id49" name="id49">5&nbsp;&nbsp;&nbsp;pgqueryobject methods</a><ul class="auto-toc">
 <li><a class="reference" href="#getresult-get-query-values-as-list-of-tuples" id="id50" name="id50">5.1&nbsp;&nbsp;&nbsp;getresult - get query values as list of tuples</a></li>
 <li><a class="reference" href="#dictresult-get-query-values-as-list-of-dictionaries" id="id51" name="id51">5.2&nbsp;&nbsp;&nbsp;dictresult - get query values as list of dictionaries</a></li>
 <li><a class="reference" href="#listfields-lists-fields-names-of-previous-query-result" id="id52" name="id52">5.3&nbsp;&nbsp;&nbsp;listfields - lists fields names of previous query result</a></li>
 <li><a class="reference" href="#fieldname-fieldnum-field-name-number-conversion" id="id53" name="id53">5.4&nbsp;&nbsp;&nbsp;fieldname, fieldnum - field name/number conversion</a></li>
 <li><a class="reference" href="#ntuples-return-number-of-tuples-in-query-object" id="id54" name="id54">5.5&nbsp;&nbsp;&nbsp;ntuples - return number of tuples in query object</a></li>
 </ul>
 </li>
 <li><a class="reference" href="#large-objects-pglarge" id="id55" name="id55">6&nbsp;&nbsp;&nbsp;Large objects: pglarge</a><ul class="auto-toc">
 <li><a class="reference" href="#open-opens-a-large-object" id="id56" name="id56">6.1&nbsp;&nbsp;&nbsp;open - opens a large object</a></li>
 <li><a class="reference" href="#close-closes-a-large-object" id="id57" name="id57">6.2&nbsp;&nbsp;&nbsp;close - closes a large object</a></li>
 <li><a class="reference" href="#read-write-tell-seek-unlink-file-like-large-object-handling" id="id58" name="id58">6.3&nbsp;&nbsp;&nbsp;read, write, tell, seek, unlink - file like large object handling</a></li>
 <li><a class="reference" href="#size-gives-the-large-object-size" id="id59" name="id59">6.4&nbsp;&nbsp;&nbsp;size - gives the large object size</a></li>
 <li><a class="reference" href="#export-saves-a-large-object-to-a-file" id="id60" name="id60">6.5&nbsp;&nbsp;&nbsp;export - saves a large object to a file</a></li>
 <li><a class="reference" href="#id4" id="id61" name="id61">6.6&nbsp;&nbsp;&nbsp;Object attributes</a></li>
 </ul>
 </li>
 </ul>
 </div>
 <div class="section">
 <h1><a class="toc-backref" href="#id5" id="introduction" name="introduction">1&nbsp;&nbsp;&nbsp;Introduction</a></h1>
 <p>You may either choose to use the
 <a class="reference" href="pg.html">&quot;classic&quot; PyGreSQL interface</a>
 provided by the <cite>pg</cite> module or else the
 <a class="reference" href="pgdb.html">DB-API 2.0 compliant interface</a>
 provided by the <cite>pgdb</cite> module.</p>
 <p>The following documentation covers only the older <cite>pg</cite> API.</p>
 <p>The <cite>pg</cite> module handles three types of objects,</p>
 <ul class="simple">
 <li>the <cite>pgobject</cite>, which handles the connection
 and all the requests to the database,</li>
 <li>the <cite>pglarge</cite> object, which handles
 all the accesses to PostgreSQL large objects,</li>
 <li>the <cite>pgqueryobject</cite> that handles query results</li>
 </ul>
 <p>and it provides a convenient wrapper class <cite>DB</cite> for the <cite>pgobject</cite>.</p>
 <p>If you want to see a simple example of the use of some of these functions,
 see <a class="reference" href="http://ontario.bikerides.ca">http://ontario.bikerides.ca</a> where you can find a link at the bottom to the
 actual Python code for the page.</p>
 </div>
 <div class="section">
 <h1><a class="toc-backref" href="#id6" id="module-functions-and-constants" name="module-functions-and-constants">2&nbsp;&nbsp;&nbsp;Module functions and constants</a></h1>
 <p>The <cite>pg</cite> module defines a few functions that allow to connect
 to a database and to define &quot;default variables&quot; that override
 the environment variables used by PostgreSQL.</p>
 <p>These &quot;default variables&quot; were designed to allow you to handle general
 connection parameters without heavy code in your programs. You can prompt the
 user for a value, put it in the default variable, and forget it, without
 having to modify your environment. The support for default variables can be
 disabled by setting the -DNO_DEF_VAR option in the Python setup file. Methods
 relative to this are specified by the tag [DV].</p>
 <p>All variables are set to <cite>None</cite> at module initialization, specifying that
 standard environment variables should be used.</p>
 <div class="section">
 <h2><a class="toc-backref" href="#id7" id="connect-opens-a-pg-connection" name="connect-opens-a-pg-connection">2.1&nbsp;&nbsp;&nbsp;connect - opens a pg connection</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 connect([dbname], [host], [port], [opt], [tty], [user], [passwd])
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">dbname:</th><td class="field-body">name of connected database (string/None)</td>
 </tr>
 <tr class="field"><th class="field-name">host:</th><td class="field-body">name of the server host (string/None)</td>
 </tr>
 <tr class="field"><th class="field-name">port:</th><td class="field-body">port used by the database server (integer/-1)</td>
 </tr>
 <tr class="field"><th class="field-name">opt:</th><td class="field-body">connection options (string/None)</td>
 </tr>
 <tr class="field"><th class="field-name">tty:</th><td class="field-body">debug terminal (string/None)</td>
 </tr>
 <tr class="field"><th class="field-name">user:</th><td class="field-body">PostgreSQL user (string/None)</td>
 </tr>
 <tr class="field"><th class="field-name">passwd:</th><td class="field-body">password for user (string/None)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">pgobject:</th><td class="field-body">If successful, the <cite>pgobject</cite> handling the connection</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">bad argument type, or too many arguments</td>
 </tr>
 <tr class="field"><th class="field-name">SyntaxError:</th><td class="field-body">duplicate argument definition</td>
 </tr>
 <tr class="field"><th class="field-name" colspan="2">pg.InternalError:</th></tr>
 <tr><td>&nbsp;</td><td class="field-body">some error occurred during pg connection definition</td>
 </tr>
 </tbody>
 </table>
 <p class="last">(plus all exceptions relative to object allocation)</p>
 </dd>
 <dt>Description:</dt>
 <dd>This function opens a connection to a specified database on a given
 PostgreSQL server. You can use keywords here, as described in the
 Python tutorial. The names of the keywords are the name of the
 parameters given in the syntax line. For a precise description
 of the parameters, please refer to the PostgreSQL user manual.</dd>
 </dl>
 <p>Examples:</p>
 <pre class="literal-block">
 import pg

 con1 = pg.connect('testdb', 'myhost', 5432, None, None, 'bob', None)
 con2 = pg.connect(dbname='testdb', host='localhost', user='bob')
 </pre>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id8" id="get-defhost-set-defhost-default-server-host-dv" name="get-defhost-set-defhost-default-server-host-dv">2.2&nbsp;&nbsp;&nbsp;get_defhost, set_defhost - default server host [DV]</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 get_defhost()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">string, None:</th><td class="field-body">default host specification</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method returns the current default host specification,
 or <cite>None</cite> if the environment variables should be used.
 Environment variables won't be looked up.</dd>
 </dl>
 <p>Syntax:</p>
 <pre class="literal-block">
 set_defhost(host)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">host:</th><td class="field-body">new default host (string/None)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">string, None:</th><td class="field-body">previous default host specification</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">bad argument type, or too many arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This methods sets the default host value for new connections.
 If <cite>None</cite> is supplied as parameter, environment variables will
 be used in future connections. It returns the previous setting
 for default host.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id9" id="get-defport-set-defport-default-server-port-dv" name="get-defport-set-defport-default-server-port-dv">2.3&nbsp;&nbsp;&nbsp;get_defport, set_defport - default server port [DV]</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 get_defport()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">integer, None:</th><td class="field-body">default port specification</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method returns the current default port specification,
 or <cite>None</cite> if the environment variables should be used.
 Environment variables won't be looked up.</dd>
 </dl>
 <p>Syntax:</p>
 <pre class="literal-block">
 set_defport(port)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">port:</th><td class="field-body">new default port (integer/-1)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">integer, None:</th><td class="field-body">previous default port specification</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This methods sets the default port value for new connections. If -1 is
 supplied as parameter, environment variables will be used in future
 connections. It returns the previous setting for default port.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id10" id="get-defopt-set-defopt-default-connection-options-dv" name="get-defopt-set-defopt-default-connection-options-dv">2.4&nbsp;&nbsp;&nbsp;get_defopt, set_defopt - default connection options [DV]</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 get_defopt()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">string, None:</th><td class="field-body">default options specification</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method returns the current default connection options  specification,
 or <cite>None</cite> if the environment variables should be used. Environment variables
 won't be looked up.</dd>
 </dl>
 <p>Syntax:</p>
 <pre class="literal-block">
 set_defopt(options)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">options:</th><td class="field-body">new default connection options (string/None)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">string, None:</th><td class="field-body">previous default options specification</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">bad argument type, or too many arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This methods sets the default connection options value for new connections.
 If <cite>None</cite> is supplied as parameter, environment variables will be used in
 future connections. It returns the previous setting for default options.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id11" id="get-deftty-set-deftty-default-debug-tty-dv" name="get-deftty-set-deftty-default-debug-tty-dv">2.5&nbsp;&nbsp;&nbsp;get_deftty, set_deftty - default debug tty [DV]</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 get_deftty()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">string, None:</th><td class="field-body">default debug terminal specification</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method returns the current default debug terminal specification, or
 <cite>None</cite> if the environment variables should be used. Environment variables
 won't be looked up.</dd>
 </dl>
 <p>Syntax:</p>
 <pre class="literal-block">
 set_deftty(terminal)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">terminal:</th><td class="field-body">new default debug terminal (string/None)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">string, None:</th><td class="field-body">previous default debug terminal specification</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">bad argument type, or too many arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This methods sets the default debug terminal value for new connections. If
 <cite>None</cite> is supplied as parameter, environment variables will be used in future
 connections. It returns the previous setting for default terminal.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id12" id="get-defbase-set-defbase-default-database-name-dv" name="get-defbase-set-defbase-default-database-name-dv">2.6&nbsp;&nbsp;&nbsp;get_defbase, set_defbase - default database name [DV]</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 get_defbase()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">string, None:</th><td class="field-body">default database name specification</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method returns the current default database name specification, or
 <cite>None</cite> if the environment variables should be used. Environment variables
 won't be looked up.</dd>
 </dl>
 <p>Syntax:</p>
 <pre class="literal-block">
 set_defbase(base)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">base:</th><td class="field-body">new default base name (string/None)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">string, None:</th><td class="field-body">previous default database name specification</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">bad argument type, or too many arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method sets the default database name value for new connections. If
 <cite>None</cite> is supplied as parameter, environment variables will be used in
 future connections. It returns the previous setting for default host.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id13" id="escape-string-escape-a-string-for-use-within-sql" name="escape-string-escape-a-string-for-use-within-sql">2.7&nbsp;&nbsp;&nbsp;escape_string - escape a string for use within SQL</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 escape_string(string)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">string:</th><td class="field-body">the string that is to be escaped</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">str:</th><td class="field-body">the escaped string</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">bad argument type, or too many arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This function escapes a string for use within an SQL command.
 This is useful when inserting data values as literal constants
 in SQL commands. Certain characters (such as quotes and backslashes)
 must be escaped to prevent them from being interpreted specially
 by the SQL parser. <cite>escape_string</cite> performs this operation.
 Note that there is also a <cite>pgobject</cite> method with the same name
 which takes connection properties into account.</dd>
 </dl>
 <div class="caution">
 <p class="first admonition-title">Caution!</p>
 <p class="last">It is especially important to do proper escaping when
 handling strings that were received from an untrustworthy source.
 Otherwise there is a security risk: you are vulnerable to &quot;SQL injection&quot;
 attacks wherein unwanted SQL commands are fed to your database.</p>
 </div>
 <p>Example:</p>
 <pre class="literal-block">
 name = raw_input(&quot;Name? &quot;)
 phone = con.query(&quot;select phone from employees&quot;
   &quot; where name='%s'&quot; % escape_string(name)).getresult()
 </pre>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id14" id="escape-bytea-escape-binary-data-for-use-within-sql-as-type-bytea" name="escape-bytea-escape-binary-data-for-use-within-sql-as-type-bytea">2.8&nbsp;&nbsp;&nbsp;escape_bytea - escape binary data for use within SQL as type <cite>bytea</cite></a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 escape_bytea(datastring)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">datastring:</th><td class="field-body">string containing the binary data that is to be escaped</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">str:</th><td class="field-body">the escaped string</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">bad argument type, or too many arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>Escapes binary data for use within an SQL command with the type <cite>bytea</cite>.
 As with <cite>escape_string</cite>, this is only used when inserting data directly
 into an SQL command string.
 Note that there is also a <cite>pgobject</cite> method with the same name
 which takes connection properties into account.</dd>
 </dl>
 <p>Example:</p>
 <pre class="literal-block">
 picture = file('garfield.gif', 'rb').read()
 con.query(&quot;update pictures set img='%s' where name='Garfield'&quot;
   % escape_bytea(picture))
 </pre>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id15" id="unescape-bytea-unescape-bytea-data-that-has-been-retrieved-as-text" name="unescape-bytea-unescape-bytea-data-that-has-been-retrieved-as-text">2.9&nbsp;&nbsp;&nbsp;unescape_bytea -- unescape <cite>bytea</cite> data that has been retrieved as text</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 unescape_bytea(string)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">datastring:</th><td class="field-body">the <cite>bytea</cite> data string that has been retrieved as text</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">str:</th><td class="field-body">string containing the binary data</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">bad argument type, or too many arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>Converts an escaped string representation of binary data into binary
 data - the reverse of <cite>escape_bytea</cite>. This is needed when retrieving
 <cite>bytea</cite> data with the <cite>getresult()</cite> or <cite>dictresult()</cite> method.</dd>
 </dl>
 <p>Example:</p>
 <pre class="literal-block">
 picture = unescape_bytea(con.query(
   &quot;select img from pictures where name='Garfield'&quot;).getresult[0][0])
 file('garfield.gif', 'wb').write(picture)
 </pre>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id16" id="set-decimal-set-a-decimal-type-to-be-used-for-numeric-values" name="set-decimal-set-a-decimal-type-to-be-used-for-numeric-values">2.10&nbsp;&nbsp;&nbsp;set_decimal -- set a decimal type to be used for numeric values</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 set_decimal(cls)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">cls:</th><td class="field-body">the Python class to be used for PostgreSQL numeric values</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This function can be used to specify the Python class that shall be
 used by PyGreSQL to hold PostgreSQL numeric values. The default class
 is decimal.Decimal if available, otherwise the float type is used.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id17" id="module-constants" name="module-constants">2.11&nbsp;&nbsp;&nbsp;Module constants</a></h2>
 <p>Some constants are defined in the module dictionary.
 They are intended to be used as parameters for methods calls.
 You should refer to the libpq description in the PostgreSQL user manual
 for more information about them. These constants are:</p>
 <table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name" colspan="2">version, __version__:</th></tr>
 <tr><td>&nbsp;</td><td class="field-body">constants that give the current version.</td>
 </tr>
 <tr class="field"><th class="field-name" colspan="2">INV_READ, INV_WRITE:</th></tr>
 <tr><td>&nbsp;</td><td class="field-body">large objects access modes,
 used by <cite>(pgobject.)locreate</cite> and <cite>(pglarge.)open</cite></td>
 </tr>
 <tr class="field"><th class="field-name" colspan="2">SEEK_SET, SEEK_CUR, SEEK_END:</th></tr>
 <tr><td>&nbsp;</td><td class="field-body">positional flags,
 used by <cite>(pglarge.)seek</cite></td>
 </tr>
 </tbody>
 </table>
 </div>
 </div>
 <div class="section">
 <h1><a class="toc-backref" href="#id18" id="connection-objects-pgobject" name="connection-objects-pgobject">3&nbsp;&nbsp;&nbsp;Connection objects: pgobject</a></h1>
 <p>This object handles a connection to a PostgreSQL database. It embeds and
 hides all the parameters that define this connection, thus just leaving really
 significant parameters in function calls.</p>
 <div class="caution">
 <p class="first admonition-title">Caution!</p>
 <p>Some methods give direct access to the connection socket.
 <em>Do not use them unless you really know what you are doing.</em>
 If you prefer disabling them,
 set the -DNO_DIRECT option in the Python setup file.</p>
 <p class="last"><strong>These methods are specified by the tag [DA].</strong></p>
 </div>
 <div class="note">
 <p class="first admonition-title">Note</p>
 <p>Some other methods give access to large objects
 (refer to PostgreSQL user manual for more information about these).
 If you want to forbid access to these from the module,
 set the -DNO_LARGE option in the Python setup file.</p>
 <p class="last"><strong>These methods are specified by the tag [LO].</strong></p>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id19" id="query-executes-a-sql-command-string" name="query-executes-a-sql-command-string">3.1&nbsp;&nbsp;&nbsp;query - executes a SQL command string</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 query(command)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">command:</th><td class="field-body">SQL command (string)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name" colspan="2">pgqueryobject, None:</th></tr>
 <tr><td>&nbsp;</td><td class="field-body">result values</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">bad argument type, or too many arguments</td>
 </tr>
 <tr class="field"><th class="field-name">ValueError:</th><td class="field-body">empty SQL query or lost connection</td>
 </tr>
 <tr class="field"><th class="field-name" colspan="2">pg.ProgrammingError:</th></tr>
 <tr><td>&nbsp;</td><td class="field-body">error in query</td>
 </tr>
 <tr class="field"><th class="field-name" colspan="2">pg.InternalError':</th></tr>
 <tr><td>&nbsp;</td><td class="field-body">error during query processing</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method simply sends a SQL query to the database. If the query is an
 insert statement that inserted exactly one row into a table that has OIDs, the
 return value is the OID of the newly inserted row. If the query is an update
 or delete statement, or an insert statement that did not insert exactly one
 row in a table with OIDs, then the numer of rows affected is returned as a
 string. If it is a statement that returns rows as a result (usually a select
 statement, but maybe also an &quot;insert/update ... returning&quot; statement), this
 method returns a <cite>pgqueryobject</cite> that can be accessed via the <cite>getresult()</cite>
 or <cite>dictresult()</cite> method or simply printed. Otherwise, it returns <cite>None</cite>.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id20" id="reset-resets-the-connection" name="reset-resets-the-connection">3.2&nbsp;&nbsp;&nbsp;reset - resets the connection</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 reset()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd>None</dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many (any) arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method resets the current database connection.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id21" id="cancel-abandon-processing-of-current-sql-command" name="cancel-abandon-processing-of-current-sql-command">3.3&nbsp;&nbsp;&nbsp;cancel - abandon processing of current SQL command</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 cancel()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd>None</dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many (any) arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method requests that the server abandon processing
 of the current SQL command.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id22" id="close-close-the-database-connection" name="close-close-the-database-connection">3.4&nbsp;&nbsp;&nbsp;close - close the database connection</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 close()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd>None</dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many (any) arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method closes the database connection. The connection will
 be closed in any case when the connection is deleted but this
 allows you to explicitly close it. It is mainly here to allow
 the DB-SIG API wrapper to implement a close function.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id23" id="fileno-returns-the-socket-used-to-connect-to-the-database" name="fileno-returns-the-socket-used-to-connect-to-the-database">3.5&nbsp;&nbsp;&nbsp;fileno - returns the socket used to connect to the database</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 fileno()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many (any) arguments</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method returns the underlying socket id used to connect
 to the database. This is useful for use in select calls, etc.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id24" id="getnotify-gets-the-last-notify-from-the-server" name="getnotify-gets-the-last-notify-from-the-server">3.6&nbsp;&nbsp;&nbsp;getnotify - gets the last notify from the server</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 getnotify()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">tuple, None:</th><td class="field-body">last notify from server</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This methods try to get a notify from the server (from the SQL statement
 NOTIFY). If the server returns no notify, the methods returns None.
 Otherwise, it returns a tuple (couple) <cite>(relname, pid)</cite>, where <cite>relname</cite>
 is the name of the notify and <cite>pid</cite> the process id of the connection that
 triggered the notify. Remember to do a listen query first otherwise
 getnotify() will always return <cite>None</cite>.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id25" id="inserttable-insert-a-list-into-a-table" name="inserttable-insert-a-list-into-a-table">3.7&nbsp;&nbsp;&nbsp;inserttable - insert a list into a table</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 inserttable(table, values)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">table:</th><td class="field-body">the table name (string)</td>
 </tr>
 <tr class="field"><th class="field-name">values:</th><td class="field-body">list of rows values (list)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd>None</dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection, bad argument type, or too many arguments</td>
 </tr>
 <tr class="field"><th class="field-name">MemoryError:</th><td class="field-body">insert buffer could not be allocated</td>
 </tr>
 <tr class="field"><th class="field-name">ValueError:</th><td class="field-body">unsupported values</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method allow to <em>quickly</em> insert large blocks of data in a table:
 It inserts the whole values list into the given table. Internally, it
 uses the COPY command of the PostgreSQL database. The list is a list
 of tuples/lists that define the values for each inserted row. The rows
 values may contain string, integer, long or double (real) values.</dd>
 </dl>
 <div class="caution">
 <p class="first admonition-title">Caution!</p>
 <p class="last"><em>Be very careful</em>:
 This method doesn't typecheck the fields according to the table definition;
 it just look whether or not it knows how to handle such types.</p>
 </div>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id26" id="putline-writes-a-line-to-the-server-socket-da" name="putline-writes-a-line-to-the-server-socket-da">3.8&nbsp;&nbsp;&nbsp;putline - writes a line to the server socket [DA]</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 putline(line)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">line:</th><td class="field-body">line to be written (string)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd>None</dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection, bad parameter type, or too many parameters</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method allows to directly write a string to the server socket.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id27" id="getline-gets-a-line-from-server-socket-da" name="getline-gets-a-line-from-server-socket-da">3.9&nbsp;&nbsp;&nbsp;getline - gets a line from server socket [DA]</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 getline()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">string:</th><td class="field-body">the line read</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection</td>
 </tr>
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name">MemoryError:</th><td class="field-body">buffer overflow</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method allows to directly read a string from the server socket.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id28" id="endcopy-synchronizes-client-and-server-da" name="endcopy-synchronizes-client-and-server-da">3.10&nbsp;&nbsp;&nbsp;endcopy - synchronizes client and server [DA]</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 endcopy()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd>None</dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection</td>
 </tr>
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many parameters</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>The use of direct access methods may desynchonize client and server.
 This method ensure that client and server will be synchronized.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id29" id="locreate-create-a-large-object-in-the-database-lo" name="locreate-create-a-large-object-in-the-database-lo">3.11&nbsp;&nbsp;&nbsp;locreate - create a large object in the database [LO]</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 locreate(mode)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">mode:</th><td class="field-body">large object create mode</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">pglarge:</th><td class="field-body">object handling the PostGreSQL large object</td>
 </tr>
 </tbody>
 </table>
 </dd>
 </dl>
 <p>Exceptions raised:</p>
 <blockquote>
 <table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection, bad parameter type, or too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name" colspan="2">pg.OperationalError:</th></tr>
 <tr><td>&nbsp;</td><td class="field-body">creation error</td>
 </tr>
 </tbody>
 </table>
 </blockquote>
 <dl class="docutils">
 <dt>Description:</dt>
 <dd>This method creates a large object in the database. The mode can be defined
 by OR-ing the constants defined in the pg module (INV_READ, INV_WRITE and
 INV_ARCHIVE). Please refer to PostgreSQL user manual for a description of
 the mode values.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id30" id="getlo-build-a-large-object-from-given-oid-lo" name="getlo-build-a-large-object-from-given-oid-lo">3.12&nbsp;&nbsp;&nbsp;getlo - build a large object from given oid [LO]</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 getlo(oid)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">oid:</th><td class="field-body">OID of the existing large object (integer)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">pglarge:</th><td class="field-body">object handling the PostGreSQL large object</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection, bad parameter type, or too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name">ValueError:</th><td class="field-body">bad OID value (0 is invalid_oid)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method allows to reuse a formerly created large object through the
 <cite>pglarge</cite> interface, providing the user have its OID.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id31" id="loimport-import-a-file-to-a-large-object-lo" name="loimport-import-a-file-to-a-large-object-lo">3.13&nbsp;&nbsp;&nbsp;loimport - import a file to a large object [LO]</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 loimport(name)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">name:</th><td class="field-body">the name of the file to be imported (string)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">pglarge:</th><td class="field-body">object handling the PostGreSQL large object</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection, bad argument type, or too many arguments</td>
 </tr>
 <tr class="field"><th class="field-name" colspan="2">pg.OperationalError:</th></tr>
 <tr><td>&nbsp;</td><td class="field-body">error during file import</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This methods allows to create large objects in a very simple way. You just
 give the name of a file containing the data to be use.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id32" id="object-attributes" name="object-attributes">3.14&nbsp;&nbsp;&nbsp;Object attributes</a></h2>
 <p>Every <cite>pgobject</cite> defines a set of read-only attributes that describe the
 connection and its status. These attributes are:</p>
 <blockquote>
 <table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">host:</th><td class="field-body">the host name of the server (string)</td>
 </tr>
 <tr class="field"><th class="field-name">port:</th><td class="field-body">the port of the server (integer)</td>
 </tr>
 <tr class="field"><th class="field-name">db:</th><td class="field-body">the selected database (string)</td>
 </tr>
 <tr class="field"><th class="field-name">options:</th><td class="field-body">the connection options (string)</td>
 </tr>
 <tr class="field"><th class="field-name">tty:</th><td class="field-body">the connection debug terminal (string)</td>
 </tr>
 <tr class="field"><th class="field-name">user:</th><td class="field-body">user name on the database system (string)</td>
 </tr>
 <tr class="field"><th class="field-name" colspan="2">protocol_version:</th></tr>
 <tr><td>&nbsp;</td><td class="field-body">the frontend/backend protocol being used (integer)</td>
 </tr>
 <tr class="field"><th class="field-name">server_version:</th><td class="field-body">the backend version (integer, e.g. 80305 for 8.3.5)</td>
 </tr>
 <tr class="field"><th class="field-name">status:</th><td class="field-body">the status of the connection (integer: 1 - OK, 0 - bad)</td>
 </tr>
 <tr class="field"><th class="field-name">error:</th><td class="field-body">the last warning/error message from the server (string)</td>
 </tr>
 </tbody>
 </table>
 </blockquote>
 </div>
 </div>
 <div class="section">
 <h1><a class="toc-backref" href="#id33" id="the-db-wrapper-class" name="the-db-wrapper-class">4&nbsp;&nbsp;&nbsp;The DB wrapper class</a></h1>
 <p>The <cite>pgobject</cite> methods are wrapped in the class <cite>DB</cite>.
 The preferred way to use this module is as follows:</p>
 <pre class="literal-block">
 import pg

 db = pg.DB(...) # see below

 for r in db.query( # just for example
     &quot;&quot;&quot;SELECT foo,bar
        FROM foo_bar_table
        WHERE foo !~ bar&quot;&quot;&quot;
     ).dictresult():

     print '%(foo)s %(bar)s' % r
 </pre>
 <p>This class can be subclassed as in this example:</p>
 <pre class="literal-block">
 import pg

 class DB_ride(pg.DB):
   &quot;&quot;&quot;This class encapsulates the database functions and the specific
      methods for the ride database.&quot;&quot;&quot;

   def __init__(self):
       &quot;&quot;&quot;Opens a database connection to the rides database&quot;&quot;&quot;

       pg.DB.__init__(self, dbname = 'ride')
       self.query(&quot;&quot;&quot;SET DATESTYLE TO 'ISO'&quot;&quot;&quot;)

   [Add or override methods here]
 </pre>
 <p>The following describes the methods and variables of this class.</p>
 <div class="section">
 <h2><a class="toc-backref" href="#id34" id="initialization" name="initialization">4.1&nbsp;&nbsp;&nbsp;Initialization</a></h2>
 <p>The DB class is initialized with the same arguments as the connect
 function described in section 2. It also initializes a few
 internal variables. The statement <cite>db = DB()</cite> will open the
 local database with the name of the user just like connect() does.</p>
 <p>You can also initialize the DB class with an existing <cite>_pg</cite> or <cite>pgdb</cite>
 connection. Pass this connection as a single unnamed parameter, or as a
 single parameter named <cite>db</cite>. This allows you to use all of the methods
 of the DB class with a DB-API 2 compliant connection. Note that the
 <cite>close()</cite> and <cite>reopen()</cite> methods are inoperative in this case.</p>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id35" id="pkey-return-the-primary-key-of-a-table" name="pkey-return-the-primary-key-of-a-table">4.2&nbsp;&nbsp;&nbsp;pkey - return the primary key of a table</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 pkey(table)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">table:</th><td class="field-body">name of table</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">string:</th><td class="field-body">Name of the field which is the primary key of the table</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method returns the primary key of a table. For composite primary
 keys, the return value will be a frozenset. Note that this raises an
 exception if the table does not have a primary key.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id36" id="get-databases-get-list-of-databases-in-the-system" name="get-databases-get-list-of-databases-in-the-system">4.3&nbsp;&nbsp;&nbsp;get_databases - get list of databases in the system</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 get_databases()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">list:</th><td class="field-body">all databases in the system</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>Although you can do this with a simple select, it is added here for
 convenience.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id37" id="get-relations-get-list-of-relations-in-connected-database" name="get-relations-get-list-of-relations-in-connected-database">4.4&nbsp;&nbsp;&nbsp;get_relations - get list of relations in connected database</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 get_relations(kinds)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">kinds:</th><td class="field-body">a string or sequence of type letters</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>The type letters are <cite>r</cite> = ordinary table, <cite>i</cite> = index, <cite>S</cite> = sequence,
 <cite>v</cite> = view, <cite>c</cite> = composite type, <cite>s</cite> = special, <cite>t</cite> = TOAST table.
 If <cite>kinds</cite> is None or an empty string, all relations are returned (this is
 also the default). Although you can do this with a simple select, it is
 added here for convenience.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id38" id="get-tables-get-list-of-tables-in-connected-database" name="get-tables-get-list-of-tables-in-connected-database">4.5&nbsp;&nbsp;&nbsp;get_tables - get list of tables in connected database</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 get_tables()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Returns:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">list:</th><td class="field-body">all tables in connected database</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>Although you can do this with a simple select, it is added here for
 convenience.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id39" id="get-attnames-get-the-attribute-names-of-a-table" name="get-attnames-get-the-attribute-names-of-a-table">4.6&nbsp;&nbsp;&nbsp;get_attnames - get the attribute names of a table</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 get_attnames(table)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">table:</th><td class="field-body">name of table</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Returns:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">dictionary:</th><td class="field-body">The keys are the attribute names,
 the values are the type names of the attributes.</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>Given the name of a table, digs out the set of attribute names.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id40" id="has-table-privilege-check-whether-current-user-has-specified-table-privilege" name="has-table-privilege-check-whether-current-user-has-specified-table-privilege">4.7&nbsp;&nbsp;&nbsp;has_table_privilege - check whether current user has specified table privilege</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 has_table_privilege(table, privilege)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">table:</th><td class="field-body">name of table</td>
 </tr>
 <tr class="field"><th class="field-name">privilege:</th><td class="field-body">privilege to be checked - default is 'select'</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>Returns True if the current user has the specified privilege for the table.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id41" id="get-get-a-row-from-a-database-table-or-view" name="get-get-a-row-from-a-database-table-or-view">4.8&nbsp;&nbsp;&nbsp;get - get a row from a database table or view</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 get(table, arg, [keyname])
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">table:</th><td class="field-body">name of table or view</td>
 </tr>
 <tr class="field"><th class="field-name">arg:</th><td class="field-body">either a dictionary or the value to be looked up</td>
 </tr>
 <tr class="field"><th class="field-name">keyname:</th><td class="field-body">name of field to use as key (optional)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">dictionary:</th><td class="field-body">The keys are the attribute names,
 the values are the row values.</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method is the basic mechanism to get a single row. It assumes
 that the key specifies a unique row. If <cite>keyname</cite> is not specified
 then the primary key for the table is used. If <cite>arg</cite> is a dictionary
 then the value for the key is taken from it and it is modified to
 include the new values, replacing existing values where necessary.
 For a composite key, <cite>keyname</cite> can also be a sequence of key names.
 The OID is also put into the dictionary if the table has one, but in
 order to allow the caller to work with multiple tables, it is munged
 as <cite>oid(schema.table)</cite>.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id42" id="insert-insert-a-row-into-a-database-table" name="insert-insert-a-row-into-a-database-table">4.9&nbsp;&nbsp;&nbsp;insert - insert a row into a database table</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 insert(table, [d,] [return_changes,] [key = val, ...])
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">table:</th><td class="field-body">name of table</td>
 </tr>
 <tr class="field"><th class="field-name">d:</th><td class="field-body">optional dictionary of values</td>
 </tr>
 <tr class="field"><th class="field-name">return_changes:</th><td class="field-body">Return values in new row - default True</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">dictionary:</th><td class="field-body">The dictionary of values inserted</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd><p class="first">This method inserts a row into a table.  If the optional dictionary is
 not supplied then the required values must be included as keyword/value
 pairs.  If a dictionary is supplied then any keywords provided will be
 added to or replace the entry in the dictionary.</p>
 <p>The dictionary is then, if possible, reloaded with the values actually
 inserted in order to pick up values modified by rules, triggers, etc.</p>
 <p>Due to the way that this function works in PostgreSQL versions below
 8.2, you may find inserts taking longer and longer as your table gets
 bigger.  If this happens and it is a table with OID but no primary key
 you can overcome this problem by simply adding an index onto the OID of
 any table that you think may get large over time. You may also consider
 using the inserttable() method described in section 3.</p>
 <p>Note: With PostgreSQL versions before 8.2 the table being inserted to
 must have a primary key or an OID to use this method properly.  If not
 then the dictionary will not be filled in as described.  Also, if this
 method is called within a transaction, the transaction will abort.</p>
 <p class="last">Note: The method currently doesn't support insert into views
 although PostgreSQL does.</p>
 </dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id43" id="update-update-a-row-in-a-database-table" name="update-update-a-row-in-a-database-table">4.10&nbsp;&nbsp;&nbsp;update - update a row in a database table</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 update(table, [d,] [key = val, ...])
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">table:</th><td class="field-body">name of table</td>
 </tr>
 <tr class="field"><th class="field-name">d:</th><td class="field-body">optional dictionary of values</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">dictionary:</th><td class="field-body">the new row</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd><p class="first">Similar to insert but updates an existing row.  The update is based on the
 OID value as munged by get or passed as keyword, or on the primary key of
 the table.  The dictionary is modified, if possible, to reflect any changes
 caused by the update due to triggers, rules, default values, etc.</p>
 <p class="last">Like insert, the dictionary is optional and updates will be performed
 on the fields in the keywords.  There must be an OID or primary key
 either in the dictionary where the OID must be munged, or in the keywords
 where it can be simply the string &quot;oid&quot;.</p>
 </dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id44" id="clear-clears-row-values-in-memory" name="clear-clears-row-values-in-memory">4.11&nbsp;&nbsp;&nbsp;clear - clears row values in memory</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 clear(table, [a])
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">table:</th><td class="field-body">name of table</td>
 </tr>
 <tr class="field"><th class="field-name">a:</th><td class="field-body">optional dictionary of values</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">dictionary:</th><td class="field-body">an empty row</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd><p class="first">This method clears all the attributes to values determined by the types.
 Numeric types are set to 0, Booleans are set to 'f', dates are set
 to 'now()' and everything else is set to the empty string.
 If the array argument is present, it is used as the array and any entries
 matching attribute names are cleared with everything else left unchanged.</p>
 <p class="last">If the dictionary is not supplied a new one is created.</p>
 </dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id45" id="delete-delete-a-row-from-a-database-table" name="delete-delete-a-row-from-a-database-table">4.12&nbsp;&nbsp;&nbsp;delete - delete a row from a database table</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 delete(table, [d,] [key = val, ...])
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">table:</th><td class="field-body">name of table</td>
 </tr>
 <tr class="field"><th class="field-name">d:</th><td class="field-body">optional dictionary of values</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Returns:</dt>
 <dd>None</dd>
 <dt>Description:</dt>
 <dd>This method deletes the row from a table.  It deletes based on the OID value
 as munged by get or passed as keyword, or on the primary key of the table.
 The return value is the number of deleted rows (i.e. 0 if the row did not
 exist and 1 if the row was deleted).</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id46" id="id1" name="id1">4.13&nbsp;&nbsp;&nbsp;escape_string - escape a string for use within SQL</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 escape_string(string)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">string:</th><td class="field-body">the string that is to be escaped</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">str:</th><td class="field-body">the escaped string</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>Similar to the module function with the same name, but the
 behavior of this method is adjusted depending on the connection properties
 (such as character encoding).</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id47" id="id2" name="id2">4.14&nbsp;&nbsp;&nbsp;escape_bytea - escape binary data for use within SQL as type <cite>bytea</cite></a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 escape_bytea(datastring)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">datastring:</th><td class="field-body">string containing the binary data that is to be escaped</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">str:</th><td class="field-body">the escaped string</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>Similar to the module function with the same name, but the
 behavior of this method is adjusted depending on the connection properties
 (in particular, whether standard-conforming strings are enabled).</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id48" id="id3" name="id3">4.15&nbsp;&nbsp;&nbsp;unescape_bytea -- unescape <cite>bytea</cite> data that has been retrieved as text</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 unescape_bytea(string)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">datastring:</th><td class="field-body">the <cite>bytea</cite> data string that has been retrieved as text</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">str:</th><td class="field-body">string containing the binary data</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>See the module function with the same name.</dd>
 </dl>
 </div>
 </div>
 <div class="section">
 <h1><a class="toc-backref" href="#id49" id="pgqueryobject-methods" name="pgqueryobject-methods">5&nbsp;&nbsp;&nbsp;pgqueryobject methods</a></h1>
 <div class="section">
 <h2><a class="toc-backref" href="#id50" id="getresult-get-query-values-as-list-of-tuples" name="getresult-get-query-values-as-list-of-tuples">5.1&nbsp;&nbsp;&nbsp;getresult - get query values as list of tuples</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 getresult()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">list:</th><td class="field-body">result values as a list of tuples</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name" colspan="2">pg.InternalError:</th></tr>
 <tr><td>&nbsp;</td><td class="field-body">invalid previous result</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method returns the list of the values returned by the query.
 More information about this result may be accessed using listfields(),
 fieldname() and fieldnum() methods.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id51" id="dictresult-get-query-values-as-list-of-dictionaries" name="dictresult-get-query-values-as-list-of-dictionaries">5.2&nbsp;&nbsp;&nbsp;dictresult - get query values as list of dictionaries</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 dictresult()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">list:</th><td class="field-body">result values as a list of dictionaries</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name" colspan="2">pg.InternalError:</th></tr>
 <tr><td>&nbsp;</td><td class="field-body">invalid previous result</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method returns the list of the values returned by the query
 with each tuple returned as a dictionary with the field names
 used as the dictionary index.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id52" id="listfields-lists-fields-names-of-previous-query-result" name="listfields-lists-fields-names-of-previous-query-result">5.3&nbsp;&nbsp;&nbsp;listfields - lists fields names of previous query result</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 listfields()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">list:</th><td class="field-body">field names</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name" colspan="2">pg.InternalError:</th></tr>
 <tr><td>&nbsp;</td><td class="field-body">invalid previous result, or lost connection</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method returns the list of names of the fields defined for the
 query result. The fields are in the same order as the result values.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id53" id="fieldname-fieldnum-field-name-number-conversion" name="fieldname-fieldnum-field-name-number-conversion">5.4&nbsp;&nbsp;&nbsp;fieldname, fieldnum - field name/number conversion</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 fieldname(i)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">i:</th><td class="field-body">field number (integer)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">string:</th><td class="field-body">field name</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection, bad parameter type, or too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name">ValueError:</th><td class="field-body">invalid field number</td>
 </tr>
 <tr class="field"><th class="field-name" colspan="2">pg.InternalError:</th></tr>
 <tr><td>&nbsp;</td><td class="field-body">invalid previous result, or lost connection</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method allows to find a field name from its rank number. It can be
 useful for displaying a result. The fields are in the same order as the
 result values.</dd>
 </dl>
 <p>Syntax:</p>
 <pre class="literal-block">
 fieldnum(name)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">name:</th><td class="field-body">field name (string)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">integer:</th><td class="field-body">field number</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection, bad parameter type, or too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name">ValueError:</th><td class="field-body">unknown field name</td>
 </tr>
 <tr class="field"><th class="field-name" colspan="2">pg.InternalError:</th></tr>
 <tr><td>&nbsp;</td><td class="field-body">invalid previous result, or lost connection</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method returns a field number from its name. It can be used to
 build a function that converts result list strings to their correct
 type, using a hardcoded table definition. The number returned is the
 field rank in the result values list.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id54" id="ntuples-return-number-of-tuples-in-query-object" name="ntuples-return-number-of-tuples-in-query-object">5.5&nbsp;&nbsp;&nbsp;ntuples - return number of tuples in query object</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 ntuples()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">integer:</th><td class="field-body">number of tuples in <cite>pgqueryobject</cite></td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">Too many arguments.</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method returns the number of tuples found in a query.</dd>
 </dl>
 </div>
 </div>
 <div class="section">
 <h1><a class="toc-backref" href="#id55" id="large-objects-pglarge" name="large-objects-pglarge">6&nbsp;&nbsp;&nbsp;Large objects: pglarge</a></h1>
 <p>This object handles all the request concerning a PostgreSQL large object. It
 embeds and hides all the &quot;recurrent&quot; variables (object OID and connection),
 exactly in the same way <cite>pgobjects</cite> do, thus only keeping significant
 parameters in function calls. It keeps a reference to the <cite>pgobject</cite> used for
 its creation, sending requests though with its parameters. Any modification but
 dereferencing the <cite>pgobject</cite> will thus affect the <cite>pglarge</cite> object.
 Dereferencing the initial <cite>pgobject</cite> is not a problem since Python won't
 deallocate it before the <cite>pglarge</cite> object dereference it.
 All functions return a generic error message on call error, whatever the
 exact error was. The <cite>error</cite> attribute of the object allow to get the exact
 error message.</p>
 <p>See also the PostgreSQL programmer's guide for more information about the
 large object interface.</p>
 <div class="section">
 <h2><a class="toc-backref" href="#id56" id="open-opens-a-large-object" name="open-opens-a-large-object">6.1&nbsp;&nbsp;&nbsp;open - opens a large object</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 open(mode)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">mode:</th><td class="field-body">open mode definition (integer)</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd>None</dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection, bad parameter type, or too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name">IOError:</th><td class="field-body">already opened object, or open error</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method opens a large object for reading/writing, in the same way than
 the Unix open() function. The mode value can be obtained by OR-ing the
 constants defined in the pgmodule (INV_READ, INV_WRITE).</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id57" id="close-closes-a-large-object" name="close-closes-a-large-object">6.2&nbsp;&nbsp;&nbsp;close - closes a large object</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 close()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd>None</dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection</td>
 </tr>
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name">IOError:</th><td class="field-body">object is not opened, or close error</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method closes a previously opened large object, in the same way than
 the Unix close() function.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id58" id="read-write-tell-seek-unlink-file-like-large-object-handling" name="read-write-tell-seek-unlink-file-like-large-object-handling">6.3&nbsp;&nbsp;&nbsp;read, write, tell, seek, unlink - file like large object handling</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 read(size)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">size:</th><td class="field-body">maximal size of the buffer to be read</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">sized string:</th><td class="field-body">the read buffer</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection, invalid object,
 bad parameter type, or too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name">ValueError:</th><td class="field-body">if <cite>size</cite> is negative</td>
 </tr>
 <tr class="field"><th class="field-name">IOError:</th><td class="field-body">object is not opened, or read error</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This function allows to read data from a large object, starting at current
 position.</dd>
 </dl>
 <p>Syntax:</p>
 <pre class="literal-block">
 write(string)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>(sized) string - buffer to be written</dd>
 <dt>Return type:</dt>
 <dd>None</dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection, bad parameter type, or too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name">IOError:</th><td class="field-body">object is not opened, or write error</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This function allows to write data to a large object, starting at current
 position.</dd>
 </dl>
 <p>Syntax:</p>
 <pre class="literal-block">
 seek(offset, whence)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">offset:</th><td class="field-body">position offset</td>
 </tr>
 <tr class="field"><th class="field-name">whence:</th><td class="field-body">positional parameter</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">integer:</th><td class="field-body">new position in object</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">binvalid connection or invalid object,
 bad parameter type, or too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name">IOError:</th><td class="field-body">object is not opened, or seek error</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method allows to move the position cursor in the large object. The
 whence parameter can be obtained by OR-ing the constants defined in the
 <cite>pg</cite> module (<cite>SEEK_SET</cite>, <cite>SEEK_CUR</cite>, <cite>SEEK_END</cite>).</dd>
 </dl>
 <p>Syntax:</p>
 <pre class="literal-block">
 tell()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">integer:</th><td class="field-body">current position in large object</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection or invalid object</td>
 </tr>
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name">IOError:</th><td class="field-body">object is not opened, or seek error</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This method allows to get the current position in the large object.</dd>
 </dl>
 <p>Syntax:</p>
 <pre class="literal-block">
 unlink()
 </pre>
 <dl class="docutils">
 <dt>Parameter:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd>None</dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection or invalid object</td>
 </tr>
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name">IOError:</th><td class="field-body">object is not closed, or unlink error</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This methods unlinks (deletes) the PostgreSQL large object.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id59" id="size-gives-the-large-object-size" name="size-gives-the-large-object-size">6.4&nbsp;&nbsp;&nbsp;size - gives the large object size</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 size()
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd>None</dd>
 <dt>Return type:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">integer:</th><td class="field-body">the large object size</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection or invalid object</td>
 </tr>
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name">IOError:</th><td class="field-body">object is not opened, or seek/tell error</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This (composite) method allows to get the size of a large object. It was
 implemented because this function is very useful for a web interfaced
 database. Currently, the large object needs to be opened first.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id60" id="export-saves-a-large-object-to-a-file" name="export-saves-a-large-object-to-a-file">6.5&nbsp;&nbsp;&nbsp;export - saves a large object to a file</a></h2>
 <p>Syntax:</p>
 <pre class="literal-block">
 export(name)
 </pre>
 <dl class="docutils">
 <dt>Parameters:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">name:</th><td class="field-body">file to be created</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Return type:</dt>
 <dd>None</dd>
 <dt>Exceptions raised:</dt>
 <dd><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">TypeError:</th><td class="field-body">invalid connection or invalid object,
 bad parameter type, or too many parameters</td>
 </tr>
 <tr class="field"><th class="field-name">IOError:</th><td class="field-body">object is not closed, or export error</td>
 </tr>
 </tbody>
 </table>
 </dd>
 <dt>Description:</dt>
 <dd>This methods allows to dump the content of a large object in a very simple
 way. The exported file is created on the host of the program, not the
 server host.</dd>
 </dl>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id61" id="id4" name="id4">6.6&nbsp;&nbsp;&nbsp;Object attributes</a></h2>
 <p><cite>pglarge</cite> objects define a read-only set of attributes that allow to get
 some information about it. These attributes are:</p>
 <blockquote>
 <table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">oid:</th><td class="field-body">the OID associated with the object</td>
 </tr>
 <tr class="field"><th class="field-name">pgcnx:</th><td class="field-body">the <cite>pgobject</cite> associated with the object</td>
 </tr>
 <tr class="field"><th class="field-name">error:</th><td class="field-body">the last warning/error message of the connection</td>
 </tr>
 </tbody>
 </table>
 </blockquote>
 <div class="caution">
 <p class="first admonition-title">Caution!</p>
 <p class="last"><em>Be careful</em>:
 In multithreaded environments, <cite>error</cite> may be modified by another thread
 using the same pgobject. Remember these object are shared, not duplicated.
 You should provide some locking to be able if you want to check this.
 The <cite>oid</cite> attribute is very interesting because it allow you reuse the OID
 later, creating the <cite>pglarge</cite> object with a <cite>pgobject</cite> getlo() method call.</p>
 </div>
 </div>
 </div>
 </div>
 </body>
 </html>