Added support for capturing warnings on connections and cursors.

Author: anthony-tuininga

doc/src/api_manual/connection.rst

@@ -4,7 +4,8 @@
 API: Connection Objects
 ***********************
 
-A Connection object can be created with :meth:`oracledb.connect()`.
+A Connection object can be created with :meth:`oracledb.connect()` or with
+:meth:`ConnectionPool.acquire()`.
 
 .. note::
 
@@ -932,3 +933,34 @@ Connection Attributes
         If you connect to Oracle Database 18 or higher using Oracle Client
         libraries 12.2 or lower you will only receive the base version (such as
         18.0.0.0.0) instead of the full version (such as 18.3.0.0.0).
+
+.. attribute:: Connection.warning
+
+    This read-only attribute provides an :ref:`oracledb._Error<exchandling>`
+    object giving information about any database warnings (such as the password
+    being in the grace period, or the pool being created with a smaller than
+    requested size due to database resource restrictions) that were generated
+    during connection establishment or by :meth:`oracledb.create_pool()`. The
+    attribute will be present if there was a warning, but creation otherwise
+    completed successfully. The connection will be usable despite the warning.
+
+    For :ref:`standalone connections <standaloneconnection>`,
+    ``Connection.warning`` will be present for the lifetime of the connection.
+
+    For :ref:`pooled connections <connpooling>`, ``Connection.warning`` will be
+    cleared when a connection is released to the pool such as with
+    :meth:`ConnectionPool.release()`.
+
+    In python-oracledb Thick mode, warnings may be generated during pool
+    creation itself.  These warnings will be placed on new connections created
+    by the pool, provided no warnings were generated by the individual
+    connection creations, in which case those connection warnings will be
+    returned.
+
+    If no warning was generated the value ``None`` is returned.
+
+    .. versionadded:: 2.0.0
+
+    .. note::
+
+        This attribute is an extension to the DB API definition.

doc/src/api_manual/cursor.rst

@@ -634,3 +634,21 @@ Cursor Attributes
     .. note::
 
         The DB API definition does not define this attribute.
+
+.. attribute:: Cursor.warning
+
+    This read-only attribute provides an :ref:`oracledb._Error<exchandling>`
+    object giving information about any database warnings (such as PL/SQL
+    compilation warnings) that were generated during the last call to
+    :meth:`~Cursor.execute()` or :meth:`~Cursor.executemany()`. This value is
+    automatically cleared on the next call to :meth:`~Cursor.execute()` or
+    :meth:`~Cursor.executemany()`. If no warning was generated the value
+    ``None`` is returned.
+
+    See :ref:`plsqlwarning` for more information.
+
+    .. versionadded:: 2.0.0
+
+    .. note::
+
+        The DB API definition does not define this attribute.

doc/src/release_notes.rst

@@ -47,6 +47,11 @@ Common Changes
 ++++++++++++++
 
 #)  Dropped support for Python 3.6 and added support for Python 3.12.
+#)  Added property :attr:`Cursor.warning` for database warnings (such as PL/SQL
+    compilation warnings) generated by calls to :meth:`Cursor.execute()` or
+    :meth:`Cursor.executemany()`.
+#)  Added property :attr:`Connection.warning` for warnings (such as the password
+    being in the grace period) generated during connection.
 #)  Added properties that provide information about the database:
     :attr:`Connection.db_domain`, :attr:`Connection.db_name`,
     :attr:`Connection.max_open_cursors`, :attr:`Connection.service_name`

doc/src/user_guide/plsql_execution.rst

@@ -34,8 +34,8 @@ then the following Python code can be used to call it:
     cursor.callproc('myproc', [123, out_val])
     print(out_val.getvalue())        # will print 246
 
-Calling :meth:`Cursor.callproc()` actually generates an anonymous PL/SQL block
-as shown below, which is then executed:
+Calling :meth:`Cursor.callproc()` internally generates an :ref:`anonymous PL/SQL
+block <anonplsql>` and executes it.  This is equivalent to the application code:
 
 .. code-block:: python
 
@@ -113,6 +113,8 @@ The Python code that will call this procedure looks as follows:
 See :ref:`bind` for information on binding.
 
 
+.. _anonplsql:
+
 Anonymous PL/SQL Blocks
 -----------------------
 
@@ -134,34 +136,56 @@ Creating Stored Procedures and Packages
 ---------------------------------------
 
 To create PL/SQL stored procedures and packages, use :meth:`Cursor.execute()`
