granicus.if.org Git - postgresql/blob - doc/src/sgml/pygresql.sgml

   1 <!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/pygresql.sgml,v 1.4 2001/11/19 03:58:24 tgl Exp $ -->
   2
   3 <chapter id="pygresql">
   4  <title><application>PyGreSQL</application> - <application>Python</application> Interface</title>
   5
   6  <note>
   7   <title>Author</title>
   8   <para>
   9    Written by D'Arcy J.M. Cain (<email>darcy@druid.net</email>).
  10    Based heavily on code written by Pascal Andre
  11    <email>andre@chimay.via.ecp.fr</email>.  Copyright &copy; 1995,
  12    Pascal Andre.  Further modifications Copyright &copy; 1997-2000 by
  13    D'Arcy J.M. Cain.
  14   </para>
  15  </note>
  16
  17
  18 <![IGNORE[
  19  <sect1 id="pygresql-install">
  20   <title>Installation</title>
  21
  22   <itemizedlist>
  23    <listitem>
  24     <para>
  25      If you are on <acronym>NetBSD</acronym>, look in the packages
  26      directory under databases. If it isn't there yet, it should be
  27      there shortly.  You can also pick up the package files from
  28      <ulink url="ftp://ftp.druid.net/pub/distrib/pygresql.pkg.tgz"
  29      >ftp://ftp.druid.net/pub/distrib/pygresql.pkg.tgz</ulink>.  There
  30      is also a package in the <acronym>FreeBSD</acronym> ports
  31      collection but as I write this it is at version 2.1.  I will try
  32      to get that updated as well.
  33     </para>
  34    </listitem>
  35
  36    <listitem>
  37     <para>
  38      For Linux installation look at <filename>README.linux</filename>.
  39      If you're on an <acronym>x86</acronym> system that uses
  40      <acronym>RPMs</acronym>, then you can pick up an
  41      <acronym>RPM</acronym> at <ulink
  42      url="ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm"
  43      >ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm</ulink>.
  44     </para>
  45    </listitem>
  46
  47    <listitem>
  48     <para>
  49      Note that if you are using the <acronym>DB-API</acronym> module
  50      you must also install <acronym>mxDateTime</acronym> from <ulink
  51      url="http://starship.python.net/~lemburg/mxDateTime.html"
  52      >http://starship.python.net/~lemburg/mxDateTime.html</ulink>.
  53     </para>
  54    </listitem>
  55
  56    <listitem>
  57     <para>
  58      Also, check out <filename>setup.py</filename> for an alternate
  59      method of installing the package using Python's Distutils.
  60     </para>
  61    </listitem>
  62
  63   </itemizedlist>
  64
  65   <para>
  66    You have two options. You can compile
  67    <productname>PyGreSQL</productname> as a stand-alone module or you
  68    can build it into the <productname>Python</productname>
  69    interpreter.
  70   </para>
  71
  72   <sect2>
  73    <title>General</title>
  74
  75    <itemizedlist>
  76     <listitem>
  77      <para>
  78       You must first have installed <productname>Python</productname>
  79       and <productname>PostgreSQL</productname> on your system.  The
  80       header files and developer's libraries for both
  81       <productname>Python</productname> and
  82       <productname>PostgreSQL</productname> must be installed on your
  83       system before you can build <productname>PyGreSQL</productname>.
  84       If you built both <productname>Python</productname> and
  85       <productname>PostgreSQL</productname> from source, you should be
  86       fine.  If your system uses some package mechanism (such as
  87       <acronym>RPM</acronym> or <acronym>NetBSD</acronym> packages),
  88       then you probably need to install packages such as
  89       <acronym>Python-devel</acronym> in addition to the
  90       <productname>Python</productname> package.
  91      </para>
  92     </listitem>
  93
  94     <listitem>
  95      <para>
  96       <productname>PyGreSQL</productname> is implemented as three
  97       parts, a C module labeled <acronym>_pg</acronym> and two
  98       <productname>Python</productname> wrappers called
  99       <filename>pg.py</filename> and <filename>pgdb.py</filename>.
 100       This changed between 2.1 and 2.2 and again in 3.0.  These
 101       changes should not affect any existing programs but the
 102       installation is slightly different.
 103      </para>
 104     </listitem>
 105
 106     <listitem>
 107      <para>
 108       Download and unpack the <productname>PyGreSQL</productname>
 109       tarball if you haven't already done so.
 110      </para>
 111     </listitem>
 112    </itemizedlist>
 113   </sect2>
 114
 115   <sect2>
 116    <title>Stand-alone</title>
 117
 118    <itemizedlist>
 119     <listitem>
 120      <para>
 121       In the directory containing <filename>pgmodule.c</filename>, run
 122       the following command
 123
 124 <programlisting>
 125 cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c
 126 </programlisting>
 127
 128       where:
 129       <itemizedlist>
 130        <listitem>
 131         <para>
 132          [pyInc] = path of the <productname>Python</productname>
 133          include (usually <filename>Python.h</filename>)
 134         </para>
 135        </listitem>
 136
 137        <listitem>
 138         <para>
 139          [pgInc] = path of the <productname>PostgreSQL</productname>
 140          include (usually <filename>postgres.h</filename>)
 141         </para>
 142        </listitem>
 143
 144        <listitem>
 145         <para>
 146          [pgLib] = path of the <productname>PostgreSQL</productname>
 147          libraries (usually <filename>libpq.so</filename> or
 148          <filename>libpq.a</filename>)
 149         </para>
 150        </listitem>
 151       </itemizedlist>
 152
 153       Some options may be added to this line:
 154       <itemizedlist>
 155        <listitem>
 156         <para>
 157          <literal>-DNO_DEF_VAR</literal> - no default variables
 158          support
 159         </para>
 160        </listitem>
 161
 162        <listitem>
 163         <para>
 164          <literal>-DNO_DIRECT</literal>   - no direct access methods
 165         </para>
 166        </listitem>
 167
 168        <listitem>
 169         <para>
 170          <literal>-DNO_LARGE</literal>    - no large object support
 171         </para>
 172        </listitem>
 173
 174        <listitem>
 175         <para>
 176          <literal>-DNO_SNPRINTF</literal> - if running a system with
 177          no snprintf call
 178         </para>
 179        </listitem>
 180
 181        <listitem>
 182         <para>
 183          <literal>-DNO_PQSOCKET</literal> - if running an older
 184          <productname>PostgreSQL</productname>
 185         </para>
 186        </listitem>
 187       </itemizedlist>
 188
 189       On some systems you may need to include
 190       <literal>-lcrypt</literal> in the list of libraries to make it
 191       compile.
 192
 193       Define <literal>DNO_PQSOCKET</literal> if you are using a
 194       version of <productname>PostgreSQL</productname> before 6.4 that
 195       does not have the <function>PQsocket</function> function.  The
 196       other options will be described in the next sections.
 197      </para>
 198     </listitem>
 199    <listitem>
 200
 201    <para>
 202     Test the new module.  Something like the following should work.
 203 <screen>
 204 <prompt>$</prompt> <userinput>python</userinput>
 205
 206 <prompt>&gt;&gt;&gt;</prompt> <userinput>import _pg</userinput>
 207 <prompt>&gt;&gt;&gt;</prompt> <userinput>db = _pg.connect('thilo', 'localhost')</userinput>
 208 <prompt>&gt;&gt;&gt;</prompt> <userinput>db.query("INSERT INTO test VALUES ('ping', 'pong');")</userinput>
 209 18304
 210 <prompt>&gt;&gt;&gt;</prompt> <userinput>db.query("SELECT * FROM test;")</userinput>
 211  eins | zwei
 212 ------+------
 213  ping | pong
 214 (1 row)
 215 </screen>
 216           </para>
 217         </listitem>
 218         <listitem>
 219           <para>
 220             Finally, move the <filename>_pg.so</filename>,
 221             <filename>pg.py</filename>, and <filename>pgdb.py</filename>
 222             to a directory in your <literal>PYTHONPATH</literal>.
 223             A good place would be
 224             <filename>/usr/lib/python1.5/site-python</filename>
 225             if your <productname>Python</productname> modules are in
 226             <filename>/usr/lib/python1.5</filename>.
 227           </para>
 228         </listitem>
 229       </itemizedlist>
 230     </sect2>
 231
 232
 233     <sect2>
 234       <title>Built-in to python interpreter</title>
 235
 236       <itemizedlist>
 237         <listitem>
 238           <para>
 239             Find the directory where your <filename>Setup</filename>
 240             file lives (usually <filename>??/Modules</filename>) in
 241             the <productname>Python</productname> source hierarchy and
 242             copy or symlink the <filename>pgmodule.c</filename> file there.
 243           </para>
 244         </listitem>
 245         <listitem>
 246           <para>
 247             Add the following line to your Setup file
 248             <ProgramListing>
 249 _pg  pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems
 250             </ProgramListing>
 251             where:
 252             <itemizedlist>
 253               <listitem>
 254                 <para>
 255                   [pgInc] = path of the <productname>PostgreSQL</productname>
 256                   include (usually <filename>postgres.h</filename>)
 257                 </para>
 258               </listitem>
 259               <listitem>
 260                 <para>
 261                   [pgLib] = path of the <productname>PostgreSQL</productname>
 262                   libraries (usually <filename>libpq.so</filename>
 263                   or <filename>libpq.a</filename>)
 264                 </para>
 265               </listitem>
 266             </itemizedlist>
 267             Some options may be added to this line:
 268             <itemizedlist>
 269               <listitem>
 270                 <para>
 271                   <literal>-DNO_DEF_VAR</literal>  - no default variables
 272                   support
 273                 </para>
 274               </listitem>
 275               <listitem>
 276                 <para>
 277                   <literal>-DNO_DIRECT</literal>   - no direct access methods
 278                 </para>
 279               </listitem>
 280               <listitem>
 281                 <para>
 282                   <literal>-DNO_LARGE</literal>    - no large object support
 283                 </para>
 284               </listitem>
 285               <listitem>
 286                 <para>
 287                   <literal>-DNO_SNPRINTF</literal> - if running a system with
 288                   no snprintf call
 289                 </para>
 290               </listitem>
 291               <listitem>
 292                 <para>
 293                   <literal>-DNO_PQSOCKET</literal> - if running an older
 294                   <productname>PostgreSQL</productname>
 295                 </para>
 296               </listitem>
 297             </itemizedlist>
 298
 299             Define <literal>DNO_PQSOCKET</literal> if you are using a version of
 300             <productname>PostgreSQL</productname> before 6.4
 301             that does not have the <function>PQsocket</function> function.
 302             The other options will be described in the next sections.
 303           </para>
 304         </listitem>
 305         <listitem>
 306           <para>
 307             If you want a shared module, make sure that the
 308             <literal>*shared*</literal> keyword is uncommented and
 309             add the above line below it. You used to need to install
 310             your shared modules with <literal>make sharedinstall</> but this no
 311             longer seems to be true.
 312           </para>
 313         </listitem>
 314         <listitem>
 315           <para>
 316             Copy <filename>pg.py</filename> to the lib directory where
 317             the rest of your modules are. For example, that's
 318             <filename>/usr/local/lib/Python</filename> on my system.
 319           </para>
 320         </listitem>
 321         <listitem>
 322           <para>
 323             Rebuild <productname>Python</productname> from the root
 324             directory of the <productname>Python</productname> source
 325             hierarchy by running
 326             <ProgramListing>
 327 make -f Makefile.pre.in boot
 328 make && make install
 329             </ProgramListing>
 330           </para>
 331         </listitem>
 332         <listitem>
 333           <para>
 334             For more details read the documentation at the top of
 335             <filename>Makefile.pre.in</filename>
 336           </para>
 337         </listitem>
 338       </itemizedlist>
 339     </sect2>
 340
 341   </sect1>
 342
 343 ]]>
 344
 345  <sect1 id="pygresql-pg">
 346   <title>The <literal>pg</literal> Module</title>
 347
 348   <para>
 349    You may either choose to use the old mature interface provided by
 350    the <literal>pg</literal> module or otherwise the newer
 351    <literal>pgdb</literal> interface compliant with the <ulink
 352    url="http://www.python.org/topics/database/DatabaseAPI-2.0.html"
 353    ><acronym>DB-API 2.0</acronym></ulink> specification developed by
 354    the <productname>Python</productname> <acronym>DB-SIG</acronym>.
 355   </para>
 356
 357   <para>
 358    Here we describe only the older <literal>pg</literal>
 359    <acronym>API</acronym>. As long as
 360    <productname>PyGreSQL</productname> does not contain a description
 361    of the <acronym>DB-API</acronym> you should read about the
 362    <acronym>API</acronym> at <ulink
 363    url="http://www.python.org/topics/database/DatabaseAPI-2.0.html"
 364    >http://www.python.org/topics/database/DatabaseAPI-2.0.html</ulink>.
 365   </para>
 366
 367   <para>
 368    A tutorial-like introduction to the <acronym>DB-API</acronym> can
 369    be found at <ulink
 370    url="http://www2.linuxjournal.com/lj-issues/issue49/2605.html"
 371    >http://www2.linuxjournal.com/lj-issues/issue49/2605.html</ulink>
 372   </para>
 373
 374   <para>
 375    The <literal>pg</literal> module defines three objects:
 376    <itemizedlist>
 377     <listitem>
 378      <para>
 379       <classname>pgobject</classname>, which handles the connection and all the
 380       requests to the database,
 381      </para>
 382     </listitem>
 383
 384     <listitem>
 385      <para>
 386       <classname>pglargeobject</classname>, which handles all the accesses
 387       to <productname>Postgres</productname> large objects, and
 388      </para>
 389     </listitem>
 390
 391     <listitem>
 392      <para>
 393       <literal>pgqueryobject</literal> that handles query results.
 394      </para>
 395     </listitem>
 396    </itemizedlist>
 397   </para>
 398
 399   <para>
 400    If you want to see a simple example of the use of some of these
 401    functions, see <ulink url="http://www.druid.net/rides"
 402    >http://www.druid.net/rides</ulink> where I have a link at the
 403    bottom to the actual <productname>Python</productname> code for the
 404    page.
 405   </para>
 406
 407   <sect2>
 408    <title>Constants</title>
 409
 410    <para>
 411     Some constants are defined in the <literal>pg</literal> module
 412     dictionary.  They are intended to be used as a parameters for
 413     methods calls.  You should refer to the <literal>libpq</literal>
 414     description (<xref linkend="libpq">) for more information about
 415     them. These constants are:
 416
 417     <variablelist>
 418      <varlistentry>
 419       <term><varname>INV_READ</varname></term>
 420       <term><varname>INV_WRITE</varname></term>
 421       <listitem>
 422        <para>
 423         large objects access modes, used by
 424         <function>(pgobject.)locreate</function> and
 425         <function>(pglarge.)open</function>.
 426        </para>
 427       </listitem>
 428      </varlistentry>
 429
 430      <varlistentry>
 431       <term><varname>SEEK_SET</varname></term>
 432       <term><varname>SEEK_CUR</varname></term>
 433       <term><varname>SEEK_END</varname></term>
 434       <listitem>
 435        <para>
 436         positional flags, used by <function>(pglarge.)seek</function>.
 437        </para>
 438       </listitem>
 439      </varlistentry>
 440
 441      <varlistentry>
 442       <term><varname>version</varname></term>
 443       <term><varname>__version__</varname></term>
 444       <listitem>
 445        <para>
 446         constants that give the current version
 447        </para>
 448       </listitem>
 449      </varlistentry>
 450     </variablelist>
 451    </para>
 452   </sect2>
 453  </sect1>
 454
 455
 456  <sect1 id="pygresql-pg-functions">
 457   <title><literal>pg</literal> Module Functions</title>
 458
 459   <para>
 460    <literal>pg</literal> module defines only a few methods that allow
 461    to connect to a database and to define <quote>default
 462    variables</quote> that override the environment variables used by
 463    <productname>PostgreSQL</productname>.
 464   </para>
 465
 466   <para>
 467    These <quote>default variables</quote> were designed to allow you
 468    to handle general connection parameters without heavy code in your
 469    programs. You can prompt the user for a value, put it in the
 470    default variable, and forget it, without having to modify your
 471    environment. The support for default variables can be disabled by
 472    setting the <acronym>-DNO_DEF_VAR</acronym> option in the Python
 473    Setup file. Methods relative to this are specified by te tag [DV].
 474   </para>
 475
 476   <para>
 477    All variables are set to <symbol>None</symbol> at module
 478    initialization, specifying that standard environment variables
 479    should be used.
 480   </para>
 481
 482   <refentry id="pygresql-connect">
 483    <refmeta>
 484     <refentrytitle>connect</refentrytitle>
 485     <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
 486    </refmeta>
 487
 488    <refnamediv>
 489     <refname>connect</refname>
 490     <refpurpose>opens a connection to the database server</refpurpose>
 491    </refnamediv>
 492
 493    <refsynopsisdiv>
 494 <synopsis>
 495 connect(<optional><replaceable>dbname</replaceable></optional>, <optional><replaceable>host</replaceable></optional>, <optional><replaceable>port</replaceable></optional>, <optional><replaceable>opt</replaceable></optional>, <optional><replaceable>tty</replaceable></optional>, <optional><replaceable>user</replaceable></optional>, <optional><replaceable>passwd</replaceable></optional>)
 496 </synopsis>
 497
 498     <refsect2 id="pygresql-connect-parameters">
 499      <title>Parameters</title>
 500
 501      <variablelist>
 502       <varlistentry>
 503        <term><replaceable>dbname</replaceable></term>
 504
 505        <listitem>
 506         <para>Name of connected database (string/None).</para>
 507        </listitem>
 508       </varlistentry>
 509
 510       <varlistentry>
 511        <term><replaceable>host</replaceable></term>
 512
 513        <listitem>
 514         <para>Name of the server host (string/None).</para>
 515        </listitem>
 516       </varlistentry>
 517
 518       <varlistentry>
 519        <term><replaceable>port</replaceable></term>
 520
 521        <listitem>
 522         <para>Port used by the database server (integer/-1).</para>
 523        </listitem>
 524       </varlistentry>
 525
 526       <varlistentry>
 527        <term><replaceable>opt</replaceable></term>
 528
 529        <listitem>
 530         <para>
 531          Options for the server (string/None).
 532         </para>
 533        </listitem>
 534       </varlistentry>
 535
 536       <varlistentry>
 537        <term><replaceable>tty</replaceable></term>
 538
 539        <listitem>
 540         <para>
 541          File or tty for optional debug output from backend
 542          (string/None).
 543         </para>
 544        </listitem>
 545       </varlistentry>
 546
 547       <varlistentry>
 548        <term><replaceable>user</replaceable></term>
 549
 550        <listitem>
 551         <para>
 552          <productname>PostgreSQL</productname> user (string/None).
 553         </para>
 554        </listitem>
 555       </varlistentry>
 556
 557       <varlistentry>
 558        <term><replaceable>passwd</replaceable></term>
 559
 560        <listitem>
 561         <para>Password for user (string/None).</para>
 562        </listitem>
 563       </varlistentry>
 564      </variablelist>
 565     </refsect2>
 566
 567     <refsect2 id="pygresql-connect-return">
 568      <title>Return Type</title>
 569
 570      <variablelist>
 571       <varlistentry>
 572        <term><replaceable>pgobject</replaceable></term>
 573
 574        <listitem>
 575         <para>
 576          If successful, an object handling a database connection is returned.
 577         </para>
 578        </listitem>
 579       </varlistentry>
 580      </variablelist>
 581     </refsect2>
 582
 583     <refsect2 id="pygresql-connect-exceptions">
 584      <title>Exceptions</title>
 585
 586      <variablelist>
 587       <varlistentry>
 588        <term><errorname>TypeError</errorname></term>
 589
 590        <listitem>
 591         <para>
 592          Bad argument type, or too many arguments.
 593         </para>
 594        </listitem>
 595       </varlistentry>
 596
 597       <varlistentry>
 598        <term><errorname>SyntaxError</errorname></term>
 599
 600        <listitem>
 601         <para>
 602          Duplicate argument definition.
 603         </para>
 604        </listitem>
 605       </varlistentry>
 606
 607       <varlistentry>
 608        <term><errorname>pg.error</errorname></term>
 609
 610        <listitem>
 611         <para>
 612          Some error occurred during pg connection definition.
 613         </para>
 614        </listitem>
 615       </varlistentry>
 616      </variablelist>
 617
 618      <para>
 619       (+ all exceptions relative to object allocation)
 620      </para>
 621     </refsect2>
 622    </refsynopsisdiv>
 623
 624    <refsect1 id="pygresql-connect-description">
 625     <title>Description</title>
 626
 627     <para>
 628      This method opens a connection to a specified database on a given
 629      <productname>PostgreSQL</productname> server. You can use
 630      keywords here, as described in the
 631      <productname>Python</productname> tutorial.  The names of the
 632      keywords are the name of the parameters given in the syntax
 633      line. For a precise description of the parameters, please refer
 634      to the <productname>PostgreSQL</productname> user manual.
 635     </para>
 636    </refsect1>
 637
 638    <refsect1 id="pygresql-connect-examples">
 639     <title>Examples</title>
 640
 641     <para>
 642 <programlisting>
 643 import pg
 644
 645 con1 = pg.connect('testdb', 'myhost', 5432, None, None, 'bob', None)
 646 con2 = pg.connect(dbname='testdb', host='localhost', user='bob')
 647 </programlisting>
 648     </para>
 649    </refsect1>
 650
 651   </refentry>
 652
 653
 654   <refentry id="pygresql-get-defhost">
 655    <refmeta>
 656     <refentrytitle>get_defhost</refentrytitle>
 657     <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
 658    </refmeta>
 659
 660    <refnamediv>
 661     <refname>get_defhost</refname>
 662     <refpurpose>get default host name [DV]</refpurpose>
 663    </refnamediv>
 664
 665    <refsynopsisdiv>
 666 <synopsis>
 667 get_defhost()
 668 </synopsis>
 669
 670     <refsect2 id="pygresql-get-defhost-parameters">
 671      <title>Parameters</title>
 672
 673      <para>
 674       none
 675      </para>
 676     </refsect2>
 677
 678     <refsect2 id="pygresql-get-defhost-return">
 679      <title>Return Type</title>
 680
 681      <variablelist>
 682       <varlistentry>
 683        <term>string or None</term>
 684
 685        <listitem>
 686         <para>
 687          Default host specification
 688         </para>
 689        </listitem>
 690       </varlistentry>
 691      </variablelist>
 692     </refsect2>
 693
 694     <refsect2 id="pygresql-get-defhost-exceptions">
 695      <title>Exceptions</title>
 696
 697      <variablelist>
 698       <varlistentry>
 699        <term><errorname>SyntaxError</errorname></term>
 700
 701        <listitem>
 702         <para>
 703          Too many arguments.
 704         </para>
 705        </listitem>
 706       </varlistentry>
 707      </variablelist>
 708     </refsect2>
 709
 710    </refsynopsisdiv>
 711
 712    <refsect1 id="pygresql-get-defhost-description">
 713     <title>Description</title>
 714
 715     <para>
 716      <function>get_defhost()</function> returns the current default
 717      host specification, or None if the environment variables should
 718      be used. Environment variables will not be looked up.
 719     </para>
 720    </refsect1>
 721
 722   </refentry>
 723
 724
 725   <refentry id="pygresql-set-defhost">
 726     <refmeta>
 727       <refentrytitle>set_defhost</refentrytitle>
 728       <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
 729     </refmeta>
 730     <refnamediv>
 731       <refname>set_defhost</refname>
 732       <refpurpose>set default host name [DV]</refpurpose>
 733     </refnamediv>
 734
 735     <refsynopsisdiv>
 736 <synopsis>
 737 set_defhost(<replaceable>host</replaceable>)
 738 </synopsis>
 739
 740       <refsect2 id="pygresql-set-defhost-parameters">
 741         <title>Parameters</title>
 742         <variablelist>
 743           <varlistentry>
 744             <term>
 745               <replaceable>host</replaceable>
 746             </term>
 747             <listitem>
 748               <para>New default host (string/None).</para>
 749             </listitem>
 750           </varlistentry>
 751         </variablelist>
 752       </refsect2>
 753
 754       <refsect2 id="pygresql-set-defhost-return">
 755         <title>Return Type</title>
 756         <variablelist>
 757           <varlistentry>
 758             <term>
 759               string or None
 760             </term>
 761             <listitem>
 762               <para>
 763                 Previous default host specification.
 764               </para>
 765             </listitem>
 766           </varlistentry>
 767         </variablelist>
 768       </refsect2>
 769
 770       <refsect2 id="pygresql-set-defhost-exceptions">
 771         <title>Exceptions</title>
 772         <variablelist>
 773           <varlistentry>
 774             <term>
 775               <errorname>TypeError</errorname>
 776             </term>
 777             <listitem>
 778               <para>
 779                 Bad argument type, or too many arguments.
 780               </para>
 781             </listitem>
 782           </varlistentry>
 783         </variablelist>
 784       </refsect2>
 785
 786     </refsynopsisdiv>
 787
 788     <refsect1 id="pygresql-set-defhost-description">
 789       <title>Description</title>
 790       <para>
 791         <function>set_defhost()</function> sets the default host value
 792         for new connections. If None is supplied as parameter, environment
 793         variables will be used in future connections. It returns the
 794         previous setting for default host.
 795       </para>
 796     </refsect1>
 797
 798   </refentry>
 799
 800 <!-- ********************************************************** -->
 801
 802   <refentry id="pygresql-get-defport">
 803     <refmeta>
 804       <refentrytitle>get_defport</refentrytitle>
 805       <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
 806     </refmeta>
 807     <refnamediv>
 808       <refname>get_defport</refname>
 809       <refpurpose>get default port [DV]</refpurpose>
 810     </refnamediv>
 811
 812     <refsynopsisdiv>
 813 <synopsis>
 814 get_defport()
 815 </synopsis>
 816
 817       <refsect2 id="R2-PYGRESQL-GET-DEFPORT-1">
 818         <title>Parameters</title>
 819         <para>
 820           none
 821         </para>
 822       </refsect2>
 823
 824       <refsect2 id="R2-PYGRESQL-GET-DEFPORT-2">
 825         <title>Return Type</title>
 826         <variablelist>
 827           <varlistentry>
 828             <term>
 829               integer or None
 830             </term>
 831             <listitem>
 832               <para>
 833                 Default port specification
 834               </para>
 835             </listitem>
 836           </varlistentry>
 837         </variablelist>
 838       </refsect2>
 839
 840       <refsect2 id="R2-PYGRESQL-GET-DEFPORT-3">
 841         <title>Exceptions</title>
 842         <variablelist>
 843           <varlistentry>
 844             <term>
 845               <errorname>SyntaxError</errorname>
 846             </term>
 847             <listitem>
 848               <para>
 849                 Too many arguments.
 850               </para>
 851             </listitem>
 852           </varlistentry>
 853         </variablelist>
 854       </refsect2>
 855
 856     </refsynopsisdiv>
 857
 858     <refsect1 id="R1-PYGRESQL-GET-DEFPORT-1">
 859       <title>Description</title>
 860       <para>
 861         <function>get_defport()</function> returns the current default
 862         port specification, or None if the environment variables should
 863         be used. Environment variables will not be looked up.
 864       </para>
 865     </refsect1>
 866
 867   </refentry>
 868
 869 <!-- ********************************************************** -->
 870
 871   <refentry id="PYGRESQL-SET-DEFPORT">
 872     <refmeta>
 873       <refentrytitle>set_defport</refentrytitle>
 874       <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
 875     </refmeta>
 876     <refnamediv>
 877       <refname>set_defport</refname>
 878       <refpurpose>set default port [DV]</refpurpose>
 879     </refnamediv>
 880
 881     <refsynopsisdiv>
 882 <synopsis>
 883 set_defport(<replaceable>port</replaceable>)
 884 </synopsis>
 885
 886       <refsect2 id="R2-PYGRESQL-SET-DEFPORT-1">
 887         <title>Parameters</title>
 888         <variablelist>
 889           <varlistentry>
 890             <term>
 891               <replaceable>port</replaceable>
 892             </term>
 893             <listitem>
 894               <para>New default host (integer/-1).</para>
 895             </listitem>
 896           </varlistentry>
 897         </variablelist>
 898       </refsect2>
 899
 900       <refsect2 id="R2-PYGRESQL-SET-DEFPORT-2">
 901         <title>Return Type</title>
 902         <variablelist>
 903           <varlistentry>
 904             <term>
 905               integer or None
 906             </term>
 907             <listitem>
 908               <para>
 909                 Previous default port specification.
 910               </para>
 911             </listitem>
 912           </varlistentry>
 913         </variablelist>
 914       </refsect2>
 915
 916       <refsect2 id="R2-PYGRESQL-SET-DEFPORT-3">
 917         <title>Exceptions</title>
 918         <variablelist>
 919           <varlistentry>
 920             <term>
 921               <errorname>TypeError</errorname>
 922             </term>
 923             <listitem>
 924               <para>
 925                 Bad argument type, or too many arguments.
 926               </para>
 927             </listitem>
 928           </varlistentry>
 929         </variablelist>
 930       </refsect2>
 931
 932     </refsynopsisdiv>
 933
 934     <refsect1 id="R1-PYGRESQL-SET-DEFPORT-1">
 935       <title>Description</title>
 936       <para>
 937         <function>set_defport()</function> sets the default port value
 938         for new connections. If -1 is supplied as parameter, environment
 939         variables will be used in future connections. It returns the
 940         previous setting for default port.
 941       </para>
 942     </refsect1>
 943
 944   </refentry>
 945
 946 <!-- ********************************************************** -->
 947
 948   <refentry id="PYGRESQL-GET-DEFOPT">
 949     <refmeta>
 950       <refentrytitle>get_defopt</refentrytitle>
 951       <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
 952     </refmeta>
 953     <refnamediv>
 954       <refname>get_defopt</refname>
 955       <refpurpose>get default options specification [DV]</refpurpose>
 956     </refnamediv>
 957
 958     <refsynopsisdiv>
 959 <synopsis>
 960 get_defopt()
 961 </synopsis>
 962
 963       <refsect2 id="R2-PYGRESQL-GET-DEFOPT-1">
 964         <title>Parameters</title>
 965         <para>
 966           none
 967         </para>
 968       </refsect2>
 969
 970       <refsect2 id="R2-PYGRESQL-GET-DEFOPT-2">
 971         <title>Return Type</title>
 972         <variablelist>
 973           <varlistentry>
 974             <term>
 975               string or None
 976             </term>
 977             <listitem>
 978               <para>
 979                 Default options specification
 980               </para>
 981             </listitem>
 982           </varlistentry>
 983         </variablelist>
 984       </refsect2>
 985
 986       <refsect2 id="R2-PYGRESQL-GET-DEFOPT-3">
 987         <title>Exceptions</title>
 988         <variablelist>
 989           <varlistentry>
 990             <term>
 991               <errorname>SyntaxError</errorname>
 992             </term>
 993             <listitem>
 994               <para>
 995                 Too many arguments.
 996               </para>
 997             </listitem>
 998           </varlistentry>
 999         </variablelist>
