<!-- $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>