[Lxml-checkins] r46537 - in lxml/trunk: doc src/lxml src/lxml/tests

[scoder at codespeak.net]

Author: scoder
Date: Thu Sep 13 15:10:02 2007
New Revision: 46537

Modified:
   lxml/trunk/doc/tutorial.txt
   lxml/trunk/src/lxml/etree.pyx
   lxml/trunk/src/lxml/tests/test_elementtree.py
Log:
ET 1.3 compatibility fixes: getiterator() returns a list, bool(element) writes a warning

Modified: lxml/trunk/doc/tutorial.txt
==============================================================================
--- lxml/trunk/doc/tutorial.txt	(original)
+++ lxml/trunk/doc/tutorial.txt	Thu Sep 13 15:10:02 2007
@@ -122,16 +122,15 @@
     >>> print child.tag
     child1
 
+    >>> print len(root)
+    3
+
     >>> for child in root:
     ...     print child.tag
     child1
     child2
     child3
 
-    >>> if root:
-    ...     print "root has children!"
-    root has children!
-
     >>> root.insert(0, etree.Element("child0"))
     >>> start = root[:1]
     >>> end   = root[-1:]
@@ -148,10 +147,17 @@
     child1
     child2
 
-Note how the last element was *moved* to a different position in the last
-example.  This is a difference from the original ElementTree (and from lists),
-where elements can sit in multiple positions of any number of trees.  In
-lxml.etree, elements can only sit in one position of one tree at a time.
+Prior to ElementTree 1.3 and lxml 2.0, you could also check the truth value of
+an Element to see if it has children, i.e. if the list of children is empty.
+This is no longer supported as people tend to find it surprising that a
+non-None reference to an existing Element can evaluate to False.  Instead, use
+``len(element)``, which is both more explicit and less error prone.
+
+Note in the examples that the last element was *moved* to a different position
+in the last example.  This is a difference from the original ElementTree (and
+from lists), where elements can sit in multiple positions of any number of
+trees.  In lxml.etree, elements can only sit in one position of one tree at a
+time.
 
 If you want to *copy* an element to a different position, consider creating an
 independent *deep copy* using the ``copy`` module from Python's standard

Modified: lxml/trunk/src/lxml/etree.pyx
==============================================================================
--- lxml/trunk/src/lxml/etree.pyx	(original)
+++ lxml/trunk/src/lxml/etree.pyx	Thu Sep 13 15:10:02 2007
@@ -865,6 +865,13 @@
 
     def __nonzero__(self):
         cdef xmlNode* c_node
+        import warnings
+        warnings.warn(
+            "The behavior of this method will change in future versions. "
+            "Use specific 'len(elem)' or 'elem is not None' test instead.",
+            FutureWarning
+            )
+        # emulate old behaviour
         c_node = _findChildBackwards(self._c_node, 0)
         return c_node != NULL
 
@@ -1066,8 +1073,8 @@
         return _elementTreeFactory(self._doc, None)
 
     def getiterator(self, tag=None):
-        """Iterate over all elements in the subtree in document order (depth
-        first pre-order), starting with this element.
+        """Returns a sequence 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.
@@ -1075,10 +1082,11 @@
         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 in favour of the ``el.iter()``
-        method.  In new code, use it only for backwards compatibility.
+        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.
         """
-        return ElementDepthFirstIterator(self, tag)
+        return list(ElementDepthFirstIterator(self, tag))
 
     def iter(self, tag=None):
         """Iterate over all elements in the subtree in document order (depth

Modified: lxml/trunk/src/lxml/tests/test_elementtree.py
==============================================================================
--- lxml/trunk/src/lxml/tests/test_elementtree.py	(original)
+++ lxml/trunk/src/lxml/tests/test_elementtree.py	Thu Sep 13 15:10:02 2007
@@ -2524,7 +2524,8 @@
         self.assert_(btree.getroot() is atree.getroot())
         self.assertEquals('Foo', atree.getroot().text)
 
-    def test_element_boolean(self):
+    def _test_element_boolean(self):
+        # deprecated as of ET 1.3/lxml 2.0
         etree = self.etree
         e = etree.Element('foo')
         self.assertEquals(False, bool(e))