-with a SQL CREATE command.
+with a CREATE command. For example:
+
+.. code-block:: python
+
+    cursor.execute("""
+            create or replace procedure myprocedure
+            (p_in in number, p_out out number) as
+            begin
+                p_out := p_in * 2;
+            end;""")
+
+.. _plsqlwarning:
 
-Creation warning messages can be found from database views like USER_ERRORS.
+PL/SQL Compilation Warnings
++++++++++++++++++++++++++++
 
-For example, creating a procedure with an error could be like:
+When creating PL/SQL procedures and functions (or creating types) in
+python-oracledb, the statement might succeed without throwing an error, but
+there may be additional informational messages. (These messages are sometimes
+known in Oracle as "success with info" messages). If your application needs to
+show such messages, they must be explicitly looked for using
+:attr:`Cursor.warning`. A subsequent query from a table like ``USER_ERRORS``
+will show more details. For example:
 
 .. code-block:: python
 
     with connection.cursor() as cursor:
+
         cursor.execute("""
-                create or replace procedure badproc (a in number) as
-                begin
-                    WRONG WRONG WRONG
-                end;""")
-        cursor.execute("""
-                select line, position, text
-                from user_errors
-                where name = 'BADPROC' and type = 'PROCEDURE'
-                order by name, type, line, position""")
-        errors = cursor.fetchall()
-        if errors:
-            for info in errors:
+                    create or replace procedure badproc as
+                    begin
+                        WRONG WRONG WRONG
+                    end;""")
+
+        if cursor.warning.full_code == "DPY-7000":
+            print(cursor.warning)
+
+            # Get details
+            cursor.execute("""
+                    select line, position, text
+                    from user_errors
+                    where name = 'BADPROC' and type = 'PROCEDURE'
+                    order by name, type, line, position""")
+            for info in cursor:
                 print("Error at line {} position {}:\n{}".format(*info))
-        else:
-            print("Created successfully")
 
 The output would be::
 
+    DPY-7000: creation succeeded with compilation errors
+    Error at line 3 position 27:
     PLS-00103: Encountered the symbol "WRONG" when expecting one of the following:
 
        := . ( @ % ;

src/oracledb/base_impl.pxd

@@ -242,6 +242,7 @@ cdef class BaseConnImpl:
         readonly str proxy_user
         public object inputtypehandler
         public object outputtypehandler
+        public object warning
         public bint autocommit
         public bint invoke_session_callback
         readonly tuple server_version
@@ -279,6 +280,7 @@ cdef class BaseCursorImpl:
         public list bind_vars
         public type bind_style
         public dict bind_vars_by_name
+        public object warning
         uint32_t _buffer_rowcount
         uint32_t _buffer_index
         uint32_t _fetch_array_size

src/oracledb/connection.py

@@ -1084,6 +1084,16 @@ def version(self) -> str:
             self._version = ".".join(str(c) for c in self._impl.server_version)
         return self._version
 
+    @property
+    def warning(self) -> errors._Error:
+        """
+        Returns any warning that was generated when the connection was created,
+        or the value None if no warning was generated. The value will be
+        cleared for pooled connections after they are returned to the pool.
+        """
+        self._verify_connected()
+        return self._impl.warning
+
     def xid(
         self,
         format_id: int,

src/oracledb/cursor.py

@@ -428,6 +428,7 @@ def execute(
         self._set_input_sizes = False
         if parameters is not None:
             impl.bind_one(self, parameters)
+        impl.warning = None
         impl.execute(self)
         if impl.fetch_vars is not None:
             return self
@@ -882,3 +883,14 @@ def var(
             bypass_decode,
             convert_nulls=convert_nulls,
         )
+
+    @property
+    def warning(self) -> Union[errors._Error, None]:
+        """
+        Returns any warning that was generated during the last call to
+        execute() or executemany(), or the value None if no warning was
+        generated. This value will be cleared on the next call to execute() or
+        executemany().
+        """
+        self._verify_open()
+        return self._impl.warning

src/oracledb/errors.py

@@ -134,6 +134,15 @@ def _get_error_text(error_num: int, **args) -> str:
     return f"{ERR_PREFIX}-{error_num:04}: {message}"
 
 
+def _create_warning(error_num: int, **args) -> _Error:
+    """
+    Returns a warning error object for the specified error number and supplied
+    arguments.
+    """
+    message = _get_error_text(error_num, **args)
+    return _Error(message, iswarning=True)
+
+
 def _raise_err(
     error_num: int,
     context_error_message: str = None,
@@ -291,6 +300,9 @@ def _raise_from_string(exc_type: Exception, message: str) -> None:
 ERR_PROXY_FAILURE = 6004
 ERR_CONNECTION_FAILED = 6005
 
+# error numbers that result in Warning
+WRN_COMPILATION_ERROR = 7000
+
 # Oracle error number cross reference
 ERR_ORACLE_ERROR_XREF = {
     28: ERR_CONNECTION_CLOSED,
@@ -309,6 +321,7 @@ def _raise_from_string(exc_type: Exception, message: str) -> None:
     24459: ERR_POOL_NO_CONNECTION_AVAILABLE,
     24496: ERR_POOL_NO_CONNECTION_AVAILABLE,
     24338: ERR_INVALID_REF_CURSOR,
+    24344: WRN_COMPILATION_ERROR,
     38902: ERR_TOO_MANY_BATCH_ERRORS,
 }
 
@@ -331,6 +344,7 @@ def _raise_from_string(exc_type: Exception, message: str) -> None:
     4: exceptions.DatabaseError,
     5: exceptions.InternalError,
     6: exceptions.OperationalError,
+    7: exceptions.Warning,
 }
 
 # error messages that have a troubleshooting section available
@@ -610,4 +624,5 @@ def _raise_from_string(exc_type: Exception, message: str) -> None:
     ERR_WRONG_SCROLL_MODE: (
         "scroll mode must be relative, absolute, first or last"
     ),
+    WRN_COMPILATION_ERROR: "creation succeeded with compilation errors",
 }

src/oracledb/impl/thick/connection.pyx

@@ -271,6 +271,7 @@ cdef class ThickConnImpl(BaseConnImpl):
             ConnectParamsImpl pool_params
             dpiAccessToken access_token
             dpiVersionInfo version_info
+            dpiErrorInfo error_info
             ConnectionParams params
             int status
 
@@ -388,10 +389,15 @@ cdef class ThickConnImpl(BaseConnImpl):
                                     params.password_len, params.dsn_ptr,
                                     params.dsn_len, &common_params,
                                     &conn_params, &self._handle)
-            if status == DPI_SUCCESS:
-                status = dpiConn_getServerVersion(self._handle, NULL, NULL,
-                                                  &version_info)
+            dpiContext_getError(driver_context, &error_info)
         if status < 0:
+            _raise_from_info(&error_info)
+        elif error_info.isWarning:
+            self.warning = _create_new_from_info(&error_info)
+        if conn_params.outNewSession and self.warning is None:
+            self.warning = pool_impl.warning
+        if dpiConn_getServerVersion(self._handle, NULL, NULL,
+                                    &version_info) < 0:
             _raise_from_odpi()
         self.server_version = (
             version_info.versionNum,

src/oracledb/impl/thick/cursor.pyx

@@ -244,6 +244,7 @@ cdef class ThickCursorImpl(BaseCursorImpl):
         """
         cdef:
             uint32_t mode, num_query_cols
