From 8a10b1e4506c27773628fff1f3d99ca850211862 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Mon, 20 Sep 2021 09:48:57 -0400 Subject: [PATCH] clarify "encoding" parameter further Prevent any reading of this parameter that would omit that it is not used under Python 3 and in Python 2 is not used very much either. Fixes: #7050 Change-Id: Iaf619f1ee164fc58afe710d11627ed6368d74343 --- lib/sqlalchemy/engine/create.py | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py index b5ec22116a..f9dccb66ce 100644 --- a/lib/sqlalchemy/engine/create.py +++ b/lib/sqlalchemy/engine/create.py @@ -180,16 +180,24 @@ def create_engine(url, **kwargs): :ref:`change_4737` - :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 DBAPIs own encoding facilities.** + :param encoding: **legacy Python 2 value only, where it only applies to + specific DBAPIs, not used in Python 3 for any modern DBAPI driver. + Please refer to individual dialect documentation for client encoding + behaviors.** Defaults to the string value ``utf-8``. This value + refers **only** to the character encoding that is used when SQLAlchemy + sends or receives data from a :term:`DBAPI` that does not support + Python Unicode and **is only used under Python 2**, only for certain + DBAPI drivers, and only in certain circumstances. **Python 3 users + please DISREGARD this parameter and refer to the documentation for the + specific dialect in use in order to configure character encoding + behavior.** .. 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 + encoding issues that were prevalent with **some DBAPIS only** + under **Python 2 only**. Under Python 3 it is not used by + any modern dialect. For DBAPIs that require + client encoding configurations, which are most of those outside + of SQLite, please consult specific :ref:`dialect documentation ` for details. All modern DBAPIs that work in Python 3 necessarily feature direct -- 2.47.2