python-ldap-dev

documentation updates

[James A. <ja...@da...>]

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

Re: documentation updates

[James A. <ja...@da...>]

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

Re: documentation updates

[James A. <ja...@da...>]

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

Status of module dsml

[<mi...@st...>]

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.

Re: documentation updates

[<mi...@st...>]

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.

Re: documentation updates

[<mi...@st...>]

James,

Michael Ströder wrote:
> 
> 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...

Well, actually it took more time to have a running latex environment again.

I've committed many modifications to ldap*.tex but not all. Please 
review. Some new module descriptions are still not in there.

> 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.

Hmm, I don't know whether I want to endorse the use of module 
ldap.cidict. Since Python 2.3 has support for sets now this is somewhat 
outdated.

Ciao, Michael.

Re: documentation updates

[James A. <ja...@da...>]

On Wed, 2007-12-26 at 14:24 +0100, Michael Ströder wrote:
> Well, actually it took more time to have a running latex environment again.
> 
> I've committed many modifications to ldap*.tex but not all. Please 
> review. Some new module descriptions are still not in there.

Looks pretty good.

> > 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.
> 
> Hmm, I don't know whether I want to endorse the use of module 
> ldap.cidict. Since Python 2.3 has support for sets now this is somewhat 
> outdated.

The main feature of cidict is that it's case-insensitive - I didn't
think Python's sets were? cidict is still being used in this example
written at the end of last year: 
http://www.packtpub.com/article/python-ldap-applications-ldap-opearations

James Andrewartha

Re: documentation updates

[Michael S. <mi...@st...>]

James Andrewartha wrote:
>> Hmm, I don't know whether I want to endorse the use of module 
>> ldap.cidict. Since Python 2.3 has support for sets now this is somewhat 
>> outdated.
> 
> The main feature of cidict is that it's case-insensitive - I didn't
> think Python's sets were? cidict is still being used in this example
> written at the end of last year: 
> http://www.packtpub.com/article/python-ldap-applications-ldap-opearations

Hmm, it's used therein to store an entry. Yes, one could use it like this.

But for higher-level stuff I'd rather like to endorse something like 
class ldap.schema.models.Entry which is a full schema-aware dictionary 
for LDAP entries. It solves all name alias and name->OID mapping 
problems but requires LDAPv3 subschema subentry information to be 
retrieved and initialized. But I consider this also to be somewhat 
immature since I'm probably the only one who's using it. And one to do 
left: Attribute sub-types are not handled.

Ciao, Michael.