Added support for application context in thin mode; tweak documentation

for edition as well since they are closely related enhancements.

Author: anthony-tuininga

doc/src/api_manual/async_connection.rst

@@ -485,9 +485,8 @@ AsyncConnection Attributes
 
 .. attribute:: AsyncConnection.edition
 
-    This read-only attribute gets the session edition and is only available in
-    Oracle Database 11.2 (the server must be at this level or higher for this
-    to work). This attribute is ignored in python-oracledb Thin mode.
+    This read-only attribute gets the session edition and is only available
+    with Oracle Database 11.2, or later.
 
 .. attribute:: AsyncConnection.external_name
 

doc/src/api_manual/connect_params.rst

@@ -100,7 +100,7 @@ ConnectParams Attributes
     used by the connection. It is a list of 3-tuples that includes the
     namespace, name, and value.  Each entry in the tuple is a string.
 
-    This attribute is only supported in python-oracledb Thick mode.
+    This attribute is supported in both python-oracledb Thin and Thick modes.
 
 .. attribute:: ConnectParams.cclass
 

doc/src/api_manual/connection.rst

@@ -677,9 +677,8 @@ Connection Attributes
 
 .. attribute:: Connection.edition
 
-    This read-only attribute gets the session edition and is only available in
-    Oracle Database 11.2 (both client and server must be at this level or
-    higher for this to work).
+    This read-only attribute gets the session edition and is only available
+    with Oracle Database 11.2, or later.
 
     .. note::
 

doc/src/api_manual/module.rst

@@ -253,9 +253,9 @@ Oracledb Methods
     :attr:`defaults.stmtcachesize`.
 
     The ``edition`` parameter is expected to be a string that indicates the
-    edition to use for the connection. This parameter cannot be used
-    simultaneously with the ``cclass`` parameter. This value is only used in
-    the python-oracledb Thick mode and is ignored in the Thin mode.
+    edition to use for the connection. It requires Oracle Database 11.2, or
+    later. This parameter cannot be used simultaneously with the ``cclass``
+    parameter.
 
     The ``tag`` parameter is expected to be a string that identifies the type
     of connection that should be returned from a pool. This value is only used
@@ -276,8 +276,7 @@ Oracledb Methods
     The ``appcontext`` parameter is expected to be a list of 3-tuples that
     identifies the application context used by the connection. This parameter
     should contain namespace, name, and value and each entry in the tuple
-    should be a string.  This value is only used in the python-oracledb Thick
-    mode and is ignored in the Thin mode.
+    should be a string.
 
     The ``shardingkey`` parameter and ``supershardingkey`` parameters, if
     specified, are expected to be a sequence of values which identifies the
@@ -389,7 +388,8 @@ Oracledb Methods
     .. versionchanged:: 2.5.0
 
         The ``program``, ``machine``, ``terminal``, ``osuser``, and
-        ``driver_name`` parameters were added.
+        ``driver_name`` parameters were added. Support for ``edition`` and
+        ``appcontext`` was added to python-oracledb Thin mode.
 
     .. versionchanged:: 2.3.0
 
@@ -434,6 +434,8 @@ Oracledb Methods
     and can be specified as keyword parameters.  See
     :ref:`standaloneconnection` information about connections.
 
+    This method can only be used in python-oracledb Thin mode.
+
     .. versionadded:: 2.0.0
 
     Some values, such as the database host name, can be specified as
@@ -584,8 +586,6 @@ Oracledb Methods
     specifies the initial size of the statement cache. The default is the
     value of :attr:`defaults.stmtcachesize`.
 
-    The ``edition`` parameter is ignored in the python-oracledb Thin mode.
-
     The ``tag`` parameter is ignored in the python-oracledb Thin mode.
 
     The ``matchanytag`` parameter is ignored in the python-oracledb Thin mode.
@@ -594,7 +594,10 @@ Oracledb Methods
     directory in which configuration files (tnsnames.ora) are found. The
     default is the value of :attr:`defaults.config_dir`.
 
-    The ``appcontext`` parameter is ignored in the python-oracledb Thin mode.
+    The ``appcontext`` parameter is expected to be a list of 3-tuples that
+    identifies the application context used by the connection. This parameter
+    should contain namespace, name, and value and each entry in the tuple
+    should be a string.
 
     The ``shardingkey`` parameter and ``supershardingkey`` parameters are
     ignored in the python-oracledb Thin mode.
