Skip to content

Commit aa11350

Browse files
anthony-tuiningaanthony-tuininga
committed
Further documentation improvements.
1 parent dd99c40 commit aa11350

File tree

7 files changed

+97
-93
lines changed

7 files changed

+97
-93
lines changed

‎doc/README.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
11
Sphinx is used to generate the HTML for the python-oracledb documentation.
22

3-
The generated python-oracledb documentation is at https://python-oracledb.readthedocs.io/
3+
The generated python-oracledb documentation is at
4+
https://python-oracledb.readthedocs.io/
45

56
This directory contains the documentation source. It is written using reST
67
(re-Structured Text). The source files are processed using Sphinx and can be
78
turned into HTML, PDF or ePub documentation.
89

9-
If you wish to build documentation yourself, install Sphinx. It is available
10-
on many Linux distributions as a pre-built package. You can also install it
11-
using the Python package manager "pip", for example::
10+
If you wish to build documentation yourself, install Sphinx and the Read the
11+
Docs theme. Sphinx is available on many Linux distributions as a pre-built
12+
package. You can also install Sphinx and the Read the Docs theme using the
13+
Python package manager "pip", for example::
1214

13-
python -m pip install Sphinx
15+
python -m pip install -r requirements.txt
1416

1517
For more information on Sphinx, please visit this page:
1618

‎doc/requirements.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
1-
sphinx==4.1.2
1+
sphinx>=4.2.0
2+
sphinx-rtd-theme

‎doc/src/api_manual/module.rst‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1753,8 +1753,6 @@ module.html#session-pool-get-modes>`_ constants that were used in cx_Oracle
17531753
of time (defined by the ``wait_timeout`` parameter) for a session to become
17541754
available before returning with an error.
17551755

1756-
This constant is not supported in the python-oracledb Thin mode.
1757-
17581756
.. note::
17591757

17601758
This constant deprecates the ``SPOOL_ATTRVAL_TIMEDWAIT`` constant that

‎doc/src/conf.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,10 @@
8484
# The style sheet to use for HTML and HTML Help pages. A file of that name
8585
# must exist either in Sphinx' static/ path, or in one of the custom paths
8686
# given in html_static_path.
87-
html_style = 'default.css'
87+
# html_style = 'default.css'
88+
89+
# The theme to use for readthedocs.
90+
html_theme = 'sphinx_rtd_theme'
8891

8992
# Add any paths that contain custom static files (such as style sheets) here,
9093
# relative to this directory. They are copied after the builtin static files,

‎doc/src/user_guide/appendix_b.rst‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -215,9 +215,6 @@ differs from the python-oracledb Thick mode in the following ways:
215215
``handle`` parameters. The parameters that are ignored in the Thick mode include
216216
``wallet_password``, ``disable_oob``, ``config_dir``, and ``debug_jdwp`` parameters.
217217

218-
* The ``getmode`` value :data:`~oracledb.POOL_GETMODE_TIMEDWAIT` is not
219-
implemented in the python-oracledb Thin mode.
220-
221218
* The python-oracledb Thin mode only suppports :ref:`homogeneous
222219
<connpooltypes>` pools.
223220

@@ -314,8 +311,13 @@ Globalization in Thin and Thick Modes
314311
=====================================
315312

316313
All NLS environment variables, and the ``ORA_SDTZ`` and ``ORA_TZFILE``
317-
variables, are ignored by the python-oracledb Thin mode. Use Python's
318-
capabilities instead. See :ref:`globalization`.
314+
environment variables, are ignored by the python-oracledb Thin mode. Use
315+
Python's capabilities instead.
316+
317+
The python-oracledb Thin mode can only use NCHAR, NVARCHAR2, and NCLOB data
318+
when Oracle Database's secondary character set is AL16UTF16.
319+
320+
See :ref:`globalization`.
319321

320322
Tracing in Thin and Thick Modes
321323
===============================

‎doc/src/user_guide/exception_handling.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,8 @@ in the examples below:
9595

9696
python-oracledb Thin mode Error::
9797

98-
[Errno 61] Connection refused
98+
DPY-6005: cannot connect to database. Connection failed with "[Errno 61]
99+
Connection refused"
99100

100101
python-oracledb Thick mode Error::
101102

‎doc/src/user_guide/globalization.rst‎

