Skip to content

Commit bc48256

Browse files
anthony-tuiningaanthony-tuininga
committed
Documentation improvements.
1 parent 72bb4e4 commit bc48256

File tree

12 files changed

+171
-97
lines changed

12 files changed

+171
-97
lines changed

‎doc/src/api_manual/connect_param.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ ConnectParams Methods
5151
externalauth=None, mode=None, disable_oob=None, stmtcachesize=None, \
5252
edition=None, tag=None, matchanytag=None, config_dir=None, \
5353
appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \
54-
connection_id_prefix=None, handle=None)
54+
connection_id_prefix=None, ssl_context=None, handle=None)
5555

5656
Sets the default values for one or more of the parameters of an empty
5757
ConnectParams object. A default will be overriden when a connection string

‎doc/src/api_manual/cursor.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -581,6 +581,9 @@ Cursor Attributes
581581
The attribute is only used for tuning row fetches from the database. It
582582
does not affect data inserts.
583583

584+
Queries that return LOBs and similar types will never prefetch rows, so the
585+
``prefetchrows`` value is ignored in those cases.
586+
584587
See :ref:`Tuning Fetch Performance <tuningfetch>` for more information.
585588

586589
.. note::

‎doc/src/api_manual/defaults.rst

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,10 +57,11 @@ Defaults Attributes
5757

5858
.. attribute:: defaults.fetch_lobs
5959

60-
When the value of this attribute is True, then queries to LOB columns return
61-
LOB locators. When the value of this attribute is False, then strings or bytes
62-
are fetched. If LOBs are larger than 1 GB, then this attribute should be set to
63-
True and the LOBs should be streamed. See :ref:`lobdata`.
60+
When the value of this attribute is True, then queries to LOB columns
61+
return LOB locators. When the value of this attribute is False, then CLOBs
62+
and NCLOBs are fetched as strings, and BLOBs are fetched as bytes. If LOBs
63+
are larger than 1 GB, then this attribute should be set to True and the
64+
LOBs should be streamed. See :ref:`lobdata`.
6465

6566
An output type handler such as the one previously required in cx_Oracle (see
6667
`return_lobs_as_strings.py <https://github.com/oracle/python-cx_Oracle/blob/main/samples/

‎doc/src/api_manual/module.rst

Lines changed: 51 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ Oracledb Methods
4848
edition=None, tag=None, matchanytag=False, \
4949
config_dir=oracledb.defaults.config_dir, appcontext=[], \
5050
shardingkey=[], supershardingkey=[], debug_jdwp=None, \
51-
connection_id_prefix=None, handle=0)
51+
connection_id_prefix=None, ssl_context=None, handle=0)
5252

5353
Constructor for creating a connection to the database. Returns a
5454
:ref:`Connection Object <connobj>`. All parameters are optional and can be
@@ -295,13 +295,25 @@ Oracledb Methods
295295
ctx=dblatest&id=GUID-B0FC69F9-2EBC-44E8-ACB2-62FBA14ABD5C>`__. This value
296296
is only used in the python-oracledb Thin mode.
297297

298+
The ``ssl_context`` parameter is expected to be an `SSLContext object
299+
<https://docs.python.org/3/library/ssl.html#ssl-contexts>`__ which is used
300+
for connecting to the database using TLS. This SSL context will be
301+
modified to include the private key or any certificates found in a
302+
separately supplied wallet. This parameter should only be specified if
303+
the default SSLContext object cannot be used. This value is only used in
304+
the python-oracledb Thin mode.
305+
298306
If the ``handle`` parameter is specified, it must be of type OCISvcCtx\*
299307
and is only of use when embedding Python in an application (like
300308
PowerBuilder) which has already made the connection. The connection thus
301309
created should *never* be used after the source handle has been closed or
302310
destroyed. This value is only used in the python-oracledb Thick mode. It
303311
should be used with extreme caution. The default value is 0.
304312

313+
.. versionchanged:: 2.0.0
314+
315+
The ``ssl_context`` parameter was added.
316+
305317
.. function:: ConnectParams(user=None, proxy_user=None, password=None, \
306318
newpassword=None, wallet_password=None, access_token=None, host=None, \
307319
port=1521, protocol="tcp", https_proxy=None, https_proxy_port=0, \
@@ -314,7 +326,7 @@ Oracledb Methods
314326
edition=None, tag=None, matchanytag=False, \
315327
config_dir=oracledb.defaults.config_dir, appcontext=[], \
316328
shardingkey=[], supershardingkey=[], debug_jdwp=None, \
317-
connection_id_prefix=None, handle=0)
329+
connection_id_prefix=None, ssl_context=None, handle=0)
318330

