[Lxml-checkins] r49906 - in lxml/trunk: . src/lxml

[scoder at codespeak.net]

Author: scoder
Date: Tue Dec 18 22:28:50 2007
New Revision: 49906

Modified:
   lxml/trunk/   (props changed)
   lxml/trunk/CHANGES.txt
   lxml/trunk/src/lxml/lxml.etree.pyx
Log:
 r3103 at delle:  sbehnel | 2007-12-18 10:11:28 +0100
 reverted getiterator() behaviour to returning a real iterator, method is now officially deprecated


Modified: lxml/trunk/CHANGES.txt
==============================================================================
--- lxml/trunk/CHANGES.txt	(original)
+++ lxml/trunk/CHANGES.txt	Tue Dec 18 22:28:50 2007
@@ -23,6 +23,13 @@
 Other changes
 -------------
 
+* The ``getiterator()`` method on Elements and ElementTrees was
+  reverted to return an iterator as it did in lxml 1.x.  The ET API
+  specification allows it to return either a sequence or an iterator,
+  and it traditionally returned a sequence in ET and an iterator in
+  lxml.  However, it is now deprecated in favour of the ``iter()``
+  method, which should be used in new code wherever possible.
+
 * The 'pretty printed' serialisation of ElementTree objects now
   appends a newline at the end of the document and also inserts
   newlines between the top-level processing instructions and comments

Modified: lxml/trunk/src/lxml/lxml.etree.pyx
==============================================================================
--- lxml/trunk/src/lxml/lxml.etree.pyx	(original)
+++ lxml/trunk/src/lxml/lxml.etree.pyx	Tue Dec 18 22:28:50 2007
@@ -1099,20 +1099,27 @@
         return _elementTreeFactory(self._doc, None)
 
     def getiterator(self, tag=None):
-        """Returns a sequence of all elements in the subtree in document order
-        (depth first pre-order), starting with this element.
+        """Returns a sequence or iterator of all elements in the subtree in
+        document order (depth first pre-order), starting with this
+        element.
 
-        Can be restricted to find only elements with a specific tag or from a
-        namespace.
+        Can be restricted to find only elements with a specific tag
+        (pass ``tag="xyz"``) or from a namespace (pass ``tag="{ns}*"``).
 
         You can also pass the Element, Comment, ProcessingInstruction and
         Entity factory functions to look only for the specific element type.
 
-        Note that this method previously returned an iterator, which diverged
-        from the original ElementTree behaviour.  If you want an efficient
-        iterator, use the ``el.iter()`` method instead.
+        Note that this method is deprecated as of ElementTree 1.3 and
+        lxml 2.0.  It returns an iterator in lxml, which diverges from
+        the original ElementTree behaviour.  If you want an efficient
+        iterator, use the ``element.iter()`` method instead.  You
+        should only use this method in new code if you require
+        backwards compatibility with older versions of lxml or
+        ElementTree.
+
+        @deprecated
         """
-        return list(ElementDepthFirstIterator(self, tag))
+        return ElementDepthFirstIterator(self, tag)
 
     def iter(self, tag=None):
         """Iterate over all elements in the subtree in document order (depth
@@ -1456,17 +1463,29 @@
         return path
 
     def getiterator(self, tag=None):
-        """Creates an iterator for the root element. The iterator loops over all elements
-        in this tree, in document order.
+        """Returns a sequence or iterator of all elements in document order
+        (depth first pre-order), starting with the root element.
+
+        Can be restricted to find only elements with a specific tag
+        (pass ``tag="xyz"`` or ``tag="{ns}xyz"``) or from a namespace
+        (pass ``tag="{ns}*"``).
 
-        Note that this method is deprecated in favour of the ``el.iter()``
-        method.  In new code, use it only if you require backwards
-        compatibility.
+        You can also pass the Element, Comment, ProcessingInstruction and
+        Entity factory functions to look only for the specific element type.
+
+        Note that this method is deprecated as of ElementTree 1.3 and
+        lxml 2.0.  It returns an iterator in lxml, which diverges from
+        the original ElementTree behaviour.  If you want an efficient
+        iterator, use the ``tree.iter()`` method instead.  You should
+        only use this method in new code if you require backwards
+        compatibility with older versions of lxml or ElementTree.
+
+        @deprecated
         """
         root = self.getroot()
         if root is None:
             return ()
-        return root.iter(tag)
+        return root.getiterator(tag)
 
     def iter(self, tag=None):
         """Creates an iterator for the root element.  The iterator loops over
@@ -1479,7 +1498,7 @@
 
     def find(self, path):
         """Finds the first toplevel element with given tag.  Same as
-        getroot().find(path).
+        ``tree.getroot().find(path)``.
         """
         self._assertHasRoot()
         root = self.getroot()