Skip to content

Commit cc841fa

Browse files
anthony-tuiningaanthony-tuininga
committed
Added user guide documentation.
1 parent 10d4ad8 commit cc841fa

34 files changed

+5005
-278
lines changed

‎doc/src/aq.rst renamed to ‎doc/src/api_manual/aq.rst

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
.. _aq:
22

3-
****************
4-
Advanced Queuing
5-
****************
3+
*********************
4+
Advanced Queuing (AQ)
5+
*********************
6+
7+
See :ref:`aqusermanual` for more information about using AQ in cx_Oracle.
68

79
.. note::
810

@@ -307,4 +309,3 @@ Message Properties
307309
the dequeue. It will be one of the values :data:`~cx_Oracle.MSG_WAITING`,
308310
:data:`~cx_Oracle.MSG_READY`, :data:`~cx_Oracle.MSG_PROCESSED` or
309311
:data:`~cx_Oracle.MSG_EXPIRED`.
310-

‎doc/src/connection.rst renamed to ‎doc/src/api_manual/connection.rst

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -690,4 +690,3 @@ Connection Object
690690
If you connect to Oracle Database 18 or higher with client libraries
691691
12.2 or lower that you will only receive the base version (such as
692692
18.0.0.0.0) instead of the full version (18.3.0.0.0).
693-

‎doc/src/cursor.rst renamed to ‎doc/src/api_manual/cursor.rst

Lines changed: 28 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,8 @@ Cursor Object
9696
positional parameters. The result of the call is the return value of the
9797
function.
9898

99+
See :ref:`plsqlfunc` for an example.
100+
99101
.. note::
100102

101103
The DB API definition does not define this method.
@@ -116,6 +118,8 @@ Cursor Object
116118
possibly new values. Keyword parameters will be included after the
117119
positional parameters and are not returned as part of the output sequence.
118120

121+
See :ref:`plsqlproc` for an example.
122+
119123
.. note::
120124

121125
The DB API definition does not allow for keyword parameters.
@@ -152,14 +156,16 @@ Cursor Object
152156

153157
.. method:: Cursor.execute(statement, [parameters], \*\*keywordParameters)
154158

155-
Execute a statement against the database. Parameters may be passed as a
156-
dictionary or sequence or as keyword parameters. If the parameters are a
157-
dictionary, the values will be bound by name and if the parameters are a
158-
sequence the values will be bound by position. Note that if the values are
159-
bound by position, the order of the variables is from left to right as they
160-
are encountered in the statement and SQL statements are processed
161-
differently than PL/SQL statements. For this reason, it is generally
162-
recommended to bind parameters by name instead of by position.
159+
Execute a statement against the database. See :ref:`sqlexecution`.
160+
161+
Parameters may be passed as a dictionary or sequence or as keyword
162+
parameters. If the parameters are a dictionary, the values will be bound by
163+
name and if the parameters are a sequence the values will be bound by
164+
position. Note that if the values are bound by position, the order of the
165+
variables is from left to right as they are encountered in the statement
166+
and SQL statements are processed differently than PL/SQL statements. For
167+
this reason, it is generally recommended to bind parameters by name instead
168+
of by position.
163169

164170
Parameters passed as a dictionary are name and value pairs. The name maps
165171
to the bind variable name used by the statement and the value maps to the
@@ -193,12 +199,14 @@ Cursor Object
193199

194200
Prepare a statement for execution against a database and then execute it
195201
against all parameter mappings or sequences found in the sequence
196-
parameters. The statement is managed in the same way as the
197-
:meth:`~Cursor.execute()` method manages it. If the size of the buffers
198-
allocated for any of the parameters exceeds 2 GB, you will receive the
199-
error "DPI-1015: array size of <n> is too large", where <n> varies with the
200-
size of each element being allocated in the buffer. If you receive this
201-
error, decrease the number of elements in the sequence parameters.
202+
parameters. See :ref:`batchstmnt`.
203+
204+
The statement is managed in the same way as the :meth:`~Cursor.execute()`
205+
method manages it. If the size of the buffers allocated for any of the
206+
parameters exceeds 2 GB, you will receive the error "DPI-1015: array size
207+
of <n> is too large", where <n> varies with the size of each element being
208+
allocated in the buffer. If you receive this error, decrease the number of
209+
elements in the sequence parameters.
202210

