Disallow non-native psycopg2 Unicode in Python 3; update docs

Fixed issue where the psycopg2 dialect would silently pass the
``use_native_unicode=False`` flag without actually having any effect under
Python 3, as the psycopg2 DBAPI uses Unicode unconditionally under Python
3.  This usage now raises an :class:`_exc.ArgumentError` when used under
Python 3. Added test support for Python 2.

Additionally, added documentation for client_encoding parameter
that may be passed to libpq directly via psycopg2.

Change-Id: I40ddf6382c157fa9399c21f0e01064197ea100f8

1 files changed, 20 insertions, 0 deletions

diff --git a/test/dialect/postgresql/test_dialect.py b/test/dialect/postgresql/test_dialect.py
index 08be41b75..075994cb9 100644
--- a/test/dialect/postgresql/test_dialect.py
+++ b/test/dialect/postgresql/test_dialect.py
@@ -114,6 +114,26 @@ class DialectTest(fixtures.TestBase):
         ]:
             eq_(dialect._get_server_version_info(mock_conn(string)), version)
 
+    @testing.requires.python3
+    @testing.requires.psycopg2_compatibility
+    def test_pg_dialect_no_native_unicode_in_python3(self, testing_engine):
+        with testing.expect_raises_message(
+            exc.ArgumentError,
+            "psycopg2 native_unicode mode is required under Python 3",
+        ):
+            testing_engine(options=dict(use_native_unicode=False))
+
+    @testing.requires.python2
+    @testing.requires.psycopg2_compatibility
+    def test_pg_dialect_no_native_unicode_in_python2(self, testing_engine):
+        e = testing_engine(options=dict(use_native_unicode=False))
+        with e.connect() as conn:
+            eq_(
+                conn.exec_driver_sql(u"SELECT '🐍 voix m’a réveillé'").scalar(),
+                u"🐍 voix m’a réveillé".encode("utf-8"),
+            )
+
+    @testing.requires.python2
     @testing.requires.psycopg2_compatibility
     def test_pg_dialect_use_native_unicode_from_config(self):
         config = {