Menu
▾
▴
[Pypgsql-checkins] CVS: pypgsql README.html,NONE,1.1 README,1.29,1.30
|
From: Billy G. A. <bal...@us...> - 2002-12-05 05:34:33
|
Update of /cvsroot/pypgsql/pypgsql
In directory sc8-pr-cvs1:/tmp/cvs-serv32076
Modified Files:
README
Added Files:
README.html
Log Message:
04DEC2002 bga Updated readme file to generate the README.html using
docutils-0.2 on my system.
--- Added the generated README.html to the repository.
--- NEW FILE: README.html ---
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" SYSTEM "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="generator" content="Docutils: http://docutils.sourceforge.net/">
<link rel="stylesheet" href="default.css" type="text/css" />
<meta name="version" content="#ident "@(#) $Id: README.html,v 1.1 2002/12/05 05:34:30 ballie01 Exp $"" />
</head>
<body>
<div class="document">
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><td class="docinfo-name">Version: </td><td>
#ident "@(#) $Id: README.html,v 1.1 2002/12/05 05:34:30 ballie01 Exp $"</td></tr>
</tbody>
</table>
[...1867 lines suppressed...]
[<pyPgSQL.PgSQL.Cursor instance at 0x818495c>]
>>> c = rs[0]
>>> for i in c.description:
... print i
...
['model_year', varchar, 4, 8, None, None, None, 0]
['mktg_div_name', varchar, 50, 54, None, None, None, 0]
['model_desc', varchar, 50, 54, None, None, None, 0]
['book_types', varchar, 50, 54, None, None, None, 0]
['vehicle_syskey', integer, 4, 4, None, None, None, 0]
>>> r = c.fetchone()
>>> r
['2003', 'Buick', 'Century', '1;8;9', 2211]
>>> </pre>
</blockquote>
</div>
</div>
</div>
</body>
</html>
Index: README
===================================================================
RCS file: /cvsroot/pypgsql/pypgsql/README,v
retrieving revision 1.29
retrieving revision 1.30
diff -C2 -d -r1.29 -r1.30
*** README 1 Dec 2002 20:11:07 -0000 1.29
--- README 5 Dec 2002 05:34:30 -0000 1.30
***************
*** 1,7 ****
:Version: #ident "@(#) $Id$"
pyPgSQL - v2.3: Python DB-API 2.0 Compliant Interface Module for PostgreSQL.
! ============================================================================
!
0. Copyright notice and License
===============================
--- 1,8 ----
:Version: #ident "@(#) $Id$"
+ ----------------------------------------------------------------------------
pyPgSQL - v2.3: Python DB-API 2.0 Compliant Interface Module for PostgreSQL.
! ----------------------------------------------------------------------------
! ===============================
0. Copyright notice and License
===============================
***************
*** 28,31 ****
--- 29,33 ----
PERFORMANCE OF THIS SOFTWARE.
+ =================
1. About pyPgSQL
=================
***************
*** 83,88 ****
:pgversion.[ch]: the C code implementing the PgVersion
class.
! :pymemstrdup.c: the C code implementing a version of strdup() that
! uses Python's heap for the needed memory.
:pyPgSQL/__init__.py: the initialization code for the pyPgSQL
package.
--- 85,90 ----
:pgversion.[ch]: the C code implementing the PgVersion
class.
! :pymemstrdup.c: the C code implementing a version of strdup()
! that uses Python's heap for the needed memory.
:pyPgSQL/__init__.py: the initialization code for the pyPgSQL
package.
***************
*** 113,117 ****
b. Edit the setup.py file to reflect the your environment. The setup.py file
! contains comments regarding USE_CUSTOM to guide you in customizing this file.
c. Execute ``python setup.py build`` to build the extension module.
--- 115,120 ----
b. Edit the setup.py file to reflect the your environment. The setup.py file
! contains comments regarding USE_CUSTOM to guide you in customizing this
! file.
c. Execute ``python setup.py build`` to build the extension module.
***************
*** 122,127 ****
automatically detected.)
! Note: You may require root access to install the module. Consult your
! local system administrator.
1.4 Testing the PgSQL module.
--- 125,130 ----
automatically detected.)
! :NOTE: You may require root access to install the module.
! Consult your local system administrator.
1.4 Testing the PgSQL module.
***************
*** 131,135 ****
directory:
! ``python test/PgSQLTestCases.py``
If the test cases run without any failures, then you can be reasonably sure
--- 134,138 ----
directory:
! ``python test/PgSQLTestCases.py``
If the test cases run without any failures, then you can be reasonably sure
***************
*** 141,146 ****
such a database with the following commands::
! createdb -E UNICODE pypgsql
! createlang plpgsql pypgsql
1.5 Additional information about ...
--- 144,149 ----
such a database with the following commands::
! createdb -E UNICODE pypgsql
! createlang plpgsql pypgsql
1.5 Additional information about ...
***************
*** 153,156 ****
--- 156,160 ----
:mxDateTime: http://starship.python.net/~lemburg/mxDateTime.html
+ ===========================
2. Programming Information
===========================
***************
*** 158,172 ****
2.1 The libpq module
--------------------
!
2.1.1 Importing libpq
---------------------
The module, libpq, is part of the pyPgSQL package. It is imported using
! the following statement::
! from pyPgSQL import libpq
- Note: This has change from 1.x releases of pyPgSQL where "import libpq"
- was used to import the module.
2.1.2 libpq Constants
--- 162,174 ----
2.1 The libpq module
--------------------
!
2.1.1 Importing libpq
---------------------
The module, libpq, is part of the pyPgSQL package. It is imported using
! the following statement:
! >>> from pyPgSQL import libpq
2.1.2 libpq Constants
***************
*** 234,238 ****
:RESULT_DQL: result was generated by a DQL query.
:RESULT_DML: result was generated by a DML query.
! :RESULT_EMPTY: query generated an empty result..
:RESULT_ERROR: query generated an error.
--- 236,240 ----
:RESULT_DQL: result was generated by a DQL query.
:RESULT_DML: result was generated by a DML query.
! :RESULT_EMPTY: query generated an empty result.
:RESULT_ERROR: query generated an error.
***************
*** 368,375 ****
*Description*:
This method returns a PgBoolean object initialized from the
! value of object. It recognizes the following string values::
! For true.: '1', 'T', 'TRUE', 'Y', 'YES', 'ON'
! For false: '0', 'F', 'FALSE', 'N', 'NO', 'OFF'
For numeric object, zero is false, non-zero is true.
--- 370,377 ----
*Description*:
This method returns a PgBoolean object initialized from the
! value of object. It recognizes the following string values:
! For true.: '1', 'T', 'TRUE', 'Y', 'YES', 'ON'
! For false: '0', 'F', 'FALSE', 'N', 'NO', 'OFF'
For numeric object, zero is false, non-zero is true.
***************
*** 438,461 ****
following characters escaped::
! 1. The backslash character (as '\\')
! 2. The single quote (as "\'")
! 3. The <CR> character (as '\r')
! 4. The <NL> character (as '\n')
! 5. The <BS> character (as '\b')
! 6. The <FF> character (as '\f')
! 7. The <TAB> character (as '\t')
! 8. All other control characters as '\OOO' where OOO is
! the octal representation of the character's ordinal
! number.
! The string is also quoted with single quotes.
!
! If forArray is one (1), the escaping is changed as follows:
! 1. The backslash character (as '\\\\')
! (2 through 7 remain the same)
! 8. All other control characters as '\\\\000'
! 9. The double quote (as '\"')
! The string is also quoted with double quotes, instead of single
! quotes.
*Returns*:
--- 440,462 ----
following characters escaped::
! 1. The backslash character (as '\\')
! 2. The single quote (as "\'")
! 3. The <CR> character (as '\r')
! 4. The <NL> character (as '\n')
! 5. The <BS> character (as '\b')
! 6. The <FF> character (as '\f')
! 7. The <TAB> character (as '\t')
! 8. All other control characters as '\OOO' where OOO is
! the octal representation of the character's ordinal
! number.
! The string is also quoted with single quotes.
! If forArray is one (1), the escaping is changed as follows:
! 1. The backslash character (as '\\\\')
! (2 through 7 remain the same)
! 8. All other control characters as '\\\\000'
! 9. The double quote (as '\"')
! The string is also quoted with double quotes, instead of single
! quotes.
*Returns*:
***************
*** 472,491 ****
escaped as follows::
! 1. <NUL> characters: '\\000' (Note: with 2 backslashes)
! 2. Non-printable characters: '\OOO' (Note OOO is the octal
! representation of the characters ordinal number)
! 3. Backslashes: '\\\\' (Note: with 4 backslashes)
! 4. Single quote: "\'"
! The string is also quoted with single quotes.
! If forArray is one (1), the escaping is changed as follows:
! 1. <NUL> characters: '\\\\000' (Note: with 4 backslashes)
! 2. Non-printable characters: '\\\\OOO'
! 3. Backslashes: '\\\\\\\\' (Note: with 8 backslashes)
! 4. Single quote: "\'"
! 5. The double quote (as '\\"')
! The string is also quoted with double quotes, instead of single
! quotes.
*Returns*:
--- 473,492 ----
escaped as follows::
! 1. <NUL> characters: '\\000' (Note: with 2 backslashes)
! 2. Non-printable characters: '\OOO' (Note OOO is the octal
! representation of the characters ordinal number)
! 3. Backslashes: '\\\\' (Note: with 4 backslashes)
! 4. Single quote: "\'"
! The string is also quoted with single quotes.
! If forArray is one (1), the escaping is changed as follows:
! 1. <NUL> characters: '\\\\000' (Note: with 4 backslashes)
! 2. Non-printable characters: '\\\\OOO'
! 3. Backslashes: '\\\\\\\\' (Note: with 8 backslashes)
! 4. Single quote: "\'"
! 5. The double quote (as '\\"')
! The string is also quoted with double quotes, instead of single
! quotes.
*Returns*:
***************
*** 563,570 ****
notices are placed in the list so that the list.pop()
method will retrieve the oldest notice on the list.
! NOTE: While this attribute is read-only, you can still
! manipulate the list using any of the list's methods
! (pop, append, insert, etc.). You just can't assign
! a new value to the attribute.
:version: version information about the backend that this connection
object is connected to.
--- 564,573 ----
notices are placed in the list so that the list.pop()
method will retrieve the oldest notice on the list.
!
! :NOTE: While this attribute is read-only, you can still
! manipulate the list using any of the list's methods
! (pop, append, insert, etc.). You just can't assign
! a new value to the attribute.
!
:version: version information about the backend that this connection
object is connected to.
***************
*** 818,822 ****
the backend server) into a (dynamically sized) buffer. This method
implements the PQgetline function and is used with the PostgreSQL COPY
! command..
*Exceptions*:
--- 821,825 ----
the backend server) into a (dynamically sized) buffer. This method
implements the PQgetline function and is used with the PostgreSQL COPY
! command.
*Exceptions*:
***************
*** 840,844 ****
by the backend server) into a (dynamically sized) buffer. This method
implements the PQgetline function and is used with the PostgreSQL COPY
! command..
*Exceptions*:
--- 843,847 ----
by the backend server) into a (dynamically sized) buffer. This method
implements the PQgetline function and is used with the PostgreSQL COPY
! command.
*Exceptions*:
***************
*** 860,864 ****
The putline method sends a (null-terminated) string to the backend.
This method implements the PQputline function and is used with the
! PostgreSQL COPY command..
*Exceptions*:
--- 863,867 ----
The putline method sends a (null-terminated) string to the backend.
This method implements the PQputline function and is used with the
! PostgreSQL COPY command.
*Exceptions*:
***************
*** 883,887 ****
backend using getline. It must be issued or the backend may get "out of
sync" with the frontend. This method implements the PQputline function
! and is used with the PostgreSQL COPY command..
*Exceptions*:
--- 886,890 ----
backend using getline. It must be issued or the backend may get "out of
sync" with the frontend. This method implements the PQputline function
! and is used with the PostgreSQL COPY command.
*Exceptions*:
***************
*** 1012,1016 ****
tuple data, 0 if it contains ASCII data. It returns
the output of the PQbinaryTuples function call.
! Note: Binary portals are not supported at this time.
:cmdStatus: The command status string from the SQL command that
generated the PGresult. It returns the output to the
--- 1015,1021 ----
tuple data, 0 if it contains ASCII data. It returns
the output of the PQbinaryTuples function call.
!
! :NOTE: Binary portals are not supported at this time.
!
:cmdStatus: The command status string from the SQL command that
generated the PGresult. It returns the output to the
***************
*** 1304,1308 ****
between binary and non-binary data.
! Note: 'w+' will NOT truncate the large object.
*Note*:
--- 1309,1313 ----
between binary and non-binary data.
! :NOTE: 'w+' will NOT truncate the large object.
*Note*:
***************
*** 1343,1349 ****
*Description*:
This method will export the PostgreSQL large object to the
! specified UNIX filename. Note: The file is stored on the
! database server, not the client machine (if different from
! the server).
2.1.4.4 The PgNotify Object
--- 1348,1356 ----
*Description*:
This method will export the PostgreSQL large object to the
! specified UNIX filename.
!
! *Note*:
! The file is stored on the database server, not the client machine (if
! different from the server).
2.1.4.4 The PgNotify Object
***************
*** 1372,1390 ****
object using the str() or repr() function.
! For example, for version 6.5.3, the contents of the PgVersion object would be::
! connection.version == "PostgreSQL 6.5.3 on <system dependent info>"
! connection.version.major == 6
! connection.version.minor == 5
! connection.version.level == 3
! connection.version.post70 == 0
! For example, for version 7.1.1, the contents of PgVer would be::
! connection.version == "PostgreSQL 7.1.1 on <system dependent info>"
! connection.version.major == 7
! connection.version.minor == 1
! connection.version.level == 1
! connection.version.post70 == 1
Also, you can use the PgVersion object to compare against a number or string
--- 1379,1401 ----
object using the str() or repr() function.
! For example, for version 6.5.3, the contents of the PgVersion object would be:
! ::
! connection.version == "PostgreSQL 6.5.3 on <system dependent info>"
! connection.version.major == 6
! connection.version.minor == 5
! connection.version.level == 3
! connection.version.post70 == 0
! For example, for version 7.1.1, the contents of PgVer would be:
!
! ::
!
! connection.version == "PostgreSQL 7.1.1 on <system dependent info>"
! connection.version.major == 7
! connection.version.minor == 1
! connection.version.level == 1
! connection.version.post70 == 1
Also, you can use the PgVersion object to compare against a number or string
***************
*** 1393,1413 ****
An example:
! Assume that the PostgreSQL version is 7.0.2, then::
! connection.version == 70002 will be true.
! connection.version < 70001L will be false.
! connection.version > 70001.0 will be true.
You can also compare against a string as follows:
! Assume that the PostgreSQL version is 7.1.2, then::
! connection.version == "7.0.2" will be false.
! connection.version < "7.0.1" will be false.
! connection.version > "7.1" will be true.
! Note: Both the libpq and PgSQL connection objects have the version attribute.
! Note: Comparisons against strings (i.e. "7.0.1") does not work in Python 2.0.
2.2 The PgSQL module
--- 1404,1429 ----
An example:
! Assume that the PostgreSQL version is 7.0.2, then:
! ::
!
! connection.version == 70002 will be true.
! connection.version < 70001L will be false.
! connection.version > 70001.0 will be true.
You can also compare against a string as follows:
! Assume that the PostgreSQL version is 7.1.2, then:
! ::
! connection.version == "7.0.2" will be false.
! connection.version < "7.0.1" will be false.
! connection.version > "7.1" will be true.
! :NOTE: Both the libpq and PgSQL connection objects have the version attribute.
!
! :NOTE: Comparisons against strings (i.e. "7.0.1") does not work in
! Python 2.0.
2.2 The PgSQL module
***************
*** 1425,1432 ****
the following statement:
! from pyPgSQL import PgSQL
!
! Note: This has change from previous releases of pyPgSQL where "import PgSQL"
! was used to import the module.
2.2.2 Differences at the Module Level
--- 1441,1445 ----
the following statement:
! >>> from pyPgSQL import PgSQL
2.2.2 Differences at the Module Level
***************
*** 1471,1475 ****
a list plus adds a __quote__ method for quoting arrays.
! 3. The following class is defined:
:PgVersion: Contains the version number of PostgreSQL database engine that
--- 1484,1488 ----
a list plus adds a __quote__ method for quoting arrays.
! 4. The following class is defined:
:PgVersion: Contains the version number of PostgreSQL database engine that
***************
*** 1479,1483 ****
PgVersion object.
! 4. The following constructors are defined by the PgSQL module.
:PgBoolean: Construct a PgBoolean from a Python numeric or string.
--- 1492,1496 ----
PgVersion object.
! 5. The following constructors are defined by the PgSQL module.
:PgBoolean: Construct a PgBoolean from a Python numeric or string.
***************
*** 1489,1493 ****
These constructors are documented in the libpq section of this document.
! 5. The following attribute is defined in the PgSQL module:
:fetchReturnsList: controls the type of result returns by the fetchXXX
--- 1502,1506 ----
These constructors are documented in the libpq section of this document.
! 6. The following attribute is defined in the PgSQL module:
:fetchReturnsList: controls the type of result returns by the fetchXXX
***************
*** 1506,1511 ****
This attribute is a list of notices returned by the pq library.
! Note: Under normal usage, certain (but not all) notices received from the
! libpq C-API library are converted into Warning exceptions.
2. The Connection object has an additional read-only attribute called version.
--- 1519,1524 ----
This attribute is a list of notices returned by the pq library.
! :NOTE: Under normal usage, certain (but not all) notices received from
! the libpq C-API library are converted into Warning exceptions.
2. The Connection object has an additional read-only attribute called version.
***************
*** 1524,1529 ****
"READ COMMITED", or "SERIALIZABLE". PgSQL will issue the appropriate "SET
TRANSACTION LEVEL" statement whenever a new transaction is started for
! the connection. Note: The value of this attribute can not be changed if
! there are any active cursors for the connection.
2.2.3.1 unlink
--- 1537,1544 ----
"READ COMMITED", or "SERIALIZABLE". PgSQL will issue the appropriate "SET
TRANSACTION LEVEL" statement whenever a new transaction is started for
! the connection.
!
! :NOTE: The value of this attribute can not be changed if there are any
! active cursors for the connection.
2.2.3.1 unlink
***************
*** 1554,1560 ****
result set (or nothing).
! NOTE: Beginning with PostgreSQL 7.2, it is possible to return a refer-
! ence to a cursor from PL/pgSQL. PgSQL will create a new Cursor
! object for the referenced cursor that is returned.
3. When using the execute method, you should only use '%s' [or '%(name)s']
--- 1569,1575 ----
result set (or nothing).
! :NOTE: Beginning with PostgreSQL 7.2, it is possible to return a
! reference to a cursor from PL/pgSQL. PgSQL will create a new
! Cursor object for the referenced cursor that is returned.
3. When using the execute method, you should only use '%s' [or '%(name)s']
***************
*** 1569,1579 ****
using the column name as an attribute of the PgResultSet object. The column
names are case-insensitive.
! [Note: This feature is controlled by the fetchReturnsList attribute of
! the PgSQL module.]
5. The fetchmany and fetchall methods return a sequence of PgResultSet objects
instead of a sequence of sequences.
! [Note: This feature is controlled by the fetchReturnsList attribute of
! the PgSQL module.]
6. A PostgreSQL specific attribute, named oidValue, was added to the cursor
--- 1584,1596 ----
using the column name as an attribute of the PgResultSet object. The column
names are case-insensitive.
!
! :NOTE: This feature is controlled by the fetchReturnsList attribute of
! the PgSQL module.
5. The fetchmany and fetchall methods return a sequence of PgResultSet objects
instead of a sequence of sequences.
!
! :NOTE: This feature is controlled by the fetchReturnsList attribute of
! the PgSQL module.
6. A PostgreSQL specific attribute, named oidValue, was added to the cursor
***************
*** 1582,1585 ****
--- 1599,1603 ----
way to get the object ID of a newly inserted record.
+ ==================================
3.0 General Notes and Observations
==================================
***************
*** 1587,1600 ****
The PostgreSQL database system has no auto-commit setting. It is always in
auto-commit mode unless a transaction is started. To achieve the DB-API 2.0
! mandated behaviour, when connection.autocommit is 0, a transaction is started
! when the first cursor is created for a connection. After a commit or rollback,
! a new transaction is created on the next call to execute().
! ----------
! PostgreSQL arrays are no longer (directly) represented by Python lists. This
! means that lists and tuples are not longer treated specially by
Cursor.execute(). This resolves a problem of using the IN SQL syntax with
Cursor.execute(). For example, the following statement will now work:
! Cursor.execute('select * from table where column1 in %s', ((1, 3, 4),))
It will generate the following SQL statement:
--- 1605,1620 ----
The PostgreSQL database system has no auto-commit setting. It is always in
auto-commit mode unless a transaction is started. To achieve the DB-API 2.0
! mandated behaviour, when connection.autocommit is 0, a transaction is
! started when the first cursor is created for a connection. After a commit
! or rollback, a new transaction is created on the next call to execute().
!
! ----------------------------------------------------------------------------
!
! PostgreSQL arrays are no longer (directly) represented by Python lists.
! This means that lists and tuples are not longer treated specially by
Cursor.execute(). This resolves a problem of using the IN SQL syntax with
Cursor.execute(). For example, the following statement will now work:
! >>> Cursor.execute('select * from table where column1 in %s', ((1, 3, 4),))
It will generate the following SQL statement:
***************
*** 1603,1627 ****
It also means that to insert an PostgreSQL array, you must pass a PgArray
! instance to Cursor.execute(). For example, if you have a list that you
! want to insert into a table as a PostgreSQL array, you would use:
! cursor.execute('insert in sometable values (%s)', PgArray(yourlist))
You can also build a PostgreSQL array by creating an empty PgArray instance
and populating it using the various list methods (.append(), .insert(), etc.).
! ----------
When working with PostgreSQL large object, you MUST be in a transaction.
The code will try to ensure that a transaction is active while working with
large object (i.e. lo_open will start a transaction if necessary. lo_close
will end the transaction if it determines that lo_open started one.)
! ----------
Beginning with PostgreSQL 7.2, you can now create a cursor in PL/pgSQL and
! return a reference to that cursor. PgSQL will transform the reference to the
! created cursor into a Cursor object that can be used to fetch the results of
! the cursor. For example (assuming that mmYearInfo returns a reference cursor):
- $ python
- Python 2.2.2 (#7, Nov 27 2002, 17:10:05) [C] on openunix8
- Type "help", "copyright", "credits" or "license" for more information.
>>> from pyPgSQL import PgSQL
>>> cx = PgSQL.connect(database='esi')
--- 1623,1649 ----
It also means that to insert an PostgreSQL array, you must pass a PgArray
! instance to Cursor.execute(). For example, if you have a list that you want
! to insert into a table as a PostgreSQL array, you would use:
! >>> cursor.execute('insert in sometable values (%s)', PgArray(yourlist))
You can also build a PostgreSQL array by creating an empty PgArray instance
and populating it using the various list methods (.append(), .insert(), etc.).
!
! ----------------------------------------------------------------------------
!
When working with PostgreSQL large object, you MUST be in a transaction.
The code will try to ensure that a transaction is active while working with
large object (i.e. lo_open will start a transaction if necessary. lo_close
will end the transaction if it determines that lo_open started one.)
!
! ----------------------------------------------------------------------------
!
Beginning with PostgreSQL 7.2, you can now create a cursor in PL/pgSQL and
! return a reference to that cursor. PgSQL will transform the reference to
! the created cursor into a Cursor object that can be used to fetch the
! results of the cursor. For example (assuming that mmYearInfo returns a
! reference cursor):
>>> from pyPgSQL import PgSQL
>>> cx = PgSQL.connect(database='esi')
|