readme

关系型数据库 Postgresql 6.5.2

  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.

from pg import DB
db = 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:
   List of attribute names
 Description:
   Given the name of a table, digs out the list 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.


 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. Future directions
====================

The large object and direct access functions need much more attention.

I want to add a DB-SIG API wrapper around the underlying module.  This
will be in 3.0.