head	1.19;
access;
symbols
	REL7_3_21:1.18
	REL7_3_20:1.18
	REL7_3_19:1.18
	REL7_3_18:1.18
	REL7_3_17:1.18
	REL7_3_16:1.18
	REL7_3_15:1.18
	REL7_3_14:1.18
	REL7_3_13:1.18
	REL7_3_12:1.18
	REL7_3_11:1.18
	REL7_2_8:1.17
	REL7_3_10:1.18
	REL7_2_7:1.17
	REL7_3_9:1.18
	REL7_3_8:1.18
	REL7_2_6:1.17
	REL7_2_5:1.17
	REL7_3_7:1.18
	REL7_3_6:1.18
	REL7_3_4:1.18
	REL7_3_2:1.18
	REL7_2_4:1.17
	REL7_3_STABLE:1.18.0.2
	REL7_2_3:1.17
	REL7_2_STABLE:1.17.0.2
	REL7_2:1.17
	REL7_2_RC2:1.17
	REL7_2_RC1:1.17
	REL7_2_BETA5:1.17
	REL7_2_BETA4:1.17
	REL7_2_BETA3:1.16
	REL7_2_BETA2:1.15
	REL7_2_BETA1:1.14
	REL7_1_2:1.11
	REL7_1_STABLE:1.11.0.2
	REL7_1_BETA:1.7
	REL7_1_BETA3:1.7
	REL7_1_BETA2:1.7
	REL7_1:1.10
	REL7_0_PATCHES:1.5.0.4
	REL7_0:1.5
	REL6_5_PATCHES:1.5.0.2
	REL6_5:1.5
	REL6_4:1.1.0.2
	release-6-3:1.1;
locks; strict;
comment	@# @;


1.19
date	2003.08.01.04.19.04;	author scrappy;	state dead;
branches;
next	1.18;

1.18
date	2002.09.23.21.10.12;	author petere;	state Exp;
branches;
next	1.17;

1.17
date	2001.12.03.12.39.44;	author darcy;	state Exp;
branches;
next	1.16;

1.16
date	2001.11.19.03.58.25;	author tgl;	state Exp;
branches;
next	1.15;

1.15
date	2001.11.04.19.47.16;	author darcy;	state Exp;
branches;
next	1.14;

1.14
date	2001.09.10.04.21.14;	author momjian;	state Exp;
branches;
next	1.13;

1.13
date	2001.06.20.11.20.34;	author darcy;	state Exp;
branches;
next	1.12;

1.12
date	2001.05.15.13.28.56;	author darcy;	state Exp;
branches;
next	1.11;

1.11
date	2001.05.02.11.21.57;	author darcy;	state Exp;
branches;
next	1.10;

1.10
date	2001.03.25.22.22.51;	author darcy;	state Exp;
branches;
next	1.9;

1.9
date	2001.03.03.13.54.35;	author darcy;	state Exp;
branches;
next	1.8;

1.8
date	2001.02.02.18.21.59;	author momjian;	state Exp;
branches;
next	1.7;

1.7
date	2000.11.10.22.29.20;	author momjian;	state Exp;
branches;
next	1.6;

1.6
date	2000.10.02.03.27.27;	author momjian;	state Exp;
branches;
next	1.5;

1.5
date	99.05.19.14.46.54;	author scrappy;	state Exp;
branches;
next	1.4;

1.4
date	99.05.17.06.15.25;	author momjian;	state Exp;
branches;
next	1.3;

1.3
date	99.05.10.16.10.38;	author momjian;	state dead;
branches;
next	1.2;

1.2
date	98.12.17.01.43.03;	author momjian;	state Exp;
branches;
next	1.1;

1.1
date	98.01.25.06.09.18;	author scrappy;	state Exp;
branches
	1.1.2.1;
next	;

1.1.2.1
date	98.12.17.01.43.37;	author momjian;	state Exp;
branches;
next	;


desc
@@


1.19
log
@
remove python module, as its moved to http://www.pygresql.org
@
text
@
PyGreSQL - v3.3: PostgreSQL module for Python
==============================================

0. Copyright notice
===================

  PyGreSQL, version 3.3
  A Python interface for PostgreSQL database.
  Written by D'Arcy J.M. Cain, darcy@@druid.net<BR>
  Based heavily on code written by Pascal Andre, andre@@chimay.via.ecp.fr.
  Copyright (c) 1995, Pascal ANDRE (andre@@via.ecp.fr)

  Permission to use, copy, modify, and distribute this software and its
  documentation for any purpose, without fee, and without a written agreement
  is hereby granted, provided that the above copyright notice and this
  paragraph and the following two paragraphs appear in all copies or in any 
  new file that contains a substantial portion of this file.

  IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, 
  SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, 
  ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE 
  AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

  THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED
  TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
  PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE 
  AUTHOR HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, 
  ENHANCEMENTS, OR MODIFICATIONS.

  Further modifications copyright 1997 - 2000 by D'Arcy J.M. Cain
  (darcy@@druid.net) subject to the same terms and conditions as above.

  Note that as of March 1 2001 the development of PyGreSQL has been moved
  directly into the PostgreSQL development tree and is subject to the
  PostgreSQL copyright except where contradicted by the above copyrights
  in which case the above copyrights apply.


1. Presentation
===============

1.1. Introduction
-----------------

PostgreSQL is a database system derived from Postgres4.2. It conforms to
(most of) ANSI SQL and offers many interesting capabilities (C dynamic linking
for functions or type definition, etc.). This package is copyright by the
Regents of the University of California, and is freely distributable.

Python is an interpreted programming language. It is object oriented, simple
to use (light syntax, simple and straightforward statements), and has many
extensions for building GUIs, interfacing with WWW, etc. An intelligent web
browser (HotJava like) is currently under development (November 1995), and
this should open programmers many doors. Python is copyrighted by Stichting S
Mathematisch Centrum, Amsterdam, The Netherlands, and is freely distributable.

PyGreSQL is a python module that interfaces to a PostgreSQL database. It
embeds the PostgreSQL query library to allow easy use of the powerful
PostgreSQL features from a Python script.

PyGreSQL 2.0 was developed and tested on a NetBSD 1.3_BETA system.  It is
based on the PyGres95 code written by Pascal Andre, andre@@chimay.via.ecp.fr.
I changed the version to 2.0 and updated the code for Python 1.5 and
PostgreSQL 6.2.1.  While I was at it I upgraded the code to use full ANSI 
style prototypes and changed the order of arguments to connect.


1.2. Distribution files
-----------------------

  README       - this file
  Announce     - announcement of this release
  ChangeLog    - changes that affected this package during its history
  pgmodule.c   - the C python module
  pg.py        - PyGreSQL DB class.
  pgdb.py      - DB-SIG DB-API 2.0 compliant API wrapper for PygreSQL
  tutorial/    - demos directory
                 Content: basics.py, syscat.py, advanced.py, func.py and
                 pgtools.py.  The samples here have been taken from the
                 PostgreSQL manual and were used for module testing.  They
                 demonstrate some PostgreSQL features.  Pgtools.py is an
                 add-in used for demonstration.

1.3. Installation
-----------------

* If you are building this from source on most systems you can simply add
  the flag "--with-python" to the Configure command when building PostgreSQL.
  This will cause PyGreSQL to be built at the same time.  For this to work
  you must already have built Python as well as the mxDateTime package
  from http://starship.python.net/~lemburg/mxDateTime.html.

* For a Linux x86 system that uses RPMs, you can pick up an RPM at 
  ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm

* Note that if you are using the DB-API module you must also install
  mxDateTime from http://starship.python.net/~lemburg/mxDateTime.html.

