pygresql.sgml

<!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/pygresql.sgml,v 1.10 2003/04/07 01:29:25 petere Exp $ -->

<chapter id="pygresql">
 <title><application>PyGreSQL</application> - <application>Python</application> Interface</title>

 <note>
  <title>Author</title>
  <para>
   Written by D'Arcy J.M. Cain (<email>darcy@druid.net</email>).
   Based heavily on code written by Pascal Andre
   <email>andre@chimay.via.ecp.fr</email>.  Copyright &copy; 1995,
   Pascal Andre.  Further modifications Copyright &copy; 1997-2000 by
   D'Arcy J.M. Cain.
  </para>
 </note>


<![IGNORE[
 <sect1 id="pygresql-install">
  <title>Installation</title>

  <itemizedlist>
   <listitem>
    <para>
     Note that if you are using the <acronym>DB-API</acronym> module
     you must also install <literal>mxDateTime</literal> from <ulink
     url="http://starship.python.net/~lemburg/mxDateTime.html"
     >http://starship.python.net/~lemburg/mxDateTime.html</ulink>.
    </para>
   </listitem>

   <listitem>
    <para>
     Also, check out <filename>setup.py</filename> for an alternate
     method of installing the package using <application>Python</application>'s Distutils.
    </para>
   </listitem>
  </itemizedlist>
    
  <para>
   You have two options. You can compile
   <application>PyGreSQL</application> as a stand-alone module or you
   can build it into the <application>Python</application>
   interpreter.
  </para>

  <sect2>
   <title>General</title>

   <itemizedlist>
    <listitem>
     <para>
      You must first have installed <application>Python</application>
      and <productname>PostgreSQL</productname> on your system.  The
      header files and developer's libraries for both
      <application>Python</application> and
      <productname>PostgreSQL</productname> must be installed on your
      system before you can build <application>PyGreSQL</application>.
      If you built both <application>Python</application> and
      <productname>PostgreSQL</productname> from source, you should be
      fine.  If your system uses some package mechanism (such as
      <acronym>RPM</acronym> or <systemitem class="osname">NetBSD</systemitem> packages),
      then you probably need to install packages such as
      <application>Python-devel</application> in addition to the
      <application>Python</application> package.
     </para>
    </listitem>

    <listitem>
     <para>
      <application>PyGreSQL</application> is implemented as three
      parts, a C module labeled <literal>_pg</literal> and two
      <application>Python</application> wrappers called
      <filename>pg.py</filename> and <filename>pgdb.py</filename>.
      This changed between 2.1 and 2.2 and again in 3.0.  These
      changes should not affect any existing programs but the
      installation is slightly different.
     </para>
    </listitem>

    <listitem>
     <para>
      Download and unpack the <application>PyGreSQL</application>
      tarball if you haven't already done so.
     </para>
    </listitem>
   </itemizedlist>
  </sect2>

  <sect2>
   <title>Stand-alone</title>

   <itemizedlist>
    <listitem>
     <para>
      In the directory containing <filename>pgmodule.c</filename>, run
      the following command

<programlisting>
cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c
</programlisting>

      where:
      <itemizedlist>
       <listitem>
        <para>
         [pyInc] = path of the <application>Python</application>
         include (usually <filename>Python.h</filename>)
        </para>
       </listitem>

       <listitem>
        <para>
         [pgInc] = path of the <productname>PostgreSQL</productname>
         include (usually <filename>postgres.h</filename>)
        </para>
       </listitem>

       <listitem>
        <para>
         [pgLib] = path of the <productname>PostgreSQL</productname>
         libraries (usually <filename>libpq.so</filename> or
         <filename>libpq.a</filename>)
        </para>
       </listitem>
      </itemizedlist>

      Some options may be added to this line:
      <itemizedlist>
       <listitem>
        <para>
         <option>-DNO_DEF_VAR</option> - no default variables
         support
        </para>
       </listitem>

       <listitem>
        <para>
         <option>-DNO_DIRECT</option>   - no direct access methods
        </para>
       </listitem>

       <listitem>
        <para>
         <option>-DNO_LARGE</option>    - no large object support
        </para>
       </listitem>

       <listitem>
        <para>
         <option>-DNO_SNPRINTF</option> - if running a system with
         no snprintf call
        </para>
       </listitem>

       <listitem>
        <para>
         <option>-DNO_PQSOCKET</option> - if running an older
         <productname>PostgreSQL</productname>
        </para>
       </listitem>
      </itemizedlist>

      On some systems you may need to include
      <option>-lcrypt</option> in the list of libraries to make it
      compile.

      Define <option>DNO_PQSOCKET</option> if you are using a
      version of <productname>PostgreSQL</productname> before 6.4 that
      does not have the <function>PQsocket</function> function.  The
      other options will be described in the next sections.
     </para>
    </listitem>
   <listitem>

   <para>
    Test the new module.  Something like the following should work.
<screen>
<prompt>$</prompt> <userinput>python</userinput>

<prompt>&gt;&gt;&gt;</prompt> <userinput>import _pg</userinput>
<prompt>&gt;&gt;&gt;</prompt> <userinput>db = _pg.connect('thilo', 'localhost')</userinput>
<prompt>&gt;&gt;&gt;</prompt> <userinput>db.query("INSERT INTO test VALUES ('ping', 'pong');")</userinput>
18304
<prompt>&gt;&gt;&gt;</prompt> <userinput>db.query("SELECT * FROM test;")</userinput>
 eins | zwei
------+------
 ping | pong
(1 row)
</screen>
          </para>
        </listitem>
        <listitem>
          <para>
            Finally, move the <filename>_pg.so</filename>,
            <filename>pg.py</filename>, and <filename>pgdb.py</filename>
            to a directory in your <envar>PYTHONPATH</envar>.
            A good place would be
            <filename>/usr/lib/python1.5/site-python</filename>
            if your <application>Python</application> modules are in
            <filename>/usr/lib/python1.5</filename>.
          </para>
        </listitem>
      </itemizedlist>
    </sect2>


    <sect2>
      <title>Built-in to python interpreter</title>

      <itemizedlist>
        <listitem>
          <para>
            Find the directory where your <filename>Setup</filename>
            file lives (usually <filename>??/Modules</filename>) in 
            the <application>Python</application> source hierarchy and
            copy or symlink the <filename>pgmodule.c</filename> file there.
          </para>
        </listitem>
        <listitem>
          <para>
            Add the following line to your <filename>Setup</> file
<programlisting>
_pg  pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems
</programlisting>
            where:
            <itemizedlist>
              <listitem>
                <para>
                  [pgInc] = path of the <productname>PostgreSQL</productname>
                  include (usually <filename>postgres.h</filename>)
                </para>
              </listitem>
              <listitem>
                <para>
                  [pgLib] = path of the <productname>PostgreSQL</productname>
                  libraries (usually <filename>libpq.so</filename>
                  or <filename>libpq.a</filename>)
                </para>
              </listitem>
            </itemizedlist>
            Some options may be added to this line:
            <itemizedlist>
              <listitem>
                <para>
                  <option>-DNO_DEF_VAR</option>  - no default variables
                  support
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>-DNO_DIRECT</option>   - no direct access methods
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>-DNO_LARGE</option>    - no large object support
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>-DNO_SNPRINTF</option> - if running a system with
                  no snprintf call
                </para>
              </listitem>
              <listitem>
                <para>
                  <option>-DNO_PQSOCKET</option> - if running an older
                  <productname>PostgreSQL</productname>
                </para>
              </listitem>
            </itemizedlist>

            Define <option>-DNO_PQSOCKET</option> if you are using a version of
            <productname>PostgreSQL</productname> before 6.4
            that does not have the <function>PQsocket</function> function.
            The other options will be described in the next sections.
          </para>
        </listitem>
        <listitem>
          <para>
            If you want a shared module, make sure that the 
            <literal>*shared*</literal> key word is uncommented and
            add the above line below it. You used to need to install
            your shared modules with <literal>make sharedinstall</> but this no
            longer seems to be true.
          </para>
        </listitem>
        <listitem>
          <para>
            Copy <filename>pg.py</filename> to the lib directory where
            the rest of your modules are. For example, that's
            <filename>/usr/local/lib/Python</filename> on my system.
          </para>
        </listitem>
        <listitem>
          <para>
            Rebuild <application>Python</application> from the root
            directory of the <application>Python</application> source
            hierarchy by running
<programlisting>
make -f Makefile.pre.in boot
make && make install
</programlisting>
          </para>
        </listitem>
        <listitem>
          <para>
            For more details read the documentation at the top of
            <filename>Makefile.pre.in</filename>
          </para>
        </listitem>
      </itemizedlist>
    </sect2>

  </sect1>

]]>

 <para>
  You may either choose to use the old mature interface provided by
  the <literal>pg</literal> module or otherwise the newer
  <literal>pgdb</literal> interface compliant with the <ulink
  url="http://www.python.org/topics/database/DatabaseAPI-2.0.html"
  ><acronym>DB-API 2.0</acronym></ulink> specification developed by
  the <application>Python</application> <acronym>DB-SIG</acronym>.
 </para>

 <para>
  Here we describe only the older <literal>pg</literal>
  <acronym>API</acronym>. As long as
  <application>PyGreSQL</application> does not contain a description
  of the <acronym>DB-API</acronym> you should read about the
  <acronym>API</acronym> at <ulink
  url="http://www.python.org/topics/database/DatabaseAPI-2.0.html"
  >http://www.python.org/topics/database/DatabaseAPI-2.0.html</ulink>.
  A tutorial-like introduction to the <acronym>DB-API</acronym> can be
  found at <ulink
  url="http://www2.linuxjournal.com/lj-issues/issue49/2605.html"
  >http://www2.linuxjournal.com/lj-issues/issue49/2605.html</ulink>.
 </para>

 <sect1 id="pygresql-pg">
  <title>The <literal>pg</literal> Module</title>

  <para>
   The <literal>pg</literal> module defines three objects:
   <itemizedlist>
    <listitem>
     <para>
      <classname>pgobject</classname>, which handles the connection and all the
      requests to the database,
     </para>
    </listitem>

    <listitem>
     <para>
      <classname>pglargeobject</classname>, which handles all the accesses
      to <productname>PostgreSQL</productname> large objects, and
     </para>
    </listitem>

    <listitem>
     <para>
      <classname>pgqueryobject</classname>, which handles query results.
     </para>
    </listitem>
   </itemizedlist>
  </para>

  <para>
   If you want to see a simple example of the use this module,
   see <ulink url="http://www.druid.net/rides"></ulink> where you can find a link at the
   bottom to the actual <application>Python</application> code for the
   page.
  </para>

  <sect2>
   <title>Constants</title>

   <para>
    Some constants are defined in the <literal>pg</literal> module
    dictionary.  They are intended to be used as a parameters for
    methods calls.  You should refer to the <application>libpq</application>
    description (<xref linkend="libpq">) for more information about
    them. These constants are:

    <variablelist>
     <varlistentry>
      <term><varname>INV_READ</varname></term>
      <term><varname>INV_WRITE</varname></term>
      <listitem>
       <para>
        Large objects access modes, used by
        <function>(pgobject.)locreate</function> and
        <function>(pglarge.)open</function>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><varname>SEEK_SET</varname></term>
      <term><varname>SEEK_CUR</varname></term>
      <term><varname>SEEK_END</varname></term>
      <listitem>
       <para>
        Positional flags, used by <function>(pglarge.)seek</function>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><varname>version</varname></term>
      <term><varname>__version__</varname></term>
      <listitem>
       <para>
        Constants that give the current version
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>
 </sect1>


 <sect1 id="pygresql-pg-functions">
  <title><literal>pg</literal> Module Functions</title>

  <para>
   <literal>pg</literal> module defines only a few methods that allow
   to connect to a database and to define <quote>default
   variables</quote> that override the environment variables used by
   <productname>PostgreSQL</productname>.
  </para>

  <para>
   These <quote>default variables</quote> were designed to allow you
   to handle general connection parameters without heavy code in your
   programs. You can prompt the user for a value, put it in the
   default variable, and forget it, without having to modify your
   environment. The support for default variables can be disabled at build time by
   setting the <option>-DNO_DEF_VAR</option> option in the Python
   <filename>Setup</> file. Methods relative to this are specified by the tag [DV].
  </para>

  <para>
   All default values are set to <symbol>None</symbol> at module
   initialization, specifying that standard environment variables
   should be used.
  </para>

  <refentry id="pygresql-connect">
   <refmeta>
    <refentrytitle>connect</refentrytitle>
    <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
   </refmeta>

   <refnamediv>
    <refname>connect</refname>
    <refpurpose>open a connection to the database server</refpurpose>
   </refnamediv>

   <refsynopsisdiv>
<synopsis>
connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter>host</parameter></optional>, <optional><parameter>port</parameter></optional>, <optional><parameter>opt</parameter></optional>, <optional><parameter>tty</parameter></optional>, <optional><parameter>user</parameter></optional>, <optional><parameter>passwd</parameter></optional>)
</synopsis>

    <refsect2 id="pygresql-connect-parameters">
     <title>Parameters</title>
          
     <variablelist>
      <varlistentry>
       <term><parameter>dbname</parameter></term>

       <listitem>
        <para>Name of connected database (string/<symbol>None</>)</para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><parameter>host</parameter></term>

       <listitem>
        <para>Name of the server host (string/<symbol>None</>)</para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><parameter>port</parameter></term>

       <listitem>
        <para>Port used by the database server (integer/-1)</para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><parameter>opt</parameter></term>

       <listitem>
        <para>
         Options for the server (string/<symbol>None</>)
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><parameter>tty</parameter></term>

       <listitem>
        <para>
         File or TTY for optional debug output from server
         (string/<symbol>None</>)
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><parameter>user</parameter></term>

       <listitem>
        <para>
         <productname>PostgreSQL</productname> user (string/<symbol>None</>)
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><parameter>passwd</parameter></term>

       <listitem>
        <para>Password for user (string/<symbol>None</>)</para>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect2>
        
    <refsect2 id="pygresql-connect-return">
     <title>Return Type</title>

     <variablelist>
      <varlistentry>
       <term><parameter>pgobject</parameter></term>

       <listitem>
        <para>
         If successful, an object handling a database connection is returned.
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect2>
        
    <refsect2 id="pygresql-connect-exceptions">
     <title>Exceptions</title>

     <variablelist>
      <varlistentry>
       <term><classname>TypeError</classname></term>

       <listitem>
        <para>
         Bad argument type, or too many arguments.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><classname>SyntaxError</classname></term>

       <listitem>
        <para>
         Duplicate argument definition.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><classname>pg.error</classname></term>

       <listitem>
        <para>
         Some error occurred during <literal>pg</> connection definition.
        </para>
       </listitem>
      </varlistentry>
     </variablelist>

     <para>
      (plus all exceptions relative to object allocation)
     </para>
    </refsect2>
   </refsynopsisdiv>
      
   <refsect1 id="pygresql-connect-description">
    <title>Description</title>

    <para>
     This method opens a connection to a specified database on a given
     <productname>PostgreSQL</productname> server. The arguments can be
     given using key words here.  The names of the
     key words are the name of the parameters given in the syntax
     line. For a precise description of the parameters, please refer
     to <xref linkend="libpq">.
    </para>
   </refsect1>
      
   <refsect1 id="pygresql-connect-examples">
    <title>Examples</title>

    <para>
<programlisting>
import pg

con1 = pg.connect('testdb', 'myhost', 5432, None, None, 'bob', None)
con2 = pg.connect(dbname='testdb', host='localhost', user='bob')
</programlisting>
    </para>
   </refsect1>
      
  </refentry>


  <refentry id="pygresql-get-defhost">
   <refmeta>
    <refentrytitle>get_defhost</refentrytitle>
    <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
   </refmeta>

   <refnamediv>
    <refname>get_defhost</refname>
    <refpurpose>get default host name [DV]</refpurpose>
   </refnamediv>

   <refsynopsisdiv>
<synopsis>
get_defhost()
</synopsis>

    <refsect2 id="pygresql-get-defhost-parameters">
     <title>Parameters</title>

     <para>
      none
     </para>
    </refsect2>

    <refsect2 id="pygresql-get-defhost-return">
     <title>Return Type</title>

     <variablelist>
      <varlistentry>
       <term>string or <symbol>None</></term>

       <listitem>
        <para>
         Default host specification
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect2>

    <refsect2 id="pygresql-get-defhost-exceptions">
     <title>Exceptions</title>

     <variablelist>
      <varlistentry>
       <term><classname>SyntaxError</classname></term>

       <listitem>
        <para>
         Too many arguments.
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect2>

   </refsynopsisdiv>

   <refsect1 id="pygresql-get-defhost-description">
    <title>Description</title>

    <para>
     <function>get_defhost()</function> returns the current default
     host specification, or <symbol>None</> if the environment variables should
     be used. Environment variables will not be looked up.
    </para>
   </refsect1>

  </refentry>


  <refentry id="pygresql-set-defhost">
   <refmeta>
    <refentrytitle>set_defhost</refentrytitle>
    <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
   </refmeta>

   <refnamediv>
    <refname>set_defhost</refname>
    <refpurpose>set default host name [DV]</refpurpose>
   </refnamediv>

   <refsynopsisdiv>
<synopsis>
set_defhost(<parameter>host</parameter>)
</synopsis>

    <refsect2 id="pygresql-set-defhost-parameters">
     <title>Parameters</title>
     <variablelist>
      <varlistentry>
       <term>
        <parameter>host</parameter>
       </term>
       <listitem>
        <para>New default host (string/<symbol>None</>).</para>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect2>

    <refsect2 id="pygresql-set-defhost-return">
     <title>Return Type</title>
     <variablelist>
      <varlistentry>
       <term>
        string or <symbol>None</>
       </term>
       <listitem>
        <para>
         Previous default host specification.
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect2>

    <refsect2 id="pygresql-set-defhost-exceptions">
     <title>Exceptions</title>
     <variablelist>
      <varlistentry>
       <term>
        <classname>TypeError</classname>
       </term>
       <listitem>
        <para>
         Bad argument type, or too many arguments.
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect2>

   </refsynopsisdiv>

   <refsect1 id="pygresql-set-defhost-description">
    <title>Description</title>
    <para>
     <function>set_defhost()</function> sets the default host value
     for new connections. If <symbol>None</symbol> is supplied as parameter, environment
     variables will be used in future connections. It returns the 
     previous setting for default host.
    </para>
   </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="pygresql-get-defport">
    <refmeta>
      <refentrytitle>get_defport</refentrytitle>
      <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>get_defport</refname>
      <refpurpose>get default port [DV]</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
get_defport()
</synopsis>

      <refsect2 id="R2-PYGRESQL-GET-DEFPORT-1">
        <title>Parameters</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-GET-DEFPORT-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              integer or <symbol>None</symbol>
            </term>
            <listitem>
              <para>
                Default port specification
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-GET-DEFPORT-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>SyntaxError</classname>
            </term>
            <listitem>
              <para>
                Too many arguments.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-GET-DEFPORT-1">
      <title>Description</title>
      <para>
        <function>get_defport()</function> returns the current default
        port specification, or <symbol>None</symbol> if the environment variables should
        be used. Environment variables will not be looked up.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-SET-DEFPORT">
    <refmeta>
      <refentrytitle>set_defport</refentrytitle>
      <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>set_defport</refname>
      <refpurpose>set default port [DV]</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
set_defport(<parameter>port</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-SET-DEFPORT-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>port</parameter>
            </term>
            <listitem>
              <para>New default host (integer/-1).</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-SET-DEFPORT-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              integer or <symbol>None</symbol>
            </term>
            <listitem>
              <para>
                Previous default port specification.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-SET-DEFPORT-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad argument type, or too many arguments.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-SET-DEFPORT-1">
      <title>Description</title>
      <para>
        <function>set_defport()</function> sets the default port value
        for new connections. If -1 is supplied as parameter, environment
        variables will be used in future connections. It returns the 
        previous setting for default port.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-GET-DEFOPT">
    <refmeta>
      <refentrytitle>get_defopt</refentrytitle>
      <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>get_defopt</refname>
      <refpurpose>get default options specification [DV]</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
get_defopt()
</synopsis>

      <refsect2 id="R2-PYGRESQL-GET-DEFOPT-1">
        <title>Parameters</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-GET-DEFOPT-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              string or <symbol>None</symbol>
            </term>
            <listitem>
              <para>
                Default options specification
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-GET-DEFOPT-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>SyntaxError</classname>
            </term>
            <listitem>
              <para>
                Too many arguments.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-GET-DEFOPT-1">
      <title>Description</title>
      <para>
        <function>get_defopt()</function> returns the current default
        connection options specification, or <symbol>None</symbol> if the environment variables should
        be used. Environment variables will not be looked up.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-SET-DEFOPT">
    <refmeta>
      <refentrytitle>set_defopt</refentrytitle>
      <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>set_defopt</refname>
      <refpurpose>set default options specification [DV]</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
set_defopt(<parameter>options</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-SET-DEFOPT-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>options</parameter>
            </term>
            <listitem>
              <para>New default connection options (string/<symbol>None</symbol>).</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-SET-DEFOPT-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              string or <symbol>None</symbol>
            </term>
            <listitem>
              <para>
                Previous default opt specification.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-SET-DEFOPT-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad argument type, or too many arguments.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-SET-DEFOPT-1">
      <title>Description</title>
      <para>
        <function>set_defopt()</function> sets the default connection options value
        for new connections. If <symbol>None</symbol> is supplied as parameter, environment
        variables will be used in future connections. It returns the 
        previous setting for default options.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-GET-DEFTTY">
    <refmeta>
      <refentrytitle>get_deftty</refentrytitle>
      <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>get_deftty</refname>
      <refpurpose>get default connection debug terminal specification [DV]</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
get_deftty()
</synopsis>

      <refsect2 id="R2-PYGRESQL-GET-DEFTTY-1">
        <title>Parameters</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-GET-DEFTTY-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              string or <symbol>None</symbol>
            </term>
            <listitem>
              <para>
                Default debug terminal specification
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-GET-DEFTTY-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>SyntaxError</classname>
            </term>
            <listitem>
              <para>
                Too many arguments.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-GET-DEFTTY-1">
      <title>Description</title>
      <para>
        <function>get_deftty()</function> returns the current default
        debug terminal specification, or <symbol>None</symbol> if the environment variables should
        be used. Environment variables will not be looked up.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-SET-DEFTTY">
    <refmeta>
      <refentrytitle>set_deftty</refentrytitle>
      <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>set_deftty</refname>
      <refpurpose>set default connection debug terminal specification [DV]</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
set_deftty(<parameter>terminal</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-SET-DEFTTY-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>terminal</parameter>
            </term>
            <listitem>
              <para>New default debug terminal (string/<symbol>None</symbol>).</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-SET-DEFTTY-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              string or <symbol>None</symbol>
            </term>
            <listitem>
              <para>
                Previous default debug terminal specification.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-SET-DEFTTY-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad argument type, or too many arguments.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-SET-DEFTTY-1">
      <title>Description</title>
      <para>
        <function>set_deftty()</function> sets the default terminal value
        for new connections. If <symbol>None</symbol> is supplied as parameter, environment
        variables will be used in future connections. It returns the 
        previous setting for default terminal.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-GET-DEFBASE">
    <refmeta>
      <refentrytitle>get_defbase</refentrytitle>
      <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>get_defbase</refname>
      <refpurpose>get default database name specification [DV]</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
get_defbase()
</synopsis>

      <refsect2 id="R2-PYGRESQL-GET-DEFBASE-1">
        <title>Parameters</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-GET-DEFBASE-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              string or <symbol>None</symbol>
            </term>
            <listitem>
              <para>
                Default debug database name specification
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-GET-DEFBASE-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>SyntaxError</classname>
            </term>
            <listitem>
              <para>
                Too many arguments.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-GET-DEFBASE-1">
      <title>Description</title>
      <para>
        <function>get_defbase()</function> returns the current default
        database name specification, or <symbol>None</symbol> if the environment variables should
        be used. Environment variables will not be looked up.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-SET-DEFBASE">
    <refmeta>
      <refentrytitle>set_defbase</refentrytitle>
      <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>set_defbase</refname>
      <refpurpose>set default database name specification [DV]</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
set_defbase(<parameter>database</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-SET-DEFBASE-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>database</parameter>
            </term>
            <listitem>
              <para>New default database name (string/<symbol>None</symbol>).</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-SET-DEFBASE-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              string or <symbol>None</symbol>
            </term>
            <listitem>
              <para>
                Previous default database name specification.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-SET-DEFBASE-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad argument type, or too many arguments.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-SET-DEFBASE-1">
      <title>Description</title>
      <para>
        <function>set_defbase()</function> sets the default database name
        for new connections. If <symbol>None</symbol> is supplied as parameter, environment
        variables will be used in future connections. It returns the 
        previous setting for default database name.
      </para>
    </refsect1>

  </refentry>

 </sect1>


 <sect1 id="pygresql-pg-pgobject">
  <title>Connection Object: <classname>pgobject</classname></title>

  <para>
   This object handles a connection to the
   <productname>PostgreSQL</productname> database.  It embeds and
   hides all the parameters that define this connection, leaving just
   really significant parameters in function calls.
  </para>

  <para>
   Some methods give direct access to the connection socket. They are
   specified by the tag [DA].  <emphasis>Do not use them unless you
   really know what you are doing.</emphasis> If you prefer disabling
   them, set the <option>-DNO_DIRECT</option> option in the
   <application>Python</application> <filename>Setup</filename> file.
  </para>

  <para>
   Some other methods give access to large objects.  if you want to
   forbid access to these from the module, set the
   <option>-DNO_LARGE</option> option in the
   <application>Python</application> <filename>Setup</filename> file.
   These methods are specified by the tag [LO].
  </para>

  <para>
   Every <classname>pgobject</classname> defines a set of read-only
   attributes that describe the connection and its status. These
   attributes are:

   <variablelist>
    <varlistentry>
     <term>host</term>    
     <listitem>
      <para>
       the host name of the server (string)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>port</term>
     <listitem>
      <para>
       the port of the server (integer)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>db</term>
     <listitem>
      <para>
       the selected database (string)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>options</term>
     <listitem>
      <para>
       the connection options (string)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>tty</term>
     <listitem>
      <para>
       the connection debug terminal (string)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>user</term>
     <listitem>
      <para>
       user name on the database system (string)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>status</term>
     <listitem>
      <para>
       the status of the connection (integer: 1 - OK, 0 - bad)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>error</term>
     <listitem>
      <para>
       the last warning/error message from the server (string)
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>


  <refentry id="PYGRESQL-QUERY">
    <refmeta>
      <refentrytitle>query</refentrytitle>
      <refmiscinfo>PYGRESQL - Query</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>query</refname>
      <refpurpose>execute a SQL command</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
query(<parameter>command</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-QUERY-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>command</parameter>
            </term>
            <listitem>
              <para>SQL command (string).</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-QUERY-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>pgqueryobject</> or <symbol>None</symbol>
            </term>
            <listitem>
              <para>
                Result values.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-QUERY-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad argument type, or too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>ValueError</classname>
            </term>
            <listitem>
              <para>
                Empty SQL query.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Error during query processing, or invalid connection.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-QUERY-1">
      <title>Description</title>
      <para>
        <function>query()</function> method sends a <acronym>SQL</acronym>
        query to the database. If the query is an insert statement, the return
        value is the <acronym>OID</acronym> of the newly inserted row.
        If it is otherwise a query that does not return a result
        (i.e., is not a some kind of <literal>SELECT</literal> statement), it returns <symbol>None</symbol>.
        Otherwise, it returns a <classname>pgqueryobject</classname> that can be accessed via the
        <function>getresult()</function> or <function>dictresult()</function>
          methods or simply printed.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-RESET">
    <refmeta>
      <refentrytitle>reset</refentrytitle>
      <refmiscinfo>PYGRESQL - Reset</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>reset</refname>
      <refpurpose>reset the connection</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
reset()
</synopsis>

      <refsect2 id="R2-PYGRESQL-RESET-1">
        <title>Parameters</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-RESET-2">
        <title>Return Type</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-RESET-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Too many (any) arguments.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-RESET-1">
      <title>Description</title>
      <para>
        <function>reset()</function> method resets the current database.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-CLOSE">
    <refmeta>
      <refentrytitle>close</refentrytitle>
      <refmiscinfo>PYGRESQL - Close</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>close</refname>
      <refpurpose>close the database connection</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
close()
</synopsis>

      <refsect2 id="R2-PYGRESQL-CLOSE-1">
        <title>Parameters</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-CLOSE-2">
        <title>Return Type</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-CLOSE-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Too many (any) arguments.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-CLOSE-1">
      <title>Description</title>
      <para>
        <function>close()</function> method closes the database connection.
        The connection will be closed in any case when the connection is deleted but this
        allows you to explicitly close it.  It is mainly here to allow
        the DB-SIG API wrapper to implement a close function.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-FILENO">
    <refmeta>
      <refentrytitle>fileno</refentrytitle>
      <refmiscinfo>PYGRESQL - Fileno</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>fileno</refname>
      <refpurpose>return the socket used to connect to the database</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
fileno()
</synopsis>

      <refsect2 id="R2-PYGRESQL-FILENO-1">
        <title>Parameters</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-FILENO-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              socket id
            </term>
            <listitem>
              <para>
                The underlying socket id used to connect to the database.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-FILENO-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Too many (any) arguments.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-FILENO-1">
      <title>Description</title>
      <para>
        <function>fileno()</function> method returns the underlying socket id used to connect
        to the database. This is useful for use in <function>select</function> calls, etc.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-GETNOTIFY">
    <refmeta>
      <refentrytitle>getnotify</refentrytitle>
      <refmiscinfo>PYGRESQL - Getnotify</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>getnotify</refname>
      <refpurpose>get the last notify from the server</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
getnotify()
</synopsis>

      <refsect2 id="R2-PYGRESQL-GETNOTIFY-1">
        <title>Parameters</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-GETNOTIFY-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              tuple, <symbol>None</symbol>
            </term>
            <listitem>
              <para>
                Last notify from server
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-GETNOTIFY-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Too many (any) arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid connection.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-GETNOTIFY-1">
      <title>Description</title>
      <para>
        <function>getnotify()</function> method tries to get a notify from
        the server (from the SQL statement <literal>NOTIFY</literal>).
        If the server returns no notify, the methods returns <symbol>None</symbol>. 
        Otherwise, it returns a tuple (couple) <literal>(relname, pid)</literal>,
        where <literal>relname</literal> is the name of the notify and <literal>pid</literal>
        the process id of the connection that triggered the notify.
        Remember to do a listen query first otherwise <function>getnotify</> will always return <symbol>None</symbol>.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-INSERTTABLE">
    <refmeta>
      <refentrytitle>inserttable</refentrytitle>
      <refmiscinfo>PYGRESQL - Inserttable</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>inserttable</refname>
      <refpurpose>insert a list into a table</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
inserttable(<parameter>table</parameter>, <parameter>values</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-INSERTTABLE-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>table</parameter>
            </term>
            <listitem>
              <para>The table name (string).</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <parameter>values</parameter>
            </term>
            <listitem>
              <para>The list of rows values to insert (list).</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-INSERTTABLE-2">
        <title>Return Type</title>
          <para>
            none
          </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-INSERTTABLE-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad argument type or too many (any) arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid connection.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-INSERTTABLE-1">
      <title>Description</title>
      <para>
        <function>inserttable()</function> method allows to quickly
        insert large blocks of data in a table: it inserts the whole
        values list into the given table. The list is a list of
        tuples/lists that define the values for each inserted row. The
        rows values may contain string, integer, long or double (real)
        values.  <emphasis>Be very careful:</emphasis> this method
        does not type-check the fields according to the table
        definition; it just look whether or not it knows how to handle
        such types.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-PUTLINE">
    <refmeta>
      <refentrytitle>putline</refentrytitle>
      <refmiscinfo>PYGRESQL - Putline</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>putline</refname>
      <refpurpose>write a line to the server socket [DA]</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
putline(<parameter>line</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-PUTLINE-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>line</parameter>
            </term>
            <listitem>
              <para>Line to be written (string).</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PUTLINE-2">
        <title>Return Type</title>
          <para>
            none
          </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PUTLINE-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad argument type or too many (any) arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid connection.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PUTLINE-1">
      <title>Description</title>
      <para>
        <function>putline()</function> method allows to directly write a string to the server socket.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-GETLINE">
    <refmeta>
      <refentrytitle>getline</refentrytitle>
      <refmiscinfo>PYGRESQL - Getline</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>getline</refname>
      <refpurpose>get a line from server socket [DA]</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
getline()
</synopsis>

      <refsect2 id="R2-PYGRESQL-GETLINE-1">
        <title>Parameters</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-GETLINE-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              string
            </term>
            <listitem>
              <para>
                The line read.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-GETLINE-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad argument type or too many (any) arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid connection.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-GETLINE-1">
      <title>Description</title>
      <para>
        <function>getline()</function> method allows to directly read a string from the server socket.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-ENDCOPY">
    <refmeta>
      <refentrytitle>endcopy</refentrytitle>
      <refmiscinfo>PYGRESQL - Endcopy</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>endcopy</refname>
      <refpurpose>synchronize client and server [DA]</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
endcopy()
</synopsis>

      <refsect2 id="R2-PYGRESQL-ENDCOPY-1">
        <title>Parameters</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-ENDCOPY-2">
        <title>Return Type</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-ENDCOPY-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad argument type or too many (any) arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid connection.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-ENDCOPY-1">
      <title>Description</title>
      <para>
        The use of direct access methods may desynchronize client and server. This
        method ensure that client and server will be synchronized.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-LOCREATE">
    <refmeta>
      <refentrytitle>locreate</refentrytitle>
      <refmiscinfo>PYGRESQL - Locreate</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>locreate</refname>
      <refpurpose>create a large object in the database [LO]</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
locreate(<parameter>mode</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-LOCREATE-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>mode</parameter>
            </term>
            <listitem>
              <para>Large object create mode.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-LOCREATE-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>pglarge</>
            </term>
            <listitem>
              <para>
                Object handling the <productname>PostgreSQL</productname> large object.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-LOCREATE-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad argument type or too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid connection, or creation error.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-LOCREATE-1">
      <title>Description</title>
      <para>
        <function>locreate()</function> method creates a large object in the database.
        The mode can be defined by OR-ing the constants defined in the pg module
        (<literal>INV_READ</literal> and <literal>INV_WRITE</literal>).
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-GETLO">
    <refmeta>
      <refentrytitle>getlo</refentrytitle>
      <refmiscinfo>PYGRESQL - Getlo</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>getlo</refname>
      <refpurpose>build a large object from given OID [LO]</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
getlo(<parameter>oid</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-GETLO-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>oid</parameter>
            </term>
            <listitem>
              <para>OID of the existing large object (integer).</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-GETLO-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>pglarge</>
            </term>
            <listitem>
              <para>
                Object handling the <productname>PostgreSQL</productname> large object.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-GETLO-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad argument type or too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid connection.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-GETLO-1">
      <title>Description</title>
      <para>
        <function>getlo()</function> method allows to reuse a formerly
        created large object through the <classname>pglarge</classname> interface, providing
        the user has its OID.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-LOIMPORT">
    <refmeta>
      <refentrytitle>loimport</refentrytitle>
      <refmiscinfo>PYGRESQL - Loimport</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>loimport</refname>
      <refpurpose>import a file to a <productname>PostgreSQL</productname> large object [LO]</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
loimport(<parameter>filename</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-LOIMPORT-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>filename</parameter>
            </term>
            <listitem>
              <para>The name of the file to be imported (string).</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-LOIMPORT-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>pglarge</>
            </term>
            <listitem>
              <para>
                Object handling the <productname>PostgreSQL</productname> large object.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-LOIMPORT-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad argument type or too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid connection, or error during file import.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-LOIMPORT-1">
      <title>Description</title>
      <para>
        <function>loimport()</function> method allows to create large objects
        in a very simple way. You just give the name of a file containing the
        data to be use.
      </para>
    </refsect1>

    </refentry>

 </sect1>


 <sect1 id="pygresql-pg-DB">
  <title>Database Wrapper Class: <classname>DB</classname></title>

  <para>
   The <literal>pg</literal> module contains a class called
   <classname>DB</classname> wrapping a <classname>pgobject</classname>.
   This <classname>pgobject</classname> can be addressed as a
   <classname>DB</classname> class member named <varname>db</varname>
   to get access to the read-only attributes of the corresponding connection
   (e.g. <varname>db.error</varname>).  All <classname>pgobject</classname>
   methods (e.g. <function>query()</function>) are directly included as members
   in the class <classname>DB</classname> also.  A number of additional
   higher level <classname>DB</classname> class methods are described below.
   The preferred way to use this module is as follows  (see description of the
   initialization method below):

<programlisting>
import pg

db = pg.DB(...)

for r in db.query(
    "SELECT foo,bar
       FROM foo_bar_table
      WHERE foo !~ bar"
    ).dictresult():

    print '%(foo)s %(bar)s' % r
</programlisting>

   The following describes the methods and variables of this class.
  </para>

  <para>
   The <classname>DB</classname> class is initialized with the same
   arguments as the <function>pg.connect</function> method.  It also
   initializes a few internal variables.  The statement <literal>db =
   DB()</literal> will open the local database with the name of the
   user just like <function>pg.connect()</function> does.
  </para>

    <refentry id="PYGRESQL-DB-PKEY">
      <refmeta>
        <refentrytitle>pkey</refentrytitle>
        <refmiscinfo>PYGRESQL - Pkey</refmiscinfo>
      </refmeta>
      <refnamediv>
        <refname>pkey</refname>
        <refpurpose>return the primary key of a table</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
<synopsis>
pkey(<parameter>table</parameter>)
</synopsis>

        <refsect2 id="R2-PYGRESQL-DB-PKEY-1">
          <title>Parameters</title>
          <variablelist>
            <varlistentry>
              <term>
                <parameter>table</parameter>
              </term>
              <listitem>
                <para>
                  name of table.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2 id="R2-PYGRESQL-DB-PKEY-2">
          <title>Return Type</title>
          <variablelist>
            <varlistentry>
              <term>
                string
              </term>
              <listitem>
                <para>
                  Name of field which is the primary key of the table.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

      </refsynopsisdiv>

      <refsect1 id="R1-PYGRESQL-DB-PKEY-1">
        <title>Description</title>
        <para>
          <function>pkey()</function> method returns the primary key
          of a table.  Note that this raises an exception if the table
          does not have a primary key.
        </para>
      </refsect1>

    </refentry>

    <!-- ********************************************************** -->

    <refentry id="PYGRESQL-DB-GET-DATABASES">
      <refmeta>
        <refentrytitle>get_databases</refentrytitle>
        <refmiscinfo>PYGRESQL - Get_databases</refmiscinfo>
      </refmeta>
      <refnamediv>
        <refname>get_databases</refname>
        <refpurpose>get list of databases in the system</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
<synopsis>
get_databases()
</synopsis>

        <refsect2 id="R2-PYGRESQL-DB-GET-DATABASES-1">
          <title>Parameters</title>
          <para>
            none
          </para>
        </refsect2>

        <refsect2 id="R2-PYGRESQL-DB-GET-DATABASES-2">
          <title>Return Type</title>
          <variablelist>
            <varlistentry>
              <term>
                list
              </term>
              <listitem>
                <para>
                  List of databases in the system.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

      </refsynopsisdiv>

      <refsect1 id="R1-PYGRESQL-DB-GET-DATABASES-1">
        <title>Description</title>
        <para>
          Although you can do this with a simple select,
          it is added here for convenience
        </para>
      </refsect1>

    </refentry>

    <!-- ********************************************************** -->

    <refentry id="PYGRESQL-DB-GET-TABLES">
      <refmeta>
        <refentrytitle>get_tables</refentrytitle>
        <refmiscinfo>PYGRESQL - get_tables</refmiscinfo>
      </refmeta>
      <refnamediv>
        <refname>get_tables</refname>
        <refpurpose>get list of tables in connected database</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
<synopsis>
get_tables()
</synopsis>

        <refsect2 id="R2-PYGRESQL-DB-GET-TABLES-1">
          <title>Parameters</title>
          <para>
            none
          </para>
        </refsect2>

        <refsect2 id="R2-PYGRESQL-DB-GET-TABLES-2">
          <title>Return Type</title>
          <variablelist>
            <varlistentry>
              <term>
                list
              </term>
              <listitem>
                <para>
                  List of tables in connected database.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

      </refsynopsisdiv>

      <refsect1 id="R1-PYGRESQL-DB-GET-TABLES-1">
        <title>Description</title>
        <para>
          Although you can do this with a simple select,
          it is added here for convenience
        </para>
      </refsect1>

    </refentry>

    <!-- ********************************************************** -->

    <refentry id="PYGRESQL-DB-GET-ATTNAMES">
      <refmeta>
        <refentrytitle>get_attnames</refentrytitle>
        <refmiscinfo>PYGRESQL - Get_Attnames</refmiscinfo>
      </refmeta>
      <refnamediv>
        <refname>get_attnames</refname>
        <refpurpose>return the attribute names of a table</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
<synopsis>
get_attnames(<parameter>table</parameter>)
</synopsis>

        <refsect2 id="R2-PYGRESQL-DB-GET-ATTNAMES-1">
          <title>Parameters</title>
          <variablelist>
            <varlistentry>
              <term>
                <parameter>table</parameter>
              </term>
              <listitem>
                <para>
                  name of table.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2 id="R2-PYGRESQL-DB-GET-ATTNAMES-2">
          <title>Return Type</title>
          <variablelist>
            <varlistentry>
              <term>
                dictionary
              </term>
              <listitem>
                <para>
		 The dictionary's keys are
		 the attribute names, the values are the type names of
		 the attributes.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

      </refsynopsisdiv>

      <refsect1 id="R1-PYGRESQL-DB-GET-ATTNAMES-1">
        <title>Description</title>
        <para>
          Given the name of a table, digs out the set of attribute names
	  and types.
        </para>
      </refsect1>

    </refentry>

    <!-- ********************************************************** -->

    <refentry id="PYGRESQL-DB-GET">
      <refmeta>
        <refentrytitle>get</refentrytitle>
        <refmiscinfo>PYGRESQL - Get</refmiscinfo>
      </refmeta>
      <refnamediv>
        <refname>get</refname>
        <refpurpose>get a tuple from a database table</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
<synopsis>
get(<parameter>table</parameter>, <parameter>arg</parameter>, <optional><parameter>keyname</parameter></optional>)
</synopsis>

        <refsect2 id="R2-PYGRESQL-DB-GET-1">
          <title>Parameters</title>
          <variablelist>
            <varlistentry>
              <term>
                <parameter>table</parameter>
              </term>
              <listitem>
                <para>
                  Name of table.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <parameter>arg</parameter>
              </term>
              <listitem>
                <para>
                  Either a dictionary or the value to be looked up.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional><parameter>keyname</parameter></optional>
              </term>
              <listitem>
                <para>
                  Name of field to use as key (optional).
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2 id="R2-PYGRESQL-DB-GET-2">
          <title>Return Type</title>
          <variablelist>
            <varlistentry>
              <term>
                dictionary
              </term>
              <listitem>
                <para>
                  A dictionary mapping attribute names to row values.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

      </refsynopsisdiv>

      <refsect1 id="R1-PYGRESQL-DB-GET-1">
        <title>Description</title>
        <para>
          This method is the basic mechanism to get a single row.  It assumes
          that the key specifies a unique row.  If <parameter>keyname</> is not specified
          then the primary key for the table is used.  If <parameter>arg</> is a dictionary
          then the value for the key is taken from it and it is modified to
          include the new values, replacing existing values where necessary.
          The OID is also put into the dictionary but in order to allow the
          caller to work with multiple tables, the attribute name is munged
          to make it unique.  It consists of the string <literal>oid_</literal> followed by
          the name of the table.
        </para>
      </refsect1>

    </refentry>

    <!-- ********************************************************** -->

    <refentry id="PYGRESQL-DB-INSERT">
      <refmeta>
        <refentrytitle>insert</refentrytitle>
        <refmiscinfo>PYGRESQL - Insert</refmiscinfo>
      </refmeta>
      <refnamediv>
        <refname>insert</refname>
        <refpurpose>insert a tuple into a database table</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
<synopsis>
insert(<parameter>table</parameter>, <parameter>a</parameter>)
</synopsis>

        <refsect2 id="R2-PYGRESQL-DB-INSERT-1">
          <title>Parameters</title>
          <variablelist>
            <varlistentry>
              <term>
                <parameter>table</parameter>
              </term>
              <listitem>
                <para>
                  Name of table.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <parameter>a</parameter>
              </term>
              <listitem>
                <para>
                  A dictionary of values.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2 id="R2-PYGRESQL-DB-INSERT-2">
          <title>Return Type</title>
          <variablelist>
            <varlistentry>
              <term>
                integer
              </term>
              <listitem>
                <para>
                  The OID of the newly inserted row.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

      </refsynopsisdiv>

      <refsect1 id="R1-PYGRESQL-DB-INSERT-1">
        <title>Description</title>
        <para>
          This method inserts values into the table specified filling in the
          values from the dictionary.  It then reloads the dictionary with the
          values from the database.  This causes the dictionary to be updated
          with values that are modified by rules, triggers, etc.
        </para>

        <para>
         Due to the way that this function works you will find inserts
         taking longer and longer as your table gets bigger.  To
         overcome this problem simply add an index onto the OID of any
         table that you think may get large over time.
        </para>
      </refsect1>

    </refentry>

    <!-- ********************************************************** -->

    <refentry id="PYGRESQL-DB-UPDATE">
      <refmeta>
        <refentrytitle>update</refentrytitle>
        <refmiscinfo>PYGRESQL - Update</refmiscinfo>
      </refmeta>
      <refnamediv>
        <refname>update</refname>
        <refpurpose>update a database table</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
<synopsis>
update(<parameter>table</parameter>, <parameter>a</parameter>)
</synopsis>

        <refsect2 id="R2-PYGRESQL-DB-UPDATE-1">
          <title>Parameters</title>
          <variablelist>
            <varlistentry>
              <term>
                <parameter>table</parameter>
              </term>
              <listitem>
                <para>
                  Name of table.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <parameter>a</parameter>
              </term>
              <listitem>
                <para>
                  A dictionary of values.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2 id="R2-PYGRESQL-DB-UPDATE-2">
          <title>Return Type</title>
          <variablelist>
            <varlistentry>
              <term>
                integer
              </term>
              <listitem>
                <para>
                  The OID of the newly updated row.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

      </refsynopsisdiv>

      <refsect1 id="R1-PYGRESQL-DB-UPDATE-1">
        <title>Description</title>
        <para>
          Similar to insert but updates an existing row.  The update is based
          on the OID value as munged by get.  The array returned is the
          one sent modified to reflect any changes caused by the update due
          to triggers, rules, defaults, etc.
        </para>
      </refsect1>

    </refentry>

    <!-- ********************************************************** -->

    <refentry id="PYGRESQL-DB-CLEAR">
      <refmeta>
        <refentrytitle>clear</refentrytitle>
        <refmiscinfo>PYGRESQL - Clear</refmiscinfo>
      </refmeta>
      <refnamediv>
        <refname>clear</refname>
        <refpurpose>clear a database table</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
<synopsis>
clear(<parameter>table</parameter>, <optional><parameter>a</parameter></optional>)
</synopsis>

        <refsect2 id="R2-PYGRESQL-DB-CLEAR-1">
          <title>Parameters</title>
          <variablelist>
            <varlistentry>
              <term>
                <parameter>table</parameter>
              </term>
              <listitem>
                <para>
                  Name of table.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional><parameter>a</parameter></optional>
              </term>
              <listitem>
                <para>
                  A dictionary of values.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2 id="R2-PYGRESQL-DB-CLEAR-2">
          <title>Return Type</title>
          <variablelist>
            <varlistentry>
              <term>
                dictionary
              </term>
              <listitem>
                <para>
                  A dictionary with an empty row.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

      </refsynopsisdiv>

      <refsect1 id="R1-PYGRESQL-DB-CLEAR-1">
        <title>Description</title>
        <para>
          This method clears all the attributes to values determined by the types.
          Numeric types are set to 0, dates are set to <literal>'today'</literal> and everything
          else is set to the empty string.  If the array argument is present,
          it is used as the array and any entries matching attribute names
          are cleared with everything else left unchanged.
        </para>
      </refsect1>

    </refentry>

    <!-- ********************************************************** -->

    <refentry id="PYGRESQL-DB-DELETE">
      <refmeta>
        <refentrytitle>delete</refentrytitle>
        <refmiscinfo>PYGRESQL - Delete</refmiscinfo>
      </refmeta>
      <refnamediv>
        <refname>delete</refname>
        <refpurpose>delete a row from a table</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
<synopsis>
delete(<parameter>table</parameter>, <optional><parameter>a</parameter></optional>)
</synopsis>

        <refsect2 id="R2-PYGRESQL-DB-DELETE-1">
          <title>Parameters</title>
          <variablelist>
            <varlistentry>
              <term>
                <parameter>table</parameter>
              </term>
              <listitem>
                <para>
                  Name of table.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional><parameter>a</parameter></optional>
              </term>
              <listitem>
                <para>
                  A dictionary of values.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2 id="R2-PYGRESQL-DB-DELETE-2">
          <title>Return Type</title>
          <para>
            none
          </para>
        </refsect2>

      </refsynopsisdiv>

      <refsect1 id="R1-PYGRESQL-DB-DELETE-1">
        <title>Description</title>
        <para>
          This method deletes the row from a table.  It deletes based on the OID
          as munged as described above.
        </para>
      </refsect1>

    </refentry>

    <!-- ********************************************************** -->

  </sect1>

  <!-- ********************************************************** -->
  <!-- ********************************************************** -->

  <sect1 id="pygresql-pg-pgqueryobject">
    <title>Query Result Object: <classname>pgqueryobject</classname></title>

    <!-- ********************************************************** -->

    <refentry id="PYGRESQL-PGQUERYOBJECT-GETRESULT">
      <refmeta>
        <refentrytitle>getresult</refentrytitle>
        <refmiscinfo>PYGRESQL - Getresult</refmiscinfo>
      </refmeta>
      <refnamediv>
        <refname>getresult</refname>
        <refpurpose>get the values returned by the query</refpurpose>
      </refnamediv>
      
      <refsynopsisdiv>
<synopsis>
getresult()
</synopsis>
        
        <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-GETRESULT-1">
          <title>Parameters</title>
          <para>
            none
          </para>
        </refsect2>

        <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-GETRESULT-2">
          <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              list
            </term>
            <listitem>
              <para>
                List of tuples.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-GETRESULT-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>SyntaxError</classname>
            </term>
            <listitem>
              <para>
                Too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid previous result.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-GETRESULT-1">
      <title>Description</title>
      <para>
        <function>getresult()</function> method returns the list of the values returned by the query.
        More information about this result may be accessed using <function>listfields</function>,
        <function>fieldname</function> and <function>fieldnum</function> methods.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-PGQUERYOBJECT-DICTRESULT">
    <refmeta>
      <refentrytitle>dictresult</refentrytitle>
      <refmiscinfo>PYGRESQL - Dictresult</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>dictresult</refname>
      <refpurpose>get the values returned by the query as a list of dictionaries</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
dictresult()
</synopsis>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-DICTRESULT-1">
        <title>Parameters</title>
          <para>
            none
          </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-DICTRESULT-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              list
            </term>
            <listitem>
              <para>
                List of dictionaries.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-DICTRESULT-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>SyntaxError</classname>
            </term>
            <listitem>
              <para>
                Too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid previous result.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-DICTRESULT-1">
      <title>Description</title>
      <para>
        <function>dictresult()</function> method returns the list of the values returned by the query
        with each tuple returned as a dictionary with the field names
        used as the dictionary index.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-PGQUERYOBJECT-LISTFIELDS">
    <refmeta>
      <refentrytitle>listfields</refentrytitle>
      <refmiscinfo>PYGRESQL - Listfields</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>listfields</refname>
      <refpurpose>list the fields names of the query result</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
listfields()
</synopsis>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-1">
        <title>Parameters</title>
          <para>
            none
          </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              list
            </term>
            <listitem>
              <para>
                field names
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>SyntaxError</classname>
            </term>
            <listitem>
              <para>
                Too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid query result, or invalid connection.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-1">
      <title>Description</title>
      <para>
        <function>listfields()</function> method returns the list of field names defined for the
        query result. The fields are in the same order as the result values.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-PGQUERYOBJECT-FIELDNAME">
    <refmeta>
      <refentrytitle>fieldname</refentrytitle>
      <refmiscinfo>PYGRESQL - Fieldname</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>fieldname</refname>
      <refpurpose>get field name by number</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
fieldname(<parameter>i</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>i</parameter>
            </term>
            <listitem>
              <para>
                field number (integer).
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              string
            </term>
            <listitem>
              <para>
                field name.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad parameter type, or too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>ValueError</classname>
            </term>
            <listitem>
              <para>
                Invalid field number.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid query result, or invalid connection.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-FIELDNAME-1">
      <title>Description</title>
      <para>
        <function>fieldname()</function> method allows to find a field name from its rank number. It can be 
        useful for displaying a result. The fields are in the same order than the
        result values.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-PGQUERYOBJECT-FIELDNUM">
    <refmeta>
      <refentrytitle>fieldnum</refentrytitle>
      <refmiscinfo>PYGRESQL - Fieldnum</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>fieldnum</refname>
      <refpurpose>get field number by name</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
fieldnum(<parameter>name</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>name</parameter>
            </term>
            <listitem>
              <para>
                field name (string).
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              integer
            </term>
            <listitem>
              <para>
                field number (integer).
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad parameter type, or too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>ValueError</classname>
            </term>
            <listitem>
              <para>
                Unknown field name.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid query result, or invalid connection.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-FIELDNUM-1">
      <title>Description</title>
      <para>
        <function>fieldnum()</function> method returns a field number from its name.
        It can be used to build a function that converts result list strings to their correct
        type, using a hardcoded table definition.  The number returned is the
        field rank in the result values list.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-PGQUERYOBJECT-NTUPLES">
    <refmeta>
      <refentrytitle>ntuples</refentrytitle>
      <refmiscinfo>PYGRESQL - Ntuples</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>ntuples</refname>
      <refpurpose>return the number of tuples in query object</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
ntuples()
</synopsis>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-NTUPLES-1">
        <title>Parameters</title>
          <para>
            none
          </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-NTUPLES-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              integer
            </term>
            <listitem>
              <para>
                The number of tuples in query object.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-NTUPLES-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>SyntaxError</classname>
            </term>
            <listitem>
              <para>
                Too many arguments.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-NTUPLES-1">
      <title>Description</title>
      <para>
        <function>ntuples()</function> method returns the number of tuples found in a query.
      </para>
    </refsect1>

  </refentry>

 </sect1>


 <sect1 id="pygresql-pg-pglarge">
  <title>Large Object: <classname>pglarge</classname></title>

  <para>
   This object handles all the request concerning a
   <productname>PostgreSQL</productname> large object. It embeds and
   hides all the <quote>recurrent</quote> variables (object OID and
   connection), exactly in the same way
   <classname>pgobject</classname>s do, thus only keeping significant
   parameters in function calls. It keeps a reference to the <classname>pgobject</classname>
   used for its creation, sending requests though with its
   parameters. Any modification but dereferencing the
   <classname>pgobject</classname> will thus affect the
   <classname>pglarge</classname> object.  Dereferencing the initial
   <classname>pgobject</classname> is not a problem since
   <application>Python</application> will not deallocate it before the
   large object dereference it.  All functions return a generic error
   message on call error, whatever the exact error was. The
   <structfield>error</structfield> attribute of the object allows to
   get the exact error message.
  </para>

  <para>
   <classname>pglarge</classname> objects define a read-only set of
   attributes that allow to get some information about it. These
   attributes are:

   <variablelist>
    <varlistentry>
     <term><structfield>oid</></term>
     <listitem>
      <para>
       the OID associated with the object
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><structfield>pgcnx</></term>
     <listitem>
      <para>
       the <classname>pgobject</classname> associated with the object
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><structfield>error</></term>
     <listitem>
      <para>
       the last warning/error message of the connection
      </para>
     </listitem>
    </varlistentry>
   </variablelist>

   <important>
    <para>
     In multithreaded environments, <structfield>error</structfield>
     may be modified by another thread using the same
     <classname>pgobject</classname>. Remember that these object are
     shared, not duplicated; you should provide some locking if you
     want to check for the error message in this situation.  The OID
     attribute is very interesting because it allow you to reuse the
     OID later, creating the <classname>pglarge</classname> object
     with a <classname>pgobject</classname>
     <function>getlo()</function> method call.
    </para>
   </important>
  </para>

  <para>
   See also <xref linkend="largeobjects"> for more information about the
   <productname>PostgreSQL</productname> large object interface.
  </para>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-PGLARGEOBJECT-OPEN">
    <refmeta>
      <refentrytitle>open</refentrytitle>
      <refmiscinfo>PYGRESQL - Open</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>open</refname>
      <refpurpose>open a large object</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
open(<parameter>mode</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>mode</parameter>
            </term>
            <listitem>
              <para>
                open mode definition (integer).
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-2">
        <title>Return Type</title>
          <para>
            none
          </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad parameter type, or too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>IOError</classname>
            </term>
            <listitem>
              <para>
                Already opened object, or open error.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid  connection.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-OPEN-1">
      <title>Description</title>
      <para>
        <function>open()</function> method opens a large object for reading/writing,
        in the same way than the Unix <function>open()</function>
        function. The mode value can be obtained by OR-ing the constants defined in
        the pg module (<literal>INV_READ</literal>, <literal>INV_WRITE</literal>).
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-PGLARGEOBJECT-CLOSE">
    <refmeta>
      <refentrytitle>close</refentrytitle>
      <refmiscinfo>PYGRESQL - Close</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>close</refname>
      <refpurpose>close the large object</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
close()
</synopsis>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-CLOSE-1">
        <title>Parameters</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-CLOSE-2">
        <title>Return Type</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-CLOSE-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>SyntaxError</classname>
            </term>
            <listitem>
              <para>
                Too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>IOError</classname>
            </term>
            <listitem>
              <para>
                Object is not opened, or close error.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid  connection.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-CLOSE-1">
      <title>Description</title>
      <para>
        <function>close()</function> method closes previously opened large object,
        in the same way than the Unix <function>close()</function> function.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-PGLARGEOBJECT-READ">
    <refmeta>
      <refentrytitle>read</refentrytitle>
      <refmiscinfo>PYGRESQL - Read</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>read</refname>
      <refpurpose>read from the large object</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
read(<parameter>size</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>size</parameter>
            </term>
            <listitem>
              <para>
                Maximal size of the buffer to be read (integer).
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              string
            </term>
            <listitem>
              <para>
                The read buffer.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad parameter type, or too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>IOError</classname>
            </term>
            <listitem>
              <para>
                Object is not opened, or read error.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid  connection or invalid object.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-READ-1">
      <title>Description</title>
      <para>
        <function>read()</function> method allows to read data from the large object,
        starting at current position.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-PGLARGEOBJECT-WRITE">
    <refmeta>
      <refentrytitle>write</refentrytitle>
      <refmiscinfo>PYGRESQL - Write</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>write</refname>
      <refpurpose>write to the large object</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
write(<parameter>string</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>string</parameter>
            </term>
            <listitem>
              <para>
                Buffer to be written (string).
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-2">
        <title>Return Type</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad parameter type, or too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>IOError</classname>
            </term>
            <listitem>
              <para>
                Object is not opened, or write error.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid  connection or invalid object.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-WRITE-1">
      <title>Description</title>
      <para>
        <function>write()</function> method allows to write data to the large object,
        starting at current position.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-PGLARGEOBJECT-SEEK">
    <refmeta>
      <refentrytitle>seek</refentrytitle>
      <refmiscinfo>PYGRESQL - Seek</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>seek</refname>
      <refpurpose>change current position in the large object</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
seek(<parameter>offset</parameter>, <parameter>whence</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>offset</parameter>
            </term>
            <listitem>
              <para>
                Position offset (integer).
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <parameter>whence</parameter>
            </term>
            <listitem>
              <para>
                Positional parameter (integer).
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              integer
            </term>
            <listitem>
              <para>
                New current position in the object.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad parameter type, or too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>IOError</classname>
            </term>
            <listitem>
              <para>
                Object is not opened, or seek error.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid  connection or invalid object.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-SEEK-1">
      <title>Description</title>
      <para>
        <function>seek()</function> method allows to move the cursor position
        in the large object. The whence parameter can be obtained by OR-ing the constants defined in the 
        <literal>pg</literal> module (<literal>SEEK_SET</>, <literal>SEEK_CUR</>, <literal>SEEK_END</literal>).
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-PGLARGEOBJECT-TELL">
    <refmeta>
      <refentrytitle>tell</refentrytitle>
      <refmiscinfo>PYGRESQL - Tell</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>tell</refname>
      <refpurpose>return current position in the large object</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
tell()
</synopsis>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-TELL-1">
        <title>Parameters</title>
          <para>
            none
          </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-TELL-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              integer
            </term>
            <listitem>
              <para>
                Current position in the object.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-TELL-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>SyntaxError</classname>
            </term>
            <listitem>
              <para>
                Too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>IOError</classname>
            </term>
            <listitem>
              <para>
                Object is not opened, or seek error.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid  connection or invalid object.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-TELL-1">
      <title>Description</title>
      <para>
        <function>tell()</function> method allows to get the current position in the large object.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-PGLARGEOBJECT-UNLINK">
    <refmeta>
      <refentrytitle>unlink</refentrytitle>
      <refmiscinfo>PYGRESQL - Unlink</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>unlink</refname>
      <refpurpose>delete the large object</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
unlink()
</synopsis>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-UNLINK-1">
        <title>Parameters</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-UNLINK-2">
        <title>Return Type</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-UNLINK-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>SyntaxError</classname>
            </term>
            <listitem>
              <para>
                Too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>IOError</classname>
            </term>
            <listitem>
              <para>
                Object is not closed, or unlink error.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid  connection or invalid object.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-UNLINK-1">
      <title>Description</title>
      <para>
        <function>unlink()</function> method unlinks (deletes) the large object.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-PGLARGEOBJECT-SIZE">
    <refmeta>
      <refentrytitle>size</refentrytitle>
      <refmiscinfo>PYGRESQL - Size</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>size</refname>
      <refpurpose>return the large object size</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
size()
</synopsis>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SIZE-1">
        <title>Parameters</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SIZE-2">
        <title>Return Type</title>
        <variablelist>
          <varlistentry>
            <term>
              integer
            </term>
            <listitem>
              <para>
                The large object size.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SIZE-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>SyntaxError</classname>
            </term>
            <listitem>
              <para>
                Too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>IOError</classname>
            </term>
            <listitem>
              <para>
                Object is not opened, or seek/tell error.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid  connection or invalid object.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-SIZE-1">
      <title>Description</title>
      <para>
        <function>size()</function> method allows to get the size of
        the large object. It was implemented because this function 
        is very useful for a WWW-interfaced database.
        Currently, the large object needs to be opened first.
      </para>
    </refsect1>

  </refentry>

<!-- ********************************************************** -->

  <refentry id="PYGRESQL-PGLARGEOBJECT-EXPORT">
    <refmeta>
      <refentrytitle>export</refentrytitle>
      <refmiscinfo>PYGRESQL - Export</refmiscinfo>
    </refmeta>
    <refnamediv>
      <refname>export</refname>
      <refpurpose>save the large object to file</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<synopsis>
export(<parameter>filename</parameter>)
</synopsis>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-1">
        <title>Parameters</title>
        <variablelist>
          <varlistentry>
            <term>
              <parameter>filename</parameter>
            </term>
            <listitem>
              <para>
                The file to be created.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-2">
        <title>Return Type</title>
        <para>
          none
        </para>
      </refsect2>

      <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-3">
        <title>Exceptions</title>
        <variablelist>
          <varlistentry>
            <term>
              <classname>TypeError</classname>
            </term>
            <listitem>
              <para>
                Bad argument type, or too many arguments.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>IOError</classname>
            </term>
            <listitem>
              <para>
                Object is not closed, or export error.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <classname>pg.error</classname>
            </term>
            <listitem>
              <para>
                Invalid  connection or invalid object.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect2>

    </refsynopsisdiv>

    <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-EXPORT-1">
      <title>Description</title>
      <para>
        <function>export()</function> method allows to dump the
        content of a large object in a very simple way.
        The exported file is created on the host of the program,
        not the server host.
      </para>
    </refsect1>

  </refentry>

 </sect1>

</chapter>