From 6fa3f3c28a4f2e1fecf9eb4e1770bb28144c2afb Mon Sep 17 00:00:00 2001
From: Stefan Behnel <stefan_ml@behnel.de>
Date: Mon, 13 Aug 2012 10:11:23 +0200
Subject: document wildcard iteration

---
 doc/tutorial.txt | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

(limited to 'doc/tutorial.txt')

diff --git a/doc/tutorial.txt b/doc/tutorial.txt
index 926b3a44..7af1ec46 100644
--- a/doc/tutorial.txt
+++ b/doc/tutorial.txt
@@ -479,7 +479,7 @@ serialised the tree to XML:
     another - Child 3
 
 If you know you are only interested in a single tag, you can pass its name to
-``iter()`` to have it filter for you.  Since lxml 2.4, you can also pass more
+``iter()`` to have it filter for you.  Since lxml 3.0, you can also pass more
 than one tag to intercept on multiple tags during iteration.
 
 .. sourcecode:: pycon
@@ -528,6 +528,9 @@ make sure only Element objects are returned, you can pass the
     ...     print(element.text)
     &#234;
 
+Note that passing a wildcard ``"*"`` tag name will also yield all
+``Element`` nodes (and only elements).
+
 In lxml.etree, elements provide `further iterators`_ for all directions in the
 tree: children, parents (or rather ancestors) and siblings.
 
@@ -1118,6 +1121,34 @@ You can also use XPath with fully qualified names:
     >>> print(results[0].tag)
     {http://www.w3.org/1999/xhtml}body
 
+For convenience, you can use ``"*"`` wildcards in all iterators of lxml.etree,
+both for tag names and namespaces:
+
+.. sourcecode:: pycon
+
+    >>> for el in xhtml.iter('*'): print(el.tag)   # any element
+    {http://www.w3.org/1999/xhtml}html
+    {http://www.w3.org/1999/xhtml}body
+    >>> for el in xhtml.iter('{http://www.w3.org/1999/xhtml}*'): print(el.tag)
+    {http://www.w3.org/1999/xhtml}html
+    {http://www.w3.org/1999/xhtml}body
+    >>> for el in xhtml.iter('{*}body'): print(el.tag)
+    {http://www.w3.org/1999/xhtml}body
+
+To look for elements that do not have a namespace, either use the
+plain tag name or provide the empty namespace explicitly:
+
+.. sourcecode:: pycon
+
+    >>> [ el.tag for el in xhtml.iter('{http://www.w3.org/1999/xhtml}body') ]
+    ['{http://www.w3.org/1999/xhtml}body']
+    >>> [ el.tag for el in xhtml.iter('body') ]
+    []
+    >>> [ el.tag for el in xhtml.iter('{}body') ]
+    []
+    >>> [ el.tag for el in xhtml.iter('{}*') ]
+    []
+
 
 The E-factory
 =============
-- 
cgit v1.2.1