diff --git a/doc/conf.py b/doc/conf.py index 208eb6f..abf6b10 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -40,9 +40,9 @@ copyright = '2008, Anthony Tuininga' # other places throughout the built documents. # # The short X.Y version. -version = '4.4' +version = '5.0' # The full version, including alpha/beta/rc tags. -release = '4.4' +release = '5.0' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: diff --git a/doc/connection.rst b/doc/connection.rst index ca678d6..d9ca158 100644 --- a/doc/connection.rst +++ b/doc/connection.rst @@ -74,6 +74,20 @@ Connection Object Cancel a long-running transaction. This is only effective on non-Windows platforms. + .. note:: + + This method is an extension to the DB API definition. + + +.. method:: Connection.changepassword(oldpassword, newpassword) + + Change the password of the logon. This method also modifies the attribute + :data:`Connection.password` upon successful completion. + + .. note:: + + This method is an extension to the DB API definition. + .. attribute:: Connection.clientinfo @@ -98,6 +112,15 @@ Connection Object Commit any pending transactions to the database. +.. attribute:: Connection.current_schema + + This read-write attribute sets the current schema attribute for the session. + + .. note:: + + This attribute is an extension to the DB API definition. + + .. method:: Connection.cursor() Return a new Cursor object (:ref:`cursorobj`) using the connection. @@ -118,6 +141,21 @@ Connection Object This read-only attribute returns the IANA character set name of the character set in use by the Oracle client. + .. note:: + + This attribute is an extension to the DB API definition and is only + available in Python 2.x when not built in unicode mode. + + +.. attribute:: Connection.inputtypehandler + + This read-write attribute specifies a method called for each value that is + bound to a statement executed on any cursor associated with this connection. + The method signature is handler(cursor, value, arraysize) and the return + value is expected to be a variable object or None in which case a default + variable object will be created. If this attribute is None, the default + behavior will take place for all values bound to statements. + .. note:: This attribute is an extension to the DB API definition. @@ -148,6 +186,21 @@ Connection Object This read-only attribute returns the IANA character set name of the national character set in use by the Oracle client. + .. note:: + + This attribute is an extension to the DB API definition and is only + available in Python 2.x when not built in unicode mode. + + +.. attribute:: Connection.outputtypehandler + + This read-write attribute specifies a method called for each value that is + to be fetched from any cursor associated with this connection. The method + signature is handler(cursor, name, defaultType, length, precision, scale) + and the return value is expected to be a variable object or None in which + case a default variable object will be created. If this attribute is None, + the default behavior will take place for all values fetched from cursors. + .. note:: This attribute is an extension to the DB API definition. @@ -175,7 +228,9 @@ Connection Object .. method:: Connection.prepare() - Prepare the distributed (global) transaction for commit. + Prepare the distributed (global) transaction for commit. Return a boolean + indicating if a transaction was actually prepared in order to avoid the + error ORA-24756 (transaction does not exist). .. note:: diff --git a/doc/cursor.rst b/doc/cursor.rst index 55b4ddb..e04b543 100644 --- a/doc/cursor.rst +++ b/doc/cursor.rst @@ -230,6 +230,21 @@ Cursor Object The DB API definition does not define this attribute. +.. attribute:: Cursor.inputtypehandler + + This read-write attribute specifies a method called for each value that is + bound to a statement executed on the cursor and overrides the attribute with + the same name on the connection if specified. The method signature is + handler(cursor, value, arraysize) and the return value is expected to be a + variable object or None in which case a default variable object will be + created. If this attribute is None, the value of the attribute with the same + name on the connection is used. + + .. note:: + + This attribute is an extension to the DB API definition. + + .. method:: Cursor.__iter__() Returns the cursor itself to be used as an iterator. @@ -264,6 +279,20 @@ Cursor Object The DB API definition does not define this attribute. +.. attribute:: Cursor.outputtypehandler + + This read-write attribute specifies a method called for each value that is + to be fetched from this cursor. The method signature is + handler(cursor, name, defaultType, length, precision, scale) and the return + value is expected to be a variable object or None in which case a default + variable object will be created. If this attribute is None, the value of + the attribute with the same name on the connection is used instead. + + .. note:: + + This attribute is an extension to the DB API definition. + + .. method:: Cursor.parse(statement) This can be used to parse a statement without actually executing it (this @@ -336,15 +365,22 @@ Cursor Object The DB API definition does not define this attribute. -.. method:: Cursor.var(dataType, [size]) +.. method:: Cursor.var(dataType, [size, arraysize, inconverter, outconverter]) - Create a variable associated with the cursor of the given type and size and - return a variable object (:ref:`varobj`). If the size is not specified and - the type is a string or binary, 4000 bytes (maximum allowable by Oracle) is - allocated; if the size is not specified and the type is a long string or - long binary, 128KB is allocated. This method was designed for use with - PL/SQL in/out variables where the length or type cannot be determined - automatically from the Python object passed in. + Create a variable associated with the cursor of the given type and + characteristics and return a variable object (:ref:`varobj`). If the size is + not specified and the type is a string or binary, 4000 bytes (maximum + allowable by Oracle) is allocated; if the size is not specified and the type + is a long string or long binary, 128KB is allocated. If the arraysize is not + specified, the bind array size (usually 1) is used. The inconverter and + outconverter specify methods used for converting values to/from the + database. More information can be found in the section on variable objects. + + + This method was designed for use with PL/SQL in/out variables where the + length or type cannot be determined automatically from the Python object + passed in or for use in input and output type handlers defined on cursors + or connections. .. note:: diff --git a/doc/module.rst b/doc/module.rst index 8b26e36..fb82187 100644 --- a/doc/module.rst +++ b/doc/module.rst @@ -23,30 +23,58 @@ Module Interface available in Oracle 10g Release 2 and higher. -.. function:: Connection([user, password, dsn, mode, handle, pool, threaded, twophase]) - connect([user, password, dsn, mode, handle, pool, threaded, twophase]) +.. function:: Connection([user, password, dsn, mode, handle, pool, threaded, twophase, events, cclass, purity, newpassword]) + connect([user, password, dsn, mode, handle, pool, threaded, twophase, events, cclass, purity, newpassword]) Constructor for creating a connection to the database. Return a Connection object (:ref:`connobj`). All arguments are optional and can be specified as - keyword parameters. The dsn (data source name) is the TNS entry (from the - Oracle names server or tnsnames.ora file) or is a string like the one - returned from makedsn(). If only one parameter is passed, a connect string - is assumed which is to be of the format ``user/password@dsn``, the same - format accepted by Oracle applications such as SQL\*Plus. If the mode is - specified, it must be one of :data:`SYSDBA` or :data:`SYSOPER` which are - defined at the module level; otherwise it defaults to the normal mode of - connecting. If the handle is specified, it must be of type OCISvcCtx\* and - is only of use when embedding Python in an application (like PowerBuilder) - which has already made the connection. The pool is only valid in Oracle 9i - and is a session pool object (:ref:`sesspool`) which is the equivalent of - calling pool.acquire(). The threaded attribute is expected to be a boolean - expression which indicates whether or not Oracle should use the mode - OCI_THREADED to wrap accesses to connections with a mutex. Doing so in - single threaded applications imposes a performance penalty of about 10-15% - which is why the default is False. The twophase attribute is expected to be - a boolean expression which indicates whether or not the attributes should be - set on the connection object to allow for two phase commit. The default for - this value is also False because of bugs in Oracle prior to Oracle 10g. + keyword parameters. + + The dsn (data source name) is the TNS entry (from the Oracle names server or + tnsnames.ora file) or is a string like the one returned from makedsn(). If + only one parameter is passed, a connect string is assumed which is to be of + the format ``user/password@dsn``, the same format accepted by Oracle + applications such as SQL\*Plus. + + If the mode is specified, it must be one of :data:`SYSDBA` or + :data:`SYSOPER` which are defined at the module level; otherwise it defaults + to the normal mode of connecting. + + If the handle is specified, it must be of type OCISvcCtx\* and is only of + use when embedding Python in an application (like PowerBuilder) which has + already made the connection. + + The pool argument is expected to be a session pool object (:ref:`sesspool`) + and the use of this argument is the equivalent of calling pool.acquire(). + + The threaded argument is expected to be a boolean expression which + indicates whether or not Oracle should use the mode OCI_THREADED to wrap + accesses to connections with a mutex. Doing so in single threaded + applications imposes a performance penalty of about 10-15% which is why the + default is False. + + The twophase argument is expected to be a boolean expression which + indicates whether or not the attributes should be set on the connection + object to allow for two phase commit. The default for this value is also + False because of bugs in Oracle prior to Oracle 10g. + + The events argument is expected to be a boolean expression which indicates + whether or not to initialize Oracle in events mode (only available in Oracle + 11g and higher). + + The cclass argument is expected to be a string and defines the connection + class for database resident connection pooling (DRCP) in Oracle 11g and + higher. + + The purity argument is expected to be one of :data:`ATTR_PURITY_NEW` (the + session must be new without any prior session state), + :data:`ATTR_PURITY_NEW` (the session may have been used before) or + :data:`ATTR_PURITY_DEFAULT` (the default behavior which is defined by Oracle + in its documentation). This argument is only relevant in Oracle 11g and + higher. + + The newpassword argument is expected to be a string if specified and sets + the password for the logon during the connection process. .. function:: Cursor(connection) @@ -138,6 +166,39 @@ Constants String constant stating the supported DB API level. Currently '2.0'. +.. data:: ATTR_PURITY_DEFAULT + + This constant is used when using database resident connection pooling (DRCP) + and specifies that the purity of the session is the default value used by + Oracle (see Oracle's documentation for more information). + + .. note:: + + This attribute is an extension to the DB API definition. + + +.. data:: ATTR_PURITY_NEW + + This constant is used when using database resident connection pooling (DRCP) + and specifies that the session acquired from the pool should be new and not + have any prior session state. + + .. note:: + + This attribute is an extension to the DB API definition. + + +.. data:: ATTR_PURITY_SELF + + This constant is used when using database resident connection pooling (DRCP) + and specifies that the session acquired from the pool need not be new and + may have prior session state. + + .. note:: + + This attribute is an extension to the DB API definition. + + .. data:: buildtime String constant stating the time when the binary was built. @@ -326,6 +387,16 @@ Constants This attribute is an extension to the DB API definition. +.. data:: INTERVAL + + This type object is used to describe columns in a database that are of type + interval day to second. + + .. note:: + + This attribute is an extension to the DB API definition. + + .. data:: LOB This type object is the Python type of :data:`BLOB` and :data:`CLOB` data diff --git a/doc/variable.rst b/doc/variable.rst index 5075606..c624de4 100644 --- a/doc/variable.rst +++ b/doc/variable.rst @@ -21,11 +21,27 @@ Variable Objects Return the value at the given position in the variable. +.. attribute:: Variable.inconverter + + This read-write attribute specifies the method used to convert data from + Python to the Oracle database. The method signature is converter(value) + and the expected return value is the value to bind to the database. If this + attribute is None, the value is bound directly without any conversion. + + .. attribute:: Variable.maxlength This read-only attribute returns the maximum length of the variable. +.. attribute:: Variable.outconverter + + This read-write attribute specifies the method used to convert data from + from the Oracle to Python. The method signature is converter(value) + and the expected return value is the value to return to Python. If this + attribute is None, the value is returned directly without any conversion. + + .. method:: Variable.setvalue(pos, value) Set the value at the given position in the variable. diff --git a/html/connection.html b/html/connection.html index 9035ccc..2c43ec3 100644 --- a/html/connection.html +++ b/html/connection.html @@ -2,13 +2,13 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-Cancel a long-running transaction. This is only effective on non-Windows +platforms.
+Note
+This method is an extension to the DB API definition.
+Change the password of the logon. This method also modifies the attribute +Connection.password upon successful completion.
+Note
+This method is an extension to the DB API definition.
+This read-write attribute sets the current schema attribute for the session.
+Note
+This attribute is an extension to the DB API definition.
+Note
+This attribute is an extension to the DB API definition and is only +available in Python 2.x when not built in unicode mode.
+This read-write attribute specifies a method called for each value that is +bound to a statement executed on any cursor associated with this connection. +The method signature is handler(cursor, value, arraysize) and the return +value is expected to be a variable object or None in which case a default +variable object will be created. If this attribute is None, the default +behavior will take place for all values bound to statements.
+Note
This attribute is an extension to the DB API definition.
Note
+This attribute is an extension to the DB API definition and is only +available in Python 2.x when not built in unicode mode.
+This read-write attribute specifies a method called for each value that is +to be fetched from any cursor associated with this connection. The method +signature is handler(cursor, name, defaultType, length, precision, scale) +and the return value is expected to be a variable object or None in which +case a default variable object will be created. If this attribute is None, +the default behavior will take place for all values fetched from cursors.
+Note
This attribute is an extension to the DB API definition.
This read-only attribute returns the password of the user which established -the connection to the database.
+This read-write attribute initially contains the password of the user which +established the connection to the database.
Note
This attribute is an extension to the DB API definition.
@@ -219,7 +277,9 @@ available in Oracle 10g R2 and higher.Prepare the distributed (global) transaction for commit.
+Prepare the distributed (global) transaction for commit. Return a boolean +indicating if a transaction was actually prepared in order to avoid the +error ORA-24756 (transaction does not exist).
Note
This method is an extension to the DB API definition.
@@ -370,12 +430,12 @@ connection has been established.