Make the DB API Extension doc a simple italic line.

Author: anthony-tuininga

doc/src/_ext/dbapi_extension.py

@@ -0,0 +1,64 @@
+# -----------------------------------------------------------------------------
+# Copyright (c) 2025, Oracle and/or its affiliates.
+#
+# This software is dual-licensed to you under the Universal Permissive License
+# (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
+# 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
+# either license.
+#
+# If you elect to accept the software under the Apache License, Version 2.0,
+# the following applies:
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# dbapi_extension.py
+#
+# Used to document functionality that is an extension to the DB API definition.
+# -----------------------------------------------------------------------------
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+
+class DbApiExtension(Directive):
+    has_content = True
+
+    def run(self):
+        text = f"{self.prefix} {' '.join(self.content)}"
+        result = [nodes.emphasis(text=text), nodes.paragraph()]
+        return result
+
+
+class DbApiMethodExtension(DbApiExtension):
+    prefix = "This method is an extension to the DB API definition."
+
+
+class DbApiAttributeExtension(DbApiExtension):
+    prefix = "This attribute is an extension to the DB API definition."
+
+
+class DbApiConstantExtension(DbApiExtension):
+    prefix = "These constants are extensions to the DB API definition."
+
+
+class DbApiObjectExtension(DbApiExtension):
+    prefix = "This object is an extension to the DB API definition."
+
+
+def setup(app):
+    app.add_directive("dbapimethodextension", DbApiMethodExtension)
+    app.add_directive("dbapiattributeextension", DbApiAttributeExtension)
+    app.add_directive("dbapiconstantextension", DbApiConstantExtension)
+    app.add_directive("dbapiobjectextension", DbApiObjectExtension)

doc/src/api_manual/aq.rst

@@ -6,10 +6,6 @@ API: Advanced Queuing (AQ)
 
 See :ref:`aqusermanual` for more information about using AQ in python-oracledb.
 
-.. note::
-
-    All of these objects are extensions to the DB API.
-
 .. _queue:
 
 Queue Objects
@@ -18,6 +14,8 @@ Queue Objects
 These objects are created using the :meth:`Connection.queue()` method and are
 used to enqueue and dequeue messages.
 
+.. dbapiobjectextension::
+
 Queue Methods
 -------------
 
@@ -119,12 +117,10 @@ Queue Attributes
 Dequeue Options
 ===============
 
-.. note::
-
-    These objects are used to configure how messages are dequeued from queues.
-    An instance of this object is found in the attribute
-    :attr:`Queue.deqOptions`.
+These objects are used to configure how messages are dequeued from queues.
+An instance of this object is found in the attribute :attr:`Queue.deqOptions`.
 
+.. dbapiobjectextension::
 
 .. attribute:: DeqOptions.condition
 
@@ -214,12 +210,10 @@ Dequeue Options
 Enqueue Options
 ===============
 
-.. note::
-
-    These objects are used to configure how messages are enqueued into queues.
-    An instance of this object is found in the attribute
-    :attr:`Queue.enqOptions`.
+These objects are used to configure how messages are enqueued into queues. An
+instance of this object is found in the attribute :attr:`Queue.enqOptions`.
 
+.. dbapiobjectextension::
 
 .. attribute:: EnqOptions.deliverymode
 
@@ -249,14 +243,13 @@ Enqueue Options
 Message Properties
 ==================
 
-.. note::
-
-    These objects are used to identify the properties of messages that are
-    enqueued and dequeued in queues. They are created by the method
-    :meth:`Connection.msgproperties()`.  They are used by the methods
-    :meth:`Queue.enqone()` and :meth:`Queue.enqmany()` and
-    returned by the methods :meth:`Queue.deqone()` and :meth:`Queue.deqmany()`.
+These objects are used to identify the properties of messages that are enqueued
+and dequeued in queues. They are created by the method
+:meth:`Connection.msgproperties()`.  They are used by the methods
+:meth:`Queue.enqone()` and :meth:`Queue.enqmany()` and returned by the methods
+:meth:`Queue.deqone()` and :meth:`Queue.deqmany()`.
 
+.. dbapiobjectextension::
 
 .. attribute:: MessageProperties.attempts
 

doc/src/api_manual/async_connection.rst

@@ -8,8 +8,9 @@ An AsyncConnection object can be created with :meth:`oracledb.connect_async()`
 or with :meth:`AsyncConnectionPool.acquire()`. AsyncConnections support use of
 concurrent programming with `asyncio <https://docs.python.org/3/library/
 asyncio.html>`__. Unless explicitly noted as synchronous, the AsyncConnection
-methods should be used with ``await``. This object is an extension to the DB
-API.
+methods should be used with ``await``.
+
+.. dbapiobjectextension::
 
 .. versionadded:: 2.0.0
 
