New convenience methods LDAPObject.read_s() and LDAPObject.find_uniqu…

…e_entry()

CHANGES

@@ -6,6 +6,8 @@ Changes since 2.4.16:
 Lib/
 * New convenience function ldap.dn.is_dn()
 * New convenience function ldap.escape_str()
+* New convenience methods LDAPObject.read_s() and
+  LDAPObject.find_unique_entry()
 
 Modules/
 
@@ -1108,4 +1110,4 @@ Released 2.0.0pre02 2002-02-01
 ----------------------------------------------------------------
 Released 1.10alpha3 2000-09-19
 
-$Id: CHANGES,v 1.321 2014/05/20 20:27:55 stroeder Exp $
+$Id: CHANGES,v 1.322 2014/07/25 17:08:56 stroeder Exp $

Lib/ldap/__init__.py

@@ -3,7 +3,7 @@
 
 See http://www.python-ldap.org/ for details.
 
-$Id: __init__.py,v 1.92 2014/05/20 20:44:28 stroeder Exp $
+$Id: __init__.py,v 1.93 2014/07/25 17:08:56 stroeder Exp $
 """
 
 # This is also the overall release version number
@@ -84,6 +84,8 @@ def release(self):
 
 from functions import open,initialize,init,get_option,set_option,escape_str
 
+from ldapobject import NO_UNIQUE_ENTRY
+
 from ldap.dn import explode_dn,explode_rdn,str2dn,dn2str
 del str2dn
 del dn2str

Lib/ldap/ldapobject.py

@@ -3,7 +3,7 @@
 
 See http://www.python-ldap.org/ for details.
 
-\$Id: ldapobject.py,v 1.138 2014/02/19 20:05:57 stroeder Exp $
+\$Id: ldapobject.py,v 1.139 2014/07/25 17:08:56 stroeder Exp $
 
 Compability:
 - Tested with Python 2.0+ but should work with Python 1.5.x
@@ -41,6 +41,13 @@
 from ldap import LDAPError
 
 
+class NO_UNIQUE_ENTRY(ldap.NO_SUCH_OBJECT):
+  """
+  Exception raised if a LDAP search returned more than entry entry
+  although assumed to return a unique single search result.
+  """
+
+
 class SimpleLDAPObject:
   """
   Drop-in wrapper class around _ldap.LDAPObject
@@ -638,24 +645,59 @@ def search_subschemasubentry_s(self,dn=''):
     except IndexError:
       return None
 
+  def read_s(self,dn,filterstr=None,attrlist=None,serverctrls=None,clientctrls=None,timeout=-1):
+    """
+    Reads and returns a single entry specified by `dn'.
+    
+    Other attributes just like those passed to `search_ext_s()'
+    """
+    r = self.search_ext_s(
+      dn,
+      ldap.SCOPE_BASE,
+      filterstr or '(objectClass=*)',
+      attrlist=attrlist,
+      serverctrls=serverctrls,
+      clientctrls=clientctrls,
+      timeout=timeout,
+    )
+    if r:
+      return r[0][1]
+    else:
+      return ldap.NO_SUCH_OBJECT('Empty search result reading %s' % (repr(dn)))
+
   def read_subschemasubentry_s(self,subschemasubentry_dn,attrs=None):
     """
     Returns the sub schema sub entry's data
     """
-    attrs = attrs or SCHEMA_ATTRS
     try:
-      r = self.search_s(
-        subschemasubentry_dn,ldap.SCOPE_BASE,
-        '(objectClass=subschema)',
-        attrs
+      subschemasubentry = self.read_s(
+        subschemasubentry_dn,
+        filterstr='(objectClass=subschema)',
+        attrlist=attrs or SCHEMA_ATTRS
       )
     except ldap.NO_SUCH_OBJECT:
       return None
     else:
-      if r:
-        return r[0][1]
-      else:
-        return None
+      return subschemasubentry
+
+  def find_unique_entry(self,base,scope=ldap.SCOPE_SUBTREE,filterstr='(objectClass=*)',attrlist=None,attrsonly=0,serverctrls=None,clientctrls=None,timeout=-1):
+    """
+    Returns a unique entry, raises exception if not unique
+    """
+    r = self.search_ext_s(
+      base,
+      scope,
+      filterstr,
+      attrlist=attrlist or ['*'],
+      attrsonly=attrsonly,
+      serverctrls=serverctrls,
+      clientctrls=clientctrls,
+      timeout=timeout,
+      sizelimit=2,
+    )
+    if len(r)!=1:
+      raise NO_UNIQUE_ENTRY('No or non-unique search result for %s' % (repr(filterstr)))
+    return r[0]
 
 
 class NonblockingLDAPObject(SimpleLDAPObject):