From 829027081d8cb1891732b8d7d631bfcc827fe213 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Tue, 5 Dec 2017 16:07:08 +0100 Subject: [PATCH] Doc: LDAPBytesWarning doc improvements - Make filtering note apply to both causes of the warning - Add formal class documentation - Add cross-references --- Doc/bytes_mode.rst | 14 +++++++++----- Doc/reference/ldap.rst | 12 ++++++++++++ 2 files changed, 21 insertions(+), 5 deletions(-) diff --git a/Doc/bytes_mode.rst b/Doc/bytes_mode.rst index 62ab496..c775b27 100644 --- a/Doc/bytes_mode.rst +++ b/Doc/bytes_mode.rst @@ -66,9 +66,11 @@ Unspecified: relaxed mode with warnings Text values returned from python-ldap are always ``unicode``. Text values supplied to python-ldap should be ``unicode``; - warnings of type :class:`ldap.LDAPBytesWarning` are emitted when they - are not. :class:`ldap.LDAPBytesWarning` is a subclass of - :class:`BytesWarning`. + warnings are emitted when they are not. + + The warnings are of type :class:`~ldap.LDAPBytesWarning`, which + is a subclass of :class:`BytesWarning` designed to be easily + :ref:`filtered out ` if needed. Backwards-compatible behavior is not scheduled for removal until Python 2 itself reaches end of life. @@ -107,8 +109,10 @@ Note that only the result's *values* are of the ``bytes`` type: ] -Filter warning --------------- +.. _filter-bytes-warning: + +Filtering warnings +------------------ The bytes mode warnings can be filtered out and ignored with a simple filter. diff --git a/Doc/reference/ldap.rst b/Doc/reference/ldap.rst index 1f7ae5b..4b163da 100644 --- a/Doc/reference/ldap.rst +++ b/Doc/reference/ldap.rst @@ -564,6 +564,18 @@ The above exceptions are raised when a result code from an underlying API call does not indicate success. +Warnings +======== + +.. py:class:: LDAPBytesWarning + + Raised when bytes/text mismatch in non-strict bytes mode. + + See :ref:`bytes_mode` for details. + + .. versionadded:: 3.0.0 + + .. _ldap-objects: LDAPObject classes