http://git-wip-us.apache.org/repos/asf/incubator-hawq/blob/192cff1f/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pg.html ---------------------------------------------------------------------- diff --git a/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pg.html b/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pg.html new file mode 100644 index 0000000..2e90378 --- /dev/null +++ b/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pg.html @@ -0,0 +1,2429 @@ +<?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 Introduction</a></li> +<li><a class="reference" href="#module-functions-and-constants" id="id6" name="id6">2 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 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 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 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 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 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 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 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 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 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 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 Module constants</a></li> +</ul> +</li> +<li><a class="reference" href="#connection-objects-pgobject" id="id18" name="id18">3 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 query - executes a SQL command string</a></li> +<li><a class="reference" href="#reset-resets-the-connection" id="id20" name="id20">3.2 reset - resets the connection</a></li> +<li><a class="reference" href="#cancel-abandon-processing-of-current-sql-command" id="id21" name="id21">3.3 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 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 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 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 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 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 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 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 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 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 loimport - import a file to a large object [LO]</a></li> +<li><a class="reference" href="#object-attributes" id="id32" name="id32">3.14 Object attributes</a></li> +</ul> +</li> +<li><a class="reference" href="#the-db-wrapper-class" id="id33" name="id33">4 The DB wrapper class</a><ul class="auto-toc"> +<li><a class="reference" href="#initialization" id="id34" name="id34">4.1 Initialization</a></li> +<li><a class="reference" href="#pkey-return-the-primary-key-of-a-table" id="id35" name="id35">4.2 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 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 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 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 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 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 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 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 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 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 delete - delete a row from a database table</a></li> +<li><a class="reference" href="#id1" id="id46" name="id46">4.13 escape_string - escape a string for use within SQL</a></li> +<li><a class="reference" href="#id2" id="id47" name="id47">4.14 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 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 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 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 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 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 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 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 Large objects: pglarge</a><ul class="auto-toc"> +<li><a class="reference" href="#open-opens-a-large-object" id="id56" name="id56">6.1 open - opens a large object</a></li> +<li><a class="reference" href="#close-closes-a-large-object" id="id57" name="id57">6.2 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 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 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 export - saves a large object to a file</a></li> +<li><a class="reference" href="#id4" id="id61" name="id61">6.6 Object attributes</a></li> +</ul> +</li> +</ul> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id5" id="introduction" name="introduction">1 Introduction</a></h1> +<p>You may either choose to use the +<a class="reference" href="pg.html">"classic" 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 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 "default variables" that override +the environment variables used by PostgreSQL.</p> +<p>These "default variables" 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 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> </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 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 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 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 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 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 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 "SQL injection" +attacks wherein unwanted SQL commands are fed to your database.</p> +</div> +<p>Example:</p> +<pre class="literal-block"> +name = raw_input("Name? ") +phone = con.query("select phone from employees" + " where name='%s'" % 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 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("update pictures set img='%s' where name='Garfield'" + % 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 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( + "select img from pictures where name='Garfield'").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 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 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> </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> </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> </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 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 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> </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> </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> </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 "insert/update ... returning" 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 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 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 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 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 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 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 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 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 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 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> </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 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 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> </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 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> </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 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 + """SELECT foo,bar + FROM foo_bar_table + WHERE foo !~ bar""" + ).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): + """This class encapsulates the database functions and the specific + methods for the ride database.""" + + def __init__(self): + """Opens a database connection to the rides database""" + + pg.DB.__init__(self, dbname = 'ride') + self.query("""SET DATESTYLE TO 'ISO'""") + + [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 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 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 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 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 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 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 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 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 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 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 "oid".</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 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 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 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 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 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 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 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> </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 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> </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 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> </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 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> </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> </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 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" i
<TRUNCATED>
