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.
