Skip to content

Commit 41b60b7

Browse files
anthony-tuiningaanthony-tuininga
committed
Make the DB API Extension doc a simple italic line.
1 parent ce08518 commit 41b60b7

19 files changed

+402
-489
lines changed

‎doc/src/_ext/dbapi_extension.py

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# -----------------------------------------------------------------------------
2+
# Copyright (c) 2025, Oracle and/or its affiliates.
3+
#
4+
# This software is dual-licensed to you under the Universal Permissive License
5+
# (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
6+
# 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
7+
# either license.
8+
#
9+
# If you elect to accept the software under the Apache License, Version 2.0,
10+
# the following applies:
11+
#
12+
# Licensed under the Apache License, Version 2.0 (the "License");
13+
# you may not use this file except in compliance with the License.
14+
# You may obtain a copy of the License at
15+
#
16+
# https://www.apache.org/licenses/LICENSE-2.0
17+
#
18+
# Unless required by applicable law or agreed to in writing, software
19+
# distributed under the License is distributed on an "AS IS" BASIS,
20+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21+
# See the License for the specific language governing permissions and
22+
# limitations under the License.
23+
# -----------------------------------------------------------------------------
24+
25+
# -----------------------------------------------------------------------------
26+
# dbapi_extension.py
27+
#
28+
# Used to document functionality that is an extension to the DB API definition.
29+
# -----------------------------------------------------------------------------
30+
31+
from docutils import nodes
32+
from docutils.parsers.rst import Directive
33+
34+
35+
class DbApiExtension(Directive):
36+
has_content = True
37+
38+
def run(self):
39+
text = f"{self.prefix} {' '.join(self.content)}"
40+
result = [nodes.emphasis(text=text), nodes.paragraph()]
41+
return result
42+
43+
44+
class DbApiMethodExtension(DbApiExtension):
45+
prefix = "This method is an extension to the DB API definition."
46+
47+
48+
class DbApiAttributeExtension(DbApiExtension):
49+
prefix = "This attribute is an extension to the DB API definition."
50+
51+
52+
class DbApiConstantExtension(DbApiExtension):
53+
prefix = "These constants are extensions to the DB API definition."
54+
55+
56+
class DbApiObjectExtension(DbApiExtension):
57+
prefix = "This object is an extension to the DB API definition."
58+
59+
60+
def setup(app):
61+
app.add_directive("dbapimethodextension", DbApiMethodExtension)
62+
app.add_directive("dbapiattributeextension", DbApiAttributeExtension)
63+
app.add_directive("dbapiconstantextension", DbApiConstantExtension)
64+
app.add_directive("dbapiobjectextension", DbApiObjectExtension)

‎doc/src/api_manual/aq.rst

Lines changed: 14 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,6 @@ API: Advanced Queuing (AQ)
66

77
See :ref:`aqusermanual` for more information about using AQ in python-oracledb.
88

9-
.. note::
10-
11-
All of these objects are extensions to the DB API.
12-
139
.. _queue:
1410

1511
Queue Objects
@@ -18,6 +14,8 @@ Queue Objects
1814
These objects are created using the :meth:`Connection.queue()` method and are
1915
used to enqueue and dequeue messages.
2016

17+
.. dbapiobjectextension::
18+
2119
Queue Methods
2220
-------------
2321

@@ -119,12 +117,10 @@ Queue Attributes
119117
Dequeue Options
120118
===============
121119

122-
.. note::
123-
124-
These objects are used to configure how messages are dequeued from queues.
125-
An instance of this object is found in the attribute
126-
:attr:`Queue.deqOptions`.
120+
These objects are used to configure how messages are dequeued from queues.
121+
An instance of this object is found in the attribute :attr:`Queue.deqOptions`.
127122

123+
.. dbapiobjectextension::
128124

129125
.. attribute:: DeqOptions.condition
130126

@@ -214,12 +210,10 @@ Dequeue Options
214210
Enqueue Options
215211
===============
216212

217-
.. note::
218-
219-
These objects are used to configure how messages are enqueued into queues.
220-
An instance of this object is found in the attribute
221-
:attr:`Queue.enqOptions`.
213+
These objects are used to configure how messages are enqueued into queues. An
214+
instance of this object is found in the attribute :attr:`Queue.enqOptions`.
222215

216+
.. dbapiobjectextension::
223217

224218
.. attribute:: EnqOptions.deliverymode
225219

@@ -249,14 +243,13 @@ Enqueue Options
249243
Message Properties
250244
==================
251245

252-
.. note::
253-
254-
These objects are used to identify the properties of messages that are
255-
enqueued and dequeued in queues. They are created by the method
256-
:meth:`Connection.msgproperties()`. They are used by the methods
257-
:meth:`Queue.enqone()` and :meth:`Queue.enqmany()` and
258-
returned by the methods :meth:`Queue.deqone()` and :meth:`Queue.deqmany()`.
246+
These objects are used to identify the properties of messages that are enqueued
247+
and dequeued in queues. They are created by the method
248+
:meth:`Connection.msgproperties()`. They are used by the methods
249+
:meth:`Queue.enqone()` and :meth:`Queue.enqmany()` and returned by the methods
250+
:meth:`Queue.deqone()` and :meth:`Queue.deqmany()`.
259251

252+
.. dbapiobjectextension::
260253

261254
.. attribute:: MessageProperties.attempts
262255

‎doc/src/api_manual/async_connection.rst

