Re: documentation updates
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.
James Andrewartha
Index: Lib/ldap/controls.py
===
RCS file: /cvsroot/python-ldap/python-ldap/Lib/ldap/controls.py,v
retrieving revision 1.5
diff -p -u -p -u -r1.5 controls.py
--- Lib/ldap/controls.py 16 Jul 2007 10:49:48 - 1.5
+++ Lib/ldap/controls.py 23 Oct 2007 09:22:36 -
@@ -71,7 +71,7 @@ class SimplePagedResultsControl(LDAPCont
controlType = ldap.LDAP_CONTROL_PAGE_OID
def __init__(self,controlType,criticality,controlValue=None,encodedControlValue=None):
-LDAPControl.__init__(self,ldap.LDAP_CONTROL_PAGE_OID,criticality,controlValue,encodedControlValue)
+LDAPControl.__init__(self,self.controlType,criticality,controlValue,encodedControlValue)
def encodeControlValue(self,value):
size,cookie = value
Index: Doc/ldap-controls.tex
===
RCS file: /cvsroot/python-ldap/python-ldap/Doc/ldap-controls.tex,v
retrieving revision 1.1
diff -u -r1.1 ldap-controls.tex
--- Doc/ldap-controls.tex 2 Mar 2005 09:32:52 - 1.1
+++ Doc/ldap-controls.tex 23 Oct 2007 09:20:10 -
@@ -12,16 +12,56 @@
\modulesynopsis{High-level access to LDAP controls.}
-The \module{ldap.controls} module defines the following functions:
+The \module{ldap.controls} module defines the following classes:
-\begin{funcdesc}{EncodeControlTuples}{ldapControls} % -> list
+\begin{classdesc}{LDAPControl}{controlType, criticality \optional{, controlValue=\constant{None} \optional{, encodedControlValue=\constant{None
+Base class for all LDAP controls. This class should not be used directly,
+instead one of the following subclasses should be used as appropriate.
+
+\begin{methoddesc}[LDAPControl]{encodeControlValue}{value}
+Dummy class to be overridden by subclasses.
+\end{methoddesc}
+
+\begin{methoddesc}[LDAPControl]{decodeControlValue}{value}
+Dummy class to be overridden by subclasses.
+\end{methoddesc}
+
+\begin{methoddesc}[LDAPControl]{getEncodedTuple}{}
+Return a readily encoded 3-tuple which can be directly
+passed to C module _ldap. Called by \function{ldap.EncodeControlTuples}.
+\end{methoddesc}
+\end{classdesc}
+
+\begin{classdesc}{BooleanControl}{controlType, criticality \optional{, controlValue=\constant{None} \optional{, encodedControlValue=\constant{None
+Base class for simple controls with booelan control value.
+
+In this base class \var{controlValue} has to be passed as
+boolean type (\constant{True}/\constant{False} or \constant{1}/\constant{0}).
+\end{classdesc}
+\begin{classdesc}{SimplePagedResultsControl}{controlType, criticality \optional{, controlValue=\constant{None} \optional{, encodedControlValue=\constant{None
+The class provides the LDAP Control Extension for Simple Paged Results Manipulation. \var{controlType} is ignored
+in favor of \constant{ldap.LDAP_CONTROL_PAGE_OID}.
+\begin{seealso}
+\seerfc{2696}{LDAP Control Extension for Simple Paged Results Manipulation}{}
+\end{seealso}
+\end{classdesc}
+
+\begin{classdesc}{MatchedValuesControl}{criticality \optional{, controlValue=\constant{None}}}
+This class provides the LDAP Matched Values control. \var{controlValue} is an LDAP filter.
+\begin{seealso}
+\seerfc{3876}{Returning Matched Values with the Lightweight Directory Access Protocol version 3 (LDAPv3)}{}
+\end{seealso}
+\end{classdesc}
+The \module{ldap.controls} module defines the following functions:
+\begin{funcdesc}{EncodeControlTuples}{ldapControls} % -> list
+ Return list of readily encoded 3-tuples which can be directly
+ passed to C module _ldap.
\end{funcdesc}
\begin{funcdesc}{DecodeControlTuples}{ldapControlTuples} % -> list
-
-
+ Decode a list of readily encoded 3-tuples as returned by the C module _ldap.
\end{funcdesc}
-
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
Re: documentation updates
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}{call
Re: documentation updates
James, first of all many thanks for your efforts working on this. James Andrewartha wrote: > > Is there anything else I need to do to get these applied, and the > version of the docs on the website updated? I've started reviewing your patches this morning and I have some doubts about some details which need clarification. This will take a little bit. I will follow-up on this when I have some spare time left. Maybe tomorrow... One general note: I didn't document some stuff since I didn't want to endorse it because I don't consider certain APIs to be really stable (say: designed well). Examples are class SmartLDAPObject, the API of ldap.schema etc. So take a break until I follow-up on this. Thanks again. Ciao, Michael. - 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
Status of module dsml
James Andrewartha wrote: > I had a quick look at porting the docstrings of dsml, but it refers > to DSMLv1 when v2 was released in 2002. python-ldap's module implements DSMLv1, not DSMLv2. Gee, looking at the module I don't remember what I've implemented there... You see, DSML is very low on my priority list. Frankly I have some doubts about what it's good for. ;-) Ciao, Michael. - 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
