Hi,
The first patch removes an invalid LDAP option. The second updates the
LDAPObject documentation, and the third updates LDAPObject docstrings.
Hopefully I'll have time to look at updating the rest of the docs soon.
James Andrewartha
Index: Modules/constants.c
===================================================================
RCS file: /cvsroot/python-ldap/python-ldap/Modules/constants.c,v
retrieving revision 1.30
diff -u -r1.30 constants.c
--- Modules/constants.c 17 Jul 2007 19:37:27 -0000 1.30
+++ Modules/constants.c 23 Oct 2007 01:10:45 -0000
@@ -154,7 +154,6 @@
add_int(d,OPT_HOST_NAME);
add_int(d,OPT_ERROR_STRING);
add_int(d,OPT_MATCHED_DN);
- add_int(d,OPT_PRIVATE_EXTENSION_BASE);
add_int(d,OPT_DEBUG_LEVEL);
add_int(d,OPT_TIMEOUT);
add_int(d,OPT_REFHOPLIMIT);
Index: Doc/ldap.tex
===================================================================
RCS file: /cvsroot/python-ldap/python-ldap/Doc/ldap.tex,v
retrieving revision 1.30
diff -u -r1.30 ldap.tex
--- Doc/ldap.tex 27 Mar 2007 22:31:51 -0000 1.30
+++ Doc/ldap.tex 23 Oct 2007 01:10:45 -0000
@@ -120,8 +120,10 @@
\subsubsection{Options}
-For use with functions and method set_option() and get_option() the
-following option identifiers are defined as constants:
+To manage the behavior of python-ldap there are a number of options that can be
+set. For more details, see \manpage{ldap.conf}{5} and \manpage{ldap_get_options}{3}.
+The functions and method set_option() and get_option() use the following option
+identifiers, which are defined as constants:
\begin{datadesc}{OPT_API_FEATURE_INFO}
\end{datadesc}
@@ -136,6 +138,7 @@
\end{datadesc}
\begin{datadesc}{OPT_DEREF}
+ Specifies how alias derefencing is done when performing a search.
\end{datadesc}
\begin{datadesc}{OPT_ERROR_STRING}
@@ -157,6 +160,7 @@
\end{datadesc}
\begin{datadesc}{OPT_REFERRALS}
+ Boolean specifying if referrals should be automatically followed, defaults to \code{True}.
\end{datadesc}
\begin{datadesc}{OPT_REFHOPLIMIT}
@@ -300,9 +304,6 @@
The entry already exists. E.g. the \var{dn} specified with \method{add()}
already exists in the DIT.
\end{excdesc}
-\begin{excdesc}{}
-
-\end{excdesc}
\begin{excdesc}{AUTH_UNKNOWN}
The authentication method specified to \method{bind()} is not known.
\end{excdesc}
@@ -522,12 +523,17 @@
and wait for and return with the server's result, or with
\constant{None} if no data is expected.
-LDAPObject instances, have the following methods:
+Methods with `\constant{_ext}' (and some without) accept two extra arguments,
+\var{serverctrls} and \var{clientctrls} which are server and client controls.
+They can be constructed with the \refmodule{ldap.controls} module.
+
+LDAPObject instances have the following methods:
%%------------------------------------------------------------
%% abandon
\begin{methoddesc}[LDAPObject]{abandon}{msgid}
+ \methodline[LDAPObject]{abandon_ext}{msgid \optional{, serverctrls=\constant{None} \optional{, clientctrls=\constant{None}}}}
Abandons or cancels an LDAP operation in progress. The \var{msgid} argument
should be the message ID of an outstanding LDAP operation as returned by
the asynchronous methods \method{search()}, \method{modify()}, etc.
@@ -541,11 +547,13 @@
\begin{methoddesc}[LDAPObject]{add}{dn, modlist} % -> int
\methodline{add_s}{dn, modlist}
+ \methodline{add_ext}{dn, modlist \optional{, serverctrls=\constant{None} \optional{, clientctrls=\constant{None}}}}
+ \methodline{add_ext_s}{dn, modlist \optional{, serverctrls=\constant{None} \optional{, clientctrls=\constant{None}}}}
Performs an LDAP add operation. The \var{dn} argument is the distinguished
name (DN) of the entry to add, and \var{modlist} is a list of attributes to be
added. The modlist is similar the one passed to \method{modify()}, except that the
operation integer is omitted from the tuples in modlist. You might want to
-look into sub-module l\refmodule{ldap.modlist} for generating the modlist.
+look into sub-module \refmodule{ldap.modlist} for generating the modlist.
\end{methoddesc}
%%------------------------------------------------------------
@@ -573,19 +581,19 @@
\end{methoddesc}
%%------------------------------------------------------------
-%%
-\begin{methoddesc}[LDAPObject]{cancel}{
- cancelid,
- \optional{, serverctrls=\constant{None}
- \optional{, clientctrls=\constant{None}}}}
- Send cancels extended operation for an LDAP operation specified by \var{cancelid}.
- The \var{cancelid} should be the message id of an outstanding LDAP operation as returned
- by the asynchronous methods search(), modify() etc. The caller
- can expect that the result of an abandoned operation will not be
- returned from a future call to result().
- In opposite to abandon() this extended operation gets an result from
- the server and thus should be preferred if the server supports it.
-\end{methoddesc}
+%% cacncel is not implmenented
+%\begin{methoddesc}[LDAPObject]{cancel}{
+% cancelid
+% \optional{, serverctrls=\constant{None}
+% \optional{, clientctrls=\constant{None}}}}
+% Send cancels extended operation for an LDAP operation specified by \var{cancelid}.
+% The \var{cancelid} should be the message id of an outstanding LDAP operation as returned
+% by the asynchronous methods search(), modify() etc. The caller
+% can expect that the result of an abandoned operation will not be
+% returned from a future call to result().
+% In opposite to abandon() this extended operation gets an result from
+% the server and thus should be preferred if the server supports it.
+%\end{methoddesc}
%%------------------------------------------------------------
@@ -593,10 +601,18 @@
\begin{methoddesc}[LDAPObject]{compare}{dn, attr, value} % -> int
\methodline[LDAPObject]{compare_s}{dn, attr, value} % -> tuple
+ \methodline[LDAPObject]{compare_ext}{
+ dn, attr, value
+ \optional{, serverctrls=\constant{None}
+ \optional{, clientctrls=\constant{None}}}} % -> int
+ \methodline[LDAPObject]{compare_ext_s}{
+ dn, attr, value
+ \optional{, serverctrls=\constant{None}
+ \optional{, clientctrls=\constant{None}}}} % -> tuple
Perform an LDAP comparison between the attribute named \var{attr} of
-entry \var{dn}, and the value \var{value}. The synchronous form
+entry \var{dn}, and the value \var{value}. The synchronous forms
returns \constant{0} for false, or \constant{1} for true.
-The asynchronous form returns the message ID of the initiated request,
+The asynchronous forms returns the message ID of the initiated request,
and the result of the asynchronous compare can be obtained using
\method{result()}.
@@ -613,7 +629,9 @@
\begin{methoddesc}[LDAPObject]{delete}{dn} % -> int
\methodline[LDAPObject]{delete_s}{dn} % -> None
-Performs an LDAP delete operation on \var{dn}. The asynchronous form
+ \methodline[LDAPObject]{delete_ext}{dn \optional{, serverctrls=\constant{None} \optional{, clientctrls=\constant{None}}}} % -> int
+ \methodline[LDAPObject]{delete_ext_s}{dn \optional{, serverctrls=\constant{None} \optional{, clientctrls=\constant{None}}}} % -> None
+Performs an LDAP delete operation on \var{dn}. The asynchronous forms
returns the message id of the initiated request, and the result can be obtained
from a subsequent call to \method{result()}.
\end{methoddesc}
@@ -621,8 +639,16 @@
%%------------------------------------------------------------
%% modify
-\begin{methoddesc}[LDAPObject]{modify}{ dn, modlist } % -> int
- \methodline[LDAPObject]{modify_s}{ dn, modlist } % -> None
+\begin{methoddesc}[LDAPObject]{modify}{dn, modlist} % -> int
+ \methodline[LDAPObject]{modify_s}{dn, modlist} % -> None
+ \methodline[LDAPObject]{modify_ext}{
+ dn, modlist
+ \optional{, serverctrls=\constant{None}
+ \optional{, clientctrls=\constant{None}}}} % -> int
+ \methodline[LDAPObject]{modify_ext_s}{
+ dn, modlist
+ \optional{, serverctrls=\constant{None}
+ \optional{, clientctrls=\constant{None}}}} % -> None
Performs an LDAP modify operation on an entry's attributes.
The \var{dn} argument is the distinguished name (DN) of the entry to modify,
and \var{modlist} is a list of modifications to make to that entry.
@@ -636,8 +662,8 @@
delete or replace respectively. For the delete operation, \var{mod_vals}
may be \constant{None} indicating that all attributes are to be deleted.
-The asynchronous method \method{modify()} returns the message ID of the
-initiated request.
+The asynchronous methods \method{modify()} and \method{modify_ext()} return the
+message ID of the initiated request.
You might want to look into sub-module \refmodule{ldap.modlist} for
generating \var{modlist}.
@@ -664,9 +690,9 @@
%%------------------------------------------------------------
%% passwd
-\begin{methoddesc}[LDAPObject]{passwd}{user,oldpw,newpw}
+\begin{methoddesc}[LDAPObject]{passwd}{user,oldpw,newpw \optional{, serverctrls=\constant{None} \optional{, clientctrls=\constant{None}}}}
%-> int
- \methodline[LDAPObject]{passwd_s}{user,oldpw,newpw}
+ \methodline[LDAPObject]{passwd_s}{user,oldpw,newpw \optional{, serverctrls=\constant{None} \optional{, clientctrls=\constant{None}}}}
% -> None
Perform a `LDAP Password Modify Extended Operation' operation
on the entry specified by \var{user}.
@@ -766,6 +792,9 @@
\end{methoddesc}
+%%------------------------------------------------------------
+%% result2
+
\begin{methoddesc}[LDAPObject]{result2}{\optional{ msgid=\constant{RES_ANY} \optional{, all=\constant{1} \optional{, timeout=\constant{-1}}}}} % -> 3-tuple
This method behaves almost exactly like \method{result()}. But
it returns a 3-tuple also containing the message id of the
@@ -776,6 +805,14 @@
\end{methoddesc}
%%------------------------------------------------------------
+%% result3
+
+\begin{methoddesc}[LDAPObject]{result3}{\optional{ msgid=\constant{RES_ANY} \optional{, all=\constant{1} \optional{, timeout=\constant{-1}}}}} % -> 4-tuple
+This method behaves almost exactly like \method{result2()}. But it
+returns an extra item in the tuple, decoded server controls.
+\end{methoddesc}
+
+%%------------------------------------------------------------
%% search
\begin{methoddesc}[LDAPObject]{search}{base, scope \optional{,filterstr=\constant{'(objectClass=*)'} \optional{,
@@ -853,17 +890,28 @@
\end{methoddesc}
%%------------------------------------------------------------
+%% start_tls_s
+
+\begin{methoddesc}[LDAPObject]{start_tls_s}{} % -> None
+ Negotiate TLS with server. The `version' attribute must have been
+ set to \constant{VERSION3} (which it is by default) before calling start_tls_s.
+ If TLS could not be started an exception will be raised.
+\end{methoddesc}
+
+%%------------------------------------------------------------
%% unbind
\begin{methoddesc}[LDAPObject]{unbind}{} % -> int
\methodline{unbind_s}{} % -> None
+ \methodline{unbind_ext}{\optional{, serverctrls=\constant{None} \optional{, clientctrls=\constant{None}}}} % -> int
+ \methodline{unbind_ext_s}{\optional{, serverctrls=\constant{None} \optional{, clientctrls=\constant{None}}}} % -> None
This call is used to unbind from the directory, terminate the current
association, and free resources. Once called, the connection to the
LDAP server is closed and the LDAP object is marked invalid.
Further invocation of methods on the object will yield exceptions.
-The \method{unbind()} and \method{unbind_s()} methods are both
-synchronous in nature
+The \method{unbind()}, \method{unbind_s()}, \method{unbind_ext()} and \method{unbind_ext_()}
+methods are all synchronous in nature.
\end{methoddesc}
%%------------------------------------------------------------
@@ -880,17 +928,35 @@
\subsubsection{LDAP options}
+%%------------------------------------------------------------
+%% get_option
+
\begin{methoddesc}[LDAPObject]{get_option}{option} % -> None
This function returns the value of the LDAPObject option
specified by \var{option}.
\end{methoddesc}
+%%------------------------------------------------------------
+%% set_options
+
\begin{methoddesc}[LDAPObject]{set_option}{option, invalue} % -> None
This function sets the value of the LDAPObject option
specified by \var{option} to \var{invalue}.
\end{methoddesc}
%%------------------------------------------------------------
+%% set_cache_options
+
+\begin{methoddesc}[LDAPObject]{set_cache_options}{option} -> None
+ Changes the caching behaviour. Currently supported options are
+ \constant{CACHE_OPT_CACHENOERRS}, which suppresses caching of requests
+ that resulted in an error, and
+ \constant{CACHE_OPT_CACHEALLERRS}, which enables caching of all requests.
+ The default behaviour is not to cache requests that result in
+ errors, except those that result in a \constant{SIZELIMIT_EXCEEDED} exception.
+\end{methoddesc}
+
+%%------------------------------------------------------------
%% manage_dsa_it
\begin{methoddesc}[LDAPObject]{manage_dsa_it}{enable, \optional{, critical=\constant{0}}}
@@ -983,6 +1049,74 @@
This option is used in the wrapper module.
\end{memberdesc}
+%%============================================================
+%% subclasses
+
+\subsubsection{Subclasses}
+
+There are several subclasses of \class{LDAPObject} that provide
+extra features. To use them, call their constructors directly,
+or assign them to \var{ldap.LDAPObject} and then use \method{ldap.initialize()}
+as usual.
+
+%%------------------------------------------------------------
+%% NonblockingLDAPObject
+
+\begin{classdesc}{NonblockingLDAPObject}{self, uri \optional{, result_timeout=\constant{-1}}}
+\end{classdesc}
+
+%%------------------------------------------------------------
+%% ReconnectLDAPObject
+
+\begin{classdesc}{ReconnectLDAPObject}{self, uri \optional{, result_timeout=\constant{-1} \optional{, retry_max=\constant{1} \optional{, retry_delay=\constant{60.0}}}}}
+ In case of server failure (\constant{ldap.SERVER_DOWN}) the implementations
+ of all synchronous operation methods (\method{search_s()} etc.) will do
+ an automatic reconnect and rebind and will retry the very same
+ operation.
+
+ This is very handy for broken LDAP server implementations
+ (e.g. in Lotus Domino) which drop connections very often making
+ it impossible to have a long-lasting control flow in the
+ application.
+
+ Its constructor is like \class{LDAPObject} with two additional
+ arguments. \var{retry_max} is the maximum count of reconnect trials,
+ and \var{retry_delay} is the time span to wait between two reconnect trials.
+\end{classdesc}
+
+%%------------------------------------------------------------
+%% SmartLDAPObject
+
+\begin{classdesc}{SmartLDAPObject}{
+ self, uri
+ \optional{, result_timeout=\constant{-1}
+ \optional{, retry_max=\constant{1}
+ \optional{, retry_delay=\constant{60.0}
+ \optional{, who=\constant{''}
+ \optional{, cred=\constant{''}
+ \optional{, start_tls=\constant{1}
+ \optional{, tls_cacertfile=\constant{None}
+ \optional{, tls_cacertdir=\constant{None}
+ \optional{, tls_clcertfile=\constant{None}
+ \optional{, tls_clkeyfile=\constant{None}}}}}}}}}}}}
+This class extends \class{ReconnectLDAPObject} and makes \method{__init__()}
+do some smarter things like negotiating the LDAP protocol version and calling
+\method{start_tls_s()}.
+
+\var{who} and \var{cred} are the bind DN and credential to use in a simple
+bind after connecting. \var{start_tls} determines if StartTLS extended operation is tried
+on a LDAPv3 server and if the LDAP URL scheme is ldap:.
+If LDAP URL scheme is not ldap: (e.g. ldaps: or ldapi:)
+this parameter is ignored. \constant{0} means Don't use StartTLS ext op,
+\constant{1} (default) means try StartTLS ext op but proceed when unavailable and
+\constant{2} means try StartTLS ext op and re-raise exception if it fails.
+
+\var{tls_cacertfile}, \var{tls_cacertdir}, \var{tls_clcertfile} and \var{tls_clkeyfile}
+are the locations of a CA certificate, a directory of CA certificates (both for verifying
+the server identity), the client certificate and the client key (if the server requires
+a client certificate).
+
+\end{classdesc}
% ==== 4. ====
% Now is probably a good time for a complete example. (Alternatively,
Index: Lib/ldap/ldapobject.py
===================================================================
RCS file: /cvsroot/python-ldap/python-ldap/Lib/ldap/ldapobject.py,v
retrieving revision 1.98
diff -u -r1.98 ldapobject.py
--- Lib/ldap/ldapobject.py 5 Jun 2007 09:56:15 -0000 1.98
+++ Lib/ldap/ldapobject.py 23 Oct 2007 01:10:45 -0000
@@ -347,6 +347,15 @@
return self.rename_s(dn,newrdn,None,delold)
def passwd(self,user,oldpw,newpw,serverctrls=None,clientctrls=None):
+ """
+ passwd(user, oldpw, newpw [,serverctrls=None [,clientctrls=None]]) -> int
+ passwd_s(user, oldpw, newpw [,serverctrls=None [,clientctrls=None]]) -> None
+ Perform a `LDAP Password Modify Extended Operation' operation on the
+ entry specified by user. The old password in oldpw is replaced with the
+ new password in newpw by a LDAP server supporting this operation.
+
+ See also: RFC 3062, LDAP Password Modify Extended Operation.
+ """
return self._ldap_call(self._l.passwd,user,oldpw,newpw,EncodeControlTuples(serverctrls),EncodeControlTuples(clientctrls))
def passwd_s(self,user,oldpw,newpw,serverctrls=None,clientctrls=None):
@@ -389,7 +398,8 @@
If the result of a specific operation is required, msgid should
be set to the invocation message id returned when the operation
- was initiated; otherwise RES_ANY should be supplied.
+ was initiated; otherwise RES_ANY should be supplied and result2()
+ should be used instead.
The all parameter only has meaning for search() responses
and is used to select whether a single entry of the search
@@ -429,10 +439,23 @@
return res_type,res_data
def result2(self,msgid=_ldap.RES_ANY,all=1,timeout=None):
+ """
+ result2([msgid=_ldap.RES_ANY [,all=1 [,timeout=None]]])
+ This method behaves almost exactly like result(). But it returns a
+ 3-tuple also containing the message id of the outstanding LDAP
+ operation a particular result message belongs to. This is especially
+ handy if one needs to dispatch results obtained with msgid=RES_ANY to
+ several consumer threads which invoked a particular LDAP operation.
+ """
res_type, res_data, res_msgid, srv_ctrls = self.result3(msgid,all,timeout)
return res_type, res_data, res_msgid
def result3(self,msgid=_ldap.RES_ANY,all=1,timeout=None):
+ """
+ result2([msgid=_ldap.RES_ANY [,all=1 [,timeout=None]]])
+ This method behaves almost exactly like result(). But it returns an
+ extra item at the end of the tuple, the decoded server controls.
+ """
if timeout is None:
timeout = self.timeout
rtype, rdata, rmsgid, serverctrls = self._ldap_call(self._l.result3,msgid,all,timeout)
@@ -522,7 +545,7 @@
"""
start_tls_s() -> None
Negotiate TLS with server. The `version' attribute must have been
- set to VERSION3 before calling start_tls_s.
+ set to VERSION3 (which it is by default) before calling start_tls_s.
If TLS could not be started an exception will be raised.
"""
return self._ldap_call(self._l.start_tls_s)
-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
Python-LDAP-dev mailing list
Python-LDAP-dev@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/python-ldap-dev
