From 5bbad66e0ecf886ce3af03035e5f256ecc25b21e Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Sun, 4 Mar 2001 18:54:07 +0000
Subject: [PATCH] PyGreSQL documentation. Based on the README, converted to
DocBook by Mikhail Terekhov <terekhov@emc.com>.
---
doc/src/sgml/filelist.sgml | 3 +-
doc/src/sgml/libpq.sgml | 6 +-
doc/src/sgml/programmer.sgml | 3 +-
doc/src/sgml/pygresql.sgml | 4482 ++++++++++++++++++++++++++++++++++
4 files changed, 4489 insertions(+), 5 deletions(-)
create mode 100644 doc/src/sgml/pygresql.sgml
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index f38c6b0cd22..b56bd4c24e4 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.8 2001/02/04 15:28:18 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.9 2001/03/04 18:54:07 petere Exp $ -->
<!entity history SYSTEM "history.sgml">
<!entity info SYSTEM "info.sgml">
@@ -62,6 +62,7 @@
<!entity libpq SYSTEM "libpq.sgml">
<!entity libpqpp SYSTEM "libpq++.sgml">
<!entity libpgtcl SYSTEM "libpgtcl.sgml">
+<!entity pygresql SYSTEM "pygresql.sgml">
<!entity lisp SYSTEM "lisp.sgml">
<!entity lobj SYSTEM "lobj.sgml">
<!entity odbc SYSTEM "odbc.sgml">
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 13b69533d2c..53455d7853f 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,9 +1,9 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.57 2001/01/20 20:59:28 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.58 2001/03/04 18:54:07 petere Exp $
-->
- <chapter id="libpq-chapter">
- <title id="libpq">libpq - C Library</title>
+ <chapter id="libpq">
+ <title>libpq - C Library</title>
<para>
<filename>libpq</filename> is the <acronym>C</acronym>
diff --git a/doc/src/sgml/programmer.sgml b/doc/src/sgml/programmer.sgml
index f4f3812fdd1..7cb73ac5e42 100644
--- a/doc/src/sgml/programmer.sgml
+++ b/doc/src/sgml/programmer.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.34 2001/02/04 15:28:18 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.35 2001/03/04 18:54:07 petere Exp $
PostgreSQL Programmer's Guide.
-->
@@ -48,6 +48,7 @@ PostgreSQL Programmer's Guide.
&ecpg;
&odbc;
&jdbc;
+ &pygresql;
&lisp;
</part>
diff --git a/doc/src/sgml/pygresql.sgml b/doc/src/sgml/pygresql.sgml
new file mode 100644
index 00000000000..28c13d5daa5
--- /dev/null
+++ b/doc/src/sgml/pygresql.sgml
@@ -0,0 +1,4482 @@
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/pygresql.sgml,v 1.1 2001/03/04 18:54:07 petere Exp $ -->
+
+<chapter id="pygresql">
+ <title><application>PyGreSQL</application> - <application>Python</application> Interface</title>
+
+ <note>
+ <title>Author</title>
+ <para>
+ Written by D'Arcy J.M. Cain (<email>darcy@druid.net</email>).
+ Based heavily on code written by Pascal Andre
+ <email>andre@chimay.via.ecp.fr</email>. Copyright © 1995,
+ Pascal Andre. Further modifications Copyright © 1997-2000 by
+ D'Arcy J.M. Cain.
+ </para>
+ </note>
+
+
+<![IGNORE[
+ <sect1 id="pygresql-install">
+ <title>Installation</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ If you are on <acronym>NetBSD</acronym>, look in the packages
+ directory under databases. If it isn't there yet, it should be
+ there shortly. You can also pick up the package files from
+ <ulink url="ftp://ftp.druid.net/pub/distrib/pygresql.pkg.tgz"
+ >ftp://ftp.druid.net/pub/distrib/pygresql.pkg.tgz</ulink>. There
+ is also a package in the <acronym>FreeBSD</acronym> ports
+ collection but as I write this it is at version 2.1. I will try
+ to get that updated as well.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ For Linux installation look at <filename>README.linux</filename>.
+ If you're on an <acronym>x86</acronym> system that uses
+ <acronym>RPMs</acronym>, then you can pick up an
+ <acronym>RPM</acronym> at <ulink
+ url="ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm"
+ >ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm</ulink>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Note that if you are using the <acronym>DB-API</acronym> module
+ you must also install <acronym>mxDateTime</acronym> from <ulink
+ url="http://starship.python.net/~lemburg/mxDateTime.html"
+ >http://starship.python.net/~lemburg/mxDateTime.html</ulink>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Also, check out <filename>setup.py</filename> for an alternate
+ method of installing the package using Python's Distutils.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ You have two options. You can compile
+ <productname>PyGreSQL</productname> as a stand-alone module or you
+ can build it into the <productname>Python</productname>
+ interpreter.
+ </para>
+
+ <sect2>
+ <title>General</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ You must first have installed <productname>Python</productname>
+ and <productname>PostgreSQL</productname> on your system. The
+ header files and developer's libraries for both
+ <productname>Python</productname> and
+ <productname>PostgreSQL</productname> must be installed on your
+ system before you can build <productname>PyGreSQL</productname>.
+ If you built both <productname>Python</productname> and
+ <productname>PostgreSQL</productname> from source, you should be
+ fine. If your system uses some package mechanism (such as
+ <acronym>RPM</acronym> or <acronym>NetBSD</acronym> packages),
+ then you probably need to install packages such as
+ <acronym>Python-devel</acronym> in addition to the
+ <productname>Python</productname> package.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <productname>PyGreSQL</productname> is implemented as three
+ parts, a C module labeled <acronym>_pg</acronym> and two
+ <productname>Python</productname> wrappers called
+ <filename>pg.py</filename> and <filename>pgdb.py</filename>.
+ This changed between 2.1 and 2.2 and again in 3.0. These
+ changes should not affect any existing programs but the
+ installation is slightly different.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Download and unpack the <productname>PyGreSQL</productname>
+ tarball if you haven't already done so.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Stand-alone</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ In the directory containing <filename>pgmodule.c</filename>, run
+ the following command
+
+<programlisting>
+cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c
+</programlisting>
+
+ where:
+ <itemizedlist>
+ <listitem>
+ <para>
+ [pyInc] = path of the <productname>Python</productname>
+ include (usually <filename>Python.h</filename>)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ [pgInc] = path of the <productname>PostgreSQL</productname>
+ include (usually <filename>postgres.h</filename>)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ [pgLib] = path of the <productname>PostgreSQL</productname>
+ libraries (usually <filename>libpq.so</filename> or
+ <filename>libpq.a</filename>)
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ Some options may be added to this line:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>-DNO_DEF_VAR</literal> - no default variables
+ support
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>-DNO_DIRECT</literal> - no direct access methods
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>-DNO_LARGE</literal> - no large object support
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>-DNO_SNPRINTF</literal> - if running a system with
+ no snprintf call
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>-DNO_PQSOCKET</literal> - if running an older
+ <productname>PostgreSQL</productname>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ On some systems you may need to include
+ <literal>-lcrypt</literal> in the list of libraries to make it
+ compile.
+
+ Define <literal>DNO_PQSOCKET</literal> if you are using a
+ version of <productname>PostgreSQL</productname> before 6.4 that
+ does not have the <function>PQsocket</function> function. The
+ other options will be described in the next sections.
+ </para>
+ </listitem>
+ <listitem>
+
+ <para>
+ Test the new module. Something like the following should work.
+<screen>
+<prompt>$</prompt> <userinput>python</userinput>
+
+<prompt>>>></prompt> <userinput>import _pg</userinput>
+<prompt>>>></prompt> <userinput>db = _pg.connect('thilo', 'localhost')</userinput>
+<prompt>>>></prompt> <userinput>db.query("INSERT INTO test VALUES ('ping', 'pong');")</userinput>
+18304
+<prompt>>>></prompt> <userinput>db.query("SELECT * FROM test;")</userinput>
+ eins | zwei
+------+------
+ ping | pong
+(1 row)
+</screen>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Finally, move the <filename>_pg.so</filename>,
+ <filename>pg.py</filename>, and <filename>pgdb.py</filename>
+ to a directory in your <literal>PYTHONPATH</literal>.
+ A good place would be
+ <filename>/usr/lib/python1.5/site-python</filename>
+ if your <productname>Python</productname> modules are in
+ <filename>/usr/lib/python1.5</filename>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+
+ <sect2>
+ <title>Built-in to python interpreter</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Find the directory where your '<filename>Setup</filename>'
+ file lives (usually <filename>??/Modules</filename>) in
+ the <productname>Python</productname> source hierarchy and
+ copy or symlink the '<filename>pgmodule.c</filename>' file there.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the following line to your Setup file
+ <ProgramListing>
+_pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems
+ </ProgramListing>
+ where:
+ <itemizedlist>
+ <listitem>
+ <para>
+ [pgInc] = path of the <productname>PostgreSQL</productname>
+ include (usually <filename>postgres.h</filename>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ [pgLib] = path of the <productname>PostgreSQL</productname>
+ libraries (usually <filename>libpq.so</filename>
+ or <filename>libpq.a</filename>)
+ </para>
+ </listitem>
+ </itemizedlist>
+ Some options may be added to this line:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>-DNO_DEF_VAR</literal> - no default variables
+ support
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>-DNO_DIRECT</literal> - no direct access methods
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>-DNO_LARGE</literal> - no large object support
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>-DNO_SNPRINTF</literal> - if running a system with
+ no snprintf call
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>-DNO_PQSOCKET</literal> - if running an older
+ <productname>PostgreSQL</productname>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ Define <literal>DNO_PQSOCKET</literal> if you are using a version of
+ <productname>PostgreSQL</productname> before 6.4
+ that does not have the <function>PQsocket</function> function.
+ The other options will be described in the next sections.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you want a shared module, make sure that the
+ "<literal>*shared*</literal>" keyword is uncommented and
+ add the above line below it. You used to need to install
+ your shared modules with "make sharedinstall" but this no
+ longer seems to be true.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Copy <filename>pg.py</filename> to the lib directory where
+ the rest of your modules are. For example, that's
+ <filename>/usr/local/lib/Python</filename> on my system.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Rebuild <productname>Python</productname> from the root
+ directory of the <productname>Python</productname> source
+ hierarchy by running
+ <ProgramListing>
+make -f Makefile.pre.in boot
+make && make install
+ </ProgramListing>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ For more details read the documentation at the top of
+ <filename>Makefile.pre.in</filename>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ </sect1>
+
+]]>
+
+ <sect1 id="pygresql-pg">
+ <title>The <literal>pg</literal> Module</title>
+
+ <para>
+ You may either choose to use the old mature interface provided by
+ the <literal>pg</literal> module or otherwise the newer
+ <literal>pgdb</literal> interface compliant with the <ulink
+ url="http://www.python.org/topics/database/DatabaseAPI-2.0.html"
+ ><acronym>DB-API 2.0</acronym></ulink> specification developed by
+ the <productname>Python</productname> <acronym>DB-SIG</acronym>.
+ </para>
+
+ <para>
+ Here we describe only the older <literal>pg</literal>
+ <acronym>API</acronym>. As long as
+ <productname>PyGreSQL</productname> does not contain a description
+ of the <acronym>DB-API</acronym> you should read about the
+ <acronym>API</acronym> at <ulink
+ url="http://www.python.org/topics/database/DatabaseAPI-2.0.html"
+ >http://www.python.org/topics/database/DatabaseAPI-2.0.html</ulink>.
+ </para>
+
+ <para>
+ A tutorial-like introduction to the <acronym>DB-API</acronym> can
+ be found at <ulink
+ url="http://www2.linuxjournal.com/lj-issues/issue49/2605.html"
+ >http://www2.linuxjournal.com/lj-issues/issue49/2605.html</ulink>
+ </para>
+
+ <para>
+ The <literal>pg</literal> module defines three objects:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <classname>pgobject</classname>, which handles the connection and all the
+ requests to the database,
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <classname>pglargeobject</classname>, which handles all the accesses
+ to <productname>Postgres</productname> large objects, and
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>pgqueryobject</literal> that handles query results.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ If you want to see a simple example of the use of some of these
+ functions, see <ulink url="http://www.druid.net/rides"
+ >http://www.druid.net/rides</ulink> where I have a link at the
+ bottom to the actual <productname>Python</productname> code for the
+ page.
+ </para>
+
+ <sect2>
+ <title>Constants</title>
+
+ <para>
+ Some constants are defined in the <literal>pg</literal> module
+ dictionary. They are intended to be used as a parameters for
+ methods calls. You should refer to the <literal>libpq</literal>
+ description (<xref linkend="libpq">) for more information about
+ them. These constants are:
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>INV_READ</varname></term>
+ <term><varname>INV_WRITE</varname></term>
+ <term><varname>INV_ARCHIVE</varname></term>
+ <listitem>
+ <para>
+ large objects access modes, used by
+ <function>(pgobject.)locreate</function> and
+ <function>(pglarge.)open</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>SEEK_SET</varname></term>
+ <term><varname>SEEK_CUR</varname></term>
+ <term><varname>SEEK_END</varname></term>
+ <listitem>
+ <para>
+ positional flags, used by <function>(pglarge.)seek</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>version</varname></term>
+ <term><varname>__version__</varname></term>
+ <listitem>
+ <para>
+ constants that give the current version
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
+ </sect1>
+
+
+ <sect1 id="pygresql-pg-functions">
+ <title><literal>pg</literal> Module Functions</title>
+
+ <para>
+ <literal>pg</literal> module defines only a few methods that allow
+ to connect to a database and to define <quote>default
+ variables</quote> that override the environment variables used by
+ <productname>PostgreSQL</productname>.
+ </para>
+
+ <para>
+ These <quote>default variables</quote> 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 <acronym>-DNO_DEF_VAR</acronym> option in the Python
+ Setup file. Methods relative to this are specified by te tag [DV].
+ </para>
+
+ <para>
+ All variables are set to <symbol>None</symbol> at module
+ initialization, specifying that standard environment variables
+ should be used.
+ </para>
+
+ <refentry id="pygresql-connect">
+ <refmeta>
+ <refentrytitle>connect</refentrytitle>
+ <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>connect</refname>
+ <refpurpose>opens a connection to the database server</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+connect(<optional><replaceable>dbname</replaceable></optional>, <optional><replaceable>host</replaceable></optional>, <optional><replaceable>port</replaceable></optional>, <optional><replaceable>opt</replaceable></optional>, <optional><replaceable>tty</replaceable></optional>, <optional><replaceable>user</replaceable></optional>, <optional><replaceable>passwd</replaceable></optional>)
+</synopsis>
+
+ <refsect2 id="pygresql-connect-parameters">
+ <title>Parameters</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><replaceable>dbname</replaceable></term>
+
+ <listitem>
+ <para>Name of connected database (string/None).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>host</replaceable></term>
+
+ <listitem>
+ <para>Name of the server host (string/None).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>port</replaceable></term>
+
+ <listitem>
+ <para>Port used by the database server (integer/-1).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>opt</replaceable></term>
+
+ <listitem>
+ <para>
+ Options for the server (string/None).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>tty</replaceable></term>
+
+ <listitem>
+ <para>
+ File or tty for optional debug output from backend
+ (string/None).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>user</replaceable></term>
+
+ <listitem>
+ <para>
+ <productname>PostgreSQL</productname> user (string/None).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>passwd</replaceable></term>
+
+ <listitem>
+ <para>Password for user (string/None).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="pygresql-connect-return">
+ <title>Return Type</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><replaceable>pgobject</replaceable></term>
+
+ <listitem>
+ <para>
+ If successful, an object handling a database connection is returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="pygresql-connect-exceptions">
+ <title>Exceptions</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><errorname>TypeError</errorname></term>
+
+ <listitem>
+ <para>
+ Bad argument type, or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><errorname>SyntaxError</errorname></term>
+
+ <listitem>
+ <para>
+ Duplicate argument definition.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><errorname>pg.error</errorname></term>
+
+ <listitem>
+ <para>
+ Some error occurred during pg connection definition.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ (+ all exceptions relative to object allocation)
+ </para>
+ </refsect2>
+ </refsynopsisdiv>
+
+ <refsect1 id="pygresql-connect-description">
+ <title>Description</title>
+
+ <para>
+ This method opens a connection to a specified database on a given
+ <productname>PostgreSQL</productname> server. You can use
+ keywords here, as described in the
+ <productname>Python</productname> 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 <productname>PostgreSQL</productname> user manual.
+ </para>
+ </refsect1>
+
+ <refsect1 id="pygresql-connect-examples">
+ <title>Examples</title>
+
+ <para>
+<programlisting>
+import pg
+
+con1 = pg.connect('testdb', 'myhost', 5432, None, None, 'bob', None)
+con2 = pg.connect(dbname='testdb', host='localhost', user='bob')
+</programlisting>
+ </para>
+ </refsect1>
+
+ </refentry>
+
+
+ <refentry id="pygresql-get-defhost">
+ <refmeta>
+ <refentrytitle>get_defhost</refentrytitle>
+ <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>get_defhost</refname>
+ <refpurpose>get default host name [DV]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+get_defhost()
+</synopsis>
+
+ <refsect2 id="pygresql-get-defhost-parameters">
+ <title>Parameters</title>
+
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="pygresql-get-defhost-return">
+ <title>Return Type</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>string or None</term>
+
+ <listitem>
+ <para>
+ Default host specification
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="pygresql-get-defhost-exceptions">
+ <title>Exceptions</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><errorname>SyntaxError</errorname></term>
+
+ <listitem>
+ <para>
+ Too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="pygresql-get-defhost-description">
+ <title>Description</title>
+
+ <para>
+ <function>get_defhost()</function> returns the current default
+ host specification, or None if the environment variables should
+ be used. Environment variables will not be looked up.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+
+ <refentry id="pygresql-set-defhost">
+ <refmeta>
+ <refentrytitle>set_defhost</refentrytitle>
+ <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>set_defhost</refname>
+ <refpurpose>set default host name [DV]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+set_defhost(<replaceable>host</replaceable>)
+</synopsis>
+
+ <refsect2 id="pygresql-set-defhost-parameters">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>host</replaceable>
+ </term>
+ <listitem>
+ <para>New default host (string/None).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="pygresql-set-defhost-return">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ string or None
+ </term>
+ <listitem>
+ <para>
+ Previous default host specification.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="pygresql-set-defhost-exceptions">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad argument type, or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="pygresql-set-defhost-description">
+ <title>Description</title>
+ <para>
+ <function>set_defhost()</function> sets the default host value
+ for new connections. If None is supplied as parameter, environment
+ variables will be used in future connections. It returns the
+ previous setting for default host.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="pygresql-get-defport">
+ <refmeta>
+ <refentrytitle>get_defport</refentrytitle>
+ <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>get_defport</refname>
+ <refpurpose>get default port [DV]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+get_defport()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-GET-DEFPORT-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-GET-DEFPORT-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ integer or None
+ </term>
+ <listitem>
+ <para>
+ Default port specification
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-GET-DEFPORT-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>SyntaxError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-GET-DEFPORT-1">
+ <title>Description</title>
+ <para>
+ <function>get_defport()</function> returns the current default
+ port specification, or None if the environment variables should
+ be used. Environment variables will not be looked up.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-SET-DEFPORT">
+ <refmeta>
+ <refentrytitle>set_defport</refentrytitle>
+ <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>set_defport</refname>
+ <refpurpose>set default port [DV]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+set_defport(<replaceable>port</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-SET-DEFPORT-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>port</replaceable>
+ </term>
+ <listitem>
+ <para>New default host (integer/-1).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-SET-DEFPORT-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ integer or None
+ </term>
+ <listitem>
+ <para>
+ Previous default port specification.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-SET-DEFPORT-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad argument type, or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-SET-DEFPORT-1">
+ <title>Description</title>
+ <para>
+ <function>set_defport()</function> 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.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-GET-DEFOPT">
+ <refmeta>
+ <refentrytitle>get_defopt</refentrytitle>
+ <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>get_defopt</refname>
+ <refpurpose>get default options specification [DV]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+get_defopt()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-GET-DEFOPT-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-GET-DEFOPT-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ string or None
+ </term>
+ <listitem>
+ <para>
+ Default options specification
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-GET-DEFOPT-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>SyntaxError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-GET-DEFOPT-1">
+ <title>Description</title>
+ <para>
+ <function>get_defopt()</function> returns the current default
+ connection options specification, or None if the environment variables should
+ be used. Environment variables will not be looked up.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-SET-DEFOPT">
+ <refmeta>
+ <refentrytitle>set_defopt</refentrytitle>
+ <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>set_defopt</refname>
+ <refpurpose>set options specification [DV]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+set_defopt(<replaceable>options</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-SET-DEFOPT-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>options</replaceable>
+ </term>
+ <listitem>
+ <para>New default connection options (string/None).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-SET-DEFOPT-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ string or None
+ </term>
+ <listitem>
+ <para>
+ Previous default opt specification.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-SET-DEFOPT-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad argument type, or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-SET-DEFOPT-1">
+ <title>Description</title>
+ <para>
+ <function>set_defopt()</function> sets the default connection options value
+ for new connections. If None is supplied as parameter, environment
+ variables will be used in future connections. It returns the
+ previous setting for default options.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-GET-DEFTTY">
+ <refmeta>
+ <refentrytitle>get_deftty</refentrytitle>
+ <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>get_deftty</refname>
+ <refpurpose>get default connection debug terminal specification [DV]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+get_deftty()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-GET-DEFTTY-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-GET-DEFTTY-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ string or None
+ </term>
+ <listitem>
+ <para>
+ Default debug terminal specification
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-GET-DEFTTY-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>SyntaxError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-GET-DEFTTY-1">
+ <title>Description</title>
+ <para>
+ <function>get_deftty()</function> returns the current default
+ debug terminal specification, or None if the environment variables should
+ be used. Environment variables will not be looked up.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-SET-DEFTTY">
+ <refmeta>
+ <refentrytitle>set_deftty</refentrytitle>
+ <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>set_deftty</refname>
+ <refpurpose>set default debug terminal specification [DV]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+set_deftty(<replaceable>terminal</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-SET-DEFTTY-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>terminal</replaceable>
+ </term>
+ <listitem>
+ <para>New default debug terminal (string/None).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-SET-DEFTTY-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ string or None
+ </term>
+ <listitem>
+ <para>
+ Previous default debug terminal specification.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-SET-DEFTTY-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad argument type, or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-SET-DEFTTY-1">
+ <title>Description</title>
+ <para>
+ <function>set_deftty()</function> sets the default terminal value
+ for new connections. If None is supplied as parameter, environment
+ variables will be used in future connections. It returns the
+ previous setting for default terminal.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-GET-DEFBASE">
+ <refmeta>
+ <refentrytitle>get_defbase</refentrytitle>
+ <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>get_defbase</refname>
+ <refpurpose>get default database name specification [DV]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+get_defbase()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-GET-DEFBASE-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-GET-DEFBASE-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ string or None
+ </term>
+ <listitem>
+ <para>
+ Default debug database name specification
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-GET-DEFBASE-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>SyntaxError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-GET-DEFBASE-1">
+ <title>Description</title>
+ <para>
+ <function>get_defbase()</function> returns the current default
+ database name specification, or None if the environment variables should
+ be used. Environment variables will not be looked up.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-SET-DEFBASE">
+ <refmeta>
+ <refentrytitle>set_defbase</refentrytitle>
+ <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>set_defbase</refname>
+ <refpurpose>set default database name specification [DV]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+set_defbase(<replaceable>database</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-SET-DEFBASE-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>database</replaceable>
+ </term>
+ <listitem>
+ <para>New default database name (string/None).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-SET-DEFBASE-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ string or None
+ </term>
+ <listitem>
+ <para>
+ Previous default database name specification.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-SET-DEFBASE-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad argument type, or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-SET-DEFBASE-1">
+ <title>Description</title>
+ <para>
+ <function>set_defbase()</function> sets the default database name
+ for new connections. If None is supplied as parameter, environment
+ variables will be used in future connections. It returns the
+ previous setting for default database name.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+ </sect1>
+
+
+ <sect1 id="pygresql-pg-pgobject">
+ <title>Connection object: <classname>pgobject</classname></title>
+
+ <para>
+ This object handles a connection to the
+ <productname>PostgreSQL</productname> database. It embeds and
+ hides all the parameters that define this connection, leaving just
+ really significant parameters in function calls.
+ </para>
+
+ <para>
+ Some methods give direct access to the connection socket. They are
+ specified by the tag [DA]. <emphasis>Do not use them unless you
+ really know what you are doing.</emphasis> If you prefer disabling
+ them, set the <literal>-DNO_DIRECT</literal> option in the
+ <productname>Python</productname> <filename>Setup</filename> file.
+ </para>
+
+ <para>
+ Some other methods give access to large objects. if you want to
+ forbid access to these from the module, set the
+ <literal>-DNO_LARGE</literal> option in the
+ <productname>Python</productname> <filename>Setup</filename> file.
+ These methods are specified by the tag [LO].
+ </para>
+
+ <para>
+ Every <literal>pgobject</literal> defines a set of read-only
+ attributes that describe the connection and its status. These
+ attributes are:
+
+ <variablelist>
+ <varlistentry>
+ <term>host</term>
+ <listitem>
+ <para>
+ the host name of the server (string)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>port</term>
+ <listitem>
+ <para>
+ the port of the server (integer)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>db</term>
+ <listitem>
+ <para>
+ the selected database (string)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>options</term>
+ <listitem>
+ <para>
+ the connection options (string)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>tty</term>
+ <listitem>
+ <para>
+ the connection debug terminal (string)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>user</term>
+ <listitem>
+ <para>
+ user name on the database system (string)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>status</term>
+ <listitem>
+ <para>
+ the status of the connection (integer: 1 - OK, 0 - BAD)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>error</term>
+ <listitem>
+ <para>
+ the last warning/error message from the server (string)
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+
+ <refentry id="PYGRESQL-QUERY">
+ <refmeta>
+ <refentrytitle>query</refentrytitle>
+ <refmiscinfo>PYGRESQL - Query</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>query</refname>
+ <refpurpose>executes a SQL command</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+query(<replaceable>command</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-QUERY-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>command</replaceable>
+ </term>
+ <listitem>
+ <para>SQL command (string).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-QUERY-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ pgqueryobject or None
+ </term>
+ <listitem>
+ <para>
+ Result values.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-QUERY-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad argument type, or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>ValueError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Empty SQL query.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Error during query processing, or invalid connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-QUERY-1">
+ <title>Description</title>
+ <para>
+ <function>query()</function> method sends a <acronym>SQL</acronym>
+ query to the database. If the query is an insert statement, the return
+ value is the <acronym>OID</acronym> of the newly inserted row.
+ If it is otherwise a query that does not return a result
+ (i.e., is not a some kind of <literal>SELECT</literal> statement), it returns None.
+ Otherwise, it returns a <literal>pgqueryobject</literal> that can be accessed via the
+ <function>getresult()</function> or <function>dictresult()</function>
+ methods or simply printed.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-RESET">
+ <refmeta>
+ <refentrytitle>reset</refentrytitle>
+ <refmiscinfo>PYGRESQL - Reset</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>reset</refname>
+ <refpurpose>resets the connection</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+reset()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-RESET-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-RESET-2">
+ <title>Return Type</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-RESET-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many (any) arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-RESET-1">
+ <title>Description</title>
+ <para>
+ <function>reset()</function> method resets the current database.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-CLOSE">
+ <refmeta>
+ <refentrytitle>close</refentrytitle>
+ <refmiscinfo>PYGRESQL - Close</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>close</refname>
+ <refpurpose>close the database connection</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+close()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-CLOSE-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-CLOSE-2">
+ <title>Return Type</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-CLOSE-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many (any) arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-CLOSE-1">
+ <title>Description</title>
+ <para>
+ <function>close()</function> 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.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-FILENO">
+ <refmeta>
+ <refentrytitle>fileno</refentrytitle>
+ <refmiscinfo>PYGRESQL - Fileno</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>fileno</refname>
+ <refpurpose>returns the socket used to connect to the database</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+fileno()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-FILENO-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-FILENO-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ socket id
+ </term>
+ <listitem>
+ <para>
+ The underlying socket id used to connect to the database.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-FILENO-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many (any) arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-FILENO-1">
+ <title>Description</title>
+ <para>
+ <function>fileno()</function> method returns the underlying socket id used to connect
+ to the database. This is useful for use in <function>select</function> calls, etc.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-GETNOTIFY">
+ <refmeta>
+ <refentrytitle>getnotify</refentrytitle>
+ <refmiscinfo>PYGRESQL - Getnotify</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>getnotify</refname>
+ <refpurpose>gets the last notify from the server</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+getnotify()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-GETNOTIFY-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-GETNOTIFY-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ tuple, None
+ </term>
+ <listitem>
+ <para>
+ Last notify from server
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-GETNOTIFY-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many (any) arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-GETNOTIFY-1">
+ <title>Description</title>
+ <para>
+ <function>getnotify()</function> method tries to get a notify from
+ the server (from the <literal>SQL</literal> statement <literal>NOTIFY</literal>).
+ If the server returns no notify, the methods returns None.
+ Otherwise, it returns a tuple (couple) <literal>(relname, pid)</literal>,
+ where <literal>relname</literal> is the name of the notify and <literal>pid</literal>
+ the process id of the connection that triggered the notify.
+ Remember to do a listen query first otherwise getnotify will always return None.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-INSERTTABLE">
+ <refmeta>
+ <refentrytitle>inserttable</refentrytitle>
+ <refmiscinfo>PYGRESQL - Inserttable</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>inserttable</refname>
+ <refpurpose>inserts a list into a table</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-INSERTTABLE-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>table</replaceable>
+ </term>
+ <listitem>
+ <para>The table name (string).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <replaceable>values</replaceable>
+ </term>
+ <listitem>
+ <para>The list of rows values to insert (list).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-INSERTTABLE-2">
+ <title>Return Type</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-INSERTTABLE-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad argument type or too many (any) arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-INSERTTABLE-1">
+ <title>Description</title>
+ <para>
+ <function>inserttable()</function> method allows to quickly
+ insert large blocks of data in a table: it inserts the whole
+ values list into the given table. 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. <emphasis>Be very careful:</emphasis> this method
+ does not typecheck the fields according to the table
+ definition; it just look whether or not it knows how to handle
+ such types.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PUTLINE">
+ <refmeta>
+ <refentrytitle>putline</refentrytitle>
+ <refmiscinfo>PYGRESQL - Putline</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>putline</refname>
+ <refpurpose>writes a line to the server socket [DA]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+putline(<replaceable>line</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PUTLINE-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>line</replaceable>
+ </term>
+ <listitem>
+ <para>Line to be written (string).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PUTLINE-2">
+ <title>Return Type</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PUTLINE-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad argument type or too many (any) arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PUTLINE-1">
+ <title>Description</title>
+ <para>
+ <function>putline()</function> method allows to directly write a string to the server socket.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-GETLINE">
+ <refmeta>
+ <refentrytitle>getline</refentrytitle>
+ <refmiscinfo>PYGRESQL - Getline</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>getline</refname>
+ <refpurpose>gets a line from server socket [DA]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+getline()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-GETLINE-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-GETLINE-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ string
+ </term>
+ <listitem>
+ <para>
+ The line read.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-GETLINE-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad argument type or too many (any) arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-GETLINE-1">
+ <title>Description</title>
+ <para>
+ <function>getline()</function> method allows to directly read a string from the server socket.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-ENDCOPY">
+ <refmeta>
+ <refentrytitle>endcopy</refentrytitle>
+ <refmiscinfo>PYGRESQL - Endcopy</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>endcopy</refname>
+ <refpurpose>synchronizes client and server [DA]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+endcopy()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-ENDCOPY-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-ENDCOPY-2">
+ <title>Return Type</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-ENDCOPY-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad argument type or too many (any) arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-ENDCOPY-1">
+ <title>Description</title>
+ <para>
+ The use of direct access methods may desynchronize client and server. This
+ method ensure that client and server will be synchronized.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-LOCREATE">
+ <refmeta>
+ <refentrytitle>locreate</refentrytitle>
+ <refmiscinfo>PYGRESQL - Locreate</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>locreate</refname>
+ <refpurpose>creates of large object in the database [LO]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+locreate(<replaceable>mode</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-LOCREATE-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>mode</replaceable>
+ </term>
+ <listitem>
+ <para>Large object create mode.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-LOCREATE-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ pglarge
+ </term>
+ <listitem>
+ <para>
+ Object handling the <productname>PostgreSQL</productname> large object.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-LOCREATE-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad argument type or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection, or creation error.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-LOCREATE-1">
+ <title>Description</title>
+ <para>
+ <function>locreate()</function> method creates a large object in the database.
+ The mode can be defined by OR-ing the constants defined in the pg module
+ (<literal>INV_READ, INV_WRITE</literal> and <literal>INV_ARCHIVE</literal>).
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-GETLO">
+ <refmeta>
+ <refentrytitle>getlo</refentrytitle>
+ <refmiscinfo>PYGRESQL - Getlo</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>getlo</refname>
+ <refpurpose>builds a large object from given <literal>oid</literal> [LO]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+getlo(<replaceable>oid</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-GETLO-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>oid</replaceable>
+ </term>
+ <listitem>
+ <para><literal>OID</literal> of the existing large object (integer).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-GETLO-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ pglarge
+ </term>
+ <listitem>
+ <para>
+ Object handling the <productname>PostgreSQL</productname> large object.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-GETLO-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad argument type or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-GETLO-1">
+ <title>Description</title>
+ <para>
+ <function>getlo()</function> method allows to reuse a formerly
+ created large object through the <classname>pglarge</classname> interface, providing
+ the user have its <literal>oid</literal>.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-LOIMPORT">
+ <refmeta>
+ <refentrytitle>loimport</refentrytitle>
+ <refmiscinfo>PYGRESQL - Loimport</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>loimport</refname>
+ <refpurpose>imports a file to a <productname>PostgreSQL</productname> large object [LO]</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+loimport(<replaceable>filename</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-LOIMPORT-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>filename</replaceable>
+ </term>
+ <listitem>
+ <para>The name of the file to be imported (string).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-LOIMPORT-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ pglarge
+ </term>
+ <listitem>
+ <para>
+ Object handling the <productname>PostgreSQL</productname> large object.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-LOIMPORT-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad argument type or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection, or error during file import.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-LOIMPORT-1">
+ <title>Description</title>
+ <para>
+ <function>loimport()</function> method allows to create large objects
+ in a very simple way. You just give the name of a file containing the
+ data to be use.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+ </sect1>
+
+
+ <sect1 id="pygresql-pg-DB">
+ <title>Database wrapper class: <classname>DB</classname></title>
+
+ <para>
+ <classname>pg</classname> module contains a class called
+ <classname>DB</classname>. All <classname>pgobject</classname>
+ methods are included in this class also. A number of additional
+ <classname>DB</classname> class methods are described below. The
+ preferred way to use this module is as follows (See description of
+ the initialization method below.):
+
+<programlisting>
+import pg
+
+db = pg.DB(...)
+
+for r in db.query(
+ "SELECT foo,bar
+ FROM foo_bar_table
+ WHERE foo !~ bar"
+ ).dictresult():
+
+ print '%(foo)s %(bar)s' % r
+</programlisting>
+
+ The following describes the methods and variables of this class.
+ </para>
+
+ <para>
+ The <classname>DB</classname> class is initialized with the same
+ arguments as the <function>pg.connect</function> method. It also
+ initializes a few internal variables. The statement <literal>db =
+ DB()</literal> will open the local database with the name of the
+ user just like <function>pg.connect()</function> does.
+ </para>
+
+ <refentry id="PYGRESQL-DB-PKEY">
+ <refmeta>
+ <refentrytitle>pkey</refentrytitle>
+ <refmiscinfo>PYGRESQL - Pkey</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>pkey</refname>
+ <refpurpose>returns the primary key of a table</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+pkey(<replaceable>table</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-DB-PKEY-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>table</replaceable>
+ </term>
+ <listitem>
+ <para>
+ name of table.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-DB-PKEY-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ string
+ </term>
+ <listitem>
+ <para>
+ Name of field which is the primary key of the table.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-DB-PKEY-1">
+ <title>Description</title>
+ <para>
+ <function>pkey()</function> method returns the primary key
+ of a table. Note that this raises an exception if the table
+ does not have a primary key.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+ <!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-DB-GET-DATABASES">
+ <refmeta>
+ <refentrytitle>get_databases</refentrytitle>
+ <refmiscinfo>PYGRESQL - Get_databases</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>get_databases</refname>
+ <refpurpose>get list of databases in the system</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+get_databases()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-DB-GET-DATABASES-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-DB-GET-DATABASES-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ list
+ </term>
+ <listitem>
+ <para>
+ List of databases in the system.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-DB-GET-DATABASES-1">
+ <title>Description</title>
+ <para>
+ Although you can do this with a simple select,
+ it is added here for convenience
+ </para>
+ </refsect1>
+
+ </refentry>
+
+ <!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-DB-GET-TABLES">
+ <refmeta>
+ <refentrytitle>get_tables</refentrytitle>
+ <refmiscinfo>PYGRESQL - get_tables</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>get_tables</refname>
+ <refpurpose>get list of tables in connected database</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+get_tables()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-DB-GET-TABLES-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-DB-GET-TABLES-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ list
+ </term>
+ <listitem>
+ <para>
+ List of tables in connected database.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-DB-GET-TABLES-1">
+ <title>Description</title>
+ <para>
+ Although you can do this with a simple select,
+ it is added here for convenience
+ </para>
+ </refsect1>
+
+ </refentry>
+
+ <!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-DB-GET-ATTNAMES">
+ <refmeta>
+ <refentrytitle>get_attnames</refentrytitle>
+ <refmiscinfo>PYGRESQL - Get_Attnames</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>get_attnames</refname>
+ <refpurpose>returns the attribute names of a table</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+get_attnames(<replaceable>table</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-DB-GET-ATTNAMES-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>table</replaceable>
+ </term>
+ <listitem>
+ <para>
+ name of table.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-DB-GET-ATTNAMES-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ list
+ </term>
+ <listitem>
+ <para>
+ List of attribute names.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-DB-GET-ATTNAMES-1">
+ <title>Description</title>
+ <para>
+ Given the name of a table, digs out the list of attribute names.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+ <!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-DB-GET">
+ <refmeta>
+ <refentrytitle>get</refentrytitle>
+ <refmiscinfo>PYGRESQL - Get</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>get</refname>
+ <refpurpose>get a tuple from a database table</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional><replaceable>keyname</replaceable></optional>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-DB-GET-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>table</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Name of table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <replaceable>arg</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Either a dictionary or the value to be looked up.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <optional><replaceable>keyname</replaceable></optional>
+ </term>
+ <listitem>
+ <para>
+ Name of field to use as key (optional).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-DB-GET-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ dictionary
+ </term>
+ <listitem>
+ <para>
+ A dictionary mapping attribute names to row values.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-DB-GET-1">
+ <title>Description</title>
+ <para>
+ This method is the basic mechanism to get a single row. It assumes
+ that the key specifies a unique row. If keyname is not specified
+ then the primary key for the table is used. If arg 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.
+ The oid is also put into the dictionary but in order to allow the
+ caller to work with multiple tables, the attribute name is munged
+ to make it unique. It consists of the string <literal>oid_</literal> followed by
+ the name of the table.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+ <!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-DB-INSERT">
+ <refmeta>
+ <refentrytitle>insert</refentrytitle>
+ <refmiscinfo>PYGRESQL - Insert</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>insert</refname>
+ <refpurpose>insert a tuple into a database table</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-DB-INSERT-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>table</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Name of table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <replaceable>a</replaceable>
+ </term>
+ <listitem>
+ <para>
+ A dictionary of values.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-DB-INSERT-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ integer
+ </term>
+ <listitem>
+ <para>
+ The OID of the newly inserted row.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-DB-INSERT-1">
+ <title>Description</title>
+ <para>
+ This method inserts values into the table specified filling in the
+ values from the dictionary. It then reloads the dictionary with the
+ values from the database. This causes the dictionary to be updated
+ with values that are modified by rules, triggers, etc.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+ <!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-DB-UPDATE">
+ <refmeta>
+ <refentrytitle>update</refentrytitle>
+ <refmiscinfo>PYGRESQL - Update</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>update</refname>
+ <refpurpose>update a database table</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+update(<replaceable>table</replaceable>, <replaceable>a</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-DB-UPDATE-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>table</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Name of table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <replaceable>a</replaceable>
+ </term>
+ <listitem>
+ <para>
+ A dictionary of values.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-DB-UPDATE-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ integer
+ </term>
+ <listitem>
+ <para>
+ The OID of the newly updated row.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-DB-UPDATE-1">
+ <title>Description</title>
+ <para>
+ Similar to insert but updates an existing row. The update is based
+ on the OID value as munged by get. The array returned is the
+ one sent modified to reflect any changes caused by the update due
+ to triggers, rules, defaults, etc.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+ <!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-DB-CLEAR">
+ <refmeta>
+ <refentrytitle>clear</refentrytitle>
+ <refmiscinfo>PYGRESQL - Clear</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>clear</refname>
+ <refpurpose>clear a database table</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+clear(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></optional>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-DB-CLEAR-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>table</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Name of table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <optional><replaceable>a</replaceable></optional>
+ </term>
+ <listitem>
+ <para>
+ A dictionary of values.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-DB-CLEAR-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ dictionary
+ </term>
+ <listitem>
+ <para>
+ A dictionary with an empty row.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-DB-CLEAR-1">
+ <title>Description</title>
+ <para>
+ This method clears all the attributes to values determined by the types.
+ Numeric types are set to 0, dates are set to <literal>'today'</literal> 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.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+ <!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-DB-DELETE">
+ <refmeta>
+ <refentrytitle>delete</refentrytitle>
+ <refmiscinfo>PYGRESQL - Delete</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>delete</refname>
+ <refpurpose>deletes the row from a table</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></optional>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-DB-DELETE-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>table</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Name of table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <optional><replaceable>a</replaceable></optional>
+ </term>
+ <listitem>
+ <para>
+ A dictionary of values.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-DB-DELETE-2">
+ <title>Return Type</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-DB-DELETE-1">
+ <title>Description</title>
+ <para>
+ This method deletes the row from a table. It deletes based on the OID
+ as munged as described above.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+ <!-- ********************************************************** -->
+
+ </sect1>
+
+ <!-- ********************************************************** -->
+ <!-- ********************************************************** -->
+
+ <sect1 id="pygresql-pg-pgqueryobject">
+ <title>Query result object: <literal>pgqueryobject</literal></title>
+
+ <!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PGQUERYOBJECT-GETRESULT">
+ <refmeta>
+ <refentrytitle>getresult</refentrytitle>
+ <refmiscinfo>PYGRESQL - Getresult</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>getresult</refname>
+ <refpurpose>gets the values returned by the query</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+getresult()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-GETRESULT-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-GETRESULT-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ list
+ </term>
+ <listitem>
+ <para>
+ List of tuples.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-GETRESULT-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>SyntaxError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid previous result.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-GETRESULT-1">
+ <title>Description</title>
+ <para>
+ <function>getresult()</function> method returns the list of the values returned by the query.
+ More information about this result may be accessed using <function>listfields</function>,
+ <function>fieldname</function> and <function>fieldnum</function> methods.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PGQUERYOBJECT-DICTRESULT">
+ <refmeta>
+ <refentrytitle>dictresult</refentrytitle>
+ <refmiscinfo>PYGRESQL - Dictresult</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>dictresult</refname>
+ <refpurpose>like getresult but returns a list of dictionaries</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+dictresult()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-DICTRESULT-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-DICTRESULT-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ list
+ </term>
+ <listitem>
+ <para>
+ List of dictionaries.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-DICTRESULT-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>SyntaxError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid previous result.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-DICTRESULT-1">
+ <title>Description</title>
+ <para>
+ <function>dictresult()</function> 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.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PGQUERYOBJECT-LISTFIELDS">
+ <refmeta>
+ <refentrytitle>listfields</refentrytitle>
+ <refmiscinfo>PYGRESQL - Listfields</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>listfields</refname>
+ <refpurpose>lists the fields names of the query result</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+listfields()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ list
+ </term>
+ <listitem>
+ <para>
+ field names
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>SyntaxError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid query result, or invalid connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-1">
+ <title>Description</title>
+ <para>
+ <function>listfields()</function> method returns the list of field names defined for the
+ query result. The fields are in the same order as the result values.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PGQUERYOBJECT-FIELDNAME">
+ <refmeta>
+ <refentrytitle>fieldname</refentrytitle>
+ <refmiscinfo>PYGRESQL - Fieldname</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>fieldname</refname>
+ <refpurpose>field number-name conversion</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+fieldname(<replaceable>i</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>i</replaceable>
+ </term>
+ <listitem>
+ <para>
+ field number (integer).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ string
+ </term>
+ <listitem>
+ <para>
+ field name.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad parameter type, or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <replaceable>ValueError</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Invalid field number.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid query result, or invalid connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-FIELDNAME-1">
+ <title>Description</title>
+ <para>
+ <function>fieldname()</function> 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 than the
+ result values.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PGQUERYOBJECT-FIELDNUM">
+ <refmeta>
+ <refentrytitle>fieldnum</refentrytitle>
+ <refmiscinfo>PYGRESQL - Fieldnum</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>fieldnum</refname>
+ <refpurpose>field name-number conversion</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+fieldnum(<replaceable>name</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>name</replaceable>
+ </term>
+ <listitem>
+ <para>
+ field name (string).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ integer
+ </term>
+ <listitem>
+ <para>
+ field number (integer).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad parameter type, or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <replaceable>ValueError</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Unknown field name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid query result, or invalid connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-FIELDNUM-1">
+ <title>Description</title>
+ <para>
+ <function>fieldnum()</function> 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.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PGQUERYOBJECT-NTUPLES">
+ <refmeta>
+ <refentrytitle>ntuples</refentrytitle>
+ <refmiscinfo>PYGRESQL - Ntuples</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ntuples</refname>
+ <refpurpose>returns the number of tuples in query object</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+ntuples()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-NTUPLES-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-NTUPLES-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ integer
+ </term>
+ <listitem>
+ <para>
+ The number of tuples in query object.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-NTUPLES-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>SyntaxError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-NTUPLES-1">
+ <title>Description</title>
+ <para>
+ <function>ntuples()</function> method returns the number of tuples found in a query.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+ </sect1>
+
+
+ <sect1 id="pygresql-pg-pglarge">
+ <title>Large Object: <classname>pglarge</classname></title>
+
+ <para>
+ This object handles all the request concerning a
+ <productname>PostgreSQL</productname> large object. It embeds and
+ hides all the <quote>recurrent</quote> variables (object oid and
+ connection), exactly in the same way
+ <classname>pgobject</classname>s do, thus only keeping significant
+ parameters in function calls. It keeps a reference to the <classname>pgobject</classname>
+ used for its creation, sending requests though with its
+ parameters. Any modification but dereferencing the
+ <classname>pgobject</classname> will thus affect the
+ <classname>pglarge</classname> object. Dereferencing the initial
+ <classname>pgobject</classname> is not a problem since
+ <application>Python</application> will not deallocate it before the
+ large object dereference it. All functions return a generic error
+ message on call error, whatever the exact error was. The
+ <structfield>error</structfield> attribute of the object allows to
+ get the exact error message.
+ </para>
+
+ <para>
+ <classname>pglarge</classname> objects define a read-only set of
+ attributes that allow to get some information about it. These
+ attributes are:
+
+ <variablelist>
+ <varlistentry>
+ <term>oid</term>
+ <listitem>
+ <para>
+ the oid associated with the object
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>pgcnx</term>
+ <listitem>
+ <para>
+ the <classname>pgobject</classname> associated with the object
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>error</term>
+ <listitem>
+ <para>
+ the last warning/error message of the connection
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <note>
+ <title>Be careful</title>
+
+ <para>
+ In multithreaded environments, <structfield>error</structfield>
+ may be modified by another thread using the same
+ <classname>pgobject</classname>. Remember these object are
+ shared, not duplicated; you should provide some locking to be
+ able if you want to check this. The oid attribute is very
+ interesting because it allow you reuse the oid later, creating
+ the <classname>pglarge</classname> object with a <classname>pgobject</classname>
+ <function>getlo()</function> method call.
+ </para>
+ </note>
+ </para>
+
+ <para>
+ See also <xref linkend="largeobjects"> for more information about the
+ <productname>PostgreSQL</productname> large object interface.
+ </para>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PGLARGEOBJECT-OPEN">
+ <refmeta>
+ <refentrytitle>open</refentrytitle>
+ <refmiscinfo>PYGRESQL - Open</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>open</refname>
+ <refpurpose>opens a large object</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+open(<replaceable>mode</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>mode</replaceable>
+ </term>
+ <listitem>
+ <para>
+ open mode definition (integer).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-2">
+ <title>Return Type</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad parameter type, or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>IOError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Already opened object, or open error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-OPEN-1">
+ <title>Description</title>
+ <para>
+ <function>open()</function> method opens a large object for reading/writing,
+ in the same way than the <acronym>UNIX</acronym> <function>open()</function>
+ function. The mode value can be obtained by OR-ing the constants defined in
+ the pg module (<literal>INV_READ, INV_WRITE</literal>).
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PGLARGEOBJECT-CLOSE">
+ <refmeta>
+ <refentrytitle>close</refentrytitle>
+ <refmiscinfo>PYGRESQL - Close</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>close</refname>
+ <refpurpose>closes the large object</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+close()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-CLOSE-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-CLOSE-2">
+ <title>Return Type</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-CLOSE-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>SyntaxError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>IOError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Object is not opened, or close error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-CLOSE-1">
+ <title>Description</title>
+ <para>
+ <function>close()</function> method closes previously opened large object,
+ in the same way than the <acronym>UNIX</acronym> <function>close()</function> function.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PGLARGEOBJECT-READ">
+ <refmeta>
+ <refentrytitle>read</refentrytitle>
+ <refmiscinfo>PYGRESQL - Read</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>read</refname>
+ <refpurpose>reads from the large object</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+read(<replaceable>size</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>size</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Maximal size of the buffer to be read (integer).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ string
+ </term>
+ <listitem>
+ <para>
+ The read buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad parameter type, or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>IOError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Object is not opened, or read error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection or invalid object.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-READ-1">
+ <title>Description</title>
+ <para>
+ <function>read()</function> method allows to read data from the large object,
+ starting at current position.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PGLARGEOBJECT-WRITE">
+ <refmeta>
+ <refentrytitle>write</refentrytitle>
+ <refmiscinfo>PYGRESQL - Write</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>write</refname>
+ <refpurpose>writes to the large object</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+write(<replaceable>string</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>string</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Buffer to be written (string).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-2">
+ <title>Return Type</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad parameter type, or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>IOError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Object is not opened, or write error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection or invalid object.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-WRITE-1">
+ <title>Description</title>
+ <para>
+ <function>write()</function> method allows to write data to the large object,
+ starting at current position.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PGLARGEOBJECT-SEEK">
+ <refmeta>
+ <refentrytitle>seek</refentrytitle>
+ <refmiscinfo>PYGRESQL - Seek</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>seek</refname>
+ <refpurpose>change current position in the large object</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>offset</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Position offset (integer).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <replaceable>whence</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Positional parameter (integer).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ integer
+ </term>
+ <listitem>
+ <para>
+ New current position in the object.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad parameter type, or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>IOError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Object is not opened, or seek error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection or invalid object.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-SEEK-1">
+ <title>Description</title>
+ <para>
+ <function>seek()</function> method allows to move the cursor position
+ in the large object. The whence parameter can be obtained by OR-ing the constants defined in the
+ <literal>pg</literal> module (<literal>SEEK_SET, SEEK_CUR, SEEK_END</literal>).
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PGLARGEOBJECT-TELL">
+ <refmeta>
+ <refentrytitle>tell</refentrytitle>
+ <refmiscinfo>PYGRESQL - Tell</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>tell</refname>
+ <refpurpose>returns current position in the large object</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+tell()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-TELL-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-TELL-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ integer
+ </term>
+ <listitem>
+ <para>
+ Current position in the object.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-TELL-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>SyntaxError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>IOError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Object is not opened, or seek error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection or invalid object.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-TELL-1">
+ <title>Description</title>
+ <para>
+ <function>tell()</function> method allows to get the current position in the large object.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PGLARGEOBJECT-UNLINK">
+ <refmeta>
+ <refentrytitle>unlink</refentrytitle>
+ <refmiscinfo>PYGRESQL - Unlink</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>unlink</refname>
+ <refpurpose>deletes the large object</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+unlink()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-UNLINK-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-UNLINK-2">
+ <title>Return Type</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-UNLINK-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>SyntaxError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>IOError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Object is not closed, or unlink error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection or invalid object.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-UNLINK-1">
+ <title>Description</title>
+ <para>
+ <function>unlink()</function> method unlinks (deletes) the large object.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PGLARGEOBJECT-SIZE">
+ <refmeta>
+ <refentrytitle>size</refentrytitle>
+ <refmiscinfo>PYGRESQL - Size</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>size</refname>
+ <refpurpose>gives the large object size</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+size()
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SIZE-1">
+ <title>Parameters</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SIZE-2">
+ <title>Return Type</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ integer
+ </term>
+ <listitem>
+ <para>
+ The large object size.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SIZE-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>SyntaxError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>IOError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Object is not opened, or seek/tell error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection or invalid object.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-SIZE-1">
+ <title>Description</title>
+ <para>
+ <function>size()</function> method allows to get the size of
+ the large object. It was implemented because this function
+ is very useful for a WWW interfaced database.
+ Currently the large object needs to be opened.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+<!-- ********************************************************** -->
+
+ <refentry id="PYGRESQL-PGLARGEOBJECT-EXPORT">
+ <refmeta>
+ <refentrytitle>export</refentrytitle>
+ <refmiscinfo>PYGRESQL - Export</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>export</refname>
+ <refpurpose>saves the large object to file</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+export(<replaceable>filename</replaceable>)
+</synopsis>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-1">
+ <title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable>filename</replaceable>
+ </term>
+ <listitem>
+ <para>
+ The file to be created.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-2">
+ <title>Return Type</title>
+ <para>
+ none
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-3">
+ <title>Exceptions</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <errorname>TypeError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Bad argument type, or too many arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>IOError</errorname>
+ </term>
+ <listitem>
+ <para>
+ Object is not closed, or export error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <errorname>pg.error</errorname>
+ </term>
+ <listitem>
+ <para>
+ Invalid connection or invalid object.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-EXPORT-1">
+ <title>Description</title>
+ <para>
+ <function>export()</function> method 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.
+ </para>
+ </refsect1>
+
+ </refentry>
+
+ </sect1>
+
+
+ <sect1 id="pygresql-db-api">
+ <title><acronym>DB-API</acronym> Interface</title>
+
+ <comment>
+ This section needs to be written.
+ </comment>
+
+ <para>
+ See <ulink
+ url="http://www.python.org/topics/database/DatabaseAPI-2.0.html"
+ >http://www.python.org/topics/database/DatabaseAPI-2.0.html</ulink>
+ for a description of the <acronym>DB-API</acronym> 2.0.
+ </para>
+ </sect1>
+
+</chapter>
--
GitLab