Move PyGreSQL usage documentation from README into DocBook. Some other
editing.
This commit is contained in:
parent
5fa3418304
commit
0d3be98ae9
File diff suppressed because it is too large
Load Diff
|
@ -63,8 +63,7 @@ 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.
|
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
|
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
|
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. The latest
|
style prototypes and changed the order of arguments to connect.
|
||||||
version of PyGreSQL works with PostgreSQL 7.1.3 and Python 2.1.
|
|
||||||
|
|
||||||
|
|
||||||
1.2. Distribution files
|
1.2. Distribution files
|
||||||
|
@ -92,8 +91,7 @@ version of PyGreSQL works with PostgreSQL 7.1.3 and Python 2.1.
|
||||||
you must already have built Python as well as the mxDateTime package
|
you must already have built Python as well as the mxDateTime package
|
||||||
from http://starship.python.net/~lemburg/mxDateTime.html.
|
from http://starship.python.net/~lemburg/mxDateTime.html.
|
||||||
|
|
||||||
* For Linux installation look at README.linux. If you're on an x86 system
|
* For a Linux x86 system that uses RPMs, you can pick up an RPM at
|
||||||
that uses RPMs, then you can pick up an RPM at
|
|
||||||
ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm
|
ftp://ftp.druid.net/pub/distrib/pygresql.i386.rpm
|
||||||
|
|
||||||
* Note that if you are using the DB-API module you must also install
|
* Note that if you are using the DB-API module you must also install
|
||||||
|
@ -238,844 +236,10 @@ For support:
|
||||||
2. Programming information
|
2. Programming information
|
||||||
==========================
|
==========================
|
||||||
|
|
||||||
You may either choose to use the old, mature interface provided by the
|
See main PostgreSQL documentation.
|
||||||
'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
|
3. Todo
|
||||||
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.
|
|
||||||
|
|
||||||
|
|
||||||
5. Todo
|
|
||||||
=======
|
=======
|
||||||
|
|
||||||
The large object and direct access functions need much more attention.
|
The large object and direct access functions need much more attention.
|
||||||
|
@ -1089,7 +253,7 @@ The DB-API module needs to be documented.
|
||||||
The fetch method should use real cursors.
|
The fetch method should use real cursors.
|
||||||
|
|
||||||
|
|
||||||
6. Future directions
|
4. Future directions
|
||||||
====================
|
====================
|
||||||
|
|
||||||
Users should be able to register their own types with _pg.
|
Users should be able to register their own types with _pg.
|
||||||
|
|
|
@ -1,46 +0,0 @@
|
||||||
Thanks to thilo@eevolute.com and others for this README and the RPM
|
|
||||||
|
|
||||||
Note: The precompiled RPM package is not available at www.eevolute.com.
|
|
||||||
You may use the spec file provided with PyGreSQL to build your
|
|
||||||
own package.
|
|
||||||
Hartmut Goebel <hartmut@goebel.noris.de>
|
|
||||||
|
|
||||||
|
|
||||||
INSTALLING PyGreSQL on Redhat Linux 5.1 or 5.2
|
|
||||||
==============================================
|
|
||||||
|
|
||||||
Things are pretty easy on Redhat Linux. You can either get a precompiled
|
|
||||||
RPM package from
|
|
||||||
|
|
||||||
ftp://www.eevolute.com/pub/python/
|
|
||||||
|
|
||||||
or try in compile and install it yourself:
|
|
||||||
|
|
||||||
bash$ make redhat # this just compiles the module as a shared object
|
|
||||||
cc -fpic -shared -o _pg.so -I/usr/include/python1.5 pgmodule.c -lpq
|
|
||||||
bash$ python # you can test it from your local directory
|
|
||||||
Python 1.5.1 (#1, May 6 1998, 01:48:27) [GCC 2.7.2.3] on linux-i386
|
|
||||||
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
|
|
||||||
>>> 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)
|
|
||||||
|
|
||||||
bash$ su # Yow! Seems to work - now install it properly
|
|
||||||
bash# cp _pg.so /usr/lib/python1.5/lib-dynload
|
|
||||||
|
|
||||||
done!
|
|
||||||
|
|
||||||
Oliver White (ojw@muzak.iinet.net.au) sent me the following information
|
|
||||||
about installing on Debian.
|
|
||||||
|
|
||||||
Hi, I thought you might want to upgrade your documentation for PyGreSQL
|
|
||||||
to let people know they can get it by simply typing 'apt-get install
|
|
||||||
python-pygresql', on debian (duh). This would have saved me a lot of
|
|
||||||
trouble.
|
|
||||||
|
|
Loading…
Reference in New Issue