[Freeipa-devel] Using the new LDAP code

[Petr Viktorin]

Hello,
A big refactoring of our LDAP code should be merged soon-ish now. Here's 
a summary for developers.


If you see these outside ipaldap.py, you're looking at deprecated API:
- methods with camelCaseNames
- methods with _s and _ext postfixes (modify_s, search_ext, ...)

The exception is client code and places where we don't want to read the 
schema (migration, AD). These are still limited to raw python-ldap for now.



The LDAPEntry class represents LDAP entries. It behaves like a 
dictionary of lists: entry.get(attrname) or entry[attrname] should 
always give you a list.

LDAPEntry.dn will give you the entry's DN.

Single-value attributes are represented as lists with a single value. 
(For now, some code still puts bare values instead of lists in entries, 
in that case you'll still get a bare value from get()/__getitem__. That 
should be fixed eventually.)
The "single_value" method gets a single value, with checking. Always use 
`entry.single_value('abc')` instead of `entry.get('abc')[0]`.
Also, single_value allows a default: `entry.single_value('abc', None)`.

LDAPEntry is case-insensitive and handles attributes with multiple 
names: entry['cn'] and entry['CN'] and entry['CommonName'] are equivalent.

IPA plugins traditionally use (dn, entry_attrs) pairs to represent 
entries. To make that work, iterating over an LDAPEntry will, for now, 
yield the DN and the entry itself. Always use keys() or values() when 
iterating over an entry.

LDAPEntry objects are tied to a connection. Do not create them directly, 
use a connection method like make_entry() or get_entry().


Speaking of connections, there still are two classes for those: ldap2 
and IPAdmin.
ldap2 is an API plugin created using the IPA settings. It works in 
Apache (per-thread connections). It also applies the default IPA 
settings (time & records limit).
Use IPAdmin if IPA is not installed yet (or when it's being 
uninstalled), or if you need to connect to a non-default server or bind 
as a user like the DM.

Besides the connecting code, both of these (will ideally) have the same 
API, based on the old ldap2. A rough summary:

- make_entry(dn, attrs)
- get_entry(dn)
- add_entry(entry)
- update_entry(entry)
- delete_entry(entry_or_dn)

- get_entries(base_dn, [scope, [filter, [attrs_list]]]): simple search
- find_entries: more powerful (and backwards-compatible) search
- make_filter & friends, unchanged from ldap2


ldap2's DN normalization – appending the suffix to DNs that don't end 
with it ­– is gone, you need to do that manually now.



That should be it, if you don't intend to hack on ipaldap itself or the 
ldapupdater. If you have any questions, ask! (Or look at the code :)

-- 
Petr³