* Also, check out setup.py for an alternate method of installing the package.

You have two options.  You can compile PyGreSQL as a stand-alone module 
or you can build it into the Python interpreter.

GENERAL 

* You must first have installed Python and PostgreSQL on your system.
  The header files and developer's libraries for both Python and PostgreSQL
  must be installed on your system before you can build PyGreSQL.  If you 
  built both Python and PostgreSQL from source, you should be fine.  If your 
  system uses some package mechanism (such as RPMs or NetBSD packages), then 
  you probably need to install packages such as Python-devel in addition to 
  the Python package.

* PyGreSQL is implemented as three parts, a C module labeled _pg and two
  Python wrappers called pg.py and pgdb.py.  This changed between 2.1 and
  2.2 and again in 3.0.  These changes should not affect any existing
  programs but the installation is slightly different.

* Download and unpack the PyGreSQL tarball if you haven't already done so.

STAND-ALONE

* In the directory containing pgmodule.c, run the following command
  cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c
  where:
    [pyInc] = path of the Python include (usually Python.h)
    [pgInc] = path of the PostgreSQL include (usually postgres.h)
    [pgLib] = path of the PostgreSQL libraries (usually libpq.so or libpq.a)
  Some options may be added to this line:
    -DNO_DEF_VAR  - no default variables support
    -DNO_DIRECT   - no direct access methods
    -DNO_LARGE    - no large object support
    -DNO_SNPRINTF - if running a system with no snprintf call
    -DNO_PQSOCKET - if running an older PostgreSQL

  On some systems you may need to include -lcrypt in the list of libraries
  to make it compile.

  Define NO_PQSOCKET if you are using a version of PostgreSQL before 6.4
  that does not have the PQsocket function.  The other options will be
  described in the next sections.

* Test the new module.  Something like the following should work.
  
  $ python

  >>> import _pg
  >>> db = _pg.connect('thilo','localhost')
  >>> db.query("INSERT INTO test VALUES ('ping','pong')")
  18304
  >>> db.query("SELECT * FROM test")
  eins|zwei
  ----+----
  ping|pong
  (1 row)

* Finally, move the _pg.so, pg.py, and pgdb.py to a directory in your 
  PYTHONPATH.  A good place would be /usr/lib/python1.5/site-python if
  your Python modules are in /usr/lib/python1.5.

BUILT-IN TO PYTHON INTERPRETER

* Find the directory where your 'Setup' file lives (usually ??/Modules) in 
  the Python source hierarchy and copy or symlink the 'pgmodule.c' file there.

* Add the following line to your Setup file
    _pg  pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems
  where:
    [pgInc] = path of PostgreSQL include (often /usr/local/include/python1.5)
    [pgLib] = path of the PostgreSQL libraries (often /usr/local/lib/python1.5)
  Some options may be added to this line:
    -DNO_DEF_VAR  - no default variables support
    -DNO_DIRECT   - no direct access methods
    -DNO_LARGE    - no large object support
    -DNO_SNPRINTF - if running a system with no snprintf call
    -DNO_PQSOCKET - if running an older PostgreSQL

  Define NO_PQSOCKET if you are using a version of PostgreSQL before 6.4
  that does not have the PQsocket function.  The other options will be
  described in the next sections.

* If you want a shared module, make sure that the "*shared*" keyword is
  uncommented and add the above line below it.  You used to need to install
  your shared modules with "make sharedinstall but this no longer seems
  to be true."

* Copy pg.py to the lib directory where the rest of your modules are. For
  example, that's /usr/local/lib/Python on my system.

* Rebuild Python from the root directory of the Python source hierarchy by 
  running 'make -f Makefile.pre.in boot' and 'make && make install'

* For more details read the documentation at the top of Makefile.pre.in


1.4. Where to get ... ?
-----------------------

The home sites of the different packages are:

  - Python:     http://www.python.org/
  - PosgreSQL:  http://www.PostgreSQL.org/
  - PyGreSQL:   http://www.druid.net/pygresql/

A Linux RPM can be picked up from
ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm.  A NetBSD package thould
be in the distribution soon and is available at
ftp://ftp.druid.net/pub/distrib/pygresql.pkg.tgz.  A WIN32 package is
available at http://highqualdev.com/.

1.5. Information and support
----------------------------

If you need information about these packages please check their web sites:

  - Python:     http://www.python.org/
  - PostgreSQL: http://www.postgresql.org/
  - PyGres95:   http://www.via.ecp.fr/via/products/pygres.html
  - PyGreSQL:   http://www.druid.net/pygresql/

For support:

  - Python:      newgroup comp.lang.python
  - PostgreSQL:  mailing list (see package documentation for information)
  - PyGres95:    contact me (andre@@via.ecp.fr) for bug reports, ideas,
                 remarks I will try to answer as long as my free time allow
                 me to do that.
  - PyGreSQL:    contact me (darcy@@druid.net) concerning the changes to 2.x
                 and up.  If you would like to proposes changes please 
                 join the PyGreSQL mailing list and send context diffs
                 there.  See http://www.vex.net/mailman/listinfo/pygresql
                 to join the mailing list.


2. Programming information
==========================

See main PostgreSQL documentation.


3. Todo
=======

The large object and direct access functions need much more attention.

An update query should return the number of rows affected.

The C module needs to be cleaned up and redundant code merged.

The DB-API module needs to be documented.

The fetch method should use real cursors.


4. Future directions
====================

Users should be able to register their own types with _pg.

I would like a new method that returns a dictionary of dictionaries from
a SELECT.


@


1.18
log
@Move PyGreSQL usage documentation from README into DocBook.  Some other
editing.
@
text
@@


1.17
log
@Bump version to 3.3.  Mostly this is because there is some confusion about
the latest version and I wanted to make sure that there was a clean release.

I also change the build files as I discussed in my letter of Nov 6, 2001.  At
the time I was asked to hold off until after the release.
@
text
@d66 1
a66 2
style prototypes and changed the order of arguments to connect.  The latest
version of PyGreSQL works with PostgreSQL 7.1.3 and Python 2.1.
d94 1
a94 2
* For Linux installation look at README.linux.  If you're on an x86 system 
  that uses RPMs, then you can pick up an RPM at 
d239 1
a239 835
You may either choose to use the old, mature interface provided by the
'pg' module or else the newer 'pgdb' interface compliant with DB-API 2.0
specification developed by the Python DB-SIG.

The remainder of this chapter and the next chapter describe only
the older 'pg' API.  As long as PyGreSQL does not contain a
description of the DB-API you should read about the API at
http://www.python.org/topics/database/DatabaseAPI-2.0.html

A tutorial like introduction to the DB-API can be found at
http://www2.linuxjournal.com/lj-issues/issue49/2605.html

The 'pg' module defines three objects: the pgobject that handles the connection
and all the requests to the database, the pglargeobject that handles
all the accesses to Postgres large objects and pgqueryobject that handles
query results.

If you want to see a simple example of the use of some of these functions,
see http://www.druid.net/rides/ where I have a link at the bottom to the
actual Python code for the page.

2.1. pg module description
----------------------------

The module defines only a few methods that allow to connect to a database and
to allow to define "default variables" that override the environment variables
used by PostgreSQL. 

These "default variables" were designed to allow you to handle general 
connection parameters without heavy code in your programs. You can prompt the
user for a value, put it in the default variable, and forget it, without 
having to modify your environment. The support for default variables can be
disabled by setting the -DNO_DEF_VAR option in the Python Setup file. Methods
relative to this are specified by te tag [DV].

All variables are set to None at module initialization, specifying that 
standard environment variables should be used.

  2.1.1. connect - opens a pg connection
  ----------------------------------------

  Syntax:      
    connect(dbname, host, port, opt, tty, user, passwd)
  Parameters: 
    dbname        - name of connected database (string/None)
    host          - name of the server host (string/None)
    port          - port used by the database server (integer/-1)
    opt           - connection options (string/None)
    tty           - debug terminal (string/None)
	user          - PostgreSQL user (string/None)
    passwd        - password for user (string/None)
  Return type:
    pgobject      - the object handling the connection
  Exceptions raised:
    TypeError     - bad argument type, or too many arguments
    SyntaxError   - duplicate argument definition 
    pg.error      - some error occurred during pg connection definition
    (+ all exceptions relative to object allocation)
  Description:
    This method opens a connection to a specified database on a given
    PostgreSQL server. You can use keywords here, as described in the
    Python tutorial; 
    the names of the keywords are the name of the parameters given in the 
    syntax line. For a precise description of the parameters, please refer to 
    the PostgreSQL user manual.

  2.1.2. get_defhost, set_defhost - default server host name handling [DV]
  ------------------------------------------------------------------------

  Syntax: get_defhost()
  Parameters: 
    none
  Return type:
    string, None  - default host specification
  Exceptions raised:
    SyntaxError   - too many arguments
  Description:
    This method returns the current default host specification, or None if the
    environment variables should be used. Environment variables won't be looked
    up.

  Syntax: set_defhost(host)
  Parameters:
    host          - new default host (string/None)
  Return type:
    string, None  - previous default host specification
  Exceptions raised:
    TypeError     - bad argument type, or too many arguments
  Description:
    This methods sets the default host value for new connections. If None is
    supplied as parameter, environment variables will be used in future 
    connections. It returns the previous setting for default host.

  2.1.3. get_defport, set_defport - default server port handling [DV]
  -------------------------------------------------------------------

  Syntax: get_defport()
  Parameters: none
  Return type:
    integer, None - default port specification
  Exceptions raised:
    SyntaxError   - too many arguments
  Description: 
    This method returns the current default port specification, or None if
    the environment variables should be used. Environment variables won't
    be looked up.

  Syntax: set_defport(port)
  Parameters:
    port          - new default port (integer/-1)
  Return type:
    integer, None - previous default port specification
  Description:
    This methods sets the default port value for new connections. If -1 is
    supplied as parameter, environment variables will be used in future 
    connections. It returns the previous setting for default port.

  2.1.4. get_defopt, set_defopt - default connection options handling [DV]
  ------------------------------------------------------------------------

  Syntax: get_defopt()
  Parameters: none
  Return type:
    string, None  - default options specification
  Exceptions raised:
    SyntaxError   - too many arguments
  Description:
    This method returns the current default connection options  specification,
    or None if the environment variables should be used. Environment variables 
    won't be looked up.

  Syntax: set_defopt(options)
  Parameters:
    options       - new default connection options (string/None)
  Return type:
    string, None  - previous default options specification
  Exceptions raised:
    TypeError     - bad argument type, or too many arguments
  Description:
    This methods sets the default connection options value for new connections.
    If None is supplied as parameter, environment variables will be used in 
    future connections. It returns the previous setting for default options.

  2.1.5. get_deftty, set_deftty - default connection debug tty handling [DV]
  --------------------------------------------------------------------------

  Syntax: get_deftty()
  Parameters: none
  Return type:
    string, None  - default debug terminal specification
  Exceptions raised:
    SyntaxError   - too many arguments
  Description:
    This method returns the current default debug terminal specification, or 
    None if the environment variables should be used. Environment variables 
    won't be looked up.

  Syntax: set_deftty(terminal)
  Parameters:
    terminal      - new default debug terminal (string/None)
  Return type:
    string, None  - previous default debug terminal specification
  Exceptions raised:
    TypeError     - bad argument type, or too many arguments
  Description:
    This methods sets the default debug terminal value for new connections. If
    None is supplied as parameter, environment variables will be used in future
    connections. It returns the previous setting for default terminal.

  2.1.6. get_defbase, set_defbase - default database name handling [DV]
  ---------------------------------------------------------------------

  Syntax: get_defbase()
  Parameters: none
  Return type:
    string, None  - default database name specification
  Exceptions raised:
    SyntaxError   - too many arguments
  Description:
    This method returns the current default database name specification, or 
    None if the environment variables should be used. Environment variables 
    won't be looked up.

  Syntax: set_defbase(base)
  Parameters:
    base          - new default base name (string/None)
  Return type:
    string, None  - previous default database name specification
  Exceptions raised:
    TypeError     - bad argument type, or too many arguments
  Description:
    This method sets the default database name value for new connections. If 
    None is supplied as parameter, environment variables will be used in 
    future connections. It returns the previous setting for default host.

  2.1.7. Module constants
  -----------------------

  Some constants are defined in the module dictionary. They are intended to be
used as parameters for methods calls. You should refer to PostgreSQL user 
manual for more information about them. These constants are:

  - large objects access modes, used by (pgobject.)locreate and 
    (pglarge.)open: (pg.)INV_READ, (pg.)INV_WRITE
  - positional flags, used by (pglarge.)seek: (pg.)SEEK_SET, 
    (pg.)SEEK_CUR, (pg.)SEEK_END.
  - version and __version__ constants that give the current version.

  2.1.9. 
  2.1.10. Miscellaneous attributes

  The following methods return information about the current connection.

  - 
2.2. pgobject description
---------------------------

  This object handle a connection to a PostgreSQL database. It embeds and 
hides all the parameters that define this connection, thus just leaving really
significant parameters in function calls.
  Some methods give direct access to the connection socket. They are specified
