dnrops
/
python-oracledb
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Further documentation improvements.

This commit is contained in:
Anthony Tuininga 2022-07-15 11:41:44 -06:00
parent dd99c40a37
commit aa1135093f
7 changed files with 102 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
doc/README.md
View File

@ -1,16 +1,18 @@
Sphinx is used to generate the HTML for the python-oracledb documentation.
The generated python-oracledb documentation is at https://python-oracledb.readthedocs.io/
The generated python-oracledb documentation is at
https://python-oracledb.readthedocs.io/
This directory contains the documentation source. It is written using reST
(re-Structured Text). The source files are processed using Sphinx and can be
turned into HTML, PDF or ePub documentation.
If you wish to build documentation yourself, install Sphinx. It is available
on many Linux distributions as a pre-built package. You can also install it
using the Python package manager "pip", for example::
If you wish to build documentation yourself, install Sphinx and the Read the
Docs theme. Sphinx is available on many Linux distributions as a pre-built
package. You can also install Sphinx and the Read the Docs theme using the
Python package manager "pip", for example::
python -m pip install Sphinx
python -m pip install -r requirements.txt
For more information on Sphinx, please visit this page:

3
doc/requirements.txt
View File

@ -1 +1,2 @@
sphinx==4.1.2
sphinx>=4.2.0
sphinx-rtd-theme

2
doc/src/api_manual/module.rst
View File

@ -1753,8 +1753,6 @@ module.html#session-pool-get-modes>`_ constants that were used in cx_Oracle
of time (defined by the ``wait_timeout`` parameter) for a session to become
available before returning with an error.
This constant is not supported in the python-oracledb Thin mode.
.. note::
This constant deprecates the ``SPOOL_ATTRVAL_TIMEDWAIT`` constant that

5
doc/src/conf.py
View File

@ -84,7 +84,10 @@ pygments_style = 'sphinx'
# The style sheet to use for HTML and HTML Help pages. A file of that name
# must exist either in Sphinx' static/ path, or in one of the custom paths
# given in html_static_path.
html_style = 'default.css'
# html_style = 'default.css'
# The theme to use for readthedocs.
html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,

12
doc/src/user_guide/appendix_b.rst
View File

@ -215,9 +215,6 @@ differs from the python-oracledb Thick mode in the following ways:
``handle`` parameters. The parameters that are ignored in the Thick mode include
``wallet_password``, ``disable_oob``, ``config_dir``, and ``debug_jdwp`` parameters.
* The ``getmode`` value :data:`~oracledb.POOL_GETMODE_TIMEDWAIT` is not
implemented in the python-oracledb Thin mode.
* The python-oracledb Thin mode only suppports :ref:`homogeneous
<connpooltypes>` pools.
@ -314,8 +311,13 @@ Globalization in Thin and Thick Modes
=====================================
All NLS environment variables, and the ``ORA_SDTZ`` and ``ORA_TZFILE``
variables, are ignored by the python-oracledb Thin mode. Use Python's
capabilities instead. See :ref:`globalization`.
environment variables, are ignored by the python-oracledb Thin mode. Use
Python's capabilities instead.
The python-oracledb Thin mode can only use NCHAR, NVARCHAR2, and NCLOB data
when Oracle Database's secondary character set is AL16UTF16.
See :ref:`globalization`.
Tracing in Thin and Thick Modes
===============================

3
doc/src/user_guide/exception_handling.rst
View File

@ -95,7 +95,8 @@ in the examples below:
python-oracledb Thin mode Error::
[Errno 61] Connection refused
DPY-6005: cannot connect to database. Connection failed with "[Errno 61]
Connection refused"
python-oracledb Thick mode Error::

163
doc/src/user_guide/globalization.rst
View File