203211
If there are no parameters, or parameters have previously been bound, the
204212
number of iterations can be specified as an integer instead of needing to
@@ -252,6 +260,8 @@ Cursor Object
252260
An exception is raised if the previous call to :meth:`~Cursor.execute()`
253261
did not produce any result set or no call was issued yet.
254262

263+
See :ref:`fetching` for an example.
264+
255265

256266
.. method:: Cursor.fetchmany([numRows=cursor.arraysize])
257267

@@ -267,6 +277,7 @@ Cursor Object
267277
An exception is raised if the previous call to :meth:`~Cursor.execute()`
268278
did not produce any result set or no call was issued yet.
269279

280+
See :ref:`fetching` for an example.
270281

271282
.. method:: Cursor.fetchone()
272283

@@ -276,6 +287,7 @@ Cursor Object
276287
An exception is raised if the previous call to :meth:`~Cursor.execute()`
277288
did not produce any result set or no call was issued yet.
278289

290+
See :ref:`fetching` for an example.
279291

280292
.. method:: Cursor.fetchraw([numRows=cursor.arraysize])
281293

@@ -387,6 +399,8 @@ Cursor Object
387399
variable object will be created. If this attribute is None, the value of
388400
the attribute with the same name on the connection is used instead.
389401

402+
See :ref:`outputtypehandlers`.
403+
390404
.. note::
391405

392406
This attribute is an extension to the DB API definition.
@@ -556,4 +570,3 @@ Cursor Object
556570
.. note::
557571

558572
The DB API definition does not define this method.
559-

‎doc/src/lob.rst renamed to ‎doc/src/api_manual/lob.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
LOB Objects
55
***********
66

7+
See :ref:`lobdata` for more information about using LOBs.
8+
79
.. note::
810

911
This object is an extension the DB API. It is returned whenever Oracle
@@ -86,4 +88,3 @@ LOB Objects
8688
offset will have to be chosen carefully to avoid splitting a character.
8789
Note that if you want to make the LOB value smaller, you must use the
8890
:meth:`~LOB.trim()` function.
89-

‎doc/src/module.rst renamed to ‎doc/src/api_manual/module.rst

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -36,27 +36,29 @@ Module Interface
3636
This method is an extension to the DB API definition.
3737

3838