@@ -647,20 +648,18 @@ AsyncConnection Attributes
 
     This read-only attribute specifies the session serial number associated with
     the connection. It is the same value returned by the SQL
-    ``SELECT SERIAL# FROM V$SESSION``. It is available only in python-oracledb
-    Thin mode.
+    ``SELECT SERIAL# FROM V$SESSION``.
 
-    .. versionadded:: 2.5.0
+    It is available only in python-oracledb Thin mode.
 
-    .. note::
+    For applications using :ref:`drcp`, the ``serial_num`` attribute may not
+    contain the current session state until a round-trip is made to the
+    database after acquiring a session.  It is recommended to not use this
+    attribute if your application uses DRCP but may not perform a round-trip.
 
-        This attribute is an extension to the DB API definition.
+    .. dbapiattributeextension::
 
-        For applications using :ref:`drcp`, the ``serial_num`` attribute may
-        not contain the current session state until a round-trip is made to the
-        database after acquiring a session.  It is recommended to not use this
-        attribute if your application uses DRCP but may not perform a
-        round-trip.
+    .. versionadded:: 2.5.0
 
 .. attribute:: AsyncConnection.service_name
 
@@ -672,20 +671,19 @@ AsyncConnection Attributes
 
     This read-only attribute specifies the session identifier associated with
     the connection. It is the same value returned by the SQL
-    ``SELECT SID FROM V$SESSION``. It is available only in python-oracledb
-    Thin mode.
+    ``SELECT SID FROM V$SESSION``.
 
-    .. versionadded:: 2.5.0
+    It is available only in python-oracledb Thin mode.
 
-    .. note::
+    For applications using :ref:`drcp`, the ``session_id`` attribute may
+    not contain the current session state until a round-trip is made to the
+    database after acquiring a session.  It is recommended to not use this
+    attribute if your application uses DRCP but may not perform a
+    round-trip.
 
-        This attribute is an extension to the DB API definition.
+    .. dbapiattributeextension::
 
-        For applications using :ref:`drcp`, the ``session_id`` attribute may
-        not contain the current session state until a round-trip is made to the
-        database after acquiring a session.  It is recommended to not use this
-        attribute if your application uses DRCP but may not perform a
-        round-trip.
+    .. versionadded:: 2.5.0
 
 .. attribute:: AsyncConnection.stmtcachesize
 

doc/src/api_manual/async_connection_pool.rst

@@ -5,8 +5,9 @@ API: AsyncConnectionPool Objects
 ********************************
 
 An AsyncConnectionPool object can be created with
-:meth:`oracledb.create_pool_async()`. This object is an extension to the DB
-API.
+:meth:`oracledb.create_pool_async()`.
+
+.. dbapiobjectextension::
 
 .. versionadded:: 2.0.0
 

doc/src/api_manual/async_cursor.rst

@@ -6,7 +6,9 @@ API: AsyncCursor Objects
 
 An AsyncCursor object can be created with :meth:`AsyncConnection.cursor()`.
 Unless explicitly noted as synchronous, the AsyncCursor methods should be used
-with ``await``. This object is an extension to the DB API.
+with ``await``.
+
+.. dbapiobjectextension::
 
 .. versionadded:: 2.0.0
 
@@ -340,11 +342,6 @@ AsyncCursor Methods
     An error is raised if the mode is *relative* or *absolute* and the scroll
     operation would position the cursor outside of the result set.
 
-    .. note::
-
-        This method is an extension to the DB API definition but it is
-        mentioned in PEP 249 as an optional extension.
-
 .. method:: AsyncCursor.setoutputsize(size, [column])
 
     This method does nothing and is retained solely for compatibility with the

doc/src/api_manual/async_lob.rst

@@ -6,7 +6,9 @@ API: AsyncLOB Objects
 
 An AsyncLOB object can be created with :meth:`AsyncConnection.createlob()`.
 Also, this object is returned whenever Oracle :data:`CLOB`, :data:`BLOB` and
-:data:`BFILE` columns are fetched. This object is an extension to the DB API.
+:data:`BFILE` columns are fetched.
+
+.. dbapiobjectextension::
 
 See :ref:`lobdata` for more information about using LOBs.
 

doc/src/api_manual/connect_params.rst

@@ -4,12 +4,10 @@
 API: ConnectParams Objects
 **************************
 
-.. note::
+The ConnectParams objects are created by :meth:`oracledb.ConnectParams()`.
+See :ref:`usingconnparams` for more information.
 
-    This object is an extension to the DB API.
-
-These objects are created by :meth:`oracledb.ConnectParams()`.  See
-:ref:`usingconnparams` for more information.
+.. dbapiobjectextension::
 
 .. _connparamsmeth: