diff options
| -rw-r--r-- | doc/src/sgml/filelist.sgml | 3 | ||||
| -rw-r--r-- | doc/src/sgml/libpq.sgml | 6 | ||||
| -rw-r--r-- | doc/src/sgml/programmer.sgml | 3 | ||||
| -rw-r--r-- | doc/src/sgml/pygresql.sgml | 4482 |
4 files changed, 4489 insertions, 5 deletions
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index f38c6b0cd22..b56bd4c24e4 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -1,4 +1,4 @@ -<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.8 2001/02/04 15:28:18 petere Exp $ --> +<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.9 2001/03/04 18:54:07 petere Exp $ --> <!entity history SYSTEM "history.sgml"> <!entity info SYSTEM "info.sgml"> @@ -62,6 +62,7 @@ <!entity libpq SYSTEM "libpq.sgml"> <!entity libpqpp SYSTEM "libpq++.sgml"> <!entity libpgtcl SYSTEM "libpgtcl.sgml"> +<!entity pygresql SYSTEM "pygresql.sgml"> <!entity lisp SYSTEM "lisp.sgml"> <!entity lobj SYSTEM "lobj.sgml"> <!entity odbc SYSTEM "odbc.sgml"> diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 13b69533d2c..53455d7853f 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,9 +1,9 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.57 2001/01/20 20:59:28 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.58 2001/03/04 18:54:07 petere Exp $ --> - <chapter id="libpq-chapter"> - <title id="libpq">libpq - C Library</title> + <chapter id="libpq"> + <title>libpq - C Library</title> <para> <filename>libpq</filename> is the <acronym>C</acronym> diff --git a/doc/src/sgml/programmer.sgml b/doc/src/sgml/programmer.sgml index f4f3812fdd1..7cb73ac5e42 100644 --- a/doc/src/sgml/programmer.sgml +++ b/doc/src/sgml/programmer.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.34 2001/02/04 15:28:18 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.35 2001/03/04 18:54:07 petere Exp $ PostgreSQL Programmer's Guide. --> @@ -48,6 +48,7 @@ PostgreSQL Programmer's Guide. &ecpg; &odbc; &jdbc; + &pygresql; &lisp; </part> diff --git a/doc/src/sgml/pygresql.sgml b/doc/src/sgml/pygresql.sgml new file mode 100644 index 00000000000..28c13d5daa5 --- /dev/null +++ b/doc/src/sgml/pygresql.sgml @@ -0,0 +1,4482 @@ +<!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/pygresql.sgml,v 1.1 2001/03/04 18:54:07 petere Exp $ --> + +<chapter id="pygresql"> + <title><application>PyGreSQL</application> - <application>Python</application> Interface</title> + + <note> + <title>Author</title> + <para> + Written by D'Arcy J.M. Cain (<email>darcy@druid.net</email>). + Based heavily on code written by Pascal Andre + <email>andre@chimay.via.ecp.fr</email>. Copyright © 1995, + Pascal Andre. Further modifications Copyright © 1997-2000 by + D'Arcy J.M. Cain. + </para> + </note> + + +<![IGNORE[ + <sect1 id="pygresql-install"> + <title>Installation</title> + + <itemizedlist> + <listitem> + <para> + If you are on <acronym>NetBSD</acronym>, look in the packages + directory under databases. If it isn't there yet, it should be + there shortly. You can also pick up the package files from + <ulink url="ftp://ftp.druid.net/pub/distrib/pygresql.pkg.tgz" + >ftp://ftp.druid.net/pub/distrib/pygresql.pkg.tgz</ulink>. There + is also a package in the <acronym>FreeBSD</acronym> ports + collection but as I write this it is at version 2.1. I will try + to get that updated as well. + </para> + </listitem> + + <listitem> + <para> + For Linux installation look at <filename>README.linux</filename>. + If you're on an <acronym>x86</acronym> system that uses + <acronym>RPMs</acronym>, then you can pick up an + <acronym>RPM</acronym> at <ulink + url="ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm" + >ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm</ulink>. + </para> + </listitem> + + <listitem> + <para> + Note that if you are using the <acronym>DB-API</acronym> module + you must also install <acronym>mxDateTime</acronym> from <ulink + url="http://starship.python.net/~lemburg/mxDateTime.html" + >http://starship.python.net/~lemburg/mxDateTime.html</ulink>. + </para> + </listitem> + + <listitem> + <para> + Also, check out <filename>setup.py</filename> for an alternate + method of installing the package using Python's Distutils. + </para> + </listitem> + + </itemizedlist> + + <para> + You have two options. You can compile + <productname>PyGreSQL</productname> as a stand-alone module or you + can build it into the <productname>Python</productname> + interpreter. + </para> + + <sect2> + <title>General</title> + + <itemizedlist> + <listitem> + <para> + You must first have installed <productname>Python</productname> + and <productname>PostgreSQL</productname> on your system. The + header files and developer's libraries for both + <productname>Python</productname> and + <productname>PostgreSQL</productname> must be installed on your + system before you can build <productname>PyGreSQL</productname>. + If you built both <productname>Python</productname> and + <productname>PostgreSQL</productname> from source, you should be + fine. If your system uses some package mechanism (such as + <acronym>RPM</acronym> or <acronym>NetBSD</acronym> packages), + then you probably need to install packages such as + <acronym>Python-devel</acronym> in addition to the + <productname>Python</productname> package. + </para> + </listitem> + + <listitem> + <para> + <productname>PyGreSQL</productname> is implemented as three + parts, a C module labeled <acronym>_pg</acronym> and two + <productname>Python</productname> wrappers called + <filename>pg.py</filename> and <filename>pgdb.py</filename>. + This changed between 2.1 and 2.2 and again in 3.0. These + changes should not affect any existing programs but the + installation is slightly different. + </para> + </listitem> + + <listitem> + <para> + Download and unpack the <productname>PyGreSQL</productname> + tarball if you haven't already done so. + </para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>Stand-alone</title> + + <itemizedlist> + <listitem> + <para> + In the directory containing <filename>pgmodule.c</filename>, run + the following command + +<programlisting> +cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c +</programlisting> + + where: + <itemizedlist> + <listitem> + <para> + [pyInc] = path of the <productname>Python</productname> + include (usually <filename>Python.h</filename>) + </para> + </listitem> + + <listitem> + <para> + [pgInc] = path of the <productname>PostgreSQL</productname> + include (usually <filename>postgres.h</filename>) + </para> + </listitem> + + <listitem> + <para> + [pgLib] = path of the <productname>PostgreSQL</productname> + libraries (usually <filename>libpq.so</filename> or + <filename>libpq.a</filename>) + </para> + </listitem> + </itemizedlist> + + Some options may be added to this line: + <itemizedlist> + <listitem> + <para> + <literal>-DNO_DEF_VAR</literal> - no default variables + support + </para> + </listitem> + + <listitem> + <para> + <literal>-DNO_DIRECT</literal> - no direct access methods + </para> + </listitem> + + <listitem> + <para> + <literal>-DNO_LARGE</literal> - no large object support + </para> + </listitem> + + <listitem> + <para> + <literal>-DNO_SNPRINTF</literal> - if running a system with + no snprintf call + </para> + </listitem> + + <listitem> + <para> + <literal>-DNO_PQSOCKET</literal> - if running an older + <productname>PostgreSQL</productname> + </para> + </listitem> + </itemizedlist> + + On some systems you may need to include + <literal>-lcrypt</literal> in the list of libraries to make it + compile. + + Define <literal>DNO_PQSOCKET</literal> if you are using a + version of <productname>PostgreSQL</productname> before 6.4 that + does not have the <function>PQsocket</function> function. The + other options will be described in the next sections. + </para> + </listitem> + <listitem> + + <para> + Test the new module. Something like the following should work. +<screen> +<prompt>$</prompt> <userinput>python</userinput> + +<prompt>>>></prompt> <userinput>import _pg</userinput> +<prompt>>>></prompt> <userinput>db = _pg.connect('thilo', 'localhost')</userinput> +<prompt>>>></prompt> <userinput>db.query("INSERT INTO test VALUES ('ping', 'pong');")</userinput> +18304 +<prompt>>>></prompt> <userinput>db.query("SELECT * FROM test;")</userinput> + eins | zwei +------+------ + ping | pong +(1 row) +</screen> + </para> + </listitem> + <listitem> + <para> + Finally, move the <filename>_pg.so</filename>, + <filename>pg.py</filename>, and <filename>pgdb.py</filename> + to a directory in your <literal>PYTHONPATH</literal>. + A good place would be + <filename>/usr/lib/python1.5/site-python</filename> + if your <productname>Python</productname> modules are in + <filename>/usr/lib/python1.5</filename>. + </para> + </listitem> + </itemizedlist> + </sect2> + + + <sect2> + <title>Built-in to python interpreter</title> + + <itemizedlist> + <listitem> + <para> + Find the directory where your '<filename>Setup</filename>' + file lives (usually <filename>??/Modules</filename>) in + the <productname>Python</productname> source hierarchy and + copy or symlink the '<filename>pgmodule.c</filename>' file there. + </para> + </listitem> + <listitem> + <para> + Add the following line to your Setup file + <ProgramListing> +_pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems + </ProgramListing> + where: + <itemizedlist> + <listitem> + <para> + [pgInc] = path of the <productname>PostgreSQL</productname> + include (usually <filename>postgres.h</filename>) + </para> + </listitem> + <listitem> + <para> + [pgLib] = path of the <productname>PostgreSQL</productname> + libraries (usually <filename>libpq.so</filename> + or <filename>libpq.a</filename>) + </para> + </listitem> + </itemizedlist> + Some options may be added to this line: + <itemizedlist> + <listitem> + <para> + <literal>-DNO_DEF_VAR</literal> - no default variables + support + </para> + </listitem> + <listitem> + <para> + <literal>-DNO_DIRECT</literal> - no direct access methods + </para> + </listitem> + <listitem> + <para> + <literal>-DNO_LARGE</literal> - no large object support + </para> + </listitem> + <listitem> + <para> + <literal>-DNO_SNPRINTF</literal> - if running a system with + no snprintf call + </para> + </listitem> + <listitem> + <para> + <literal>-DNO_PQSOCKET</literal> - if running an older + <productname>PostgreSQL</productname> + </para> + </listitem> + </itemizedlist> + + Define <literal>DNO_PQSOCKET</literal> if you are using a version of + <productname>PostgreSQL</productname> before 6.4 + that does not have the <function>PQsocket</function> function. + The other options will be described in the next sections. + </para> + </listitem> + <listitem> + <para> + If you want a shared module, make sure that the + "<literal>*shared*</literal>" keyword is uncommented and + add the above line below it. You used to need to install + your shared modules with "make sharedinstall" but this no + longer seems to be true. + </para> + </listitem> + <listitem> + <para> + Copy <filename>pg.py</filename> to the lib directory where + the rest of your modules are. For example, that's + <filename>/usr/local/lib/Python</filename> on my system. + </para> + </listitem> + <listitem> + <para> + Rebuild <productname>Python</productname> from the root + directory of the <productname>Python</productname> source + hierarchy by running + <ProgramListing> +make -f Makefile.pre.in boot +make && make install + </ProgramListing> + </para> + </listitem> + <listitem> + <para> + For more details read the documentation at the top of + <filename>Makefile.pre.in</filename> + </para> + </listitem> + </itemizedlist> + </sect2> + + </sect1> + +]]> + + <sect1 id="pygresql-pg"> + <title>The <literal>pg</literal> Module</title> + + <para> + You may either choose to use the old mature interface provided by + the <literal>pg</literal> module or otherwise the newer + <literal>pgdb</literal> interface compliant with the <ulink + url="http://www.python.org/topics/database/DatabaseAPI-2.0.html" + ><acronym>DB-API 2.0</acronym></ulink> specification developed by + the <productname>Python</productname> <acronym>DB-SIG</acronym>. + </para> + + <para> + Here we describe only the older <literal>pg</literal> + <acronym>API</acronym>. As long as + <productname>PyGreSQL</productname> does not contain a description + of the <acronym>DB-API</acronym> you should read about the + <acronym>API</acronym> at <ulink + url="http://www.python.org/topics/database/DatabaseAPI-2.0.html" + >http://www.python.org/topics/database/DatabaseAPI-2.0.html</ulink>. + </para> + + <para> + A tutorial-like introduction to the <acronym>DB-API</acronym> can + be found at <ulink + url="http://www2.linuxjournal.com/lj-issues/issue49/2605.html" + >http://www2.linuxjournal.com/lj-issues/issue49/2605.html</ulink> + </para> + + <para> + The <literal>pg</literal> module defines three objects: + <itemizedlist> + <listitem> + <para> + <classname>pgobject</classname>, which handles the connection and all the + requests to the database, + </para> + </listitem> + + <listitem> + <para> + <classname>pglargeobject</classname>, which handles all the accesses + to <productname>Postgres</productname> large objects, and + </para> + </listitem> + + <listitem> + <para> + <literal>pgqueryobject</literal> that handles query results. + </para> + </listitem> + </itemizedlist> + </para> + + <para> + If you want to see a simple example of the use of some of these + functions, see <ulink url="http://www.druid.net/rides" + >http://www.druid.net/rides</ulink> where I have a link at the + bottom to the actual <productname>Python</productname> code for the + page. + </para> + + <sect2> + <title>Constants</title> + + <para> + Some constants are defined in the <literal>pg</literal> module + dictionary. They are intended to be used as a parameters for + methods calls. You should refer to the <literal>libpq</literal> + description (<xref linkend="libpq">) for more information about + them. These constants are: + + <variablelist> + <varlistentry> + <term><varname>INV_READ</varname></term> + <term><varname>INV_WRITE</varname></term> + <term><varname>INV_ARCHIVE</varname></term> + <listitem> + <para> + large objects access modes, used by + <function>(pgobject.)locreate</function> and + <function>(pglarge.)open</function>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>SEEK_SET</varname></term> + <term><varname>SEEK_CUR</varname></term> + <term><varname>SEEK_END</varname></term> + <listitem> + <para> + positional flags, used by <function>(pglarge.)seek</function>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>version</varname></term> + <term><varname>__version__</varname></term> + <listitem> + <para> + constants that give the current version + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </sect2> + </sect1> + + + <sect1 id="pygresql-pg-functions"> + <title><literal>pg</literal> Module Functions</title> + + <para> + <literal>pg</literal> module defines only a few methods that allow + to connect to a database and to define <quote>default + variables</quote> that override the environment variables used by + <productname>PostgreSQL</productname>. + </para> + + <para> + These <quote>default variables</quote> were designed to allow you + to handle general connection parameters without heavy code in your + programs. You can prompt the user for a value, put it in the + default variable, and forget it, without having to modify your + environment. The support for default variables can be disabled by + setting the <acronym>-DNO_DEF_VAR</acronym> option in the Python + Setup file. Methods relative to this are specified by te tag [DV]. + </para> + + <para> + All variables are set to <symbol>None</symbol> at module + initialization, specifying that standard environment variables + should be used. + </para> + + <refentry id="pygresql-connect"> + <refmeta> + <refentrytitle>connect</refentrytitle> + <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>connect</refname> + <refpurpose>opens a connection to the database server</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +connect(<optional><replaceable>dbname</replaceable></optional>, <optional><replaceable>host</replaceable></optional>, <optional><replaceable>port</replaceable></optional>, <optional><replaceable>opt</replaceable></optional>, <optional><replaceable>tty</replaceable></optional>, <optional><replaceable>user</replaceable></optional>, <optional><replaceable>passwd</replaceable></optional>) +</synopsis> + + <refsect2 id="pygresql-connect-parameters"> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable>dbname</replaceable></term> + + <listitem> + <para>Name of connected database (string/None).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>host</replaceable></term> + + <listitem> + <para>Name of the server host (string/None).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>port</replaceable></term> + + <listitem> + <para>Port used by the database server (integer/-1).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>opt</replaceable></term> + + <listitem> + <para> + Options for the server (string/None). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>tty</replaceable></term> + + <listitem> + <para> + File or tty for optional debug output from backend + (string/None). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>user</replaceable></term> + + <listitem> + <para> + <productname>PostgreSQL</productname> user (string/None). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>passwd</replaceable></term> + + <listitem> + <para>Password for user (string/None).</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="pygresql-connect-return"> + <title>Return Type</title> + + <variablelist> + <varlistentry> + <term><replaceable>pgobject</replaceable></term> + + <listitem> + <para> + If successful, an object handling a database connection is returned. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="pygresql-connect-exceptions"> + <title>Exceptions</title> + + <variablelist> + <varlistentry> + <term><errorname>TypeError</errorname></term> + + <listitem> + <para> + Bad argument type, or too many arguments. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><errorname>SyntaxError</errorname></term> + + <listitem> + <para> + Duplicate argument definition. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><errorname>pg.error</errorname></term> + + <listitem> + <para> + Some error occurred during pg connection definition. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + (+ all exceptions relative to object allocation) + </para> + </refsect2> + </refsynopsisdiv> + + <refsect1 id="pygresql-connect-description"> + <title>Description</title> + + <para> + This method opens a connection to a specified database on a given + <productname>PostgreSQL</productname> server. You can use + keywords here, as described in the + <productname>Python</productname> tutorial. The names of the + keywords are the name of the parameters given in the syntax + line. For a precise description of the parameters, please refer + to the <productname>PostgreSQL</productname> user manual. + </para> + </refsect1> + + <refsect1 id="pygresql-connect-examples"> + <title>Examples</title> + + <para> +<programlisting> +import pg + +con1 = pg.connect('testdb', 'myhost', 5432, None, None, 'bob', None) +con2 = pg.connect(dbname='testdb', host='localhost', user='bob') +</programlisting> + </para> + </refsect1> + + </refentry> + + + <refentry id="pygresql-get-defhost"> + <refmeta> + <refentrytitle>get_defhost</refentrytitle> + <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>get_defhost</refname> + <refpurpose>get default host name [DV]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +get_defhost() +</synopsis> + + <refsect2 id="pygresql-get-defhost-parameters"> + <title>Parameters</title> + + <para> + none + </para> + </refsect2> + + <refsect2 id="pygresql-get-defhost-return"> + <title>Return Type</title> + + <variablelist> + <varlistentry> + <term>string or None</term> + + <listitem> + <para> + Default host specification + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="pygresql-get-defhost-exceptions"> + <title>Exceptions</title> + + <variablelist> + <varlistentry> + <term><errorname>SyntaxError</errorname></term> + + <listitem> + <para> + Too many arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="pygresql-get-defhost-description"> + <title>Description</title> + + <para> + <function>get_defhost()</function> returns the current default + host specification, or None if the environment variables should + be used. Environment variables will not be looked up. + </para> + </refsect1> + + </refentry> + + + <refentry id="pygresql-set-defhost"> + <refmeta> + <refentrytitle>set_defhost</refentrytitle> + <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo> + </refmeta> + <refnamediv> + <refname>set_defhost</refname> + <refpurpose>set default host name [DV]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +set_defhost(<replaceable>host</replaceable>) +</synopsis> + + <refsect2 id="pygresql-set-defhost-parameters"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>host</replaceable> + </term> + <listitem> + <para>New default host (string/None).</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="pygresql-set-defhost-return"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + string or None + </term> + <listitem> + <para> + Previous default host specification. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="pygresql-set-defhost-exceptions"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad argument type, or too many arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="pygresql-set-defhost-description"> + <title>Description</title> + <para> + <function>set_defhost()</function> sets the default host value + for new connections. If None is supplied as parameter, environment + variables will be used in future connections. It returns the + previous setting for default host. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="pygresql-get-defport"> + <refmeta> + <refentrytitle>get_defport</refentrytitle> + <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo> + </refmeta> + <refnamediv> + <refname>get_defport</refname> + <refpurpose>get default port [DV]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +get_defport() +</synopsis> + + <refsect2 id="R2-PYGRESQL-GET-DEFPORT-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-GET-DEFPORT-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + integer or None + </term> + <listitem> + <para> + Default port specification + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-GET-DEFPORT-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>SyntaxError</errorname> + </term> + <listitem> + <para> + Too many arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-GET-DEFPORT-1"> + <title>Description</title> + <para> + <function>get_defport()</function> returns the current default + port specification, or None if the environment variables should + be used. Environment variables will not be looked up. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-SET-DEFPORT"> + <refmeta> + <refentrytitle>set_defport</refentrytitle> + <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo> + </refmeta> + <refnamediv> + <refname>set_defport</refname> + <refpurpose>set default port [DV]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +set_defport(<replaceable>port</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-SET-DEFPORT-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>port</replaceable> + </term> + <listitem> + <para>New default host (integer/-1).</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-SET-DEFPORT-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + integer or None + </term> + <listitem> + <para> + Previous default port specification. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-SET-DEFPORT-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad argument type, or too many arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-SET-DEFPORT-1"> + <title>Description</title> + <para> + <function>set_defport()</function> sets the default port value + for new connections. If -1 is supplied as parameter, environment + variables will be used in future connections. It returns the + previous setting for default port. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-GET-DEFOPT"> + <refmeta> + <refentrytitle>get_defopt</refentrytitle> + <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo> + </refmeta> + <refnamediv> + <refname>get_defopt</refname> + <refpurpose>get default options specification [DV]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +get_defopt() +</synopsis> + + <refsect2 id="R2-PYGRESQL-GET-DEFOPT-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-GET-DEFOPT-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + string or None + </term> + <listitem> + <para> + Default options specification + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-GET-DEFOPT-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>SyntaxError</errorname> + </term> + <listitem> + <para> + Too many arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-GET-DEFOPT-1"> + <title>Description</title> + <para> + <function>get_defopt()</function> returns the current default + connection options specification, or None if the environment variables should + be used. Environment variables will not be looked up. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-SET-DEFOPT"> + <refmeta> + <refentrytitle>set_defopt</refentrytitle> + <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo> + </refmeta> + <refnamediv> + <refname>set_defopt</refname> + <refpurpose>set options specification [DV]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +set_defopt(<replaceable>options</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-SET-DEFOPT-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>options</replaceable> + </term> + <listitem> + <para>New default connection options (string/None).</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-SET-DEFOPT-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + string or None + </term> + <listitem> + <para> + Previous default opt specification. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-SET-DEFOPT-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad argument type, or too many arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-SET-DEFOPT-1"> + <title>Description</title> + <para> + <function>set_defopt()</function> sets the default connection options value + for new connections. If None is supplied as parameter, environment + variables will be used in future connections. It returns the + previous setting for default options. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-GET-DEFTTY"> + <refmeta> + <refentrytitle>get_deftty</refentrytitle> + <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo> + </refmeta> + <refnamediv> + <refname>get_deftty</refname> + <refpurpose>get default connection debug terminal specification [DV]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +get_deftty() +</synopsis> + + <refsect2 id="R2-PYGRESQL-GET-DEFTTY-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-GET-DEFTTY-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + string or None + </term> + <listitem> + <para> + Default debug terminal specification + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-GET-DEFTTY-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>SyntaxError</errorname> + </term> + <listitem> + <para> + Too many arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-GET-DEFTTY-1"> + <title>Description</title> + <para> + <function>get_deftty()</function> returns the current default + debug terminal specification, or None if the environment variables should + be used. Environment variables will not be looked up. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-SET-DEFTTY"> + <refmeta> + <refentrytitle>set_deftty</refentrytitle> + <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo> + </refmeta> + <refnamediv> + <refname>set_deftty</refname> + <refpurpose>set default debug terminal specification [DV]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +set_deftty(<replaceable>terminal</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-SET-DEFTTY-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>terminal</replaceable> + </term> + <listitem> + <para>New default debug terminal (string/None).</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-SET-DEFTTY-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + string or None + </term> + <listitem> + <para> + Previous default debug terminal specification. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-SET-DEFTTY-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad argument type, or too many arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-SET-DEFTTY-1"> + <title>Description</title> + <para> + <function>set_deftty()</function> sets the default terminal value + for new connections. If None is supplied as parameter, environment + variables will be used in future connections. It returns the + previous setting for default terminal. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-GET-DEFBASE"> + <refmeta> + <refentrytitle>get_defbase</refentrytitle> + <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo> + </refmeta> + <refnamediv> + <refname>get_defbase</refname> + <refpurpose>get default database name specification [DV]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +get_defbase() +</synopsis> + + <refsect2 id="R2-PYGRESQL-GET-DEFBASE-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-GET-DEFBASE-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + string or None + </term> + <listitem> + <para> + Default debug database name specification + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-GET-DEFBASE-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>SyntaxError</errorname> + </term> + <listitem> + <para> + Too many arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-GET-DEFBASE-1"> + <title>Description</title> + <para> + <function>get_defbase()</function> returns the current default + database name specification, or None if the environment variables should + be used. Environment variables will not be looked up. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-SET-DEFBASE"> + <refmeta> + <refentrytitle>set_defbase</refentrytitle> + <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo> + </refmeta> + <refnamediv> + <refname>set_defbase</refname> + <refpurpose>set default database name specification [DV]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +set_defbase(<replaceable>database</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-SET-DEFBASE-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>database</replaceable> + </term> + <listitem> + <para>New default database name (string/None).</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-SET-DEFBASE-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + string or None + </term> + <listitem> + <para> + Previous default database name specification. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-SET-DEFBASE-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad argument type, or too many arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-SET-DEFBASE-1"> + <title>Description</title> + <para> + <function>set_defbase()</function> sets the default database name + for new connections. If None is supplied as parameter, environment + variables will be used in future connections. It returns the + previous setting for default database name. + </para> + </refsect1> + + </refentry> + + </sect1> + + + <sect1 id="pygresql-pg-pgobject"> + <title>Connection object: <classname>pgobject</classname></title> + + <para> + This object handles a connection to the + <productname>PostgreSQL</productname> database. It embeds and + hides all the parameters that define this connection, leaving just + really significant parameters in function calls. + </para> + + <para> + Some methods give direct access to the connection socket. They are + specified by the tag [DA]. <emphasis>Do not use them unless you + really know what you are doing.</emphasis> If you prefer disabling + them, set the <literal>-DNO_DIRECT</literal> option in the + <productname>Python</productname> <filename>Setup</filename> file. + </para> + + <para> + Some other methods give access to large objects. if you want to + forbid access to these from the module, set the + <literal>-DNO_LARGE</literal> option in the + <productname>Python</productname> <filename>Setup</filename> file. + These methods are specified by the tag [LO]. + </para> + + <para> + Every <literal>pgobject</literal> defines a set of read-only + attributes that describe the connection and its status. These + attributes are: + + <variablelist> + <varlistentry> + <term>host</term> + <listitem> + <para> + the host name of the server (string) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>port</term> + <listitem> + <para> + the port of the server (integer) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>db</term> + <listitem> + <para> + the selected database (string) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>options</term> + <listitem> + <para> + the connection options (string) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>tty</term> + <listitem> + <para> + the connection debug terminal (string) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>user</term> + <listitem> + <para> + user name on the database system (string) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>status</term> + <listitem> + <para> + the status of the connection (integer: 1 - OK, 0 - BAD) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>error</term> + <listitem> + <para> + the last warning/error message from the server (string) + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + + <refentry id="PYGRESQL-QUERY"> + <refmeta> + <refentrytitle>query</refentrytitle> + <refmiscinfo>PYGRESQL - Query</refmiscinfo> + </refmeta> + <refnamediv> + <refname>query</refname> + <refpurpose>executes a SQL command</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +query(<replaceable>command</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-QUERY-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>command</replaceable> + </term> + <listitem> + <para>SQL command (string).</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-QUERY-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + pgqueryobject or None + </term> + <listitem> + <para> + Result values. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-QUERY-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad argument type, or too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>ValueError</errorname> + </term> + <listitem> + <para> + Empty SQL query. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Error during query processing, or invalid connection. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-QUERY-1"> + <title>Description</title> + <para> + <function>query()</function> method sends a <acronym>SQL</acronym> + query to the database. If the query is an insert statement, the return + value is the <acronym>OID</acronym> of the newly inserted row. + If it is otherwise a query that does not return a result + (i.e., is not a some kind of <literal>SELECT</literal> statement), it returns None. + Otherwise, it returns a <literal>pgqueryobject</literal> that can be accessed via the + <function>getresult()</function> or <function>dictresult()</function> + methods or simply printed. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-RESET"> + <refmeta> + <refentrytitle>reset</refentrytitle> + <refmiscinfo>PYGRESQL - Reset</refmiscinfo> + </refmeta> + <refnamediv> + <refname>reset</refname> + <refpurpose>resets the connection</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +reset() +</synopsis> + + <refsect2 id="R2-PYGRESQL-RESET-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-RESET-2"> + <title>Return Type</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-RESET-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Too many (any) arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-RESET-1"> + <title>Description</title> + <para> + <function>reset()</function> method resets the current database. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-CLOSE"> + <refmeta> + <refentrytitle>close</refentrytitle> + <refmiscinfo>PYGRESQL - Close</refmiscinfo> + </refmeta> + <refnamediv> + <refname>close</refname> + <refpurpose>close the database connection</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +close() +</synopsis> + + <refsect2 id="R2-PYGRESQL-CLOSE-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-CLOSE-2"> + <title>Return Type</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-CLOSE-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Too many (any) arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-CLOSE-1"> + <title>Description</title> + <para> + <function>close()</function> method closes the database connection. + The connection will be closed in any case when the connection is deleted but this + allows you to explicitly close it. It is mainly here to allow + the DB-SIG API wrapper to implement a close function. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-FILENO"> + <refmeta> + <refentrytitle>fileno</refentrytitle> + <refmiscinfo>PYGRESQL - Fileno</refmiscinfo> + </refmeta> + <refnamediv> + <refname>fileno</refname> + <refpurpose>returns the socket used to connect to the database</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +fileno() +</synopsis> + + <refsect2 id="R2-PYGRESQL-FILENO-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-FILENO-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + socket id + </term> + <listitem> + <para> + The underlying socket id used to connect to the database. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-FILENO-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Too many (any) arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-FILENO-1"> + <title>Description</title> + <para> + <function>fileno()</function> method returns the underlying socket id used to connect + to the database. This is useful for use in <function>select</function> calls, etc. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-GETNOTIFY"> + <refmeta> + <refentrytitle>getnotify</refentrytitle> + <refmiscinfo>PYGRESQL - Getnotify</refmiscinfo> + </refmeta> + <refnamediv> + <refname>getnotify</refname> + <refpurpose>gets the last notify from the server</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +getnotify() +</synopsis> + + <refsect2 id="R2-PYGRESQL-GETNOTIFY-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-GETNOTIFY-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + tuple, None + </term> + <listitem> + <para> + Last notify from server + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-GETNOTIFY-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Too many (any) arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-GETNOTIFY-1"> + <title>Description</title> + <para> + <function>getnotify()</function> method tries to get a notify from + the server (from the <literal>SQL</literal> statement <literal>NOTIFY</literal>). + If the server returns no notify, the methods returns None. + Otherwise, it returns a tuple (couple) <literal>(relname, pid)</literal>, + where <literal>relname</literal> is the name of the notify and <literal>pid</literal> + the process id of the connection that triggered the notify. + Remember to do a listen query first otherwise getnotify will always return None. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-INSERTTABLE"> + <refmeta> + <refentrytitle>inserttable</refentrytitle> + <refmiscinfo>PYGRESQL - Inserttable</refmiscinfo> + </refmeta> + <refnamediv> + <refname>inserttable</refname> + <refpurpose>inserts a list into a table</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-INSERTTABLE-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>table</replaceable> + </term> + <listitem> + <para>The table name (string).</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable>values</replaceable> + </term> + <listitem> + <para>The list of rows values to insert (list).</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-INSERTTABLE-2"> + <title>Return Type</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-INSERTTABLE-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad argument type or too many (any) arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-INSERTTABLE-1"> + <title>Description</title> + <para> + <function>inserttable()</function> method allows to quickly + insert large blocks of data in a table: it inserts the whole + values list into the given table. The list is a list of + tuples/lists that define the values for each inserted row. The + rows values may contain string, integer, long or double (real) + values. <emphasis>Be very careful:</emphasis> this method + does not typecheck the fields according to the table + definition; it just look whether or not it knows how to handle + such types. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-PUTLINE"> + <refmeta> + <refentrytitle>putline</refentrytitle> + <refmiscinfo>PYGRESQL - Putline</refmiscinfo> + </refmeta> + <refnamediv> + <refname>putline</refname> + <refpurpose>writes a line to the server socket [DA]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +putline(<replaceable>line</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-PUTLINE-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>line</replaceable> + </term> + <listitem> + <para>Line to be written (string).</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PUTLINE-2"> + <title>Return Type</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PUTLINE-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad argument type or too many (any) arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PUTLINE-1"> + <title>Description</title> + <para> + <function>putline()</function> method allows to directly write a string to the server socket. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-GETLINE"> + <refmeta> + <refentrytitle>getline</refentrytitle> + <refmiscinfo>PYGRESQL - Getline</refmiscinfo> + </refmeta> + <refnamediv> + <refname>getline</refname> + <refpurpose>gets a line from server socket [DA]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +getline() +</synopsis> + + <refsect2 id="R2-PYGRESQL-GETLINE-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-GETLINE-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + string + </term> + <listitem> + <para> + The line read. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-GETLINE-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad argument type or too many (any) arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-GETLINE-1"> + <title>Description</title> + <para> + <function>getline()</function> method allows to directly read a string from the server socket. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-ENDCOPY"> + <refmeta> + <refentrytitle>endcopy</refentrytitle> + <refmiscinfo>PYGRESQL - Endcopy</refmiscinfo> + </refmeta> + <refnamediv> + <refname>endcopy</refname> + <refpurpose>synchronizes client and server [DA]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +endcopy() +</synopsis> + + <refsect2 id="R2-PYGRESQL-ENDCOPY-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-ENDCOPY-2"> + <title>Return Type</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-ENDCOPY-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad argument type or too many (any) arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-ENDCOPY-1"> + <title>Description</title> + <para> + The use of direct access methods may desynchronize client and server. This + method ensure that client and server will be synchronized. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-LOCREATE"> + <refmeta> + <refentrytitle>locreate</refentrytitle> + <refmiscinfo>PYGRESQL - Locreate</refmiscinfo> + </refmeta> + <refnamediv> + <refname>locreate</refname> + <refpurpose>creates of large object in the database [LO]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +locreate(<replaceable>mode</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-LOCREATE-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>mode</replaceable> + </term> + <listitem> + <para>Large object create mode.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-LOCREATE-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + pglarge + </term> + <listitem> + <para> + Object handling the <productname>PostgreSQL</productname> large object. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-LOCREATE-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad argument type or too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection, or creation error. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-LOCREATE-1"> + <title>Description</title> + <para> + <function>locreate()</function> method creates a large object in the database. + The mode can be defined by OR-ing the constants defined in the pg module + (<literal>INV_READ, INV_WRITE</literal> and <literal>INV_ARCHIVE</literal>). + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-GETLO"> + <refmeta> + <refentrytitle>getlo</refentrytitle> + <refmiscinfo>PYGRESQL - Getlo</refmiscinfo> + </refmeta> + <refnamediv> + <refname>getlo</refname> + <refpurpose>builds a large object from given <literal>oid</literal> [LO]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +getlo(<replaceable>oid</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-GETLO-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>oid</replaceable> + </term> + <listitem> + <para><literal>OID</literal> of the existing large object (integer).</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-GETLO-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + pglarge + </term> + <listitem> + <para> + Object handling the <productname>PostgreSQL</productname> large object. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-GETLO-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad argument type or too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-GETLO-1"> + <title>Description</title> + <para> + <function>getlo()</function> method allows to reuse a formerly + created large object through the <classname>pglarge</classname> interface, providing + the user have its <literal>oid</literal>. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-LOIMPORT"> + <refmeta> + <refentrytitle>loimport</refentrytitle> + <refmiscinfo>PYGRESQL - Loimport</refmiscinfo> + </refmeta> + <refnamediv> + <refname>loimport</refname> + <refpurpose>imports a file to a <productname>PostgreSQL</productname> large object [LO]</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +loimport(<replaceable>filename</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-LOIMPORT-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>filename</replaceable> + </term> + <listitem> + <para>The name of the file to be imported (string).</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-LOIMPORT-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + pglarge + </term> + <listitem> + <para> + Object handling the <productname>PostgreSQL</productname> large object. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-LOIMPORT-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad argument type or too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection, or error during file import. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-LOIMPORT-1"> + <title>Description</title> + <para> + <function>loimport()</function> method allows to create large objects + in a very simple way. You just give the name of a file containing the + data to be use. + </para> + </refsect1> + + </refentry> + + </sect1> + + + <sect1 id="pygresql-pg-DB"> + <title>Database wrapper class: <classname>DB</classname></title> + + <para> + <classname>pg</classname> module contains a class called + <classname>DB</classname>. All <classname>pgobject</classname> + methods are included in this class also. A number of additional + <classname>DB</classname> class methods are described below. The + preferred way to use this module is as follows (See description of + the initialization method below.): + +<programlisting> +import pg + +db = pg.DB(...) + +for r in db.query( + "SELECT foo,bar + FROM foo_bar_table + WHERE foo !~ bar" + ).dictresult(): + + print '%(foo)s %(bar)s' % r +</programlisting> + + The following describes the methods and variables of this class. + </para> + + <para> + The <classname>DB</classname> class is initialized with the same + arguments as the <function>pg.connect</function> method. It also + initializes a few internal variables. The statement <literal>db = + DB()</literal> will open the local database with the name of the + user just like <function>pg.connect()</function> does. + </para> + + <refentry id="PYGRESQL-DB-PKEY"> + <refmeta> + <refentrytitle>pkey</refentrytitle> + <refmiscinfo>PYGRESQL - Pkey</refmiscinfo> + </refmeta> + <refnamediv> + <refname>pkey</refname> + <refpurpose>returns the primary key of a table</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +pkey(<replaceable>table</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-DB-PKEY-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>table</replaceable> + </term> + <listitem> + <para> + name of table. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-DB-PKEY-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + string + </term> + <listitem> + <para> + Name of field which is the primary key of the table. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-DB-PKEY-1"> + <title>Description</title> + <para> + <function>pkey()</function> method returns the primary key + of a table. Note that this raises an exception if the table + does not have a primary key. + </para> + </refsect1> + + </refentry> + + <!-- ********************************************************** --> + + <refentry id="PYGRESQL-DB-GET-DATABASES"> + <refmeta> + <refentrytitle>get_databases</refentrytitle> + <refmiscinfo>PYGRESQL - Get_databases</refmiscinfo> + </refmeta> + <refnamediv> + <refname>get_databases</refname> + <refpurpose>get list of databases in the system</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +get_databases() +</synopsis> + + <refsect2 id="R2-PYGRESQL-DB-GET-DATABASES-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-DB-GET-DATABASES-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + list + </term> + <listitem> + <para> + List of databases in the system. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-DB-GET-DATABASES-1"> + <title>Description</title> + <para> + Although you can do this with a simple select, + it is added here for convenience + </para> + </refsect1> + + </refentry> + + <!-- ********************************************************** --> + + <refentry id="PYGRESQL-DB-GET-TABLES"> + <refmeta> + <refentrytitle>get_tables</refentrytitle> + <refmiscinfo>PYGRESQL - get_tables</refmiscinfo> + </refmeta> + <refnamediv> + <refname>get_tables</refname> + <refpurpose>get list of tables in connected database</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +get_tables() +</synopsis> + + <refsect2 id="R2-PYGRESQL-DB-GET-TABLES-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-DB-GET-TABLES-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + list + </term> + <listitem> + <para> + List of tables in connected database. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-DB-GET-TABLES-1"> + <title>Description</title> + <para> + Although you can do this with a simple select, + it is added here for convenience + </para> + </refsect1> + + </refentry> + + <!-- ********************************************************** --> + + <refentry id="PYGRESQL-DB-GET-ATTNAMES"> + <refmeta> + <refentrytitle>get_attnames</refentrytitle> + <refmiscinfo>PYGRESQL - Get_Attnames</refmiscinfo> + </refmeta> + <refnamediv> + <refname>get_attnames</refname> + <refpurpose>returns the attribute names of a table</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +get_attnames(<replaceable>table</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-DB-GET-ATTNAMES-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>table</replaceable> + </term> + <listitem> + <para> + name of table. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-DB-GET-ATTNAMES-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + list + </term> + <listitem> + <para> + List of attribute names. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-DB-GET-ATTNAMES-1"> + <title>Description</title> + <para> + Given the name of a table, digs out the list of attribute names. + </para> + </refsect1> + + </refentry> + + <!-- ********************************************************** --> + + <refentry id="PYGRESQL-DB-GET"> + <refmeta> + <refentrytitle>get</refentrytitle> + <refmiscinfo>PYGRESQL - Get</refmiscinfo> + </refmeta> + <refnamediv> + <refname>get</refname> + <refpurpose>get a tuple from a database table</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional><replaceable>keyname</replaceable></optional>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-DB-GET-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>table</replaceable> + </term> + <listitem> + <para> + Name of table. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable>arg</replaceable> + </term> + <listitem> + <para> + Either a dictionary or the value to be looked up. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <optional><replaceable>keyname</replaceable></optional> + </term> + <listitem> + <para> + Name of field to use as key (optional). + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-DB-GET-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + dictionary + </term> + <listitem> + <para> + A dictionary mapping attribute names to row values. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-DB-GET-1"> + <title>Description</title> + <para> + This method is the basic mechanism to get a single row. It assumes + that the key specifies a unique row. If keyname is not specified + then the primary key for the table is used. If arg is a dictionary + then the value for the key is taken from it and it is modified to + include the new values, replacing existing values where necessary. + The oid is also put into the dictionary but in order to allow the + caller to work with multiple tables, the attribute name is munged + to make it unique. It consists of the string <literal>oid_</literal> followed by + the name of the table. + </para> + </refsect1> + + </refentry> + + <!-- ********************************************************** --> + + <refentry id="PYGRESQL-DB-INSERT"> + <refmeta> + <refentrytitle>insert</refentrytitle> + <refmiscinfo>PYGRESQL - Insert</refmiscinfo> + </refmeta> + <refnamediv> + <refname>insert</refname> + <refpurpose>insert a tuple into a database table</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-DB-INSERT-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>table</replaceable> + </term> + <listitem> + <para> + Name of table. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable>a</replaceable> + </term> + <listitem> + <para> + A dictionary of values. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-DB-INSERT-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + integer + </term> + <listitem> + <para> + The OID of the newly inserted row. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-DB-INSERT-1"> + <title>Description</title> + <para> + This method inserts values into the table specified filling in the + values from the dictionary. It then reloads the dictionary with the + values from the database. This causes the dictionary to be updated + with values that are modified by rules, triggers, etc. + </para> + </refsect1> + + </refentry> + + <!-- ********************************************************** --> + + <refentry id="PYGRESQL-DB-UPDATE"> + <refmeta> + <refentrytitle>update</refentrytitle> + <refmiscinfo>PYGRESQL - Update</refmiscinfo> + </refmeta> + <refnamediv> + <refname>update</refname> + <refpurpose>update a database table</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +update(<replaceable>table</replaceable>, <replaceable>a</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-DB-UPDATE-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>table</replaceable> + </term> + <listitem> + <para> + Name of table. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable>a</replaceable> + </term> + <listitem> + <para> + A dictionary of values. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-DB-UPDATE-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + integer + </term> + <listitem> + <para> + The OID of the newly updated row. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-DB-UPDATE-1"> + <title>Description</title> + <para> + Similar to insert but updates an existing row. The update is based + on the OID value as munged by get. The array returned is the + one sent modified to reflect any changes caused by the update due + to triggers, rules, defaults, etc. + </para> + </refsect1> + + </refentry> + + <!-- ********************************************************** --> + + <refentry id="PYGRESQL-DB-CLEAR"> + <refmeta> + <refentrytitle>clear</refentrytitle> + <refmiscinfo>PYGRESQL - Clear</refmiscinfo> + </refmeta> + <refnamediv> + <refname>clear</refname> + <refpurpose>clear a database table</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +clear(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></optional>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-DB-CLEAR-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>table</replaceable> + </term> + <listitem> + <para> + Name of table. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <optional><replaceable>a</replaceable></optional> + </term> + <listitem> + <para> + A dictionary of values. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-DB-CLEAR-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + dictionary + </term> + <listitem> + <para> + A dictionary with an empty row. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-DB-CLEAR-1"> + <title>Description</title> + <para> + This method clears all the attributes to values determined by the types. + Numeric types are set to 0, dates are set to <literal>'today'</literal> and everything + else is set to the empty string. If the array argument is present, + it is used as the array and any entries matching attribute names + are cleared with everything else left unchanged. + </para> + </refsect1> + + </refentry> + + <!-- ********************************************************** --> + + <refentry id="PYGRESQL-DB-DELETE"> + <refmeta> + <refentrytitle>delete</refentrytitle> + <refmiscinfo>PYGRESQL - Delete</refmiscinfo> + </refmeta> + <refnamediv> + <refname>delete</refname> + <refpurpose>deletes the row from a table</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></optional>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-DB-DELETE-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>table</replaceable> + </term> + <listitem> + <para> + Name of table. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <optional><replaceable>a</replaceable></optional> + </term> + <listitem> + <para> + A dictionary of values. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-DB-DELETE-2"> + <title>Return Type</title> + <para> + none + </para> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-DB-DELETE-1"> + <title>Description</title> + <para> + This method deletes the row from a table. It deletes based on the OID + as munged as described above. + </para> + </refsect1> + + </refentry> + + <!-- ********************************************************** --> + + </sect1> + + <!-- ********************************************************** --> + <!-- ********************************************************** --> + + <sect1 id="pygresql-pg-pgqueryobject"> + <title>Query result object: <literal>pgqueryobject</literal></title> + + <!-- ********************************************************** --> + + <refentry id="PYGRESQL-PGQUERYOBJECT-GETRESULT"> + <refmeta> + <refentrytitle>getresult</refentrytitle> + <refmiscinfo>PYGRESQL - Getresult</refmiscinfo> + </refmeta> + <refnamediv> + <refname>getresult</refname> + <refpurpose>gets the values returned by the query</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +getresult() +</synopsis> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-GETRESULT-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-GETRESULT-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + list + </term> + <listitem> + <para> + List of tuples. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-GETRESULT-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>SyntaxError</errorname> + </term> + <listitem> + <para> + Too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid previous result. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-GETRESULT-1"> + <title>Description</title> + <para> + <function>getresult()</function> method returns the list of the values returned by the query. + More information about this result may be accessed using <function>listfields</function>, + <function>fieldname</function> and <function>fieldnum</function> methods. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-PGQUERYOBJECT-DICTRESULT"> + <refmeta> + <refentrytitle>dictresult</refentrytitle> + <refmiscinfo>PYGRESQL - Dictresult</refmiscinfo> + </refmeta> + <refnamediv> + <refname>dictresult</refname> + <refpurpose>like getresult but returns a list of dictionaries</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +dictresult() +</synopsis> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-DICTRESULT-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-DICTRESULT-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + list + </term> + <listitem> + <para> + List of dictionaries. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-DICTRESULT-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>SyntaxError</errorname> + </term> + <listitem> + <para> + Too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid previous result. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-DICTRESULT-1"> + <title>Description</title> + <para> + <function>dictresult()</function> method returns the list of the values returned by the query + with each tuple returned as a dictionary with the field names + used as the dictionary index. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-PGQUERYOBJECT-LISTFIELDS"> + <refmeta> + <refentrytitle>listfields</refentrytitle> + <refmiscinfo>PYGRESQL - Listfields</refmiscinfo> + </refmeta> + <refnamediv> + <refname>listfields</refname> + <refpurpose>lists the fields names of the query result</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +listfields() +</synopsis> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + list + </term> + <listitem> + <para> + field names + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>SyntaxError</errorname> + </term> + <listitem> + <para> + Too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid query result, or invalid connection. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-1"> + <title>Description</title> + <para> + <function>listfields()</function> method returns the list of field names defined for the + query result. The fields are in the same order as the result values. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-PGQUERYOBJECT-FIELDNAME"> + <refmeta> + <refentrytitle>fieldname</refentrytitle> + <refmiscinfo>PYGRESQL - Fieldname</refmiscinfo> + </refmeta> + <refnamediv> + <refname>fieldname</refname> + <refpurpose>field number-name conversion</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +fieldname(<replaceable>i</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>i</replaceable> + </term> + <listitem> + <para> + field number (integer). + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + string + </term> + <listitem> + <para> + field name. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad parameter type, or too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable>ValueError</replaceable> + </term> + <listitem> + <para> + Invalid field number. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid query result, or invalid connection. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-FIELDNAME-1"> + <title>Description</title> + <para> + <function>fieldname()</function> method allows to find a field name from its rank number. It can be + useful for displaying a result. The fields are in the same order than the + result values. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-PGQUERYOBJECT-FIELDNUM"> + <refmeta> + <refentrytitle>fieldnum</refentrytitle> + <refmiscinfo>PYGRESQL - Fieldnum</refmiscinfo> + </refmeta> + <refnamediv> + <refname>fieldnum</refname> + <refpurpose>field name-number conversion</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +fieldnum(<replaceable>name</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>name</replaceable> + </term> + <listitem> + <para> + field name (string). + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + integer + </term> + <listitem> + <para> + field number (integer). + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad parameter type, or too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable>ValueError</replaceable> + </term> + <listitem> + <para> + Unknown field name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid query result, or invalid connection. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-FIELDNUM-1"> + <title>Description</title> + <para> + <function>fieldnum()</function> method returns a field number from its name. + It can be used to build a function that converts result list strings to their correct + type, using a hardcoded table definition. The number returned is the + field rank in the result values list. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-PGQUERYOBJECT-NTUPLES"> + <refmeta> + <refentrytitle>ntuples</refentrytitle> + <refmiscinfo>PYGRESQL - Ntuples</refmiscinfo> + </refmeta> + <refnamediv> + <refname>ntuples</refname> + <refpurpose>returns the number of tuples in query object</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +ntuples() +</synopsis> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-NTUPLES-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-NTUPLES-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + integer + </term> + <listitem> + <para> + The number of tuples in query object. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-NTUPLES-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>SyntaxError</errorname> + </term> + <listitem> + <para> + Too many arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-NTUPLES-1"> + <title>Description</title> + <para> + <function>ntuples()</function> method returns the number of tuples found in a query. + </para> + </refsect1> + + </refentry> + + </sect1> + + + <sect1 id="pygresql-pg-pglarge"> + <title>Large Object: <classname>pglarge</classname></title> + + <para> + This object handles all the request concerning a + <productname>PostgreSQL</productname> large object. It embeds and + hides all the <quote>recurrent</quote> variables (object oid and + connection), exactly in the same way + <classname>pgobject</classname>s do, thus only keeping significant + parameters in function calls. It keeps a reference to the <classname>pgobject</classname> + used for its creation, sending requests though with its + parameters. Any modification but dereferencing the + <classname>pgobject</classname> will thus affect the + <classname>pglarge</classname> object. Dereferencing the initial + <classname>pgobject</classname> is not a problem since + <application>Python</application> will not deallocate it before the + large object dereference it. All functions return a generic error + message on call error, whatever the exact error was. The + <structfield>error</structfield> attribute of the object allows to + get the exact error message. + </para> + + <para> + <classname>pglarge</classname> objects define a read-only set of + attributes that allow to get some information about it. These + attributes are: + + <variablelist> + <varlistentry> + <term>oid</term> + <listitem> + <para> + the oid associated with the object + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>pgcnx</term> + <listitem> + <para> + the <classname>pgobject</classname> associated with the object + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>error</term> + <listitem> + <para> + the last warning/error message of the connection + </para> + </listitem> + </varlistentry> + </variablelist> + + <note> + <title>Be careful</title> + + <para> + In multithreaded environments, <structfield>error</structfield> + may be modified by another thread using the same + <classname>pgobject</classname>. Remember these object are + shared, not duplicated; you should provide some locking to be + able if you want to check this. The oid attribute is very + interesting because it allow you reuse the oid later, creating + the <classname>pglarge</classname> object with a <classname>pgobject</classname> + <function>getlo()</function> method call. + </para> + </note> + </para> + + <para> + See also <xref linkend="largeobjects"> for more information about the + <productname>PostgreSQL</productname> large object interface. + </para> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-PGLARGEOBJECT-OPEN"> + <refmeta> + <refentrytitle>open</refentrytitle> + <refmiscinfo>PYGRESQL - Open</refmiscinfo> + </refmeta> + <refnamediv> + <refname>open</refname> + <refpurpose>opens a large object</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +open(<replaceable>mode</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>mode</replaceable> + </term> + <listitem> + <para> + open mode definition (integer). + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-2"> + <title>Return Type</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad parameter type, or too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>IOError</errorname> + </term> + <listitem> + <para> + Already opened object, or open error. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-OPEN-1"> + <title>Description</title> + <para> + <function>open()</function> method opens a large object for reading/writing, + in the same way than the <acronym>UNIX</acronym> <function>open()</function> + function. The mode value can be obtained by OR-ing the constants defined in + the pg module (<literal>INV_READ, INV_WRITE</literal>). + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-PGLARGEOBJECT-CLOSE"> + <refmeta> + <refentrytitle>close</refentrytitle> + <refmiscinfo>PYGRESQL - Close</refmiscinfo> + </refmeta> + <refnamediv> + <refname>close</refname> + <refpurpose>closes the large object</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +close() +</synopsis> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-CLOSE-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-CLOSE-2"> + <title>Return Type</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-CLOSE-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>SyntaxError</errorname> + </term> + <listitem> + <para> + Too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>IOError</errorname> + </term> + <listitem> + <para> + Object is not opened, or close error. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-CLOSE-1"> + <title>Description</title> + <para> + <function>close()</function> method closes previously opened large object, + in the same way than the <acronym>UNIX</acronym> <function>close()</function> function. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-PGLARGEOBJECT-READ"> + <refmeta> + <refentrytitle>read</refentrytitle> + <refmiscinfo>PYGRESQL - Read</refmiscinfo> + </refmeta> + <refnamediv> + <refname>read</refname> + <refpurpose>reads from the large object</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +read(<replaceable>size</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>size</replaceable> + </term> + <listitem> + <para> + Maximal size of the buffer to be read (integer). + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + string + </term> + <listitem> + <para> + The read buffer. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad parameter type, or too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>IOError</errorname> + </term> + <listitem> + <para> + Object is not opened, or read error. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection or invalid object. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-READ-1"> + <title>Description</title> + <para> + <function>read()</function> method allows to read data from the large object, + starting at current position. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-PGLARGEOBJECT-WRITE"> + <refmeta> + <refentrytitle>write</refentrytitle> + <refmiscinfo>PYGRESQL - Write</refmiscinfo> + </refmeta> + <refnamediv> + <refname>write</refname> + <refpurpose>writes to the large object</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +write(<replaceable>string</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>string</replaceable> + </term> + <listitem> + <para> + Buffer to be written (string). + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-2"> + <title>Return Type</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad parameter type, or too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>IOError</errorname> + </term> + <listitem> + <para> + Object is not opened, or write error. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection or invalid object. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-WRITE-1"> + <title>Description</title> + <para> + <function>write()</function> method allows to write data to the large object, + starting at current position. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-PGLARGEOBJECT-SEEK"> + <refmeta> + <refentrytitle>seek</refentrytitle> + <refmiscinfo>PYGRESQL - Seek</refmiscinfo> + </refmeta> + <refnamediv> + <refname>seek</refname> + <refpurpose>change current position in the large object</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>offset</replaceable> + </term> + <listitem> + <para> + Position offset (integer). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable>whence</replaceable> + </term> + <listitem> + <para> + Positional parameter (integer). + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + integer + </term> + <listitem> + <para> + New current position in the object. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad parameter type, or too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>IOError</errorname> + </term> + <listitem> + <para> + Object is not opened, or seek error. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection or invalid object. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-SEEK-1"> + <title>Description</title> + <para> + <function>seek()</function> method allows to move the cursor position + in the large object. The whence parameter can be obtained by OR-ing the constants defined in the + <literal>pg</literal> module (<literal>SEEK_SET, SEEK_CUR, SEEK_END</literal>). + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-PGLARGEOBJECT-TELL"> + <refmeta> + <refentrytitle>tell</refentrytitle> + <refmiscinfo>PYGRESQL - Tell</refmiscinfo> + </refmeta> + <refnamediv> + <refname>tell</refname> + <refpurpose>returns current position in the large object</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +tell() +</synopsis> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-TELL-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-TELL-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + integer + </term> + <listitem> + <para> + Current position in the object. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-TELL-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>SyntaxError</errorname> + </term> + <listitem> + <para> + Too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>IOError</errorname> + </term> + <listitem> + <para> + Object is not opened, or seek error. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection or invalid object. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-TELL-1"> + <title>Description</title> + <para> + <function>tell()</function> method allows to get the current position in the large object. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-PGLARGEOBJECT-UNLINK"> + <refmeta> + <refentrytitle>unlink</refentrytitle> + <refmiscinfo>PYGRESQL - Unlink</refmiscinfo> + </refmeta> + <refnamediv> + <refname>unlink</refname> + <refpurpose>deletes the large object</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +unlink() +</synopsis> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-UNLINK-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-UNLINK-2"> + <title>Return Type</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-UNLINK-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>SyntaxError</errorname> + </term> + <listitem> + <para> + Too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>IOError</errorname> + </term> + <listitem> + <para> + Object is not closed, or unlink error. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection or invalid object. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-UNLINK-1"> + <title>Description</title> + <para> + <function>unlink()</function> method unlinks (deletes) the large object. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-PGLARGEOBJECT-SIZE"> + <refmeta> + <refentrytitle>size</refentrytitle> + <refmiscinfo>PYGRESQL - Size</refmiscinfo> + </refmeta> + <refnamediv> + <refname>size</refname> + <refpurpose>gives the large object size</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +size() +</synopsis> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SIZE-1"> + <title>Parameters</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SIZE-2"> + <title>Return Type</title> + <variablelist> + <varlistentry> + <term> + integer + </term> + <listitem> + <para> + The large object size. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SIZE-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>SyntaxError</errorname> + </term> + <listitem> + <para> + Too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>IOError</errorname> + </term> + <listitem> + <para> + Object is not opened, or seek/tell error. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection or invalid object. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-SIZE-1"> + <title>Description</title> + <para> + <function>size()</function> method allows to get the size of + the large object. It was implemented because this function + is very useful for a WWW interfaced database. + Currently the large object needs to be opened. + </para> + </refsect1> + + </refentry> + +<!-- ********************************************************** --> + + <refentry id="PYGRESQL-PGLARGEOBJECT-EXPORT"> + <refmeta> + <refentrytitle>export</refentrytitle> + <refmiscinfo>PYGRESQL - Export</refmiscinfo> + </refmeta> + <refnamediv> + <refname>export</refname> + <refpurpose>saves the large object to file</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +export(<replaceable>filename</replaceable>) +</synopsis> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-1"> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term> + <replaceable>filename</replaceable> + </term> + <listitem> + <para> + The file to be created. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-2"> + <title>Return Type</title> + <para> + none + </para> + </refsect2> + + <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-3"> + <title>Exceptions</title> + <variablelist> + <varlistentry> + <term> + <errorname>TypeError</errorname> + </term> + <listitem> + <para> + Bad argument type, or too many arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>IOError</errorname> + </term> + <listitem> + <para> + Object is not closed, or export error. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <errorname>pg.error</errorname> + </term> + <listitem> + <para> + Invalid connection or invalid object. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsynopsisdiv> + + <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-EXPORT-1"> + <title>Description</title> + <para> + <function>export()</function> method allows to dump the + content of a large object in a very simple way. + The exported file is created on the host of the program, + not the server host. + </para> + </refsect1> + + </refentry> + + </sect1> + + + <sect1 id="pygresql-db-api"> + <title><acronym>DB-API</acronym> Interface</title> + + <comment> + This section needs to be written. + </comment> + + <para> + See <ulink + url="http://www.python.org/topics/database/DatabaseAPI-2.0.html" + >http://www.python.org/topics/database/DatabaseAPI-2.0.html</ulink> + for a description of the <acronym>DB-API</acronym> 2.0. + </para> + </sect1> + +</chapter> |