@@ -689,7 +692,8 @@ Oracledb Methods
     .. versionchanged:: 2.5.0
 
         The ``program``, ``machine``, ``terminal``, ``osuser``, and
-        ``driver_name`` parameters were added.
+        ``driver_name`` parameters were added. Support for ``edition`` and
+        ``appcontext`` was added.
 
     .. versionchanged:: 2.3.0
 
@@ -891,9 +895,9 @@ Oracledb Methods
     :attr:`defaults.stmtcachesize`.
 
     The ``edition`` parameter is expected to be a string that indicates the
-    edition to use for the connection. This parameter cannot be used
-    simultaneously with the ``cclass`` parameter. This value is used in the
-    python-oracledb Thick mode.
+    edition to use for the connection. It requires Oracle Database 11.2, or
+    later. This parameter cannot be used simultaneously with the ``cclass``
+    parameter.
 
     The ``tag`` parameter is expected to be a string that identifies the type of
     connection that should be returned from a pool. This value is only used
@@ -913,8 +917,7 @@ Oracledb Methods
     The ``appcontext`` parameter is expected to be a list of 3-tuples that
     identifies the application context used by the connection. This parameter
     should contain namespace, name, and value and each entry in the tuple
-    should be a string.  This value is only used inthe python-oracledb Thick
-    mode.
+    should be a string.
 
     The ``shardingkey`` parameter and ``supershardingkey`` parameters, if
     specified, are expected to be a sequence of values which identifies the
@@ -1352,9 +1355,9 @@ Oracledb Methods
     :attr:`defaults.stmtcachesize`.
 
     The ``edition`` parameter is expected to be a string that indicates the
-    edition to use for the connection. This parameter cannot be used
-    simultaneously with the ``cclass`` parameter. This value is used in the
-    python-oracledb Thick mode and is ignored in the Thin mode.
+    edition to use for the connection. It requires Oracle Database 11.2, or
+    later. This parameter cannot be used simultaneously with the ``cclass``
+    parameter.
 
     The ``tag`` parameter is expected to be a string that identifies the type
     of connection that should be returned from a pool. This value is only used
@@ -1488,7 +1491,8 @@ Oracledb Methods
     .. versionchanged:: 2.5.0
 
         The ``program``, ``machine``, ``terminal``, ``osuser``, and
-        ``driver_name`` parameters were added.
+        ``driver_name`` parameters were added. Support for ``edition`` and
+        ``appcontext`` was added to python-oracledb Thin mode.
 
     .. versionchanged:: 2.3.0
 
@@ -1538,6 +1542,8 @@ Oracledb Methods
     ``create_pool_async()`` is a synchronous method. See
     :ref:`Connection pooling <asyncconnpool>` for more information.
 
+    This method can only be used in python-oracledb Thin mode.
+
     .. versionadded:: 2.0.0
 
     Some values, such as the database host name, can be specified as
@@ -1744,8 +1750,6 @@ Oracledb Methods
     specifies the initial size of the statement cache. The default is the
     value of :attr:`defaults.stmtcachesize`.
 
-    The ``edition`` parameter is ignored in the python-oracledb Thin mode.
-
     The ``tag`` parameter is ignored in the python-oracledb Thin mode.
 
     The ``matchanytag`` parameter is ignored in the python-oracledb Thin mode.
@@ -1754,7 +1758,10 @@ Oracledb Methods
     directory in which configuration files (tnsnames.ora) are found. The
     default is the value of :attr:`defaults.config_dir`.
 
-    The ``appcontext`` parameter is ignored in the python-oracledb Thin mode.
+    The ``appcontext`` parameter is expected to be a list of 3-tuples that
+    identifies the application context used by the connection. This parameter
+    should contain namespace, name, and value and each entry in the tuple
+    should be a string.
 
     The ``shardingkey`` parameter and ``supershardingkey`` parameters are
     ignored in the python-oracledb Thin mode.
@@ -1849,7 +1856,8 @@ Oracledb Methods
     .. versionchanged:: 2.5.0
 
         The ``program``, ``machine``, ``terminal``, ``osuser``, and
-        ``driver_name`` parameters were added.
+        ``driver_name`` parameters were added. Support for ``edition`` and
+        ``appcontext`` was added.
 
     .. versionchanged:: 2.3.0
 
@@ -2271,9 +2279,9 @@ Oracledb Methods
     :attr:`defaults.stmtcachesize`.
 
     The ``edition`` parameter is expected to be a string that indicates the