319331
Contains all the parameters that can be used to establish a connection to
320332
the database.
@@ -526,11 +538,22 @@ Oracledb Methods
526538
ctx=dblatest&id=GUID-B0FC69F9-2EBC-44E8-ACB2-62FBA14ABD5C>`__. This value
527539
is only used in the python-oracledb Thin mode.
528540

541+
The ``ssl_context`` parameter is expected to be an `SSLContext object
542+
<https://docs.python.org/3/library/ssl.html#ssl-contexts>`__ which is used
543+
for connecting to the database using TLS. This SSL context will be
544+
modified to include the private key or any certificates found in a
545+
separately supplied wallet. This parameter should only be specified if
546+
the default SSLContext object cannot be used. This value is only used in
547+
the python-oracledb Thin mode.
548+
529549
The ``handle`` parameter is expected to be an integer which represents a
530550
pointer to a valid service context handle. This value is only used in the
531551
python-oracledb Thick mode. It should be used with extreme caution. The
532552
default value is 0.
533553

554+
.. versionchanged:: 2.0.0
555+
556+
The ``ssl_context`` parameter was added.
534557

535558
.. function:: create_pool(dsn=None, pool_class=oracledb.ConnectionPool, \
536559
params=None, min=1, max=2, increment=1, \
@@ -550,7 +573,7 @@ Oracledb Methods
550573
edition=None, tag=None, matchanytag=False, \
551574
config_dir=oracledb.defaults.config_dir, appcontext=[], \
552575
shardingkey=[], supershardingkey=[], debug_jdwp=None, \
553-
connection_id_prefix=None, handle=0)
576+
connection_id_prefix=None, ssl_context=None, handle=0)
554577

555578
Creates a connection pool with the supplied parameters and returns the
556579
:ref:`ConnectionPool object <connpool>` for the pool. See :ref:`Connection
@@ -844,13 +867,25 @@ Oracledb Methods
844867
ctx=dblatest&id=GUID-B0FC69F9-2EBC-44E8-ACB2-62FBA14ABD5C>`__. This value
845868
is only used in the python-oracledb Thin mode.
846869

870+
The ``ssl_context`` parameter is expected to be an `SSLContext object
871+
<https://docs.python.org/3/library/ssl.html#ssl-contexts>`__ which is used
872+
for connecting to the database using TLS. This SSL context will be
873+
modified to include the private key or any certificates found in a
874+
separately supplied wallet. This parameter should only be specified if
875+
the default SSLContext object cannot be used. This value is only used in
876+
the python-oracledb Thin mode.
877+
847878
If the ``handle`` parameter is specified, it must be of type OCISvcCtx\*
848879
and is only of use when embedding Python in an application (like
849880
PowerBuilder) which has already made the connection. The connection thus
850881
created should *never* be used after the source handle has been closed or
851882
destroyed. This value is only used in the python-oracledb Thick mode. It
852883
should be used with extreme caution. The deault value is 0.
853884

