Added documentation for BYTES caster

This commit is contained in:
Daniele Varrazzo 2019-01-18 16:15:15 +00:00
parent ddbe495d70
commit 49777de74c
4 changed files with 39 additions and 3 deletions

2
NEWS
View File

@ -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`).

View File

@ -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.

View File

@ -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

View File

@ -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