Add getFirstElementCustomFilter to AdvancedHTMLParser and AdvancedTag. They find the FIRST item matching given criteria.

Author: kata198

AdvancedHTMLParser/Parser.py

@@ -392,6 +392,33 @@ def getElementsCustomFilter(self, filterFunc, root='root'):
             elements += self.getElementsCustomFilter(filterFunc, child)
         return TagCollection(elements)
 
+
+    def getFirstElementCustomFilter(self, filterFunc, root='root'):
+        '''
+            getFirstElementCustomFilter - Scan elements using a provided function, stop and return the first match.
+
+                @see getElementsCustomFilter to match multiple elements
+
+            @param filterFunc <function>(node) - A function that takes an AdvancedTag as an argument, and returns True if some arbitrary criteria is met
+
+            @return - An AdvancedTag of the node that matched, or None if no match.
+        '''
+        (root, isFromRoot) = self._handleRootArg(root)
+
+        elements = []
+
+        if isFromRoot is True and filterFunc(root) is True:
+            return root
+
+        for child in root.children:
+            if filterFunc(child) is True:
+                return child
+            subRet = self.getFirstElementCustomFilter(filterFunc, child)
+            if subRet:
+                return subRet
+
+        return None
+
     def contains(self, em):
         '''
             Checks if #em is found anywhere within this element tree

AdvancedHTMLParser/Tags.py

@@ -939,6 +939,8 @@ def getElementsCustomFilter(self, filterFunc):
             @param filterFunc <function> - A function or lambda expression that should return "True" if the passed node matches criteria.
 
             @return - TagCollection of matching results
+
+            @see getFirstElementCustomFilter
         '''
         elements = []
 
@@ -949,6 +951,29 @@ def getElementsCustomFilter(self, filterFunc):
 
         return TagCollection(elements)
 
+    def getFirstElementCustomFilter(self, filterFunc):
+        '''
+            getFirstElementCustomFilter - Gets the first element which matches a given filter func.
+
+                Scans first child, to the bottom, then next child to the bottom, etc. Does not include "self" node.
+
+            @param filterFunc <function> - A function or lambda expression that should return "True" if the passed node matches criteria.
+
+            @return <AdvancedTag/None> - First match, or None
+
+            @see getElementsCustomFilter
+        '''
+
+        for child in self.children:
+            if filterFunc(child) is True:
+                return child
+
+            childSearchResult = child.getFirstElementCustomFilter(filterFunc)
+            if childSearchResult is not None:
+                return childSearchResult
+
+        return None
+
     def getPeersByAttr(self, attrName, attrValue):
         '''
             getPeersByAttr - Gets peers (elements on same level) which match an attribute/value combination.

tests/AdvancedHTMLParserTests/test_CustomFilter.py

@@ -126,6 +126,27 @@ def searchFunc(node):
         assert len(results) == 1
         assert results[0].id == 'item4'
 
+    def test_oneElementCustomFilter(self):
+
+        parser = self.parser
+
+        def searchFunc(node):
+            return bool(node.hasClass('three'))
+
+
+        firstThreeNode = parser.getFirstElementCustomFilter(searchFunc)
+
+        assert firstThreeNode , 'Expected to get a node with class="three" on AdvancedHTMLParser.getFirstElementCustomFilter'
+        assert firstThreeNode.id == 'item4' , 'Expected to get id="item4"'
+
+        bodyNode = parser.getElementsByTagName('body')[0]
+        assert bodyNode , 'Failed to find body node'
+
+        firstThreeNode = bodyNode.getFirstElementCustomFilter(searchFunc)
+
+        assert firstThreeNode , 'Expected to get a node with class="three" on AdvancedTag.getFirstElementCustomFilter'
+        assert firstThreeNode.id == 'item4' , 'Expected to get id="item4"'
+
 
 
 if __name__ == '__main__':