@ -4,48 +4,24 @@
Character Sets and Globalization
********************************
Character Sets
==============
Database Character Set
----------------------
Data fetched from and sent to Oracle Database will be mapped between the
database character set and the "Oracle client" character set of the Oracle
Client libraries used by python-oracledb. If data cannot be correctly mapped between
client and server character sets, then it may be corrupted or queries may fail
with :ref:`"codec can't decode byte" <codecerror>`.
`database character set
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-EA913CC8-C5BA-4FB3-A1B8-882734AF4F43>`__
and the "Oracle client" character set of the Oracle Client libraries used by
python-oracledb. If data cannot be correctly mapped between client and server
character sets, then it may be corrupted or queries may fail with :ref:`"codec
can't decode byte" <codecerror>`.
All database character sets are supported by the python-oracledb Thick mode.
The database performs any required conversion for the python-oracledb Thin
mode.
For the `national character set
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-4E12D991-C286-4F1A-AFC6-F35040A5DE4F>`__
used for NCHAR, NVARCHAR2, and NCLOB data types:
- AL16UTF16 is supported by both the python-oracledb Thin and Thick modes
- UTF8 is not supported by the python-oracledb Thin mode
Python-oracledb Thick mode uses Oracle's National Language Support (NLS) to
assist in globalizing applications, see :ref:`thicklocale`.
.. note::
All NLS environment variables are ignored by the python-oracledb Thin mode.
Also the ``ORA_SDTZ`` and ``ORA_TZFILE`` variables are ignored. See
:ref:`thindatenumber`.
For more information, see the `Database Globalization Support Guide
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=NLSPG>`__.
Setting the Client Character Set
================================
In python-oracledb, the encoding used for all character data is "UTF-8". The
``encoding`` and ``nencoding`` parameters of the :meth:`oracledb.connect`
and :meth:`oracledb.create_pool` methods are ignored.
All database character sets are supported by the python-oracledb.
.. _findingcharset:
Finding the Oracle Database Character Set
=========================================
To find the database character set, execute the query:
.. code-block:: sql
@ -54,8 +30,17 @@ To find the database character set, execute the query:
FROM nls_database_parameters
WHERE parameter = 'NLS_CHARACTERSET';
To find the database 'national character set' used for NCHAR and related types,
execute the query:
Database National Character Set
-------------------------------
For the secondary `national character set
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-4E12D991-C286-4F1A-AFC6-F35040A5DE4F>`__
used for NCHAR, NVARCHAR2, and NCLOB data types:
- AL16UTF16 is supported by both the python-oracledb Thin and Thick modes
- UTF8 is not supported by the python-oracledb Thin mode
To find the database's national character set, execute the query:
.. code-block:: sql
@ -63,27 +48,69 @@ execute the query:
FROM nls_database_parameters
WHERE parameter = 'NLS_NCHAR_CHARACTERSET';
To find the current "client" character set used by python-oracledb, execute the
query:
Setting the Client Character Set
--------------------------------
.. code-block:: sql
In python-oracledb, the encoding used for all character data is "UTF-8". The
``encoding`` and ``nencoding`` parameters of the :meth:`oracledb.connect`
and :meth:`oracledb.create_pool` methods are deprecated and ignored.
SELECT DISTINCT client_charset AS client_charset
FROM v$session_connect_info
WHERE sid = SYS_CONTEXT('USERENV', 'SID');
Setting the Client Locale
=========================
Thick Mode Oracle Database National Language Support (NLS)
----------------------------------------------------------
The python-oracledb Thick mode uses Oracle Database's National Language Support
(NLS) functionality to assist in globalizing applications, for example to
convert numbers and dates to strings in the locale specific format.
You can use the ``NLS_LANG`` environment variable to set the language and
territory used by the Oracle Client libraries. For example, on Linux you could
set::
export NLS_LANG=JAPANESE_JAPAN
The language ("JAPANESE" in this example) specifies conventions such as the
language used for Oracle Database messages, sorting, day names, and month
names. The territory ("JAPAN") specifies conventions such as the default date,
monetary, and numeric formats. If the language is not specified, then the value
defaults to AMERICAN. If the territory is not specified, then the value is
derived from the language value. See `Choosing a Locale with the NLS_LANG
Environment Variable
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-86A29834-AE29-4BA5-8A78-E19C168B690A>`__
If the ``NLS_LANG`` environment variable is set in the application with
``os.environ['NLS_LANG']``, it must be set before any connection pool is
created, or before any standalone connections are created.
Any client character set value in the ``NLS_LANG`` variable, for example
``JAPANESE_JAPAN.JA16SJIS``, is ignored by python-oracledb. See `Setting the
Client Character Set`_.
Other Oracle globalization variables, such as ``NLS_DATE_FORMAT`` can also be
set to change the behavior of python-oracledb Thick, see `Setting NLS Parameters
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
id=GUID-6475CA50-6476-4559-AD87-35D431276B20>`__.
For more information, see the `Database Globalization Support Guide
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=NLSPG>`__.
.. _thindatenumber:
Locale-aware Number and Date Conversions in python-oracledb Thin Mode
=====================================================================
Thin Mode Locale-aware Number and Date Conversions
--------------------------------------------------
In python-oracledb Thick mode, Oracle NLS routines convert numbers and dates to
strings in the locale specific format. But in the python-oracledb Thin mode,
output type handlers need to be used to perform similar conversions. The
examples below show a simple conversion and also how the Python locale module
can be used. Type handlers like those below can also be used in
python-oracledb Thick mode.
.. note::
All NLS environment variables are ignored by the python-oracledb Thin mode.
Also the ``ORA_SDTZ`` and ``ORA_TZFILE`` variables are ignored.
In the python-oracledb Thin mode, output type handlers need to be used to
perform similar conversions. The examples below show a simple conversion and
also how the Python locale module can be used. Type handlers like those below
can also be used in python-oracledb Thick mode.
To convert numbers:
@ -188,33 +215,3 @@ To convert dates:
for row in cursor:
print(row) # gives 'Mi 15 Dez 19:57:56 2021'
print()
.. _thicklocale:
Setting the Oracle Client Locale in python-oracledb Thick Mode
==============================================================
You can use the ``NLS_LANG`` environment variable to set the language and
territory used by the Oracle Client libraries. For example, on Linux you could
set::
export NLS_LANG=JAPANESE_JAPAN
The language ("JAPANESE" in this example) specifies conventions such as the
language used for Oracle Database messages, sorting, day names, and month
names. The territory ("JAPAN") specifies conventions such as the default date,
monetary, and numeric formats. If the language is not specified, then the value
defaults to AMERICAN. If the territory is not specified, then the value is
derived from the language value. See `Choosing a Locale with the NLS_LANG
Environment Variable
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-86A29834-AE29-4BA5-8A78-E19C168B690A>`__
If the ``NLS_LANG`` environment variable is set in the application with
``os.environ['NLS_LANG']``, it must be set before any connection pool is
created, or before any standalone connections are created.
Other Oracle globalization variables, such as ``NLS_DATE_FORMAT`` can also be
set to change the behavior of python-oracledb Thick, see `Setting NLS Parameters
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
id=GUID-6475CA50-6476-4559-AD87-35D431276B20>`__.