database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-05-01 01:04:50 +03:00
Code
postgres/doc/src/sgml/pygresql.sgml
Peter Eisentraut a8cb3368db General editing
2003-04-07 01:29:26 +00:00

4451 lines
120 KiB
Plaintext
Raw Blame History

<!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/pygresql.sgml,v 1.10 2003/04/07 01:29:25 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 &copy; 1995,
Pascal Andre. Further modifications Copyright &copy; 1997-2000 by
D'Arcy J.M. Cain.
</para>
</note>
<![IGNORE[
<sect1 id="pygresql-install">
<title>Installation</title>
<itemizedlist>
<listitem>
<para>
Note that if you are using the <acronym>DB-API</acronym> module
you must also install <literal>mxDateTime</literal> 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 <application>Python</application>'s Distutils.
</para>
</listitem>
</itemizedlist>
<para>
You have two options. You can compile
<application>PyGreSQL</application> as a stand-alone module or you
can build it into the <application>Python</application>
interpreter.
</para>
<sect2>
<title>General</title>
<itemizedlist>
<listitem>
<para>
You must first have installed <application>Python</application>
and <productname>PostgreSQL</productname> on your system. The
header files and developer's libraries for both
<application>Python</application> and
<productname>PostgreSQL</productname> must be installed on your
system before you can build <application>PyGreSQL</application>.
If you built both <application>Python</application> and
<productname>PostgreSQL</productname> from source, you should be
fine. If your system uses some package mechanism (such as
<acronym>RPM</acronym> or <systemitem class="osname">NetBSD</systemitem> packages),
then you probably need to install packages such as
<application>Python-devel</application> in addition to the
<application>Python</application> package.
</para>
</listitem>
<listitem>
<para>
<application>PyGreSQL</application> is implemented as three
parts, a C module labeled <literal>_pg</literal> and two
<application>Python</application> 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 <application>PyGreSQL</application>
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 <application>Python</application>
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>
<option>-DNO_DEF_VAR</option> - no default variables
support
</para>
</listitem>
<listitem>
<para>
<option>-DNO_DIRECT</option> - no direct access methods
</para>
</listitem>
<listitem>
<para>
<option>-DNO_LARGE</option> - no large object support
</para>
</listitem>
<listitem>
<para>
<option>-DNO_SNPRINTF</option> - if running a system with
no snprintf call
</para>
</listitem>
<listitem>
<para>
<option>-DNO_PQSOCKET</option> - if running an older
<productname>PostgreSQL</productname>
</para>
</listitem>
</itemizedlist>
On some systems you may need to include
<option>-lcrypt</option> in the list of libraries to make it
compile.
Define <option>DNO_PQSOCKET</option> 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>&gt;&gt;&gt;</prompt> <userinput>import _pg</userinput>
<prompt>&gt;&gt;&gt;</prompt> <userinput>db = _pg.connect('thilo', 'localhost')</userinput>
<prompt>&gt;&gt;&gt;</prompt> <userinput>db.query("INSERT INTO test VALUES ('ping', 'pong');")</userinput>
18304
<prompt>&gt;&gt;&gt;</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 <envar>PYTHONPATH</envar>.
A good place would be
<filename>/usr/lib/python1.5/site-python</filename>
if your <application>Python</application> 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 <application>Python</application> source hierarchy and
copy or symlink the <filename>pgmodule.c</filename> file there.
</para>
</listitem>
<listitem>
<para>
Add the following line to your <filename>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>
<option>-DNO_DEF_VAR</option> - no default variables
support
</para>
</listitem>
<listitem>
<para>
<option>-DNO_DIRECT</option> - no direct access methods
</para>
</listitem>
<listitem>
<para>
<option>-DNO_LARGE</option> - no large object support
</para>
</listitem>
<listitem>
<para>
<option>-DNO_SNPRINTF</option> - if running a system with
no snprintf call
</para>
</listitem>
<listitem>
<para>
<option>-DNO_PQSOCKET</option> - if running an older
<productname>PostgreSQL</productname>
</para>
</listitem>
</itemizedlist>
Define <option>-DNO_PQSOCKET</option> 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> key word is uncommented and
add the above line below it. You used to need to install
your shared modules with <literal>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 <application>Python</application> from the root
directory of the <application>Python</application> 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>
]]>
<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 <application>Python</application> <acronym>DB-SIG</acronym>.
</para>
<para>
Here we describe only the older <literal>pg</literal>
<acronym>API</acronym>. As long as
<application>PyGreSQL</application> 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>.
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>
<sect1 id="pygresql-pg">
<title>The <literal>pg</literal> Module</title>
<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>PostgreSQL</productname> large objects, and
</para>
</listitem>
<listitem>
<para>
<classname>pgqueryobject</classname>, which handles query results.
</para>
</listitem>
</itemizedlist>
</para>
<para>
If you want to see a simple example of the use this module,
see <ulink url="http://www.druid.net/rides"></ulink> where you can find a link at the
bottom to the actual <application>Python</application> 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 <application>libpq</application>
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>
<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 at build time by
setting the <option>-DNO_DEF_VAR</option> option in the Python
<filename>Setup</> file. Methods relative to this are specified by the tag [DV].
</para>
<para>
All default values 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>open a connection to the database server</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter>host</parameter></optional>, <optional><parameter>port</parameter></optional>, <optional><parameter>opt</parameter></optional>, <optional><parameter>tty</parameter></optional>, <optional><parameter>user</parameter></optional>, <optional><parameter>passwd</parameter></optional>)
</synopsis>
<refsect2 id="pygresql-connect-parameters">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>dbname</parameter></term>
<listitem>
<para>Name of connected database (string/<symbol>None</>)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>host</parameter></term>
<listitem>
<para>Name of the server host (string/<symbol>None</>)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>port</parameter></term>
<listitem>
<para>Port used by the database server (integer/-1)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>opt</parameter></term>
<listitem>
<para>
Options for the server (string/<symbol>None</>)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>tty</parameter></term>
<listitem>
<para>
File or TTY for optional debug output from server
(string/<symbol>None</>)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>user</parameter></term>
<listitem>
<para>
<productname>PostgreSQL</productname> user (string/<symbol>None</>)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>passwd</parameter></term>
<listitem>
<para>Password for user (string/<symbol>None</>)</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id="pygresql-connect-return">
<title>Return Type</title>
<variablelist>
<varlistentry>
<term><parameter>pgobject</parameter></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><classname>TypeError</classname></term>
<listitem>
<para>
Bad argument type, or too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><classname>SyntaxError</classname></term>
<listitem>
<para>
Duplicate argument definition.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><classname>pg.error</classname></term>
<listitem>
<para>
Some error occurred during <literal>pg</> connection definition.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
(plus 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. The arguments can be
given using key words here. The names of the
key words are the name of the parameters given in the syntax
line. For a precise description of the parameters, please refer
to <xref linkend="libpq">.
</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 <symbol>None</></term>
<listitem>
<para>
Default host specification
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id="pygresql-get-defhost-exceptions">
<title>Exceptions</title>
<variablelist>
<varlistentry>
<term><classname>SyntaxError</classname></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 <symbol>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(<parameter>host</parameter>)
</synopsis>
<refsect2 id="pygresql-set-defhost-parameters">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>host</parameter>
</term>
<listitem>
<para>New default host (string/<symbol>None</>).</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id="pygresql-set-defhost-return">
<title>Return Type</title>
<variablelist>
<varlistentry>
<term>
string or <symbol>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>
<classname>TypeError</classname>
</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 <symbol>None</symbol> 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 <symbol>None</symbol>
</term>
<listitem>
<para>
Default port specification
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id="R2-PYGRESQL-GET-DEFPORT-3">
<title>Exceptions</title>
<variablelist>
<varlistentry>
<term>
<classname>SyntaxError</classname>
</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 <symbol>None</symbol> 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(<parameter>port</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-SET-DEFPORT-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>port</parameter>
</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 <symbol>None</symbol>
</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>
<classname>TypeError</classname>
</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 <symbol>None</symbol>
</term>
<listitem>
<para>
Default options specification
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id="R2-PYGRESQL-GET-DEFOPT-3">
<title>Exceptions</title>
<variablelist>
<varlistentry>
<term>
<classname>SyntaxError</classname>
</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 <symbol>None</symbol> 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 default options specification [DV]</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
set_defopt(<parameter>options</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-SET-DEFOPT-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>options</parameter>
</term>
<listitem>
<para>New default connection options (string/<symbol>None</symbol>).</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id="R2-PYGRESQL-SET-DEFOPT-2">
<title>Return Type</title>
<variablelist>
<varlistentry>
<term>
string or <symbol>None</symbol>
</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>
<classname>TypeError</classname>
</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 <symbol>None</symbol> 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 <symbol>None</symbol>
</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>
<classname>SyntaxError</classname>
</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 <symbol>None</symbol> 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 connection debug terminal specification [DV]</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
set_deftty(<parameter>terminal</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-SET-DEFTTY-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>terminal</parameter>
</term>
<listitem>
<para>New default debug terminal (string/<symbol>None</symbol>).</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id="R2-PYGRESQL-SET-DEFTTY-2">
<title>Return Type</title>
<variablelist>
<varlistentry>
<term>
string or <symbol>None</symbol>
</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>
<classname>TypeError</classname>
</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 <symbol>None</symbol> 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 <symbol>None</symbol>
</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>
<classname>SyntaxError</classname>
</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 <symbol>None</symbol> 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(<parameter>database</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-SET-DEFBASE-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>database</parameter>
</term>
<listitem>
<para>New default database name (string/<symbol>None</symbol>).</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id="R2-PYGRESQL-SET-DEFBASE-2">
<title>Return Type</title>
<variablelist>
<varlistentry>
<term>
string or <symbol>None</symbol>
</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>
<classname>TypeError</classname>
</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 <symbol>None</symbol> 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 <option>-DNO_DIRECT</option> option in the
<application>Python</application> <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
<option>-DNO_LARGE</option> option in the
<application>Python</application> <filename>Setup</filename> file.
These methods are specified by the tag [LO].
</para>
<para>
Every <classname>pgobject</classname> 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>execute a SQL command</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
query(<parameter>command</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-QUERY-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>command</parameter>
</term>
<listitem>
<para>SQL command (string).</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id="R2-PYGRESQL-QUERY-2">
<title>Return Type</title>
<variablelist>
<varlistentry>
<term>
<classname>pgqueryobject</> or <symbol>None</symbol>
</term>
<listitem>
<para>
Result values.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id="R2-PYGRESQL-QUERY-3">
<title>Exceptions</title>
<variablelist>
<varlistentry>
<term>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Bad argument type, or too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>ValueError</classname>
</term>
<listitem>
<para>
Empty SQL query.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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 <symbol>None</symbol>.
Otherwise, it returns a <classname>pgqueryobject</classname> 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>reset 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>
<classname>TypeError</classname>
</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>
<classname>TypeError</classname>
</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>return 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>
<classname>TypeError</classname>
</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>get 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, <symbol>None</symbol>
</term>
<listitem>
<para>
Last notify from server
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id="R2-PYGRESQL-GETNOTIFY-3">
<title>Exceptions</title>
<variablelist>
<varlistentry>
<term>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Too many (any) arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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 SQL statement <literal>NOTIFY</literal>).
If the server returns no notify, the methods returns <symbol>None</symbol>.
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 <function>getnotify</> will always return <symbol>None</symbol>.
</para>
</refsect1>
</refentry>
<!-- ********************************************************** -->
<refentry id="PYGRESQL-INSERTTABLE">
<refmeta>
<refentrytitle>inserttable</refentrytitle>
<refmiscinfo>PYGRESQL - Inserttable</refmiscinfo>
</refmeta>
<refnamediv>
<refname>inserttable</refname>
<refpurpose>insert a list into a table</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
inserttable(<parameter>table</parameter>, <parameter>values</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-INSERTTABLE-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>table</parameter>
</term>
<listitem>
<para>The table name (string).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>values</parameter>
</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>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Bad argument type or too many (any) arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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 type-check 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>write a line to the server socket [DA]</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
putline(<parameter>line</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-PUTLINE-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>line</parameter>
</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>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Bad argument type or too many (any) arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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>get 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>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Bad argument type or too many (any) arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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>synchronize 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>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Bad argument type or too many (any) arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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>create a large object in the database [LO]</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
locreate(<parameter>mode</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-LOCREATE-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>mode</parameter>
</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>
<classname>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>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Bad argument type or too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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</literal> and <literal>INV_WRITE</literal>).
</para>
</refsect1>
</refentry>
<!-- ********************************************************** -->
<refentry id="PYGRESQL-GETLO">
<refmeta>
<refentrytitle>getlo</refentrytitle>
<refmiscinfo>PYGRESQL - Getlo</refmiscinfo>
</refmeta>
<refnamediv>
<refname>getlo</refname>
<refpurpose>build a large object from given OID [LO]</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
getlo(<parameter>oid</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-GETLO-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>oid</parameter>
</term>
<listitem>
<para>OID of the existing large object (integer).</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id="R2-PYGRESQL-GETLO-2">
<title>Return Type</title>
<variablelist>
<varlistentry>
<term>
<classname>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>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Bad argument type or too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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 has its OID.
</para>
</refsect1>
</refentry>
<!-- ********************************************************** -->
<refentry id="PYGRESQL-LOIMPORT">
<refmeta>
<refentrytitle>loimport</refentrytitle>
<refmiscinfo>PYGRESQL - Loimport</refmiscinfo>
</refmeta>
<refnamediv>
<refname>loimport</refname>
<refpurpose>import a file to a <productname>PostgreSQL</productname> large object [LO]</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
loimport(<parameter>filename</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-LOIMPORT-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>filename</parameter>
</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>
<classname>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>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Bad argument type or too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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>
The <literal>pg</literal> module contains a class called
<classname>DB</classname> wrapping a <classname>pgobject</classname>.
This <classname>pgobject</classname> can be addressed as a
<classname>DB</classname> class member named <varname>db</varname>
to get access to the read-only attributes of the corresponding connection
(e.g. <varname>db.error</varname>). All <classname>pgobject</classname>
methods (e.g. <function>query()</function>) are directly included as members
in the class <classname>DB</classname> also. A number of additional
higher level <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>return the primary key of a table</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
pkey(<parameter>table</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-DB-PKEY-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>table</parameter>
</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>return the attribute names of a table</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
get_attnames(<parameter>table</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-DB-GET-ATTNAMES-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>table</parameter>
</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>
dictionary
</term>
<listitem>
<para>
The dictionary's keys are
the attribute names, the values are the type names of
the attributes.
</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 set of attribute names
and types.
</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(<parameter>table</parameter>, <parameter>arg</parameter>, <optional><parameter>keyname</parameter></optional>)
</synopsis>
<refsect2 id="R2-PYGRESQL-DB-GET-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>table</parameter>
</term>
<listitem>
<para>
Name of table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>arg</parameter>
</term>
<listitem>
<para>
Either a dictionary or the value to be looked up.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<optional><parameter>keyname</parameter></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 <parameter>keyname</> is not specified
then the primary key for the table is used. If <parameter>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(<parameter>table</parameter>, <parameter>a</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-DB-INSERT-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>table</parameter>
</term>
<listitem>
<para>
Name of table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>a</parameter>
</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>
<para>
Due to the way that this function works you will find inserts
taking longer and longer as your table gets bigger. To
overcome this problem simply add an index onto the OID of any
table that you think may get large over time.
</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(<parameter>table</parameter>, <parameter>a</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-DB-UPDATE-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>table</parameter>
</term>
<listitem>
<para>
Name of table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>a</parameter>
</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(<parameter>table</parameter>, <optional><parameter>a</parameter></optional>)
</synopsis>
<refsect2 id="R2-PYGRESQL-DB-CLEAR-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>table</parameter>
</term>
<listitem>
<para>
Name of table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<optional><parameter>a</parameter></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>delete a row from a table</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
delete(<parameter>table</parameter>, <optional><parameter>a</parameter></optional>)
</synopsis>
<refsect2 id="R2-PYGRESQL-DB-DELETE-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>table</parameter>
</term>
<listitem>
<para>
Name of table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<optional><parameter>a</parameter></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: <classname>pgqueryobject</classname></title>
<!-- ********************************************************** -->
<refentry id="PYGRESQL-PGQUERYOBJECT-GETRESULT">
<refmeta>
<refentrytitle>getresult</refentrytitle>
<refmiscinfo>PYGRESQL - Getresult</refmiscinfo>
</refmeta>
<refnamediv>
<refname>getresult</refname>
<refpurpose>get 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>
<classname>SyntaxError</classname>
</term>
<listitem>
<para>
Too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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>get the values returned by the query as 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>
<classname>SyntaxError</classname>
</term>
<listitem>
<para>
Too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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>list 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>
<classname>SyntaxError</classname>
</term>
<listitem>
<para>
Too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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>get field name by number</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
fieldname(<parameter>i</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>i</parameter>
</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>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Bad parameter type, or too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>ValueError</classname>
</term>
<listitem>
<para>
Invalid field number.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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>get field number by name</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
fieldnum(<parameter>name</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>name</parameter>
</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>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Bad parameter type, or too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>ValueError</classname>
</term>
<listitem>
<para>
Unknown field name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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>return 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>
<classname>SyntaxError</classname>
</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><structfield>oid</></term>
<listitem>
<para>
the OID associated with the object
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><structfield>pgcnx</></term>
<listitem>
<para>
the <classname>pgobject</classname> associated with the object
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><structfield>error</></term>
<listitem>
<para>
the last warning/error message of the connection
</para>
</listitem>
</varlistentry>
</variablelist>
<important>
<para>
In multithreaded environments, <structfield>error</structfield>
may be modified by another thread using the same
<classname>pgobject</classname>. Remember that these object are
shared, not duplicated; you should provide some locking if you
want to check for the error message in this situation. The OID
attribute is very interesting because it allow you to reuse the
OID later, creating the <classname>pglarge</classname> object
with a <classname>pgobject</classname>
<function>getlo()</function> method call.
</para>
</important>
</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>open a large object</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
open(<parameter>mode</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>mode</parameter>
</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>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Bad parameter type, or too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>IOError</classname>
</term>
<listitem>
<para>
Already opened object, or open error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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 Unix <function>open()</function>
function. The mode value can be obtained by OR-ing the constants defined in
the pg module (<literal>INV_READ</literal>, <literal>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>close 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>
<classname>SyntaxError</classname>
</term>
<listitem>
<para>
Too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>IOError</classname>
</term>
<listitem>
<para>
Object is not opened, or close error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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 Unix <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>read from the large object</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
read(<parameter>size</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>size</parameter>
</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>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Bad parameter type, or too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>IOError</classname>
</term>
<listitem>
<para>
Object is not opened, or read error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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>write to the large object</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
write(<parameter>string</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>string</parameter>
</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>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Bad parameter type, or too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>IOError</classname>
</term>
<listitem>
<para>
Object is not opened, or write error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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(<parameter>offset</parameter>, <parameter>whence</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>offset</parameter>
</term>
<listitem>
<para>
Position offset (integer).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>whence</parameter>
</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>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Bad parameter type, or too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>IOError</classname>
</term>
<listitem>
<para>
Object is not opened, or seek error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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</>, <literal>SEEK_CUR</>, <literal>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>return 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>
<classname>SyntaxError</classname>
</term>
<listitem>
<para>
Too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>IOError</classname>
</term>
<listitem>
<para>
Object is not opened, or seek error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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>delete 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>
<classname>SyntaxError</classname>
</term>
<listitem>
<para>
Too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>IOError</classname>
</term>
<listitem>
<para>
Object is not closed, or unlink error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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>return 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>
<classname>SyntaxError</classname>
</term>
<listitem>
<para>
Too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>IOError</classname>
</term>
<listitem>
<para>
Object is not opened, or seek/tell error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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 first.
</para>
</refsect1>
</refentry>
<!-- ********************************************************** -->
<refentry id="PYGRESQL-PGLARGEOBJECT-EXPORT">
<refmeta>
<refentrytitle>export</refentrytitle>
<refmiscinfo>PYGRESQL - Export</refmiscinfo>
</refmeta>
<refnamediv>
<refname>export</refname>
<refpurpose>save the large object to file</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
export(<parameter>filename</parameter>)
</synopsis>
<refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-1">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>filename</parameter>
</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>
<classname>TypeError</classname>
</term>
<listitem>
<para>
Bad argument type, or too many arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>IOError</classname>
</term>
<listitem>
<para>
Object is not closed, or export error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<classname>pg.error</classname>
</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>
</chapter>
View Git Blame Copy Permalink