39-
.. function:: Connection(user=None, password=None, dsn=None, \
39+
.. function:: connect(user=None, password=None, dsn=None, mode=cx_Oracle.DEFAULT_AUTH, \
40+
handle=0, pool=None, threaded=False, events=False, cclass=None, \
41+
purity=cx_Oracle.ATTR_PURITY_DEFAULT, newpassword=None, \
42+
encoding=None, nencoding=None, edition=None, appcontext=[], tag=None, \
43+
matchanytag=None, shardingkey=[], supershardingkey=[])
44+
Connection(user=None, password=None, dsn=None, \
4045
mode=cx_Oracle.DEFAULT_AUTH, handle=0, pool=None, threaded=False, \
4146
events=False, cclass=None, purity=cx_Oracle.ATTR_PURITY_DEFAULT, \
4247
newpassword=None, encoding=None, nencoding=None, edition=None, \
4348
appcontext=[], tag=None, matchanytag=False, shardingkey=[], \
4449
supershardingkey=[])
45-
connect(user=None, password=None, dsn=None, mode=cx_Oracle.DEFAULT_AUTH, \
46-
handle=0, pool=None, threaded=False, events=False, cclass=None, \
47-
purity=cx_Oracle.ATTR_PURITY_DEFAULT, newpassword=None, \
48-
encoding=None, nencoding=None, edition=None, appcontext=[], tag=None, \
49-
matchanytag=None, shardingkey=[], supershardingkey=[])
5050

5151
Constructor for creating a connection to the database. Return a
5252
:ref:`connection object <connobj>`. All parameters are optional and can be
53-
specified as keyword parameters.
53+
specified as keyword parameters. See :ref:`connhandling` information about
54+
connections.
5455

5556
The dsn (data source name) is the TNS entry (from the Oracle names server
5657
or tnsnames.ora file) or is a string like the one returned from
5758
:meth:`~cx_Oracle.makedsn()`. If only one parameter is passed, a connect
5859
string is assumed which is to be of the format ``user/password@dsn``, the
59-
same format accepted by Oracle applications such as SQL\*Plus.
60+
same format accepted by Oracle applications such as SQL\*Plus. See
61+
:ref:`connstr` for more information.
6062

6163
If the mode is specified, it must be one of the
6264
:ref:`connection authorization modes<connection-authorization-modes>`
@@ -140,7 +142,7 @@ Module Interface
140142

141143
.. function:: Cursor(connection)
142144

143-
Constructor for creating a cursor. Return a new
145+
Constructor for creating a cursor. Return a new
144146
:ref:`cursor object <cursorobj>` using the connection.
145147

146148
.. note::
@@ -187,6 +189,8 @@ Module Interface
187189
like `Application Continuity <https://www.oracle.com/pls/topic/lookup?
188190
ctx=dblatest&id=GUID-A8DD9422-2F82-42A9-9555-134296416E8F>`__.
189191

192+
See :ref:`connpool` for information on connection pooling.
193+
190194
Session pooling creates a pool of available connections to the
191195
database, allowing applications to acquire a connection very quickly.
192196
It is of primary use in a server where connections are requested
@@ -747,6 +751,8 @@ for subscriptions created by the :meth:`Connection.subscribe()` method.
747751
being started up.
748752

749753

754+
.. _cqn-operation-codes:
755+
750756
Operation Codes
751757
---------------
752758

@@ -894,6 +900,8 @@ method.
894900
events.
895901

896902

903+
.. _subscr-namespaces:
904+
897905
Subscription Namespaces
898906
-----------------------
899907

@@ -912,6 +920,8 @@ method.
912920
change notification messages are to be sent. This is the default value.
913921

914922

923+
.. _subscr-protocols:
924+
915925
Subscription Protocols
916926
----------------------
917927

@@ -947,6 +957,8 @@ values for the protocol parameter of the :meth:`Connection.subscribe()` method.
947957
supported.
948958

949959

960+
.. _subscr-qos:
961+
950962
Subscription Quality of Service
951963
-------------------------------
952964

@@ -986,6 +998,8 @@ or more of these values can be OR'ed together.
986998
or deleted rows should be included in the message objects that are sent.
987999

9881000

1001+
.. _types:
1002+
9891003
Types
9901004
=====
9911005

@@ -1258,6 +1272,8 @@ Exceptions
12581272
supported by the database. It is a subclass of DatabaseError.
12591273

12601274

1275+
.. _exchandling:
1276+
12611277
Exception handling
12621278
==================
12631279

@@ -1317,4 +1333,3 @@ This allows you to use the exceptions for example in the following way:
13171333
error, = exc.args
13181334
print("Oracle-Error-Code:", error.code)
13191335
print("Oracle-Error-Message:", error.message)
1320-

‎doc/src/objecttype.rst renamed to ‎doc/src/api_manual/object_type.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ Object Type Objects
4949

5050

5151
Object Objects
52-
==============
52+
--------------
5353

5454
.. note::
5555

@@ -71,6 +71,8 @@ Object Objects
7171
Return a dictionary where the collection's indexes are the keys and the
7272
elements are its values.
7373

74+
.. versionadded:: 7.0
75+
7476

7577
.. method:: Object.aslist()
7678

@@ -149,4 +151,3 @@ Object Objects
149151
.. method:: Object.trim(num)
150152

151153
Remove the specified number of elements from the end of the collection.
152-

‎doc/src/session_pool.rst renamed to ‎doc/src/api_manual/session_pool.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ SessionPool Object
1010

1111
Connection pooling in cx_Oracle is handled by SessionPool objects.
1212

13+
See :ref:`connpool` for information on connection pooling.
14+
1315

1416
.. method:: SessionPool.acquire(user=None, password=None, cclass=None, \
1517
purity=cx_Oracle.ATTR_PURITY_DEFAULT, tag=None, matchanytag=False, \
@@ -185,4 +187,3 @@ SessionPool Object
185187
:data:`cx_Oracle.SPOOL_ATTRVAL_TIMEDWAIT`.
186188

187189
.. versionadded:: 6.4
188-

‎doc/src/soda.rst renamed to ‎doc/src/api_manual/soda.rst

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,12 @@
44
SODA
55
****
66

7-
An overview of Simple Oracle Document Access (SODA) can be found
8-
`here
9-
<https://docs.oracle.com/en/database/oracle/simple-oracle-document-access>`__.
7+
`Oracle Database Simple Oracle Document Access (SODA)
8+
<https://docs.oracle.com/en/database/oracle/simple-oracle-document-access>`__
9+
allows documents to be inserted, queried, and retrieved from Oracle Database
10+
using a set of NoSQL-style cx_Oracle methods.
11+
12+
See :ref:`sodausermanual` for a cx_Oracle example.
1013

1114
SODA requires Oracle Client 18.3 or higher and Oracle Database 18.1 and higher.
1215
The role SODA_APP must be granted to the user.
@@ -110,7 +113,7 @@ SODA Collection Object
110113
.. note::
111114

112115
This object is an extension the DB API. It is used to represent SODA
113-
collections and is created by methods
116+
collections and is created by methods
114117
:meth:`SodaDatabase.createCollection()` and
115118
:meth:`SodaDatabase.openCollection()`.
116119

@@ -520,4 +523,3 @@ SODA Operation Object
520523
criteria can be specified by chaining methods together.
521524

522525
.. versionadded:: 7.0
523-

‎doc/src/subscription.rst renamed to ‎doc/src/api_manual/subscription.rst

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ Subscription Object
9898
.. _msgobjects:
9999

100100
Message Objects
101-
===============
101+
---------------
102102

103103
.. note::
104104

@@ -177,7 +177,7 @@ Message Objects
177177

178178

179179
Message Table Objects
180-
=====================
180+
---------------------
181181

182182
.. note::
183183

@@ -206,7 +206,7 @@ Message Table Objects
206206

207207

208208
Message Row Objects
209-
===================
209+
-------------------
210210

211211
.. note::
212212

@@ -227,19 +227,19 @@ Message Row Objects
227227

228228

229229
Message Query Objects
230-
=====================
230+
---------------------
231231

232232
.. note::
233233

234234
This object is created internally for each query result set changed when
235235
notification is received and is found in the queries attribute of message
236236
objects.
237-
237+
238238

239239
.. attribute:: MessageQuery.id
240240

241241
This read-only attribute returns the query id of the query for which the
242-
result set changed. The value will match the value returned by
242+
result set changed. The value will match the value returned by
243243
Subscription.registerquery when the related query was registered.
244244

245245

@@ -255,4 +255,3 @@ Message Query Objects
255255
This read-only attribute returns a list of message table objects that give
256256
information about the table changes that caused the query result set to
257257
change for this notification.
258-

‎doc/src/variable.rst renamed to ‎doc/src/api_manual/variable.rst

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,4 +81,3 @@ Variable Objects
8181
positions in the variable as a list. This is the equivalent of calling
8282
:meth:`~Variable.getvalue()` for each valid position and the length will
8383
correspond to the value of the :attr:`~Variable.actualElements` attribute.
84-

‎doc/src/conf.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,7 @@
108108
# Output file base name for HTML help builder.
109109
htmlhelp_basename = 'cx_Oracledoc'
110110

111+
numfig = True
111112

112113
# Options for LaTeX output
113114
# ------------------------

‎doc/src/images/cx_Oracle_arch.png

41.1 KB
Loading

0 commit comments

Comments
 (0)