readme

关系型数据库 Postgresql 6.5.2

PyGreSQL - v2.4: PostgreSQL module for Python
==============================================

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

  PyGreSQL, version 2.4
  A Python interface for PostgreSQL database.
  Written by D'Arcy J.M. Cain, [e-mail]<BR>
  Based heavily on code written by Pascal Andre, [e-mail].
  Copyright (c) 1995, Pascal ANDRE ([e-mail])

  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, 1998 and 1999 by D'Arcy J.M. Cain
  ([e-mail]) subject to the same terms and conditions as above.

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, [e-mail].
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.
  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
-----------------

* You first have to get and build Python and PostgreSQL.

* 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 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 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
    -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.

* 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

* 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


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://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.

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 ([e-mail]) for bug reports, ideas, remarks
                 I will try to answer as long as my free time allow me to do 
                 that.
  - PyGreSQL:    contact me ([e-mail]) concerning the changes to 2.x.


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

This 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