1000       </refsect2>
1001
1002     </refsynopsisdiv>
1003
1004     <refsect1 id="R1-PYGRESQL-GET-DEFOPT-1">
1005       <title>Description</title>
1006       <para>
1007         <function>get_defopt()</function> returns the current default
1008         connection options specification, or None if the environment variables should
1009         be used. Environment variables will not be looked up.
1010       </para>
1011     </refsect1>
1012
1013   </refentry>
1014
1015 <!-- ********************************************************** -->
1016
1017   <refentry id="PYGRESQL-SET-DEFOPT">
1018     <refmeta>
1019       <refentrytitle>set_defopt</refentrytitle>
1020       <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
1021     </refmeta>
1022     <refnamediv>
1023       <refname>set_defopt</refname>
1024       <refpurpose>set options specification [DV]</refpurpose>
1025     </refnamediv>
1026
1027     <refsynopsisdiv>
1028 <synopsis>
1029 set_defopt(<replaceable>options</replaceable>)
1030 </synopsis>
1031
1032       <refsect2 id="R2-PYGRESQL-SET-DEFOPT-1">
1033         <title>Parameters</title>
1034         <variablelist>
1035           <varlistentry>
1036             <term>
1037               <replaceable>options</replaceable>
1038             </term>
1039             <listitem>
1040               <para>New default connection options (string/None).</para>
1041             </listitem>
1042           </varlistentry>
1043         </variablelist>
1044       </refsect2>
1045
1046       <refsect2 id="R2-PYGRESQL-SET-DEFOPT-2">
1047         <title>Return Type</title>
1048         <variablelist>
1049           <varlistentry>
1050             <term>
1051               string or None
1052             </term>
1053             <listitem>
1054               <para>
1055                 Previous default opt specification.
1056               </para>
1057             </listitem>
1058           </varlistentry>
1059         </variablelist>
1060       </refsect2>
1061
1062       <refsect2 id="R2-PYGRESQL-SET-DEFOPT-3">
1063         <title>Exceptions</title>
1064         <variablelist>
1065           <varlistentry>
1066             <term>
1067               <errorname>TypeError</errorname>
1068             </term>
1069             <listitem>
1070               <para>
1071                 Bad argument type, or too many arguments.
1072               </para>
1073             </listitem>
1074           </varlistentry>
1075         </variablelist>
1076       </refsect2>
1077
1078     </refsynopsisdiv>
1079
1080     <refsect1 id="R1-PYGRESQL-SET-DEFOPT-1">
1081       <title>Description</title>
1082       <para>
1083         <function>set_defopt()</function> sets the default connection options value
1084         for new connections. If None is supplied as parameter, environment
1085         variables will be used in future connections. It returns the
1086         previous setting for default options.
1087       </para>
1088     </refsect1>
1089
1090   </refentry>
1091
1092 <!-- ********************************************************** -->
1093
1094   <refentry id="PYGRESQL-GET-DEFTTY">
1095     <refmeta>
1096       <refentrytitle>get_deftty</refentrytitle>
1097       <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
1098     </refmeta>
1099     <refnamediv>
1100       <refname>get_deftty</refname>
1101       <refpurpose>get default connection debug terminal specification [DV]</refpurpose>
1102     </refnamediv>
1103
1104     <refsynopsisdiv>
1105 <synopsis>
1106 get_deftty()
1107 </synopsis>
1108
1109       <refsect2 id="R2-PYGRESQL-GET-DEFTTY-1">
1110         <title>Parameters</title>
1111         <para>
1112           none
1113         </para>
1114       </refsect2>
1115
1116       <refsect2 id="R2-PYGRESQL-GET-DEFTTY-2">
1117         <title>Return Type</title>
1118         <variablelist>
1119           <varlistentry>
1120             <term>
1121               string or None
1122             </term>
1123             <listitem>
1124               <para>
1125                 Default debug terminal specification
1126               </para>
1127             </listitem>
1128           </varlistentry>
1129         </variablelist>
1130       </refsect2>
1131
1132       <refsect2 id="R2-PYGRESQL-GET-DEFTTY-3">
1133         <title>Exceptions</title>
1134         <variablelist>
1135           <varlistentry>
1136             <term>
1137               <errorname>SyntaxError</errorname>
1138             </term>
1139             <listitem>
1140               <para>
1141                 Too many arguments.
1142               </para>
1143             </listitem>
1144           </varlistentry>
1145         </variablelist>
1146       </refsect2>
1147
1148     </refsynopsisdiv>
1149
1150     <refsect1 id="R1-PYGRESQL-GET-DEFTTY-1">
1151       <title>Description</title>
1152       <para>
1153         <function>get_deftty()</function> returns the current default
1154         debug terminal specification, or None if the environment variables should
1155         be used. Environment variables will not be looked up.
1156       </para>
1157     </refsect1>
1158
1159   </refentry>
1160
1161 <!-- ********************************************************** -->
1162
1163   <refentry id="PYGRESQL-SET-DEFTTY">
1164     <refmeta>
1165       <refentrytitle>set_deftty</refentrytitle>
1166       <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
1167     </refmeta>
1168     <refnamediv>
1169       <refname>set_deftty</refname>
1170       <refpurpose>set default debug terminal specification [DV]</refpurpose>
1171     </refnamediv>
1172
1173     <refsynopsisdiv>
1174 <synopsis>
1175 set_deftty(<replaceable>terminal</replaceable>)
1176 </synopsis>
1177
1178       <refsect2 id="R2-PYGRESQL-SET-DEFTTY-1">
1179         <title>Parameters</title>
1180         <variablelist>
1181           <varlistentry>
1182             <term>
1183               <replaceable>terminal</replaceable>
1184             </term>
1185             <listitem>
1186               <para>New default debug terminal (string/None).</para>
1187             </listitem>
1188           </varlistentry>
1189         </variablelist>
1190       </refsect2>
1191
1192       <refsect2 id="R2-PYGRESQL-SET-DEFTTY-2">
1193         <title>Return Type</title>
1194         <variablelist>
1195           <varlistentry>
1196             <term>
1197               string or None
1198             </term>
1199             <listitem>
1200               <para>
1201                 Previous default debug terminal specification.
1202               </para>
1203             </listitem>
1204           </varlistentry>
1205         </variablelist>
1206       </refsect2>
1207
1208       <refsect2 id="R2-PYGRESQL-SET-DEFTTY-3">
1209         <title>Exceptions</title>
1210         <variablelist>
1211           <varlistentry>
1212             <term>
1213               <errorname>TypeError</errorname>
1214             </term>
1215             <listitem>
1216               <para>
1217                 Bad argument type, or too many arguments.
1218               </para>
1219             </listitem>
1220           </varlistentry>
1221         </variablelist>
1222       </refsect2>
1223
1224     </refsynopsisdiv>
1225
1226     <refsect1 id="R1-PYGRESQL-SET-DEFTTY-1">
1227       <title>Description</title>
1228       <para>
1229         <function>set_deftty()</function> sets the default terminal value
1230         for new connections. If None is supplied as parameter, environment
1231         variables will be used in future connections. It returns the
1232         previous setting for default terminal.
1233       </para>
1234     </refsect1>
1235
1236   </refentry>
1237
1238 <!-- ********************************************************** -->
1239
1240   <refentry id="PYGRESQL-GET-DEFBASE">
1241     <refmeta>
1242       <refentrytitle>get_defbase</refentrytitle>
1243       <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
1244     </refmeta>
1245     <refnamediv>
1246       <refname>get_defbase</refname>
1247       <refpurpose>get default database name specification [DV]</refpurpose>
1248     </refnamediv>
1249
1250     <refsynopsisdiv>
1251 <synopsis>
1252 get_defbase()
1253 </synopsis>
1254
1255       <refsect2 id="R2-PYGRESQL-GET-DEFBASE-1">
1256         <title>Parameters</title>
1257         <para>
1258           none
1259         </para>
1260       </refsect2>
1261
1262       <refsect2 id="R2-PYGRESQL-GET-DEFBASE-2">
1263         <title>Return Type</title>
1264         <variablelist>
1265           <varlistentry>
1266             <term>
1267               string or None
1268             </term>
1269             <listitem>
1270               <para>
1271                 Default debug database name specification
1272               </para>
1273             </listitem>
1274           </varlistentry>
1275         </variablelist>
1276       </refsect2>
1277
1278       <refsect2 id="R2-PYGRESQL-GET-DEFBASE-3">
1279         <title>Exceptions</title>
1280         <variablelist>
1281           <varlistentry>
1282             <term>
1283               <errorname>SyntaxError</errorname>
1284             </term>
1285             <listitem>
1286               <para>
1287                 Too many arguments.
1288               </para>
1289             </listitem>
1290           </varlistentry>
1291         </variablelist>
1292       </refsect2>
1293
1294     </refsynopsisdiv>
1295
1296     <refsect1 id="R1-PYGRESQL-GET-DEFBASE-1">
1297       <title>Description</title>
1298       <para>
1299         <function>get_defbase()</function> returns the current default
1300         database name specification, or None if the environment variables should
1301         be used. Environment variables will not be looked up.
1302       </para>
1303     </refsect1>
1304
1305   </refentry>
1306
1307 <!-- ********************************************************** -->
1308
1309   <refentry id="PYGRESQL-SET-DEFBASE">
1310     <refmeta>
1311       <refentrytitle>set_defbase</refentrytitle>
1312       <refmiscinfo>PYGRESQL - Connection Management</refmiscinfo>
1313     </refmeta>
1314     <refnamediv>
1315       <refname>set_defbase</refname>
1316       <refpurpose>set default database name specification [DV]</refpurpose>
1317     </refnamediv>
1318
1319     <refsynopsisdiv>
1320 <synopsis>
1321 set_defbase(<replaceable>database</replaceable>)
1322 </synopsis>
1323
1324       <refsect2 id="R2-PYGRESQL-SET-DEFBASE-1">
1325         <title>Parameters</title>
1326         <variablelist>
1327           <varlistentry>
1328             <term>
1329               <replaceable>database</replaceable>
1330             </term>
1331             <listitem>
1332               <para>New default database name (string/None).</para>
1333             </listitem>
1334           </varlistentry>
1335         </variablelist>
1336       </refsect2>
1337
1338       <refsect2 id="R2-PYGRESQL-SET-DEFBASE-2">
1339         <title>Return Type</title>
1340         <variablelist>
1341           <varlistentry>
1342             <term>
1343               string or None
1344             </term>
1345             <listitem>
1346               <para>
1347                 Previous default database name specification.
1348               </para>
1349             </listitem>
1350           </varlistentry>
1351         </variablelist>
1352       </refsect2>
1353
1354       <refsect2 id="R2-PYGRESQL-SET-DEFBASE-3">
1355         <title>Exceptions</title>
1356         <variablelist>
1357           <varlistentry>
1358             <term>
1359               <errorname>TypeError</errorname>
1360             </term>
1361             <listitem>
1362               <para>
1363                 Bad argument type, or too many arguments.
1364               </para>
1365             </listitem>
1366           </varlistentry>
1367         </variablelist>
1368       </refsect2>
1369
1370     </refsynopsisdiv>
1371
1372     <refsect1 id="R1-PYGRESQL-SET-DEFBASE-1">
1373       <title>Description</title>
1374       <para>
1375         <function>set_defbase()</function> sets the default database name
1376         for new connections. If None is supplied as parameter, environment
1377         variables will be used in future connections. It returns the
1378         previous setting for default database name.
1379       </para>
1380     </refsect1>
1381
1382   </refentry>
1383
1384  </sect1>
1385
1386
1387  <sect1 id="pygresql-pg-pgobject">
1388   <title>Connection object: <classname>pgobject</classname></title>
1389
1390   <para>
1391    This object handles a connection to the
1392    <productname>PostgreSQL</productname> database.  It embeds and
1393    hides all the parameters that define this connection, leaving just
1394    really significant parameters in function calls.
1395   </para>
1396
1397   <para>
1398    Some methods give direct access to the connection socket. They are
1399    specified by the tag [DA].  <emphasis>Do not use them unless you
1400    really know what you are doing.</emphasis> If you prefer disabling
1401    them, set the <literal>-DNO_DIRECT</literal> option in the
1402    <productname>Python</productname> <filename>Setup</filename> file.
1403   </para>
1404
1405   <para>
1406    Some other methods give access to large objects.  if you want to
1407    forbid access to these from the module, set the
1408    <literal>-DNO_LARGE</literal> option in the
1409    <productname>Python</productname> <filename>Setup</filename> file.
1410    These methods are specified by the tag [LO].
1411   </para>
1412
1413   <para>
1414    Every <literal>pgobject</literal> defines a set of read-only
1415    attributes that describe the connection and its status. These
1416    attributes are:
1417
1418    <variablelist>
1419     <varlistentry>
1420      <term>host</term>
1421      <listitem>
1422       <para>
1423        the host name of the server (string)
1424       </para>
1425      </listitem>
1426     </varlistentry>
1427
1428     <varlistentry>
1429      <term>port</term>
1430      <listitem>
1431       <para>
1432        the port of the server (integer)
1433       </para>
1434      </listitem>
1435     </varlistentry>
1436
1437     <varlistentry>
1438      <term>db</term>
1439      <listitem>
1440       <para>
1441        the selected database (string)
1442       </para>
1443      </listitem>
1444     </varlistentry>
1445
1446     <varlistentry>
1447      <term>options</term>
1448      <listitem>
1449       <para>
1450        the connection options (string)
1451       </para>
1452      </listitem>
1453     </varlistentry>
1454
1455     <varlistentry>
1456      <term>tty</term>
1457      <listitem>
1458       <para>
1459        the connection debug terminal (string)
1460       </para>
1461      </listitem>
1462     </varlistentry>
1463
1464     <varlistentry>
1465      <term>user</term>
1466      <listitem>
1467       <para>
1468        user name on the database system (string)
1469       </para>
1470      </listitem>
1471     </varlistentry>
1472
1473     <varlistentry>
1474      <term>status</term>
1475      <listitem>
1476       <para>
1477        the status of the connection (integer: 1 - OK, 0 - BAD)
1478       </para>
1479      </listitem>
1480     </varlistentry>
1481
1482     <varlistentry>
1483      <term>error</term>
1484      <listitem>
1485       <para>
1486        the last warning/error message from the server (string)
1487       </para>
1488      </listitem>
1489     </varlistentry>
1490    </variablelist>
1491   </para>
1492
1493
1494   <refentry id="PYGRESQL-QUERY">
1495     <refmeta>
1496       <refentrytitle>query</refentrytitle>
1497       <refmiscinfo>PYGRESQL - Query</refmiscinfo>
1498     </refmeta>
1499     <refnamediv>
1500       <refname>query</refname>
1501       <refpurpose>executes a SQL command</refpurpose>
1502     </refnamediv>
1503
1504     <refsynopsisdiv>
1505 <synopsis>
1506 query(<replaceable>command</replaceable>)
1507 </synopsis>
1508
1509       <refsect2 id="R2-PYGRESQL-QUERY-1">
1510         <title>Parameters</title>
1511         <variablelist>
1512           <varlistentry>
1513             <term>
1514               <replaceable>command</replaceable>
1515             </term>
1516             <listitem>
1517               <para>SQL command (string).</para>
1518             </listitem>
1519           </varlistentry>
1520         </variablelist>
1521       </refsect2>
1522
1523       <refsect2 id="R2-PYGRESQL-QUERY-2">
1524         <title>Return Type</title>
1525         <variablelist>
1526           <varlistentry>
1527             <term>
1528               pgqueryobject or None
1529             </term>
1530             <listitem>
1531               <para>
1532                 Result values.
1533               </para>
1534             </listitem>
1535           </varlistentry>
1536         </variablelist>
1537       </refsect2>
1538
1539       <refsect2 id="R2-PYGRESQL-QUERY-3">
1540         <title>Exceptions</title>
1541         <variablelist>
1542           <varlistentry>
1543             <term>
1544               <errorname>TypeError</errorname>
1545             </term>
1546             <listitem>
1547               <para>
1548                 Bad argument type, or too many arguments.
1549               </para>
1550             </listitem>
1551           </varlistentry>
1552           <varlistentry>
1553             <term>
1554               <errorname>ValueError</errorname>
1555             </term>
1556             <listitem>
1557               <para>
1558                 Empty SQL query.
1559               </para>
1560             </listitem>
1561           </varlistentry>
1562           <varlistentry>
1563             <term>
1564               <errorname>pg.error</errorname>
1565             </term>
1566             <listitem>
1567               <para>
1568                 Error during query processing, or invalid connection.
1569               </para>
1570             </listitem>
1571           </varlistentry>
1572         </variablelist>
1573       </refsect2>
1574
1575     </refsynopsisdiv>
1576
1577     <refsect1 id="R1-PYGRESQL-QUERY-1">
1578       <title>Description</title>
1579       <para>
1580         <function>query()</function> method sends a <acronym>SQL</acronym>
1581         query to the database. If the query is an insert statement, the return
1582         value is the <acronym>OID</acronym> of the newly inserted row.
1583         If it is otherwise a query that does not return a result
1584         (i.e., is not a some kind of <literal>SELECT</literal> statement), it returns None.
1585         Otherwise, it returns a <literal>pgqueryobject</literal> that can be accessed via the
1586         <function>getresult()</function> or <function>dictresult()</function>
1587           methods or simply printed.
1588       </para>
1589     </refsect1>
1590
1591   </refentry>
1592
1593 <!-- ********************************************************** -->
1594
1595   <refentry id="PYGRESQL-RESET">
1596     <refmeta>
1597       <refentrytitle>reset</refentrytitle>
1598       <refmiscinfo>PYGRESQL - Reset</refmiscinfo>
1599     </refmeta>
1600     <refnamediv>
1601       <refname>reset</refname>
1602       <refpurpose>resets the connection</refpurpose>
1603     </refnamediv>
1604
1605     <refsynopsisdiv>
1606 <synopsis>
1607 reset()
1608 </synopsis>
1609
1610       <refsect2 id="R2-PYGRESQL-RESET-1">
1611         <title>Parameters</title>
1612         <para>
1613           none
1614         </para>
1615       </refsect2>
1616
1617       <refsect2 id="R2-PYGRESQL-RESET-2">
1618         <title>Return Type</title>
1619         <para>
1620           none
1621         </para>
1622       </refsect2>
1623
1624       <refsect2 id="R2-PYGRESQL-RESET-3">
1625         <title>Exceptions</title>
1626         <variablelist>
1627           <varlistentry>
1628             <term>
1629               <errorname>TypeError</errorname>
1630             </term>
1631             <listitem>
1632               <para>
1633                 Too many (any) arguments.
1634               </para>
1635             </listitem>
1636           </varlistentry>
1637         </variablelist>
1638       </refsect2>
1639
1640     </refsynopsisdiv>
1641
1642     <refsect1 id="R1-PYGRESQL-RESET-1">
1643       <title>Description</title>
1644       <para>
1645         <function>reset()</function> method resets the current database.
1646       </para>
1647     </refsect1>
1648
1649   </refentry>
1650
1651 <!-- ********************************************************** -->
1652
1653   <refentry id="PYGRESQL-CLOSE">
1654     <refmeta>
1655       <refentrytitle>close</refentrytitle>
1656       <refmiscinfo>PYGRESQL - Close</refmiscinfo>
1657     </refmeta>
1658     <refnamediv>
1659       <refname>close</refname>
1660       <refpurpose>close the database connection</refpurpose>
1661     </refnamediv>
1662
1663     <refsynopsisdiv>
1664 <synopsis>
1665 close()
1666 </synopsis>
1667
1668       <refsect2 id="R2-PYGRESQL-CLOSE-1">
1669         <title>Parameters</title>
1670         <para>
1671           none
1672         </para>
1673       </refsect2>
1674
1675       <refsect2 id="R2-PYGRESQL-CLOSE-2">
1676         <title>Return Type</title>
1677         <para>
1678           none
1679         </para>
1680       </refsect2>
1681
1682       <refsect2 id="R2-PYGRESQL-CLOSE-3">
1683         <title>Exceptions</title>
1684         <variablelist>
1685           <varlistentry>
1686             <term>
1687               <errorname>TypeError</errorname>
1688             </term>
1689             <listitem>
1690               <para>
1691                 Too many (any) arguments.
1692               </para>
1693             </listitem>
1694           </varlistentry>
1695         </variablelist>
1696       </refsect2>
1697
1698     </refsynopsisdiv>
1699
1700     <refsect1 id="R1-PYGRESQL-CLOSE-1">
1701       <title>Description</title>
1702       <para>
1703         <function>close()</function> method closes the database connection.
1704         The connection will be closed in any case when the connection is deleted but this
1705         allows you to explicitly close it.  It is mainly here to allow
1706         the DB-SIG API wrapper to implement a close function.
1707       </para>
1708     </refsect1>
1709
1710   </refentry>
1711
1712 <!-- ********************************************************** -->
1713
1714   <refentry id="PYGRESQL-FILENO">
1715     <refmeta>
1716       <refentrytitle>fileno</refentrytitle>
1717       <refmiscinfo>PYGRESQL - Fileno</refmiscinfo>
1718     </refmeta>
1719     <refnamediv>
1720       <refname>fileno</refname>
1721       <refpurpose>returns the socket used to connect to the database</refpurpose>
1722     </refnamediv>
1723
1724     <refsynopsisdiv>
1725 <synopsis>
1726 fileno()
1727 </synopsis>
1728
1729       <refsect2 id="R2-PYGRESQL-FILENO-1">
1730         <title>Parameters</title>
1731         <para>
1732           none
1733         </para>
1734       </refsect2>
1735
1736       <refsect2 id="R2-PYGRESQL-FILENO-2">
1737         <title>Return Type</title>
1738         <variablelist>
1739           <varlistentry>
1740             <term>
1741               socket id
1742             </term>
1743             <listitem>
1744               <para>
1745                 The underlying socket id used to connect to the database.
1746               </para>
1747             </listitem>
1748           </varlistentry>
1749         </variablelist>
1750       </refsect2>
1751
1752       <refsect2 id="R2-PYGRESQL-FILENO-3">
1753         <title>Exceptions</title>
1754         <variablelist>
1755           <varlistentry>
1756             <term>
1757               <errorname>TypeError</errorname>
1758             </term>
1759             <listitem>
1760               <para>
1761                 Too many (any) arguments.
1762               </para>
1763             </listitem>
1764           </varlistentry>
1765         </variablelist>
1766       </refsect2>
1767
1768     </refsynopsisdiv>
1769
1770     <refsect1 id="R1-PYGRESQL-FILENO-1">
1771       <title>Description</title>
1772       <para>
1773         <function>fileno()</function> method returns the underlying socket id used to connect
1774         to the database. This is useful for use in <function>select</function> calls, etc.
1775       </para>
1776     </refsect1>
1777
1778   </refentry>
1779
1780 <!-- ********************************************************** -->
1781
1782   <refentry id="PYGRESQL-GETNOTIFY">
1783     <refmeta>
1784       <refentrytitle>getnotify</refentrytitle>
1785       <refmiscinfo>PYGRESQL - Getnotify</refmiscinfo>
1786     </refmeta>
1787     <refnamediv>
1788       <refname>getnotify</refname>
1789       <refpurpose>gets the last notify from the server</refpurpose>
1790     </refnamediv>
1791
1792     <refsynopsisdiv>
1793 <synopsis>
1794 getnotify()
1795 </synopsis>
1796
1797       <refsect2 id="R2-PYGRESQL-GETNOTIFY-1">
1798         <title>Parameters</title>
1799         <para>
1800           none
1801         </para>
1802       </refsect2>
1803
1804       <refsect2 id="R2-PYGRESQL-GETNOTIFY-2">
1805         <title>Return Type</title>
1806         <variablelist>
1807           <varlistentry>
1808             <term>
1809               tuple, None
1810             </term>
1811             <listitem>
1812               <para>
1813                 Last notify from server
1814               </para>
1815             </listitem>
1816           </varlistentry>
1817         </variablelist>
1818       </refsect2>
1819
1820       <refsect2 id="R2-PYGRESQL-GETNOTIFY-3">
1821         <title>Exceptions</title>
1822         <variablelist>
1823           <varlistentry>
1824             <term>
1825               <errorname>TypeError</errorname>
1826             </term>
1827             <listitem>
1828               <para>
1829                 Too many (any) arguments.
1830               </para>
1831             </listitem>
1832           </varlistentry>
1833           <varlistentry>
1834             <term>
1835               <errorname>pg.error</errorname>
1836             </term>
1837             <listitem>
1838               <para>
1839                 Invalid connection.
1840               </para>
1841             </listitem>
1842           </varlistentry>
1843         </variablelist>
1844       </refsect2>
1845
1846     </refsynopsisdiv>
1847
1848     <refsect1 id="R1-PYGRESQL-GETNOTIFY-1">
1849       <title>Description</title>
1850       <para>
1851         <function>getnotify()</function> method tries to get a notify from
1852         the server (from the <literal>SQL</literal> statement <literal>NOTIFY</literal>).
1853         If the server returns no notify, the methods returns None.
1854         Otherwise, it returns a tuple (couple) <literal>(relname, pid)</literal>,
1855         where <literal>relname</literal> is the name of the notify and <literal>pid</literal>
1856         the process id of the connection that triggered the notify.
1857         Remember to do a listen query first otherwise getnotify will always return None.
1858       </para>
1859     </refsect1>
1860
1861   </refentry>
1862
1863 <!-- ********************************************************** -->
1864
1865   <refentry id="PYGRESQL-INSERTTABLE">
1866     <refmeta>
1867       <refentrytitle>inserttable</refentrytitle>
1868       <refmiscinfo>PYGRESQL - Inserttable</refmiscinfo>
1869     </refmeta>
1870     <refnamediv>
1871       <refname>inserttable</refname>
1872       <refpurpose>inserts a list into a table</refpurpose>
1873     </refnamediv>
1874
1875     <refsynopsisdiv>
1876 <synopsis>
1877 inserttable(<replaceable>table</replaceable>, <replaceable>values</replaceable>)
1878 </synopsis>
1879
1880       <refsect2 id="R2-PYGRESQL-INSERTTABLE-1">
1881         <title>Parameters</title>
1882         <variablelist>
1883           <varlistentry>
1884             <term>
1885               <replaceable>table</replaceable>
1886             </term>
1887             <listitem>
1888               <para>The table name (string).</para>
1889             </listitem>
1890           </varlistentry>
1891           <varlistentry>
1892             <term>
1893               <replaceable>values</replaceable>
1894             </term>
1895             <listitem>
1896               <para>The list of rows values to insert (list).</para>
1897             </listitem>
1898           </varlistentry>
1899         </variablelist>
1900       </refsect2>
1901
1902       <refsect2 id="R2-PYGRESQL-INSERTTABLE-2">
1903         <title>Return Type</title>
1904           <para>
1905             none
1906           </para>
1907       </refsect2>
1908
1909       <refsect2 id="R2-PYGRESQL-INSERTTABLE-3">
1910         <title>Exceptions</title>
1911         <variablelist>
1912           <varlistentry>
1913             <term>
1914               <errorname>TypeError</errorname>
1915             </term>
1916             <listitem>
1917               <para>
1918                 Bad argument type or too many (any) arguments.
1919               </para>
1920             </listitem>
1921           </varlistentry>
1922           <varlistentry>
1923             <term>
1924               <errorname>pg.error</errorname>
1925             </term>
1926             <listitem>
1927               <para>
1928                 Invalid connection.
1929               </para>
1930             </listitem>
1931           </varlistentry>
1932         </variablelist>
1933       </refsect2>
1934
1935     </refsynopsisdiv>
1936
1937     <refsect1 id="R1-PYGRESQL-INSERTTABLE-1">
1938       <title>Description</title>
1939       <para>
1940         <function>inserttable()</function> method allows to quickly
1941         insert large blocks of data in a table: it inserts the whole
1942         values list into the given table. The list is a list of
1943         tuples/lists that define the values for each inserted row. The
1944         rows values may contain string, integer, long or double (real)
1945         values.  <emphasis>Be very careful:</emphasis> this method
1946         does not typecheck the fields according to the table
1947         definition; it just look whether or not it knows how to handle
1948         such types.
1949       </para>
1950     </refsect1>
1951
1952   </refentry>
1953
1954 <!-- ********************************************************** -->
1955
1956   <refentry id="PYGRESQL-PUTLINE">
1957     <refmeta>
1958       <refentrytitle>putline</refentrytitle>
1959       <refmiscinfo>PYGRESQL - Putline</refmiscinfo>
1960     </refmeta>
1961     <refnamediv>
1962       <refname>putline</refname>
1963       <refpurpose>writes a line to the server socket [DA]</refpurpose>
1964     </refnamediv>
1965
1966     <refsynopsisdiv>
1967 <synopsis>
1968 putline(<replaceable>line</replaceable>)
1969 </synopsis>
1970
1971       <refsect2 id="R2-PYGRESQL-PUTLINE-1">
1972         <title>Parameters</title>
1973         <variablelist>
1974           <varlistentry>
1975             <term>
1976               <replaceable>line</replaceable>
1977             </term>
1978             <listitem>
1979               <para>Line to be written (string).</para>
1980             </listitem>
1981           </varlistentry>
1982         </variablelist>
1983       </refsect2>
1984
1985       <refsect2 id="R2-PYGRESQL-PUTLINE-2">
1986         <title>Return Type</title>
1987           <para>
1988             none
1989           </para>
1990       </refsect2>
1991
1992       <refsect2 id="R2-PYGRESQL-PUTLINE-3">
1993         <title>Exceptions</title>
1994         <variablelist>
1995           <varlistentry>
1996             <term>
1997               <errorname>TypeError</errorname>
1998             </term>
1999             <listitem>
2000               <para>
2001                 Bad argument type or too many (any) arguments.
2002               </para>
2003             </listitem>
2004           </varlistentry>
2005           <varlistentry>
2006             <term>
2007               <errorname>pg.error</errorname>
2008             </term>
2009             <listitem>
2010               <para>
2011                 Invalid connection.
2012               </para>
2013             </listitem>
2014           </varlistentry>
2015         </variablelist>
2016       </refsect2>
2017
2018     </refsynopsisdiv>
2019
2020     <refsect1 id="R1-PYGRESQL-PUTLINE-1">
2021       <title>Description</title>
2022       <para>
2023         <function>putline()</function> method allows to directly write a string to the server socket.
2024       </para>
2025     </refsect1>
2026
2027   </refentry>
2028
2029 <!-- ********************************************************** -->
2030
2031   <refentry id="PYGRESQL-GETLINE">
2032     <refmeta>
2033       <refentrytitle>getline</refentrytitle>
2034       <refmiscinfo>PYGRESQL - Getline</refmiscinfo>
2035     </refmeta>
2036     <refnamediv>
2037       <refname>getline</refname>
2038       <refpurpose>gets a line from server socket [DA]</refpurpose>
2039     </refnamediv>
2040
2041     <refsynopsisdiv>
2042 <synopsis>
2043 getline()
2044 </synopsis>
2045
2046       <refsect2 id="R2-PYGRESQL-GETLINE-1">
2047         <title>Parameters</title>
2048         <para>
2049           none
2050         </para>
2051       </refsect2>
2052
2053       <refsect2 id="R2-PYGRESQL-GETLINE-2">
2054         <title>Return Type</title>
2055         <variablelist>
2056           <varlistentry>
2057             <term>
2058               string
2059             </term>
2060             <listitem>
2061               <para>
2062                 The line read.
2063               </para>
2064             </listitem>
2065           </varlistentry>
2066         </variablelist>
2067       </refsect2>
2068
2069       <refsect2 id="R2-PYGRESQL-GETLINE-3">
2070         <title>Exceptions</title>
2071         <variablelist>
2072           <varlistentry>
2073             <term>
2074               <errorname>TypeError</errorname>
2075             </term>
2076             <listitem>
2077               <para>
2078                 Bad argument type or too many (any) arguments.
2079               </para>
2080             </listitem>
2081           </varlistentry>
2082           <varlistentry>
2083             <term>
2084               <errorname>pg.error</errorname>
2085             </term>
2086             <listitem>
2087               <para>
2088                 Invalid connection.
2089               </para>
2090             </listitem>
2091           </varlistentry>
2092         </variablelist>
2093       </refsect2>
2094
2095     </refsynopsisdiv>
2096
2097     <refsect1 id="R1-PYGRESQL-GETLINE-1">
2098       <title>Description</title>
2099       <para>
2100         <function>getline()</function> method allows to directly read a string from the server socket.
2101       </para>
2102     </refsect1>
2103
2104   </refentry>
2105
2106 <!-- ********************************************************** -->
2107
2108   <refentry id="PYGRESQL-ENDCOPY">
2109     <refmeta>
2110       <refentrytitle>endcopy</refentrytitle>
2111       <refmiscinfo>PYGRESQL - Endcopy</refmiscinfo>
2112     </refmeta>
2113     <refnamediv>
2114       <refname>endcopy</refname>
2115       <refpurpose>synchronizes client and server [DA]</refpurpose>
2116     </refnamediv>
2117
2118     <refsynopsisdiv>
2119 <synopsis>
2120 endcopy()
2121 </synopsis>
2122
2123       <refsect2 id="R2-PYGRESQL-ENDCOPY-1">
2124         <title>Parameters</title>
2125         <para>
2126           none
2127         </para>
2128       </refsect2>
2129
2130       <refsect2 id="R2-PYGRESQL-ENDCOPY-2">
2131         <title>Return Type</title>
2132         <para>
2133           none
2134         </para>
2135       </refsect2>
2136
2137       <refsect2 id="R2-PYGRESQL-ENDCOPY-3">
2138         <title>Exceptions</title>
2139         <variablelist>
2140           <varlistentry>
2141             <term>
2142               <errorname>TypeError</errorname>
2143             </term>
2144             <listitem>
2145               <para>
2146                 Bad argument type or too many (any) arguments.
2147               </para>
2148             </listitem>
2149           </varlistentry>
2150           <varlistentry>
2151             <term>
2152               <errorname>pg.error</errorname>
2153             </term>
2154             <listitem>
2155               <para>
2156                 Invalid connection.
2157               </para>
2158             </listitem>
2159           </varlistentry>
2160         </variablelist>
2161       </refsect2>
2162
2163     </refsynopsisdiv>
2164
2165     <refsect1 id="R1-PYGRESQL-ENDCOPY-1">
2166       <title>Description</title>
2167       <para>
2168         The use of direct access methods may desynchronize client and server. This
2169         method ensure that client and server will be synchronized.
2170       </para>
2171     </refsect1>
2172
2173   </refentry>
2174
2175 <!-- ********************************************************** -->
2176
2177   <refentry id="PYGRESQL-LOCREATE">
2178     <refmeta>
2179       <refentrytitle>locreate</refentrytitle>
2180       <refmiscinfo>PYGRESQL - Locreate</refmiscinfo>
2181     </refmeta>
2182     <refnamediv>
2183       <refname>locreate</refname>
2184       <refpurpose>creates of large object in the database [LO]</refpurpose>
2185     </refnamediv>
2186
2187     <refsynopsisdiv>
2188 <synopsis>
2189 locreate(<replaceable>mode</replaceable>)
2190 </synopsis>
2191
2192       <refsect2 id="R2-PYGRESQL-LOCREATE-1">
2193         <title>Parameters</title>
2194         <variablelist>
2195           <varlistentry>
2196             <term>
2197               <replaceable>mode</replaceable>
2198             </term>
2199             <listitem>
2200               <para>Large object create mode.</para>
2201             </listitem>
2202           </varlistentry>
2203         </variablelist>
2204       </refsect2>
2205
2206       <refsect2 id="R2-PYGRESQL-LOCREATE-2">
2207         <title>Return Type</title>
2208         <variablelist>
2209           <varlistentry>
2210             <term>
2211               pglarge
2212             </term>
2213             <listitem>
2214               <para>
2215                 Object handling the <productname>PostgreSQL</productname> large object.
2216               </para>
2217             </listitem>
2218           </varlistentry>
2219         </variablelist>
2220       </refsect2>
2221
2222       <refsect2 id="R2-PYGRESQL-LOCREATE-3">
2223         <title>Exceptions</title>
2224         <variablelist>
2225           <varlistentry>
2226             <term>
2227               <errorname>TypeError</errorname>
2228             </term>
2229             <listitem>
2230               <para>
2231                 Bad argument type or too many arguments.
2232               </para>
2233             </listitem>
2234           </varlistentry>
2235           <varlistentry>
2236             <term>
2237               <errorname>pg.error</errorname>
2238             </term>
2239             <listitem>
2240               <para>
2241                 Invalid connection, or creation error.
2242               </para>
2243             </listitem>
2244           </varlistentry>
2245         </variablelist>
2246       </refsect2>
2247
2248     </refsynopsisdiv>
2249
2250     <refsect1 id="R1-PYGRESQL-LOCREATE-1">
2251       <title>Description</title>
2252       <para>
2253         <function>locreate()</function> method creates a large object in the database.
2254         The mode can be defined by OR-ing the constants defined in the pg module
2255         (<literal>INV_READ and INV_WRITE</literal>).
2256       </para>
2257     </refsect1>
2258
2259   </refentry>
2260
2261 <!-- ********************************************************** -->
2262
2263   <refentry id="PYGRESQL-GETLO">
2264     <refmeta>
2265       <refentrytitle>getlo</refentrytitle>
2266       <refmiscinfo>PYGRESQL - Getlo</refmiscinfo>
2267     </refmeta>
2268     <refnamediv>
2269       <refname>getlo</refname>
2270       <refpurpose>builds a large object from given <literal>oid</literal> [LO]</refpurpose>
2271     </refnamediv>
2272
2273     <refsynopsisdiv>
2274 <synopsis>
2275 getlo(<replaceable>oid</replaceable>)
2276 </synopsis>
2277
2278       <refsect2 id="R2-PYGRESQL-GETLO-1">
2279         <title>Parameters</title>
2280         <variablelist>
2281           <varlistentry>
2282             <term>
2283               <replaceable>oid</replaceable>
2284             </term>
2285             <listitem>
2286               <para><literal>OID</literal> of the existing large object (integer).</para>
2287             </listitem>
2288           </varlistentry>
2289         </variablelist>
2290       </refsect2>
2291
2292       <refsect2 id="R2-PYGRESQL-GETLO-2">
2293         <title>Return Type</title>
2294         <variablelist>
2295           <varlistentry>
2296             <term>
2297               pglarge
2298             </term>
2299             <listitem>
2300               <para>
2301                 Object handling the <productname>PostgreSQL</productname> large object.
2302               </para>
2303             </listitem>
2304           </varlistentry>
2305         </variablelist>
2306       </refsect2>
2307
2308       <refsect2 id="R2-PYGRESQL-GETLO-3">
2309         <title>Exceptions</title>
2310         <variablelist>
2311           <varlistentry>
2312             <term>
2313               <errorname>TypeError</errorname>
2314             </term>
2315             <listitem>
2316               <para>
2317                 Bad argument type or too many arguments.
2318               </para>
2319             </listitem>
2320           </varlistentry>
2321           <varlistentry>
2322             <term>
2323               <errorname>pg.error</errorname>
2324             </term>
2325             <listitem>
2326               <para>
2327                 Invalid connection.
2328               </para>
2329             </listitem>
2330           </varlistentry>
2331         </variablelist>
2332       </refsect2>
2333
2334     </refsynopsisdiv>
2335
2336     <refsect1 id="R1-PYGRESQL-GETLO-1">
2337       <title>Description</title>
2338       <para>
2339         <function>getlo()</function> method allows to reuse a formerly
2340         created large object through the <classname>pglarge</classname> interface, providing
2341         the user have its <literal>oid</literal>.
2342       </para>
2343     </refsect1>
2344
2345   </refentry>
2346
2347 <!-- ********************************************************** -->
2348
2349   <refentry id="PYGRESQL-LOIMPORT">
2350     <refmeta>
2351       <refentrytitle>loimport</refentrytitle>
2352       <refmiscinfo>PYGRESQL - Loimport</refmiscinfo>
2353     </refmeta>
2354     <refnamediv>
2355       <refname>loimport</refname>
2356       <refpurpose>imports a file to a <productname>PostgreSQL</productname> large object [LO]</refpurpose>
2357     </refnamediv>
2358
2359     <refsynopsisdiv>
2360 <synopsis>
2361 loimport(<replaceable>filename</replaceable>)
2362 </synopsis>
2363
2364       <refsect2 id="R2-PYGRESQL-LOIMPORT-1">
2365         <title>Parameters</title>
2366         <variablelist>
2367           <varlistentry>
2368             <term>
2369               <replaceable>filename</replaceable>
2370             </term>
2371             <listitem>
2372               <para>The name of the file to be imported (string).</para>
2373             </listitem>
2374           </varlistentry>
2375         </variablelist>
2376       </refsect2>
2377
2378       <refsect2 id="R2-PYGRESQL-LOIMPORT-2">
2379         <title>Return Type</title>
2380         <variablelist>
2381           <varlistentry>
2382             <term>
2383               pglarge
2384             </term>
2385             <listitem>
2386               <para>
2387                 Object handling the <productname>PostgreSQL</productname> large object.
2388               </para>
2389             </listitem>
2390           </varlistentry>
2391         </variablelist>
2392       </refsect2>
2393
2394       <refsect2 id="R2-PYGRESQL-LOIMPORT-3">
2395         <title>Exceptions</title>
2396         <variablelist>
2397           <varlistentry>
2398             <term>
2399               <errorname>TypeError</errorname>
2400             </term>
2401             <listitem>
2402               <para>
2403                 Bad argument type or too many arguments.
2404               </para>
2405             </listitem>
2406           </varlistentry>
2407           <varlistentry>
2408             <term>
2409               <errorname>pg.error</errorname>
2410             </term>
2411             <listitem>
2412               <para>
2413                 Invalid connection, or error during file import.
2414               </para>
2415             </listitem>
2416           </varlistentry>
2417         </variablelist>
2418       </refsect2>
2419
2420     </refsynopsisdiv>
2421
2422     <refsect1 id="R1-PYGRESQL-LOIMPORT-1">
2423       <title>Description</title>
2424       <para>
2425         <function>loimport()</function> method allows to create large objects
2426         in a very simple way. You just give the name of a file containing the
2427         data to be use.
2428       </para>
2429     </refsect1>
2430
2431     </refentry>
2432
2433  </sect1>
2434
2435
2436  <sect1 id="pygresql-pg-DB">
2437   <title>Database wrapper class: <classname>DB</classname></title>
2438
2439   <para>
2440    <classname>pg</classname> module contains a class called
2441    <classname>DB</classname>.  All <classname>pgobject</classname>
2442    methods are included in this class also.  A number of additional
2443    <classname>DB</classname> class methods are described below.  The
2444    preferred way to use this module is as follows (See description of
2445    the initialization method below.):
2446
2447 <programlisting>
2448 import pg
2449
2450 db = pg.DB(...)
2451
2452 for r in db.query(
2453     "SELECT foo,bar
2454        FROM foo_bar_table
2455       WHERE foo !~ bar"
2456     ).dictresult():
2457
2458     print '%(foo)s %(bar)s' % r
2459 </programlisting>
2460
2461    The following describes the methods and variables of this class.
2462   </para>
2463
2464   <para>
2465    The <classname>DB</classname> class is initialized with the same
2466    arguments as the <function>pg.connect</function> method.  It also
2467    initializes a few internal variables.  The statement <literal>db =
2468    DB()</literal> will open the local database with the name of the
2469    user just like <function>pg.connect()</function> does.
2470   </para>
2471
2472     <refentry id="PYGRESQL-DB-PKEY">
2473       <refmeta>
2474         <refentrytitle>pkey</refentrytitle>
2475         <refmiscinfo>PYGRESQL - Pkey</refmiscinfo>
2476       </refmeta>
2477       <refnamediv>
2478         <refname>pkey</refname>
2479         <refpurpose>returns the primary key of a table</refpurpose>
2480       </refnamediv>
2481
2482       <refsynopsisdiv>
2483 <synopsis>
2484 pkey(<replaceable>table</replaceable>)
2485 </synopsis>
2486
2487         <refsect2 id="R2-PYGRESQL-DB-PKEY-1">
2488           <title>Parameters</title>
2489           <variablelist>
2490             <varlistentry>
2491               <term>
2492                 <replaceable>table</replaceable>
2493               </term>
2494               <listitem>
2495                 <para>
2496                   name of table.
2497                 </para>
2498               </listitem>
2499             </varlistentry>
2500           </variablelist>
2501         </refsect2>
2502
2503         <refsect2 id="R2-PYGRESQL-DB-PKEY-2">
2504           <title>Return Type</title>
2505           <variablelist>
2506             <varlistentry>
2507               <term>
2508                 string
2509               </term>
2510               <listitem>
2511                 <para>
2512                   Name of field which is the primary key of the table.
2513                 </para>
2514               </listitem>
2515             </varlistentry>
2516           </variablelist>
2517         </refsect2>
2518
2519       </refsynopsisdiv>
2520
2521       <refsect1 id="R1-PYGRESQL-DB-PKEY-1">
2522         <title>Description</title>
2523         <para>
2524           <function>pkey()</function> method returns the primary key
2525           of a table.  Note that this raises an exception if the table
2526           does not have a primary key.
2527         </para>
2528       </refsect1>
2529
2530     </refentry>
2531
2532     <!-- ********************************************************** -->
2533
2534     <refentry id="PYGRESQL-DB-GET-DATABASES">
2535       <refmeta>
2536         <refentrytitle>get_databases</refentrytitle>
2537         <refmiscinfo>PYGRESQL - Get_databases</refmiscinfo>
2538       </refmeta>
2539       <refnamediv>
2540         <refname>get_databases</refname>
2541         <refpurpose>get list of databases in the system</refpurpose>
2542       </refnamediv>
2543
2544       <refsynopsisdiv>
2545 <synopsis>
2546 get_databases()
2547 </synopsis>
2548
2549         <refsect2 id="R2-PYGRESQL-DB-GET-DATABASES-1">
2550           <title>Parameters</title>
2551           <para>
2552             none
2553           </para>
2554         </refsect2>
2555
2556         <refsect2 id="R2-PYGRESQL-DB-GET-DATABASES-2">
2557           <title>Return Type</title>
2558           <variablelist>
2559             <varlistentry>
2560               <term>
2561                 list
2562               </term>
2563               <listitem>
2564                 <para>
2565                   List of databases in the system.
2566                 </para>
2567               </listitem>
2568             </varlistentry>
2569           </variablelist>
2570         </refsect2>
2571
2572       </refsynopsisdiv>
2573
2574       <refsect1 id="R1-PYGRESQL-DB-GET-DATABASES-1">
2575         <title>Description</title>
2576         <para>
2577           Although you can do this with a simple select,
2578           it is added here for convenience
2579         </para>
2580       </refsect1>
2581
2582     </refentry>
2583
2584     <!-- ********************************************************** -->
2585
2586     <refentry id="PYGRESQL-DB-GET-TABLES">
2587       <refmeta>
2588         <refentrytitle>get_tables</refentrytitle>
2589         <refmiscinfo>PYGRESQL - get_tables</refmiscinfo>
2590       </refmeta>
2591       <refnamediv>
2592         <refname>get_tables</refname>
2593         <refpurpose>get list of tables in connected database</refpurpose>
2594       </refnamediv>
2595
2596       <refsynopsisdiv>
2597 <synopsis>
2598 get_tables()
2599 </synopsis>
2600
2601         <refsect2 id="R2-PYGRESQL-DB-GET-TABLES-1">
2602           <title>Parameters</title>
2603           <para>
2604             none
2605           </para>
2606         </refsect2>
2607
2608         <refsect2 id="R2-PYGRESQL-DB-GET-TABLES-2">
2609           <title>Return Type</title>
2610           <variablelist>
2611             <varlistentry>
2612               <term>
2613                 list
2614               </term>
2615               <listitem>
2616                 <para>
2617                   List of tables in connected database.
2618                 </para>
2619               </listitem>
2620             </varlistentry>
2621           </variablelist>
2622         </refsect2>
2623
2624       </refsynopsisdiv>
2625
2626       <refsect1 id="R1-PYGRESQL-DB-GET-TABLES-1">
2627         <title>Description</title>
2628         <para>
2629           Although you can do this with a simple select,
2630           it is added here for convenience
2631         </para>
2632       </refsect1>
2633
2634     </refentry>
2635
2636     <!-- ********************************************************** -->
2637
2638     <refentry id="PYGRESQL-DB-GET-ATTNAMES">
2639       <refmeta>
2640         <refentrytitle>get_attnames</refentrytitle>
2641         <refmiscinfo>PYGRESQL - Get_Attnames</refmiscinfo>
2642       </refmeta>
2643       <refnamediv>
2644         <refname>get_attnames</refname>
2645         <refpurpose>returns the attribute names of a table</refpurpose>
2646       </refnamediv>
2647
2648       <refsynopsisdiv>
2649 <synopsis>
2650 get_attnames(<replaceable>table</replaceable>)
2651 </synopsis>
2652
2653         <refsect2 id="R2-PYGRESQL-DB-GET-ATTNAMES-1">
2654           <title>Parameters</title>
2655           <variablelist>
2656             <varlistentry>
2657               <term>
2658                 <replaceable>table</replaceable>
2659               </term>
2660               <listitem>
2661                 <para>
2662                   name of table.
2663                 </para>
2664               </listitem>
2665             </varlistentry>
2666           </variablelist>
2667         </refsect2>
2668
2669         <refsect2 id="R2-PYGRESQL-DB-GET-ATTNAMES-2">
2670           <title>Return Type</title>
2671           <variablelist>
2672             <varlistentry>
2673               <term>
2674                 dictionary
2675               </term>
2676               <listitem>
2677                 <para>
2678                  The dictionary's keys are
2679                  the attribute names, the values are the type names of
2680                  the attributes.
2681                 </para>
2682               </listitem>
2683             </varlistentry>
2684           </variablelist>
2685         </refsect2>
2686
2687       </refsynopsisdiv>
2688
2689       <refsect1 id="R1-PYGRESQL-DB-GET-ATTNAMES-1">
2690         <title>Description</title>
2691         <para>
2692           Given the name of a table, digs out the set of attribute names
2693           and types.
2694         </para>
2695       </refsect1>
2696
2697     </refentry>
2698
2699     <!-- ********************************************************** -->
2700
2701     <refentry id="PYGRESQL-DB-GET">
2702       <refmeta>
2703         <refentrytitle>get</refentrytitle>
2704         <refmiscinfo>PYGRESQL - Get</refmiscinfo>
2705       </refmeta>
2706       <refnamediv>
2707         <refname>get</refname>
2708         <refpurpose>get a tuple from a database table</refpurpose>
2709       </refnamediv>
2710
2711       <refsynopsisdiv>
2712 <synopsis>
2713 get(<replaceable>table</replaceable>, <replaceable>arg</replaceable>, <optional><replaceable>keyname</replaceable></optional>)
2714 </synopsis>
2715
2716         <refsect2 id="R2-PYGRESQL-DB-GET-1">
2717           <title>Parameters</title>
2718           <variablelist>
2719             <varlistentry>
2720               <term>
2721                 <replaceable>table</replaceable>
2722               </term>
2723               <listitem>
2724                 <para>
2725                   Name of table.
2726                 </para>
2727               </listitem>
2728             </varlistentry>
2729             <varlistentry>
2730               <term>
2731                 <replaceable>arg</replaceable>
2732               </term>
2733               <listitem>
2734                 <para>
2735                   Either a dictionary or the value to be looked up.
2736                 </para>
2737               </listitem>
2738             </varlistentry>
2739             <varlistentry>
2740               <term>
2741                 <optional><replaceable>keyname</replaceable></optional>
2742               </term>
2743               <listitem>
2744                 <para>
2745                   Name of field to use as key (optional).
2746                 </para>
2747               </listitem>
2748             </varlistentry>
2749           </variablelist>
2750         </refsect2>
2751
2752         <refsect2 id="R2-PYGRESQL-DB-GET-2">
2753           <title>Return Type</title>
2754           <variablelist>
2755             <varlistentry>
2756               <term>
2757                 dictionary
2758               </term>
2759               <listitem>
2760                 <para>
2761                   A dictionary mapping attribute names to row values.
2762                 </para>
2763               </listitem>
2764             </varlistentry>
2765           </variablelist>
2766         </refsect2>
2767
2768       </refsynopsisdiv>
2769
2770       <refsect1 id="R1-PYGRESQL-DB-GET-1">
2771         <title>Description</title>
2772         <para>
2773           This method is the basic mechanism to get a single row.  It assumes
2774           that the key specifies a unique row.  If keyname is not specified
2775           then the primary key for the table is used.  If arg is a dictionary
2776           then the value for the key is taken from it and it is modified to
2777           include the new values, replacing existing values where necessary.
2778           The oid is also put into the dictionary but in order to allow the
2779           caller to work with multiple tables, the attribute name is munged
2780           to make it unique.  It consists of the string <literal>oid_</literal> followed by
2781           the name of the table.
2782         </para>
2783       </refsect1>
2784
2785     </refentry>
2786
2787     <!-- ********************************************************** -->
2788
2789     <refentry id="PYGRESQL-DB-INSERT">
2790       <refmeta>
2791         <refentrytitle>insert</refentrytitle>
2792         <refmiscinfo>PYGRESQL - Insert</refmiscinfo>
2793       </refmeta>
2794       <refnamediv>
2795         <refname>insert</refname>
2796         <refpurpose>insert a tuple into a database table</refpurpose>
2797       </refnamediv>
2798
2799       <refsynopsisdiv>
2800 <synopsis>
2801 insert(<replaceable>table</replaceable>, <replaceable>a</replaceable>)
2802 </synopsis>
2803
2804         <refsect2 id="R2-PYGRESQL-DB-INSERT-1">
2805           <title>Parameters</title>
2806           <variablelist>
2807             <varlistentry>
2808               <term>
2809                 <replaceable>table</replaceable>
2810               </term>
2811               <listitem>
2812                 <para>
2813                   Name of table.
2814                 </para>
2815               </listitem>
2816             </varlistentry>
2817             <varlistentry>
2818               <term>
2819                 <replaceable>a</replaceable>
2820               </term>
2821               <listitem>
2822                 <para>
2823                   A dictionary of values.
2824                 </para>
2825               </listitem>
2826             </varlistentry>
2827           </variablelist>
2828         </refsect2>
2829
2830         <refsect2 id="R2-PYGRESQL-DB-INSERT-2">
2831           <title>Return Type</title>
2832           <variablelist>
2833             <varlistentry>
2834               <term>
2835                 integer
2836               </term>
2837               <listitem>
2838                 <para>
2839                   The OID of the newly inserted row.
2840                 </para>
2841               </listitem>
2842             </varlistentry>
2843           </variablelist>
2844         </refsect2>
2845
2846       </refsynopsisdiv>
2847
2848       <refsect1 id="R1-PYGRESQL-DB-INSERT-1">
2849         <title>Description</title>
2850         <para>
2851           This method inserts values into the table specified filling in the
2852           values from the dictionary.  It then reloads the dictionary with the
2853           values from the database.  This causes the dictionary to be updated
2854           with values that are modified by rules, triggers, etc.
2855         </para>
2856       </refsect1>
2857
2858     </refentry>
2859
2860     <!-- ********************************************************** -->
2861
2862     <refentry id="PYGRESQL-DB-UPDATE">
2863       <refmeta>
2864         <refentrytitle>update</refentrytitle>
2865         <refmiscinfo>PYGRESQL - Update</refmiscinfo>
2866       </refmeta>
2867       <refnamediv>
2868         <refname>update</refname>
2869         <refpurpose>update a database table</refpurpose>
2870       </refnamediv>
2871
2872       <refsynopsisdiv>
2873 <synopsis>
2874 update(<replaceable>table</replaceable>, <replaceable>a</replaceable>)
2875 </synopsis>
2876
2877         <refsect2 id="R2-PYGRESQL-DB-UPDATE-1">
2878           <title>Parameters</title>
2879           <variablelist>
2880             <varlistentry>
2881               <term>
2882                 <replaceable>table</replaceable>
2883               </term>
2884               <listitem>
2885                 <para>
2886                   Name of table.
2887                 </para>
2888               </listitem>
2889             </varlistentry>
2890             <varlistentry>
2891               <term>
2892                 <replaceable>a</replaceable>
2893               </term>
2894               <listitem>
2895                 <para>
2896                   A dictionary of values.
2897                 </para>
2898               </listitem>
2899             </varlistentry>
2900           </variablelist>
2901         </refsect2>
2902
2903         <refsect2 id="R2-PYGRESQL-DB-UPDATE-2">
2904           <title>Return Type</title>
2905           <variablelist>
2906             <varlistentry>
2907               <term>
2908                 integer
2909               </term>
2910               <listitem>
2911                 <para>
2912                   The OID of the newly updated row.
2913                 </para>
2914               </listitem>
2915             </varlistentry>
2916           </variablelist>
2917         </refsect2>
2918
2919       </refsynopsisdiv>
2920
2921       <refsect1 id="R1-PYGRESQL-DB-UPDATE-1">
2922         <title>Description</title>
2923         <para>
2924           Similar to insert but updates an existing row.  The update is based
2925           on the OID value as munged by get.  The array returned is the
2926           one sent modified to reflect any changes caused by the update due
2927           to triggers, rules, defaults, etc.
2928         </para>
2929       </refsect1>
2930
2931     </refentry>
2932
2933     <!-- ********************************************************** -->
2934
2935     <refentry id="PYGRESQL-DB-CLEAR">
2936       <refmeta>
2937         <refentrytitle>clear</refentrytitle>
2938         <refmiscinfo>PYGRESQL - Clear</refmiscinfo>
2939       </refmeta>
2940       <refnamediv>
2941         <refname>clear</refname>
2942         <refpurpose>clear a database table</refpurpose>
2943       </refnamediv>
2944
2945       <refsynopsisdiv>
2946 <synopsis>
2947 clear(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></optional>)
2948 </synopsis>
2949
2950         <refsect2 id="R2-PYGRESQL-DB-CLEAR-1">
2951           <title>Parameters</title>
2952           <variablelist>
2953             <varlistentry>
2954               <term>
2955                 <replaceable>table</replaceable>
2956               </term>
2957               <listitem>
2958                 <para>
2959                   Name of table.
2960                 </para>
2961               </listitem>
2962             </varlistentry>
2963             <varlistentry>
2964               <term>
2965                 <optional><replaceable>a</replaceable></optional>
2966               </term>
2967               <listitem>
2968                 <para>
2969                   A dictionary of values.
2970                 </para>
2971               </listitem>
2972             </varlistentry>
2973           </variablelist>
2974         </refsect2>
2975
2976         <refsect2 id="R2-PYGRESQL-DB-CLEAR-2">
2977           <title>Return Type</title>
2978           <variablelist>
2979             <varlistentry>
2980               <term>
2981                 dictionary
2982               </term>
2983               <listitem>
2984                 <para>
2985                   A dictionary with an empty row.
2986                 </para>
2987               </listitem>
2988             </varlistentry>
2989           </variablelist>
2990         </refsect2>
2991
2992       </refsynopsisdiv>
2993
2994       <refsect1 id="R1-PYGRESQL-DB-CLEAR-1">
2995         <title>Description</title>
2996         <para>
2997           This method clears all the attributes to values determined by the types.
2998           Numeric types are set to 0, dates are set to <literal>'today'</literal> and everything
2999           else is set to the empty string.  If the array argument is present,
3000           it is used as the array and any entries matching attribute names
3001           are cleared with everything else left unchanged.
3002         </para>
3003       </refsect1>
3004
3005     </refentry>
3006
3007     <!-- ********************************************************** -->
3008
3009     <refentry id="PYGRESQL-DB-DELETE">
3010       <refmeta>
3011         <refentrytitle>delete</refentrytitle>
3012         <refmiscinfo>PYGRESQL - Delete</refmiscinfo>
3013       </refmeta>
3014       <refnamediv>
3015         <refname>delete</refname>
3016         <refpurpose>deletes the row from a table</refpurpose>
3017       </refnamediv>
3018
3019       <refsynopsisdiv>
3020 <synopsis>
3021 delete(<replaceable>table</replaceable>, <optional><replaceable>a</replaceable></optional>)
3022 </synopsis>
3023
3024         <refsect2 id="R2-PYGRESQL-DB-DELETE-1">
3025           <title>Parameters</title>
3026           <variablelist>
3027             <varlistentry>
3028               <term>
3029                 <replaceable>table</replaceable>
3030               </term>
3031               <listitem>
3032                 <para>
3033                   Name of table.
3034                 </para>
3035               </listitem>
3036             </varlistentry>
3037             <varlistentry>
3038               <term>
3039                 <optional><replaceable>a</replaceable></optional>
3040               </term>
3041               <listitem>
3042                 <para>
3043                   A dictionary of values.
3044                 </para>
3045               </listitem>
3046             </varlistentry>
3047           </variablelist>
3048         </refsect2>
3049
3050         <refsect2 id="R2-PYGRESQL-DB-DELETE-2">
3051           <title>Return Type</title>
3052           <para>
3053             none
3054           </para>
3055         </refsect2>
3056
3057       </refsynopsisdiv>
3058
3059       <refsect1 id="R1-PYGRESQL-DB-DELETE-1">
3060         <title>Description</title>
3061         <para>
3062           This method deletes the row from a table.  It deletes based on the OID
3063           as munged as described above.
3064         </para>
3065       </refsect1>
3066
3067     </refentry>
3068
3069     <!-- ********************************************************** -->
3070
3071   </sect1>
3072
3073   <!-- ********************************************************** -->
3074   <!-- ********************************************************** -->
3075
3076   <sect1 id="pygresql-pg-pgqueryobject">
3077     <title>Query result object: <literal>pgqueryobject</literal></title>
3078
3079     <!-- ********************************************************** -->
3080
3081     <refentry id="PYGRESQL-PGQUERYOBJECT-GETRESULT">
3082       <refmeta>
3083         <refentrytitle>getresult</refentrytitle>
3084         <refmiscinfo>PYGRESQL - Getresult</refmiscinfo>
3085       </refmeta>
3086       <refnamediv>
3087         <refname>getresult</refname>
3088         <refpurpose>gets the values returned by the query</refpurpose>
3089       </refnamediv>
3090
3091       <refsynopsisdiv>
3092 <synopsis>
3093 getresult()
3094 </synopsis>
3095
3096         <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-GETRESULT-1">
3097           <title>Parameters</title>
3098           <para>
3099             none
3100           </para>
3101         </refsect2>
3102
3103         <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-GETRESULT-2">
3104           <title>Return Type</title>
3105         <variablelist>
3106           <varlistentry>
3107             <term>
3108               list
3109             </term>
3110             <listitem>
3111               <para>
3112                 List of tuples.
3113               </para>
3114             </listitem>
3115           </varlistentry>
3116         </variablelist>
3117       </refsect2>
3118
3119       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-GETRESULT-3">
3120         <title>Exceptions</title>
3121         <variablelist>
3122           <varlistentry>
3123             <term>
3124               <errorname>SyntaxError</errorname>
3125             </term>
3126             <listitem>
3127               <para>
3128                 Too many arguments.
3129               </para>
3130             </listitem>
3131           </varlistentry>
3132           <varlistentry>
3133             <term>
3134               <errorname>pg.error</errorname>
3135             </term>
3136             <listitem>
3137               <para>
3138                 Invalid previous result.
3139               </para>
3140             </listitem>
3141           </varlistentry>
3142         </variablelist>
3143       </refsect2>
3144
3145     </refsynopsisdiv>
3146
3147     <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-GETRESULT-1">
3148       <title>Description</title>
3149       <para>
3150         <function>getresult()</function> method returns the list of the values returned by the query.
3151         More information about this result may be accessed using <function>listfields</function>,
3152         <function>fieldname</function> and <function>fieldnum</function> methods.
3153       </para>
3154     </refsect1>
3155
3156   </refentry>
3157
3158 <!-- ********************************************************** -->
3159
3160   <refentry id="PYGRESQL-PGQUERYOBJECT-DICTRESULT">
3161     <refmeta>
3162       <refentrytitle>dictresult</refentrytitle>
3163       <refmiscinfo>PYGRESQL - Dictresult</refmiscinfo>
3164     </refmeta>
3165     <refnamediv>
3166       <refname>dictresult</refname>
3167       <refpurpose>like getresult but returns a list of dictionaries</refpurpose>
3168     </refnamediv>
3169
3170     <refsynopsisdiv>
3171 <synopsis>
3172 dictresult()
3173 </synopsis>
3174
3175       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-DICTRESULT-1">
3176         <title>Parameters</title>
3177           <para>
3178             none
3179           </para>
3180       </refsect2>
3181
3182       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-DICTRESULT-2">
3183         <title>Return Type</title>
3184         <variablelist>
3185           <varlistentry>
3186             <term>
3187               list
3188             </term>
3189             <listitem>
3190               <para>
3191                 List of dictionaries.
3192               </para>
3193             </listitem>
3194           </varlistentry>
3195         </variablelist>
3196       </refsect2>
3197
3198       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-DICTRESULT-3">
3199         <title>Exceptions</title>
3200         <variablelist>
3201           <varlistentry>
3202             <term>
3203               <errorname>SyntaxError</errorname>
3204             </term>
3205             <listitem>
3206               <para>
3207                 Too many arguments.
3208               </para>
3209             </listitem>
3210           </varlistentry>
3211           <varlistentry>
3212             <term>
3213               <errorname>pg.error</errorname>
3214             </term>
3215             <listitem>
3216               <para>
3217                 Invalid previous result.
3218               </para>
3219             </listitem>
3220           </varlistentry>
3221         </variablelist>
3222       </refsect2>
3223
3224     </refsynopsisdiv>
3225
3226     <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-DICTRESULT-1">
3227       <title>Description</title>
3228       <para>
3229         <function>dictresult()</function> method returns the list of the values returned by the query
3230         with each tuple returned as a dictionary with the field names
3231         used as the dictionary index.
3232       </para>
3233     </refsect1>
3234
3235   </refentry>
3236
3237 <!-- ********************************************************** -->
3238
3239   <refentry id="PYGRESQL-PGQUERYOBJECT-LISTFIELDS">
3240     <refmeta>
3241       <refentrytitle>listfields</refentrytitle>
3242       <refmiscinfo>PYGRESQL - Listfields</refmiscinfo>
3243     </refmeta>
3244     <refnamediv>
3245       <refname>listfields</refname>
3246       <refpurpose>lists the fields names of the query result</refpurpose>
3247     </refnamediv>
3248
3249     <refsynopsisdiv>
3250 <synopsis>
3251 listfields()
3252 </synopsis>
3253
3254       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-1">
3255         <title>Parameters</title>
3256           <para>
3257             none
3258           </para>
3259       </refsect2>
3260
3261       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-2">
3262         <title>Return Type</title>
3263         <variablelist>
3264           <varlistentry>
3265             <term>
3266               list
3267             </term>
3268             <listitem>
3269               <para>
3270                 field names
3271               </para>
3272             </listitem>
3273           </varlistentry>
3274         </variablelist>
3275       </refsect2>
3276
3277       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-3">
3278         <title>Exceptions</title>
3279         <variablelist>
3280           <varlistentry>
3281             <term>
3282               <errorname>SyntaxError</errorname>
3283             </term>
3284             <listitem>
3285               <para>
3286                 Too many arguments.
3287               </para>
3288             </listitem>
3289           </varlistentry>
3290           <varlistentry>
3291             <term>
3292               <errorname>pg.error</errorname>
3293             </term>
3294             <listitem>
3295               <para>
3296                 Invalid query result, or invalid connection.
3297               </para>
3298             </listitem>
3299           </varlistentry>
3300         </variablelist>
3301       </refsect2>
3302
3303     </refsynopsisdiv>
3304
3305     <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-LISTFIELDS-1">
3306       <title>Description</title>
3307       <para>
3308         <function>listfields()</function> method returns the list of field names defined for the
3309         query result. The fields are in the same order as the result values.
3310       </para>
3311     </refsect1>
3312
3313   </refentry>
3314
3315 <!-- ********************************************************** -->
3316
3317   <refentry id="PYGRESQL-PGQUERYOBJECT-FIELDNAME">
3318     <refmeta>
3319       <refentrytitle>fieldname</refentrytitle>
3320       <refmiscinfo>PYGRESQL - Fieldname</refmiscinfo>
3321     </refmeta>
3322     <refnamediv>
3323       <refname>fieldname</refname>
3324       <refpurpose>field number-name conversion</refpurpose>
3325     </refnamediv>
3326
3327     <refsynopsisdiv>
3328 <synopsis>
3329 fieldname(<replaceable>i</replaceable>)
3330 </synopsis>
3331
3332       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-1">
3333         <title>Parameters</title>
3334         <variablelist>
3335           <varlistentry>
3336             <term>
3337               <replaceable>i</replaceable>
3338             </term>
3339             <listitem>
3340               <para>
3341                 field number (integer).
3342               </para>
3343             </listitem>
3344           </varlistentry>
3345         </variablelist>
3346       </refsect2>
3347
3348       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-2">
3349         <title>Return Type</title>
3350         <variablelist>
3351           <varlistentry>
3352             <term>
3353               string
3354             </term>
3355             <listitem>
3356               <para>
3357                 field name.
3358               </para>
3359             </listitem>
3360           </varlistentry>
3361         </variablelist>
3362       </refsect2>
3363
3364       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNAME-3">
3365         <title>Exceptions</title>
3366         <variablelist>
3367           <varlistentry>
3368             <term>
3369               <errorname>TypeError</errorname>
3370             </term>
3371             <listitem>
3372               <para>
3373                 Bad parameter type, or too many arguments.
3374               </para>
3375             </listitem>
3376           </varlistentry>
3377           <varlistentry>
3378             <term>
3379               <replaceable>ValueError</replaceable>
3380             </term>
3381             <listitem>
3382               <para>
3383                 Invalid field number.
3384               </para>
3385             </listitem>
3386           </varlistentry>
3387           <varlistentry>
3388             <term>
3389               <errorname>pg.error</errorname>
3390             </term>
3391             <listitem>
3392               <para>
3393                 Invalid query result, or invalid connection.
3394               </para>
3395             </listitem>
3396           </varlistentry>
3397         </variablelist>
3398       </refsect2>
3399
3400     </refsynopsisdiv>
3401
3402     <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-FIELDNAME-1">
3403       <title>Description</title>
3404       <para>
3405         <function>fieldname()</function> method allows to find a field name from its rank number. It can be
3406         useful for displaying a result. The fields are in the same order than the
3407         result values.
3408       </para>
3409     </refsect1>
3410
3411   </refentry>
3412
3413 <!-- ********************************************************** -->
3414
3415   <refentry id="PYGRESQL-PGQUERYOBJECT-FIELDNUM">
3416     <refmeta>
3417       <refentrytitle>fieldnum</refentrytitle>
3418       <refmiscinfo>PYGRESQL - Fieldnum</refmiscinfo>
3419     </refmeta>
3420     <refnamediv>
3421       <refname>fieldnum</refname>
3422       <refpurpose>field name-number conversion</refpurpose>
3423     </refnamediv>
3424
3425     <refsynopsisdiv>
3426 <synopsis>
3427 fieldnum(<replaceable>name</replaceable>)
3428 </synopsis>
3429
3430       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-1">
3431         <title>Parameters</title>
3432         <variablelist>
3433           <varlistentry>
3434             <term>
3435               <replaceable>name</replaceable>
3436             </term>
3437             <listitem>
3438               <para>
3439                 field name (string).
3440               </para>
3441             </listitem>
3442           </varlistentry>
3443         </variablelist>
3444       </refsect2>
3445
3446       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-2">
3447         <title>Return Type</title>
3448         <variablelist>
3449           <varlistentry>
3450             <term>
3451               integer
3452             </term>
3453             <listitem>
3454               <para>
3455                 field number (integer).
3456               </para>
3457             </listitem>
3458           </varlistentry>
3459         </variablelist>
3460       </refsect2>
3461
3462       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-FIELDNUM-3">
3463         <title>Exceptions</title>
3464         <variablelist>
3465           <varlistentry>
3466             <term>
3467               <errorname>TypeError</errorname>
3468             </term>
3469             <listitem>
3470               <para>
3471                 Bad parameter type, or too many arguments.
3472               </para>
3473             </listitem>
3474           </varlistentry>
3475           <varlistentry>
3476             <term>
3477               <replaceable>ValueError</replaceable>
3478             </term>
3479             <listitem>
3480               <para>
3481                 Unknown field name.
3482               </para>
3483             </listitem>
3484           </varlistentry>
3485           <varlistentry>
3486             <term>
3487               <errorname>pg.error</errorname>
3488             </term>
3489             <listitem>
3490               <para>
3491                 Invalid query result, or invalid connection.
3492               </para>
3493             </listitem>
3494           </varlistentry>
3495         </variablelist>
3496       </refsect2>
3497
3498     </refsynopsisdiv>
3499
3500     <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-FIELDNUM-1">
3501       <title>Description</title>
3502       <para>
3503         <function>fieldnum()</function> method returns a field number from its name.
3504         It can be used to build a function that converts result list strings to their correct
3505         type, using a hardcoded table definition.  The number returned is the
3506         field rank in the result values list.
3507       </para>
3508     </refsect1>
3509
3510   </refentry>
3511
3512 <!-- ********************************************************** -->
3513
3514   <refentry id="PYGRESQL-PGQUERYOBJECT-NTUPLES">
3515     <refmeta>
3516       <refentrytitle>ntuples</refentrytitle>
3517       <refmiscinfo>PYGRESQL - Ntuples</refmiscinfo>
3518     </refmeta>
3519     <refnamediv>
3520       <refname>ntuples</refname>
3521       <refpurpose>returns the number of tuples in query object</refpurpose>
3522     </refnamediv>
3523
3524     <refsynopsisdiv>
3525 <synopsis>
3526 ntuples()
3527 </synopsis>
3528
3529       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-NTUPLES-1">
3530         <title>Parameters</title>
3531           <para>
3532             none
3533           </para>
3534       </refsect2>
3535
3536       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-NTUPLES-2">
3537         <title>Return Type</title>
3538         <variablelist>
3539           <varlistentry>
3540             <term>
3541               integer
3542             </term>
3543             <listitem>
3544               <para>
3545                 The number of tuples in query object.
3546               </para>
3547             </listitem>
3548           </varlistentry>
3549         </variablelist>
3550       </refsect2>
3551
3552       <refsect2 id="R2-PYGRESQL-PGQUERYOBJECT-NTUPLES-3">
3553         <title>Exceptions</title>
3554         <variablelist>
3555           <varlistentry>
3556             <term>
3557               <errorname>SyntaxError</errorname>
3558             </term>
3559             <listitem>
3560               <para>
3561                 Too many arguments.
3562               </para>
3563             </listitem>
3564           </varlistentry>
3565         </variablelist>
3566       </refsect2>
3567
3568     </refsynopsisdiv>
3569
3570     <refsect1 id="R1-PYGRESQL-PGQUERYOBJECT-NTUPLES-1">
3571       <title>Description</title>
3572       <para>
3573         <function>ntuples()</function> method returns the number of tuples found in a query.
3574       </para>
3575     </refsect1>
3576
3577   </refentry>
3578
3579  </sect1>
3580
3581
3582  <sect1 id="pygresql-pg-pglarge">
3583   <title>Large Object: <classname>pglarge</classname></title>
3584
3585   <para>
3586    This object handles all the request concerning a
3587    <productname>PostgreSQL</productname> large object. It embeds and
3588    hides all the <quote>recurrent</quote> variables (object oid and
3589    connection), exactly in the same way
3590    <classname>pgobject</classname>s do, thus only keeping significant
3591    parameters in function calls. It keeps a reference to the <classname>pgobject</classname>
3592    used for its creation, sending requests though with its
3593    parameters. Any modification but dereferencing the
3594    <classname>pgobject</classname> will thus affect the
3595    <classname>pglarge</classname> object.  Dereferencing the initial
3596    <classname>pgobject</classname> is not a problem since
3597    <application>Python</application> will not deallocate it before the
3598    large object dereference it.  All functions return a generic error
3599    message on call error, whatever the exact error was. The
3600    <structfield>error</structfield> attribute of the object allows to
3601    get the exact error message.
3602   </para>
3603
3604   <para>
3605    <classname>pglarge</classname> objects define a read-only set of
3606    attributes that allow to get some information about it. These
3607    attributes are:
3608
3609    <variablelist>
3610     <varlistentry>
3611      <term>oid</term>
3612      <listitem>
3613       <para>
3614        the oid associated with the object
3615       </para>
3616      </listitem>
3617     </varlistentry>
3618
3619     <varlistentry>
3620      <term>pgcnx</term>
3621      <listitem>
3622       <para>
3623        the <classname>pgobject</classname> associated with the object
3624       </para>
3625      </listitem>
3626     </varlistentry>
3627
3628     <varlistentry>
3629      <term>error</term>
3630      <listitem>
3631       <para>
3632        the last warning/error message of the connection
3633       </para>
3634      </listitem>
3635     </varlistentry>
3636    </variablelist>
3637
3638    <note>
3639     <title>Be careful</title>
3640
3641     <para>
3642      In multithreaded environments, <structfield>error</structfield>
3643      may be modified by another thread using the same
3644      <classname>pgobject</classname>. Remember these object are
3645      shared, not duplicated; you should provide some locking to be
3646      able if you want to check this.  The oid attribute is very
3647      interesting because it allow you reuse the oid later, creating
3648      the <classname>pglarge</classname> object with a <classname>pgobject</classname>
3649      <function>getlo()</function> method call.
3650     </para>
3651    </note>
3652   </para>
3653
3654   <para>
3655    See also <xref linkend="largeobjects"> for more information about the
3656    <productname>PostgreSQL</productname> large object interface.
3657   </para>
3658
3659 <!-- ********************************************************** -->
3660
3661   <refentry id="PYGRESQL-PGLARGEOBJECT-OPEN">
3662     <refmeta>
3663       <refentrytitle>open</refentrytitle>
3664       <refmiscinfo>PYGRESQL - Open</refmiscinfo>
3665     </refmeta>
3666     <refnamediv>
3667       <refname>open</refname>
3668       <refpurpose>opens a large object</refpurpose>
3669     </refnamediv>
3670
3671     <refsynopsisdiv>
3672 <synopsis>
3673 open(<replaceable>mode</replaceable>)
3674 </synopsis>
3675
3676       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-1">
3677         <title>Parameters</title>
3678         <variablelist>
3679           <varlistentry>
3680             <term>
3681               <replaceable>mode</replaceable>
3682             </term>
3683             <listitem>
3684               <para>
3685                 open mode definition (integer).
3686               </para>
3687             </listitem>
3688           </varlistentry>
3689         </variablelist>
3690       </refsect2>
3691
3692       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-2">
3693         <title>Return Type</title>
3694           <para>
3695             none
3696           </para>
3697       </refsect2>
3698
3699       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-OPEN-3">
3700         <title>Exceptions</title>
3701         <variablelist>
3702           <varlistentry>
3703             <term>
3704               <errorname>TypeError</errorname>
3705             </term>
3706             <listitem>
3707               <para>
3708                 Bad parameter type, or too many arguments.
3709               </para>
3710             </listitem>
3711           </varlistentry>
3712           <varlistentry>
3713             <term>
3714               <errorname>IOError</errorname>
3715             </term>
3716             <listitem>
3717               <para>
3718                 Already opened object, or open error.
3719               </para>
3720             </listitem>
3721           </varlistentry>
3722           <varlistentry>
3723             <term>
3724               <errorname>pg.error</errorname>
3725             </term>
3726             <listitem>
3727               <para>
3728                 Invalid  connection.
3729               </para>
3730             </listitem>
3731           </varlistentry>
3732         </variablelist>
3733       </refsect2>
3734
3735     </refsynopsisdiv>
3736
3737     <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-OPEN-1">
3738       <title>Description</title>
3739       <para>
3740         <function>open()</function> method opens a large object for reading/writing,
3741         in the same way than the <acronym>UNIX</acronym> <function>open()</function>
3742         function. The mode value can be obtained by OR-ing the constants defined in
3743         the pg module (<literal>INV_READ, INV_WRITE</literal>).
3744       </para>
3745     </refsect1>
3746
3747   </refentry>
3748
3749 <!-- ********************************************************** -->
3750
3751   <refentry id="PYGRESQL-PGLARGEOBJECT-CLOSE">
3752     <refmeta>
3753       <refentrytitle>close</refentrytitle>
3754       <refmiscinfo>PYGRESQL - Close</refmiscinfo>
3755     </refmeta>
3756     <refnamediv>
3757       <refname>close</refname>
3758       <refpurpose>closes the large object</refpurpose>
3759     </refnamediv>
3760
3761     <refsynopsisdiv>
3762 <synopsis>
3763 close()
3764 </synopsis>
3765
3766       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-CLOSE-1">
3767         <title>Parameters</title>
3768         <para>
3769           none
3770         </para>
3771       </refsect2>
3772
3773       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-CLOSE-2">
3774         <title>Return Type</title>
3775         <para>
3776           none
3777         </para>
3778       </refsect2>
3779
3780       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-CLOSE-3">
3781         <title>Exceptions</title>
3782         <variablelist>
3783           <varlistentry>
3784             <term>
3785               <errorname>SyntaxError</errorname>
3786             </term>
3787             <listitem>
3788               <para>
3789                 Too many arguments.
3790               </para>
3791             </listitem>
3792           </varlistentry>
3793           <varlistentry>
3794             <term>
3795               <errorname>IOError</errorname>
3796             </term>
3797             <listitem>
3798               <para>
3799                 Object is not opened, or close error.
3800               </para>
3801             </listitem>
3802           </varlistentry>
3803           <varlistentry>
3804             <term>
3805               <errorname>pg.error</errorname>
3806             </term>
3807             <listitem>
3808               <para>
3809                 Invalid  connection.
3810               </para>
3811             </listitem>
3812           </varlistentry>
3813         </variablelist>
3814       </refsect2>
3815
3816     </refsynopsisdiv>
3817
3818     <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-CLOSE-1">
3819       <title>Description</title>
3820       <para>
3821         <function>close()</function> method closes previously opened large object,
3822         in the same way than the <acronym>UNIX</acronym> <function>close()</function> function.
3823       </para>
3824     </refsect1>
3825
3826   </refentry>
3827
3828 <!-- ********************************************************** -->
3829
3830   <refentry id="PYGRESQL-PGLARGEOBJECT-READ">
3831     <refmeta>
3832       <refentrytitle>read</refentrytitle>
3833       <refmiscinfo>PYGRESQL - Read</refmiscinfo>
3834     </refmeta>
3835     <refnamediv>
3836       <refname>read</refname>
3837       <refpurpose>reads from the large object</refpurpose>
3838     </refnamediv>
3839
3840     <refsynopsisdiv>
3841 <synopsis>
3842 read(<replaceable>size</replaceable>)
3843 </synopsis>
3844
3845       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-1">
3846         <title>Parameters</title>
3847         <variablelist>
3848           <varlistentry>
3849             <term>
3850               <replaceable>size</replaceable>
3851             </term>
3852             <listitem>
3853               <para>
3854                 Maximal size of the buffer to be read (integer).
3855               </para>
3856             </listitem>
3857           </varlistentry>
3858         </variablelist>
3859       </refsect2>
3860
3861       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-2">
3862         <title>Return Type</title>
3863         <variablelist>
3864           <varlistentry>
3865             <term>
3866               string
3867             </term>
3868             <listitem>
3869               <para>
3870                 The read buffer.
3871               </para>
3872             </listitem>
3873           </varlistentry>
3874         </variablelist>
3875       </refsect2>
3876
3877       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-READ-3">
3878         <title>Exceptions</title>
3879         <variablelist>
3880           <varlistentry>
3881             <term>
3882               <errorname>TypeError</errorname>
3883             </term>
3884             <listitem>
3885               <para>
3886                 Bad parameter type, or too many arguments.
3887               </para>
3888             </listitem>
3889           </varlistentry>
3890           <varlistentry>
3891             <term>
3892               <errorname>IOError</errorname>
3893             </term>
3894             <listitem>
3895               <para>
3896                 Object is not opened, or read error.
3897               </para>
3898             </listitem>
3899           </varlistentry>
3900           <varlistentry>
3901             <term>
3902               <errorname>pg.error</errorname>
3903             </term>
3904             <listitem>
3905               <para>
3906                 Invalid  connection or invalid object.
3907               </para>
3908             </listitem>
3909           </varlistentry>
3910         </variablelist>
3911       </refsect2>
3912
3913     </refsynopsisdiv>
3914
3915     <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-READ-1">
3916       <title>Description</title>
3917       <para>
3918         <function>read()</function> method allows to read data from the large object,
3919         starting at current position.
3920       </para>
3921     </refsect1>
3922
3923   </refentry>
3924
3925 <!-- ********************************************************** -->
3926
3927   <refentry id="PYGRESQL-PGLARGEOBJECT-WRITE">
3928     <refmeta>
3929       <refentrytitle>write</refentrytitle>
3930       <refmiscinfo>PYGRESQL - Write</refmiscinfo>
3931     </refmeta>
3932     <refnamediv>
3933       <refname>write</refname>
3934       <refpurpose>writes to the large object</refpurpose>
3935     </refnamediv>
3936
3937     <refsynopsisdiv>
3938 <synopsis>
3939 write(<replaceable>string</replaceable>)
3940 </synopsis>
3941
3942       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-1">
3943         <title>Parameters</title>
3944         <variablelist>
3945           <varlistentry>
3946             <term>
3947               <replaceable>string</replaceable>
3948             </term>
3949             <listitem>
3950               <para>
3951                 Buffer to be written (string).
3952               </para>
3953             </listitem>
3954           </varlistentry>
3955         </variablelist>
3956       </refsect2>
3957
3958       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-2">
3959         <title>Return Type</title>
3960         <para>
3961           none
3962         </para>
3963       </refsect2>
3964
3965       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-WRITE-3">
3966         <title>Exceptions</title>
3967         <variablelist>
3968           <varlistentry>
3969             <term>
3970               <errorname>TypeError</errorname>
3971             </term>
3972             <listitem>
3973               <para>
3974                 Bad parameter type, or too many arguments.
3975               </para>
3976             </listitem>
3977           </varlistentry>
3978           <varlistentry>
3979             <term>
3980               <errorname>IOError</errorname>
3981             </term>
3982             <listitem>
3983               <para>
3984                 Object is not opened, or write error.
3985               </para>
3986             </listitem>
3987           </varlistentry>
3988           <varlistentry>
3989             <term>
3990               <errorname>pg.error</errorname>
3991             </term>
3992             <listitem>
3993               <para>
3994                 Invalid  connection or invalid object.
3995               </para>
3996             </listitem>
3997           </varlistentry>
3998         </variablelist>
3999       </refsect2>
4000
4001     </refsynopsisdiv>
4002
4003     <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-WRITE-1">
4004       <title>Description</title>
4005       <para>
4006         <function>write()</function> method allows to write data to the large object,
4007         starting at current position.
4008       </para>
4009     </refsect1>
4010
4011   </refentry>
4012
4013 <!-- ********************************************************** -->
4014
4015   <refentry id="PYGRESQL-PGLARGEOBJECT-SEEK">
4016     <refmeta>
4017       <refentrytitle>seek</refentrytitle>
4018       <refmiscinfo>PYGRESQL - Seek</refmiscinfo>
4019     </refmeta>
4020     <refnamediv>
4021       <refname>seek</refname>
4022       <refpurpose>change current position in the large object</refpurpose>
4023     </refnamediv>
4024
4025     <refsynopsisdiv>
4026 <synopsis>
4027 seek(<replaceable>offset</replaceable>, <replaceable>whence</replaceable>)
4028 </synopsis>
4029
4030       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-1">
4031         <title>Parameters</title>
4032         <variablelist>
4033           <varlistentry>
4034             <term>
4035               <replaceable>offset</replaceable>
4036             </term>
4037             <listitem>
4038               <para>
4039                 Position offset (integer).
4040               </para>
4041             </listitem>
4042           </varlistentry>
4043           <varlistentry>
4044             <term>
4045               <replaceable>whence</replaceable>
4046             </term>
4047             <listitem>
4048               <para>
4049                 Positional parameter (integer).
4050               </para>
4051             </listitem>
4052           </varlistentry>
4053         </variablelist>
4054       </refsect2>
4055
4056       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-2">
4057         <title>Return Type</title>
4058         <variablelist>
4059           <varlistentry>
4060             <term>
4061               integer
4062             </term>
4063             <listitem>
4064               <para>
4065                 New current position in the object.
4066               </para>
4067             </listitem>
4068           </varlistentry>
4069         </variablelist>
4070       </refsect2>
4071
4072       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SEEK-3">
4073         <title>Exceptions</title>
4074         <variablelist>
4075           <varlistentry>
4076             <term>
4077               <errorname>TypeError</errorname>
4078             </term>
4079             <listitem>
4080               <para>
4081                 Bad parameter type, or too many arguments.
4082               </para>
4083             </listitem>
4084           </varlistentry>
4085           <varlistentry>
4086             <term>
4087               <errorname>IOError</errorname>
4088             </term>
4089             <listitem>
4090               <para>
4091                 Object is not opened, or seek error.
4092               </para>
4093             </listitem>
4094           </varlistentry>
4095           <varlistentry>
4096             <term>
4097               <errorname>pg.error</errorname>
4098             </term>
4099             <listitem>
4100               <para>
4101                 Invalid  connection or invalid object.
4102               </para>
4103             </listitem>
4104           </varlistentry>
4105         </variablelist>
4106       </refsect2>
4107
4108     </refsynopsisdiv>
4109
4110     <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-SEEK-1">
4111       <title>Description</title>
4112       <para>
4113         <function>seek()</function> method allows to move the cursor position
4114         in the large object. The whence parameter can be obtained by OR-ing the constants defined in the
4115         <literal>pg</literal> module (<literal>SEEK_SET, SEEK_CUR, SEEK_END</literal>).
4116       </para>
4117     </refsect1>
4118
4119   </refentry>
4120
4121 <!-- ********************************************************** -->
4122
4123   <refentry id="PYGRESQL-PGLARGEOBJECT-TELL">
4124     <refmeta>
4125       <refentrytitle>tell</refentrytitle>
4126       <refmiscinfo>PYGRESQL - Tell</refmiscinfo>
4127     </refmeta>
4128     <refnamediv>
4129       <refname>tell</refname>
4130       <refpurpose>returns current position in the large object</refpurpose>
4131     </refnamediv>
4132
4133     <refsynopsisdiv>
4134 <synopsis>
4135 tell()
4136 </synopsis>
4137
4138       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-TELL-1">
4139         <title>Parameters</title>
4140           <para>
4141             none
4142           </para>
4143       </refsect2>
4144
4145       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-TELL-2">
4146         <title>Return Type</title>
4147         <variablelist>
4148           <varlistentry>
4149             <term>
4150               integer
4151             </term>
4152             <listitem>
4153               <para>
4154                 Current position in the object.
4155               </para>
4156             </listitem>
4157           </varlistentry>
4158         </variablelist>
4159       </refsect2>
4160
4161       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-TELL-3">
4162         <title>Exceptions</title>
4163         <variablelist>
4164           <varlistentry>
4165             <term>
4166               <errorname>SyntaxError</errorname>
4167             </term>
4168             <listitem>
4169               <para>
4170                 Too many arguments.
4171               </para>
4172             </listitem>
4173           </varlistentry>
4174           <varlistentry>
4175             <term>
4176               <errorname>IOError</errorname>
4177             </term>
4178             <listitem>
4179               <para>
4180                 Object is not opened, or seek error.
4181               </para>
4182             </listitem>
4183           </varlistentry>
4184           <varlistentry>
4185             <term>
4186               <errorname>pg.error</errorname>
4187             </term>
4188             <listitem>
4189               <para>
4190                 Invalid  connection or invalid object.
4191               </para>
4192             </listitem>
4193           </varlistentry>
4194         </variablelist>
4195       </refsect2>
4196
4197     </refsynopsisdiv>
4198
4199     <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-TELL-1">
4200       <title>Description</title>
4201       <para>
4202         <function>tell()</function> method allows to get the current position in the large object.
4203       </para>
4204     </refsect1>
4205
4206   </refentry>
4207
4208 <!-- ********************************************************** -->
4209
4210   <refentry id="PYGRESQL-PGLARGEOBJECT-UNLINK">
4211     <refmeta>
4212       <refentrytitle>unlink</refentrytitle>
4213       <refmiscinfo>PYGRESQL - Unlink</refmiscinfo>
4214     </refmeta>
4215     <refnamediv>
4216       <refname>unlink</refname>
4217       <refpurpose>deletes the large object</refpurpose>
4218     </refnamediv>
4219
4220     <refsynopsisdiv>
4221 <synopsis>
4222 unlink()
4223 </synopsis>
4224
4225       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-UNLINK-1">
4226         <title>Parameters</title>
4227         <para>
4228           none
4229         </para>
4230       </refsect2>
4231
4232       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-UNLINK-2">
4233         <title>Return Type</title>
4234         <para>
4235           none
4236         </para>
4237       </refsect2>
4238
4239       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-UNLINK-3">
4240         <title>Exceptions</title>
4241         <variablelist>
4242           <varlistentry>
4243             <term>
4244               <errorname>SyntaxError</errorname>
4245             </term>
4246             <listitem>
4247               <para>
4248                 Too many arguments.
4249               </para>
4250             </listitem>
4251           </varlistentry>
4252           <varlistentry>
4253             <term>
4254               <errorname>IOError</errorname>
4255             </term>
4256             <listitem>
4257               <para>
4258                 Object is not closed, or unlink error.
4259               </para>
4260             </listitem>
4261           </varlistentry>
4262           <varlistentry>
4263             <term>
4264               <errorname>pg.error</errorname>
4265             </term>
4266             <listitem>
4267               <para>
4268                 Invalid  connection or invalid object.
4269               </para>
4270             </listitem>
4271           </varlistentry>
4272         </variablelist>
4273       </refsect2>
4274
4275     </refsynopsisdiv>
4276
4277     <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-UNLINK-1">
4278       <title>Description</title>
4279       <para>
4280         <function>unlink()</function> method unlinks (deletes) the large object.
4281       </para>
4282     </refsect1>
4283
4284   </refentry>
4285
4286 <!-- ********************************************************** -->
4287
4288   <refentry id="PYGRESQL-PGLARGEOBJECT-SIZE">
4289     <refmeta>
4290       <refentrytitle>size</refentrytitle>
4291       <refmiscinfo>PYGRESQL - Size</refmiscinfo>
4292     </refmeta>
4293     <refnamediv>
4294       <refname>size</refname>
4295       <refpurpose>gives the large object size</refpurpose>
4296     </refnamediv>
4297
4298     <refsynopsisdiv>
4299 <synopsis>
4300 size()
4301 </synopsis>
4302
4303       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SIZE-1">
4304         <title>Parameters</title>
4305         <para>
4306           none
4307         </para>
4308       </refsect2>
4309
4310       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SIZE-2">
4311         <title>Return Type</title>
4312         <variablelist>
4313           <varlistentry>
4314             <term>
4315               integer
4316             </term>
4317             <listitem>
4318               <para>
4319                 The large object size.
4320               </para>
4321             </listitem>
4322           </varlistentry>
4323         </variablelist>
4324       </refsect2>
4325
4326       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-SIZE-3">
4327         <title>Exceptions</title>
4328         <variablelist>
4329           <varlistentry>
4330             <term>
4331               <errorname>SyntaxError</errorname>
4332             </term>
4333             <listitem>
4334               <para>
4335                 Too many arguments.
4336               </para>
4337             </listitem>
4338           </varlistentry>
4339           <varlistentry>
4340             <term>
4341               <errorname>IOError</errorname>
4342             </term>
4343             <listitem>
4344               <para>
4345                 Object is not opened, or seek/tell error.
4346               </para>
4347             </listitem>
4348           </varlistentry>
4349           <varlistentry>
4350             <term>
4351               <errorname>pg.error</errorname>
4352             </term>
4353             <listitem>
4354               <para>
4355                 Invalid  connection or invalid object.
4356               </para>
4357             </listitem>
4358           </varlistentry>
4359         </variablelist>
4360       </refsect2>
4361
4362     </refsynopsisdiv>
4363
4364     <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-SIZE-1">
4365       <title>Description</title>
4366       <para>
4367         <function>size()</function> method allows to get the size of
4368         the large object. It was implemented because this function
4369         is very useful for a WWW interfaced database.
4370         Currently the large object needs to be opened.
4371       </para>
4372     </refsect1>
4373
4374   </refentry>
4375
4376 <!-- ********************************************************** -->
4377
4378   <refentry id="PYGRESQL-PGLARGEOBJECT-EXPORT">
4379     <refmeta>
4380       <refentrytitle>export</refentrytitle>
4381       <refmiscinfo>PYGRESQL - Export</refmiscinfo>
4382     </refmeta>
4383     <refnamediv>
4384       <refname>export</refname>
4385       <refpurpose>saves the large object to file</refpurpose>
4386     </refnamediv>
4387
4388     <refsynopsisdiv>
4389 <synopsis>
4390 export(<replaceable>filename</replaceable>)
4391 </synopsis>
4392
4393       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-1">
4394         <title>Parameters</title>
4395         <variablelist>
4396           <varlistentry>
4397             <term>
4398               <replaceable>filename</replaceable>
4399             </term>
4400             <listitem>
4401               <para>
4402                 The file to be created.
4403               </para>
4404             </listitem>
4405           </varlistentry>
4406         </variablelist>
4407       </refsect2>
4408
4409       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-2">
4410         <title>Return Type</title>
4411         <para>
4412           none
4413         </para>
4414       </refsect2>
4415
4416       <refsect2 id="R2-PYGRESQL-PGLARGEOBJECT-EXPORT-3">
4417         <title>Exceptions</title>
4418         <variablelist>
4419           <varlistentry>
4420             <term>
4421               <errorname>TypeError</errorname>
4422             </term>
4423             <listitem>
4424               <para>
4425                 Bad argument type, or too many arguments.
4426               </para>
4427             </listitem>
4428           </varlistentry>
4429           <varlistentry>
4430             <term>
4431               <errorname>IOError</errorname>
4432             </term>
4433             <listitem>
4434               <para>
4435                 Object is not closed, or export error.
4436               </para>
4437             </listitem>
4438           </varlistentry>
4439           <varlistentry>
4440             <term>
4441               <errorname>pg.error</errorname>
4442             </term>
4443             <listitem>
4444               <para>
4445                 Invalid  connection or invalid object.
4446               </para>
4447             </listitem>
4448           </varlistentry>
4449         </variablelist>
4450       </refsect2>
4451
4452     </refsynopsisdiv>
4453
4454     <refsect1 id="R1-PYGRESQL-PGLARGEOBJECT-EXPORT-1">
4455       <title>Description</title>
4456       <para>
4457         <function>export()</function> method allows to dump the
4458         content of a large object in a very simple way.
4459         The exported file is created on the host of the program,
4460         not the server host.
4461       </para>
4462     </refsect1>
4463
4464   </refentry>
4465
4466  </sect1>
4467
4468
4469  <sect1 id="pygresql-db-api">
4470   <title><acronym>DB-API</acronym> Interface</title>
4471
4472   <comment>
4473    This section needs to be written.
4474   </comment>
4475
4476   <para>
4477    See <ulink
4478    url="http://www.python.org/topics/database/DatabaseAPI-2.0.html"
4479    >http://www.python.org/topics/database/DatabaseAPI-2.0.html</ulink>
4480    for a description of the <acronym>DB-API</acronym> 2.0.
4481   </para>
4482  </sect1>
4483
4484 </chapter>