diff --git a/Doc/reference/ldap-async.rst b/Doc/reference/ldap-async.rst index 59a34f4..76245f6 100644 --- a/Doc/reference/ldap-async.rst +++ b/Doc/reference/ldap-async.rst @@ -1,49 +1,60 @@ -************************************************************** -:py:mod:`ldap.async` Stream-processing of large search results -************************************************************** +******************************************************************** +:py:mod:`ldap.asyncsearch` Stream-processing of large search results +******************************************************************** -.. py:module:: ldap.async +.. py:module:: ldap.asyncsearch :synopsis: Framework for stream-processing of large search results. With newer Python versions one might want to consider using :py:mod:`ldap.resiter` instead. +.. versionchanged:: 3.0 + In Python 3.7 ``async`` is a reserved keyword. The module + :py:mod:`ldap.async` has been renamed to :py:mod:`ldap.asyncsearch`. The + old name :py:mod:`ldap.async` is still available for backwards + compatibility. + +.. deprecated:: 3.0 + The old name :py:mod:`ldap.async` is deprecated, but will not be removed + until Python 3.6 reaches end-of-life. + + Classes ======= -.. autoclass:: ldap.async.AsyncSearchHandler +.. autoclass:: ldap.asyncsearch.AsyncSearchHandler :members: -.. autoclass:: ldap.async.List +.. autoclass:: ldap.asyncsearch.List :members: -.. autoclass:: ldap.async.Dict +.. autoclass:: ldap.asyncsearch.Dict :members: -.. autoclass:: ldap.async.IndexedDict +.. autoclass:: ldap.asyncsearch.IndexedDict :members: -.. autoclass:: ldap.async.LDIFWriter +.. autoclass:: ldap.asyncsearch.LDIFWriter :members: -.. _ldap.async-example: +.. _ldap.asyncsearch-example: Examples ======== -.. _ldap.async-example.List: +.. _ldap.asyncsearch-example.List: -Using ldap.async.List -^^^^^^^^^^^^^^^^^^^^^ +Using ldap.asyncsearch.List +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This example demonstrates how to use class ldap.async.List for +This example demonstrates how to use class ldap.asyncsearch.List for retrieving partial search results even though the exception :exc:`ldap.SIZELIMIT_EXCEEDED` was raised because a server side limit was hit. :: - import sys,ldap,ldap.async + import sys,ldap,ldap.asyncsearch - s = ldap.async.List( + s = ldap.asyncsearch.List( ldap.initialize('ldap://localhost'), ) @@ -67,17 +78,17 @@ retrieving partial search results even though the exception ) ) -.. _ldap.async-example.LDIFWriter: +.. _ldap.asyncsearch-example.LDIFWriter: -Using ldap.async.LDIFWriter -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Using ldap.asyncsearch.LDIFWriter +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This example demonstrates how to use class ldap.async.LDIFWriter +This example demonstrates how to use class ldap.asyncsearch.LDIFWriter for writing search results as LDIF to stdout. :: - import sys,ldap,ldap.async + import sys,ldap,ldap.asyncsearch - s = ldap.async.LDIFWriter( + s = ldap.asyncsearch.LDIFWriter( ldap.initialize('ldap://localhost:1390'), sys.stdout ) diff --git a/Doc/spelling_wordlist.txt b/Doc/spelling_wordlist.txt index 70c07e6..925ddc3 100644 --- a/Doc/spelling_wordlist.txt +++ b/Doc/spelling_wordlist.txt @@ -1,5 +1,6 @@ args async +asyncsearch attr attrlist attrList diff --git a/Lib/ldap/async.py b/Lib/ldap/async.py index 23c5660..1d4505b 100644 --- a/Lib/ldap/async.py +++ b/Lib/ldap/async.py @@ -1,283 +1,15 @@ """ -ldap.async - handle async LDAP operations +ldap.asyncsearch - handle async LDAP search operations See https://www.python-ldap.org/ for details. """ +import warnings -import ldap +from ldap.asyncsearch import * +from ldap.asyncsearch import __version__ -from ldap import __version__ - -SEARCH_RESULT_TYPES = set([ - ldap.RES_SEARCH_ENTRY, - ldap.RES_SEARCH_RESULT, - ldap.RES_SEARCH_REFERENCE, -]) - -ENTRY_RESULT_TYPES = set([ - ldap.RES_SEARCH_ENTRY, - ldap.RES_SEARCH_RESULT, -]) - - -class WrongResultType(Exception): - - def __init__(self,receivedResultType,expectedResultTypes): - self.receivedResultType = receivedResultType - self.expectedResultTypes = expectedResultTypes - Exception.__init__(self) - - def __str__(self): - return 'Received wrong result type %s (expected one of %s).' % ( - self.receivedResultType, - ', '.join(self.expectedResultTypes), - ) - - -class AsyncSearchHandler: - """ - Class for stream-processing LDAP search results - - Arguments: - - l - LDAPObject instance - """ - - def __init__(self,l): - self._l = l - self._msgId = None - self._afterFirstResult = 1 - - def startSearch( - self, - 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 - """ - self._msgId = self._l.search_ext( - searchRoot,searchScope,filterStr, - attrList,attrsOnly,serverctrls,clientctrls,timeout,sizelimit - ) - self._afterFirstResult = 1 - return # startSearch() - - def preProcessing(self): - """ - Do anything you want after starting search but - before receiving and processing results - """ - - def afterFirstResult(self): - """ - Do anything you want right after successfully receiving but before - processing first result - """ - - def postProcessing(self): - """ - Do anything you want after receiving and processing all results - """ - - def processResults(self,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() - """ - self.preProcessing() - result_counter = 0 - end_result_counter = ignoreResultsNumber+processResultsCount - go_ahead = 1 - partial = 0 - self.beginResultsDropped = 0 - self.endResultBreak = result_counter - try: - result_type,result_list = None,None - while go_ahead: - while result_type is None and not result_list: - result_type,result_list,result_msgid,result_serverctrls = self._l.result3(self._msgId,0,timeout) - if self._afterFirstResult: - self.afterFirstResult() - self._afterFirstResult = 0 - if not result_list: - break - if result_type not in SEARCH_RESULT_TYPES: - raise WrongResultType(result_type,SEARCH_RESULT_TYPES) - # Loop over list of search results - for result_item in result_list: - if result_counter