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", ["[email protected]", "[email protected]"])
- setattrs([kwdict, kw])
- Takes either a mapping argument or
keyword arguments. Or both. Example:
entry.setattrs({"sn": "Bazzo"}, mail=["[email protected], "[email protected]"])
- 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 asou=Housewares
orcn=Davy Jones
. The rest of the signature can be a combination of a dictionary of attributes passed in toattrs
or keyword arguments. If noobjectClass
attribute is passed in, the default objectClass istop
. 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
).