885+
.. versionchanged:: 2.0.0
886+
887+
The ``ssl_context`` parameter was added.
888+
854889
In the python-oracledb Thick mode, connection pooling is handled by
855890
Oracle's `Session pooling <https://www.oracle.com/pls/topic/lookup?
856891
ctx=dblatest&id=GUID-F9662FFB-EAEF-495C-96FC-49C6D1D9625C>`__ technology.
@@ -979,7 +1014,7 @@ Oracledb Methods
9791014
edition=None, tag=None, matchanytag=False, \
9801015
config_dir=oracledb.defaults.config_dir, appcontext=[], \
9811016
shardingkey=[], supershardingkey=[], debug_jdwp=None, \
982-
connection_id_prefix=None, handle=0)
1017+
connection_id_prefix=None, ssl_context=None, handle=0)
9831018

9841019
Creates and returns a :ref:`PoolParams Object <poolparam>`. The object
9851020
can be passed to :meth:`oracledb.create_pool()`.
@@ -1243,11 +1278,23 @@ Oracledb Methods
12431278
ctx=dblatest&id=GUID-B0FC69F9-2EBC-44E8-ACB2-62FBA14ABD5C>`__. This value
12441279
is only used in the python-oracledb Thin mode.
12451280

1281+
The ``ssl_context`` parameter is expected to be an `SSLContext object
1282+
<https://docs.python.org/3/library/ssl.html#ssl-contexts>`__ which is used
1283+
for connecting to the database using TLS. This SSL context will be
1284+
modified to include the private key or any certificates found in a
1285+
separately supplied wallet. This parameter should only be specified if
1286+
the default SSLContext object cannot be used. This value is only used in
1287+
the python-oracledb Thin mode.
1288+
12461289
The ``handle`` parameter is expected to be an integer which represents a
12471290
pointer to a valid service context handle. This value is only used in the
12481291
python-oracledb Thick mode. It should be used with extreme caution. The
12491292
default value is 0.
12501293

1294+
.. versionchanged:: 2.0.0
1295+
1296+
The ``ssl_context`` parameter was added.
1297+
12511298
.. function:: Time(hour, minute, second)
12521299

12531300
Constructs an object holding a time value.

‎doc/src/api_manual/pool_params.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ PoolParams Methods
4646
externalauth=None, mode=None, disable_oob=None, stmtcachesize=None, \
4747
edition=None, tag=None, matchanytag=None, config_dir=None, \
4848
appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \
49-
connection_id_prefix=None, handle=None)
49+
connection_id_prefix=None, ssl_context=None, handle=None)
5050

5151
Sets one or more of the parameters.
5252

‎doc/src/user_guide/appendix_a.rst

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -214,10 +214,10 @@ see :ref:`driverdiff` and :ref:`compatibility`.
214214
- No - All NLS environment variables are ignored. Use Python globalization support instead
215215
- Yes - NLS environment variables are respected except character set in NLS_LANG
216216
- Yes - NLS environment variables are respected except character set in NLS_LANG
217-
* - Row prefetching on first query execute.(see :attr:`prefetchrows`)
218-
- Yes
219-
- Yes
220-
- Yes
217+
* - Row prefetching on first query execute (see :attr:`prefetchrows`)
218+
- Yes - unless the row contains LOBs or similar types
219+
- Yes - unless the row contains LOBs or similar types
220+
- Yes - unless the row contains LOBs or similar types
221221
* - Array fetching for queries (see :attr:`arraysize`)
222222
- Yes
223223
- Yes
@@ -318,10 +318,10 @@ see :ref:`driverdiff` and :ref:`compatibility`.
318318
- Yes
319319
- Yes
320320
- Yes
321-
* - LOB prefetching
322-
- No
323-
- No - does have LOB length prefetch
324-
- No - does have LOB length prefetch
321+
* - LOB length prefetching
322+
- Yes
323+
- Yes
324+
- Yes
325325
* - LOB locator operations such as trim
326326
- Yes
327327
- Yes

0 commit comments

Comments
 (0)