# `ldap.asyncsearch` Stream-processing of large search results

With newer Python versions one might want to consider using `ldap.resiter` instead.

Changed in version 3.0: In Python 3.7 `async` is a reserved keyword. The module `ldap.async` has been renamed to `ldap.asyncsearch`. The old name `ldap.async` is still available for backwards compatibility.

Deprecated since version 3.0: The old name `ldap.async` is deprecated, but will not be removed until Python 3.6 reaches end-of-life.

## Classes

class ldap.asyncsearch.AsyncSearchHandler(l)

  Class for stream-processing LDAP search results

  Arguments:

  l

    LDAPObject instance

  afterFirstResult()

    Do anything you want right after successfully receiving but before processing first result

  postProcessing()

    Do anything you want after receiving and processing all results

  preProcessing()

    Do anything you want after starting search but before receiving and processing results

  processResults(ignoreResultsNumber=0, processResultsCount=0, timeout=-1)
    ignoreResultsNumber

      Don’t process the first ignoreResultsNumber results.

    processResultsCount

      If non-zero this parameters indicates the number of results processed is limited to processResultsCount.

    timeout

      See parameter timeout of ldap.LDAPObject.result()

  startSearch(searchRoot, searchScope, filterStr, attrList=None, attrsOnly=0, timeout=-1, sizelimit=0, serverctrls=None, clientctrls=None)
    searchRoot

      See parameter base of method LDAPObject.search()

    searchScope

      See parameter scope of method LDAPObject.search()

    filterStr

      See parameter filter of method LDAPObject.search()

    attrList=None

      See parameter attrlist of method LDAPObject.search()

    attrsOnly

      See parameter attrsonly of method LDAPObject.search()

    timeout

      Maximum time the server shall use for search operation

    sizelimit

      Maximum number of entries a server should return (request client-side limit)

    serverctrls

      list of server-side LDAP controls

    clientctrls

      list of client-side LDAP controls

class ldap.asyncsearch.List(l)

  Class for collecting all search results.

  This does not seem to make sense in the first place but think of retrieving exactly a certain portion of the available search results.

class ldap.asyncsearch.Dict(l)

  Class for collecting all search results into a dictionary {dn:entry}

class ldap.asyncsearch.IndexedDict(l, indexed_attrs=None)

  Class for collecting all search results into a dictionary {dn:entry} and maintain case-sensitive equality indexes to entries

class ldap.asyncsearch.LDIFWriter(l, writer_obj, headerStr='', footerStr='')

  Class for writing a stream LDAP search results to a LDIF file

  Arguments:

  l

    LDAPObject instance

  writer_obj

    Either a file-like object or a ldif.LDIFWriter instance used for output

## Examples

### Using ldap.asyncsearch.List

This example demonstrates how to use class ldap.asyncsearch.List for retrieving partial search results even though the exception `ldap.SIZELIMIT_EXCEEDED` was raised because a server side limit was hit.

    import sys,ldap,ldap.asyncsearch

    s = ldap.asyncsearch.List(
      ldap.initialize('ldap://localhost'),
    )

    s.startSearch(
      'dc=stroeder,dc=com',
      ldap.SCOPE_SUBTREE,
      '(objectClass=*)',
    )

    try:
      partial = s.processResults()
    except ldap.SIZELIMIT_EXCEEDED:
      sys.stderr.write('Warning: Server-side size limit exceeded.\n')
    else:
      if partial:
        sys.stderr.write('Warning: Only partial results received.\n')

    sys.stdout.write(
      '%d results received.\n' % (
        len(s.allResults)
      )
    )

### Using ldap.asyncsearch.LDIFWriter

This example demonstrates how to use class ldap.asyncsearch.LDIFWriter for writing search results as LDIF to stdout.

    import sys,ldap,ldap.asyncsearch

    s = ldap.asyncsearch.LDIFWriter(
      ldap.initialize('ldap://localhost:1390'),
      sys.stdout
    )

    s.startSearch(
      'dc=stroeder,dc=com',
      ldap.SCOPE_SUBTREE,
      '(objectClass=*)',
    )

    try:
      partial = s.processResults()
    except ldap.SIZELIMIT_EXCEEDED:
      sys.stderr.write('Warning: Server-side size limit exceeded.\n')
    else:
      if partial:
        sys.stderr.write('Warning: Only partial results received.\n')

    sys.stderr.write(
      '%d results received.\n' % (
        s.endResultBreak-s.beginResultsDropped
      )
    )