+            dpiErrorInfo error_info
             uint64_t rowcount = 0
             int status
         if self.bind_vars is not None:
@@ -254,10 +255,14 @@ cdef class ThickCursorImpl(BaseCursorImpl):
             mode = DPI_MODE_EXEC_DEFAULT
         with nogil:
             status = dpiStmt_execute(self._handle, mode, &num_query_cols)
-            if status == DPI_SUCCESS and not self._stmt_info.isPLSQL:
+            if status == DPI_SUCCESS:
+                dpiContext_getError(driver_context, &error_info)
+                if not self._stmt_info.isPLSQL:
                     status = dpiStmt_getRowCount(self._handle, &rowcount)
         if status < 0:
             _raise_from_odpi()
+        elif error_info.isWarning:
+            self.warning = _create_new_from_info(&error_info)
         self.rowcount = rowcount
         if num_query_cols > 0:
             self._perform_define(cursor, num_query_cols)
@@ -289,13 +294,14 @@ cdef class ThickCursorImpl(BaseCursorImpl):
         if num_execs_int > 0:
             with nogil:
                 status = dpiStmt_executeMany(self._handle, mode, num_execs_int)
-                if status < 0:
-                    dpiContext_getError(driver_context, &error_info)
+                dpiContext_getError(driver_context, &error_info)
                 if not self._stmt_info.isPLSQL:
                     dpiStmt_getRowCount(self._handle, &rowcount)
             self.rowcount = rowcount
             if status < 0:
                 _raise_from_info(&error_info)
+            elif error_info.isWarning:
+                self.warning = _create_new_from_info(&error_info)
             if self._stmt_info.isReturning or self._stmt_info.isPLSQL:
                 self._transform_binds()