Lines changed: 20 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,9 @@ An AsyncConnection object can be created with :meth:`oracledb.connect_async()`
88
or with :meth:`AsyncConnectionPool.acquire()`. AsyncConnections support use of
99
concurrent programming with `asyncio <https://docs.python.org/3/library/
1010
asyncio.html>`__. Unless explicitly noted as synchronous, the AsyncConnection
11-
methods should be used with ``await``. This object is an extension to the DB
12-
API.
11+
methods should be used with ``await``.
12+
13+
.. dbapiobjectextension::
1314

1415
.. versionadded:: 2.0.0
1516

@@ -647,20 +648,18 @@ AsyncConnection Attributes
647648

648649
This read-only attribute specifies the session serial number associated with
649650
the connection. It is the same value returned by the SQL
650-
``SELECT SERIAL# FROM V$SESSION``. It is available only in python-oracledb
651-
Thin mode.
651+
``SELECT SERIAL# FROM V$SESSION``.
652652

653-
.. versionadded:: 2.5.0
653+
It is available only in python-oracledb Thin mode.
654654

655-
.. note::
655+
For applications using :ref:`drcp`, the ``serial_num`` attribute may not
656+
contain the current session state until a round-trip is made to the
657+
database after acquiring a session. It is recommended to not use this
658+
attribute if your application uses DRCP but may not perform a round-trip.
656659

657-
This attribute is an extension to the DB API definition.
660+
.. dbapiattributeextension::
658661

659-
For applications using :ref:`drcp`, the ``serial_num`` attribute may
660-
not contain the current session state until a round-trip is made to the
661-
database after acquiring a session. It is recommended to not use this
662-
attribute if your application uses DRCP but may not perform a
663-
round-trip.
662+
.. versionadded:: 2.5.0
664663

665664
.. attribute:: AsyncConnection.service_name
666665

@@ -672,20 +671,19 @@ AsyncConnection Attributes
672671

673672
This read-only attribute specifies the session identifier associated with
674673
the connection. It is the same value returned by the SQL
675-
``SELECT SID FROM V$SESSION``. It is available only in python-oracledb
676-
Thin mode.
674+
``SELECT SID FROM V$SESSION``.
677675

678-
.. versionadded:: 2.5.0
676+
It is available only in python-oracledb Thin mode.
679677

680-
.. note::
678+
For applications using :ref:`drcp`, the ``session_id`` attribute may
679+
not contain the current session state until a round-trip is made to the
680+
database after acquiring a session. It is recommended to not use this
681+
attribute if your application uses DRCP but may not perform a
682+
round-trip.
681683

682-
This attribute is an extension to the DB API definition.
684+
.. dbapiattributeextension::
683685

684-
For applications using :ref:`drcp`, the ``session_id`` attribute may
685-
not contain the current session state until a round-trip is made to the
686-
database after acquiring a session. It is recommended to not use this
687-
attribute if your application uses DRCP but may not perform a
688-
round-trip.
686+
.. versionadded:: 2.5.0
689687

690688
.. attribute:: AsyncConnection.stmtcachesize
691689

‎doc/src/api_manual/async_connection_pool.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,9 @@ API: AsyncConnectionPool Objects
55
********************************
66

77
An AsyncConnectionPool object can be created with
8-
:meth:`oracledb.create_pool_async()`. This object is an extension to the DB
9-
API.
8+
:meth:`oracledb.create_pool_async()`.
9+
10+
.. dbapiobjectextension::
1011

1112
.. versionadded:: 2.0.0
1213

‎doc/src/api_manual/async_cursor.rst

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@ API: AsyncCursor Objects
66

77
An AsyncCursor object can be created with :meth:`AsyncConnection.cursor()`.
88
Unless explicitly noted as synchronous, the AsyncCursor methods should be used
9-
with ``await``. This object is an extension to the DB API.
9+
with ``await``.
10+
11+
.. dbapiobjectextension::
1012

1113
.. versionadded:: 2.0.0
1214

@@ -340,11 +342,6 @@ AsyncCursor Methods
340342
An error is raised if the mode is *relative* or *absolute* and the scroll
341343
operation would position the cursor outside of the result set.
342344

343-
.. note::
344-
345-
This method is an extension to the DB API definition but it is
346-
mentioned in PEP 249 as an optional extension.
347-
348345
.. method:: AsyncCursor.setoutputsize(size, [column])
349346

350347
This method does nothing and is retained solely for compatibility with the

‎doc/src/api_manual/async_lob.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@ API: AsyncLOB Objects
66

77
An AsyncLOB object can be created with :meth:`AsyncConnection.createlob()`.
88
Also, this object is returned whenever Oracle :data:`CLOB`, :data:`BLOB` and
9-
:data:`BFILE` columns are fetched. This object is an extension to the DB API.
9+
:data:`BFILE` columns are fetched.
10+
11+
.. dbapiobjectextension::
1012

1113
See :ref:`lobdata` for more information about using LOBs.
1214

‎doc/src/api_manual/connect_params.rst

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,10 @@
44
API: ConnectParams Objects
55
**************************
66

7-
.. note::
7+
The ConnectParams objects are created by :meth:`oracledb.ConnectParams()`.
8+
See :ref:`usingconnparams` for more information.
89

9-
This object is an extension to the DB API.
10-
11-
These objects are created by :meth:`oracledb.ConnectParams()`. See
12-
:ref:`usingconnparams` for more information.
10+
.. dbapiobjectextension::
1311

1412
.. _connparamsmeth:
1513

0 commit comments

Comments
 (0)