by the tag [DA]. DO NOT USE THEM UNLESS YOU REALLY KNOW WHAT YOU ARE DOING. If
you prefer disabling them, set the -DNO_DIRECT option in the Python Setup file.
  Some other methods give access to large objects (refer to PostgreSQL user
manual for more information about these). if you want to forbid access to these
from the module, set the -DNO_LARGE option in the Python Setup file. These 
methods are specified by the tag [LO].

  2.2.1. query - executes a SQL command string
  --------------------------------------------

  Syntax: query(command)
  Parameters:
    command       - SQL command (string)
  Return type:
    pgqueryobject, None    - result values
  Exceptions raised:
    TypeError     - bad argument type, or too many arguments.
    ValueError    - empty SQL query
    pg.error      - error during query processing, or invalid connection
  Description:
    This method simply sends a SQL query to the database. If the query is
    an insert statement, the return value is the OID of the newly
    inserted row.  If it is otherwise a query that does not return a result
    (ie. is not a some kind of SELECT statement), it returns None.
    Otherwise, it returns a pgqueryobject that can be accessed via the
    getresult or dictresult method or simply printed.

  pgqueryobject methods
  ---------------------

    2.2.1.1. getresult - gets the values returned by the query
    -------------------------------------------------------------

    Syntax: getresult()
    Parameters: none
    Return type:
      list          - result values
    Exceptions raised:
      SyntaxError   - too many parameters
      pg.error      - invalid previous result
    Description:
      This method returns the list of the values returned by the query.
      More information about this result may be accessed using listfields,
      fieldname and fieldnum methods.

    2.2.1.2. dictresult - like getresult but returns list of dictionaries
    ---------------------------------------------------------------------

    Syntax: dictresult()
    Parameters: none
    Return type:
      list          - result values as a dictionary
    Exceptions raised:
      SyntaxError   - too many parameters
      pg.error      - invalid previous result
    Description:
      This method returns the list of the values returned by the query
      with each tuple returned as a dictionary with the field names
      used as the dictionary index.


    2.2.1.3. listfields - lists the fields names of the previous query result
    -----------------------------------------------------------------------

    Syntax: listfields()
    Parameters: none
    Return type:
      list          - fields names
    Exceptions raised:
      SyntaxError   - too many parameters
      pg.error      - invalid previous result, or invalid connection
    Description:
      This method returns the list of names of the fields defined for the
      query result. The fields are in the same order as the result values.
  
    2.2.1.4. fieldname, fieldnum - field name-number conversion
    ---------------------------------------------------------

    Syntax: fieldname(i)
    Parameters:
      i              - field number (integer)
    Return type:
      string         - field name
    Exceptions raised:
      TypeError      - bad parameter type, or too many parameters
      ValueError     - invalid field number
      pg.error       - invalid previous result, or invalid connection
    Description:
      This method allows to find a field name from its rank number. It can be 
      useful for displaying a result. The fields are in the same order as the
      result values.

    Syntax: fieldnum(name)
    Parameters:
      name           - field name (string)
    Return type:
      integer        - field number
    Exceptions raised:
      TypeError      - bad parameter type, or too many parameters
      ValueError     - unknown field name
      pg.error       - invalid previous result, or invalid connection
    Description:
      This method returns a field number from its name.  It can be used to
      build a function that converts result list strings to their correct
      type, using a hardcoded table definition.  The number returned is the
      field rank in the result values list.

    2.2.1.5 ntuples - return number of tuples in query object
    ---------------------------------------------------------

    Syntax: ntuples()
    Parameters: None
    Return type: integer
    Description:
      This method returns the number of tuples found in a query.


  2.2.2. reset - resets the connection
  ------------------------------------

  Syntax: reset()
  Parameters: None
  Return type: None
  Exceptions raised:
    TypeError     -  too many (any) arguments
  Description:
    This method resets the current database.


  2.2.3. close - close the database connection
  --------------------------------------------

  Syntax: close()
  Parameters: none
  Return type: None
  Exceptions raised:
    TypeError     -  too many (any) arguments
  Description:
    This method closes the database connection.  The connection will
    be closed in any case when the connection is deleted but this
    allows you to explicitly close it.  It is mainly here to allow
    the DB-SIG API wrapper to implement a close function.


  2.2.4. fileno - returns the socket used to connect to the database
  ------------------------------------------------------------------

  Syntax: fileno()
  Parameters: none
    Exceptions raised:
    TypeError     -  too many (any) arguments
  Description:
    This method returns the underlying socket id used to connect
    to the database.  This is useful for use in select calls, etc.
    Note:  This function depends on having a recent version of the
    database.  See "-DNO_PQSOCKET" described above.


  2.2.5. getnotify - gets the last notify from the server
  -------------------------------------------------------

  Syntax: getnotify()
  Parameters: none
  Return type:
    tuple, None    - last notify from server
  Exceptions raised:
    SyntaxError    - too many parameters
    pg.error       - invalid connection
  Description:
    This methods try to get a notify from the server (from the SQL statement 
    NOTIFY). If the server returns no notify, the methods returns None. 
    Otherwise, it returns a tuple (couple) (relname, pid), where relname is the
    name of the notify and pid the process id of the connection that triggered 
    the notify.  Remember to do a listen query first otherwise getnotify
    will always return None.

  2.2.6. inserttable - insert a list into a table
  -----------------------------------------------

  Syntax: inserttable(table, values)
  Parameters:
    table          - the table name (string)
    values         - list of rows values (list)
  Return type:
    None
  Exception raised:
    pg.error       - invalid connection
    TypeError      - bad argument type, or too many arguments
  Description:
    This method allow to quickly insert large blocks of data in a table: it
    inserts the whole values list into the given table. The list is a list of
    tuples/lists that define the values for each inserted row. The rows values
    may contain string, integer, long or double (real) values. 
    BE VERY CAREFUL: this method doesn't typecheck the fields according to the
    table definition; it just look whether or not it knows how to handle such
    types.

  2.2.7. putline - writes a line to the server socket [DA]
  --------------------------------------------------------

  Syntax: putline(line)
  Parameters:
    line           - line to be written (string)
  Return type:
    None
  Exceptions raised:
    pg.error       - invalid connection
    TypeError      - bad parameter type, or too many parameters
  Description: 
    This method allows to directly write a string to the server socket.

  2.2.8. getline - gets a line from server socket [DA]
  ----------------------------------------------------

  Syntax: getline()
  Parameters: none
  Return type:
    string         - the line read
  Exceptions raised:
    pg.error       - invalid connection
    SyntaxError    - too many parameters
  Description:
    This method allows to directly read a string from the server socket.

  2.2.9. endcopy - synchronizes client and server [DA]
  ----------------------------------------------------

  Syntax: endcopy()
  Parameters: none
  Return type:
    None
  Exceptions raised:
    pg.error       - invalid connection
    SyntaxError    - too many parameters
  Description:
    The use of direct access methods may desynchonize client and server. This
    method ensure that client and server will be synchronized.

  2.2.10. locreate - creates of large object in the database [LO]
  ---------------------------------------------------------------

  Syntax: locreate(mode)
  Parameters:
    mode           - large object create mode
  Return type:
    pglarge        - object handling the postgres large object
  Exceptions raised:
    pg.error       - invalid connection, or creation error
    TypeError      - bad parameter type, or too many parameters
  Description:
    This method creates a large object in the database. The mode can be defined
    by OR-ing the constants defined in the pg module (INV_READ, INV_WRITE and
    INV_ARCHIVE). Please refer to PostgreSQL user manual for a description of
    the mode values.

  2.2.11. getlo - builds a large object from given oid [LO]
  ---------------------------------------------------------

  Syntax: getlo(oid)
  Parameters:
    oid            - oid of the existing large object (integer)
  Return type:
    pglarge        - object handling the postgres large object
  Exceptions raised:
    pg.error       - invalid connection
    TypeError      - bad parameter type, or too many parameters
    ValueError     - bad oid value (0 is invalid_oid)
  Description:
    This method allows to reuse a formerly created large object through the 
    pglarge interface, providing the user have its oid.

  2.2.12. loimport - import a file to a postgres large object [LO]
  ----------------------------------------------------------------

  Syntax: loimport(name)
  Parameters:
    name           - the name of the file to be imported (string)
  Return type:
    pglarge        - object handling the postgres large object
  Exceptions raised:
    pg.error       - invalid connection, or error during file import
    TypeError      - bad argument type, or too many arguments
  Description: 
    This methods allows to create large objects in a very simple way. You just 
    give the name of a file containing the data to be use.

  2.2.13. pgobject attributes
  -----------------------------

  Every pgobject defines a set of read-only attributes that describe the 
connection and its status. These attributes are:
  host             - the hostname of the server (string)
  port             - the port of the server (integer)
  db               - the selected database (string)
  options          - the connection options (string)
  tty              - the connection debug terminal (string)
  user             - the username on the database system (string)
  status           - the status of the connection (integer: 1 - OK, 0 - BAD)
  error            - the last warning/error message from the server (string)

2.3. pglarge description
--------------------------

  This object handles all the request concerning a postgres large object. It 
embeds and hides all the 'recurrent' variables (object oid and connection), 
exactly in the same way pgobjects do, thus only keeping significant 
parameters in function calls. It keeps a reference to the pgobject used for
its creation, sending requests though with its parameters. Any modification but
dereferencing the pgobject will thus affect the pglarge object. 
Dereferencing the initial pgobject is not a problem since Python won't 
deallocate it before the large object dereference it.
  All functions return a generic error message on call error, whatever the 
exact error was. The 'error' attribute of the object allow to get the exact 
error message.

  2.3.1. open - opens a large object
  ----------------------------------

  Syntax: open(mode)
  Parameters:
    mode           - open mode definition (integer)
  Return type:
    None
  Exceptions raised:
    pg.error       - invalid connection
    TypeError      - bad parameter type, or too many parameters
    IOError        - already opened object, or open error
  Description:
    This method opens a large object for reading/writing, in the same way than
    the UNIX open() function. The mode value can be obtained by OR-ing the 
    constants defined in the pgmodule (INV_READ, INV_WRITE).

  2.3.2. close - closes a large object
  ------------------------------------

  Syntax: close()
  Parameters: none
  Return type:
    None
  Exceptions raised:
    pg.error       - invalid connection
    SyntaxError    - too many parameters
    IOError        - object is not opened, or close error
  Description:
    This method closes a previously opened large object, in the same way than 
    the UNIX close() function.

  2.3.4. read, write, tell, seek, unlink - file like large object handling
  ------------------------------------------------------------------------

  Syntax: read(size)
  Parameters:
    size           - maximal size of the buffer to be read
  Return type:
    sized string   - the read buffer
  Exceptions raised:
    pg.error       - invalid connection or invalid object
    TypeError      - bad parameter type, or too many parameters
    IOError        - object is not opened, or read error
  Description:
    This function allows to read data from a large object, starting at current
    position.

  Syntax: write(string)
  Parameters:
    (sized) string - buffer to be written
  Return type:
    None
  Exceptions raised:
    pg.error       - invalid connection or invalid object
    TypeError      - bad parameter type, or too many parameters
    IOError        - object is not opened, or write error
  Description:
    This function allows to write data to a large object, starting at current 
    position.

  Syntax: seek(offset, whence)
  Parameters:
    offset          - position offset
    whence          - positional parameter
  Return type:
    integer         - new position in object
  Exception raised:
    pg.error        - invalid connection or invalid object
    TypeError       - bad parameter type, or too many parameters
    IOError         - object is not opened, or seek error
  Description:
    This method allows to move the position cursor in the large object. The 
    whence parameter can be obtained by OR-ing the constants defined in the 
    pg module (SEEK_SET, SEEK_CUR, SEEK_END).

  Syntax: tell()
  Parameters: none
  Return type:
    integer         - current position in large object
  Exception raised:
    pg.error        - invalid connection or invalid object
    SyntaxError     - too many parameters
    IOError         - object is not opened, or seek error
  Description:
    This method allows to get the current position in the large object.

  Syntax: unlink()
  Parameter: none
  Return type:
    None
  Exception raised:
    pg.error        - invalid connection or invalid object
    SyntaxError     - too many parameters
    IOError         - object is not closed, or unlink error
  Description:
    This methods unlinks (deletes) the postgres large object.

  2.3.5. size - gives the large object size
  -----------------------------------------

  Syntax: size()
  Parameters: none
  Return type:
    integer         - large object size
  Exceptions raised:
    pg.error        - invalid connection or invalid object
    SyntaxError     - too many parameters
    IOError         - object is not opened, or seek/tell error
  Description:
    This (composite) method allows to get the size of a large object. Currently
    the large object needs to be opened. It was implemented because this 
    function is very useful for a WWW interfaced database.

  2.3.6. export - saves a large object to a file
  ----------------------------------------------

  Syntax: export(name)
  Parameters:
    name            - file to be created
  Return type:
    None
  Exception raised:
    pg.error        - invalid connection or invalid object
    TypeError       - bad parameter type, or too many parameters
    IOError         - object is not closed, or export error
  Description:
    This methods allows to dump the content of a large object in a very simple
    way. The exported file is created on the host of the program, not the 
    server host.

  2.3.7. Object attributes
  ------------------------

  pglarge objects define a read-only set of attributes that allow to get some
information about it. These attributes are:
  oid                - the oid associated with the object
  pgcnx              - the pgobject associated with the object
  error              - the last warning/error message of the connection
BE CAREFUL:  in multithreaded environments, 'error' may be modified by another
thread using the same pgobject. Remember these object are shared, not 
duplicated. You should provide some locking to be able if you want to check 
this.
  The oid attribute is very interesting because it allow you reuse the oid 
later, creating the pglarge object with a pgobject getlo() method call.


3. The pg wrapper
================

The previous functions are wrapped in a module called pg.  The module
has a class called DB.  The above functions are also included in the
name space so it isn't necessary to import both modules.  The preferred
way to use this module is as follows.

import pg
db = pg.DB(...) # See description of the initialization method below.

