From 3ab5e3781b9f44d458cb6213e89f50d01ea167dd Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Wed, 6 May 2020 09:47:26 -0400 Subject: Clarify create_engine encoding; update cx_Oracle The create_engine()->encoding parameter is mostly irrelevant under Python 3. make it clear this parameter is not generally useful anymore and refer readers to the dialect documenation. Update cx_Oracle documentation to feature many examples of the encoding / nencoding parameters, remove extra detail that is not generally useful and reorganize information into more specific sections, de-emphasizing legacy / Python 2 specific sections. Change-Id: I42dafb85de0a585c9e05e1e3d787d8d6bfa632c0 --- lib/sqlalchemy/engine/create.py | 52 ++++++++++++++++++++++------------------- 1 file changed, 28 insertions(+), 24 deletions(-) (limited to 'lib/sqlalchemy/engine') diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py index a53e94f1e..dbe1e8b57 100644 --- a/lib/sqlalchemy/engine/create.py +++ b/lib/sqlalchemy/engine/create.py @@ -165,25 +165,30 @@ def create_engine(url, **kwargs): :param encoding: Defaults to ``utf-8``. This is the string encoding used by SQLAlchemy for string encode/decode operations which occur within SQLAlchemy, **outside of - the DBAPI.** Most modern DBAPIs feature some degree of - direct support for Python ``unicode`` objects, - what you see in Python 2 as a string of the form - ``u'some string'``. For those scenarios where the - DBAPI is detected as not supporting a Python ``unicode`` - object, this encoding is used to determine the - source/destination encoding. It is **not used** - for those cases where the DBAPI handles unicode - directly. - - To properly configure a system to accommodate Python - ``unicode`` objects, the DBAPI should be - configured to handle unicode to the greatest - degree as is appropriate - see - the notes on unicode pertaining to the specific - target database in use at :ref:`dialect_toplevel`. + the DBAPIs own encoding facilities.** + + .. note:: The ``encoding`` parameter deals only with in-Python + encoding issues that were prevalent with many DBAPIs under Python + 2. Under Python 3 it is mostly unused. For DBAPIs that require + client encoding configurations, such as those of MySQL and Oracle, + please consult specific :ref:`dialect documentation + ` for details. + + All modern DBAPIs that work in Python 3 necessarily feature direct + support for Python unicode strings. Under Python 2, this was not + always the case. For those scenarios where the DBAPI is detected as + not supporting a Python ``unicode`` object under Python 2, this + encoding is used to determine the source/destination encoding. It is + **not used** for those cases where the DBAPI handles unicode directly. + + To properly configure a system to accommodate Python ``unicode`` + objects, the DBAPI should be configured to handle unicode to the + greatest degree as is appropriate - see the notes on unicode pertaining + to the specific target database in use at :ref:`dialect_toplevel`. Areas where string encoding may need to be accommodated - outside of the DBAPI include zero or more of: + outside of the DBAPI, nearly always under **Python 2 only**, + include zero or more of: * the values passed to bound parameters, corresponding to the :class:`.Unicode` type or the :class:`.String` type @@ -199,13 +204,12 @@ def create_engine(url, **kwargs): * the string column names retrieved from the DBAPI's ``cursor.description`` attribute. - When using Python 3, the DBAPI is required to support - *all* of the above values as Python ``unicode`` objects, - which in Python 3 are just known as ``str``. In Python 2, - the DBAPI does not specify unicode behavior at all, - so SQLAlchemy must make decisions for each of the above - values on a per-DBAPI basis - implementations are - completely inconsistent in their behavior. + When using Python 3, the DBAPI is required to support all of the above + values as Python ``unicode`` objects, which in Python 3 are just known + as ``str``. In Python 2, the DBAPI does not specify unicode behavior + at all, so SQLAlchemy must make decisions for each of the above values + on a per-DBAPI basis - implementations are completely inconsistent in + their behavior. :param execution_options: Dictionary execution options which will be applied to all connections. See -- cgit v1.2.1