diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/pygresql.sgml | 812 |
1 files changed, 389 insertions, 423 deletions
diff --git a/doc/src/sgml/pygresql.sgml b/doc/src/sgml/pygresql.sgml index 540379029dc..e739e3d5e06 100644 --- a/doc/src/sgml/pygresql.sgml +++ b/doc/src/sgml/pygresql.sgml @@ -1,4 +1,4 @@ -<!-- $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"> <title><application>PyGreSQL</application> - <application>Python</application> Interface</title> @@ -22,32 +22,8 @@ <itemizedlist> <listitem> <para> - If you are on <acronym>NetBSD</acronym>, look in the packages - directory under databases. If it isn't there yet, it should be - there shortly. You can also pick up the package files from - <ulink url="ftp://ftp.druid.net/pub/distrib/pygresql.pkg.tgz" - >ftp://ftp.druid.net/pub/distrib/pygresql.pkg.tgz</ulink>. There - is also a package in the <acronym>FreeBSD</acronym> ports - collection but as I write this it is at version 2.1. I will try - to get that updated as well. - </para> - </listitem> - - <listitem> - <para> - For Linux installation look at <filename>README.linux</filename>. - If you're on an <acronym>x86</acronym> system that uses - <acronym>RPMs</acronym>, then you can pick up an - <acronym>RPM</acronym> at <ulink - url="ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm" - >ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm</ulink>. - </para> - </listitem> - - <listitem> - <para> Note that if you are using the <acronym>DB-API</acronym> module - you must also install <acronym>mxDateTime</acronym> from <ulink + you must also install <literal>mxDateTime</literal> from <ulink url="http://starship.python.net/~lemburg/mxDateTime.html" >http://starship.python.net/~lemburg/mxDateTime.html</ulink>. </para> @@ -56,16 +32,15 @@ <listitem> <para> 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> </listitem> - </itemizedlist> <para> You have two options. You can compile - <productname>PyGreSQL</productname> as a stand-alone module or you - can build it into the <productname>Python</productname> + <application>PyGreSQL</application> as a stand-alone module or you + can build it into the <application>Python</application> interpreter. </para> @@ -75,27 +50,27 @@ <itemizedlist> <listitem> <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 header files and developer's libraries for both - <productname>Python</productname> and + <application>Python</application> and <productname>PostgreSQL</productname> must be installed on your - system before you can build <productname>PyGreSQL</productname>. - If you built both <productname>Python</productname> and + system before you can build <application>PyGreSQL</application>. + If you built both <application>Python</application> and <productname>PostgreSQL</productname> from source, you should be fine. If your system uses some package mechanism (such as - <acronym>RPM</acronym> or <acronym>NetBSD</acronym> packages), + <acronym>RPM</acronym> or <systemitem class="osname">NetBSD</systemitem> packages), then you probably need to install packages such as - <acronym>Python-devel</acronym> in addition to the - <productname>Python</productname> package. + <application>Python-devel</application> in addition to the + <application>Python</application> package. </para> </listitem> <listitem> <para> - <productname>PyGreSQL</productname> is implemented as three - parts, a C module labeled <acronym>_pg</acronym> and two - <productname>Python</productname> wrappers called + <application>PyGreSQL</application> is implemented as three + parts, a C module labeled <literal>_pg</literal> and two + <application>Python</application> wrappers called <filename>pg.py</filename> and <filename>pgdb.py</filename>. This changed between 2.1 and 2.2 and again in 3.0. These changes should not affect any existing programs but the @@ -105,7 +80,7 @@ <listitem> <para> - Download and unpack the <productname>PyGreSQL</productname> + Download and unpack the <application>PyGreSQL</application> tarball if you haven't already done so. </para> </listitem> @@ -129,7 +104,7 @@ cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c <itemizedlist> <listitem> <para> - [pyInc] = path of the <productname>Python</productname> + [pyInc] = path of the <application>Python</application> include (usually <filename>Python.h</filename>) </para> </listitem> @@ -154,43 +129,43 @@ cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c <itemizedlist> <listitem> <para> - <literal>-DNO_DEF_VAR</literal> - no default variables + <option>-DNO_DEF_VAR</option> - no default variables support </para> </listitem> <listitem> <para> - <literal>-DNO_DIRECT</literal> - no direct access methods + <option>-DNO_DIRECT</option> - no direct access methods </para> </listitem> <listitem> <para> - <literal>-DNO_LARGE</literal> - no large object support + <option>-DNO_LARGE</option> - no large object support </para> </listitem> <listitem> <para> - <literal>-DNO_SNPRINTF</literal> - if running a system with + <option>-DNO_SNPRINTF</option> - if running a system with no snprintf call </para> </listitem> <listitem> <para> - <literal>-DNO_PQSOCKET</literal> - if running an older + <option>-DNO_PQSOCKET</option> - if running an older <productname>PostgreSQL</productname> </para> </listitem> </itemizedlist> On some systems you may need to include - <literal>-lcrypt</literal> in the list of libraries to make it + <option>-lcrypt</option> in the list of libraries to make it 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 does not have the <function>PQsocket</function> function. The 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 <para> Finally, move the <filename>_pg.so</filename>, <filename>pg.py</filename>, and <filename>pgdb.py</filename> - to a directory in your <literal>PYTHONPATH</literal>. + to a directory in your <envar>PYTHONPATH</envar>. A good place would be <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>. </para> </listitem> @@ -238,16 +213,16 @@ cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c <para> Find the directory where your <filename>Setup</filename> 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. </para> </listitem> <listitem> <para> - Add the following line to your Setup file - <ProgramListing> + Add the following line to your <filename>Setup</> file +<programlisting> _pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems - </ProgramListing> +</programlisting> where: <itemizedlist> <listitem> @@ -268,35 +243,35 @@ _pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems <itemizedlist> <listitem> <para> - <literal>-DNO_DEF_VAR</literal> - no default variables + <option>-DNO_DEF_VAR</option> - no default variables support </para> </listitem> <listitem> <para> - <literal>-DNO_DIRECT</literal> - no direct access methods + <option>-DNO_DIRECT</option> - no direct access methods </para> </listitem> <listitem> <para> - <literal>-DNO_LARGE</literal> - no large object support + <option>-DNO_LARGE</option> - no large object support </para> </listitem> <listitem> <para> - <literal>-DNO_SNPRINTF</literal> - if running a system with + <option>-DNO_SNPRINTF</option> - if running a system with no snprintf call </para> </listitem> <listitem> <para> - <literal>-DNO_PQSOCKET</literal> - if running an older + <option>-DNO_PQSOCKET</option> - if running an older <productname>PostgreSQL</productname> </para> </listitem> </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 that does not have the <function>PQsocket</function> function. 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 <listitem> <para> 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 your shared modules with <literal>make sharedinstall</> but this no longer seems to be true. @@ -320,13 +295,13 @@ _pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems </listitem> <listitem> <para> - Rebuild <productname>Python</productname> from the root - directory of the <productname>Python</productname> source + Rebuild <application>Python</application> from the root + directory of the <application>Python</application> source hierarchy by running - <ProgramListing> +<programlisting> make -f Makefile.pre.in boot make && make install - </ProgramListing> +</programlisting> </para> </listitem> <listitem> @@ -342,36 +317,36 @@ make && make install ]]> + <para> + You may either choose to use the old mature interface provided by + the <literal>pg</literal> module or otherwise the newer + <literal>pgdb</literal> interface compliant with the <ulink + url="http://www.python.org/topics/database/DatabaseAPI-2.0.html" + ><acronym>DB-API 2.0</acronym></ulink> specification developed by + the <application>Python</application> <acronym>DB-SIG</acronym>. + </para> + + <para> + Here we describe only the older <literal>pg</literal> + <acronym>API</acronym>. As long as + <application>PyGreSQL</application> does not contain a description + of the <acronym>DB-API</acronym> you should read about the + <acronym>API</acronym> at <ulink + url="http://www.python.org/topics/database/DatabaseAPI-2.0.html" + >http://www.python.org/topics/database/DatabaseAPI-2.0.html</ulink>. + </para> + + <para> + A tutorial-like introduction to the <acronym>DB-API</acronym> can be + found at <ulink + url="http://www2.linuxjournal.com/lj-issues/issue49/2605.html" + >http://www2.linuxjournal.com/lj-issues/issue49/2605.html</ulink> + </para> + <sect1 id="pygresql-pg"> <title>The <literal>pg</literal> Module</title> <para> - You may either choose to use the old mature interface provided by - the <literal>pg</literal> module or otherwise the newer - <literal>pgdb</literal> interface compliant with the <ulink - url="http://www.python.org/topics/database/DatabaseAPI-2.0.html" - ><acronym>DB-API 2.0</acronym></ulink> specification developed by - the <productname>Python</productname> <acronym>DB-SIG</acronym>. - </para> - - <para> - Here we describe only the older <literal>pg</literal> - <acronym>API</acronym>. As long as - <productname>PyGreSQL</productname> does not contain a description - of the <acronym>DB-API</acronym> you should read about the - <acronym>API</acronym> at <ulink - url="http://www.python.org/topics/database/DatabaseAPI-2.0.html" - >http://www.python.org/topics/database/DatabaseAPI-2.0.html</ulink>. - </para> - - <para> - A tutorial-like introduction to the <acronym>DB-API</acronym> can - be found at <ulink - url="http://www2.linuxjournal.com/lj-issues/issue49/2605.html" - >http://www2.linuxjournal.com/lj-issues/issue49/2605.html</ulink> - </para> - - <para> The <literal>pg</literal> module defines three objects: <itemizedlist> <listitem> @@ -390,7 +365,7 @@ make && make install <listitem> <para> - <literal>pgqueryobject</literal> that handles query results. + <classname>pgqueryobject</classname> that handles query results. </para> </listitem> </itemizedlist> @@ -399,8 +374,8 @@ make && make install <para> If you want to see a simple example of the use of some of these functions, see <ulink url="http://www.druid.net/rides" - >http://www.druid.net/rides</ulink> where I have a link at the - bottom to the actual <productname>Python</productname> code for the + >http://www.druid.net/rides</ulink> where you can find a link at the + bottom to the actual <application>Python</application> code for the page. </para> @@ -410,7 +385,7 @@ make && make install <para> Some constants are defined in the <literal>pg</literal> module dictionary. They are intended to be used as a parameters for - methods calls. You should refer to the <literal>libpq</literal> + methods calls. You should refer to the <application>libpq</application> description (<xref linkend="libpq">) for more information about them. These constants are: @@ -470,7 +445,7 @@ make && make install default variable, and forget it, without having to modify your environment. The support for default variables can be disabled by 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> @@ -487,12 +462,12 @@ make && make install <refnamediv> <refname>connect</refname> - <refpurpose>opens a connection to the database server</refpurpose> + <refpurpose>open a connection to the database server</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -connect(<optional><replaceable>dbname</replaceable></optional>, <optional><replaceable>host</replaceable></optional>, <optional><replaceable>port</replaceable></optional>, <optional><replaceable>opt</replaceable></optional>, <optional><replaceable>tty</replaceable></optional>, <optional><replaceable>user</replaceable></optional>, <optional><replaceable>passwd</replaceable></optional>) +connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter>host</parameter></optional>, <optional><parameter>port</parameter></optional>, <optional><parameter>opt</parameter></optional>, <optional><parameter>tty</parameter></optional>, <optional><parameter>user</parameter></optional>, <optional><parameter>passwd</parameter></optional>) </synopsis> <refsect2 id="pygresql-connect-parameters"> @@ -500,23 +475,23 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla <variablelist> <varlistentry> - <term><replaceable>dbname</replaceable></term> + <term><parameter>dbname</parameter></term> <listitem> - <para>Name of connected database (string/None).</para> + <para>Name of connected database (string/<symbol>None</>).</para> </listitem> </varlistentry> <varlistentry> - <term><replaceable>host</replaceable></term> + <term><parameter>host</parameter></term> <listitem> - <para>Name of the server host (string/None).</para> + <para>Name of the server host (string/<symbol>None</>).</para> </listitem> </varlistentry> <varlistentry> - <term><replaceable>port</replaceable></term> + <term><parameter>port</parameter></term> <listitem> <para>Port used by the database server (integer/-1).</para> @@ -524,41 +499,41 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla </varlistentry> <varlistentry> - <term><replaceable>opt</replaceable></term> + <term><parameter>opt</parameter></term> <listitem> <para> - Options for the server (string/None). + Options for the server (string/<symbol>None</>). </para> </listitem> </varlistentry> <varlistentry> - <term><replaceable>tty</replaceable></term> + <term><parameter>tty</parameter></term> <listitem> <para> File or tty for optional debug output from backend - (string/None). + (string/<symbol>None</>). </para> </listitem> </varlistentry> <varlistentry> - <term><replaceable>user</replaceable></term> + <term><parameter>user</parameter></term> <listitem> <para> - <productname>PostgreSQL</productname> user (string/None). + <productname>PostgreSQL</productname> user (string/<symbol>None</>). </para> </listitem> </varlistentry> <varlistentry> - <term><replaceable>passwd</replaceable></term> + <term><parameter>passwd</parameter></term> <listitem> - <para>Password for user (string/None).</para> + <para>Password for user (string/<symbol>None</>).</para> </listitem> </varlistentry> </variablelist> @@ -569,7 +544,7 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla <variablelist> <varlistentry> - <term><replaceable>pgobject</replaceable></term> + <term><parameter>pgobject</parameter></term> <listitem> <para> @@ -585,7 +560,7 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla <variablelist> <varlistentry> - <term><errorname>TypeError</errorname></term> + <term><classname>TypeError</classname></term> <listitem> <para> @@ -595,7 +570,7 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla </varlistentry> <varlistentry> - <term><errorname>SyntaxError</errorname></term> + <term><classname>SyntaxError</classname></term> <listitem> <para> @@ -605,18 +580,18 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla </varlistentry> <varlistentry> - <term><errorname>pg.error</errorname></term> + <term><classname>pg.error</classname></term> <listitem> <para> - Some error occurred during pg connection definition. + Some error occurred during <literal>pg</> connection definition. </para> </listitem> </varlistentry> </variablelist> <para> - (+ all exceptions relative to object allocation) + (plus all exceptions relative to object allocation) </para> </refsect2> </refsynopsisdiv> @@ -627,9 +602,9 @@ connect(<optional><replaceable>dbname</replaceable></optional>, <optional><repla <para> This method opens a connection to a specified database on a given <productname>PostgreSQL</productname> server. You can use - keywords here, as described in the - <productname>Python</productname> tutorial. The names of the - keywords are the name of the parameters given in the syntax + key words here, as described in the + <application>Python</application> tutorial. The names of the + key words are the name of the parameters given in the syntax line. For a precise description of the parameters, please refer to the <productname>PostgreSQL</productname> user manual. </para> @@ -680,7 +655,7 @@ get_defhost() <variablelist> <varlistentry> - <term>string or None</term> + <term>string or <symbol>None</></term> <listitem> <para> @@ -696,7 +671,7 @@ get_defhost() <variablelist> <varlistentry> - <term><errorname>SyntaxError</errorname></term> + <term><classname>SyntaxError</classname></term> <listitem> <para> @@ -714,7 +689,7 @@ get_defhost() <para> <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. </para> </refsect1> @@ -723,77 +698,78 @@ get_defhost() <refentry id="pygresql-set-defhost"> - <refmeta> - <refentrytitle>set_defhost</refentrytitle> - <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo> - </refmeta> - <refnamediv> - <refname>set_defhost</refname> - <refpurpose>set default host name [DV]</refpurpose> - </refnamediv> + <refmeta> + <refentrytitle>set_defhost</refentrytitle> + <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo> + </refmeta> - <refsynopsisdiv> + <refnamediv> + <refname>set_defhost</refname> + <refpurpose>set default host name [DV]</refpurpose> + </refnamediv> + + <refsynopsisdiv> <synopsis> -set_defhost(<replaceable>host</replaceable>) +set_defhost(<parameter>host</parameter>) </synopsis> - <refsect2 id="pygresql-set-defhost-parameters"> - <title>Parameters</title> - <variablelist> - <varlistentry> - <term> - <replaceable>host</replaceable> - </term> - <listitem> - <para>New default host (string/None).</para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> + <refsect2 id="pygresql-set-defhost-parameters"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <parameter>host</parameter> + </term> + <listitem> + <para>New default host (string/<symbol>None</>).</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> - <refsect2 id="pygresql-set-defhost-return"> - <title>Return Type</title> - <variablelist> - <varlistentry> - <term> - string or None - </term> - <listitem> - <para> - Previous default host specification. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> + <refsect2 id="pygresql-set-defhost-return"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + string or <symbol>None</> + </term> + <listitem> + <para> + Previous default host specification. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> - <refsect2 id="pygresql-set-defhost-exceptions"> - <title>Exceptions</title> - <variablelist> - <varlistentry> - <term> - <errorname>TypeError</errorname> - </term> - <listitem> - <para> - Bad argument type, or too many arguments. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> + <refsect2 id="pygresql-set-defhost-exceptions"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <classname>TypeError</classname> + </term> + <listitem> + <para> + Bad argument type, or too many arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> - </refsynopsisdiv> + </refsynopsisdiv> - <refsect1 id="pygresql-set-defhost-description"> - <title>Description</title> - <para> - <function>set_defhost()</function> sets the default host value - for new connections. If None is supplied as parameter, environment - variables will be used in future connections. It returns the - previous setting for default host. - </para> - </refsect1> + <refsect1 id="pygresql-set-defhost-description"> + <title>Description</title> + <para> + <function>set_defhost()</function> sets the default host value + for new connections. If <symbol>None</symbol> is supplied as parameter, environment + variables will be used in future connections. It returns the + previous setting for default host. + </para> + </refsect1> </refentry> @@ -826,7 +802,7 @@ get_defport() <variablelist> <varlistentry> <term> - integer or None + integer or <symbol>None</symbol> </term> <listitem> <para> @@ -842,7 +818,7 @@ get_defport() <variablelist> <varlistentry> <term> - <errorname>SyntaxError</errorname> + <classname>SyntaxError</classname> </term> <listitem> <para> @@ -859,7 +835,7 @@ get_defport() <title>Description</title> <para> <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. </para> </refsect1> @@ -880,7 +856,7 @@ get_defport() <refsynopsisdiv> <synopsis> -set_defport(<replaceable>port</replaceable>) +set_defport(<parameter>port</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-SET-DEFPORT-1"> @@ -888,7 +864,7 @@ set_defport(<replaceable>port</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>port</replaceable> + <parameter>port</parameter> </term> <listitem> <para>New default host (integer/-1).</para> @@ -902,7 +878,7 @@ set_defport(<replaceable>port</replaceable>) <variablelist> <varlistentry> <term> - integer or None + integer or <symbol>None</symbol> </term> <listitem> <para> @@ -918,7 +894,7 @@ set_defport(<replaceable>port</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -972,7 +948,7 @@ get_defopt() <variablelist> <varlistentry> <term> - string or None + string or <symbol>None</symbol> </term> <listitem> <para> @@ -988,7 +964,7 @@ get_defopt() <variablelist> <varlistentry> <term> - <errorname>SyntaxError</errorname> + <classname>SyntaxError</classname> </term> <listitem> <para> @@ -1005,7 +981,7 @@ get_defopt() <title>Description</title> <para> <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. </para> </refsect1> @@ -1021,12 +997,12 @@ get_defopt() </refmeta> <refnamediv> <refname>set_defopt</refname> - <refpurpose>set options specification [DV]</refpurpose> + <refpurpose>set default options specification [DV]</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -set_defopt(<replaceable>options</replaceable>) +set_defopt(<parameter>options</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-SET-DEFOPT-1"> @@ -1034,10 +1010,10 @@ set_defopt(<replaceable>options</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>options</replaceable> + <parameter>options</parameter> </term> <listitem> - <para>New default connection options (string/None).</para> + <para>New default connection options (string/<symbol>None</symbol>).</para> </listitem> </varlistentry> </variablelist> @@ -1048,7 +1024,7 @@ set_defopt(<replaceable>options</replaceable>) <variablelist> <varlistentry> <term> - string or None + string or <symbol>None</symbol> </term> <listitem> <para> @@ -1064,7 +1040,7 @@ set_defopt(<replaceable>options</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -1081,7 +1057,7 @@ set_defopt(<replaceable>options</replaceable>) <title>Description</title> <para> <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 previous setting for default options. </para> @@ -1118,7 +1094,7 @@ get_deftty() <variablelist> <varlistentry> <term> - string or None + string or <symbol>None</symbol> </term> <listitem> <para> @@ -1134,7 +1110,7 @@ get_deftty() <variablelist> <varlistentry> <term> - <errorname>SyntaxError</errorname> + <classname>SyntaxError</classname> </term> <listitem> <para> @@ -1151,7 +1127,7 @@ get_deftty() <title>Description</title> <para> <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. </para> </refsect1> @@ -1167,12 +1143,12 @@ get_deftty() </refmeta> <refnamediv> <refname>set_deftty</refname> - <refpurpose>set default debug terminal specification [DV]</refpurpose> + <refpurpose>set default connection debug terminal specification [DV]</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -set_deftty(<replaceable>terminal</replaceable>) +set_deftty(<parameter>terminal</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-SET-DEFTTY-1"> @@ -1180,10 +1156,10 @@ set_deftty(<replaceable>terminal</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>terminal</replaceable> + <parameter>terminal</parameter> </term> <listitem> - <para>New default debug terminal (string/None).</para> + <para>New default debug terminal (string/<symbol>None</symbol>).</para> </listitem> </varlistentry> </variablelist> @@ -1194,7 +1170,7 @@ set_deftty(<replaceable>terminal</replaceable>) <variablelist> <varlistentry> <term> - string or None + string or <symbol>None</symbol> </term> <listitem> <para> @@ -1210,7 +1186,7 @@ set_deftty(<replaceable>terminal</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -1227,7 +1203,7 @@ set_deftty(<replaceable>terminal</replaceable>) <title>Description</title> <para> <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 previous setting for default terminal. </para> @@ -1264,7 +1240,7 @@ get_defbase() <variablelist> <varlistentry> <term> - string or None + string or <symbol>None</symbol> </term> <listitem> <para> @@ -1280,7 +1256,7 @@ get_defbase() <variablelist> <varlistentry> <term> - <errorname>SyntaxError</errorname> + <classname>SyntaxError</classname> </term> <listitem> <para> @@ -1297,7 +1273,7 @@ get_defbase() <title>Description</title> <para> <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. </para> </refsect1> @@ -1318,7 +1294,7 @@ get_defbase() <refsynopsisdiv> <synopsis> -set_defbase(<replaceable>database</replaceable>) +set_defbase(<parameter>database</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-SET-DEFBASE-1"> @@ -1326,10 +1302,10 @@ set_defbase(<replaceable>database</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>database</replaceable> + <parameter>database</parameter> </term> <listitem> - <para>New default database name (string/None).</para> + <para>New default database name (string/<symbol>None</symbol>).</para> </listitem> </varlistentry> </variablelist> @@ -1340,7 +1316,7 @@ set_defbase(<replaceable>database</replaceable>) <variablelist> <varlistentry> <term> - string or None + string or <symbol>None</symbol> </term> <listitem> <para> @@ -1356,7 +1332,7 @@ set_defbase(<replaceable>database</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -1373,7 +1349,7 @@ set_defbase(<replaceable>database</replaceable>) <title>Description</title> <para> <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 previous setting for default database name. </para> @@ -1385,7 +1361,7 @@ set_defbase(<replaceable>database</replaceable>) <sect1 id="pygresql-pg-pgobject"> - <title>Connection object: <classname>pgobject</classname></title> + <title>Connection Object: <classname>pgobject</classname></title> <para> This object handles a connection to the @@ -1398,20 +1374,20 @@ set_defbase(<replaceable>database</replaceable>) Some methods give direct access to the connection socket. They are specified by the tag [DA]. <emphasis>Do not use them unless you really know what you are doing.</emphasis> If you prefer disabling - them, set the <literal>-DNO_DIRECT</literal> option in the - <productname>Python</productname> <filename>Setup</filename> file. + them, set the <option>-DNO_DIRECT</option> option in the + <application>Python</application> <filename>Setup</filename> file. </para> <para> Some other methods give access to large objects. if you want to forbid access to these from the module, set the - <literal>-DNO_LARGE</literal> option in the - <productname>Python</productname> <filename>Setup</filename> file. + <option>-DNO_LARGE</option> option in the + <application>Python</application> <filename>Setup</filename> file. These methods are specified by the tag [LO]. </para> <para> - Every <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 are: @@ -1474,7 +1450,7 @@ set_defbase(<replaceable>database</replaceable>) <term>status</term> <listitem> <para> - the status of the connection (integer: 1 - OK, 0 - BAD) + the status of the connection (integer: 1 - OK, 0 - bad) </para> </listitem> </varlistentry> @@ -1498,12 +1474,12 @@ set_defbase(<replaceable>database</replaceable>) </refmeta> <refnamediv> <refname>query</refname> - <refpurpose>executes a SQL command</refpurpose> + <refpurpose>execute a SQL command</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -query(<replaceable>command</replaceable>) +query(<parameter>command</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-QUERY-1"> @@ -1511,7 +1487,7 @@ query(<replaceable>command</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>command</replaceable> + <parameter>command</parameter> </term> <listitem> <para>SQL command (string).</para> @@ -1525,7 +1501,7 @@ query(<replaceable>command</replaceable>) <variablelist> <varlistentry> <term> - pgqueryobject or None + <classname>pgqueryobject</> or <symbol>None</symbol> </term> <listitem> <para> @@ -1541,7 +1517,7 @@ query(<replaceable>command</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -1551,7 +1527,7 @@ query(<replaceable>command</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>ValueError</errorname> + <classname>ValueError</classname> </term> <listitem> <para> @@ -1561,7 +1537,7 @@ query(<replaceable>command</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -1581,8 +1557,8 @@ query(<replaceable>command</replaceable>) query to the database. If the query is an insert statement, the return value is the <acronym>OID</acronym> of the newly inserted row. If it is otherwise a query that does not return a result - (i.e., is not a some kind of <literal>SELECT</literal> statement), it returns None. - Otherwise, it returns a <literal>pgqueryobject</literal> that can be accessed via the + (i.e., is not a some kind of <literal>SELECT</literal> statement), it returns <symbol>None</symbol>. + Otherwise, it returns a <classname>pgqueryobject</classname> that can be accessed via the <function>getresult()</function> or <function>dictresult()</function> methods or simply printed. </para> @@ -1599,7 +1575,7 @@ query(<replaceable>command</replaceable>) </refmeta> <refnamediv> <refname>reset</refname> - <refpurpose>resets the connection</refpurpose> + <refpurpose>reset the connection</refpurpose> </refnamediv> <refsynopsisdiv> @@ -1626,7 +1602,7 @@ reset() <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -1684,7 +1660,7 @@ close() <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -1718,7 +1694,7 @@ close() </refmeta> <refnamediv> <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> <refsynopsisdiv> @@ -1754,7 +1730,7 @@ fileno() <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -1786,7 +1762,7 @@ fileno() </refmeta> <refnamediv> <refname>getnotify</refname> - <refpurpose>gets the last notify from the server</refpurpose> + <refpurpose>get the last notify from the server</refpurpose> </refnamediv> <refsynopsisdiv> @@ -1806,7 +1782,7 @@ getnotify() <variablelist> <varlistentry> <term> - tuple, None + tuple, <symbol>None</symbol> </term> <listitem> <para> @@ -1822,7 +1798,7 @@ getnotify() <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -1832,7 +1808,7 @@ getnotify() </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -1849,12 +1825,12 @@ getnotify() <title>Description</title> <para> <function>getnotify()</function> method tries to get a notify from - the server (from the <literal>SQL</literal> statement <literal>NOTIFY</literal>). - If the server returns no notify, the methods returns None. + the server (from the SQL statement <literal>NOTIFY</literal>). + If the server returns no notify, the methods returns <symbol>None</symbol>. Otherwise, it returns a tuple (couple) <literal>(relname, pid)</literal>, where <literal>relname</literal> is the name of the notify and <literal>pid</literal> the process id of the connection that triggered the notify. - Remember to do a listen query first otherwise getnotify will always return None. + Remember to do a listen query first otherwise <function>getnotify</> will always return <symbol>None</symbol>. </para> </refsect1> @@ -1869,12 +1845,12 @@ getnotify() </refmeta> <refnamediv> <refname>inserttable</refname> - <refpurpose>inserts a list into a table</refpurpose> + <refpurpose>insert a list into a table</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>) +inserttable(<parameter>table</parameter>, <parameter>values</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-INSERTTABLE-1"> @@ -1882,7 +1858,7 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>table</replaceable> + <parameter>table</parameter> </term> <listitem> <para>The table name (string).</para> @@ -1890,7 +1866,7 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>) </varlistentry> <varlistentry> <term> - <replaceable>values</replaceable> + <parameter>values</parameter> </term> <listitem> <para>The list of rows values to insert (list).</para> @@ -1911,7 +1887,7 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -1921,7 +1897,7 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -1943,7 +1919,7 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>) tuples/lists that define the values for each inserted row. The rows values may contain string, integer, long or double (real) values. <emphasis>Be very careful:</emphasis> this method - does not typecheck the fields according to the table + does not type-check the fields according to the table definition; it just look whether or not it knows how to handle such types. </para> @@ -1960,12 +1936,12 @@ inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>) </refmeta> <refnamediv> <refname>putline</refname> - <refpurpose>writes a line to the server socket [DA]</refpurpose> + <refpurpose>write a line to the server socket [DA]</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -putline(<replaceable>line</replaceable>) +putline(<parameter>line</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-PUTLINE-1"> @@ -1973,7 +1949,7 @@ putline(<replaceable>line</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>line</replaceable> + <parameter>line</parameter> </term> <listitem> <para>Line to be written (string).</para> @@ -1994,7 +1970,7 @@ putline(<replaceable>line</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -2004,7 +1980,7 @@ putline(<replaceable>line</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -2035,7 +2011,7 @@ putline(<replaceable>line</replaceable>) </refmeta> <refnamediv> <refname>getline</refname> - <refpurpose>gets a line from server socket [DA]</refpurpose> + <refpurpose>get a line from server socket [DA]</refpurpose> </refnamediv> <refsynopsisdiv> @@ -2071,7 +2047,7 @@ getline() <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -2081,7 +2057,7 @@ getline() </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -2112,7 +2088,7 @@ getline() </refmeta> <refnamediv> <refname>endcopy</refname> - <refpurpose>synchronizes client and server [DA]</refpurpose> + <refpurpose>synchronize client and server [DA]</refpurpose> </refnamediv> <refsynopsisdiv> @@ -2139,7 +2115,7 @@ endcopy() <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -2149,7 +2125,7 @@ endcopy() </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -2181,12 +2157,12 @@ endcopy() </refmeta> <refnamediv> <refname>locreate</refname> - <refpurpose>creates of large object in the database [LO]</refpurpose> + <refpurpose>create a large object in the database [LO]</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -locreate(<replaceable>mode</replaceable>) +locreate(<parameter>mode</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-LOCREATE-1"> @@ -2194,7 +2170,7 @@ locreate(<replaceable>mode</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>mode</replaceable> + <parameter>mode</parameter> </term> <listitem> <para>Large object create mode.</para> @@ -2208,7 +2184,7 @@ locreate(<replaceable>mode</replaceable>) <variablelist> <varlistentry> <term> - pglarge + <classname>pglarge</> </term> <listitem> <para> @@ -2224,7 +2200,7 @@ locreate(<replaceable>mode</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -2234,7 +2210,7 @@ locreate(<replaceable>mode</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -2252,7 +2228,7 @@ locreate(<replaceable>mode</replaceable>) <para> <function>locreate()</function> method creates a large object in the database. The mode can be defined by OR-ing the constants defined in the pg module - (<literal>INV_READ and INV_WRITE</literal>). + (<literal>INV_READ</literal> and <literal>INV_WRITE</literal>). </para> </refsect1> @@ -2267,12 +2243,12 @@ locreate(<replaceable>mode</replaceable>) </refmeta> <refnamediv> <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> <refsynopsisdiv> <synopsis> -getlo(<replaceable>oid</replaceable>) +getlo(<parameter>oid</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-GETLO-1"> @@ -2280,10 +2256,10 @@ getlo(<replaceable>oid</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>oid</replaceable> + <parameter>oid</parameter> </term> <listitem> - <para><literal>OID</literal> of the existing large object (integer).</para> + <para>OID of the existing large object (integer).</para> </listitem> </varlistentry> </variablelist> @@ -2294,7 +2270,7 @@ getlo(<replaceable>oid</replaceable>) <variablelist> <varlistentry> <term> - pglarge + <classname>pglarge</> </term> <listitem> <para> @@ -2310,7 +2286,7 @@ getlo(<replaceable>oid</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -2320,7 +2296,7 @@ getlo(<replaceable>oid</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -2338,7 +2314,7 @@ getlo(<replaceable>oid</replaceable>) <para> <function>getlo()</function> method allows to reuse a formerly created large object through the <classname>pglarge</classname> interface, providing - the user have its <literal>oid</literal>. + the user has its OID. </para> </refsect1> @@ -2353,12 +2329,12 @@ getlo(<replaceable>oid</replaceable>) </refmeta> <refnamediv> <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> <refsynopsisdiv> <synopsis> -loimport(<replaceable>filename</replaceable>) +loimport(<parameter>filename</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-LOIMPORT-1"> @@ -2366,7 +2342,7 @@ loimport(<replaceable>filename</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>filename</replaceable> + <parameter>filename</parameter> </term> <listitem> <para>The name of the file to be imported (string).</para> @@ -2380,7 +2356,7 @@ loimport(<replaceable>filename</replaceable>) <variablelist> <varlistentry> <term> - pglarge + <classname>pglarge</> </term> <listitem> <para> @@ -2396,7 +2372,7 @@ loimport(<replaceable>filename</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -2406,7 +2382,7 @@ loimport(<replaceable>filename</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -2434,7 +2410,7 @@ loimport(<replaceable>filename</replaceable>) <sect1 id="pygresql-pg-DB"> - <title>Database wrapper class: <classname>DB</classname></title> + <title>Database Wrapper Class: <classname>DB</classname></title> <para> <classname>pg</classname> module contains a class called @@ -2476,12 +2452,12 @@ for r in db.query( </refmeta> <refnamediv> <refname>pkey</refname> - <refpurpose>returns the primary key of a table</refpurpose> + <refpurpose>return the primary key of a table</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -pkey(<replaceable>table</replaceable>) +pkey(<parameter>table</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-DB-PKEY-1"> @@ -2489,7 +2465,7 @@ pkey(<replaceable>table</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>table</replaceable> + <parameter>table</parameter> </term> <listitem> <para> @@ -2642,12 +2618,12 @@ get_tables() </refmeta> <refnamediv> <refname>get_attnames</refname> - <refpurpose>returns the attribute names of a table</refpurpose> + <refpurpose>return the attribute names of a table</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -get_attnames(<replaceable>table</replaceable>) +get_attnames(<parameter>table</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-DB-GET-ATTNAMES-1"> @@ -2655,7 +2631,7 @@ get_attnames(<replaceable>table</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>table</replaceable> + <parameter>table</parameter> </term> <listitem> <para> @@ -2710,7 +2686,7 @@ get_attnames(<replaceable>table</replaceable>) <refsynopsisdiv> <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> <refsect2 id="R2-PYGRESQL-DB-GET-1"> @@ -2718,7 +2694,7 @@ get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional> <variablelist> <varlistentry> <term> - <replaceable>table</replaceable> + <parameter>table</parameter> </term> <listitem> <para> @@ -2728,7 +2704,7 @@ get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional> </varlistentry> <varlistentry> <term> - <replaceable>arg</replaceable> + <parameter>arg</parameter> </term> <listitem> <para> @@ -2738,7 +2714,7 @@ get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional> </varlistentry> <varlistentry> <term> - <optional><replaceable>keyname</replaceable></optional> + <optional><parameter>keyname</parameter></optional> </term> <listitem> <para> @@ -2771,11 +2747,11 @@ get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional> <title>Description</title> <para> This method is the basic mechanism to get a single row. It assumes - that the key specifies a unique row. If keyname is not specified - then the primary key for the table is used. If arg is a dictionary + that the key specifies a unique row. If <parameter>keyname</> is not specified + then the primary key for the table is used. If <parameter>arg</> is a dictionary then the value for the key is taken from it and it is modified to include the new values, replacing existing values where necessary. - The oid is also put into the dictionary but in order to allow the + The OID is also put into the dictionary but in order to allow the caller to work with multiple tables, the attribute name is munged to make it unique. It consists of the string <literal>oid_</literal> followed by the name of the table. @@ -2798,7 +2774,7 @@ get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional> <refsynopsisdiv> <synopsis> -insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>) +insert(<parameter>table</parameter>, <parameter>a</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-DB-INSERT-1"> @@ -2806,7 +2782,7 @@ insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>table</replaceable> + <parameter>table</parameter> </term> <listitem> <para> @@ -2816,7 +2792,7 @@ insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>) </varlistentry> <varlistentry> <term> - <replaceable>a</replaceable> + <parameter>a</parameter> </term> <listitem> <para> @@ -2853,6 +2829,13 @@ insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>) values from the database. This causes the dictionary to be updated with values that are modified by rules, triggers, etc. </para> + + <para> + Due to the way that this function works you will find inserts + taking longer and longer as your table gets bigger. To + overcome this problem simply add an index onto the OID of any + table that you think may get large over time. + </para> </refsect1> </refentry> @@ -2871,7 +2854,7 @@ insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>) <refsynopsisdiv> <synopsis> -update(<replaceable>table</replaceable>, <replaceable>a</replaceable>) +update(<parameter>table</parameter>, <parameter>a</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-DB-UPDATE-1"> @@ -2879,7 +2862,7 @@ update(<replaceable>table</replaceable>, <replaceable>a</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>table</replaceable> + <parameter>table</parameter> </term> <listitem> <para> @@ -2889,7 +2872,7 @@ update(<replaceable>table</replaceable>, <replaceable>a</replaceable>) </varlistentry> <varlistentry> <term> - <replaceable>a</replaceable> + <parameter>a</parameter> </term> <listitem> <para> @@ -2944,7 +2927,7 @@ update(<replaceable>table</replaceable>, <replaceable>a</replaceable>) <refsynopsisdiv> <synopsis> -clear(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></optional>) +clear(<parameter>table</parameter>, <optional><parameter>a</parameter></optional>) </synopsis> <refsect2 id="R2-PYGRESQL-DB-CLEAR-1"> @@ -2952,7 +2935,7 @@ clear(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></ <variablelist> <varlistentry> <term> - <replaceable>table</replaceable> + <parameter>table</parameter> </term> <listitem> <para> @@ -2962,7 +2945,7 @@ clear(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></ </varlistentry> <varlistentry> <term> - <optional><replaceable>a</replaceable></optional> + <optional><parameter>a</parameter></optional> </term> <listitem> <para> @@ -3013,12 +2996,12 @@ clear(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></ </refmeta> <refnamediv> <refname>delete</refname> - <refpurpose>deletes the row from a table</refpurpose> + <refpurpose>delete a row from a table</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></optional>) +delete(<parameter>table</parameter>, <optional><parameter>a</parameter></optional>) </synopsis> <refsect2 id="R2-PYGRESQL-DB-DELETE-1"> @@ -3026,7 +3009,7 @@ delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable>< <variablelist> <varlistentry> <term> - <replaceable>table</replaceable> + <parameter>table</parameter> </term> <listitem> <para> @@ -3036,7 +3019,7 @@ delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable>< </varlistentry> <varlistentry> <term> - <optional><replaceable>a</replaceable></optional> + <optional><parameter>a</parameter></optional> </term> <listitem> <para> @@ -3074,7 +3057,7 @@ delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable>< <!-- ********************************************************** --> <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>< </refmeta> <refnamediv> <refname>getresult</refname> - <refpurpose>gets the values returned by the query</refpurpose> + <refpurpose>get the values returned by the query</refpurpose> </refnamediv> <refsynopsisdiv> @@ -3121,7 +3104,7 @@ getresult() <variablelist> <varlistentry> <term> - <errorname>SyntaxError</errorname> + <classname>SyntaxError</classname> </term> <listitem> <para> @@ -3131,7 +3114,7 @@ getresult() </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -3164,7 +3147,7 @@ getresult() </refmeta> <refnamediv> <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> <refsynopsisdiv> @@ -3200,7 +3183,7 @@ dictresult() <variablelist> <varlistentry> <term> - <errorname>SyntaxError</errorname> + <classname>SyntaxError</classname> </term> <listitem> <para> @@ -3210,7 +3193,7 @@ dictresult() </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -3243,7 +3226,7 @@ dictresult() </refmeta> <refnamediv> <refname>listfields</refname> - <refpurpose>lists the fields names of the query result</refpurpose> + <refpurpose>list the fields names of the query result</refpurpose> </refnamediv> <refsynopsisdiv> @@ -3279,7 +3262,7 @@ listfields() <variablelist> <varlistentry> <term> - <errorname>SyntaxError</errorname> + <classname>SyntaxError</classname> </term> <listitem> <para> @@ -3289,7 +3272,7 @@ listfields() </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -3321,12 +3304,12 @@ listfields() </refmeta> <refnamediv> <refname>fieldname</refname> - <refpurpose>field number-name conversion</refpurpose> + <refpurpose>get field name by number</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -fieldname(<replaceable>i</replaceable>) +fieldname(<parameter>i</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-1"> @@ -3334,7 +3317,7 @@ fieldname(<replaceable>i</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>i</replaceable> + <parameter>i</parameter> </term> <listitem> <para> @@ -3366,7 +3349,7 @@ fieldname(<replaceable>i</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -3376,7 +3359,7 @@ fieldname(<replaceable>i</replaceable>) </varlistentry> <varlistentry> <term> - <replaceable>ValueError</replaceable> + <classname>ValueError</classname> </term> <listitem> <para> @@ -3386,7 +3369,7 @@ fieldname(<replaceable>i</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -3419,12 +3402,12 @@ fieldname(<replaceable>i</replaceable>) </refmeta> <refnamediv> <refname>fieldnum</refname> - <refpurpose>field name-number conversion</refpurpose> + <refpurpose>get field number by name</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -fieldnum(<replaceable>name</replaceable>) +fieldnum(<parameter>name</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-1"> @@ -3432,7 +3415,7 @@ fieldnum(<replaceable>name</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>name</replaceable> + <parameter>name</parameter> </term> <listitem> <para> @@ -3464,7 +3447,7 @@ fieldnum(<replaceable>name</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -3474,7 +3457,7 @@ fieldnum(<replaceable>name</replaceable>) </varlistentry> <varlistentry> <term> - <replaceable>ValueError</replaceable> + <classname>ValueError</classname> </term> <listitem> <para> @@ -3484,7 +3467,7 @@ fieldnum(<replaceable>name</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -3518,7 +3501,7 @@ fieldnum(<replaceable>name</replaceable>) </refmeta> <refnamediv> <refname>ntuples</refname> - <refpurpose>returns the number of tuples in query object</refpurpose> + <refpurpose>return the number of tuples in query object</refpurpose> </refnamediv> <refsynopsisdiv> @@ -3554,7 +3537,7 @@ ntuples() <variablelist> <varlistentry> <term> - <errorname>SyntaxError</errorname> + <classname>SyntaxError</classname> </term> <listitem> <para> @@ -3585,7 +3568,7 @@ ntuples() <para> This object handles all the request concerning a <productname>PostgreSQL</productname> large object. It embeds and - hides all the <quote>recurrent</quote> variables (object oid and + hides all the <quote>recurrent</quote> variables (object OID and connection), exactly in the same way <classname>pgobject</classname>s do, thus only keeping significant parameters in function calls. It keeps a reference to the <classname>pgobject</classname> @@ -3608,16 +3591,16 @@ ntuples() <variablelist> <varlistentry> - <term>oid</term> + <term><structfield>oid</></term> <listitem> <para> - the oid associated with the object + the OID associated with the object </para> </listitem> </varlistentry> <varlistentry> - <term>pgcnx</term> + <term><structfield>pgcnx</></term> <listitem> <para> the <classname>pgobject</classname> associated with the object @@ -3626,7 +3609,7 @@ ntuples() </varlistentry> <varlistentry> - <term>error</term> + <term><structfield>error</></term> <listitem> <para> the last warning/error message of the connection @@ -3635,20 +3618,19 @@ ntuples() </varlistentry> </variablelist> - <note> - <title>Be careful</title> - + <important> <para> In multithreaded environments, <structfield>error</structfield> may be modified by another thread using the same - <classname>pgobject</classname>. Remember these object are - shared, not duplicated; you should provide some locking to be - able if you want to check this. The oid attribute is very - interesting because it allow you reuse the oid later, creating - the <classname>pglarge</classname> object with a <classname>pgobject</classname> + <classname>pgobject</classname>. Remember that these object are + shared, not duplicated; you should provide some locking if you + want to check for the error message in this situation. The OID + attribute is very interesting because it allow you to reuse the + OID later, creating the <classname>pglarge</classname> object + with a <classname>pgobject</classname> <function>getlo()</function> method call. </para> - </note> + </important> </para> <para> @@ -3665,12 +3647,12 @@ ntuples() </refmeta> <refnamediv> <refname>open</refname> - <refpurpose>opens a large object</refpurpose> + <refpurpose>open a large object</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -open(<replaceable>mode</replaceable>) +open(<parameter>mode</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-1"> @@ -3678,7 +3660,7 @@ open(<replaceable>mode</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>mode</replaceable> + <parameter>mode</parameter> </term> <listitem> <para> @@ -3701,7 +3683,7 @@ open(<replaceable>mode</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -3711,7 +3693,7 @@ open(<replaceable>mode</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>IOError</errorname> + <classname>IOError</classname> </term> <listitem> <para> @@ -3721,7 +3703,7 @@ open(<replaceable>mode</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -3738,9 +3720,9 @@ open(<replaceable>mode</replaceable>) <title>Description</title> <para> <function>open()</function> method opens a large object for reading/writing, - in the same way than the <acronym>UNIX</acronym> <function>open()</function> + in the same way than the Unix <function>open()</function> function. The mode value can be obtained by OR-ing the constants defined in - the pg module (<literal>INV_READ, INV_WRITE</literal>). + the pg module (<literal>INV_READ</literal>, <literal>INV_WRITE</literal>). </para> </refsect1> @@ -3755,7 +3737,7 @@ open(<replaceable>mode</replaceable>) </refmeta> <refnamediv> <refname>close</refname> - <refpurpose>closes the large object</refpurpose> + <refpurpose>close the large object</refpurpose> </refnamediv> <refsynopsisdiv> @@ -3782,7 +3764,7 @@ close() <variablelist> <varlistentry> <term> - <errorname>SyntaxError</errorname> + <classname>SyntaxError</classname> </term> <listitem> <para> @@ -3792,7 +3774,7 @@ close() </varlistentry> <varlistentry> <term> - <errorname>IOError</errorname> + <classname>IOError</classname> </term> <listitem> <para> @@ -3802,7 +3784,7 @@ close() </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -3819,7 +3801,7 @@ close() <title>Description</title> <para> <function>close()</function> method closes previously opened large object, - in the same way than the <acronym>UNIX</acronym> <function>close()</function> function. + in the same way than the Unix <function>close()</function> function. </para> </refsect1> @@ -3834,12 +3816,12 @@ close() </refmeta> <refnamediv> <refname>read</refname> - <refpurpose>reads from the large object</refpurpose> + <refpurpose>read from the large object</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -read(<replaceable>size</replaceable>) +read(<parameter>size</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-1"> @@ -3847,7 +3829,7 @@ read(<replaceable>size</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>size</replaceable> + <parameter>size</parameter> </term> <listitem> <para> @@ -3879,7 +3861,7 @@ read(<replaceable>size</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -3889,7 +3871,7 @@ read(<replaceable>size</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>IOError</errorname> + <classname>IOError</classname> </term> <listitem> <para> @@ -3899,7 +3881,7 @@ read(<replaceable>size</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -3931,12 +3913,12 @@ read(<replaceable>size</replaceable>) </refmeta> <refnamediv> <refname>write</refname> - <refpurpose>writes to the large object</refpurpose> + <refpurpose>write to the large object</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -write(<replaceable>string</replaceable>) +write(<parameter>string</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-1"> @@ -3944,7 +3926,7 @@ write(<replaceable>string</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>string</replaceable> + <parameter>string</parameter> </term> <listitem> <para> @@ -3967,7 +3949,7 @@ write(<replaceable>string</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -3977,7 +3959,7 @@ write(<replaceable>string</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>IOError</errorname> + <classname>IOError</classname> </term> <listitem> <para> @@ -3987,7 +3969,7 @@ write(<replaceable>string</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -4024,7 +4006,7 @@ write(<replaceable>string</replaceable>) <refsynopsisdiv> <synopsis> -seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) +seek(<parameter>offset</parameter>, <parameter>whence</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-1"> @@ -4032,7 +4014,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>offset</replaceable> + <parameter>offset</parameter> </term> <listitem> <para> @@ -4042,7 +4024,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) </varlistentry> <varlistentry> <term> - <replaceable>whence</replaceable> + <parameter>whence</parameter> </term> <listitem> <para> @@ -4074,7 +4056,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -4084,7 +4066,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>IOError</errorname> + <classname>IOError</classname> </term> <listitem> <para> @@ -4094,7 +4076,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -4112,7 +4094,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) <para> <function>seek()</function> method allows to move the cursor position in the large object. The whence parameter can be obtained by OR-ing the constants defined in the - <literal>pg</literal> module (<literal>SEEK_SET, SEEK_CUR, SEEK_END</literal>). + <literal>pg</literal> module (<literal>SEEK_SET</>, <>SEEK_CUR</>, <>SEEK_END</literal>). </para> </refsect1> @@ -4127,7 +4109,7 @@ seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) </refmeta> <refnamediv> <refname>tell</refname> - <refpurpose>returns current position in the large object</refpurpose> + <refpurpose>return current position in the large object</refpurpose> </refnamediv> <refsynopsisdiv> @@ -4163,7 +4145,7 @@ tell() <variablelist> <varlistentry> <term> - <errorname>SyntaxError</errorname> + <classname>SyntaxError</classname> </term> <listitem> <para> @@ -4173,7 +4155,7 @@ tell() </varlistentry> <varlistentry> <term> - <errorname>IOError</errorname> + <classname>IOError</classname> </term> <listitem> <para> @@ -4183,7 +4165,7 @@ tell() </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -4214,7 +4196,7 @@ tell() </refmeta> <refnamediv> <refname>unlink</refname> - <refpurpose>deletes the large object</refpurpose> + <refpurpose>delete the large object</refpurpose> </refnamediv> <refsynopsisdiv> @@ -4241,7 +4223,7 @@ unlink() <variablelist> <varlistentry> <term> - <errorname>SyntaxError</errorname> + <classname>SyntaxError</classname> </term> <listitem> <para> @@ -4251,7 +4233,7 @@ unlink() </varlistentry> <varlistentry> <term> - <errorname>IOError</errorname> + <classname>IOError</classname> </term> <listitem> <para> @@ -4261,7 +4243,7 @@ unlink() </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -4292,7 +4274,7 @@ unlink() </refmeta> <refnamediv> <refname>size</refname> - <refpurpose>gives the large object size</refpurpose> + <refpurpose>return the large object size</refpurpose> </refnamediv> <refsynopsisdiv> @@ -4328,7 +4310,7 @@ size() <variablelist> <varlistentry> <term> - <errorname>SyntaxError</errorname> + <classname>SyntaxError</classname> </term> <listitem> <para> @@ -4338,7 +4320,7 @@ size() </varlistentry> <varlistentry> <term> - <errorname>IOError</errorname> + <classname>IOError</classname> </term> <listitem> <para> @@ -4348,7 +4330,7 @@ size() </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -4366,8 +4348,8 @@ size() <para> <function>size()</function> method allows to get the size of the large object. It was implemented because this function - is very useful for a WWW interfaced database. - Currently the large object needs to be opened. + is very useful for a WWW-interfaced database. + Currently, the large object needs to be opened first. </para> </refsect1> @@ -4382,12 +4364,12 @@ size() </refmeta> <refnamediv> <refname>export</refname> - <refpurpose>saves the large object to file</refpurpose> + <refpurpose>save the large object to file</refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -export(<replaceable>filename</replaceable>) +export(<parameter>filename</parameter>) </synopsis> <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-1"> @@ -4395,7 +4377,7 @@ export(<replaceable>filename</replaceable>) <variablelist> <varlistentry> <term> - <replaceable>filename</replaceable> + <parameter>filename</parameter> </term> <listitem> <para> @@ -4418,7 +4400,7 @@ export(<replaceable>filename</replaceable>) <variablelist> <varlistentry> <term> - <errorname>TypeError</errorname> + <classname>TypeError</classname> </term> <listitem> <para> @@ -4428,7 +4410,7 @@ export(<replaceable>filename</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>IOError</errorname> + <classname>IOError</classname> </term> <listitem> <para> @@ -4438,7 +4420,7 @@ export(<replaceable>filename</replaceable>) </varlistentry> <varlistentry> <term> - <errorname>pg.error</errorname> + <classname>pg.error</classname> </term> <listitem> <para> @@ -4465,20 +4447,4 @@ export(<replaceable>filename</replaceable>) </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> |