The following describes the methods and variables of this class.


 3.1. Initialization
 -------------------
 The DB class is initialized with the same arguments as the connect
 method described in section 2.  It also initializes a few internal
 variables.  The statement 'db = DB()' will open the local database
 with the name of the user just like connect() does.

 3.2. pkey
 ---------
 Syntax:
   pkey(table)
 Parameters:
   table - name of table
 Returns:
   Name of field which is the primary key of the table.
 Description:
   This method returns the primary key of a table.  Note that this raises
   an exception if the table doesn't have a primary key.

 3.3. get_databases - get list of databases in the system
 --------------------------------------------------------
 Syntax: get_databases()
 Parameters: none
 Returns: list of databases in the system
 Description:
   Although you can do this with a simple select, it is added here for
   convenience

 3.4. get_tables - get list of tables in connected database
 ----------------------------------------------------------
 Syntax: get_tables() 
 Parameters: none
 Returns: list of tables in connected database

 3.5. get_attnames
 -----------------
 Syntax: 
   get_attnames(table)       
 Parameters: 
   table - name of table
 Returns:
   Dictionary of attribute names (the names are the keys, the values
   are the names of the attributes' types)
 Description:
   Given the name of a table, digs out the set of attribute names.

 3.6. get - get a tuple from a database table
 --------------------------------------------
 Syntax: 
   get(table, arg, [keyname])
 Parameters:
   table - name of table
   arg - either a dictionary or the value to be looked up
   keyname - name of field to use as key (optional)
 Returns:
   A dictionary mapping attribute names to row values.
 Description:
   This method is the basic mechanism to get a single row.  It assumes
   that the key specifies a unique row.  If keyname is not specified
   then the primary key for the table is used.  If arg is a dictionary
   then the value for the key is taken from it and it is modified to
   include the new values, replacing existing values where necessary.
   The oid is also put into the dictionary but in order to allow the
   caller to work with multiple tables, the attribute name is munged
   to make it unique.  It consists of the string "oid_" followed by
   the name of the table.


 3.7. insert - insert a tuple into a database table
 --------------------------------------------------
 Syntax:
   insert(table, a)
 Parameters:
   table - name of table
   a - a dictionary of values
 Returns:
   The OID of the newly inserted row.
 Description:
   This method inserts values into the table specified filling in the
   values from the dictionary.  It then reloads the dictionary with the
   values from the database.  This causes the dictionary to be updated
   with values that are modified by rules, triggers, etc.

   Due to the way that this function works you will find inserts taking
   longer and longer as your table gets bigger.  To overcome this problem
   simply add an index onto the OID of any table that you think may get
   large over time.


 3.8. update
 -----------
 Syntax:
   update(table, a)             
 Parameters:
   table - name of table
   a - a dictionary of values
 Returns:
   A dictionary with the new row
 Description:
   Similar to insert but updates an existing row.  The update is based
   on the OID value as munged by get.  The array returned is the
   one sent modified to reflect any changes caused by the update due
   to triggers, rules, defaults, etc.

 3.9. clear
 ----------
 Syntax:
   clear(table, [a])
 Parameters:
   table - name of table
   a - a dictionary of values
 Returns:
   A dictionary with an empty row
 Description:
   This method clears all the attributes to values determined by the types.
   Numeric types are set to 0, dates are set to 'TODAY' and everything
   else is set to the empty string.  If the array argument is present,
   it is used as the array and any entries matching attribute names
   are cleared with everything else left unchanged.

 3.8. delete
 -----------
 Syntax:
   delete(table, a)
 Parameters:
   table - name of table
   a - a dictionary of values
 Returns:
   None
 Description:
   This method deletes the row from a table.  It deletes based on the OID
   as munged as described above.


4. DB-API reference
===================

  This section needs to be written.
d242 1
a242 1
5. Todo
d256 1
a256 1
6. Future directions
@


1.16
log
@A bunch of small doco updates motivated by scanning the comments on
the interactive docs.
@
text
@d2 1
a2 1
PyGreSQL - v3.2: PostgreSQL module for Python
d8 1
a8 1
  PyGreSQL, version 3.2
@


1.15
log
@Note that PyGreSQL has been checked against Python 2.1 now.
@
text
@d979 2
a980 1
   List of attribute names
d982 1
a982 1
   Given the name of a table, digs out the list of attribute names.
@


1.14
log
@Remove INV_ARCHIVE mention in python readme.
@
text
@d67 1
a67 1
version of PyGreSQL works with PostgreSQL 7.1.2 and Python 2.0.
@


1.13
log
@Make sure that everything says version 3.2.
@
text
@d444 1
a444 1
    (pglarge.)open: (pg.)INV_READ, (pg.)INV_WRITE, (pg.)INV_ARCHIVE
@


1.12
log
@Fix small thinko.
@
text
@d67 1
a67 1
version of PyGreSQL works with PostgreSQL 6.5 and Python 1.5.2.
@


1.11
log
@Add note explaining why inserts take longer as tables grow.  Also suggest
the way to handle this.
@
text
@d551 1
a551 1
      useful for displaying a result. The fields are in the same order than the
@


1.10
log
@Document the --with-python flag as a simpler way of installing the
PyGreSQL module when installing PostgreSQL.

Document the location of the WIN32 binaries.
@
text
@d1020 5
@


1.9
log
@Incrementing version number in preparation for next release.  Note that I
am talking with Thomas Lockhart about the idea of bringing the PyGreSQL
version number into alignment with PostgreSQL so this may change to 7.1
before the release.

I have added to the copyright to indicate that from now on the PostgreSQL
copyright will apply.  If someone wants to make that clearer please do.
The existing copyrights need to stay there for now but if necessary I can
ask Pascal Andre if he agrees to a different wording.

Added reference to the Python DB-API 2.0 compliant API wrapper.

Added reference to the PyGreSQL mailing list.
@
text
@d89 5
a93 5
* If you are on NetBSD, look in the packages directory under databases. If
  it isn't there yet, it should be there shortly.  You can also pick up the
  package files from ftp://ftp.druid.net/pub/distrib/pygresql.pkg.tgz.
  There is also a package in the FreeBSD ports collection but as I write
  this it is at version 2.1.  I will try to get that updated as well.
d211 2
a212 1
ftp://ftp.druid.net/pub/distrib/pygresql.pkg.tgz.
@


1.8
log
@Apply patches for QNX from Maurizio
@
text
@d2 1
a2 1
PyGreSQL - v3.1: PostgreSQL module for Python
d8 1
a8 1
  PyGreSQL, version 3.1
d31 1
a31 1
  Further modifications copyright 1997, 1998 and 1999 by D'Arcy J.M. Cain
d34 6
d78 1
d117 4
a120 4
* PyGreSQL is implemented as two parts, a C module labeled _pg and a
  Python wrapper called pg.py.  This changed between 2.1 and 2.2.  This
  should not affect any existing programs but the installation is slightly
  different.
d227 8
a234 4
  - PyGres95:    contact me (andre@@via.ecp.fr) for bug reports, ideas, remarks
                 I will try to answer as long as my free time allow me to do 
                 that.
  - PyGreSQL:    contact me (darcy@@druid.net) concerning the changes to 2.x.
d240 13
a252 1
This module defines three objects: the pgobject that handles the connection 
d1082 1
a1082 1
The fetch method should use real cursers.
@


1.7
log
@Update to PyGreSQL 3.1:

Fix some quoting functions. In particular handle NULLs better.

Use a method to add primary key information rather than direct
manipulation of the class structures.

Break decimal out in _quote (in pg.py) and treat it as float.

Treat timestamp like date for quoting purposes.

Remove a redundant SELECT from the get method speeding it, and
insert since it calls get, up a little.

Add test for BOOL type in typecast method to pgdbTypeCache class.
(tv@@beamnet.de)

Fix pgdb.py to send port as integer to lower level function
(dildog@@l0pht.com)

Change pg.py to speed up some operations

Allow updates on tables with no primary keys.

D'Arcy J.M. Cain
@
text
@d2 1
a2 1
PyGreSQL - v2.5: PostgreSQL module for Python
d8 1
a8 1
  PyGreSQL, version 2.5
@


1.6
log
@Update for PyGreSQL 3.0, from D'Arcy J.M. Cain
@
text
@d92 3
d120 1
a120 1
  cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems
d132 3
d1058 2
@


1.5
log
@
Bring python up to date ...

From: D'Arcy J.M. Cain <darcy@@druid.net>
@
text
@d2 1
a2 1
PyGreSQL - v2.4: PostgreSQL module for Python
d8 1
a8 1
  PyGreSQL, version 2.4
d60 2
a61 1
style prototypes and changed the order of arguments to connect.
d82 24
a105 1
* You first have to get and build Python and PostgreSQL.
d112 43
a154 2
* Find the directory where your 'Setup' file lives (usually ??/Modules) and
  copy or symlink the 'pgmodule.c' file there.
d159 2
a160 2
    [pgInc] = path of the PostgreSQL include 
    [pgLib] = path of the PostgreSQL libraries 
d165 1
d177 1
a177 1
* Copy pg.py to the lib directory where the rest of your modules are.  For
d180 2
a181 1
* Do 'make -f Makefile.pre.in boot' and do 'make && make install'
a184 8
* If you are on NetBSD, look in the packages directory under databases.  If
  it isn't there yet, it should be there shortly.  You can also pick up the
  package files from ftp://ftp.druid.net/pub/distrib/pygresql.pkg.tgz.
  There is also a package in the FreeBSD ports collection but as I write
  this it is at version 2.1.  I will try to get that updated as well.

* For Linux installation look at README.linux

d195 4
a198 3
A Linux RPM can be picked up from ftp://www.eevolute.com/pub/python/.
A NetBSD package thould be in the distribution soon and is available
at ftp://ftp.druid.net/pub/distrib/pygresql.pkg.tgz.
d457 1
a457 1
    getresult method or printed.
d474 2
a475 2
      More information about this result may be get using listfields,
      fieldname and fiednum methods.
d902 2
a903 2
from pg import DB
db = DB(...) # See description of the initialization method below.
d1036 19
a1054 1
4. Future directions
d1057 4
a1060 1
The large object and direct access functions need much more attention.
a1061 2
I want to add a DB-SIG API wrapper around the underlying module.  This
will be in 3.0.
@


1.4
log
@Re-add python.
@
text
@d2 1
a2 1
PyGreSQL - v2.3: PostgreSQL module for Python
d8 1
a8 1
  PyGreSQL, version 2.3
d132 3
a134 3
  - Python:     ftp://ftp.python.org:/pub/python
  - PosgreSQL:  ftp://ftp.PostgreSQL.org/pub/postgresql-6.4.tar.gz
  - PyGreSQL:   ftp://ftp.druid.net/pub/distrib/pygresql-2.2.tgz
d137 2
a138 1

d168 4
d479 10
d865 1
a865 19
   an exception if the table doesn't have a primary key.  Further, in the
   currently released implementation of PostgreSQL the 'PRIMARY KEY' syntax
   doesn't actually fill in the necessary tables to determine primary keys.
   You can do this yourself with the following query.

	# Set up table and primary_field variables...

     """UPDATE pg_index SET indisprimary = 't'
                            WHERE pg_index.oid in (SELECT pg_index.oid
       FROM pg_class, pg_attribute, pg_index
       WHERE pg_class.oid = pg_attribute.attrelid AND
           pg_class.oid = pg_index.indrelid AND
           pg_index.indkey[0] = pg_attribute.attnum AND
           pg_class.relname = '%(table)s' AND
           pg_attribute.attname = '%(primary_field)');""" % locals()

   This will be fixed in the upcoming 6.5 release of PostgreSQL or
   you can download the current sources now.  Downloading current
   is, as usual, at your own risk.
@


1.3
log
@Update to PyGreSQL 2.3.
@
text
@d2 1
a2 1
PyGreSQL - v2.2: PostgreSQL module for Python
d8 1
a8 1
  PyGreSQL, version 2.2
d31 2
a32 2
  Further modifications copyright 1997 by D'Arcy J.M. Cain (darcy@@druid.net)
  subject to the same terms and conditions as above.
a69 4
  pgext.py     - PyGreSQL library
                 This file should go in your Python library directory.  It
                 contains some interesting functions for pg use.   All pg
                 function are imported in this file.
d89 1
a89 1
  copy the 'pgmodule.c' file there.
d97 8
a104 4
    -DNO_DEF_VAR - no default variables support
    -DNO_DIRECT  - no direct access methods
    -DNO_LARGE   - no large object support
  These options will be described in the next sections.
d107 3
a109 2
  uncommented and add the above line below it.  You then need to install
  your shared modules with "make sharedinstall."
d118 6
d175 1
a175 1
connections parameters without heavy code in your programs. You can prompt the
d177 3
a179 3
having to modify environment. The support for default variables can be disabled
by setting the -DNO_DEF_VAR option in the Python Setup file. Methods relative 
to this are specified by te tag [DV].
d337 1
a337 1
    This methods sets the default database name value for new connections. If 
d354 6
d428 1
a428 1
    2.2.3. listfields - lists the fields names of the previous query result
d442 1
a442 1
    2.2.4. fieldname, fieldnum - field name-number conversion
d474 41
d530 2
a531 1
    the notify.
d851 5
a855 4
   current implementation of PostgreSQL the 'PRIMARY KEY' syntax doesn't
   actually fill in the necessary tables to determine primary keys.  You
   can do this yourself with the following query.  Replace $0 with the
   table name and $1 with the attribute that is the primary key.
d857 1
a857 1
     UPDATE pg_index SET indisprimary = 't'
d863 15
a877 2
           pg_class.relname = '$0' AND
           pg_attribute.attname = '$1');
d879 7
a885 1
 3.3. get_attnames
d896 2
a897 2
 3.4. get
 --------
d918 2
a919 2
 3.5. insert
 -----------
d929 3
a931 1
   values from the dictionary.
d934 1
a934 1
 3.6. update
d949 1
a949 1
 3.7. clear
a977 19
 3.9. Convenience methods
 ------------------------
 In order to allow all access to a connection to be done through the DB
 class, the following methods wrap the basic functions.

   query
   reset
   getnotify
   inserttable

 The following depend on being activated in the underlying C code

   putline
   getline
   endcopy
   locreate
   getlo
   loimport

d984 2
a985 1
I want to add a DB-SIG API wrapper around the underlying module.
@


1.2
log
@Upgrade to Pygress 2.2.
@
text
@@


1.1
log
@Merge in D'Arcy Cain's python interface (PyGreSQL 2.0)
@
text
@d2 1
a2 1
PyGreSQL - v2.0: PostgreSQL module for Python
d8 1
a8 1
  PyGreSQL, version 2.0
d45 2
a46 2
Python is a interpretated programming langage. It is object oriented, simple
to use (light syntax, simple and straighforward statements), and has many
d48 1
a48 1
browser (HotJava like) is currently under development (november 1995), and
d74 1
d80 1
a80 1
                 add-in used for demonstation.
d85 1
a85 15
You first have to get and build Python and PostgreSQL.  You have to copy the
pgmodule.c file to the Python Modules directory and add the following line to
the Setup file there.
    pg  pgmodule.c -I[pg inc] -L[pg lib] -lpq
or, for a dynamic module:
    pg  [pg mod]pgmodule.c ../Objects/access.c -I[pg inc] -L[pg lib] -lpd
where:
    pg mod       - directory where you did put the module files
    pg inc       - path of the PostgreSQL include 
    pg lib       - path of the PostgreSQL libraries 

Some options may be added to this line:
  -DNO_DEF_VAR - no default variables support
  -DNO_DIRECT  - no direct access methods
  -DNO_LARGE   - no large object support
d87 31
a117 1
These options will be described in the next sections.
d123 1
a123 1
The home sites of the differents packages are:
d126 5
a130 2
  - PosgreSQL:  ftp://ftp.PostgreSQL.org/pub/postgresql-6.2.1.tar.gz
  - PyGreSQL:   ftp://ftp.druid.net/pub/contrib/pygresql-2.0.tgz
d138 1
d149 1
a149 1
  - PyGreSQL:    contact me (darcy@@druid.net) concerning the changes to 2.0.
d174 1
a174 1
All variables are set to None at module initialisation, specifying that 
d181 1
a181 1
    connect(dbname, host, port, opt, tty)
d188 2
d195 1
a195 1
    pg.error      - some error occured during pg connection definition
d337 1
a337 1
  Some constants are defined in the module dictionnary. They are intended to be
d343 1
a343 1
  - positionnal flags, used by (pglarge.)seek: (pg.)SEEK_SET, 
d345 1
d350 1
a350 1
  This object handle a connection to a PostgreSQL database. It embends and 
d374 6
a379 4
    This method simply sends a SQL query to the database. If the command does
    not return a result (ie. is not a some kind of SELECT statement), it 
    returns None.  Otherwise, it returns a pgqueryobject that can be
    accessed via the getresult method or printed.
d395 1
a395 1
      This method returns the list of the values returned by the last query.
d397 17
a413 1
      fieldname and fiednum methods. All list elements are strings.
d473 1
a473 1
    NOTIFY). If the server returns no notify, the methods retuns None. 
d606 1
a606 1
embends and hides all the 'recurrent' variables (object oid and connection), 
d681 1
a681 1
    whence          - positionnal parameter
d709 1
a709 1
    pg.error        - invalid connection or incaid object
d762 166
@


1.1.2.1
log
@Upgrade to Pygress 2.2.
@
text
@d2 1
a2 1
PyGreSQL - v2.2: PostgreSQL module for Python
d8 1
a8 1
  PyGreSQL, version 2.2
d45 2
a46 2
Python is an interpreted programming language. It is object oriented, simple
to use (light syntax, simple and straightforward statements), and has many
d48 1
a48 1
browser (HotJava like) is currently under development (November 1995), and
a73 1
  pg.py        - PyGreSQL DB class.
d79 1
a79 1
                 add-in used for demonstration.
d84 15
a98 1
* You first have to get and build Python and PostgreSQL.
d100 1
a100 31
* PyGreSQL is implemented as two parts, a C module labeled _pg and a
  Python wrapper called pg.py.  This changed between 2.1 and 2.2.  This
  should not affect any existing programs but the installation is slightly
  different.

* Find the directory where your 'Setup' file lives (usually ??/Modules) and
  copy the 'pgmodule.c' file there.

* Add the following line to your Setup file
    _pg  pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems
  where:
    [pgInc] = path of the PostgreSQL include 
    [pgLib] = path of the PostgreSQL libraries 
  Some options may be added to this line:
    -DNO_DEF_VAR - no default variables support
    -DNO_DIRECT  - no direct access methods
    -DNO_LARGE   - no large object support
  These options will be described in the next sections.

* If you want a shared module, make sure that the "*shared*" keyword is
  uncommented and add the above line below it.  You then need to install
  your shared modules with "make sharedinstall."

* Copy pg.py to the lib directory where the rest of your modules are.  For
  example, that's /usr/local/lib/Python on my system.

* Do 'make -f Makefile.pre.in boot' and do 'make && make install'

* For more details read the documentation at the top of Makefile.pre.in

* For Linux installation look at README.linux
d106 1
a106 1
The home sites of the different packages are:
d109 2
a110 5
  - PosgreSQL:  ftp://ftp.PostgreSQL.org/pub/postgresql-6.4.tar.gz
  - PyGreSQL:   ftp://ftp.druid.net/pub/distrib/pygresql-2.2.tgz

A Linux RPM can be picked up from ftp://www.eevolute.com/pub/python/.

a117 1
  - PostgreSQL: http://www.postgresql.org/
d128 1
a128 1
  - PyGreSQL:    contact me (darcy@@druid.net) concerning the changes to 2.x.
d153 1
a153 1
All variables are set to None at module initialization, specifying that 
d160 1
a160 1
    connect(dbname, host, port, opt, tty, user, passwd)
a166 2
	user          - PostgreSQL user (string/None)
    passwd        - password for user (string/None)
d172 1
a172 1
    pg.error      - some error occurred during pg connection definition
d314 1
a314 1
  Some constants are defined in the module dictionary. They are intended to be
d320 1
a320 1
  - positional flags, used by (pglarge.)seek: (pg.)SEEK_SET, 
a321 1
  - version and __version__ constants that give the current version.
d326 1
a326 1
  This object handle a connection to a PostgreSQL database. It embeds and 
d350 4
a353 6
    This method simply sends a SQL query to the database. If the query is
    an insert statement, the return value is the OID of the newly
    inserted row.  If it is otherwise a query that does not return a result
    (ie. is not a some kind of SELECT statement), it returns None.
    Otherwise, it returns a pgqueryobject that can be accessed via the
    getresult method or printed.
d369 1
a369 1
      This method returns the list of the values returned by the query.
d371 1
a371 17
      fieldname and fiednum methods.

    2.2.1.2. dictresult - like getresult but returns list of dictionaries
    ---------------------------------------------------------------------

    Syntax: dictresult()
    Parameters: none
    Return type:
      list          - result values as a dictionary
    Exceptions raised:
      SyntaxError   - too many parameters
      pg.error      - invalid previous result
    Description:
      This method returns the list of the values returned by the query
      with each tuple returned as a dictionary with the field names
      used as the dictionary index.

d431 1
a431 1
    NOTIFY). If the server returns no notify, the methods returns None. 
d564 1
a564 1
embeds and hides all the 'recurrent' variables (object oid and connection), 
d639 1
a639 1
    whence          - positional parameter
d667 1
a667 1
    pg.error        - invalid connection or invalid object
a719 166


3. The pg wrapper
================

The previous functions are wrapped in a module called pg.  The module
has a class called DB.  The above functions are also included in the
name space so it isn't necessary to import both modules.  The preferred
way to use this module is as follows.

from pg import DB
db = DB(...) # See description of the initialization method below.

The following describes the methods and variables of this class.


 3.1. Initialization
 -------------------
 The DB class is initialized with the same arguments as the connect
 method described in section 2.  It also initializes a few internal
 variables.  The statement 'db = DB()' will open the local database
 with the name of the user just like connect() does.

 3.2. pkey
 ---------
 Syntax:
   pkey(table)
 Parameters:
   table - name of table
 Returns:
   Name of field which is the primary key of the table.
 Description:
   This method returns the primary key of a table.  Note that this raises
   an exception if the table doesn't have a primary key.  Further, in the
   current implementation of PostgreSQL the 'PRIMARY KEY' syntax doesn't
   actually fill in the necessary tables to determine primary keys.  You
   can do this yourself with the following query.  Replace $0 with the
   table name and $1 with the attribute that is the primary key.

     UPDATE pg_index SET indisprimary = 't'
                            WHERE pg_index.oid in (SELECT pg_index.oid
       FROM pg_class, pg_attribute, pg_index
       WHERE pg_class.oid = pg_attribute.attrelid AND
           pg_class.oid = pg_index.indrelid AND
           pg_index.indkey[0] = pg_attribute.attnum AND
           pg_class.relname = '$0' AND
           pg_attribute.attname = '$1');

 3.3. get_attnames
 -----------------
 Syntax: 
   get_attnames(table)       
 Parameters: 
   table - name of table
 Returns:
   List of attribute names
 Description:
   Given the name of a table, digs out the list of attribute names.

 3.4. get
 --------
 Syntax: 
   get(table, arg, [keyname])
 Parameters:
   table - name of table
   arg - either a dictionary or the value to be looked up
   keyname - name of field to use as key (optional)
 Returns:
   A dictionary mapping attribute names to row values.
 Description:
   This method is the basic mechanism to get a single row.  It assumes
   that the key specifies a unique row.  If keyname is not specified
   then the primary key for the table is used.  If arg is a dictionary
   then the value for the key is taken from it and it is modified to
   include the new values, replacing existing values where necessary.
   The oid is also put into the dictionary but in order to allow the
   caller to work with multiple tables, the attribute name is munged
   to make it unique.  It consists of the string "oid_" followed by
   the name of the table.


 3.5. insert
 -----------
 Syntax:
   insert(table, a)
 Parameters:
   table - name of table
   a - a dictionary of values
 Returns:
   The OID of the newly inserted row.
 Description:
   This method inserts values into the table specified filling in the
   values from the dictionary.


 3.6. update
 -----------
 Syntax:
   update(table, a)             
 Parameters:
   table - name of table
   a - a dictionary of values
 Returns:
   A dictionary with the new row
 Description:
   Similar to insert but updates an existing row.  The update is based
   on the OID value as munged by get.  The array returned is the
   one sent modified to reflect any changes caused by the update due
   to triggers, rules, defaults, etc.

 3.7. clear
 ----------
 Syntax:
   clear(table, [a])
 Parameters:
   table - name of table
   a - a dictionary of values
 Returns:
   A dictionary with an empty row
 Description:
   This method clears all the attributes to values determined by the types.
   Numeric types are set to 0, dates are set to 'TODAY' and everything
   else is set to the empty string.  If the array argument is present,
   it is used as the array and any entries matching attribute names
   are cleared with everything else left unchanged.

 3.8. delete
 -----------
 Syntax:
   delete(table, a)
 Parameters:
   table - name of table
   a - a dictionary of values
 Returns:
   None
 Description:
   This method deletes the row from a table.  It deletes based on the OID
   as munged as described above.

 3.9. Convenience methods
 ------------------------
 In order to allow all access to a connection to be done through the DB
 class, the following methods wrap the basic functions.

   query
   reset
   getnotify
   inserttable

 The following depend on being activated in the underlying C code

   putline
   getline
   endcopy
   locreate
   getlo
   loimport


4. Future directions
====================

The large object and direct access functions need much more attention.

I want to add a DB-SIG API wrapper around the underlying module.

@
