[python-ldap] More on ldap.controls in python-ldap 2.4

[Michael Ströder]

HI!

Please review what has been done in module ldap.controls and related stuff in
LDAPObject.result4():

1. ldap.controls resides in in Lib/ldap/controls/ and has new sub-modules.

2. The API is not backwards compatible to python-ldap 2.3:
Implementations of ResponseControl.decodeControlValue() do not return a result
anymore. Instead implementations are expected to set appropriately named class
attributes for the decoded control value fields.

3. check out argument knownLDAPControls for function
ldap.controls.DecodeControlTuples() and accompanying argument
resp_ctrl_classes for LDAPObject.result4() and the global response control
class registry in ldap.controls.KNOWN_CONTROLS.

4. The following demo scripts have been updated to make use of the new API:
Demo/page_control.py
Demo/pyasn1/readentrycontrol.py

5. New sub-modules which make use of pyasn1 were added. These have to be
explicitly imported to avoid requiring pyasn1 as mandantory installed module.
Check out:
Lib/ldap/controls/psearch.py
Lib/ldap/controls/pyasn1ctrls.py
Lib/ldap/controls/readentry.py

Further issues:

1. Response controls are not returned by _s methods in general. This can be
easily changed within LDAPObject class methods but makes results incompatible.
But I guess no-one used the results anyway.

2. Especially there's no async variant of sasl_interactive_bind_s() so bind
response controls are not accessible for LDAP SASL binds (e.g.
ldap.controls.pyasn1ctrls.AuthorizationIdentityControl).

3. Response controls are not returned in case of a LDAPError exception being
raised. Personally I'd prefer to let the C API return only error codes but
together with all other result data including response controls and let
LDAPObject.result4() raise the appropriate exception with response controls
objects attached as exception class attribute.

Your feedback and contributions (code and docs) are appreciated.

Ciao, Michael.