PROGRAMMING.txt

Programming ZopeLDAP Entry Objects

Author: Jeffrey P Shell
Date: Dec 18, 2000
Revision: For ZopeLDAP 1.1.0

Getting an Entry Object and its attributes

Using an LDAP Filter object is the best way to get an Entry object. LDAP Filter objects act like methods\functions and return a sequence of entry objects (so they can be used with any sort of looping structure). For example, if you had an LDAP Filter titled lookupByEmail with the parameter email with the content:

       mail=<dtml-var name="mail">*

Can be used in DTML like this:

       <dtml-in expr="lookupByEmail(email='jef')">
        Surname: <dtml-var name="sn"><br />
        Common name: <dtml-var name="cn"><br /><br />
       </dtml-in>

Or in a Python Script like this:

       entries = container.lookupByEmail(email='jef')

       for entry in entries:
        # do something here...

Notes about Attributes and Entry Objects

By default, LDAP always returns its attributes as sequences (Python lists), even if there is only one value. ZopeLDAP Entry objects use a special class, AttrWrap, when returning attributes accessed through normal __getattr__ (the a.b syntax). AttrWrap behaves and acts like a normal Python list with the exception that when printed as a string (ie, with dtml-var or Python str() or "%s"), it printes the results as a comma seperated list. This makes DTML representations of Entry object significantly easier. When using the Entry method get(), the attribute is returned as a Python list as returned by PythonLDAP. But if you're wanting to do tests based on attributes, you have to remember to qualify the attribute, ie:

     if entry.sn[0] == 'Shell':   # Works

     if entry.sn == 'Shell':      # Won't work

And also remember that getattr based access returns AttrWrap instances, which means the following:

    if entry.get('sn') == ['Shell']:   # Works

    if entry.sn == ['Shell']:          # Won't work

Changing attribute values

Changing attributes on Entry objects is protected by the permission Manage Entry Information. This permission can be set anywhere in Zope, and will work best when set in the folder containing the LDAP Filter used to access the Entry object. The methods exposed under this permission are:

set(key, value): example: entry.set("sn", "Shell"), entry.set("mail", ["foo@bar.com", "foo@baz.net"])
setattrs([kwdict, kw]): Takes either a mapping argument or keyword arguments. Or both. Example: entry.setattrs({"sn": "Bazzo"}, mail=["foo@bar.com, "foo@baz.net"])
setAll([kwdict, kw]): Same as setattrs, except that the existing data is replaced by what's passed in here.
remove(attr): Deletes the attribute, example: entry.remove("comments")

Accessing subentries

Attributes on Entry objects are available through the Python getattr protocol, and subentries are available through the getitem protocol via their Relative Distinguished Name (RDN).

Meaning if you had an Organizational Unit entry for Housewares and wanted to get the subentry "Betty Ford", it would appear like this (considering housewares is the Entry object):

      betty = housewares["cn=Betty Ford"]

Adding subentries

Adding subentries to an Entry object is done through the addSubentry method. Adding subentries is protected by the permission Create New Entry Objects.

addSubentry(rdn, [attrs,kw])

Add a new subentry identified by the rdn. The rdn MUST be a string in the form attr=value, such as ou=Housewares or cn=Davy Jones. The rest of the signature can be a combination of a dictionary of attributes passed in to attrs or keyword arguments. If no objectClass attribute is passed in, the default objectClass is top. The newly created Entry object is returned, wrapped in the acquisition context of its parent. Some example uses are:

       betty = housewares.addSubentry("cn=Betty Ford", {
                "objectClass": ["top", "person"],
                              "sn": "Ford",
               })

       clinic = betty.addSubentry("sn=Clinic",
                         objectClass=["top","place"],
                                              description="A good place to go..."
                      )

Deleting subentries

Deleting subentries from an Entry object is done through the deleteSubentry method. Deleting subentries is protected by the permission Delete Entry Objects.

deleteSubentry(entry)

You can either delete a subentry by its rdn, or by passing in the subentry object itself. Deletion is recursive and will delete everything below the specified entry from the LDAP server as well as the Entry object itself. Some examples uses are:

     betty.deleteSubentry("sn=Clinic")  # Delete by rdn (local id)

     housewares.deleteSubentry(betty)   # Delete by entry itself

Other Zope Interfaces supported

Entry objects are a combination of classes: The basic Entry class (either GenericEntry or TransactionalEntry at present), and one called Entry, which implements some Zope level Interfaces (of the programming kind). These include:

__bobo_traverse__ -- To traverse to subentries along the URL.
The Tree Protocol -- Allows Entry objects to be used automatically with the dtml-tree tag.
objectValues() -- Returns all of the subentries in a list.
objectIds() -- returns all of the RDN's of the subentries.
objectItems() -- returns a list of tuples in the form of (rdn, entry object).