On Tue, 2007-10-23 at 17:27 +0800, James Andrewartha wrote:
> On Tue, 2007-10-23 at 09:15 +0800, James Andrewartha wrote:
> > 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.
>
> Here's one for ldap-controls.tex, and a minor fix to ldap/controls.py
> to use the constant it defines. I've noted that the controlValue passed
> to SimplePagedResultsControl's constructor is ignored, but didn't remove
> it because that would be an API change.
ldap-{cidict,resiter,sasl}.tex are all new files covering previously
undocumented modules. dn.diff adds the dn2str method and has a few
formatting fixes. contents.diff updates python-ldap.tex to include the
new sections, and I added a new chapter for ldapurl and ldif called
"Standalone modules". ldap.tex.2.diff applies over my previous patch and
adds a few references and more cleanups.
Remaining undocumented modules include all of ldap.schema and dsml. I
had a quick look at porting the docstrings of dsml, but it refers to
DSMLv1 when v2 was released in 2002. Under-documented modules (generally
only having examples) include ldap.async, ldif and ldapurl.
Is there anything else I need to do to get these applied, and the
version of the docs on the website updated?
James Andrewartha
% $Id: ldap-cidict.tex,v 1.2 2007/03/27 22:10:17 stroeder Exp $
\section{\module{ldap.cidict} ---
LDAP filter handling }
\declaremodule{standard}{ldap.cidict}
% Author of the module code;
\moduleauthor{Michael Str\"[EMAIL PROTECTED]
% Author of the documentation,
\sectionauthor{Michael Str\"[EMAIL PROTECTED]
\sectionauthor{James [EMAIL PROTECTED]
\modulesynopsis{Case insensitive dictionary.}
The \module{ldap.cidict} module is a convenience wrapper for
dictionaries returned from LDAP servers containing attribute names of variable
case. It defines the following class:
\begin{classdesc}{cidict}{\optional{default=\constant{None}}}
This module is a subclass of \class{UserDict} and provides
a case-insensitive but case-respecting dictionary.
\end{classdesc}
The \module{ldap.cidict} module defines the following functions:
\begin{funcdesc}{strlist_minus}{a,b} % -> list
Returns a list of all items in \var{a} which are not in \var{b} (\var{a} - \var{b}).
\var{a},\var{b} are supposed to be lists of case-insensitive strings.
\end{funcdesc}
\begin{funcdesc}{strlist_intersection}{a,b} % -> list
Returns the intersection of two lists of case-insensitive strings \var{a},\var{b}.
\end{funcdesc}
\begin{funcdesc}{strlist_union}{a,b} % -> list
Returns the union of two lists of case-insensitive strings \var{a},\var{b}.
\end{funcdesc}
% $Id: ldap-resiter.tex,v 1.2 2007/03/27 22:10:17 stroeder Exp $
\section{\module{ldap.resiter} ---
LDAP filter handling }
\declaremodule{standard}{ldap.resiter}
% Author of the module code;
\moduleauthor{Michael Str\"[EMAIL PROTECTED]
% Author of the documentation,
\sectionauthor{Michael Str\"[EMAIL PROTECTED]
\sectionauthor{James [EMAIL PROTECTED]
\modulesynopsis{Processing LDAP results with iterators}
Due to its use of generators, the \module{ldap.resiter} module
requires Python 2.3 or later. It provides the following class:
\begin{classdesc}{ResultProcessor}{}
This is a mix-in class for \class{ldap.ldapopbject.LDAPObject} which adds one generator
method:
\begin{methoddesc}{allresults}{msgid \optional{, timeout=-1}}
Generator function which returns an iterator for processing all LDAP operation
results of the given \var{msgid}.
\end{methoddesc}
\end{classdesc}
% $Id: ldap-sasl.tex,v 1.2 2007/03/27 22:10:17 stroeder Exp $
\section{\module{ldap.sasl} ---
LDAP filter handling }
\declaremodule{standard}{ldap.sasl}
% Author of the module code;
\moduleauthor{Hans [EMAIL PROTECTED]
% Author of the documentation,
\sectionauthor{Hans [EMAIL PROTECTED]
\sectionauthor{James [EMAIL PROTECTED]
\modulesynopsis{Support for SASL mechanisms}
The \module{ldap.sasl} module provides SASL authentication classes.
Each class provides support for one SASL mechanism. This is done by
implementing a \method{callback()} method, which will be called by the
\class{LDAPObject}'s \method{sasl_bind_s()} method.
Implementing support for new SASL mechanism is very easy --- see
the examples of \class{digest_md5} and \class{gssapi}.
\begin{classdesc}{sasl}{cb_value_dict,mech}
This class handles SASL interactions for authentication.
If an instance of this class is passed to ldap's \method{sasl_bind_s()}
method, the library will call its callback() method. For
specific SASL authentication mechanisms, this method can be
overridden.
The (generic) base class takes a \var{cb_value_dictionary} of
question-answer pairs. Questions are specified by the respective
SASL callback id's. The \var{mech} argument is a string that specifies
the SASL mechaninsm to be uesd.
\begin{methoddesc}{callback}{cb_id,challenge,promt,defresult}
The callback method will be called by the \method{sasl_bind_s()}
method several times. Each time it will provide \var{cb_id}, which
tells us what kind of information is requested. \var{challenge} might be a
short (english) text or some binary string, from which the return value is
calculated. \var{prompt} is always a human-readable description string;
\var{defresult} is a default value provided by the sasl library
Currently, we do not use the challenge and prompt information, and
return only information which is stored in the self.cb_value_dict
cb_value_dictionary. Note that the current callback interface is not very
useful for writing generic sasl GUIs, which would need to know all
the questions to ask, before the answers are returned to the sasl
lib (in contrast to one question at a time).
\end{methoddesc}
\end{classdesc}
The following are subclasses of \class{ldap.sasl.sasl} that implement
specific SASL mechanisms:
\begin{classdesc}{cram_md5}{authc_id, password \optional{, authz_id=""}}
This class handles SASL CRAM-MD5 authentication.
\end{classdesc}
\begin{classdesc}{digest_md5}{authc_id, password \optional{, authz_id=""}}
This class handles SASL DIGEST-MD5 authentication.
\end{classdesc}
\begin{classdesc}{gssapi}{\optional{authz_id=""}}
This class handles SASL GSSAPI (i.e. Kerberos V) authentication.
\end{classdesc}
\begin{classdesc}{external}{\optional{authz_id=""}}
This class handles SASL EXTERNAL authentication (i.e. X.509 client certificate).
\end{classdesc}
Index: Doc/ldap-dn.tex
===================================================================
RCS file: /cvsroot/python-ldap/python-ldap/Doc/ldap-dn.tex,v
retrieving revision 1.3
diff -p -u -r1.3 ldap-dn.tex
--- Doc/ldap-dn.tex 27 Mar 2007 22:16:45 -0000 1.3
+++ Doc/ldap-dn.tex 23 Oct 2007 17:10:45 -0000
@@ -12,25 +12,28 @@
\modulesynopsis{LDAP Distinguished Name handling.}
-\begin{seealso}
-\seerfc{4514}{Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names.}{}
-\end{seealso}
-
The \module{ldap.dn} module defines the following functions:
\begin{funcdesc}{escape_dn_chars}{s} % -> string
+
This function escapes characters in string \var{s} which
are special in LDAP distinguished names. You should use this function when
building LDAP DN strings from arbitrary input.
\end{funcdesc}
\begin{funcdesc}{str2dn}{s} % -> list
- This function takes \var{dn} and breaks it up into its component parts
+
+ This function takes \var{s} and breaks it up into its component parts
down to AVA level.
\end{funcdesc}
+\begin{funcdesc}{dn2str}{dn} % -> list
+
+ This function takes \var{dn} and returns a single string.
+\end{funcdesc}
\begin{funcdesc}{explode_dn}{dn \optional{, notypes=\constant{0}}} % -> list
+
This function takes \var{dn} and breaks it up into its component parts.
Each part is known as an RDN (Relative Distinguished Name). The
\var{notypes} parameter is used to specify that only the RDN values be
@@ -42,9 +45,13 @@ The \module{ldap.dn} module defines the
\end{funcdesc}
\begin{funcdesc}{explode_rdn}{rdn \optional{, notypes=\constant{0}}} % -> list
+
This function takes a (multi-valued) \var{rdn} and breaks it up
into a list of characteristic attributes. The
\var{notypes} parameter is used to specify that only the RDN values be
returned and not their types.
\end{funcdesc}
+\begin{seealso}
+\seerfc{4514}{Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names.}{}
+\end{seealso}
Index: Doc/python-ldap.tex
===================================================================
RCS file: /cvsroot/python-ldap/python-ldap/Doc/python-ldap.tex,v
retrieving revision 1.10
diff -p -u -r1.10 python-ldap.tex
--- Doc/python-ldap.tex 2 Mar 2005 09:32:52 -0000 1.10
+++ Doc/python-ldap.tex 23 Oct 2007 17:14:15 -0000
@@ -36,11 +36,16 @@ LDAP standard.
\input{ldap}
\input{ldap-async}
+\input{ldap-cidict}
\input{ldap-controls}
\input{ldap-dn}
\input{ldap-filter}
\input{ldap-modlist}
\input{ldap-schema}
+\input{ldap-resiter}
+\input{ldap-sasl}
+
+\chapter{Standalone modules}
\input{ldif}
\input{ldapurl}
Index: Doc/ldap.tex
===================================================================
RCS file: /cvsroot/python-ldap/python-ldap/Doc/ldap.tex,v
retrieving revision 1.30
diff -p -u -r1.30 ldap.tex
--- Doc/ldap.tex 27 Mar 2007 22:31:51 -0000 1.30
+++ Doc/ldap.tex 23 Oct 2007 17:19:36 -0000
@@ -34,7 +34,9 @@ that lists are manipulated via Python
list operations and errors appear as exceptions.
For far more detailed information on the \C\ interface,
-please see the (expired) draft-ietf-ldapext-ldap-c-api-04.
+please see the (expired) draft-ietf-ldapext-ldap-c-api-04 and
+\manpage{ldap.h}{5} and associated manpages distributed with
+OpenLDAP.
This documentation is current for the Python LDAP module, version
$\version$.
@@ -577,7 +596,8 @@ be \constant{AUTH_SIMPLE}.
%% sasl_interactive_bind_s
\begin{methoddesc}[None]{sasl_interactive_bind_s}{who, auth} % -> None
-This call is used to bind to the directory with a SASL bind request.
+This call is used to bind to the directory with a SASL bind request. For more details on
+the methods available see the \refmodule{ldap.sasl} module.
\end{methoddesc}
%%------------------------------------------------------------
@@ -947,7 +958,8 @@
%%------------------------------------------------------------
%% set_cache_options
-\begin{methoddesc}[LDAPObject]{set_cache_options}{option} -> None
+\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
@@ -966,10 +1029,9 @@
integer flag \var{critical} specifies if the use of this extended
control is marked critical.
-\textbf{Note}
-This method is somewhat immature and might vanish in future versions
+\note{This method is somewhat immature and might vanish in future versions
if full support for extended controls will be implemented. You have been
-warned!
+warned!}
\end{methoddesc}
%%============================================================
@@ -1117,6 +1192,10 @@
a client certificate).
\end{classdesc}
+
+The \class{ResultProcessor} class in the \refmodule{ldap.resiter} module
+is a mix-in class for \class{LDAPObject} which provides \method{allresults()},
+a generator function.
% ==== 4. ====
% Now is probably a good time for a complete example. (Alternatively,
-------------------------------------------------------------------------
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
[email protected]
https://lists.sourceforge.net/lists/listinfo/python-ldap-dev
