From 0d3be98ae9524e78d51d259f4fae00850e987e9d Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Mon, 23 Sep 2002 21:10:13 +0000 Subject: [PATCH] Move PyGreSQL usage documentation from README into DocBook. Some other editing. --- doc/src/sgml/pygresql.sgml | 812 +++++++++++++-------------- src/interfaces/python/README | 846 +---------------------------- src/interfaces/python/README.linux | 46 -- 3 files changed, 394 insertions(+), 1310 deletions(-) delete mode 100644 src/interfaces/python/README.linux diff --git a/doc/src/sgml/pygresql.sgml b/doc/src/sgml/pygresql.sgml index 540379029dc..e739e3d5e06 100644 --- a/doc/src/sgml/pygresql.sgml +++ b/doc/src/sgml/pygresql.sgml @@ -1,4 +1,4 @@ - + <application>PyGreSQL</application> - <application>Python</application> Interface @@ -20,34 +20,10 @@ Installation - - - 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. - If you're on an x86 system that uses - RPMs, then 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 mxDateTime from http://starship.python.net/~lemburg/mxDateTime.html. @@ -56,16 +32,15 @@ Also, check out setup.py for an alternate - method of installing the package using Python's Distutils. + method of installing the package using Python's Distutils. - You have two options. You can compile - PyGreSQL as a stand-alone module or you - can build it into the Python + PyGreSQL as a stand-alone module or you + can build it into the Python interpreter. @@ -75,27 +50,27 @@ - You must first have installed Python + You must first have installed Python and PostgreSQL on your system. The header files and developer's libraries for both - Python and + Python and PostgreSQL must be installed on your - system before you can build PyGreSQL. - If you built both Python and + 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 - RPM or NetBSD packages), + RPM or NetBSD packages), then you probably need to install packages such as - Python-devel in addition to the - Python package. + Python-devel in addition to the + Python package. - PyGreSQL is implemented as three - parts, a C module labeled _pg and two - Python wrappers called + 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 @@ -105,7 +80,7 @@ - Download and unpack the PyGreSQL + Download and unpack the PyGreSQL tarball if you haven't already done so. @@ -129,7 +104,7 @@ cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c - [pyInc] = path of the Python + [pyInc] = path of the Python include (usually Python.h) @@ -154,43 +129,43 @@ cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c - -DNO_DEF_VAR - no default variables + - no default variables support - -DNO_DIRECT - no direct access methods + - no direct access methods - -DNO_LARGE - no large object support + - no large object support - -DNO_SNPRINTF - if running a system with + - if running a system with no snprintf call - -DNO_PQSOCKET - if running an older + - if running an older PostgreSQL On some systems you may need to include - -lcrypt in the list of libraries to make it + in the list of libraries to make it compile. - Define DNO_PQSOCKET if you are using a + Define 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. @@ -219,10 +194,10 @@ cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c Finally, move the _pg.so, pg.py, and pgdb.py - to a directory in your PYTHONPATH. + to a directory in your PYTHONPATH. A good place would be /usr/lib/python1.5/site-python - if your Python modules are in + if your Python modules are in /usr/lib/python1.5. @@ -238,16 +213,16 @@ cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c Find the directory where your Setup file lives (usually ??/Modules) in - the Python source hierarchy and + the Python source hierarchy and copy or symlink the pgmodule.c file there. - Add the following line to your Setup file - + Add the following line to your Setup file + _pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems - + where: @@ -268,35 +243,35 @@ _pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems - -DNO_DEF_VAR - no default variables + - no default variables support - -DNO_DIRECT - no direct access methods + - no direct access methods - -DNO_LARGE - no large object support + - no large object support - -DNO_SNPRINTF - if running a system with + - if running a system with no snprintf call - -DNO_PQSOCKET - if running an older + - if running an older PostgreSQL - Define DNO_PQSOCKET if you are using a version of + Define 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. @@ -305,7 +280,7 @@ _pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems If you want a shared module, make sure that the - *shared* keyword is uncommented and + *shared* key word 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. @@ -320,13 +295,13 @@ _pg pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems - Rebuild Python from the root - directory of the Python source + Rebuild Python from the root + directory of the Python source hierarchy by running - + make -f Makefile.pre.in boot make && make install - + @@ -342,35 +317,35 @@ make && make install ]]> + + You may either choose to use the old mature interface provided by + the pg module or otherwise the newer + pgdb interface compliant with the DB-API 2.0 specification developed by + the Python DB-SIG. + + + + Here we 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 http://www2.linuxjournal.com/lj-issues/issue49/2605.html + + The <literal>pg</literal> Module - - You may either choose to use the old mature interface provided by - the pg module or otherwise the newer - pgdb interface compliant with the DB-API 2.0 specification developed by - the Python DB-SIG. - - - - Here we 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 http://www2.linuxjournal.com/lj-issues/issue49/2605.html - - The pg module defines three objects: @@ -390,7 +365,7 @@ make && make install - pgqueryobject that handles query results. + pgqueryobject that handles query results. @@ -399,8 +374,8 @@ make && make install 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 + >http://www.druid.net/rides where you can find a link at the + bottom to the actual Python code for the page. @@ -410,7 +385,7 @@ make && make install Some constants are defined in the pg module dictionary. They are intended to be used as a parameters for - methods calls. You should refer to the libpq + methods calls. You should refer to the libpq description () for more information about them. These constants are: @@ -470,7 +445,7 @@ make && make install default variable, and forget it, without having to modify your environment. The support for default variables can be disabled by setting the option in the Python - Setup file. Methods relative to this are specified by te tag [DV]. + Setup file. Methods relative to this are specified by the tag [DV]. @@ -487,12 +462,12 @@ make && make install connect - opens a connection to the database server + open a connection to the database server -connect(dbname, host, port, opt, tty, user, passwd) +connect(dbname, host, port, opt, tty, user, passwd) @@ -500,23 +475,23 @@ connect(dbname, - dbname + dbname - Name of connected database (string/None). + Name of connected database (string/None). - host + host - Name of the server host (string/None). + Name of the server host (string/None). - port + port Port used by the database server (integer/-1). @@ -524,41 +499,41 @@ connect(dbname, - opt + opt - Options for the server (string/None). + Options for the server (string/None). - tty + tty File or tty for optional debug output from backend - (string/None). + (string/None). - user + user - PostgreSQL user (string/None). + PostgreSQL user (string/None). - passwd + passwd - Password for user (string/None). + Password for user (string/None). @@ -569,7 +544,7 @@ connect(dbname, - pgobject + pgobject @@ -585,7 +560,7 @@ connect(dbname, - TypeError + TypeError @@ -595,7 +570,7 @@ connect(dbname, - SyntaxError + SyntaxError @@ -605,18 +580,18 @@ connect(dbname, - pg.error + pg.error - Some error occurred during pg connection definition. + Some error occurred during pg connection definition. - (+ all exceptions relative to object allocation) + (plus all exceptions relative to object allocation) @@ -627,9 +602,9 @@ connect(dbname, 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 + key words here, as described in the + Python tutorial. The names of the + key words 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. @@ -680,7 +655,7 @@ get_defhost() - string or None + string or None @@ -696,7 +671,7 @@ get_defhost() - SyntaxError + SyntaxError @@ -714,7 +689,7 @@ get_defhost() get_defhost() returns the current default - host specification, or None if the environment variables should + host specification, or None if the environment variables should be used. Environment variables will not be looked up. @@ -723,77 +698,78 @@ get_defhost() - - set_defhost - PYGRESQL - Connection Management - - - set_defhost - set default host name [DV] - + + set_defhost + PYGRESQL - Connection Management + - + + set_defhost + set default host name [DV] + + + -set_defhost(host) +set_defhost(host) - - Parameters - - - - host - - - New default host (string/None). - - - - + + Parameters + + + + host + + + New default host (string/None). + + + + - - Return Type - - - - string or None - - - - Previous default host specification. - - - - - + + Return Type + + + + string or None + + + + Previous default host specification. + + + + + - - Exceptions - - - - TypeError - - - - Bad argument type, or too many arguments. - - - - - + + Exceptions + + + + TypeError + + + + Bad argument type, or too many arguments. + + + + + - + - - Description - - set_defhost() 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. - - + + Description + + set_defhost() 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. + + @@ -826,7 +802,7 @@ get_defport() - integer or None + integer or None @@ -842,7 +818,7 @@ get_defport() - SyntaxError + SyntaxError @@ -859,7 +835,7 @@ get_defport() Description get_defport() returns the current default - port specification, or None if the environment variables should + port specification, or None if the environment variables should be used. Environment variables will not be looked up. @@ -880,7 +856,7 @@ get_defport() -set_defport(port) +set_defport(port) @@ -888,7 +864,7 @@ set_defport(port) - port + port New default host (integer/-1). @@ -902,7 +878,7 @@ set_defport(port) - integer or None + integer or None @@ -918,7 +894,7 @@ set_defport(port) - TypeError + TypeError @@ -972,7 +948,7 @@ get_defopt() - string or None + string or None @@ -988,7 +964,7 @@ get_defopt() - SyntaxError + SyntaxError @@ -1005,7 +981,7 @@ get_defopt() Description get_defopt() returns the current default - connection options specification, or None if the environment variables should + connection options specification, or None if the environment variables should be used. Environment variables will not be looked up. @@ -1021,12 +997,12 @@ get_defopt() set_defopt - set options specification [DV] + set default options specification [DV] -set_defopt(options) +set_defopt(options) @@ -1034,10 +1010,10 @@ set_defopt(options) - options + options - New default connection options (string/None). + New default connection options (string/None). @@ -1048,7 +1024,7 @@ set_defopt(options) - string or None + string or None @@ -1064,7 +1040,7 @@ set_defopt(options) - TypeError + TypeError @@ -1081,7 +1057,7 @@ set_defopt(options) Description set_defopt() sets the default connection options value - for new connections. If None is supplied as parameter, environment + 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. @@ -1118,7 +1094,7 @@ get_deftty() - string or None + string or None @@ -1134,7 +1110,7 @@ get_deftty() - SyntaxError + SyntaxError @@ -1151,7 +1127,7 @@ get_deftty() Description get_deftty() returns the current default - debug terminal specification, or None if the environment variables should + debug terminal specification, or None if the environment variables should be used. Environment variables will not be looked up. @@ -1167,12 +1143,12 @@ get_deftty() set_deftty - set default debug terminal specification [DV] + set default connection debug terminal specification [DV] -set_deftty(terminal) +set_deftty(terminal) @@ -1180,10 +1156,10 @@ set_deftty(terminal) - terminal + terminal - New default debug terminal (string/None). + New default debug terminal (string/None). @@ -1194,7 +1170,7 @@ set_deftty(terminal) - string or None + string or None @@ -1210,7 +1186,7 @@ set_deftty(terminal) - TypeError + TypeError @@ -1227,7 +1203,7 @@ set_deftty(terminal) Description set_deftty() sets the default terminal value - for new connections. If None is supplied as parameter, environment + 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. @@ -1264,7 +1240,7 @@ get_defbase() - string or None + string or None @@ -1280,7 +1256,7 @@ get_defbase() - SyntaxError + SyntaxError @@ -1297,7 +1273,7 @@ get_defbase() Description get_defbase() returns the current default - database name specification, or None if the environment variables should + database name specification, or None if the environment variables should be used. Environment variables will not be looked up. @@ -1318,7 +1294,7 @@ get_defbase() -set_defbase(database) +set_defbase(database) @@ -1326,10 +1302,10 @@ set_defbase(database) - database + database - New default database name (string/None). + New default database name (string/None). @@ -1340,7 +1316,7 @@ set_defbase(database) - string or None + string or None @@ -1356,7 +1332,7 @@ set_defbase(database) - TypeError + TypeError @@ -1373,7 +1349,7 @@ set_defbase(database) Description set_defbase() sets the default database name - for new connections. If None is supplied as parameter, environment + for new connections. If None is supplied as parameter, environment variables will be used in future connections. It returns the previous setting for default database name. @@ -1385,7 +1361,7 @@ set_defbase(database) - Connection object: <classname>pgobject</classname> + Connection Object: <classname>pgobject</classname> This object handles a connection to the @@ -1398,20 +1374,20 @@ set_defbase(database) 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. + them, set the option in the + Python Setup file. Some other methods give access to large objects. if you want to forbid access to these from the module, set the - -DNO_LARGE option in the - Python Setup file. + option in the + Python Setup file. These methods are specified by the tag [LO]. - Every pgobject defines a set of read-only + Every pgobject defines a set of read-only attributes that describe the connection and its status. These attributes are: @@ -1474,7 +1450,7 @@ set_defbase(database) status - the status of the connection (integer: 1 - OK, 0 - BAD) + the status of the connection (integer: 1 - OK, 0 - bad) @@ -1498,12 +1474,12 @@ set_defbase(database) query - executes a SQL command + execute a SQL command -query(command) +query(command) @@ -1511,7 +1487,7 @@ query(command) - command + command SQL command (string). @@ -1525,7 +1501,7 @@ query(command) - pgqueryobject or None + pgqueryobject or None @@ -1541,7 +1517,7 @@ query(command) - TypeError + TypeError @@ -1551,7 +1527,7 @@ query(command) - ValueError + ValueError @@ -1561,7 +1537,7 @@ query(command) - pg.error + pg.error @@ -1581,8 +1557,8 @@ query(command) 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 - (i.e., is not a some kind of SELECT statement), it returns None. - Otherwise, it returns a pgqueryobject that can be accessed via the + (i.e., 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() methods or simply printed. @@ -1599,7 +1575,7 @@ query(command) reset - resets the connection + reset the connection @@ -1626,7 +1602,7 @@ reset() - TypeError + TypeError @@ -1684,7 +1660,7 @@ close() - TypeError + TypeError @@ -1718,7 +1694,7 @@ close() fileno - returns the socket used to connect to the database + return the socket used to connect to the database @@ -1754,7 +1730,7 @@ fileno() - TypeError + TypeError @@ -1786,7 +1762,7 @@ fileno() getnotify - gets the last notify from the server + get the last notify from the server @@ -1806,7 +1782,7 @@ getnotify() - tuple, None + tuple, None @@ -1822,7 +1798,7 @@ getnotify() - TypeError + TypeError @@ -1832,7 +1808,7 @@ getnotify() - pg.error + pg.error @@ -1849,12 +1825,12 @@ getnotify() Description getnotify() method tries to get a notify from - the server (from the SQL statement NOTIFY). - If the server returns no notify, the methods returns None. + 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. + Remember to do a listen query first otherwise getnotify will always return None. @@ -1869,12 +1845,12 @@ getnotify() inserttable - inserts a list into a table + insert a list into a table -inserttable(table, values) +inserttable(table, values) @@ -1882,7 +1858,7 @@ inserttable(table, values) - table + table The table name (string). @@ -1890,7 +1866,7 @@ inserttable(table, values) - values + values The list of rows values to insert (list). @@ -1911,7 +1887,7 @@ inserttable(table, values) - TypeError + TypeError @@ -1921,7 +1897,7 @@ inserttable(table, values) - pg.error + pg.error @@ -1943,7 +1919,7 @@ inserttable(table, values) 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 - does not typecheck the fields according to the table + does not type-check the fields according to the table definition; it just look whether or not it knows how to handle such types. @@ -1960,12 +1936,12 @@ inserttable(table, values) putline - writes a line to the server socket [DA] + write a line to the server socket [DA] -putline(line) +putline(line) @@ -1973,7 +1949,7 @@ putline(line) - line + line Line to be written (string). @@ -1994,7 +1970,7 @@ putline(line) - TypeError + TypeError @@ -2004,7 +1980,7 @@ putline(line) - pg.error + pg.error @@ -2035,7 +2011,7 @@ putline(line) getline - gets a line from server socket [DA] + get a line from server socket [DA] @@ -2071,7 +2047,7 @@ getline() - TypeError + TypeError @@ -2081,7 +2057,7 @@ getline() - pg.error + pg.error @@ -2112,7 +2088,7 @@ getline() endcopy - synchronizes client and server [DA] + synchronize client and server [DA] @@ -2139,7 +2115,7 @@ endcopy() - TypeError + TypeError @@ -2149,7 +2125,7 @@ endcopy() - pg.error + pg.error @@ -2181,12 +2157,12 @@ endcopy() locreate - creates of large object in the database [LO] + create a large object in the database [LO] -locreate(mode) +locreate(mode) @@ -2194,7 +2170,7 @@ locreate(mode) - mode + mode Large object create mode. @@ -2208,7 +2184,7 @@ locreate(mode) - pglarge + pglarge @@ -2224,7 +2200,7 @@ locreate(mode) - TypeError + TypeError @@ -2234,7 +2210,7 @@ locreate(mode) - pg.error + pg.error @@ -2252,7 +2228,7 @@ locreate(mode) locreate() 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 and INV_WRITE). + (INV_READ and INV_WRITE). @@ -2267,12 +2243,12 @@ locreate(mode) getlo - builds a large object from given oid [LO] + build a large object from given OID [LO] -getlo(oid) +getlo(oid) @@ -2280,10 +2256,10 @@ getlo(oid) - oid + oid - OID of the existing large object (integer). + OID of the existing large object (integer). @@ -2294,7 +2270,7 @@ getlo(oid) - pglarge + pglarge @@ -2310,7 +2286,7 @@ getlo(oid) - TypeError + TypeError @@ -2320,7 +2296,7 @@ getlo(oid) - pg.error + pg.error @@ -2338,7 +2314,7 @@ getlo(oid) getlo() method allows to reuse a formerly created large object through the pglarge interface, providing - the user have its oid. + the user has its OID. @@ -2353,12 +2329,12 @@ getlo(oid) loimport - imports a file to a PostgreSQL large object [LO] + import a file to a PostgreSQL large object [LO] -loimport(filename) +loimport(filename) @@ -2366,7 +2342,7 @@ loimport(filename) - filename + filename The name of the file to be imported (string). @@ -2380,7 +2356,7 @@ loimport(filename) - pglarge + pglarge @@ -2396,7 +2372,7 @@ loimport(filename) - TypeError + TypeError @@ -2406,7 +2382,7 @@ loimport(filename) - pg.error + pg.error @@ -2434,7 +2410,7 @@ loimport(filename) - Database wrapper class: <classname>DB</classname> + Database Wrapper Class: <classname>DB</classname> pg module contains a class called @@ -2476,12 +2452,12 @@ for r in db.query( pkey - returns the primary key of a table + return the primary key of a table -pkey(table) +pkey(table) @@ -2489,7 +2465,7 @@ pkey(table) - table + table @@ -2642,12 +2618,12 @@ get_tables() get_attnames - returns the attribute names of a table + return the attribute names of a table -get_attnames(table) +get_attnames(table) @@ -2655,7 +2631,7 @@ get_attnames(table) - table + table @@ -2710,7 +2686,7 @@ get_attnames(table) -get(table, arg, keyname) +get(table, arg, keyname) @@ -2718,7 +2694,7 @@ get(table, arg, - table + table @@ -2728,7 +2704,7 @@ get(table, arg, - arg + arg @@ -2738,7 +2714,7 @@ get(table, arg, - keyname + keyname @@ -2771,11 +2747,11 @@ get(table, arg, 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 + 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 + 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. @@ -2798,7 +2774,7 @@ get(table, arg, -insert(table, a) +insert(table, a) @@ -2806,7 +2782,7 @@ insert(table, a) - table + table @@ -2816,7 +2792,7 @@ insert(table, a) - a + a @@ -2853,6 +2829,13 @@ insert(table, a) 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. + @@ -2871,7 +2854,7 @@ insert(table, a) -update(table, a) +update(table, a) @@ -2879,7 +2862,7 @@ update(table, a) - table + table @@ -2889,7 +2872,7 @@ update(table, a) - a + a @@ -2944,7 +2927,7 @@ update(table, a) -clear(table, a) +clear(table, a) @@ -2952,7 +2935,7 @@ clear(table, a - table + table @@ -2962,7 +2945,7 @@ clear(table, a - a + a @@ -3013,12 +2996,12 @@ clear(table, a delete - deletes the row from a table + delete a row from a table -delete(table, a) +delete(table, a) @@ -3026,7 +3009,7 @@ delete(table, a< - table + table @@ -3036,7 +3019,7 @@ delete(table, a< - a + a @@ -3074,7 +3057,7 @@ delete(table, a< - Query result object: <literal>pgqueryobject</literal> + Query Result Object: <classname>pgqueryobject</classname> @@ -3085,7 +3068,7 @@ delete(table, a< getresult - gets the values returned by the query + get the values returned by the query @@ -3121,7 +3104,7 @@ getresult() - SyntaxError + SyntaxError @@ -3131,7 +3114,7 @@ getresult() - pg.error + pg.error @@ -3164,7 +3147,7 @@ getresult() dictresult - like getresult but returns a list of dictionaries + get the values returned by the query as a list of dictionaries @@ -3200,7 +3183,7 @@ dictresult() - SyntaxError + SyntaxError @@ -3210,7 +3193,7 @@ dictresult() - pg.error + pg.error @@ -3243,7 +3226,7 @@ dictresult() listfields - lists the fields names of the query result + list the fields names of the query result @@ -3279,7 +3262,7 @@ listfields() - SyntaxError + SyntaxError @@ -3289,7 +3272,7 @@ listfields() - pg.error + pg.error @@ -3321,12 +3304,12 @@ listfields() fieldname - field number-name conversion + get field name by number -fieldname(i) +fieldname(i) @@ -3334,7 +3317,7 @@ fieldname(i) - i + i @@ -3366,7 +3349,7 @@ fieldname(i) - TypeError + TypeError @@ -3376,7 +3359,7 @@ fieldname(i) - ValueError + ValueError @@ -3386,7 +3369,7 @@ fieldname(i) - pg.error + pg.error @@ -3419,12 +3402,12 @@ fieldname(i) fieldnum - field name-number conversion + get field number by name -fieldnum(name) +fieldnum(name) @@ -3432,7 +3415,7 @@ fieldnum(name) - name + name @@ -3464,7 +3447,7 @@ fieldnum(name) - TypeError + TypeError @@ -3474,7 +3457,7 @@ fieldnum(name) - ValueError + ValueError @@ -3484,7 +3467,7 @@ fieldnum(name) - pg.error + pg.error @@ -3518,7 +3501,7 @@ fieldnum(name) ntuples - returns the number of tuples in query object + return the number of tuples in query object @@ -3554,7 +3537,7 @@ ntuples() - SyntaxError + SyntaxError @@ -3585,7 +3568,7 @@ ntuples() This object handles all the request concerning a PostgreSQL large object. It embeds and - hides all the recurrent variables (object oid 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 @@ -3608,16 +3591,16 @@ ntuples() - oid + oid - the oid associated with the object + the OID associated with the object - pgcnx + pgcnx the pgobject associated with the object @@ -3626,7 +3609,7 @@ ntuples() - error + error the last warning/error message of the connection @@ -3635,20 +3618,19 @@ ntuples() - - 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 + pgobject. Remember that these object are + shared, not duplicated; you should provide some locking if you + want to check for the error message in this situation. The OID + attribute is very interesting because it allow you to reuse the + OID later, creating the pglarge object + with a pgobject getlo() method call. - + @@ -3665,12 +3647,12 @@ ntuples() open - opens a large object + open a large object -open(mode) +open(mode) @@ -3678,7 +3660,7 @@ open(mode) - mode + mode @@ -3701,7 +3683,7 @@ open(mode) - TypeError + TypeError @@ -3711,7 +3693,7 @@ open(mode) - IOError + IOError @@ -3721,7 +3703,7 @@ open(mode) - pg.error + pg.error @@ -3738,9 +3720,9 @@ open(mode) Description open() method opens a large object for reading/writing, - in the same way than the UNIX open() + in the same way than the Unix open() function. The mode value can be obtained by OR-ing the constants defined in - the pg module (INV_READ, INV_WRITE). + the pg module (INV_READ, INV_WRITE). @@ -3755,7 +3737,7 @@ open(mode) close - closes the large object + close the large object @@ -3782,7 +3764,7 @@ close() - SyntaxError + SyntaxError @@ -3792,7 +3774,7 @@ close() - IOError + IOError @@ -3802,7 +3784,7 @@ close() - pg.error + pg.error @@ -3819,7 +3801,7 @@ close() Description close() method closes previously opened large object, - in the same way than the UNIX close() function. + in the same way than the Unix close() function. @@ -3834,12 +3816,12 @@ close() read - reads from the large object + read from the large object -read(size) +read(size) @@ -3847,7 +3829,7 @@ read(size) - size + size @@ -3879,7 +3861,7 @@ read(size) - TypeError + TypeError @@ -3889,7 +3871,7 @@ read(size) - IOError + IOError @@ -3899,7 +3881,7 @@ read(size) - pg.error + pg.error @@ -3931,12 +3913,12 @@ read(size) write - writes to the large object + write to the large object -write(string) +write(string) @@ -3944,7 +3926,7 @@ write(string) - string + string @@ -3967,7 +3949,7 @@ write(string) - TypeError + TypeError @@ -3977,7 +3959,7 @@ write(string) - IOError + IOError @@ -3987,7 +3969,7 @@ write(string) - pg.error + pg.error @@ -4024,7 +4006,7 @@ write(string) -seek(offset, whence) +seek(offset, whence) @@ -4032,7 +4014,7 @@ seek(offset, whence) - offset + offset @@ -4042,7 +4024,7 @@ seek(offset, whence) - whence + whence @@ -4074,7 +4056,7 @@ seek(offset, whence) - TypeError + TypeError @@ -4084,7 +4066,7 @@ seek(offset, whence) - IOError + IOError @@ -4094,7 +4076,7 @@ seek(offset, whence) - pg.error + pg.error @@ -4112,7 +4094,7 @@ seek(offset, whence) seek() method allows to move the cursor position 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). + pg module (SEEK_SET, <>SEEK_CUR, <>SEEK_END). @@ -4127,7 +4109,7 @@ seek(offset, whence) tell - returns current position in the large object + return current position in the large object @@ -4163,7 +4145,7 @@ tell() - SyntaxError + SyntaxError @@ -4173,7 +4155,7 @@ tell() - IOError + IOError @@ -4183,7 +4165,7 @@ tell() - pg.error + pg.error @@ -4214,7 +4196,7 @@ tell() unlink - deletes the large object + delete the large object @@ -4241,7 +4223,7 @@ unlink() - SyntaxError + SyntaxError @@ -4251,7 +4233,7 @@ unlink() - IOError + IOError @@ -4261,7 +4243,7 @@ unlink() - pg.error + pg.error @@ -4292,7 +4274,7 @@ unlink() size - gives the large object size + return the large object size @@ -4328,7 +4310,7 @@ size() - SyntaxError + SyntaxError @@ -4338,7 +4320,7 @@ size() - IOError + IOError @@ -4348,7 +4330,7 @@ size() - pg.error + pg.error @@ -4366,8 +4348,8 @@ size() size() method allows to get the size of the large object. It was implemented because this function - is very useful for a WWW interfaced database. - Currently the large object needs to be opened. + is very useful for a WWW-interfaced database. + Currently, the large object needs to be opened first. @@ -4382,12 +4364,12 @@ size() export - saves the large object to file + save the large object to file -export(filename) +export(filename) @@ -4395,7 +4377,7 @@ export(filename) - filename + filename @@ -4418,7 +4400,7 @@ export(filename) - TypeError + TypeError @@ -4428,7 +4410,7 @@ export(filename) - IOError + IOError @@ -4438,7 +4420,7 @@ export(filename) - pg.error + pg.error @@ -4465,20 +4447,4 @@ export(filename) - - - <acronym>DB-API</acronym> Interface - - - This section needs to be written. - - - - See http://www.python.org/topics/database/DatabaseAPI-2.0.html - for a description of the DB-API 2.0. - - - diff --git a/src/interfaces/python/README b/src/interfaces/python/README index 17fbcd1111e..9471ff2e395 100644 --- a/src/interfaces/python/README +++ b/src/interfaces/python/README @@ -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. 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. The latest -version of PyGreSQL works with PostgreSQL 7.1.3 and Python 2.1. +style prototypes and changed the order of arguments to connect. 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 from http://starship.python.net/~lemburg/mxDateTime.html. -* For Linux installation look at README.linux. If you're on an x86 system - that uses RPMs, then you can pick up an RPM at +* 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 @@ -238,844 +236,10 @@ For support: 2. Programming information ========================== -You may either choose to use the old, mature interface provided by the -'pg' module or else the newer 'pgdb' interface compliant with DB-API 2.0 -specification developed by the Python DB-SIG. +See main PostgreSQL documentation. -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 -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 +3. Todo ======= 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. -6. Future directions +4. Future directions ==================== Users should be able to register their own types with _pg. diff --git a/src/interfaces/python/README.linux b/src/interfaces/python/README.linux deleted file mode 100644 index 66b0346c826..00000000000 --- a/src/interfaces/python/README.linux +++ /dev/null @@ -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 - - -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. -