http://git-wip-us.apache.org/repos/asf/incubator-hawq/blob/192cff1f/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pg.txt ---------------------------------------------------------------------- diff --git a/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pg.txt b/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pg.txt new file mode 100644 index 0000000..ce98629 --- /dev/null +++ b/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pg.txt @@ -0,0 +1,1382 @@ +================================ +PyGreSQL Programming Information +================================ + +------------------------------------------ +The classic PyGreSQL interface (pg module) +------------------------------------------ + +.. meta:: + :description: The classic PyGreSQL interface (pg module) + :keywords: PyGreSQL, pg, PostGreSQL, Python + +.. sectnum:: +.. contents:: Contents + + +Introduction +============ +You may either choose to use the +`"classic" PyGreSQL interface <pg.html>`_ +provided by the `pg` module or else the +`DB-API 2.0 compliant interface <pgdb.html>`_ +provided by the `pgdb` module. + +The following documentation covers only the older `pg` API. + +The `pg` module handles three types of objects, + +- the `pgobject`, which handles the connection + and all the requests to the database, +- the `pglarge` object, which handles + all the accesses to PostgreSQL large objects, +- the `pgqueryobject` that handles query results + +and it provides a convenient wrapper class `DB` for the `pgobject`. + +If you want to see a simple example of the use of some of these functions, +see http://ontario.bikerides.ca where you can find a link at the bottom to the +actual Python code for the page. + + +Module functions and constants +============================== +The `pg` module defines a few functions that allow to connect +to a database and 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 the tag [DV]. + +All variables are set to `None` at module initialization, specifying that +standard environment variables should be used. + +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: If successful, the `pgobject` handling the connection + +Exceptions raised: + :TypeError: bad argument type, or too many arguments + :SyntaxError: duplicate argument definition + :pg.InternalError: some error occurred during pg connection definition + + (plus all exceptions relative to object allocation) + +Description: + This function 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. + +Examples:: + + import pg + + con1 = pg.connect('testdb', 'myhost', 5432, None, None, 'bob', None) + con2 = pg.connect(dbname='testdb', host='localhost', user='bob') + +get_defhost, set_defhost - default server host [DV] +--------------------------------------------------- +Syntax:: + + get_defhost() + +Parameters: + None + +Return type: + :string, None: default host specification + +Exceptions raised: + :TypeError: 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. + +get_defport, set_defport - default server port [DV] +--------------------------------------------------- +Syntax:: + + get_defport() + +Parameters: + None + +Return type: + :integer, None: default port specification + +Exceptions raised: + :TypeError: 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. + +get_defopt, set_defopt - default connection options [DV] +-------------------------------------------------------- +Syntax:: + + get_defopt() + +Parameters: + None + +Return type: + :string, None: default options specification + +Exceptions raised: + :TypeError: 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. + +get_deftty, set_deftty - default debug tty [DV] +----------------------------------------------- +Syntax:: + + get_deftty() + +Parameters: + None + +Return type: + :string, None: default debug terminal specification + +Exceptions raised: + :TypeError: 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. + +get_defbase, set_defbase - default database name [DV] +----------------------------------------------------- +Syntax:: + + get_defbase() + +Parameters: + None + +Return type: + :string, None: default database name specification + +Exceptions raised: + :TypeError: 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. + +escape_string - escape a string for use within SQL +-------------------------------------------------- +Syntax:: + + escape_string(string) + +Parameters: + :string: the string that is to be escaped + +Return type: + :str: the escaped string + +Exceptions raised: + :TypeError: bad argument type, or too many arguments + +Description: + This function escapes a string for use within an SQL command. + This is useful when inserting data values as literal constants + in SQL commands. Certain characters (such as quotes and backslashes) + must be escaped to prevent them from being interpreted specially + by the SQL parser. `escape_string` performs this operation. + Note that there is also a `pgobject` method with the same name + which takes connection properties into account. + +.. caution:: It is especially important to do proper escaping when + handling strings that were received from an untrustworthy source. + Otherwise there is a security risk: you are vulnerable to "SQL injection" + attacks wherein unwanted SQL commands are fed to your database. + +Example:: + + name = raw_input("Name? ") + phone = con.query("select phone from employees" + " where name='%s'" % escape_string(name)).getresult() + +escape_bytea - escape binary data for use within SQL as type `bytea` +-------------------------------------------------------------------- +Syntax:: + + escape_bytea(datastring) + +Parameters: + :datastring: string containing the binary data that is to be escaped + +Return type: + :str: the escaped string + +Exceptions raised: + :TypeError: bad argument type, or too many arguments + +Description: + Escapes binary data for use within an SQL command with the type `bytea`. + As with `escape_string`, this is only used when inserting data directly + into an SQL command string. + Note that there is also a `pgobject` method with the same name + which takes connection properties into account. + +Example:: + + picture = file('garfield.gif', 'rb').read() + con.query("update pictures set img='%s' where name='Garfield'" + % escape_bytea(picture)) + +unescape_bytea -- unescape `bytea` data that has been retrieved as text +----------------------------------------------------------------------- +Syntax:: + + unescape_bytea(string) + +Parameters: + :datastring: the `bytea` data string that has been retrieved as text + +Return type: + :str: string containing the binary data + +Exceptions raised: + :TypeError: bad argument type, or too many arguments + +Description: + Converts an escaped string representation of binary data into binary + data - the reverse of `escape_bytea`. This is needed when retrieving + `bytea` data with the `getresult()` or `dictresult()` method. + +Example:: + + picture = unescape_bytea(con.query( + "select img from pictures where name='Garfield'").getresult[0][0]) + file('garfield.gif', 'wb').write(picture) + +set_decimal -- set a decimal type to be used for numeric values +--------------------------------------------------------------- +Syntax:: + + set_decimal(cls) + +Parameters: + :cls: the Python class to be used for PostgreSQL numeric values + +Description: + This function can be used to specify the Python class that shall be + used by PyGreSQL to hold PostgreSQL numeric values. The default class + is decimal.Decimal if available, otherwise the float type is used. + +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 the libpq description in the PostgreSQL user manual +for more information about them. These constants are: + +:version, __version__: constants that give the current version. +:INV_READ, INV_WRITE: large objects access modes, + used by `(pgobject.)locreate` and `(pglarge.)open` +:SEEK_SET, SEEK_CUR, SEEK_END: positional flags, + used by `(pglarge.)seek` + + +Connection objects: pgobject +============================ +This object handles 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. + +.. caution:: Some methods give direct access to the connection socket. + *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. + + **These methods are specified by the tag [DA].** + +.. note:: 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].** + +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 or lost connection + :pg.ProgrammingError: error in query + :pg.InternalError': error during query processing + +Description: + This method simply sends a SQL query to the database. If the query is an + insert statement that inserted exactly one row into a table that has OIDs, the + return value is the OID of the newly inserted row. If the query is an update + or delete statement, or an insert statement that did not insert exactly one + row in a table with OIDs, then the numer of rows affected is returned as a + string. If it is a statement that returns rows as a result (usually a select + statement, but maybe also an "insert/update ... returning" statement), this + method returns a `pgqueryobject` that can be accessed via the `getresult()` + or `dictresult()` method or simply printed. Otherwise, it returns `None`. + +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 connection. + +cancel - abandon processing of current SQL command +-------------------------------------------------- +Syntax:: + + cancel() + +Parameters: + None + +Return type: + None + +Exceptions raised: + :TypeError: too many (any) arguments + +Description: + This method requests that the server abandon processing + of the current SQL command. + +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. + +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. + +getnotify - gets the last notify from the server +------------------------------------------------ +Syntax:: + + getnotify() + +Parameters: + None + +Return type: + :tuple, None: last notify from server + +Exceptions raised: + :TypeError: too many parameters + :TypeError: 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`. + +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 + +Exceptions raised: + :TypeError: invalid connection, bad argument type, or too many arguments + :MemoryError: insert buffer could not be allocated + :ValueError: unsupported values + +Description: + This method allow to *quickly* insert large blocks of data in a table: + It inserts the whole values list into the given table. Internally, it + uses the COPY command of the PostgreSQL database. 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. + +.. caution:: *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. + +putline - writes a line to the server socket [DA] +------------------------------------------------- +Syntax:: + + putline(line) + +Parameters: + :line: line to be written (string) + +Return type: + None + +Exceptions raised: + :TypeError: invalid connection, bad parameter type, or too many parameters + +Description: + This method allows to directly write a string to the server socket. + +getline - gets a line from server socket [DA] +--------------------------------------------- +Syntax:: + + getline() + +Parameters: + None + +Return type: + :string: the line read + +Exceptions raised: + :TypeError: invalid connection + :TypeError: too many parameters + :MemoryError: buffer overflow + +Description: + This method allows to directly read a string from the server socket. + +endcopy - synchronizes client and server [DA] +--------------------------------------------- +Syntax:: + + endcopy() + +Parameters: + None + +Return type: + None + +Exceptions raised: + :TypeError: invalid connection + :TypeError: 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. + +locreate - create a large object in the database [LO] +----------------------------------------------------- +Syntax:: + + locreate(mode) + +Parameters: + :mode: large object create mode + +Return type: + :pglarge: object handling the PostGreSQL large object + +Exceptions raised: + + :TypeError: invalid connection, bad parameter type, or too many parameters + :pg.OperationalError: creation error + +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. + +getlo - build 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 PostGreSQL large object + +Exceptions raised: + :TypeError: invalid connection, 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. + +loimport - import a file to a large object [LO] +----------------------------------------------- +Syntax:: + + loimport(name) + +Parameters: + :name: the name of the file to be imported (string) + +Return type: + :pglarge: object handling the PostGreSQL large object + +Exceptions raised: + :TypeError: invalid connection, bad argument type, or too many arguments + :pg.OperationalError: error during file import + +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. + +Object attributes +----------------- +Every `pgobject` defines a set of read-only attributes that describe the +connection and its status. These attributes are: + + :host: the host name 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: user name on the database system (string) + :protocol_version: the frontend/backend protocol being used (integer) + :server_version: the backend version (integer, e.g. 80305 for 8.3.5) + :status: the status of the connection (integer: 1 - OK, 0 - bad) + :error: the last warning/error message from the server (string) + + +The DB wrapper class +==================== +The `pgobject` methods are wrapped in the class `DB`. +The preferred way to use this module is as follows:: + + import pg + + db = pg.DB(...) # see below + + for r in db.query( # just for example + """SELECT foo,bar + FROM foo_bar_table + WHERE foo !~ bar""" + ).dictresult(): + + print '%(foo)s %(bar)s' % r + +This class can be subclassed as in this example:: + + import pg + + class DB_ride(pg.DB): + """This class encapsulates the database functions and the specific + methods for the ride database.""" + + def __init__(self): + """Opens a database connection to the rides database""" + + pg.DB.__init__(self, dbname = 'ride') + self.query("""SET DATESTYLE TO 'ISO'""") + + [Add or override methods here] + +The following describes the methods and variables of this class. + +Initialization +-------------- +The DB class is initialized with the same arguments as the connect +function 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. + +You can also initialize the DB class with an existing `_pg` or `pgdb` +connection. Pass this connection as a single unnamed parameter, or as a +single parameter named `db`. This allows you to use all of the methods +of the DB class with a DB-API 2 compliant connection. Note that the +`close()` and `reopen()` methods are inoperative in this case. + + + +pkey - return the primary key of a table +---------------------------------------- +Syntax:: + + pkey(table) + +Parameters: + :table: name of table + +Return type: + :string: Name of the field which is the primary key of the table + +Description: + This method returns the primary key of a table. For composite primary + keys, the return value will be a frozenset. Note that this raises an + exception if the table does not have a primary key. + +get_databases - get list of databases in the system +--------------------------------------------------- +Syntax:: + + get_databases() + +Parameters: + None + +Return type: + :list: all databases in the system + +Description: + Although you can do this with a simple select, it is added here for + convenience. + +get_relations - get list of relations in connected database +----------------------------------------------------------- +Syntax:: + + get_relations(kinds) + +Parameters: + :kinds: a string or sequence of type letters + +Description: + The type letters are `r` = ordinary table, `i` = index, `S` = sequence, + `v` = view, `c` = composite type, `s` = special, `t` = TOAST table. + If `kinds` is None or an empty string, all relations are returned (this is + also the default). Although you can do this with a simple select, it is + added here for convenience. + +get_tables - get list of tables in connected database +----------------------------------------------------- +Syntax:: + + get_tables() + +Parameters: + None + +Returns: + :list: all tables in connected database + +Description: + Although you can do this with a simple select, it is added here for + convenience. + +get_attnames - get the attribute names of a table +------------------------------------------------- +Syntax:: + + get_attnames(table) + +Parameters: + :table: name of table + +Returns: + :dictionary: The keys are the attribute names, + the values are the type names of the attributes. + +Description: + Given the name of a table, digs out the set of attribute names. + +has_table_privilege - check whether current user has specified table privilege +------------------------------------------------------------------------------ +Syntax:: + + has_table_privilege(table, privilege) + +Parameters: + :table: name of table + :privilege: privilege to be checked - default is 'select' + +Description: + Returns True if the current user has the specified privilege for the table. + +get - get a row from a database table or view +--------------------------------------------- +Syntax:: + + get(table, arg, [keyname]) + +Parameters: + :table: name of table or view + :arg: either a dictionary or the value to be looked up + :keyname: name of field to use as key (optional) + +Return type: + :dictionary: The keys are the attribute names, + the values are the 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. + For a composite key, `keyname` can also be a sequence of key names. + The OID is also put into the dictionary if the table has one, but in + order to allow the caller to work with multiple tables, it is munged + as `oid(schema.table)`. + +insert - insert a row into a database table +------------------------------------------- +Syntax:: + + insert(table, [d,] [return_changes,] [key = val, ...]) + +Parameters: + :table: name of table + :d: optional dictionary of values + :return_changes: Return values in new row - default True + +Return type: + :dictionary: The dictionary of values inserted + +Description: + This method inserts a row into a table. If the optional dictionary is + not supplied then the required values must be included as keyword/value + pairs. If a dictionary is supplied then any keywords provided will be + added to or replace the entry in the dictionary. + + The dictionary is then, if possible, reloaded with the values actually + inserted in order to pick up values modified by rules, triggers, etc. + + Due to the way that this function works in PostgreSQL versions below + 8.2, you may find inserts taking longer and longer as your table gets + bigger. If this happens and it is a table with OID but no primary key + you can overcome this problem by simply adding an index onto the OID of + any table that you think may get large over time. You may also consider + using the inserttable() method described in section 3. + + Note: With PostgreSQL versions before 8.2 the table being inserted to + must have a primary key or an OID to use this method properly. If not + then the dictionary will not be filled in as described. Also, if this + method is called within a transaction, the transaction will abort. + + Note: The method currently doesn't support insert into views + although PostgreSQL does. + +update - update a row in a database table +----------------------------------------- +Syntax:: + + update(table, [d,] [key = val, ...]) + +Parameters: + :table: name of table + :d: optional dictionary of values + +Return type: + :dictionary: the new row + +Description: + Similar to insert but updates an existing row. The update is based on the + OID value as munged by get or passed as keyword, or on the primary key of + the table. The dictionary is modified, if possible, to reflect any changes + caused by the update due to triggers, rules, default values, etc. + + Like insert, the dictionary is optional and updates will be performed + on the fields in the keywords. There must be an OID or primary key + either in the dictionary where the OID must be munged, or in the keywords + where it can be simply the string "oid". + +clear - clears row values in memory +----------------------------------- +Syntax:: + + clear(table, [a]) + +Parameters: + :table: name of table + :a: optional dictionary of values + +Return type: + :dictionary: an empty row + +Description: + This method clears all the attributes to values determined by the types. + Numeric types are set to 0, Booleans are set to 'f', dates are set + to 'now()' 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. + + If the dictionary is not supplied a new one is created. + +delete - delete a row from a database table +------------------------------------------- +Syntax:: + + delete(table, [d,] [key = val, ...]) + +Parameters: + :table: name of table + :d: optional dictionary of values + +Returns: + None + +Description: + This method deletes the row from a table. It deletes based on the OID value + as munged by get or passed as keyword, or on the primary key of the table. + The return value is the number of deleted rows (i.e. 0 if the row did not + exist and 1 if the row was deleted). + +escape_string - escape a string for use within SQL +-------------------------------------------------- +Syntax:: + + escape_string(string) + +Parameters: + :string: the string that is to be escaped + +Return type: + :str: the escaped string + +Description: + Similar to the module function with the same name, but the + behavior of this method is adjusted depending on the connection properties + (such as character encoding). + +escape_bytea - escape binary data for use within SQL as type `bytea` +-------------------------------------------------------------------- +Syntax:: + + escape_bytea(datastring) + +Parameters: + :datastring: string containing the binary data that is to be escaped + +Return type: + :str: the escaped string + +Description: + Similar to the module function with the same name, but the + behavior of this method is adjusted depending on the connection properties + (in particular, whether standard-conforming strings are enabled). + +unescape_bytea -- unescape `bytea` data that has been retrieved as text +----------------------------------------------------------------------- +Syntax:: + + unescape_bytea(string) + +Parameters: + :datastring: the `bytea` data string that has been retrieved as text + +Return type: + :str: string containing the binary data + +Description: + See the module function with the same name. + + +pgqueryobject methods +===================== + +getresult - get query values as list of tuples +----------------------------------------------- +Syntax:: + + getresult() + +Parameters: + None + +Return type: + :list: result values as a list of tuples + +Exceptions raised: + :TypeError: too many parameters + :pg.InternalError: 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. + +dictresult - get query values as list of dictionaries +----------------------------------------------------- +Syntax:: + + dictresult() + +Parameters: + None + +Return type: + :list: result values as a list of dictionaries + +Exceptions raised: + :TypeError: too many parameters + :pg.InternalError: 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. + + +listfields - lists fields names of previous query result +-------------------------------------------------------- +Syntax:: + + listfields() + +Parameters: + None + +Return type: + :list: field names + +Exceptions raised: + :TypeError: too many parameters + :pg.InternalError: invalid previous result, or lost 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. + +fieldname, fieldnum - field name/number conversion +-------------------------------------------------- +Syntax:: + + fieldname(i) + +Parameters: + :i: field number (integer) + +Return type: + :string: field name + +Exceptions raised: + :TypeError: invalid connection, bad parameter type, or too many parameters + :ValueError: invalid field number + :pg.InternalError: invalid previous result, or lost 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: invalid connection, bad parameter type, or too many parameters + :ValueError: unknown field name + :pg.InternalError: invalid previous result, or lost 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. + +ntuples - return number of tuples in query object +------------------------------------------------- +Syntax:: + + ntuples() + +Parameters: + None + +Return type: + :integer: number of tuples in `pgqueryobject` + +Exceptions raised: + :TypeError: Too many arguments. + +Description: + This method returns the number of tuples found in a query. + + +Large objects: pglarge +====================== +This object handles all the request concerning a PostgreSQL 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 `pglarge` 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. + +See also the PostgreSQL programmer's guide for more information about the +large object interface. + +open - opens a large object +--------------------------- +Syntax:: + + open(mode) + +Parameters: + :mode: open mode definition (integer) + +Return type: + None + +Exceptions raised: + :TypeError: invalid connection, 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). + +close - closes a large object +----------------------------- +Syntax:: + + close() + +Parameters: + None + +Return type: + None + +Exceptions raised: + :TypeError: invalid connection + :TypeError: 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. + +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: + :TypeError: invalid connection, invalid object, + bad parameter type, or too many parameters + :ValueError: if `size` is negative + :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: + :TypeError: invalid connection, 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 + +Exceptions raised: + :TypeError: binvalid connection or invalid object, + 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 + +Exceptions raised: + :TypeError: invalid connection or invalid object + :TypeError: 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 + +Exceptions raised: + :TypeError: invalid connection or invalid object + :TypeError: too many parameters + :IOError: object is not closed, or unlink error + +Description: + This methods unlinks (deletes) the PostgreSQL large object. + +size - gives the large object size +---------------------------------- + +Syntax:: + + size() + +Parameters: + None + +Return type: + :integer: the large object size + +Exceptions raised: + :TypeError: invalid connection or invalid object + :TypeError: 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. It was + implemented because this function is very useful for a web interfaced + database. Currently, the large object needs to be opened first. + +export - saves a large object to a file +--------------------------------------- +Syntax:: + + export(name) + +Parameters: + :name: file to be created + +Return type: + None + +Exceptions raised: + :TypeError: invalid connection or invalid object, + 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. + +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 + +.. caution:: *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.
http://git-wip-us.apache.org/repos/asf/incubator-hawq/blob/192cff1f/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pgdb.html ---------------------------------------------------------------------- diff --git a/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pgdb.html b/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pgdb.html new file mode 100644 index 0000000..84962f4 --- /dev/null +++ b/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pgdb.html @@ -0,0 +1,51 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/"; /> +<title>PyGreSQL Programming Information</title> +<meta content="The DB-API compliant interface (pgdb module)" name="description" /> +<meta content="PyGreSQL, pgdb, DB-API, PostGreSQL, Python" name="keywords" /> +<link rel="stylesheet" href="docs.css" type="text/css" /> +</head> +<body> +<div class="document" id="pygresql-programming-information"> +<h1 class="title">PyGreSQL Programming Information</h1> +<h2 class="subtitle" id="the-db-api-compliant-interface-pgdb-module">The DB-API compliant interface (pgdb module)</h2> +<div class="contents topic"> +<p class="topic-title first"><a id="contents" name="contents">Contents</a></p> +<ul class="auto-toc simple"> +<li><a class="reference" href="#introduction" id="id1" name="id1">1 Introduction</a></li> +<li><a class="reference" href="#the-pgdb-module" id="id2" name="id2">2 The pgdb module</a></li> +</ul> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id1" id="introduction" name="introduction">1 Introduction</a></h1> +<p>You may either choose to use the +<a class="reference" href="pg.html">"classic" PyGreSQL interface</a> +provided by the <cite>pg</cite> module or else the +<a class="reference" href="pgdb.html">DB-API 2.0 compliant interface</a> +provided by the <cite>pgdb</cite> module.</p> +<p><a class="reference" href="http://www.python.org/dev/peps/pep-0249/";>DB-API 2.0</a> +(Python Database API Specification v2.0) +is a specification for connecting to databases (not only PostGreSQL) +from Python that has been developed by the Python DB-SIG in 1999.</p> +<p>The following documentation covers only the newer <cite>pgdb</cite> API.</p> +<dl class="docutils"> +<dt>The authoritative programming information for the DB-API is availabe at</dt> +<dd><a class="reference" href="http://www.python.org/dev/peps/pep-0249/";>http://www.python.org/dev/peps/pep-0249/</a></dd> +<dt>A tutorial-like introduction to the DB-API can be found at</dt> +<dd><a class="reference" href="http://www2.linuxjournal.com/lj-issues/issue49/2605.html";>http://www2.linuxjournal.com/lj-issues/issue49/2605.html</a></dd> +</dl> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id2" id="the-pgdb-module" name="the-pgdb-module">2 The pgdb module</a></h1> +<div class="note"> +<p class="first admonition-title">Note</p> +<p class="last">This section of the documentation still needs to be written.</p> +</div> +</div> +</div> +</body> +</html> http://git-wip-us.apache.org/repos/asf/incubator-hawq/blob/192cff1f/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pgdb.txt ---------------------------------------------------------------------- diff --git a/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pgdb.txt b/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pgdb.txt new file mode 100644 index 0000000..b333c01 --- /dev/null +++ b/tools/bin/pythonSrc/PyGreSQL-4.0/docs/pgdb.txt @@ -0,0 +1,42 @@ +================================ +PyGreSQL Programming Information +================================ + +-------------------------------------------- +The DB-API compliant interface (pgdb module) +-------------------------------------------- + +.. meta:: + :description: The DB-API compliant interface (pgdb module) + :keywords: PyGreSQL, pgdb, DB-API, PostGreSQL, Python + +.. sectnum:: +.. contents:: Contents + + +Introduction +============ +You may either choose to use the +`"classic" PyGreSQL interface <pg.html>`_ +provided by the `pg` module or else the +`DB-API 2.0 compliant interface <pgdb.html>`_ +provided by the `pgdb` module. + +`DB-API 2.0 <http://www.python.org/dev/peps/pep-0249/>`_ +(Python Database API Specification v2.0) +is a specification for connecting to databases (not only PostGreSQL) +from Python that has been developed by the Python DB-SIG in 1999. + +The following documentation covers only the newer `pgdb` API. + +The authoritative programming information for the DB-API is availabe at + http://www.python.org/dev/peps/pep-0249/ + +A tutorial-like introduction to the DB-API can be found at + http://www2.linuxjournal.com/lj-issues/issue49/2605.html + + +The pgdb module +=============== +.. note:: This section of the documentation still needs to be written. + http://git-wip-us.apache.org/repos/asf/incubator-hawq/blob/192cff1f/tools/bin/pythonSrc/PyGreSQL-4.0/docs/readme.html ---------------------------------------------------------------------- diff --git a/tools/bin/pythonSrc/PyGreSQL-4.0/docs/readme.html b/tools/bin/pythonSrc/PyGreSQL-4.0/docs/readme.html new file mode 100644 index 0000000..656f8cd --- /dev/null +++ b/tools/bin/pythonSrc/PyGreSQL-4.0/docs/readme.html @@ -0,0 +1,243 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/"; /> +<title>PyGreSQL - Python interface for PostgreSQL</title> +<meta content="PyGreSQL - Python interface for PostgreSQL" name="description" /> +<meta content="PyGreSQL, PostGreSQL, Python" name="keywords" /> +<link rel="stylesheet" href="docs.css" type="text/css" /> +</head> +<body> +<div class="document" id="pygresql-python-interface-for-postgresql"> +<h1 class="title">PyGreSQL - Python interface for PostgreSQL</h1> +<h2 class="subtitle" id="pygresql-version-4-0">PyGreSQL version 4.0</h2> +<div class="contents topic"> +<p class="topic-title first"><a id="contents" name="contents">Contents</a></p> +<ul class="simple"> +<li><a class="reference" href="#copyright-notice" id="id1" name="id1">Copyright notice</a></li> +<li><a class="reference" href="#introduction" id="id2" name="id2">Introduction</a></li> +<li><a class="reference" href="#where-to-get" id="id3" name="id3">Where to get ... ?</a><ul> +<li><a class="reference" href="#home-sites-of-the-different-packages" id="id4" name="id4">Home sites of the different packages</a></li> +<li><a class="reference" href="#download-pygresql-here" id="id5" name="id5">Download PyGreSQL here</a></li> +</ul> +</li> +<li><a class="reference" href="#distribution-files" id="id6" name="id6">Distribution files</a></li> +<li><a class="reference" href="#installation" id="id7" name="id7">Installation</a></li> +<li><a class="reference" href="#information-and-support" id="id8" name="id8">Information and support</a><ul> +<li><a class="reference" href="#for-general-information" id="id9" name="id9">For general information</a></li> +<li><a class="reference" href="#for-support" id="id10" name="id10">For support</a></li> +<li><a class="reference" href="#pygresql-programming-information" id="id11" name="id11">PyGreSQL programming information</a></li> +</ul> +</li> +<li><a class="reference" href="#changelog-and-future" id="id12" name="id12">ChangeLog and Future</a></li> +</ul> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id1" id="copyright-notice" name="copyright-notice">Copyright notice</a></h1> +<p>Written by D'Arcy J.M. Cain (<a class="reference" href="mailto:darcy@druid.net";>darcy@druid.net</a>)</p> +<p>Based heavily on code written by Pascal Andre (<a class="reference" href="mailto:andre@chimay.via.ecp.fr";>andre@chimay.via.ecp.fr</a>)</p> +<p>Copyright (c) 1995, Pascal Andre</p> +<p>Further modifications copyright (c) 1997-2008 by D'Arcy J.M. Cain +(<a class="reference" href="mailto:darcy@druid.net";>darcy@druid.net</a>)</p> +<p>Permission to use, copy, modify, and distribute this software and its +documentation for any purpose, without fee, and without a written agreement +is hereby granted, provided that the above copyright notice and this +paragraph and the following two paragraphs appear in all copies or in any +new file that contains a substantial portion of this file.</p> +<p>IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, +SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, +ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE +AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p> +<p>THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED +TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE +AUTHOR HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, +ENHANCEMENTS, OR MODIFICATIONS.</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id2" id="introduction" name="introduction">Introduction</a></h1> +<p><strong>PostgreSQL</strong> is a highly scalable, SQL compliant, open source +object-relational database management system. With more than 15 years +of development history, it is quickly becoming the de facto database +for enterprise level open source solutions. +Best of all, PostgreSQL's source code is available under the most liberal +open source license: the BSD license.</p> +<p><strong>Python</strong> Python is an interpreted, interactive, object-oriented +programming language. It is often compared to Tcl, Perl, Scheme or Java. +Python combines remarkable power with very clear syntax. It has modules, +classes, exceptions, very high level dynamic data types, and dynamic typing. +There are interfaces to many system calls and libraries, as well as to +various windowing systems (X11, Motif, Tk, Mac, MFC). New built-in modules +are easily written in C or C++. Python is also usable as an extension +language for applications that need a programmable interface. +The Python implementation is copyrighted but freely usable and distributable, +even for commercial use.</p> +<p><strong>PyGreSQL</strong> is a Python module that interfaces to a PostgreSQL database. +It embeds the PostgreSQL query library to allow easy use of the powerful +PostgreSQL features from a Python script.</p> +<p>PyGreSQL is developed and tested on a NetBSD system, but it should also +run on most other platforms where PostgreSQL and Python is running. +It is based on the PyGres95 code written by Pascal Andre (<a class="reference" href="mailto:andre@chimay.via.ecp.fr";>andre@chimay.via.ecp.fr</a>). +D'Arcy (<a class="reference" href="mailto:darcy@druid.net";>darcy@druid.net</a>) renamed it to PyGreSQL starting with +version 2.0 and serves as the "BDFL" of PyGreSQL.</p> +<p>The current version PyGreSQL 4.0 needs PostgreSQL 7.2 and Python 2.3 or above.</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id3" id="where-to-get" name="where-to-get">Where to get ... ?</a></h1> +<div class="section"> +<h2><a class="toc-backref" href="#id4" id="home-sites-of-the-different-packages" name="home-sites-of-the-different-packages">Home sites of the different packages</a></h2> +<dl class="docutils"> +<dt><strong>Python</strong>:</dt> +<dd><a class="reference" href="http://www.python.org";>http://www.python.org</a></dd> +<dt><strong>PostgreSQL</strong>:</dt> +<dd><a class="reference" href="http://www.postgresql.org";>http://www.postgresql.org</a></dd> +<dt><strong>PyGreSQL</strong>:</dt> +<dd><a class="reference" href="http://www.pygresql.org";>http://www.pygresql.org</a></dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id5" id="download-pygresql-here" name="download-pygresql-here">Download PyGreSQL here</a></h2> +<dl class="docutils"> +<dt>The <strong>released version of the source code</strong> is available at</dt> +<dd><ul class="first last simple"> +<li><a class="reference" href="ftp://ftp.pygresql.org/pub/distrib/PyGreSQL.tgz";>ftp://ftp.pygresql.org/pub/distrib/PyGreSQL.tgz</a></li> +</ul> +</dd> +<dt>You can also check the latest <strong>pre-release version</strong> at</dt> +<dd><ul class="first last simple"> +<li><a class="reference" href="ftp://ftp.pygresql.org/pub/distrib/PyGreSQL-beta.tgz";>ftp://ftp.pygresql.org/pub/distrib/PyGreSQL-beta.tgz</a></li> +</ul> +</dd> +<dt>A <strong>Linux RPM</strong> can be picked up from</dt> +<dd><ul class="first last simple"> +<li><a class="reference" href="ftp://ftp.pygresql.org/pub/distrib/pygresql.i386.rpm";>ftp://ftp.pygresql.org/pub/distrib/pygresql.i386.rpm</a></li> +</ul> +</dd> +<dt>A <strong>NetBSD package</strong> is available in their pkgsrc collection</dt> +<dd><ul class="first last simple"> +<li><a class="reference" href="ftp://ftp.netbsd.org/pub/NetBSD/packages/pkgsrc/databases/py-postgresql/README.html";>ftp://ftp.netbsd.org/pub/NetBSD/packages/pkgsrc/databases/py-postgresql/README.html</a></li> +</ul> +</dd> +<dt>A <strong>FreeBSD package</strong> is available in their ports collection</dt> +<dd><ul class="first last simple"> +<li><a class="reference" href="http://www.freebsd.org/cgi/cvsweb.cgi/ports/databases/py-PyGreSQL/";>http://www.freebsd.org/cgi/cvsweb.cgi/ports/databases/py-PyGreSQL/</a></li> +</ul> +</dd> +<dt>A <strong>Win32 package</strong> for various Python versions is available at</dt> +<dd><ul class="first last simple"> +<li><a class="reference" href="ftp://ftp.pygresql.org/pub/distrib/PyGreSQL-4.0.win32-py2.3.exe";>ftp://ftp.pygresql.org/pub/distrib/PyGreSQL-4.0.win32-py2.3.exe</a></li> +<li><a class="reference" href="ftp://ftp.pygresql.org/pub/distrib/PyGreSQL-4.0.win32-py2.4.exe";>ftp://ftp.pygresql.org/pub/distrib/PyGreSQL-4.0.win32-py2.4.exe</a></li> +<li><a class="reference" href="ftp://ftp.pygresql.org/pub/distrib/PyGreSQL-4.0.win32-py2.5.exe";>ftp://ftp.pygresql.org/pub/distrib/PyGreSQL-4.0.win32-py2.5.exe</a></li> +<li><a class="reference" href="ftp://ftp.pygresql.org/pub/distrib/PyGreSQL-4.0.win32-py2.6.exe";>ftp://ftp.pygresql.org/pub/distrib/PyGreSQL-4.0.win32-py2.6.exe</a></li> +</ul> +</dd> +<dt>You can also find PyGreSQL on the <strong>Python Package Index</strong> at</dt> +<dd><ul class="first last simple"> +<li><a class="reference" href="http://pypi.python.org/pypi/PyGreSQL/";>http://pypi.python.org/pypi/PyGreSQL/</a></li> +</ul> +</dd> +</dl> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id6" id="distribution-files" name="distribution-files">Distribution files</a></h1> +<table border="1" class="docutils"> +<colgroup> +<col width="15%" /> +<col width="85%" /> +</colgroup> +<tbody valign="top"> +<tr><td>pgmodule.c</td> +<td>the C Python module (_pg)</td> +</tr> +<tr><td>pg.py</td> +<td>the "classic" PyGreSQL module</td> +</tr> +<tr><td>pgdb.py</td> +<td>DB-SIG DB-API 2.0 compliant API wrapper for PygreSQL</td> +</tr> +<tr><td>docs/</td> +<td><p class="first">documentation directory</p> +<p>Contains: readme.txt, announce.txt, install.txt, +changelog.txt, future.txt, pg.txt and pgdb.txt.</p> +<p class="last">All text files are in ReST format, so HTML versions +can be easily created with buildhtml.py from docutils.</p> +</td> +</tr> +<tr><td>tutorial/</td> +<td><p class="first">demos directory</p> +<p>Contains: basics.py, syscat.py, advanced.py and func.py.</p> +<p class="last">The samples here have been taken from the +PostgreSQL manual and were used for module testing. +They demonstrate some PostgreSQL features.</p> +</td> +</tr> +</tbody> +</table> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id7" id="installation" name="installation">Installation</a></h1> +<p>You will find the installing instructions in +<a class="reference" href="install.html">install.txt</a>.</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id8" id="information-and-support" name="information-and-support">Information and support</a></h1> +<div class="section"> +<h2><a class="toc-backref" href="#id9" id="for-general-information" name="for-general-information">For general information</a></h2> +<dl class="docutils"> +<dt><strong>Python</strong>:</dt> +<dd><a class="reference" href="http://www.python.org";>http://www.python.org</a></dd> +<dt><strong>PostgreSQL</strong>:</dt> +<dd><a class="reference" href="http://www.postgresql.org";>http://www.postgresql.org</a></dd> +<dt><strong>PyGreSQL</strong>:</dt> +<dd><a class="reference" href="http://www.pygresql.org";>http://www.pygresql.org</a></dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id10" id="for-support" name="for-support">For support</a></h2> +<dl class="docutils"> +<dt><strong>Python</strong>:</dt> +<dd>see <a class="reference" href="http://www.python.org/community/";>http://www.python.org/community/</a></dd> +<dt><strong>PostgreSQL</strong>:</dt> +<dd>see <a class="reference" href="http://www.postgresql.org/support/";>http://www.postgresql.org/support/</a></dd> +<dt><strong>PyGreSQL</strong>:</dt> +<dd><p class="first">Contact the PyGreSQL mailing list +concerning PyGreSQL 2.0 and up.</p> +<p>If you would like to proposes changes, please join the +PyGreSQL mailing list and send context diffs there.</p> +<p class="last">See <a class="reference" href="http://mailman.vex.net/mailman/listinfo/pygresql";>http://mailman.vex.net/mailman/listinfo/pygresql</a> +to join the mailing list.</p> +</dd> +</dl> +<p>Please note that messages to individual developers will generally not be +answered directly. All questions, comments and code changes must be +submitted to the mailing list for peer review and archiving.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id11" id="pygresql-programming-information" name="pygresql-programming-information">PyGreSQL programming information</a></h2> +<p>You may either choose to use the "classic" PyGreSQL interface +provided by the <cite>pg</cite> module or else the newer DB-API 2.0 +compliant interface provided by the <cite>pgdb</cite> module.</p> +<p><a class="reference" href="http://www.python.org/dev/peps/pep-0249/";>DB-API 2.0</a> +(Python Database API Specification v2.0) +is a specification for connecting to databases (not only PostGreSQL) +from Python that has been developed by the Python DB-SIG in 1999.</p> +<p>The programming information is available in the files +<a class="reference" href="pg.html">pg.txt</a> and <a class="reference" href="pgdb.html">pgdb.txt</a>.</p> +<p>Note that PyGreSQL is not thread-safe on the connection level. Therefore +we recommend using <cite>DBUtils <http://www.webwareforpython.org/DBUtils></cite> +for multi-threaded environments, which supports both PyGreSQL interfaces.</p> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id12" id="changelog-and-future" name="changelog-and-future">ChangeLog and Future</a></h1> +<p>The ChangeLog with past changes is in the file +<a class="reference" href="changelog.html">changelog.txt</a>.</p> +<p>A to do list and wish list is in the file +<a class="reference" href="future.html">future.txt</a>.</p> +</div> +</div> +</body> +</html> http://git-wip-us.apache.org/repos/asf/incubator-hawq/blob/192cff1f/tools/bin/pythonSrc/PyGreSQL-4.0/docs/readme.txt ---------------------------------------------------------------------- diff --git a/tools/bin/pythonSrc/PyGreSQL-4.0/docs/readme.txt b/tools/bin/pythonSrc/PyGreSQL-4.0/docs/readme.txt new file mode 100644 index 0000000..77ed8ef --- /dev/null +++ b/tools/bin/pythonSrc/PyGreSQL-4.0/docs/readme.txt @@ -0,0 +1,206 @@ +========================================== +PyGreSQL - Python interface for PostgreSQL +========================================== + +-------------------- +PyGreSQL version 4.0 +-------------------- + +.. meta:: + :description: PyGreSQL - Python interface for PostgreSQL + :keywords: PyGreSQL, PostGreSQL, Python + +.. contents:: Contents + + +Copyright notice +================ + +Written by D'Arcy J.M. Cain ([email protected]) + +Based heavily on code written by Pascal Andre ([email protected]) + +Copyright (c) 1995, Pascal Andre + +Further modifications copyright (c) 1997-2008 by D'Arcy J.M. Cain +([email protected]) + +Permission to use, copy, modify, and distribute this software and its +documentation for any purpose, without fee, and without a written agreement +is hereby granted, provided that the above copyright notice and this +paragraph and the following two paragraphs appear in all copies or in any +new file that contains a substantial portion of this file. + +IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, +SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, +ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE +AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED +TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE +AUTHOR HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, +ENHANCEMENTS, OR MODIFICATIONS. + + +Introduction +============ + +**PostgreSQL** is a highly scalable, SQL compliant, open source +object-relational database management system. With more than 15 years +of development history, it is quickly becoming the de facto database +for enterprise level open source solutions. +Best of all, PostgreSQL's source code is available under the most liberal +open source license: the BSD license. + +**Python** Python is an interpreted, interactive, object-oriented +programming language. It is often compared to Tcl, Perl, Scheme or Java. +Python combines remarkable power with very clear syntax. It has modules, +classes, exceptions, very high level dynamic data types, and dynamic typing. +There are interfaces to many system calls and libraries, as well as to +various windowing systems (X11, Motif, Tk, Mac, MFC). New built-in modules +are easily written in C or C++. Python is also usable as an extension +language for applications that need a programmable interface. +The Python implementation is copyrighted but freely usable and distributable, +even for commercial use. + +**PyGreSQL** is a Python module that interfaces to a PostgreSQL database. +It embeds the PostgreSQL query library to allow easy use of the powerful +PostgreSQL features from a Python script. + +PyGreSQL is developed and tested on a NetBSD system, but it should also +run on most other platforms where PostgreSQL and Python is running. +It is based on the PyGres95 code written by Pascal Andre ([email protected]). +D'Arcy ([email protected]) renamed it to PyGreSQL starting with +version 2.0 and serves as the "BDFL" of PyGreSQL. + +The current version PyGreSQL 4.0 needs PostgreSQL 7.2 and Python 2.3 or above. + + +Where to get ... ? +================== + +Home sites of the different packages +------------------------------------ +**Python**: + http://www.python.org + +**PostgreSQL**: + http://www.postgresql.org + +**PyGreSQL**: + http://www.pygresql.org + +Download PyGreSQL here +---------------------- +The **released version of the source code** is available at + * ftp://ftp.pygresql.org/pub/distrib/PyGreSQL.tgz +You can also check the latest **pre-release version** at + * ftp://ftp.pygresql.org/pub/distrib/PyGreSQL-beta.tgz +A **Linux RPM** can be picked up from + * ftp://ftp.pygresql.org/pub/distrib/pygresql.i386.rpm +A **NetBSD package** is available in their pkgsrc collection + * ftp://ftp.netbsd.org/pub/NetBSD/packages/pkgsrc/databases/py-postgresql/README.html +A **FreeBSD package** is available in their ports collection + * http://www.freebsd.org/cgi/cvsweb.cgi/ports/databases/py-PyGreSQL/ +A **Win32 package** for various Python versions is available at + * ftp://ftp.pygresql.org/pub/distrib/PyGreSQL-4.0.win32-py2.3.exe + * ftp://ftp.pygresql.org/pub/distrib/PyGreSQL-4.0.win32-py2.4.exe + * ftp://ftp.pygresql.org/pub/distrib/PyGreSQL-4.0.win32-py2.5.exe + * ftp://ftp.pygresql.org/pub/distrib/PyGreSQL-4.0.win32-py2.6.exe +You can also find PyGreSQL on the **Python Package Index** at + * http://pypi.python.org/pypi/PyGreSQL/ + + +Distribution files +================== + +========== = +pgmodule.c the C Python module (_pg) +pg.py the "classic" PyGreSQL module +pgdb.py DB-SIG DB-API 2.0 compliant API wrapper for PygreSQL +docs/ documentation directory + + Contains: readme.txt, announce.txt, install.txt, + changelog.txt, future.txt, pg.txt and pgdb.txt. + + All text files are in ReST format, so HTML versions + can be easily created with buildhtml.py from docutils. +tutorial/ demos directory + + Contains: basics.py, syscat.py, advanced.py and func.py. + + The samples here have been taken from the + PostgreSQL manual and were used for module testing. + They demonstrate some PostgreSQL features. +========== = + + +Installation +============ +You will find the installing instructions in +`install.txt <install.html>`_. + + +Information and support +======================= + +For general information +----------------------- +**Python**: + http://www.python.org + +**PostgreSQL**: + http://www.postgresql.org + +**PyGreSQL**: + http://www.pygresql.org + +For support +----------- +**Python**: + see http://www.python.org/community/ + +**PostgreSQL**: + see http://www.postgresql.org/support/ + +**PyGreSQL**: + Contact the PyGreSQL mailing list + concerning PyGreSQL 2.0 and up. + + If you would like to proposes changes, please join the + PyGreSQL mailing list and send context diffs there. + + See http://mailman.vex.net/mailman/listinfo/pygresql + to join the mailing list. + +Please note that messages to individual developers will generally not be +answered directly. All questions, comments and code changes must be +submitted to the mailing list for peer review and archiving. + +PyGreSQL programming information +-------------------------------- +You may either choose to use the "classic" PyGreSQL interface +provided by the `pg` module or else the newer DB-API 2.0 +compliant interface provided by the `pgdb` module. + +`DB-API 2.0 <http://www.python.org/dev/peps/pep-0249/>`_ +(Python Database API Specification v2.0) +is a specification for connecting to databases (not only PostGreSQL) +from Python that has been developed by the Python DB-SIG in 1999. + +The programming information is available in the files +`pg.txt <pg.html>`_ and `pgdb.txt <pgdb.html>`_. + +Note that PyGreSQL is not thread-safe on the connection level. Therefore +we recommend using `DBUtils <http://www.webwareforpython.org/DBUtils>` +for multi-threaded environments, which supports both PyGreSQL interfaces. + + +ChangeLog and Future +==================== +The ChangeLog with past changes is in the file +`changelog.txt <changelog.html>`_. + +A to do list and wish list is in the file +`future.txt <future.html>`_.