Lines changed: 75 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -4,86 +4,113 @@
44
Character Sets and Globalization
55
********************************
66

7+
Character Sets
8+
==============
9+
10+
Database Character Set
11+
----------------------
12+
713
Data fetched from and sent to Oracle Database will be mapped between the
8-
database character set and the "Oracle client" character set of the Oracle
9-
Client libraries used by python-oracledb. If data cannot be correctly mapped between
10-
client and server character sets, then it may be corrupted or queries may fail
11-
with :ref:`"codec can't decode byte" <codecerror>`.
14+
`database character set
15+
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-EA913CC8-C5BA-4FB3-A1B8-882734AF4F43>`__
16+
and the "Oracle client" character set of the Oracle Client libraries used by
17+
python-oracledb. If data cannot be correctly mapped between client and server
18+
character sets, then it may be corrupted or queries may fail with :ref:`"codec
19+
can't decode byte" <codecerror>`.
20+
21+
All database character sets are supported by the python-oracledb.
22+
23+
.. _findingcharset:
24+
25+
To find the database character set, execute the query:
26+
27+
.. code-block:: sql
28+
29+
SELECT value AS db_charset
30+
FROM nls_database_parameters
31+
WHERE parameter = 'NLS_CHARACTERSET';
1232
13-
All database character sets are supported by the python-oracledb Thick mode.
14-
The database performs any required conversion for the python-oracledb Thin
15-
mode.
33+
Database National Character Set
34+
-------------------------------
1635

17-
For the `national character set
36+
For the secondary `national character set
1837
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-4E12D991-C286-4F1A-AFC6-F35040A5DE4F>`__
1938
used for NCHAR, NVARCHAR2, and NCLOB data types:
2039

2140
- AL16UTF16 is supported by both the python-oracledb Thin and Thick modes
2241
- UTF8 is not supported by the python-oracledb Thin mode
2342

24-
Python-oracledb Thick mode uses Oracle's National Language Support (NLS) to
25-
assist in globalizing applications, see :ref:`thicklocale`.
26-
27-
.. note::
43+
To find the database's national character set, execute the query:
2844

29-
All NLS environment variables are ignored by the python-oracledb Thin mode.
30-
Also the ``ORA_SDTZ`` and ``ORA_TZFILE`` variables are ignored. See
31-
:ref:`thindatenumber`.
45+
.. code-block:: sql
3246
33-
For more information, see the `Database Globalization Support Guide
34-
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=NLSPG>`__.
47+
SELECT value AS db_ncharset
48+
FROM nls_database_parameters
49+
WHERE parameter = 'NLS_NCHAR_CHARACTERSET';
3550
3651
Setting the Client Character Set
37-
================================
52+
--------------------------------
3853

3954
In python-oracledb, the encoding used for all character data is "UTF-8". The
4055
``encoding`` and ``nencoding`` parameters of the :meth:`oracledb.connect`
41-
and :meth:`oracledb.create_pool` methods are ignored.
56+
and :meth:`oracledb.create_pool` methods are deprecated and ignored.
4257

43-
.. _findingcharset:
4458

59+
Setting the Client Locale
60+
=========================
4561

46-
Finding the Oracle Database Character Set
47-
=========================================
62+
Thick Mode Oracle Database National Language Support (NLS)
63+
----------------------------------------------------------
4864

49-
To find the database character set, execute the query:
65+
The python-oracledb Thick mode uses Oracle Database's National Language Support
66+
(NLS) functionality to assist in globalizing applications, for example to
67+
convert numbers and dates to strings in the locale specific format.
5068

51-
.. code-block:: sql
69+
You can use the ``NLS_LANG`` environment variable to set the language and
70+
territory used by the Oracle Client libraries. For example, on Linux you could
71+
set::
5272

53-
SELECT value AS db_charset
54-
FROM nls_database_parameters
55-
WHERE parameter = 'NLS_CHARACTERSET';
73+
export NLS_LANG=JAPANESE_JAPAN
5674

57-
To find the database 'national character set' used for NCHAR and related types,
58-
execute the query:
75+
The language ("JAPANESE" in this example) specifies conventions such as the
76+
language used for Oracle Database messages, sorting, day names, and month
77+
names. The territory ("JAPAN") specifies conventions such as the default date,
78+
monetary, and numeric formats. If the language is not specified, then the value
79+
defaults to AMERICAN. If the territory is not specified, then the value is
80+
derived from the language value. See `Choosing a Locale with the NLS_LANG
81+
Environment Variable
82+
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-86A29834-AE29-4BA5-8A78-E19C168B690A>`__
5983

60-
.. code-block:: sql
84+
If the ``NLS_LANG`` environment variable is set in the application with
85+
``os.environ['NLS_LANG']``, it must be set before any connection pool is
86+
created, or before any standalone connections are created.
6187

62-
SELECT value AS db_ncharset
63-
FROM nls_database_parameters
64-
WHERE parameter = 'NLS_NCHAR_CHARACTERSET';
88+
Any client character set value in the ``NLS_LANG`` variable, for example
89+
``JAPANESE_JAPAN.JA16SJIS``, is ignored by python-oracledb. See `Setting the
90+
Client Character Set`_.
6591

66-
To find the current "client" character set used by python-oracledb, execute the
67-
query:
92+
Other Oracle globalization variables, such as ``NLS_DATE_FORMAT`` can also be
93+
set to change the behavior of python-oracledb Thick, see `Setting NLS Parameters
94+
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
95+
id=GUID-6475CA50-6476-4559-AD87-35D431276B20>`__.
6896

69-
.. code-block:: sql
97+
For more information, see the `Database Globalization Support Guide
98+
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=NLSPG>`__.
7099

71-
SELECT DISTINCT client_charset AS client_charset
72-
FROM v$session_connect_info
73-
WHERE sid = SYS_CONTEXT('USERENV', 'SID');
100+
.. _thindatenumber:
74101

102+
Thin Mode Locale-aware Number and Date Conversions
103+
--------------------------------------------------
75104

76-
.. _thindatenumber:
105+
.. note::
77106

78-
Locale-aware Number and Date Conversions in python-oracledb Thin Mode
79-
=====================================================================
107+
All NLS environment variables are ignored by the python-oracledb Thin mode.
108+
Also the ``ORA_SDTZ`` and ``ORA_TZFILE`` variables are ignored.
80109

81-
In python-oracledb Thick mode, Oracle NLS routines convert numbers and dates to
82-
strings in the locale specific format. But in the python-oracledb Thin mode,
83-
output type handlers need to be used to perform similar conversions. The
84-
examples below show a simple conversion and also how the Python locale module
85-
can be used. Type handlers like those below can also be used in
86-
python-oracledb Thick mode.
110+
In the python-oracledb Thin mode, output type handlers need to be used to
111+
perform similar conversions. The examples below show a simple conversion and
112+
also how the Python locale module can be used. Type handlers like those below
113+
can also be used in python-oracledb Thick mode.
87114

88115
To convert numbers:
89116

@@ -188,33 +215,3 @@ To convert dates:
188215
for row in cursor:
189216
print(row) # gives 'Mi 15 Dez 19:57:56 2021'
190217
print()
191-
192-
193-
.. _thicklocale:
194-
195-
Setting the Oracle Client Locale in python-oracledb Thick Mode
196-
==============================================================
197-
198-
You can use the ``NLS_LANG`` environment variable to set the language and
199-
territory used by the Oracle Client libraries. For example, on Linux you could
200-
set::
201-
202-
export NLS_LANG=JAPANESE_JAPAN
203-
204-
The language ("JAPANESE" in this example) specifies conventions such as the
205-
language used for Oracle Database messages, sorting, day names, and month
206-
names. The territory ("JAPAN") specifies conventions such as the default date,
207-
monetary, and numeric formats. If the language is not specified, then the value
208-
defaults to AMERICAN. If the territory is not specified, then the value is
209-
derived from the language value. See `Choosing a Locale with the NLS_LANG
210-
Environment Variable
211-
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-86A29834-AE29-4BA5-8A78-E19C168B690A>`__
212-
213-
If the ``NLS_LANG`` environment variable is set in the application with
214-
``os.environ['NLS_LANG']``, it must be set before any connection pool is
215-
created, or before any standalone connections are created.
216-
217-
Other Oracle globalization variables, such as ``NLS_DATE_FORMAT`` can also be
218-
set to change the behavior of python-oracledb Thick, see `Setting NLS Parameters
219-
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
220-
id=GUID-6475CA50-6476-4559-AD87-35D431276B20>`__.

0 commit comments

Comments
 (0)