-    edition to use for the connection. This parameter cannot be used
-    simultaneously with the ``cclass`` parameter. This value is used in the
-    python-oracledb Thick mode.
+    edition to use for the connection. It requires Oracle Database 11.2, or
+    later. This parameter cannot be used simultaneously with the ``cclass``
+    parameter.
 
     The ``tag`` parameter is expected to be a string that identifies the type
     of connection that should be returned from a pool. This value is only used

doc/src/release_notes.rst

@@ -48,6 +48,8 @@ Thin Mode Changes
     about any query column metadata returned from a pipeline operation.
 #)  Added support for setting the :ref:`edition <ebr>` when connecting to
     Oracle Database.
+#)  Added support for Application Contexts, i.e. the ``appcontext`` parameter
+    is supported when connecting.
 #)  Fixed bug causing some pooled connections to be permanently marked as busy
     and unavailable for reuse
     (`issue 392 <https://github.com/oracle/python-oracledb/issues/392>`__).

doc/src/user_guide/appendix_a.rst

@@ -331,7 +331,7 @@ see :ref:`driverdiff` and :ref:`compatibility`.
       - Yes
       - Yes
     * - Application Contexts
-      - No
+      - Yes
       - Yes
       - Yes
     * - Persistent and Temporary LOBs

doc/src/user_guide/appendix_b.rst

@@ -234,12 +234,13 @@ the recommended way to create a connection pool.  The use of the equivalent
 The :func:`~oracledb.create_pool()` method in the python-oracledb Thin mode
 differs from the python-oracledb Thick mode in the following ways:
 
-* Not all the parameters of the :func:`oracledb.create_pool()` method are applicable
-  to both python-oracledb modes.  Each mode ignores unrecognized parameters.
-  The parameters that are ignored in Thin mode include ``events``, ``tag``,
-  ``matchanytag``, ``appcontext``, ``shardingkey``, ``supershardingkey``, and
-  ``handle`` parameters.  The parameters that are ignored in the Thick mode include
-  ``wallet_password``, ``disable_oob``, ``config_dir``, and ``debug_jdwp`` parameters.
+* Not all the parameters of the :func:`oracledb.create_pool()` method are
+  applicable to both python-oracledb modes.  Each mode ignores unrecognized
+  parameters.  The parameters that are ignored in Thin mode include ``events``,
+  ``tag``, ``matchanytag``, ``shardingkey``, ``supershardingkey``, and
+  ``handle`` parameters.  The parameters that are ignored in the Thick mode
+  include ``wallet_password``, ``disable_oob``, ``config_dir``, and
+  ``debug_jdwp`` parameters.
 
 * The python-oracledb Thin mode only suppports :ref:`homogeneous
   <connpooltypes>` pools.

samples/app_context.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------
-# Copyright (c) 2016, 2023, Oracle and/or its affiliates.
+# Copyright (c) 2016, 2024, Oracle and/or its affiliates.
 #
 # Portions Copyright 2007-2015, Anthony Tuininga. All rights reserved.
 #
@@ -38,8 +38,9 @@
 import oracledb
 import sample_env
 
-# this script is currently only supported in python-oracledb thick mode
-oracledb.init_oracle_client(lib_dir=sample_env.get_oracle_client())
+# determine whether to use python-oracledb thin mode or thick mode
+if not sample_env.get_is_thin():
+    oracledb.init_oracle_client(lib_dir=sample_env.get_oracle_client())
 
 # client context attributes to be set
 APP_CTX_NAMESPACE = "CLIENTCONTEXT"

src/oracledb/impl/base/connect_params.pyx

@@ -93,7 +93,7 @@ cdef class ConnectParamsImpl:
         _set_obj_param(args, "ssl_context", self)
         _set_str_param(args, "debug_jdwp", self)
         _set_str_param(args, "config_dir", self)
-        _set_obj_param(args, "appcontext", self)
+        _set_app_context_param(args, "appcontext", self)
         _set_obj_param(args, "shardingkey", self)
         _set_obj_param(args, "supershardingkey", self)
         _set_bool_param(args, "externalauth", &self.externalauth)

src/oracledb/impl/base/utils.pyx

@@ -28,6 +28,29 @@
 # Cython file defining utility methods (embedded in base_impl.pyx).
 #------------------------------------------------------------------------------
 
