<!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/pygresql.sgml,v 1.2 2001/09/10 04:15:41 momjian 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>
     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>&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 <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>
      <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 and INV_WRITE</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>
