
PyGres - v0.9b : Postgres95 module for Python
=============================================

Author : Pascal ANDRE (andre@chimay.via.ecp.fr)

Introduction
------------

  Postgres95 is a database system derived from Postgres4.2. It conforms to ANSI
SQL and offer many interesting possibilities (C dynamic linking for functions
or type definition, time travel, ...). This package is copyrighted by the 
Regents of the University of California, but is freely distributable. For more
info, look to :
	http://epoch.cs.berkeley.edu:8000/postgres95/index.html
This module embends all the Postgres query C library (libpq) to allow accesing
a postgres database through Python.

Files
-----

  pg95module.c - the C python module
  pg95ext.py - PyGres95 library; should go to your Python library directory
    this file contains some 'useful' functions for pg95 use.
  basics.py, syscat.py, advanced.py and func.py - samples taken from the 
    Postgres manual (they were used for module testing); they demonstrate some
    PostGres SQL features.
  pgtools.py - tools for demo ('nice' select result display)

Installation
------------

  You first have to get and build Python and Postgres. You just have to add to 
your Setup file in the Modules directory of Python distribution :
  pg95  pg95module.c -I[pg includes] -L[pg lib path] -lpq
Some options may be added to this line:
  -DNO_DEF_VARS = no default variables support
  -DNO_DIRECT = no direct access to connection
  -DNO_LRGE = no large object support
This module can be dynamic.

Module description
------------------

  This module defines two objects: the pg95object that handles the connection 
and all the requests to the database, and the pg95largeobject that handles
all the accesses to Postgres large objects.

  Module methods
  --------------

  connect(dbname, dbhost, dbport, options, tty) : opens a connection to a 
    Postgres 95 server. This function returns a pg95object.

  default variables : the module offers an interface to set default variables
for connections (thus overiding the environment varaibles). This can be 
disabled by setting -DNO_DEF_VARS in your Setup line. The 'get' functions 
return the default setting if any or None; the 'set' functions return the 
previous variable value. The functions are:
    get_defhost(), set_defhost(string)
    get_defport(), set_defport(integer)
    get_defbase(), set_defbase(string)
    get_defopt(), set_defopt(string)
    get_deftty(), set_deftty(string)
    get_defuser(), set_defuser(string)
Please refer to Postgres manual for more information about these variables.

  Module constants (dictionnary)
  ------------------------------

  These constants are used for large objects. The first set defines the large
object access mode (for locreate or open) : INV_READ ,INV_WRITE, INV_ARCHIVE.
The second set is used for seeking a position in a large object: SEEK_SET, 
SEEK_CUR, SEEK_END.

  pg95object methods
  ------------------

  query(sql) : executes a SQL command string. If this command returns something
    the function returns it in a list.
  getresult() : returns the list associated to the last query result
  listfields() : returns the list of the fields in hte last query result
  fieldname(num) : returns the name of field #num
  fieldnum(name) : returns the num of the field name
  getnotify() : returns the last notify from the server if any or None
  inserttable(table, list) : inserts the content of the list to the table. The 
    list must contains all the fields of the table. 

  The following methods give a direct access to the server connection. This 
should be handled with care. If you want to disable it, add -DNO_DIRECT to your
Setup line.

  putline(line) : puts the line to the connection (stdin) of the server
  getline() : returns a line taken from the connection to the server
  endcopy() : synchronizes client and server after direct access

  These methods give access to pg95largeobjects. They all return an object of this 
type. This feature can be disabled by adding -DNO_LARGE to your Setup line.

  locreate(mode) : creates a large object in the base
  getlo(oid) : builds a large object using the given oid
  loimport(filename) : imports a large object from file

  pg95object attributes (read only)
  ---------------------------------

  They give information about the connection.

  host = hostname of the server
  port = port of the server
  db = selected database
  options = postgres options
  tty = debug terminal used
  user = username on the database system
  status = status of the connection (1 - OK, 0 - BAD)
  error = last warning/error message from the server

  pg95largeobject methods
  -----------------------

  open(mode) : opens a large object
  close() : closes the large object
  read(size) : read size bytes from large object and returns a sized string
  write(string) : write the string to the large object
  seek(offset, whence) : seeks a position in the large object. Returns the 
    final position in the large object
  tell() : returns the position in the large object
  export(filename) : exports the large object to the file
  unlink() : deletes the large object

  pg95largeobject attributes
  --------------------------

  oid : oid associated with the object. May be used for later access (cf getlo)
  pg95cnx : returns the pg95object associated with the pg95largeobject

______________________________________________________________________________
Please send your comments to:     andre@chimay.via.ecp.fr
