Skip to content

P
Postgres FD Implementation
Commit 0d3be98a authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

Move PyGreSQL usage documentation from README into DocBook. Some other 

editing.
parent 5fa34183
Show whitespace changes
Inline Side-by-side
Showing with 394 additions and 1310 deletions
doc/src/sgml/pygresql.sgml
View file @ 0d3be98a
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/pygresql.sgml,v 1.6 2002/03/27 19:19:22 petere Exp $ --> <!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/pygresql.sgml,v 1.7 2002/09/23 21:10:12 petere Exp $ -->
<chapter id="pygresql"> <chapter id="pygresql">
<title><application>PyGreSQL</application> - <application>Python</application> Interface</title> <title><application>PyGreSQL</application> - <application>Python</application> Interface</title>
...@@ -20,34 +20,10 @@ ...@@ -20,34 +20,10 @@
<title>Installation</title> <title>Installation</title>
<itemizedlist> <itemizedlist>
<listitem>
<para>
If you are on <acronym>NetBSD</acronym>, look in the packages
directory under databases. If it isn't there yet, it should be
there shortly. You can also pick up the package files from
<ulink url="ftp://ftp.druid.net/pub/distrib/pygresql.pkg.tgz"
>ftp://ftp.druid.net/pub/distrib/pygresql.pkg.tgz</ulink>. There
is also a package in the <acronym>FreeBSD</acronym> ports
collection but as I write this it is at version 2.1. I will try
to get that updated as well.
</para>
</listitem>
<listitem>
<para>
For Linux installation look at <filename>README.linux</filename>.
If you're on an <acronym>x86</acronym> system that uses
<acronym>RPMs</acronym>, then you can pick up an
<acronym>RPM</acronym> at <ulink
url="ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm"
>ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm</ulink>.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
Note that if you are using the <acronym>DB-API</acronym> module Note that if you are using the <acronym>DB-API</acronym> module
you must also install <acronym>mxDateTime</acronym> from <ulink you must also install <literal>mxDateTime</literal> from <ulink
url="http://starship.python.net/~lemburg/mxDateTime.html" url="http://starship.python.net/~lemburg/mxDateTime.html"
>http://starship.python.net/~lemburg/mxDateTime.html</ulink>. >http://starship.python.net/~lemburg/mxDateTime.html</ulink>.
</para> </para>
...@@ -56,16 +32,15 @@ ...@@ -56,16 +32,15 @@
<listitem> <listitem>
<para> <para>
Also, check out <filename>setup.py</filename> for an alternate Also, check out <filename>setup.py</filename> for an alternate
method of installing the package using Python's Distutils. method of installing the package using <application>Python</application>'s Distutils.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para> <para>
You have two options. You can compile You have two options. You can compile
<productname>PyGreSQL</productname> as a stand-alone module or you <application>PyGreSQL</application> as a stand-alone module or you
can build it into the <productname>Python</productname> can build it into the <application>Python</application>
interpreter. interpreter.
</para> </para>
...@@ -75,27 +50,27 @@ ...@@ -75,27 +50,27 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
You must first have installed <productname>Python</productname> You must first have installed <application>Python</application>
and <productname>PostgreSQL</productname> on your system. The and <productname>PostgreSQL</productname> on your system. The
header files and developer's libraries for both header files and developer's libraries for both
<productname>Python</productname> and <application>Python</application> and
<productname>PostgreSQL</productname> must be installed on your <productname>PostgreSQL</productname> must be installed on your
system before you can build <productname>PyGreSQL</productname>. system before you can build <application>PyGreSQL</application>.
If you built both <productname>Python</productname> and If you built both <application>Python</application> and
<productname>PostgreSQL</productname> from source, you should be <productname>PostgreSQL</productname> from source, you should be
fine. If your system uses some package mechanism (such as fine. If your system uses some package mechanism (such as
<acronym>RPM</acronym> or <acronym>NetBSD</acronym> packages), <acronym>RPM</acronym> or <systemitem class="osname">NetBSD</systemitem> packages),
then you probably need to install packages such as then you probably need to install packages such as
<acronym>Python-devel</acronym> in addition to the <application>Python-devel</application> in addition to the
<productname>Python</productname> package. <application>Python</application> package.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<productname>PyGreSQL</productname> is implemented as three <application>PyGreSQL</application> is implemented as three
parts, a C module labeled <acronym>_pg</acronym> and two parts, a C module labeled <literal>_pg</literal> and two
<productname>Python</productname> wrappers called <application>Python</application> wrappers called
<filename>pg.py</filename> and <filename>pgdb.py</filename>. <filename>pg.py</filename> and <filename>pgdb.py</filename>.
This changed between 2.1 and 2.2 and again in 3.0. These This changed between 2.1 and 2.2 and again in 3.0. These
changes should not affect any existing programs but the changes should not affect any existing programs but the
...@@ -105,7 +80,7 @@ ...@@ -105,7 +80,7 @@
<listitem> <listitem>
<para> <para>
Download and unpack the <productname>PyGreSQL</productname> Download and unpack the <application>PyGreSQL</application>
tarball if you haven't already done so. tarball if you haven't already done so.
</para> </para>
</listitem> </listitem>
...@@ -129,7 +104,7 @@ cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c ...@@ -129,7 +104,7 @@ cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
[pyInc] = path of the <productname>Python</productname> [pyInc] = path of the <application>Python</application>
include (usually <filename>Python.h</filename>) include (usually <filename>Python.h</filename>)
</para> </para>
</listitem> </listitem>
...@@ -154,43 +129,43 @@ cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c ...@@ -154,43 +129,43 @@ cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
<literal>-DNO_DEF_VAR</literal> - no default variables <option>-DNO_DEF_VAR</option> - no default variables
support support
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<literal>-DNO_DIRECT</literal> - no direct access methods <option>-DNO_DIRECT</option> - no direct access methods
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<literal>-DNO_LARGE</literal> - no large object support <option>-DNO_LARGE</option> - no large object support
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<literal>-DNO_SNPRINTF</literal> - if running a system with <option>-DNO_SNPRINTF</option> - if running a system with
no snprintf call no snprintf call
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<literal>-DNO_PQSOCKET</literal> - if running an older <option>-DNO_PQSOCKET</option> - if running an older
<productname>PostgreSQL</productname> <productname>PostgreSQL</productname>
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
On some systems you may need to include On some systems you may need to include
<literal>-lcrypt</literal> in the list of libraries to make it <option>-lcrypt</option> in the list of libraries to make it
compile. compile.
Define <literal>DNO_PQSOCKET</literal> if you are using a Define <option>DNO_PQSOCKET</option> if you are using a
version of <productname>PostgreSQL</productname> before 6.4 that version of <productname>PostgreSQL</productname> before 6.4 that
does not have the <function>PQsocket</function> function. The does not have the <function>PQsocket</function> function. The
other options will be described in the next sections. other options will be described in the next sections.
...@@ -219,10 +194,10 @@ cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c ...@@ -219,10 +194,10 @@ cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c
<para> <para>
Finally, move the <filename>_pg.so</filename>, Finally, move the <filename>_pg.so</filename>,
<filename>pg.py</filename>, and <filename>pgdb.py</filename> <filename>pg.py</filename>, and <filename>pgdb.py</filename>
to a directory in your <literal>PYTHONPATH</literal>. to a directory in your <envar>PYTHONPATH</envar>.
A good place would be A good place would be
<filename>/usr/lib/python1.5/site-python</filename> <filename>/usr/lib/python1.5/site-python</filename>
if your <productname>Python</productname> modules are in if your <application>Python</application> modules are in
<filename>/usr/lib/python1.5</filename>. <filename>/usr/lib/python1.5</filename>.
</para> </para>
</listitem> </listitem>
...@@ -238,16 +213,16 @@ cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c ...@@ -238,16 +213,16 @@ cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c
<para> <para>
Find the directory where your <filename>Setup</filename> Find the directory where your <filename>Setup</filename>
file lives (usually <filename>??/Modules</filename>) in file lives (usually <filename>??/Modules</filename>) in
the <productname>Python</productname> source hierarchy and the <application>Python</application> source hierarchy and
copy or symlink the <filename>pgmodule.c</filename> file there. copy or symlink the <filename>pgmodule.c</filename> file there.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Add the following line to your Setup file Add the following line to your <filename>Setup</> file
<ProgramListing> <programlisting>
_pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems _pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems
</ProgramListing> </programlisting>
where: where:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
...@@ -268,35 +243,35 @@ _pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems ...@@ -268,35 +243,35 @@ _pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
<literal>-DNO_DEF_VAR</literal> - no default variables <option>-DNO_DEF_VAR</option> - no default variables
support support
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<literal>-DNO_DIRECT</literal> - no direct access methods <option>-DNO_DIRECT</option> - no direct access methods
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<literal>-DNO_LARGE</literal> - no large object support <option>-DNO_LARGE</option> - no large object support
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<literal>-DNO_SNPRINTF</literal> - if running a system with <option>-DNO_SNPRINTF</option> - if running a system with
no snprintf call no snprintf call
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<literal>-DNO_PQSOCKET</literal> - if running an older <option>-DNO_PQSOCKET</option> - if running an older
<productname>PostgreSQL</productname> <productname>PostgreSQL</productname>
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
Define <literal>DNO_PQSOCKET</literal> if you are using a version of Define <option>-DNO_PQSOCKET</option> if you are using a version of
<productname>PostgreSQL</productname> before 6.4 <productname>PostgreSQL</productname> before 6.4
that does not have the <function>PQsocket</function> function. that does not have the <function>PQsocket</function> function.
The other options will be described in the next sections. The other options will be described in the next sections.
...@@ -305,7 +280,7 @@ _pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems ...@@ -305,7 +280,7 @@ _pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems
<listitem> <listitem>
<para> <para>
If you want a shared module, make sure that the If you want a shared module, make sure that the
<literal>*shared*</literal> keyword is uncommented and <literal>*shared*</literal> key word is uncommented and
add the above line below it. You used to need to install add the above line below it. You used to need to install
your shared modules with <literal>make sharedinstall</> but this no your shared modules with <literal>make sharedinstall</> but this no
longer seems to be true. longer seems to be true.
...@@ -320,13 +295,13 @@ _pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems ...@@ -320,13 +295,13 @@ _pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Rebuild <productname>Python</productname> from the root Rebuild <application>Python</application> from the root
directory of the <productname>Python</productname> source directory of the <application>Python</application> source
hierarchy by running hierarchy by running
<ProgramListing> <programlisting>
make -f Makefile.pre.in boot make -f Makefile.pre.in boot
make && make install make && make install
</ProgramListing> </programlisting>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
...@@ -342,22 +317,19 @@ make && make install ...@@ -342,22 +317,19 @@ make && make install
]]> ]]>
<sect1 id="pygresql-pg">
<title>The <literal>pg</literal> Module</title>
<para> <para>
You may either choose to use the old mature interface provided by You may either choose to use the old mature interface provided by
the <literal>pg</literal> module or otherwise the newer the <literal>pg</literal> module or otherwise the newer
<literal>pgdb</literal> interface compliant with the <ulink <literal>pgdb</literal> interface compliant with the <ulink
url="http://www.python.org/topics/database/DatabaseAPI-2.0.html" url="http://www.python.org/topics/database/DatabaseAPI-2.0.html"
><acronym>DB-API 2.0</acronym></ulink> specification developed by ><acronym>DB-API 2.0</acronym></ulink> specification developed by
the <productname>Python</productname> <acronym>DB-SIG</acronym>. the <application>Python</application> <acronym>DB-SIG</acronym>.
</para> </para>
<para> <para>
Here we describe only the older <literal>pg</literal> Here we describe only the older <literal>pg</literal>
<acronym>API</acronym>. As long as <acronym>API</acronym>. As long as
<productname>PyGreSQL</productname> does not contain a description <application>PyGreSQL</application> does not contain a description
of the <acronym>DB-API</acronym> you should read about the of the <acronym>DB-API</acronym> you should read about the
<acronym>API</acronym> at <ulink <acronym>API</acronym> at <ulink
url="http://www.python.org/topics/database/DatabaseAPI-2.0.html" url="http://www.python.org/topics/database/DatabaseAPI-2.0.html"
...@@ -365,12 +337,15 @@ make && make install ...@@ -365,12 +337,15 @@ make && make install
</para> </para>
<para> <para>
A tutorial-like introduction to the <acronym>DB-API</acronym> can A tutorial-like introduction to the <acronym>DB-API</acronym> can be
be found at <ulink found at <ulink
url="http://www2.linuxjournal.com/lj-issues/issue49/2605.html" url="http://www2.linuxjournal.com/lj-issues/issue49/2605.html"
>http://www2.linuxjournal.com/lj-issues/issue49/2605.html</ulink> >http://www2.linuxjournal.com/lj-issues/issue49/2605.html</ulink>
</para> </para>
<sect1 id="pygresql-pg">
<title>The <literal>pg</literal> Module</title>
<para> <para>
The <literal>pg</literal> module defines three objects: The <literal>pg</literal> module defines three objects:
<itemizedlist> <itemizedlist>
...@@ -390,7 +365,7 @@ make && make install ...@@ -390,7 +365,7 @@ make && make install
<listitem> <listitem>
<para> <para>
<literal>pgqueryobject</literal> that handles query results. <classname>pgqueryobject</classname> that handles query results.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
...@@ -399,8 +374,8 @@ make && make install ...@@ -399,8 +374,8 @@ make && make install
<para> <para>
If you want to see a simple example of the use of some of these If you want to see a simple example of the use of some of these
functions, see <ulink url="http://www.druid.net/rides" functions, see <ulink url="http://www.druid.net/rides"
>http://www.druid.net/rides</ulink> where I have a link at the >http://www.druid.net/rides</ulink> where you can find a link at the
bottom to the actual <productname>Python</productname> code for the bottom to the actual <application>Python</application> code for the
page. page.
</para> </para>
...@@ -410,7 +385,7 @@ make && make install ...@@ -410,7 +385,7 @@ make && make install
<para> <para>
Some constants are defined in the <literal>pg</literal> module Some constants are defined in the <literal>pg</literal> module
dictionary. They are intended to be used as a parameters for dictionary. They are intended to be used as a parameters for
methods calls. You should refer to the <literal>libpq</literal> methods calls. You should refer to the <application>libpq</application>
description (<xref linkend="libpq">) for more information about description (<xref linkend="libpq">) for more information about
them. These constants are: them. These constants are:
...@@ -470,7 +445,7 @@ make && make install ...@@ -470,7 +445,7 @@ make && make install
default variable, and forget it, without having to modify your default variable, and forget it, without having to modify your
environment. The support for default variables can be disabled by environment. The support for default variables can be disabled by
setting the <option>-DNO_DEF_VAR</option> option in the Python setting the <option>-DNO_DEF_VAR</option> option in the Python
Setup file. Methods relative to this are specified by te tag [DV]. <filename>Setup</> file. Methods relative to this are specified by the tag [DV].
</para> </para>
<para> <para>
...@@ -487,12 +462,12 @@ make && make install ...@@ -487,12 +462,12 @@ make && make install
<refnamediv> <refnamediv>
<refname>connect</refname> <refname>connect</refname>
<refpurpose>opens a connection to the database server</refpurpose> <refpurpose>open a connection to the database server</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
connect(<optional><replaceable>dbname</replaceable></optional>, <optional><replaceable>host</replaceable></optional>, <optional><replaceable>port</replaceable></optional>, <optional><replaceable>opt</replaceable></optional>, <optional><replaceable>tty</replaceable></optional>, <optional><replaceable>user</replaceable></optional>, <optional><replaceable>passwd</replaceable></optional>) 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> </synopsis>
<refsect2 id="pygresql-connect-parameters"> <refsect2 id="pygresql-connect-parameters">
...@@ -500,23 +475,23 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla ...@@ -500,23 +475,23 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><replaceable>dbname</replaceable></term> <term><parameter>dbname</parameter></term>
<listitem> <listitem>
<para>Name of connected database (string/None).</para> <para>Name of connected database (string/<symbol>None</>).</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><replaceable>host</replaceable></term> <term><parameter>host</parameter></term>
<listitem> <listitem>
<para>Name of the server host (string/None).</para> <para>Name of the server host (string/<symbol>None</>).</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><replaceable>port</replaceable></term> <term><parameter>port</parameter></term>
<listitem> <listitem>
<para>Port used by the database server (integer/-1).</para> <para>Port used by the database server (integer/-1).</para>
...@@ -524,41 +499,41 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla ...@@ -524,41 +499,41 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><replaceable>opt</replaceable></term> <term><parameter>opt</parameter></term>
<listitem> <listitem>
<para> <para>
Options for the server (string/None). Options for the server (string/<symbol>None</>).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><replaceable>tty</replaceable></term> <term><parameter>tty</parameter></term>
<listitem> <listitem>
<para> <para>
File or tty for optional debug output from backend File or tty for optional debug output from backend
(string/None). (string/<symbol>None</>).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><replaceable>user</replaceable></term> <term><parameter>user</parameter></term>
<listitem> <listitem>
<para> <para>
<productname>PostgreSQL</productname> user (string/None). <productname>PostgreSQL</productname> user (string/<symbol>None</>).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><replaceable>passwd</replaceable></term> <term><parameter>passwd</parameter></term>
<listitem> <listitem>
<para>Password for user (string/None).</para> <para>Password for user (string/<symbol>None</>).</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
...@@ -569,7 +544,7 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla ...@@ -569,7 +544,7 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><replaceable>pgobject</replaceable></term> <term><parameter>pgobject</parameter></term>
<listitem> <listitem>
<para> <para>
...@@ -585,7 +560,7 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla ...@@ -585,7 +560,7 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><errorname>TypeError</errorname></term> <term><classname>TypeError</classname></term>
<listitem> <listitem>
<para> <para>
...@@ -595,7 +570,7 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla ...@@ -595,7 +570,7 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><errorname>SyntaxError</errorname></term> <term><classname>SyntaxError</classname></term>
<listitem> <listitem>
<para> <para>
...@@ -605,18 +580,18 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla ...@@ -605,18 +580,18 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><errorname>pg.error</errorname></term> <term><classname>pg.error</classname></term>
<listitem> <listitem>
<para> <para>
Some error occurred during pg connection definition. Some error occurred during <literal>pg</> connection definition.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
<para> <para>
(+ all exceptions relative to object allocation) (plus all exceptions relative to object allocation)
</para> </para>
</refsect2> </refsect2>
</refsynopsisdiv> </refsynopsisdiv>
...@@ -627,9 +602,9 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla ...@@ -627,9 +602,9 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla
<para> <para>
This method opens a connection to a specified database on a given This method opens a connection to a specified database on a given
<productname>PostgreSQL</productname> server. You can use <productname>PostgreSQL</productname> server. You can use
keywords here, as described in the key words here, as described in the
<productname>Python</productname> tutorial. The names of the <application>Python</application> tutorial. The names of the
keywords are the name of the parameters given in the syntax key words are the name of the parameters given in the syntax
line. For a precise description of the parameters, please refer line. For a precise description of the parameters, please refer
to the <productname>PostgreSQL</productname> user manual. to the <productname>PostgreSQL</productname> user manual.
</para> </para>
...@@ -680,7 +655,7 @@ get_defhost() ...@@ -680,7 +655,7 @@ get_defhost()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>string or None</term> <term>string or <symbol>None</></term>
<listitem> <listitem>
<para> <para>
...@@ -696,7 +671,7 @@ get_defhost() ...@@ -696,7 +671,7 @@ get_defhost()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><errorname>SyntaxError</errorname></term> <term><classname>SyntaxError</classname></term>
<listitem> <listitem>
<para> <para>
...@@ -714,7 +689,7 @@ get_defhost() ...@@ -714,7 +689,7 @@ get_defhost()
<para> <para>
<function>get_defhost()</function> returns the current default <function>get_defhost()</function> returns the current default
host specification, or None if the environment variables should host specification, or <symbol>None</> if the environment variables should
be used. Environment variables will not be looked up. be used. Environment variables will not be looked up.
</para> </para>
</refsect1> </refsect1>
...@@ -727,6 +702,7 @@ get_defhost() ...@@ -727,6 +702,7 @@ get_defhost()
<refentrytitle>set_defhost</refentrytitle> <refentrytitle>set_defhost</refentrytitle>
<refmiscinfo>PYGRESQL - Connection Management</refmiscinfo> <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>set_defhost</refname> <refname>set_defhost</refname>
<refpurpose>set default host name [DV]</refpurpose> <refpurpose>set default host name [DV]</refpurpose>
...@@ -734,7 +710,7 @@ get_defhost() ...@@ -734,7 +710,7 @@ get_defhost()
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
set_defhost(<replaceable>host</replaceable>) set_defhost(<parameter>host</parameter>)
</synopsis> </synopsis>
<refsect2 id="pygresql-set-defhost-parameters"> <refsect2 id="pygresql-set-defhost-parameters">
...@@ -742,10 +718,10 @@ set_defhost(<replaceable>host</replaceable>) ...@@ -742,10 +718,10 @@ set_defhost(<replaceable>host</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>host</replaceable> <parameter>host</parameter>
</term> </term>
<listitem> <listitem>
<para>New default host (string/None).</para> <para>New default host (string/<symbol>None</>).</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
...@@ -756,7 +732,7 @@ set_defhost(<replaceable>host</replaceable>) ...@@ -756,7 +732,7 @@ set_defhost(<replaceable>host</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
string or None string or <symbol>None</>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -772,7 +748,7 @@ set_defhost(<replaceable>host</replaceable>) ...@@ -772,7 +748,7 @@ set_defhost(<replaceable>host</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -789,7 +765,7 @@ set_defhost(<replaceable>host</replaceable>) ...@@ -789,7 +765,7 @@ set_defhost(<replaceable>host</replaceable>)
<title>Description</title> <title>Description</title>
<para> <para>
<function>set_defhost()</function> sets the default host value <function>set_defhost()</function> sets the default host value
for new connections. If None is supplied as parameter, environment for new connections. If <symbol>None</symbol> is supplied as parameter, environment
variables will be used in future connections. It returns the variables will be used in future connections. It returns the
previous setting for default host. previous setting for default host.
</para> </para>
...@@ -826,7 +802,7 @@ get_defport() ...@@ -826,7 +802,7 @@ get_defport()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
integer or None integer or <symbol>None</symbol>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -842,7 +818,7 @@ get_defport() ...@@ -842,7 +818,7 @@ get_defport()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>SyntaxError</errorname> <classname>SyntaxError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -859,7 +835,7 @@ get_defport() ...@@ -859,7 +835,7 @@ get_defport()
<title>Description</title> <title>Description</title>
<para> <para>
<function>get_defport()</function> returns the current default <function>get_defport()</function> returns the current default
port specification, or None if the environment variables should port specification, or <symbol>None</symbol> if the environment variables should
be used. Environment variables will not be looked up. be used. Environment variables will not be looked up.
</para> </para>
</refsect1> </refsect1>
...@@ -880,7 +856,7 @@ get_defport() ...@@ -880,7 +856,7 @@ get_defport()
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
set_defport(<replaceable>port</replaceable>) set_defport(<parameter>port</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-SET-DEFPORT-1"> <refsect2 id="R2-PYGRESQL-SET-DEFPORT-1">
...@@ -888,7 +864,7 @@ set_defport(<replaceable>port</replaceable>) ...@@ -888,7 +864,7 @@ set_defport(<replaceable>port</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>port</replaceable> <parameter>port</parameter>
</term> </term>
<listitem> <listitem>
<para>New default host (integer/-1).</para> <para>New default host (integer/-1).</para>
...@@ -902,7 +878,7 @@ set_defport(<replaceable>port</replaceable>) ...@@ -902,7 +878,7 @@ set_defport(<replaceable>port</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
integer or None integer or <symbol>None</symbol>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -918,7 +894,7 @@ set_defport(<replaceable>port</replaceable>) ...@@ -918,7 +894,7 @@ set_defport(<replaceable>port</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -972,7 +948,7 @@ get_defopt() ...@@ -972,7 +948,7 @@ get_defopt()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
string or None string or <symbol>None</symbol>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -988,7 +964,7 @@ get_defopt() ...@@ -988,7 +964,7 @@ get_defopt()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>SyntaxError</errorname> <classname>SyntaxError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1005,7 +981,7 @@ get_defopt() ...@@ -1005,7 +981,7 @@ get_defopt()
<title>Description</title> <title>Description</title>
<para> <para>
<function>get_defopt()</function> returns the current default <function>get_defopt()</function> returns the current default
connection options specification, or None if the environment variables should connection options specification, or <symbol>None</symbol> if the environment variables should
be used. Environment variables will not be looked up. be used. Environment variables will not be looked up.
</para> </para>
</refsect1> </refsect1>
...@@ -1021,12 +997,12 @@ get_defopt() ...@@ -1021,12 +997,12 @@ get_defopt()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>set_defopt</refname> <refname>set_defopt</refname>
<refpurpose>set options specification [DV]</refpurpose> <refpurpose>set default options specification [DV]</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
set_defopt(<replaceable>options</replaceable>) set_defopt(<parameter>options</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-SET-DEFOPT-1"> <refsect2 id="R2-PYGRESQL-SET-DEFOPT-1">
...@@ -1034,10 +1010,10 @@ set_defopt(<replaceable>options</replaceable>) ...@@ -1034,10 +1010,10 @@ set_defopt(<replaceable>options</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>options</replaceable> <parameter>options</parameter>
</term> </term>
<listitem> <listitem>
<para>New default connection options (string/None).</para> <para>New default connection options (string/<symbol>None</symbol>).</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
...@@ -1048,7 +1024,7 @@ set_defopt(<replaceable>options</replaceable>) ...@@ -1048,7 +1024,7 @@ set_defopt(<replaceable>options</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
string or None string or <symbol>None</symbol>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1064,7 +1040,7 @@ set_defopt(<replaceable>options</replaceable>) ...@@ -1064,7 +1040,7 @@ set_defopt(<replaceable>options</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1081,7 +1057,7 @@ set_defopt(<replaceable>options</replaceable>) ...@@ -1081,7 +1057,7 @@ set_defopt(<replaceable>options</replaceable>)
<title>Description</title> <title>Description</title>
<para> <para>
<function>set_defopt()</function> sets the default connection options value <function>set_defopt()</function> sets the default connection options value
for new connections. If None is supplied as parameter, environment for new connections. If <symbol>None</symbol> is supplied as parameter, environment
variables will be used in future connections. It returns the variables will be used in future connections. It returns the
previous setting for default options. previous setting for default options.
</para> </para>
...@@ -1118,7 +1094,7 @@ get_deftty() ...@@ -1118,7 +1094,7 @@ get_deftty()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
string or None string or <symbol>None</symbol>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1134,7 +1110,7 @@ get_deftty() ...@@ -1134,7 +1110,7 @@ get_deftty()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>SyntaxError</errorname> <classname>SyntaxError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1151,7 +1127,7 @@ get_deftty() ...@@ -1151,7 +1127,7 @@ get_deftty()
<title>Description</title> <title>Description</title>
<para> <para>
<function>get_deftty()</function> returns the current default <function>get_deftty()</function> returns the current default
debug terminal specification, or None if the environment variables should debug terminal specification, or <symbol>None</symbol> if the environment variables should
be used. Environment variables will not be looked up. be used. Environment variables will not be looked up.
</para> </para>
</refsect1> </refsect1>
...@@ -1167,12 +1143,12 @@ get_deftty() ...@@ -1167,12 +1143,12 @@ get_deftty()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>set_deftty</refname> <refname>set_deftty</refname>
<refpurpose>set default debug terminal specification [DV]</refpurpose> <refpurpose>set default connection debug terminal specification [DV]</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
set_deftty(<replaceable>terminal</replaceable>) set_deftty(<parameter>terminal</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-SET-DEFTTY-1"> <refsect2 id="R2-PYGRESQL-SET-DEFTTY-1">
...@@ -1180,10 +1156,10 @@ set_deftty(<replaceable>terminal</replaceable>) ...@@ -1180,10 +1156,10 @@ set_deftty(<replaceable>terminal</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>terminal</replaceable> <parameter>terminal</parameter>
</term> </term>
<listitem> <listitem>
<para>New default debug terminal (string/None).</para> <para>New default debug terminal (string/<symbol>None</symbol>).</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
...@@ -1194,7 +1170,7 @@ set_deftty(<replaceable>terminal</replaceable>) ...@@ -1194,7 +1170,7 @@ set_deftty(<replaceable>terminal</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
string or None string or <symbol>None</symbol>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1210,7 +1186,7 @@ set_deftty(<replaceable>terminal</replaceable>) ...@@ -1210,7 +1186,7 @@ set_deftty(<replaceable>terminal</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1227,7 +1203,7 @@ set_deftty(<replaceable>terminal</replaceable>) ...@@ -1227,7 +1203,7 @@ set_deftty(<replaceable>terminal</replaceable>)
<title>Description</title> <title>Description</title>
<para> <para>
<function>set_deftty()</function> sets the default terminal value <function>set_deftty()</function> sets the default terminal value
for new connections. If None is supplied as parameter, environment for new connections. If <symbol>None</symbol> is supplied as parameter, environment
variables will be used in future connections. It returns the variables will be used in future connections. It returns the
previous setting for default terminal. previous setting for default terminal.
</para> </para>
...@@ -1264,7 +1240,7 @@ get_defbase() ...@@ -1264,7 +1240,7 @@ get_defbase()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
string or None string or <symbol>None</symbol>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1280,7 +1256,7 @@ get_defbase() ...@@ -1280,7 +1256,7 @@ get_defbase()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>SyntaxError</errorname> <classname>SyntaxError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1297,7 +1273,7 @@ get_defbase() ...@@ -1297,7 +1273,7 @@ get_defbase()
<title>Description</title> <title>Description</title>
<para> <para>
<function>get_defbase()</function> returns the current default <function>get_defbase()</function> returns the current default
database name specification, or None if the environment variables should database name specification, or <symbol>None</symbol> if the environment variables should
be used. Environment variables will not be looked up. be used. Environment variables will not be looked up.
</para> </para>
</refsect1> </refsect1>
...@@ -1318,7 +1294,7 @@ get_defbase() ...@@ -1318,7 +1294,7 @@ get_defbase()
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
set_defbase(<replaceable>database</replaceable>) set_defbase(<parameter>database</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-SET-DEFBASE-1"> <refsect2 id="R2-PYGRESQL-SET-DEFBASE-1">
...@@ -1326,10 +1302,10 @@ set_defbase(<replaceable>database</replaceable>) ...@@ -1326,10 +1302,10 @@ set_defbase(<replaceable>database</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>database</replaceable> <parameter>database</parameter>
</term> </term>
<listitem> <listitem>
<para>New default database name (string/None).</para> <para>New default database name (string/<symbol>None</symbol>).</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
...@@ -1340,7 +1316,7 @@ set_defbase(<replaceable>database</replaceable>) ...@@ -1340,7 +1316,7 @@ set_defbase(<replaceable>database</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
string or None string or <symbol>None</symbol>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1356,7 +1332,7 @@ set_defbase(<replaceable>database</replaceable>) ...@@ -1356,7 +1332,7 @@ set_defbase(<replaceable>database</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1373,7 +1349,7 @@ set_defbase(<replaceable>database</replaceable>) ...@@ -1373,7 +1349,7 @@ set_defbase(<replaceable>database</replaceable>)
<title>Description</title> <title>Description</title>
<para> <para>
<function>set_defbase()</function> sets the default database name <function>set_defbase()</function> sets the default database name
for new connections. If None is supplied as parameter, environment for new connections. If <symbol>None</symbol> is supplied as parameter, environment
variables will be used in future connections. It returns the variables will be used in future connections. It returns the
previous setting for default database name. previous setting for default database name.
</para> </para>
...@@ -1385,7 +1361,7 @@ set_defbase(<replaceable>database</replaceable>) ...@@ -1385,7 +1361,7 @@ set_defbase(<replaceable>database</replaceable>)
<sect1 id="pygresql-pg-pgobject"> <sect1 id="pygresql-pg-pgobject">
<title>Connection object: <classname>pgobject</classname></title> <title>Connection Object: <classname>pgobject</classname></title>
<para> <para>
This object handles a connection to the This object handles a connection to the
...@@ -1398,20 +1374,20 @@ set_defbase(<replaceable>database</replaceable>) ...@@ -1398,20 +1374,20 @@ set_defbase(<replaceable>database</replaceable>)
Some methods give direct access to the connection socket. They are Some methods give direct access to the connection socket. They are
specified by the tag [DA]. <emphasis>Do not use them unless you specified by the tag [DA]. <emphasis>Do not use them unless you
really know what you are doing.</emphasis> If you prefer disabling really know what you are doing.</emphasis> If you prefer disabling
them, set the <literal>-DNO_DIRECT</literal> option in the them, set the <option>-DNO_DIRECT</option> option in the
<productname>Python</productname> <filename>Setup</filename> file. <application>Python</application> <filename>Setup</filename> file.
</para> </para>
<para> <para>
Some other methods give access to large objects. if you want to Some other methods give access to large objects. if you want to
forbid access to these from the module, set the forbid access to these from the module, set the
<literal>-DNO_LARGE</literal> option in the <option>-DNO_LARGE</option> option in the
<productname>Python</productname> <filename>Setup</filename> file. <application>Python</application> <filename>Setup</filename> file.
These methods are specified by the tag [LO]. These methods are specified by the tag [LO].
</para> </para>
<para> <para>
Every <literal>pgobject</literal> defines a set of read-only Every <classname>pgobject</classname> defines a set of read-only
attributes that describe the connection and its status. These attributes that describe the connection and its status. These
attributes are: attributes are:
...@@ -1474,7 +1450,7 @@ set_defbase(<replaceable>database</replaceable>) ...@@ -1474,7 +1450,7 @@ set_defbase(<replaceable>database</replaceable>)
<term>status</term> <term>status</term>
<listitem> <listitem>
<para> <para>
the status of the connection (integer: 1 - OK, 0 - BAD) the status of the connection (integer: 1 - OK, 0 - bad)
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -1498,12 +1474,12 @@ set_defbase(<replaceable>database</replaceable>) ...@@ -1498,12 +1474,12 @@ set_defbase(<replaceable>database</replaceable>)
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>query</refname> <refname>query</refname>
<refpurpose>executes a SQL command</refpurpose> <refpurpose>execute a SQL command</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
query(<replaceable>command</replaceable>) query(<parameter>command</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-QUERY-1"> <refsect2 id="R2-PYGRESQL-QUERY-1">
...@@ -1511,7 +1487,7 @@ query(<replaceable>command</replaceable>) ...@@ -1511,7 +1487,7 @@ query(<replaceable>command</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>command</replaceable> <parameter>command</parameter>
</term> </term>
<listitem> <listitem>
<para>SQL command (string).</para> <para>SQL command (string).</para>
...@@ -1525,7 +1501,7 @@ query(<replaceable>command</replaceable>) ...@@ -1525,7 +1501,7 @@ query(<replaceable>command</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
pgqueryobject or None <classname>pgqueryobject</> or <symbol>None</symbol>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1541,7 +1517,7 @@ query(<replaceable>command</replaceable>) ...@@ -1541,7 +1517,7 @@ query(<replaceable>command</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1551,7 +1527,7 @@ query(<replaceable>command</replaceable>) ...@@ -1551,7 +1527,7 @@ query(<replaceable>command</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>ValueError</errorname> <classname>ValueError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1561,7 +1537,7 @@ query(<replaceable>command</replaceable>) ...@@ -1561,7 +1537,7 @@ query(<replaceable>command</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1581,8 +1557,8 @@ query(<replaceable>command</replaceable>) ...@@ -1581,8 +1557,8 @@ query(<replaceable>command</replaceable>)
query to the database. If the query is an insert statement, the return query to the database. If the query is an insert statement, the return
value is the <acronym>OID</acronym> of the newly inserted row. value is the <acronym>OID</acronym> of the newly inserted row.
If it is otherwise a query that does not return a result If it is otherwise a query that does not return a result
(i.e., is not a some kind of <literal>SELECT</literal> statement), it returns None. (i.e., is not a some kind of <literal>SELECT</literal> statement), it returns <symbol>None</symbol>.
Otherwise, it returns a <literal>pgqueryobject</literal> that can be accessed via the Otherwise, it returns a <classname>pgqueryobject</classname> that can be accessed via the
<function>getresult()</function> or <function>dictresult()</function> <function>getresult()</function> or <function>dictresult()</function>
methods or simply printed. methods or simply printed.
</para> </para>
...@@ -1599,7 +1575,7 @@ query(<replaceable>command</replaceable>) ...@@ -1599,7 +1575,7 @@ query(<replaceable>command</replaceable>)
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>reset</refname> <refname>reset</refname>
<refpurpose>resets the connection</refpurpose> <refpurpose>reset the connection</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
...@@ -1626,7 +1602,7 @@ reset() ...@@ -1626,7 +1602,7 @@ reset()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1684,7 +1660,7 @@ close() ...@@ -1684,7 +1660,7 @@ close()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1718,7 +1694,7 @@ close() ...@@ -1718,7 +1694,7 @@ close()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>fileno</refname> <refname>fileno</refname>
<refpurpose>returns the socket used to connect to the database</refpurpose> <refpurpose>return the socket used to connect to the database</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
...@@ -1754,7 +1730,7 @@ fileno() ...@@ -1754,7 +1730,7 @@ fileno()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1786,7 +1762,7 @@ fileno() ...@@ -1786,7 +1762,7 @@ fileno()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>getnotify</refname> <refname>getnotify</refname>
<refpurpose>gets the last notify from the server</refpurpose> <refpurpose>get the last notify from the server</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
...@@ -1806,7 +1782,7 @@ getnotify() ...@@ -1806,7 +1782,7 @@ getnotify()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
tuple, None tuple, <symbol>None</symbol>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1822,7 +1798,7 @@ getnotify() ...@@ -1822,7 +1798,7 @@ getnotify()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1832,7 +1808,7 @@ getnotify() ...@@ -1832,7 +1808,7 @@ getnotify()
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1849,12 +1825,12 @@ getnotify() ...@@ -1849,12 +1825,12 @@ getnotify()
<title>Description</title> <title>Description</title>
<para> <para>
<function>getnotify()</function> method tries to get a notify from <function>getnotify()</function> method tries to get a notify from
the server (from the <literal>SQL</literal> statement <literal>NOTIFY</literal>). the server (from the SQL statement <literal>NOTIFY</literal>).
If the server returns no notify, the methods returns None. If the server returns no notify, the methods returns <symbol>None</symbol>.
Otherwise, it returns a tuple (couple) <literal>(relname, pid)</literal>, Otherwise, it returns a tuple (couple) <literal>(relname, pid)</literal>,
where <literal>relname</literal> is the name of the notify and <literal>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. the process id of the connection that triggered the notify.
Remember to do a listen query first otherwise getnotify will always return None. Remember to do a listen query first otherwise <function>getnotify</> will always return <symbol>None</symbol>.
</para> </para>
</refsect1> </refsect1>
...@@ -1869,12 +1845,12 @@ getnotify() ...@@ -1869,12 +1845,12 @@ getnotify()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>inserttable</refname> <refname>inserttable</refname>
<refpurpose>inserts a list into a table</refpurpose> <refpurpose>insert a list into a table</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>) inserttable(<parameter>table</parameter>, <parameter>values</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-INSERTTABLE-1"> <refsect2 id="R2-PYGRESQL-INSERTTABLE-1">
...@@ -1882,7 +1858,7 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>) ...@@ -1882,7 +1858,7 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>table</replaceable> <parameter>table</parameter>
</term> </term>
<listitem> <listitem>
<para>The table name (string).</para> <para>The table name (string).</para>
...@@ -1890,7 +1866,7 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>) ...@@ -1890,7 +1866,7 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>values</replaceable> <parameter>values</parameter>
</term> </term>
<listitem> <listitem>
<para>The list of rows values to insert (list).</para> <para>The list of rows values to insert (list).</para>
...@@ -1911,7 +1887,7 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>) ...@@ -1911,7 +1887,7 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1921,7 +1897,7 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>) ...@@ -1921,7 +1897,7 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -1943,7 +1919,7 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>) ...@@ -1943,7 +1919,7 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>)
tuples/lists that define the values for each inserted row. The tuples/lists that define the values for each inserted row. The
rows values may contain string, integer, long or double (real) rows values may contain string, integer, long or double (real)
values. <emphasis>Be very careful:</emphasis> this method values. <emphasis>Be very careful:</emphasis> this method
does not typecheck the fields according to the table does not type-check the fields according to the table
definition; it just look whether or not it knows how to handle definition; it just look whether or not it knows how to handle
such types. such types.
</para> </para>
...@@ -1960,12 +1936,12 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>) ...@@ -1960,12 +1936,12 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>)
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>putline</refname> <refname>putline</refname>
<refpurpose>writes a line to the server socket [DA]</refpurpose> <refpurpose>write a line to the server socket [DA]</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
putline(<replaceable>line</replaceable>) putline(<parameter>line</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-PUTLINE-1"> <refsect2 id="R2-PYGRESQL-PUTLINE-1">
...@@ -1973,7 +1949,7 @@ putline(<replaceable>line</replaceable>) ...@@ -1973,7 +1949,7 @@ putline(<replaceable>line</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>line</replaceable> <parameter>line</parameter>
</term> </term>
<listitem> <listitem>
<para>Line to be written (string).</para> <para>Line to be written (string).</para>
...@@ -1994,7 +1970,7 @@ putline(<replaceable>line</replaceable>) ...@@ -1994,7 +1970,7 @@ putline(<replaceable>line</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2004,7 +1980,7 @@ putline(<replaceable>line</replaceable>) ...@@ -2004,7 +1980,7 @@ putline(<replaceable>line</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2035,7 +2011,7 @@ putline(<replaceable>line</replaceable>) ...@@ -2035,7 +2011,7 @@ putline(<replaceable>line</replaceable>)
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>getline</refname> <refname>getline</refname>
<refpurpose>gets a line from server socket [DA]</refpurpose> <refpurpose>get a line from server socket [DA]</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
...@@ -2071,7 +2047,7 @@ getline() ...@@ -2071,7 +2047,7 @@ getline()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2081,7 +2057,7 @@ getline() ...@@ -2081,7 +2057,7 @@ getline()
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2112,7 +2088,7 @@ getline() ...@@ -2112,7 +2088,7 @@ getline()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>endcopy</refname> <refname>endcopy</refname>
<refpurpose>synchronizes client and server [DA]</refpurpose> <refpurpose>synchronize client and server [DA]</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
...@@ -2139,7 +2115,7 @@ endcopy() ...@@ -2139,7 +2115,7 @@ endcopy()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2149,7 +2125,7 @@ endcopy() ...@@ -2149,7 +2125,7 @@ endcopy()
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2181,12 +2157,12 @@ endcopy() ...@@ -2181,12 +2157,12 @@ endcopy()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>locreate</refname> <refname>locreate</refname>
<refpurpose>creates of large object in the database [LO]</refpurpose> <refpurpose>create a large object in the database [LO]</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
locreate(<replaceable>mode</replaceable>) locreate(<parameter>mode</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-LOCREATE-1"> <refsect2 id="R2-PYGRESQL-LOCREATE-1">
...@@ -2194,7 +2170,7 @@ locreate(<replaceable>mode</replaceable>) ...@@ -2194,7 +2170,7 @@ locreate(<replaceable>mode</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>mode</replaceable> <parameter>mode</parameter>
</term> </term>
<listitem> <listitem>
<para>Large object create mode.</para> <para>Large object create mode.</para>
...@@ -2208,7 +2184,7 @@ locreate(<replaceable>mode</replaceable>) ...@@ -2208,7 +2184,7 @@ locreate(<replaceable>mode</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
pglarge <classname>pglarge</>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2224,7 +2200,7 @@ locreate(<replaceable>mode</replaceable>) ...@@ -2224,7 +2200,7 @@ locreate(<replaceable>mode</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2234,7 +2210,7 @@ locreate(<replaceable>mode</replaceable>) ...@@ -2234,7 +2210,7 @@ locreate(<replaceable>mode</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2252,7 +2228,7 @@ locreate(<replaceable>mode</replaceable>) ...@@ -2252,7 +2228,7 @@ locreate(<replaceable>mode</replaceable>)
<para> <para>
<function>locreate()</function> method creates a large object in the database. <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 The mode can be defined by OR-ing the constants defined in the pg module
(<literal>INV_READ and INV_WRITE</literal>). (<literal>INV_READ</literal> and <literal>INV_WRITE</literal>).
</para> </para>
</refsect1> </refsect1>
...@@ -2267,12 +2243,12 @@ locreate(<replaceable>mode</replaceable>) ...@@ -2267,12 +2243,12 @@ locreate(<replaceable>mode</replaceable>)
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>getlo</refname> <refname>getlo</refname>
<refpurpose>builds a large object from given <literal>oid</literal> [LO]</refpurpose> <refpurpose>build a large object from given OID [LO]</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
getlo(<replaceable>oid</replaceable>) getlo(<parameter>oid</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-GETLO-1"> <refsect2 id="R2-PYGRESQL-GETLO-1">
...@@ -2280,10 +2256,10 @@ getlo(<replaceable>oid</replaceable>) ...@@ -2280,10 +2256,10 @@ getlo(<replaceable>oid</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>oid</replaceable> <parameter>oid</parameter>
</term> </term>
<listitem> <listitem>
<para><literal>OID</literal> of the existing large object (integer).</para> <para>OID of the existing large object (integer).</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
...@@ -2294,7 +2270,7 @@ getlo(<replaceable>oid</replaceable>) ...@@ -2294,7 +2270,7 @@ getlo(<replaceable>oid</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
pglarge <classname>pglarge</>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2310,7 +2286,7 @@ getlo(<replaceable>oid</replaceable>) ...@@ -2310,7 +2286,7 @@ getlo(<replaceable>oid</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2320,7 +2296,7 @@ getlo(<replaceable>oid</replaceable>) ...@@ -2320,7 +2296,7 @@ getlo(<replaceable>oid</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2338,7 +2314,7 @@ getlo(<replaceable>oid</replaceable>) ...@@ -2338,7 +2314,7 @@ getlo(<replaceable>oid</replaceable>)
<para> <para>
<function>getlo()</function> method allows to reuse a formerly <function>getlo()</function> method allows to reuse a formerly
created large object through the <classname>pglarge</classname> interface, providing created large object through the <classname>pglarge</classname> interface, providing
the user have its <literal>oid</literal>. the user has its OID.
</para> </para>
</refsect1> </refsect1>
...@@ -2353,12 +2329,12 @@ getlo(<replaceable>oid</replaceable>) ...@@ -2353,12 +2329,12 @@ getlo(<replaceable>oid</replaceable>)
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>loimport</refname> <refname>loimport</refname>
<refpurpose>imports a file to a <productname>PostgreSQL</productname> large object [LO]</refpurpose> <refpurpose>import a file to a <productname>PostgreSQL</productname> large object [LO]</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
loimport(<replaceable>filename</replaceable>) loimport(<parameter>filename</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-LOIMPORT-1"> <refsect2 id="R2-PYGRESQL-LOIMPORT-1">
...@@ -2366,7 +2342,7 @@ loimport(<replaceable>filename</replaceable>) ...@@ -2366,7 +2342,7 @@ loimport(<replaceable>filename</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>filename</replaceable> <parameter>filename</parameter>
</term> </term>
<listitem> <listitem>
<para>The name of the file to be imported (string).</para> <para>The name of the file to be imported (string).</para>
...@@ -2380,7 +2356,7 @@ loimport(<replaceable>filename</replaceable>) ...@@ -2380,7 +2356,7 @@ loimport(<replaceable>filename</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
pglarge <classname>pglarge</>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2396,7 +2372,7 @@ loimport(<replaceable>filename</replaceable>) ...@@ -2396,7 +2372,7 @@ loimport(<replaceable>filename</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2406,7 +2382,7 @@ loimport(<replaceable>filename</replaceable>) ...@@ -2406,7 +2382,7 @@ loimport(<replaceable>filename</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2434,7 +2410,7 @@ loimport(<replaceable>filename</replaceable>) ...@@ -2434,7 +2410,7 @@ loimport(<replaceable>filename</replaceable>)
<sect1 id="pygresql-pg-DB"> <sect1 id="pygresql-pg-DB">
<title>Database wrapper class: <classname>DB</classname></title> <title>Database Wrapper Class: <classname>DB</classname></title>
<para> <para>
<classname>pg</classname> module contains a class called <classname>pg</classname> module contains a class called
...@@ -2476,12 +2452,12 @@ for r in db.query( ...@@ -2476,12 +2452,12 @@ for r in db.query(
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>pkey</refname> <refname>pkey</refname>
<refpurpose>returns the primary key of a table</refpurpose> <refpurpose>return the primary key of a table</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
pkey(<replaceable>table</replaceable>) pkey(<parameter>table</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-DB-PKEY-1"> <refsect2 id="R2-PYGRESQL-DB-PKEY-1">
...@@ -2489,7 +2465,7 @@ pkey(<replaceable>table</replaceable>) ...@@ -2489,7 +2465,7 @@ pkey(<replaceable>table</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>table</replaceable> <parameter>table</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2642,12 +2618,12 @@ get_tables() ...@@ -2642,12 +2618,12 @@ get_tables()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>get_attnames</refname> <refname>get_attnames</refname>
<refpurpose>returns the attribute names of a table</refpurpose> <refpurpose>return the attribute names of a table</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
get_attnames(<replaceable>table</replaceable>) get_attnames(<parameter>table</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-DB-GET-ATTNAMES-1"> <refsect2 id="R2-PYGRESQL-DB-GET-ATTNAMES-1">
...@@ -2655,7 +2631,7 @@ get_attnames(<replaceable>table</replaceable>) ...@@ -2655,7 +2631,7 @@ get_attnames(<replaceable>table</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>table</replaceable> <parameter>table</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2710,7 +2686,7 @@ get_attnames(<replaceable>table</replaceable>) ...@@ -2710,7 +2686,7 @@ get_attnames(<replaceable>table</replaceable>)
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional><replaceable>keyname</replaceable></optional>) get(<parameter>table</parameter>, <parameter>arg</parameter>, <optional><parameter>keyname</parameter></optional>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-DB-GET-1"> <refsect2 id="R2-PYGRESQL-DB-GET-1">
...@@ -2718,7 +2694,7 @@ get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional> ...@@ -2718,7 +2694,7 @@ get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>table</replaceable> <parameter>table</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2728,7 +2704,7 @@ get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional> ...@@ -2728,7 +2704,7 @@ get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>arg</replaceable> <parameter>arg</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2738,7 +2714,7 @@ get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional> ...@@ -2738,7 +2714,7 @@ get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<optional><replaceable>keyname</replaceable></optional> <optional><parameter>keyname</parameter></optional>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2771,11 +2747,11 @@ get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional> ...@@ -2771,11 +2747,11 @@ get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional>
<title>Description</title> <title>Description</title>
<para> <para>
This method is the basic mechanism to get a single row. It assumes This method is the basic mechanism to get a single row. It assumes
that the key specifies a unique row. If keyname is not specified that the key specifies a unique row. If <parameter>keyname</> is not specified
then the primary key for the table is used. If arg is a dictionary 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 then the value for the key is taken from it and it is modified to
include the new values, replacing existing values where necessary. include the new values, replacing existing values where necessary.
The oid is also put into the dictionary but in order to allow the 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 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 to make it unique. It consists of the string <literal>oid_</literal> followed by
the name of the table. the name of the table.
...@@ -2798,7 +2774,7 @@ get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional> ...@@ -2798,7 +2774,7 @@ get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>) insert(<parameter>table</parameter>, <parameter>a</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-DB-INSERT-1"> <refsect2 id="R2-PYGRESQL-DB-INSERT-1">
...@@ -2806,7 +2782,7 @@ insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>) ...@@ -2806,7 +2782,7 @@ insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>table</replaceable> <parameter>table</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2816,7 +2792,7 @@ insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>) ...@@ -2816,7 +2792,7 @@ insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>a</replaceable> <parameter>a</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2853,6 +2829,13 @@ insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>) ...@@ -2853,6 +2829,13 @@ insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>)
values from the database. This causes the dictionary to be updated values from the database. This causes the dictionary to be updated
with values that are modified by rules, triggers, etc. with values that are modified by rules, triggers, etc.
</para> </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> </refsect1>
</refentry> </refentry>
...@@ -2871,7 +2854,7 @@ insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>) ...@@ -2871,7 +2854,7 @@ insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>)
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
update(<replaceable>table</replaceable>, <replaceable>a</replaceable>) update(<parameter>table</parameter>, <parameter>a</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-DB-UPDATE-1"> <refsect2 id="R2-PYGRESQL-DB-UPDATE-1">
...@@ -2879,7 +2862,7 @@ update(<replaceable>table</replaceable>, <replaceable>a</replaceable>) ...@@ -2879,7 +2862,7 @@ update(<replaceable>table</replaceable>, <replaceable>a</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>table</replaceable> <parameter>table</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2889,7 +2872,7 @@ update(<replaceable>table</replaceable>, <replaceable>a</replaceable>) ...@@ -2889,7 +2872,7 @@ update(<replaceable>table</replaceable>, <replaceable>a</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>a</replaceable> <parameter>a</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2944,7 +2927,7 @@ update(<replaceable>table</replaceable>, <replaceable>a</replaceable>) ...@@ -2944,7 +2927,7 @@ update(<replaceable>table</replaceable>, <replaceable>a</replaceable>)
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
clear(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></optional>) clear(<parameter>table</parameter>, <optional><parameter>a</parameter></optional>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-DB-CLEAR-1"> <refsect2 id="R2-PYGRESQL-DB-CLEAR-1">
...@@ -2952,7 +2935,7 @@ clear(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></ ...@@ -2952,7 +2935,7 @@ clear(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>table</replaceable> <parameter>table</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -2962,7 +2945,7 @@ clear(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></ ...@@ -2962,7 +2945,7 @@ clear(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<optional><replaceable>a</replaceable></optional> <optional><parameter>a</parameter></optional>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3013,12 +2996,12 @@ clear(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></ ...@@ -3013,12 +2996,12 @@ clear(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>delete</refname> <refname>delete</refname>
<refpurpose>deletes the row from a table</refpurpose> <refpurpose>delete a row from a table</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></optional>) delete(<parameter>table</parameter>, <optional><parameter>a</parameter></optional>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-DB-DELETE-1"> <refsect2 id="R2-PYGRESQL-DB-DELETE-1">
...@@ -3026,7 +3009,7 @@ delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable>< ...@@ -3026,7 +3009,7 @@ delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable><
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>table</replaceable> <parameter>table</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3036,7 +3019,7 @@ delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable>< ...@@ -3036,7 +3019,7 @@ delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable><
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<optional><replaceable>a</replaceable></optional> <optional><parameter>a</parameter></optional>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3074,7 +3057,7 @@ delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable>< ...@@ -3074,7 +3057,7 @@ delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable><
<!-- ********************************************************** --> <!-- ********************************************************** -->
<sect1 id="pygresql-pg-pgqueryobject"> <sect1 id="pygresql-pg-pgqueryobject">
<title>Query result object: <literal>pgqueryobject</literal></title> <title>Query Result Object: <classname>pgqueryobject</classname></title>
<!-- ********************************************************** --> <!-- ********************************************************** -->
...@@ -3085,7 +3068,7 @@ delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable>< ...@@ -3085,7 +3068,7 @@ delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable><
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>getresult</refname> <refname>getresult</refname>
<refpurpose>gets the values returned by the query</refpurpose> <refpurpose>get the values returned by the query</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
...@@ -3121,7 +3104,7 @@ getresult() ...@@ -3121,7 +3104,7 @@ getresult()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>SyntaxError</errorname> <classname>SyntaxError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3131,7 +3114,7 @@ getresult() ...@@ -3131,7 +3114,7 @@ getresult()
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3164,7 +3147,7 @@ getresult() ...@@ -3164,7 +3147,7 @@ getresult()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>dictresult</refname> <refname>dictresult</refname>
<refpurpose>like getresult but returns a list of dictionaries</refpurpose> <refpurpose>get the values returned by the query as a list of dictionaries</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
...@@ -3200,7 +3183,7 @@ dictresult() ...@@ -3200,7 +3183,7 @@ dictresult()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>SyntaxError</errorname> <classname>SyntaxError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3210,7 +3193,7 @@ dictresult() ...@@ -3210,7 +3193,7 @@ dictresult()
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3243,7 +3226,7 @@ dictresult() ...@@ -3243,7 +3226,7 @@ dictresult()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>listfields</refname> <refname>listfields</refname>
<refpurpose>lists the fields names of the query result</refpurpose> <refpurpose>list the fields names of the query result</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
...@@ -3279,7 +3262,7 @@ listfields() ...@@ -3279,7 +3262,7 @@ listfields()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>SyntaxError</errorname> <classname>SyntaxError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3289,7 +3272,7 @@ listfields() ...@@ -3289,7 +3272,7 @@ listfields()
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3321,12 +3304,12 @@ listfields() ...@@ -3321,12 +3304,12 @@ listfields()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>fieldname</refname> <refname>fieldname</refname>
<refpurpose>field number-name conversion</refpurpose> <refpurpose>get field name by number</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
fieldname(<replaceable>i</replaceable>) fieldname(<parameter>i</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-1"> <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-1">
...@@ -3334,7 +3317,7 @@ fieldname(<replaceable>i</replaceable>) ...@@ -3334,7 +3317,7 @@ fieldname(<replaceable>i</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>i</replaceable> <parameter>i</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3366,7 +3349,7 @@ fieldname(<replaceable>i</replaceable>) ...@@ -3366,7 +3349,7 @@ fieldname(<replaceable>i</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3376,7 +3359,7 @@ fieldname(<replaceable>i</replaceable>) ...@@ -3376,7 +3359,7 @@ fieldname(<replaceable>i</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>ValueError</replaceable> <classname>ValueError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3386,7 +3369,7 @@ fieldname(<replaceable>i</replaceable>) ...@@ -3386,7 +3369,7 @@ fieldname(<replaceable>i</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3419,12 +3402,12 @@ fieldname(<replaceable>i</replaceable>) ...@@ -3419,12 +3402,12 @@ fieldname(<replaceable>i</replaceable>)
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>fieldnum</refname> <refname>fieldnum</refname>
<refpurpose>field name-number conversion</refpurpose> <refpurpose>get field number by name</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
fieldnum(<replaceable>name</replaceable>) fieldnum(<parameter>name</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-1"> <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-1">
...@@ -3432,7 +3415,7 @@ fieldnum(<replaceable>name</replaceable>) ...@@ -3432,7 +3415,7 @@ fieldnum(<replaceable>name</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>name</replaceable> <parameter>name</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3464,7 +3447,7 @@ fieldnum(<replaceable>name</replaceable>) ...@@ -3464,7 +3447,7 @@ fieldnum(<replaceable>name</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3474,7 +3457,7 @@ fieldnum(<replaceable>name</replaceable>) ...@@ -3474,7 +3457,7 @@ fieldnum(<replaceable>name</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>ValueError</replaceable> <classname>ValueError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3484,7 +3467,7 @@ fieldnum(<replaceable>name</replaceable>) ...@@ -3484,7 +3467,7 @@ fieldnum(<replaceable>name</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3518,7 +3501,7 @@ fieldnum(<replaceable>name</replaceable>) ...@@ -3518,7 +3501,7 @@ fieldnum(<replaceable>name</replaceable>)
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>ntuples</refname> <refname>ntuples</refname>
<refpurpose>returns the number of tuples in query object</refpurpose> <refpurpose>return the number of tuples in query object</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
...@@ -3554,7 +3537,7 @@ ntuples() ...@@ -3554,7 +3537,7 @@ ntuples()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>SyntaxError</errorname> <classname>SyntaxError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3585,7 +3568,7 @@ ntuples() ...@@ -3585,7 +3568,7 @@ ntuples()
<para> <para>
This object handles all the request concerning a This object handles all the request concerning a
<productname>PostgreSQL</productname> large object. It embeds and <productname>PostgreSQL</productname> large object. It embeds and
hides all the <quote>recurrent</quote> variables (object oid and hides all the <quote>recurrent</quote> variables (object OID and
connection), exactly in the same way connection), exactly in the same way
<classname>pgobject</classname>s do, thus only keeping significant <classname>pgobject</classname>s do, thus only keeping significant
parameters in function calls. It keeps a reference to the <classname>pgobject</classname> parameters in function calls. It keeps a reference to the <classname>pgobject</classname>
...@@ -3608,16 +3591,16 @@ ntuples() ...@@ -3608,16 +3591,16 @@ ntuples()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>oid</term> <term><structfield>oid</></term>
<listitem> <listitem>
<para> <para>
the oid associated with the object the OID associated with the object
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>pgcnx</term> <term><structfield>pgcnx</></term>
<listitem> <listitem>
<para> <para>
the <classname>pgobject</classname> associated with the object the <classname>pgobject</classname> associated with the object
...@@ -3626,7 +3609,7 @@ ntuples() ...@@ -3626,7 +3609,7 @@ ntuples()
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>error</term> <term><structfield>error</></term>
<listitem> <listitem>
<para> <para>
the last warning/error message of the connection the last warning/error message of the connection
...@@ -3635,20 +3618,19 @@ ntuples() ...@@ -3635,20 +3618,19 @@ ntuples()
</varlistentry> </varlistentry>
</variablelist> </variablelist>
<note> <important>
<title>Be careful</title>
<para> <para>
In multithreaded environments, <structfield>error</structfield> In multithreaded environments, <structfield>error</structfield>
may be modified by another thread using the same may be modified by another thread using the same
<classname>pgobject</classname>. Remember these object are <classname>pgobject</classname>. Remember that these object are
shared, not duplicated; you should provide some locking to be shared, not duplicated; you should provide some locking if you
able if you want to check this. The oid attribute is very want to check for the error message in this situation. The OID
interesting because it allow you reuse the oid later, creating attribute is very interesting because it allow you to reuse the
the <classname>pglarge</classname> object with a <classname>pgobject</classname> OID later, creating the <classname>pglarge</classname> object
with a <classname>pgobject</classname>
<function>getlo()</function> method call. <function>getlo()</function> method call.
</para> </para>
</note> </important>
</para> </para>
<para> <para>
...@@ -3665,12 +3647,12 @@ ntuples() ...@@ -3665,12 +3647,12 @@ ntuples()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>open</refname> <refname>open</refname>
<refpurpose>opens a large object</refpurpose> <refpurpose>open a large object</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
open(<replaceable>mode</replaceable>) open(<parameter>mode</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-1"> <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-1">
...@@ -3678,7 +3660,7 @@ open(<replaceable>mode</replaceable>) ...@@ -3678,7 +3660,7 @@ open(<replaceable>mode</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>mode</replaceable> <parameter>mode</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3701,7 +3683,7 @@ open(<replaceable>mode</replaceable>) ...@@ -3701,7 +3683,7 @@ open(<replaceable>mode</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3711,7 +3693,7 @@ open(<replaceable>mode</replaceable>) ...@@ -3711,7 +3693,7 @@ open(<replaceable>mode</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>IOError</errorname> <classname>IOError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3721,7 +3703,7 @@ open(<replaceable>mode</replaceable>) ...@@ -3721,7 +3703,7 @@ open(<replaceable>mode</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3738,9 +3720,9 @@ open(<replaceable>mode</replaceable>) ...@@ -3738,9 +3720,9 @@ open(<replaceable>mode</replaceable>)
<title>Description</title> <title>Description</title>
<para> <para>
<function>open()</function> method opens a large object for reading/writing, <function>open()</function> method opens a large object for reading/writing,
in the same way than the <acronym>UNIX</acronym> <function>open()</function> in the same way than the Unix <function>open()</function>
function. The mode value can be obtained by OR-ing the constants defined in function. The mode value can be obtained by OR-ing the constants defined in
the pg module (<literal>INV_READ, INV_WRITE</literal>). the pg module (<literal>INV_READ</literal>, <literal>INV_WRITE</literal>).
</para> </para>
</refsect1> </refsect1>
...@@ -3755,7 +3737,7 @@ open(<replaceable>mode</replaceable>) ...@@ -3755,7 +3737,7 @@ open(<replaceable>mode</replaceable>)
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>close</refname> <refname>close</refname>
<refpurpose>closes the large object</refpurpose> <refpurpose>close the large object</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
...@@ -3782,7 +3764,7 @@ close() ...@@ -3782,7 +3764,7 @@ close()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>SyntaxError</errorname> <classname>SyntaxError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3792,7 +3774,7 @@ close() ...@@ -3792,7 +3774,7 @@ close()
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>IOError</errorname> <classname>IOError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3802,7 +3784,7 @@ close() ...@@ -3802,7 +3784,7 @@ close()
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3819,7 +3801,7 @@ close() ...@@ -3819,7 +3801,7 @@ close()
<title>Description</title> <title>Description</title>
<para> <para>
<function>close()</function> method closes previously opened large object, <function>close()</function> method closes previously opened large object,
in the same way than the <acronym>UNIX</acronym> <function>close()</function> function. in the same way than the Unix <function>close()</function> function.
</para> </para>
</refsect1> </refsect1>
...@@ -3834,12 +3816,12 @@ close() ...@@ -3834,12 +3816,12 @@ close()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>read</refname> <refname>read</refname>
<refpurpose>reads from the large object</refpurpose> <refpurpose>read from the large object</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
read(<replaceable>size</replaceable>) read(<parameter>size</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-1"> <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-1">
...@@ -3847,7 +3829,7 @@ read(<replaceable>size</replaceable>) ...@@ -3847,7 +3829,7 @@ read(<replaceable>size</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>size</replaceable> <parameter>size</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3879,7 +3861,7 @@ read(<replaceable>size</replaceable>) ...@@ -3879,7 +3861,7 @@ read(<replaceable>size</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3889,7 +3871,7 @@ read(<replaceable>size</replaceable>) ...@@ -3889,7 +3871,7 @@ read(<replaceable>size</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>IOError</errorname> <classname>IOError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3899,7 +3881,7 @@ read(<replaceable>size</replaceable>) ...@@ -3899,7 +3881,7 @@ read(<replaceable>size</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3931,12 +3913,12 @@ read(<replaceable>size</replaceable>) ...@@ -3931,12 +3913,12 @@ read(<replaceable>size</replaceable>)
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>write</refname> <refname>write</refname>
<refpurpose>writes to the large object</refpurpose> <refpurpose>write to the large object</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
write(<replaceable>string</replaceable>) write(<parameter>string</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-1"> <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-1">
...@@ -3944,7 +3926,7 @@ write(<replaceable>string</replaceable>) ...@@ -3944,7 +3926,7 @@ write(<replaceable>string</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>string</replaceable> <parameter>string</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3967,7 +3949,7 @@ write(<replaceable>string</replaceable>) ...@@ -3967,7 +3949,7 @@ write(<replaceable>string</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3977,7 +3959,7 @@ write(<replaceable>string</replaceable>) ...@@ -3977,7 +3959,7 @@ write(<replaceable>string</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>IOError</errorname> <classname>IOError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -3987,7 +3969,7 @@ write(<replaceable>string</replaceable>) ...@@ -3987,7 +3969,7 @@ write(<replaceable>string</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4024,7 +4006,7 @@ write(<replaceable>string</replaceable>) ...@@ -4024,7 +4006,7 @@ write(<replaceable>string</replaceable>)
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) seek(<parameter>offset</parameter>, <parameter>whence</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-1"> <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-1">
...@@ -4032,7 +4014,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) ...@@ -4032,7 +4014,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>offset</replaceable> <parameter>offset</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4042,7 +4024,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) ...@@ -4042,7 +4024,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>whence</replaceable> <parameter>whence</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4074,7 +4056,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) ...@@ -4074,7 +4056,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4084,7 +4066,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) ...@@ -4084,7 +4066,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>IOError</errorname> <classname>IOError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4094,7 +4076,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) ...@@ -4094,7 +4076,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4112,7 +4094,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) ...@@ -4112,7 +4094,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>)
<para> <para>
<function>seek()</function> method allows to move the cursor position <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 in the large object. The whence parameter can be obtained by OR-ing the constants defined in the
<literal>pg</literal> module (<literal>SEEK_SET, SEEK_CUR, SEEK_END</literal>). <literal>pg</literal> module (<literal>SEEK_SET</>, <>SEEK_CUR</>, <>SEEK_END</literal>).
</para> </para>
</refsect1> </refsect1>
...@@ -4127,7 +4109,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) ...@@ -4127,7 +4109,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>)
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>tell</refname> <refname>tell</refname>
<refpurpose>returns current position in the large object</refpurpose> <refpurpose>return current position in the large object</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
...@@ -4163,7 +4145,7 @@ tell() ...@@ -4163,7 +4145,7 @@ tell()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>SyntaxError</errorname> <classname>SyntaxError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4173,7 +4155,7 @@ tell() ...@@ -4173,7 +4155,7 @@ tell()
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>IOError</errorname> <classname>IOError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4183,7 +4165,7 @@ tell() ...@@ -4183,7 +4165,7 @@ tell()
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4214,7 +4196,7 @@ tell() ...@@ -4214,7 +4196,7 @@ tell()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>unlink</refname> <refname>unlink</refname>
<refpurpose>deletes the large object</refpurpose> <refpurpose>delete the large object</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
...@@ -4241,7 +4223,7 @@ unlink() ...@@ -4241,7 +4223,7 @@ unlink()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>SyntaxError</errorname> <classname>SyntaxError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4251,7 +4233,7 @@ unlink() ...@@ -4251,7 +4233,7 @@ unlink()
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>IOError</errorname> <classname>IOError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4261,7 +4243,7 @@ unlink() ...@@ -4261,7 +4243,7 @@ unlink()
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4292,7 +4274,7 @@ unlink() ...@@ -4292,7 +4274,7 @@ unlink()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>size</refname> <refname>size</refname>
<refpurpose>gives the large object size</refpurpose> <refpurpose>return the large object size</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
...@@ -4328,7 +4310,7 @@ size() ...@@ -4328,7 +4310,7 @@ size()
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>SyntaxError</errorname> <classname>SyntaxError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4338,7 +4320,7 @@ size() ...@@ -4338,7 +4320,7 @@ size()
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>IOError</errorname> <classname>IOError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4348,7 +4330,7 @@ size() ...@@ -4348,7 +4330,7 @@ size()
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4366,8 +4348,8 @@ size() ...@@ -4366,8 +4348,8 @@ size()
<para> <para>
<function>size()</function> method allows to get the size of <function>size()</function> method allows to get the size of
the large object. It was implemented because this function the large object. It was implemented because this function
is very useful for a WWW interfaced database. is very useful for a WWW-interfaced database.
Currently the large object needs to be opened. Currently, the large object needs to be opened first.
</para> </para>
</refsect1> </refsect1>
...@@ -4382,12 +4364,12 @@ size() ...@@ -4382,12 +4364,12 @@ size()
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>export</refname> <refname>export</refname>
<refpurpose>saves the large object to file</refpurpose> <refpurpose>save the large object to file</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
export(<replaceable>filename</replaceable>) export(<parameter>filename</parameter>)
</synopsis> </synopsis>
<refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-1"> <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-1">
...@@ -4395,7 +4377,7 @@ export(<replaceable>filename</replaceable>) ...@@ -4395,7 +4377,7 @@ export(<replaceable>filename</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>filename</replaceable> <parameter>filename</parameter>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4418,7 +4400,7 @@ export(<replaceable>filename</replaceable>) ...@@ -4418,7 +4400,7 @@ export(<replaceable>filename</replaceable>)
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<errorname>TypeError</errorname> <classname>TypeError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4428,7 +4410,7 @@ export(<replaceable>filename</replaceable>) ...@@ -4428,7 +4410,7 @@ export(<replaceable>filename</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>IOError</errorname> <classname>IOError</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4438,7 +4420,7 @@ export(<replaceable>filename</replaceable>) ...@@ -4438,7 +4420,7 @@ export(<replaceable>filename</replaceable>)
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<errorname>pg.error</errorname> <classname>pg.error</classname>
</term> </term>
<listitem> <listitem>
<para> <para>
...@@ -4465,20 +4447,4 @@ export(<replaceable>filename</replaceable>) ...@@ -4465,20 +4447,4 @@ export(<replaceable>filename</replaceable>)
</sect1> </sect1>
<sect1 id="pygresql-db-api">
<title><acronym>DB-API</acronym> Interface</title>
<comment>
This section needs to be written.
</comment>
<para>
See <ulink
url="http://www.python.org/topics/database/DatabaseAPI-2.0.html"
>http://www.python.org/topics/database/DatabaseAPI-2.0.html</ulink>
for a description of the <acronym>DB-API</acronym> 2.0.
</para>
</sect1>
</chapter> </chapter>
src/interfaces/python/README
View file @ 0d3be98a
...@@ -63,8 +63,7 @@ PyGreSQL 2.0 was developed and tested on a NetBSD 1.3_BETA system. It is ...@@ -63,8 +63,7 @@ PyGreSQL 2.0 was developed and tested on a NetBSD 1.3_BETA system. It is
based on the PyGres95 code written by Pascal Andre, andre@chimay.via.ecp.fr. based on the PyGres95 code written by Pascal Andre, andre@chimay.via.ecp.fr.
I changed the version to 2.0 and updated the code for Python 1.5 and I changed the version to 2.0 and updated the code for Python 1.5 and
PostgreSQL 6.2.1. While I was at it I upgraded the code to use full ANSI PostgreSQL 6.2.1. While I was at it I upgraded the code to use full ANSI
style prototypes and changed the order of arguments to connect. The latest style prototypes and changed the order of arguments to connect.
version of PyGreSQL works with PostgreSQL 7.1.3 and Python 2.1.
1.2. Distribution files 1.2. Distribution files
...@@ -92,8 +91,7 @@ version of PyGreSQL works with PostgreSQL 7.1.3 and Python 2.1. ...@@ -92,8 +91,7 @@ version of PyGreSQL works with PostgreSQL 7.1.3 and Python 2.1.
you must already have built Python as well as the mxDateTime package you must already have built Python as well as the mxDateTime package
from http://starship.python.net/~lemburg/mxDateTime.html. from http://starship.python.net/~lemburg/mxDateTime.html.
* For Linux installation look at README.linux. If you're on an x86 system * For a Linux x86 system that uses RPMs, you can pick up an RPM at
that uses RPMs, then you can pick up an RPM at
ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm
* Note that if you are using the DB-API module you must also install * Note that if you are using the DB-API module you must also install
...@@ -238,844 +236,10 @@ For support: ...@@ -238,844 +236,10 @@ For support:
2. Programming information 2. Programming information
========================== ==========================
You may either choose to use the old, mature interface provided by the See main PostgreSQL documentation.
'pg' module or else the newer 'pgdb' interface compliant with DB-API 2.0
specification developed by the Python DB-SIG.
The remainder of this chapter and the next chapter describe only
the older 'pg' API. As long as PyGreSQL does not contain a
description of the DB-API you should read about the API at
http://www.python.org/topics/database/DatabaseAPI-2.0.html
A tutorial like introduction to the DB-API can be found at 3. Todo
http://www2.linuxjournal.com/lj-issues/issue49/2605.html
The 'pg' module defines three objects: the pgobject that handles the connection
and all the requests to the database, the pglargeobject that handles
all the accesses to Postgres large objects and pgqueryobject that handles
query results.
If you want to see a simple example of the use of some of these functions,
see http://www.druid.net/rides/ where I have a link at the bottom to the
actual Python code for the page.
2.1. pg module description
----------------------------
The module defines only a few methods that allow to connect to a database and
to allow to define "default variables" that override the environment variables
used by PostgreSQL.
These "default variables" were designed to allow you to handle general
connection parameters without heavy code in your programs. You can prompt the
user for a value, put it in the default variable, and forget it, without
having to modify your environment. The support for default variables can be
disabled by setting the -DNO_DEF_VAR option in the Python Setup file. Methods
relative to this are specified by te tag [DV].
All variables are set to None at module initialization, specifying that
standard environment variables should be used.
2.1.1. connect - opens a pg connection
----------------------------------------
Syntax:
connect(dbname, host, port, opt, tty, user, passwd)
Parameters:
dbname - name of connected database (string/None)
host - name of the server host (string/None)
port - port used by the database server (integer/-1)
opt - connection options (string/None)
tty - debug terminal (string/None)
user - PostgreSQL user (string/None)
passwd - password for user (string/None)
Return type:
pgobject - the object handling the connection
Exceptions raised:
TypeError - bad argument type, or too many arguments
SyntaxError - duplicate argument definition
pg.error - some error occurred during pg connection definition
(+ all exceptions relative to object allocation)
Description:
This method opens a connection to a specified database on a given
PostgreSQL server. You can use keywords here, as described in the
Python tutorial;
the names of the keywords are the name of the parameters given in the
syntax line. For a precise description of the parameters, please refer to
the PostgreSQL user manual.
2.1.2. get_defhost, set_defhost - default server host name handling [DV]
------------------------------------------------------------------------
Syntax: get_defhost()
Parameters:
none
Return type:
string, None - default host specification
Exceptions raised:
SyntaxError - too many arguments
Description:
This method returns the current default host specification, or None if the
environment variables should be used. Environment variables won't be looked
up.
Syntax: set_defhost(host)
Parameters:
host - new default host (string/None)
Return type:
string, None - previous default host specification
Exceptions raised:
TypeError - bad argument type, or too many arguments
Description:
This methods sets the default host value for new connections. If None is
supplied as parameter, environment variables will be used in future
connections. It returns the previous setting for default host.
2.1.3. get_defport, set_defport - default server port handling [DV]
-------------------------------------------------------------------
Syntax: get_defport()
Parameters: none
Return type:
integer, None - default port specification
Exceptions raised:
SyntaxError - too many arguments
Description:
This method returns the current default port specification, or None if
the environment variables should be used. Environment variables won't
be looked up.
Syntax: set_defport(port)
Parameters:
port - new default port (integer/-1)
Return type:
integer, None - previous default port specification
Description:
This methods 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.
2.1.4. get_defopt, set_defopt - default connection options handling [DV]
------------------------------------------------------------------------
Syntax: get_defopt()
Parameters: none
Return type:
string, None - default options specification
Exceptions raised:
SyntaxError - too many arguments
Description:
This method returns the current default connection options specification,
or None if the environment variables should be used. Environment variables
won't be looked up.
Syntax: set_defopt(options)
Parameters:
options - new default connection options (string/None)
Return type:
string, None - previous default options specification
Exceptions raised:
TypeError - bad argument type, or too many arguments
Description:
This methods sets the default connection options value for new connections.
If None is supplied as parameter, environment variables will be used in
future connections. It returns the previous setting for default options.
2.1.5. get_deftty, set_deftty - default connection debug tty handling [DV]
--------------------------------------------------------------------------
Syntax: get_deftty()
Parameters: none
Return type:
string, None - default debug terminal specification
Exceptions raised:
SyntaxError - too many arguments
Description:
This method returns the current default debug terminal specification, or
None if the environment variables should be used. Environment variables
won't be looked up.
Syntax: set_deftty(terminal)
Parameters:
terminal - new default debug terminal (string/None)
Return type:
string, None - previous default debug terminal specification
Exceptions raised:
TypeError - bad argument type, or too many arguments
Description:
This methods sets the default debug terminal value for new connections. If
None is supplied as parameter, environment variables will be used in future
connections. It returns the previous setting for default terminal.
2.1.6. get_defbase, set_defbase - default database name handling [DV]
---------------------------------------------------------------------
Syntax: get_defbase()
Parameters: none
Return type:
string, None - default database name specification
Exceptions raised:
SyntaxError - too many arguments
Description:
This method returns the current default database name specification, or
None if the environment variables should be used. Environment variables
won't be looked up.
Syntax: set_defbase(base)
Parameters:
base - new default base name (string/None)
Return type:
string, None - previous default database name specification
Exceptions raised:
TypeError - bad argument type, or too many arguments
Description:
This method sets the default database name value for new connections. If
None is supplied as parameter, environment variables will be used in
future connections. It returns the previous setting for default host.
2.1.7. Module constants
-----------------------
Some constants are defined in the module dictionary. They are intended to be
used as parameters for methods calls. You should refer to PostgreSQL user
manual for more information about them. These constants are:
- large objects access modes, used by (pgobject.)locreate and
(pglarge.)open: (pg.)INV_READ, (pg.)INV_WRITE
- positional flags, used by (pglarge.)seek: (pg.)SEEK_SET,
(pg.)SEEK_CUR, (pg.)SEEK_END.
- version and __version__ constants that give the current version.
2.1.9.
2.1.10. Miscellaneous attributes
The following methods return information about the current connection.
-
2.2. pgobject description
---------------------------
This object handle a connection to a PostgreSQL database. It embeds and
hides all the parameters that define this connection, thus just leaving really
significant parameters in function calls.
Some methods give direct access to the connection socket. They are specified
by the tag [DA]. DO NOT USE THEM UNLESS YOU REALLY KNOW WHAT YOU ARE DOING. If
you prefer disabling them, set the -DNO_DIRECT option in the Python Setup file.
Some other methods give access to large objects (refer to PostgreSQL user
manual for more information about these). if you want to forbid access to these
from the module, set the -DNO_LARGE option in the Python Setup file. These
methods are specified by the tag [LO].
2.2.1. query - executes a SQL command string
--------------------------------------------
Syntax: query(command)
Parameters:
command - SQL command (string)
Return type:
pgqueryobject, None - result values
Exceptions raised:
TypeError - bad argument type, or too many arguments.
ValueError - empty SQL query
pg.error - error during query processing, or invalid connection
Description:
This method simply sends a SQL query to the database. If the query is
an insert statement, the return value is the OID of the newly
inserted row. If it is otherwise a query that does not return a result
(ie. is not a some kind of SELECT statement), it returns None.
Otherwise, it returns a pgqueryobject that can be accessed via the
getresult or dictresult method or simply printed.
pgqueryobject methods
---------------------
2.2.1.1. getresult - gets the values returned by the query
-------------------------------------------------------------
Syntax: getresult()
Parameters: none
Return type:
list - result values
Exceptions raised:
SyntaxError - too many parameters
pg.error - invalid previous result
Description:
This method returns the list of the values returned by the query.
More information about this result may be accessed using listfields,
fieldname and fieldnum methods.
2.2.1.2. dictresult - like getresult but returns list of dictionaries
---------------------------------------------------------------------
Syntax: dictresult()
Parameters: none
Return type:
list - result values as a dictionary
Exceptions raised:
SyntaxError - too many parameters
pg.error - invalid previous result
Description:
This 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.
2.2.1.3. listfields - lists the fields names of the previous query result
-----------------------------------------------------------------------
Syntax: listfields()
Parameters: none
Return type:
list - fields names
Exceptions raised:
SyntaxError - too many parameters
pg.error - invalid previous result, or invalid connection
Description:
This method returns the list of names of the fields defined for the
query result. The fields are in the same order as the result values.
2.2.1.4. fieldname, fieldnum - field name-number conversion
---------------------------------------------------------
Syntax: fieldname(i)
Parameters:
i - field number (integer)
Return type:
string - field name
Exceptions raised:
TypeError - bad parameter type, or too many parameters
ValueError - invalid field number
pg.error - invalid previous result, or invalid connection
Description:
This 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 as the
result values.
Syntax: fieldnum(name)
Parameters:
name - field name (string)
Return type:
integer - field number
Exceptions raised:
TypeError - bad parameter type, or too many parameters
ValueError - unknown field name
pg.error - invalid previous result, or invalid connection
Description:
This 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.
2.2.1.5 ntuples - return number of tuples in query object
---------------------------------------------------------
Syntax: ntuples()
Parameters: None
Return type: integer
Description:
This method returns the number of tuples found in a query.
2.2.2. reset - resets the connection
------------------------------------
Syntax: reset()
Parameters: None
Return type: None
Exceptions raised:
TypeError - too many (any) arguments
Description:
This method resets the current database.
2.2.3. close - close the database connection
--------------------------------------------
Syntax: close()
Parameters: none
Return type: None
Exceptions raised:
TypeError - too many (any) arguments
Description:
This 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.
2.2.4. fileno - returns the socket used to connect to the database
------------------------------------------------------------------
Syntax: fileno()
Parameters: none
Exceptions raised:
TypeError - too many (any) arguments
Description:
This method returns the underlying socket id used to connect
to the database. This is useful for use in select calls, etc.
Note: This function depends on having a recent version of the
database. See "-DNO_PQSOCKET" described above.
2.2.5. getnotify - gets the last notify from the server
-------------------------------------------------------
Syntax: getnotify()
Parameters: none
Return type:
tuple, None - last notify from server
Exceptions raised:
SyntaxError - too many parameters
pg.error - invalid connection
Description:
This methods try to get a notify from the server (from the SQL statement
NOTIFY). If the server returns no notify, the methods returns None.
Otherwise, it returns a tuple (couple) (relname, pid), where relname is the
name of the notify and pid the process id of the connection that triggered
the notify. Remember to do a listen query first otherwise getnotify
will always return None.
2.2.6. inserttable - insert a list into a table
-----------------------------------------------
Syntax: inserttable(table, values)
Parameters:
table - the table name (string)
values - list of rows values (list)
Return type:
None
Exception raised:
pg.error - invalid connection
TypeError - bad argument type, or too many arguments
Description:
This method allow 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.
BE VERY CAREFUL: this method doesn't typecheck the fields according to the
table definition; it just look whether or not it knows how to handle such
types.
2.2.7. putline - writes a line to the server socket [DA]
--------------------------------------------------------
Syntax: putline(line)
Parameters:
line - line to be written (string)
Return type:
None
Exceptions raised:
pg.error - invalid connection
TypeError - bad parameter type, or too many parameters
Description:
This method allows to directly write a string to the server socket.
2.2.8. getline - gets a line from server socket [DA]
----------------------------------------------------
Syntax: getline()
Parameters: none
Return type:
string - the line read
Exceptions raised:
pg.error - invalid connection
SyntaxError - too many parameters
Description:
This method allows to directly read a string from the server socket.
2.2.9. endcopy - synchronizes client and server [DA]
----------------------------------------------------
Syntax: endcopy()
Parameters: none
Return type:
None
Exceptions raised:
pg.error - invalid connection
SyntaxError - too many parameters
Description:
The use of direct access methods may desynchonize client and server. This
method ensure that client and server will be synchronized.
2.2.10. locreate - creates of large object in the database [LO]
---------------------------------------------------------------
Syntax: locreate(mode)
Parameters:
mode - large object create mode
Return type:
pglarge - object handling the postgres large object
Exceptions raised:
pg.error - invalid connection, or creation error
TypeError - bad parameter type, or too many parameters
Description:
This method creates a large object in the database. The mode can be defined
by OR-ing the constants defined in the pg module (INV_READ, INV_WRITE and
INV_ARCHIVE). Please refer to PostgreSQL user manual for a description of
the mode values.
2.2.11. getlo - builds a large object from given oid [LO]
---------------------------------------------------------
Syntax: getlo(oid)
Parameters:
oid - oid of the existing large object (integer)
Return type:
pglarge - object handling the postgres large object
Exceptions raised:
pg.error - invalid connection
TypeError - bad parameter type, or too many parameters
ValueError - bad oid value (0 is invalid_oid)
Description:
This method allows to reuse a formerly created large object through the
pglarge interface, providing the user have its oid.
2.2.12. loimport - import a file to a postgres large object [LO]
----------------------------------------------------------------
Syntax: loimport(name)
Parameters:
name - the name of the file to be imported (string)
Return type:
pglarge - object handling the postgres large object
Exceptions raised:
pg.error - invalid connection, or error during file import
TypeError - bad argument type, or too many arguments
Description:
This methods allows to create large objects in a very simple way. You just
give the name of a file containing the data to be use.
2.2.13. pgobject attributes
-----------------------------
Every pgobject defines a set of read-only attributes that describe the
connection and its status. These attributes are:
host - the hostname of the server (string)
port - the port of the server (integer)
db - the selected database (string)
options - the connection options (string)
tty - the connection debug terminal (string)
user - the username on the database system (string)
status - the status of the connection (integer: 1 - OK, 0 - BAD)
error - the last warning/error message from the server (string)
2.3. pglarge description
--------------------------
This object handles all the request concerning a postgres large object. It
embeds and hides all the 'recurrent' variables (object oid and connection),
exactly in the same way pgobjects do, thus only keeping significant
parameters in function calls. It keeps a reference to the pgobject used for
its creation, sending requests though with its parameters. Any modification but
dereferencing the pgobject will thus affect the pglarge object.
Dereferencing the initial pgobject is not a problem since Python won't
deallocate it before the large object dereference it.
All functions return a generic error message on call error, whatever the
exact error was. The 'error' attribute of the object allow to get the exact
error message.
2.3.1. open - opens a large object
----------------------------------
Syntax: open(mode)
Parameters:
mode - open mode definition (integer)
Return type:
None
Exceptions raised:
pg.error - invalid connection
TypeError - bad parameter type, or too many parameters
IOError - already opened object, or open error
Description:
This method opens a large object for reading/writing, in the same way than
the UNIX open() function. The mode value can be obtained by OR-ing the
constants defined in the pgmodule (INV_READ, INV_WRITE).
2.3.2. close - closes a large object
------------------------------------
Syntax: close()
Parameters: none
Return type:
None
Exceptions raised:
pg.error - invalid connection
SyntaxError - too many parameters
IOError - object is not opened, or close error
Description:
This method closes a previously opened large object, in the same way than
the UNIX close() function.
2.3.4. read, write, tell, seek, unlink - file like large object handling
------------------------------------------------------------------------
Syntax: read(size)
Parameters:
size - maximal size of the buffer to be read
Return type:
sized string - the read buffer
Exceptions raised:
pg.error - invalid connection or invalid object
TypeError - bad parameter type, or too many parameters
IOError - object is not opened, or read error
Description:
This function allows to read data from a large object, starting at current
position.
Syntax: write(string)
Parameters:
(sized) string - buffer to be written
Return type:
None
Exceptions raised:
pg.error - invalid connection or invalid object
TypeError - bad parameter type, or too many parameters
IOError - object is not opened, or write error
Description:
This function allows to write data to a large object, starting at current
position.
Syntax: seek(offset, whence)
Parameters:
offset - position offset
whence - positional parameter
Return type:
integer - new position in object
Exception raised:
pg.error - invalid connection or invalid object
TypeError - bad parameter type, or too many parameters
IOError - object is not opened, or seek error
Description:
This method allows to move the position cursor in the large object. The
whence parameter can be obtained by OR-ing the constants defined in the
pg module (SEEK_SET, SEEK_CUR, SEEK_END).
Syntax: tell()
Parameters: none
Return type:
integer - current position in large object
Exception raised:
pg.error - invalid connection or invalid object
SyntaxError - too many parameters
IOError - object is not opened, or seek error
Description:
This method allows to get the current position in the large object.
Syntax: unlink()
Parameter: none
Return type:
None
Exception raised:
pg.error - invalid connection or invalid object
SyntaxError - too many parameters
IOError - object is not closed, or unlink error
Description:
This methods unlinks (deletes) the postgres large object.
2.3.5. size - gives the large object size
-----------------------------------------
Syntax: size()
Parameters: none
Return type:
integer - large object size
Exceptions raised:
pg.error - invalid connection or invalid object
SyntaxError - too many parameters
IOError - object is not opened, or seek/tell error
Description:
This (composite) method allows to get the size of a large object. Currently
the large object needs to be opened. It was implemented because this
function is very useful for a WWW interfaced database.
2.3.6. export - saves a large object to a file
----------------------------------------------
Syntax: export(name)
Parameters:
name - file to be created
Return type:
None
Exception raised:
pg.error - invalid connection or invalid object
TypeError - bad parameter type, or too many parameters
IOError - object is not closed, or export error
Description:
This methods 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.
2.3.7. Object attributes
------------------------
pglarge objects define a read-only set of attributes that allow to get some
information about it. These attributes are:
oid - the oid associated with the object
pgcnx - the pgobject associated with the object
error - the last warning/error message of the connection
BE CAREFUL: in multithreaded environments, 'error' may be modified by another
thread using the same pgobject. Remember these object are shared, not
duplicated. You should provide some locking to be able if you want to check
this.
The oid attribute is very interesting because it allow you reuse the oid
later, creating the pglarge object with a pgobject getlo() method call.
3. The pg wrapper
================
The previous functions are wrapped in a module called pg. The module
has a class called DB. The above functions are also included in the
name space so it isn't necessary to import both modules. The preferred
way to use this module is as follows.
import pg
db = pg.DB(...) # See description of the initialization method below.
The following describes the methods and variables of this class.
3.1. Initialization
-------------------
The DB class is initialized with the same arguments as the connect
method described in section 2. It also initializes a few internal
variables. The statement 'db = DB()' will open the local database
with the name of the user just like connect() does.
3.2. pkey
---------
Syntax:
pkey(table)
Parameters:
table - name of table
Returns:
Name of field which is the primary key of the table.
Description:
This method returns the primary key of a table. Note that this raises
an exception if the table doesn't have a primary key.
3.3. get_databases - get list of databases in the system
--------------------------------------------------------
Syntax: get_databases()
Parameters: none
Returns: list of databases in the system
Description:
Although you can do this with a simple select, it is added here for
convenience
3.4. get_tables - get list of tables in connected database
----------------------------------------------------------
Syntax: get_tables()
Parameters: none
Returns: list of tables in connected database
3.5. get_attnames
-----------------
Syntax:
get_attnames(table)
Parameters:
table - name of table
Returns:
Dictionary of attribute names (the names are the keys, the values
are the names of the attributes' types)
Description:
Given the name of a table, digs out the set of attribute names.
3.6. get - get a tuple from a database table
--------------------------------------------
Syntax:
get(table, arg, [keyname])
Parameters:
table - name of table
arg - either a dictionary or the value to be looked up
keyname - name of field to use as key (optional)
Returns:
A dictionary mapping attribute names to row values.
Description:
This method is the basic mechanism to get a single row. It assumes
that the key specifies a unique row. If keyname is not specified
then the primary key for the table is used. If arg is a dictionary
then the value for the key is taken from it and it is modified to
include the new values, replacing existing values where necessary.
The oid is also put into the dictionary but in order to allow the
caller to work with multiple tables, the attribute name is munged
to make it unique. It consists of the string "oid_" followed by
the name of the table.
3.7. insert - insert a tuple into a database table
--------------------------------------------------
Syntax:
insert(table, a)
Parameters:
table - name of table
a - a dictionary of values
Returns:
The OID of the newly inserted row.
Description:
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.
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.
3.8. update
-----------
Syntax:
update(table, a)
Parameters:
table - name of table
a - a dictionary of values
Returns:
A dictionary with the new row
Description:
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.
3.9. clear
----------
Syntax:
clear(table, [a])
Parameters:
table - name of table
a - a dictionary of values
Returns:
A dictionary with an empty row
Description:
This method clears all the attributes to values determined by the types.
Numeric types are set to 0, dates are set to 'TODAY' 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.
3.8. delete
-----------
Syntax:
delete(table, a)
Parameters:
table - name of table
a - a dictionary of values
Returns:
None
Description:
This method deletes the row from a table. It deletes based on the OID
as munged as described above.
4. DB-API reference
===================
This section needs to be written.
5. Todo
======= =======
The large object and direct access functions need much more attention. The large object and direct access functions need much more attention.
...@@ -1089,7 +253,7 @@ The DB-API module needs to be documented. ...@@ -1089,7 +253,7 @@ The DB-API module needs to be documented.
The fetch method should use real cursors. The fetch method should use real cursors.
6. Future directions 4. Future directions
==================== ====================
Users should be able to register their own types with _pg. Users should be able to register their own types with _pg.
......
src/interfaces/python/README.linux deleted 100644 → 0
View file @ 5fa34183
Thanks to thilo@eevolute.com and others for this README and the RPM
Note: The precompiled RPM package is not available at www.eevolute.com.
You may use the spec file provided with PyGreSQL to build your
own package.
Hartmut Goebel <hartmut@goebel.noris.de>
INSTALLING PyGreSQL on Redhat Linux 5.1 or 5.2
==============================================
Things are pretty easy on Redhat Linux. You can either get a precompiled
RPM package from
ftp://www.eevolute.com/pub/python/
or try in compile and install it yourself:
bash$ make redhat # this just compiles the module as a shared object
cc -fpic -shared -o _pg.so -I/usr/include/python1.5 pgmodule.c -lpq
bash$ python # you can test it from your local directory
Python 1.5.1 (#1, May 6 1998, 01:48:27) [GCC 2.7.2.3] on linux-i386
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>> import _pg
>>> db = _pg.connect('thilo', 'localhost')
>>> db.query("INSERT INTO test VALUES ('ping', 'pong')")
18304
>>> db.query("SELECT * FROM test")
eins|zwei
----+----
ping|pong
(1 row)
bash$ su # Yow! Seems to work - now install it properly
bash# cp _pg.so /usr/lib/python1.5/lib-dynload
done!
Oliver White (ojw@muzak.iinet.net.au) sent me the following information
about installing on Debian.
Hi, I thought you might want to upgrade your documentation for PyGreSQL
to let people know they can get it by simply typing 'apt-get install
python-pygresql', on debian (duh). This would have saved me a lot of
trouble.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment