Skip to content

Commit c68c42a

Browse files
anthony-tuiningaanthony-tuininga
committed
Ongoing documentation improvements.
1 parent 0ff266f commit c68c42a

File tree

3 files changed

+86
-81
lines changed

3 files changed

+86
-81
lines changed

‎doc/src/api_manual/pool_params.rst‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,10 @@ PoolParams Methods
3232
which is looked up in ``tnsnames.ora``. Parameters that are found in the connect string
3333
override any currently stored values.
3434

35-
.. method:: PoolParams.set(user=None, proxy_user=None, password=None, \
35+
.. method:: PoolParams.set(min=None, max=None, increment=None, connectiontype=None, \
36+
getmode=None, homogeneous=None, timeout=None, wait_timeout=None, \
37+
max_lifetime_session=None, session_callback=None, max_sessions_per_shard=None, \
38+
soda_metadata_cache=None, ping_interval=None, user=None, proxy_user=None, password=None, \
3639
newpassword=None, wallet_password=None, host=None, port=None, protocol=None, \
3740
https_proxy=None, https_proxy_port=None, service_name=None, sid=None, \
3841
server_type=None, cclass=None, purity=None, expire_time=None, retry_count=None, \

‎doc/src/user_guide/appendix_b.rst‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -311,8 +311,13 @@ Globalization in Thin and Thick Modes
311311
=====================================
312312

313313
All NLS environment variables, and the ``ORA_SDTZ`` and ``ORA_TZFILE``
314-
variables, are ignored by the python-oracledb Thin mode. Use Python's
315-
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`.
316321

317322
Tracing in Thin and Thick Modes
318323
===============================

‎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)