+cdef int _set_app_context_param(dict args, str name, object target) except -1:
+    """
+    Sets an application context parameter to the value provided in the
+    dictionary, if a value is provided. This value is then set directly on the
+    target.
+    """
+    in_val = args.get(name)
+    if in_val is not None:
+        message = (
+            "appcontext should be a list of 3-tuples and each 3-tuple should "
+            "contain three strings"
+        )
+        if not isinstance(in_val, list):
+            raise TypeError(message)
+        for entry in in_val:
+            if not isinstance(entry, tuple) or len(entry) != 3:
+                raise TypeError(message)
+            for value in entry:
+                if not isinstance(value, str):
+                    raise TypeError(message)
+        setattr(target, name, in_val)
+
+
 cdef int _set_bool_param(dict args, str name, bint *out_val) except -1:
     """
     Sets a boolean parameter to the value provided in the dictionary. This can

src/oracledb/impl/thick/connection.pyx

@@ -157,8 +157,6 @@ cdef class ConnectionParams:
         num_bytes = self.num_app_context * sizeof(dpiAppContext)
         self.app_context = <dpiAppContext*> cpython.PyMem_Malloc(num_bytes)
         for i in range(self.num_app_context):
-            if not isinstance(entries[i], tuple) or len(entries[i]) != 3:
-                raise TypeError("appcontext should be a list of 3-tuples")
             namespace, name, value = entries[i]
             entry = &self.app_context[i]
             self._process_context_str(namespace, &entry.namespaceName,

src/oracledb/impl/thin/messages.pyx

@@ -1459,6 +1459,7 @@ cdef class AuthMessage(Message):
         str osuser
         str driver_name
         str edition
+        list appcontext
 
     cdef int _encrypt_passwords(self) except -1:
         """
@@ -1667,6 +1668,7 @@ cdef class AuthMessage(Message):
         if self.driver_name is None:
             self.driver_name = f"{DRIVER_NAME} thn : {DRIVER_VERSION}"
         self.edition = params.edition
+        self.appcontext = params.appcontext
 
         # if drcp is used, use purity = NEW as the default purity for
         # standalone connections and purity = SELF for connections that belong
@@ -1770,6 +1772,8 @@ cdef class AuthMessage(Message):
                 num_pairs += 1
             if self.edition is not None:
                 num_pairs += 1
+            if self.appcontext is not None:
+                num_pairs += len(self.appcontext) * 3
 
         # write basic data to packet
         self._write_function_code(buf)
@@ -1836,6 +1840,13 @@ cdef class AuthMessage(Message):
                                       self.encoded_jdwp_data)
             if self.edition is not None:
                 self._write_key_value(buf, "AUTH_ORA_EDITION", self.edition)
+            if self.appcontext is not None:
+                # NOTE: these keys require a trailing null character as the
+                # server expects it!
+                for entry in self.appcontext:
+                    self._write_key_value(buf, "AUTH_APPCTX_NSPACE\0", entry[0])
+                    self._write_key_value(buf, "AUTH_APPCTX_ATTR\0", entry[1])
+                    self._write_key_value(buf, "AUTH_APPCTX_VALUE\0", entry[2])
 
 
 @cython.final

tests/test_1100_connection.py

@@ -85,10 +85,6 @@ def test_1100(self):
         self.assertEqual(conn.thin, test_env.get_is_thin())
 
     @unittest.skipIf(test_env.get_is_drcp(), "not supported with DRCP")
-    @unittest.skipIf(
-        test_env.get_is_thin(),
-        "thin mode doesn't support application context yet",
-    )
     def test_1101(self):
         "1101 - test use of application context"
         namespace = "CLIENTCONTEXT"
@@ -106,10 +102,6 @@ def test_1101(self):
             (actual_value,) = cursor.fetchone()
             self.assertEqual(actual_value, value)
 
-    @unittest.skipIf(
-        test_env.get_is_thin(),
-        "thin mode doesn't support application context yet",
-    )
     def test_1102(self):
         "1102 - test invalid use of application context"
         self.assertRaises(

tests/test_4500_connect_params.py

@@ -721,7 +721,7 @@ def test_4539(self):
             ("tag", "tag_new"),
             ("matchanytag", False),
             ("config_dir", "config_dir_new"),
-            ("appcontext", [("a", "b", "c", "new")]),
+            ("appcontext", [("a", "b", "c"), ("d", "e", "f")]),
             ("shardingkey", [1, 2, 3, 4]),
             ("supershardingkey", [6]),
             ("debug_jdwp", "host=host;port=4638"),