diff --git a/NEWS b/NEWS index e5084ecf..76b6b80f 100644 --- a/NEWS +++ b/NEWS @@ -9,6 +9,8 @@ New features: - Added `~psycopg2.errors` module. Every PostgreSQL error is converted into a specific exception class (:ticket:`#682`). - Added `~psycopg2.extensions.encrypt_password()` function (:ticket:`#576`). +- Added `~psycopg2.extensions.BYTES` adapter to manage databases with mixed + encodings on Python 3 (:ticket:`#835`). - Added `~psycopg2.extensions.Column.table_oid` and `~psycopg2.extensions.Column.table_column` attributes on `cursor.description` items (:ticket:`#661`). diff --git a/doc/src/extensions.rst b/doc/src/extensions.rst index 9704b722..9e99ef17 100644 --- a/doc/src/extensions.rst +++ b/doc/src/extensions.rst @@ -947,6 +947,7 @@ Python objects. All the typecasters are automatically registered, except from the database. See :ref:`unicode-handling` for details. .. data:: BOOLEAN + BYTES DATE DECIMAL FLOAT @@ -963,6 +964,7 @@ from the database. See :ref:`unicode-handling` for details. .. data:: BINARYARRAY BOOLEANARRAY + BYTESARRAY DATEARRAY DATETIMEARRAY DECIMALARRAY @@ -1011,5 +1013,8 @@ from the database. See :ref:`unicode-handling` for details. module. In older versions they can be imported from the implementation module `!psycopg2._psycopg`. -.. versionchanged:: 2.7.2 - added `!*DATETIMETZ*` objects. +.. versionadded:: 2.7.2 + the `!*DATETIMETZ*` objects. + +.. versionadded:: 2.8 + the `!BYTES` and `BYTESARRAY` objects. diff --git a/doc/src/faq.rst b/doc/src/faq.rst index 432e994a..24dca21e 100644 --- a/doc/src/faq.rst +++ b/doc/src/faq.rst @@ -108,6 +108,19 @@ My database is Unicode, but I receive all the strings as UTF-8 `!str`. Can I rec See :ref:`unicode-handling` for the gory details. +.. _faq-bytes: +.. cssclass:: faq + +My database is in mixed encoding. My program was working on Python 2 but Python 3 fails decoding the strings. How do I avoid decoding? + From psycopg 2.8 you can use the following adapters to always return bytes + from strings:: + + psycopg2.extensions.register_type(psycopg2.extensions.BYTES) + psycopg2.extensions.register_type(psycopg2.extensions.BYTESARRAY) + + See :ref:`unicode-handling` for an example. + + .. _faq-float: .. cssclass:: faq diff --git a/doc/src/usage.rst b/doc/src/usage.rst index e9416e35..08c6dce4 100644 --- a/doc/src/usage.rst +++ b/doc/src/usage.rst @@ -457,13 +457,29 @@ the connection or globally: see the function Unicode, you can register the related typecasters globally as soon as Psycopg is imported:: - import psycopg2 import psycopg2.extensions psycopg2.extensions.register_type(psycopg2.extensions.UNICODE) psycopg2.extensions.register_type(psycopg2.extensions.UNICODEARRAY) and forget about this story. +.. note:: + + In some cases, on Python 3, you may want to receive `!bytes` instead of + `!str`, without undergoing to any decoding. This is especially the case if + the data in the database is in mixed encoding. The + `~psycopg2.extensions.BYTES` caster is what you neeed:: + + import psycopg2.extensions + psycopg2.extensions.register_type(psycopg2.extensions.BYTES, conn) + psycopg2.extensions.register_type(psycopg2.extensions.BYTESARRAY, conn) + cur = conn.cursor() + cur.execute("select %s::text", (u"€",)) + cur.fetchone()[0] + b'\xe2\x82\xac' + + .. versionadded: 2.8 + .. index:: single: Buffer; Adaptation