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