postgres/src/interfaces/python/README

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.