Fix comments and docs.

Lib/ldap/ldapobject.py

@@ -115,7 +115,7 @@ class SimpleLDAPObject:
       return value
     elif self.bytes_mode:
       if not isinstance(value, bytes):
-        raise TypeError("All provided fields *must* be bytes in bytes mode; got %r" % (value,))
+        raise TypeError("All provided fields *must* be bytes when bytes mode is on; got %r" % (value,))
       return value.decode('utf-8')
     else:
       if not isinstance(value, text_type):

README

@@ -19,6 +19,48 @@ According to this, releases of ``pyldap`` will stick to the numbering of the ups
 
 However, some compatibility toggles will be added to bring cleaner APIs for PY3 code.
 
+Please note the ``pyldap`` installs under the same ``ldap`` module as ``python-ldap``; it **CANNOT** be installed alongside.
+
+
+--------------------------
+Upgrading from python-ldap
+--------------------------
+
+``pyldap`` brings some improvements on top of ``python-ldap``.
+
+
+Bytes/text management
+=====================
+
+The LDAP protocol states that some fields (distinguised names, relative distinguished names,
+attribute names, queries) be encoded in UTF-8; some other (mostly attribute *values*) **MAY**
+contain any type of data, and thus be treated as bytes.
+
+However, ``python-ldap`` used bytes for all fields, including those guaranteed to be text.
+In order to support Python 3, ``pyldap`` needs to make this distinction explicit; this is done
+through the ``bytes_mode`` flag to ``ldap.initialize()``.
+
+When porting from ``python-ldap``, users are advised to update their code to set ``bytes_mode=False``
+on calls to these methods.
+Under Python 2, ``pyldap`` checks aggressively the type of provided arguments, and will raise a ``TypeError``
+for any invalid parameter.
+
+The typical usage is as follow; note that only the result's *values* are of the bytes type:
+
+.. code-block:: pycon
+
+    >>> import ldap
+    >>> con = ldap.initialize('ldap://localhost:389', bytes_mode=False)
+    >>> con.simple_bind_s('login', 'secret_password')
+    >>> results = con.search_s('ou=people,dc=example,dc=org', ldap.SCOPE_SUBTREE, "(cn=Raphaël)")
+    >>> results
+    [
+        ("cn=Raphaël,ou=people,dc=example,dc=org", {
+            'cn': [b'Rapha\xc3\xabl'],
+            'sn': [b'Barrois'],
+        }),
+    ]
+
 
 ---------------------------------------
 python-ldap: LDAP client API for Python