Skip to content

Commit 2f8738b

Browse files
droideckmistotebe
droideck
and
mistotebe
committed
doc: describe OPT_SERVER_CONTROLS and OPT_CLIENT_CONTROLS
Both entries were empty. Say that they hold request controls attached to every operation, how the two set_option() variants take them, and that response controls come back from result3()/result4() instead. Point to the 4.0 issue for get_option(). Related: #643 Co-Authored-By: Ondřej Kuzník <ondra@mistotebe.net>
1 parent daeb687 commit 2f8738b

1 file changed

Lines changed: 18 additions & 0 deletions

File tree

‎Doc/reference/ldap.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,16 @@ the following option identifiers are defined as constants:
180180
181181
.. py:data:: OPT_CLIENT_CONTROLS
182182
183+
Client-side request controls that libldap attaches to every operation
184+
on the connection. :py:meth:`LDAPObject.set_option` takes a list of
185+
:py:class:`ldap.controls.RequestControl` instances, the module-level
186+
:py:func:`set_option` takes the encoded 3-tuples. Response controls
187+
never show up here, they are returned by :py:meth:`LDAPObject.result3`
188+
and :py:meth:`LDAPObject.result4`. :py:meth:`LDAPObject.get_option`
189+
decodes the stored controls with the response control classes, which
190+
only works for controls whose request and response values share a
191+
schema, see https://github.com/python-ldap/python-ldap/issues/643.
192+
183193
.. py:data:: OPT_DEBUG_LEVEL
184194
185195
Sets the debug level within the underlying OpenLDAP C lib (libldap).
@@ -220,6 +230,14 @@ the following option identifiers are defined as constants:
220230
221231
.. py:data:: OPT_SERVER_CONTROLS
222232
233+
Server-side request controls that libldap attaches to every operation
234+
on the connection unless instructed otherwise (e.g. with
235+
`search_ext(..., serverctrls=[...], ...)`), for example
236+
:py:class:`ldap.controls.sessiontrack.SessionTrackingControl`.
237+
Same rules as :py:data:`OPT_CLIENT_CONTROLS`. Controls meant for a
238+
single operation belong in the ``serverctrls`` argument of that
239+
operation instead.
240+
223241
.. py:data:: OPT_SIZELIMIT
224242
225243
.. py:data:: OPT_SUCCESS

0 commit comments

Comments
 (0)