Future warning for Node.traverse().

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@8393 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

4 files changed, 45 insertions, 14 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index 85046057e..eefd87d41 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -20,7 +20,7 @@ Changes Since 0.15
 
 * General
 
-  - Dropped support for Python 2.6, 3.3 and 3.4 (work in progress).
+  - Dropped support for Python 2.6, 3.3 and 3.4
   - Docutils now supports Python 2.7 and Python 3.5+ natively
     (without conversion by ``2to3``).
   - Keep `backslash escapes`__ in the document tree. Backslash characters in
@@ -30,19 +30,25 @@ Changes Since 0.15
 
   __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism
 
-* docutils/utils/__init__.py
+* docutils/nodes.py
 
-  - unescape() definition moved to `nodes` to avoid circular import
-    dependency. Fixes [ 366 ].
+  - Speed up Node.next_node().
+  - Warn about Node.traverse() returning an iterator instead of a list
+    in future.
+
+* docutils/statemachine.py
+
+  - Patch [ 158 ]: Speed up patterns by saving compiled versions (eric89gxl)
 
 * docutils/transforms/universal.py
 
   - Fix [ 332 ]: Standard backslash escape for smartquotes.
   - Fix [ 342 ]: No escape in roles descending from `inline literal`.
 
-* docutils/statemachine.py
+* docutils/utils/__init__.py
 
-  - Patch [ 158 ]: Speed up patterns by saving compiled versions (eric89gxl)
+  - unescape() definition moved to `nodes` to avoid circular import
+    dependency. Fixes [ 366 ].
 
 * docutils/writers/latex2e/__init__.py:
 
@@ -79,6 +85,7 @@ Changes Since 0.15
   - Fix [ 359 ]: Test suite failes on Python 3.8. odt xml sorting.
     Use ElementTree instead of minidom.
 
+
 Release 0.15.1 (2019-07-24)
 ===========================
 
diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt
index 3529b15f6..1bceddf9f 100644
--- a/docutils/RELEASE-NOTES.txt
+++ b/docutils/RELEASE-NOTES.txt
@@ -23,16 +23,18 @@ Future changes
 ==============
 
 * The "latex" writer will wrap admonitions in a "DUclass" environment.
-  If your custom stylesheets modify "\DUadmonition" to style admonitions,
-  you will need to adapt them after upgrading to versions > 0.16.
+  Stylesheets modifying "\DUadmonition" will need to adapt.
+
   Styling commands using ``\docutilsrole`` prefix will be ignored
   in versions > 0.16 (see `Generating LaTeX with Docutils`__).
-  
+
   __ docs/user/latex.html#classes
 
 * Remove the `handle_io_errors` option from io.FileInput/Output.
   Used by Sphinx up to version 1.3.1, fixed in 1.3.2 (Nov 29, 2015).
 
+* Node.traverse() will return an iterator instead of a list.
+
 * Remove `utils.unique_combinations` (obsoleted by `itertools.combinations`).
 
 * The default HTML writer "html" with frontend ``rst2html.py`` may change
diff --git a/docutils/docutils/nodes.py b/docutils/docutils/nodes.py
index 267a22f3d..264679db9 100644
--- a/docutils/docutils/nodes.py
+++ b/docutils/docutils/nodes.py
@@ -33,6 +33,28 @@ if sys.version_info >= (3, 0):
     unicode = str  # noqa
     basestring = str  # noqa
 
+
+class _traversal_list():
+    # auxiliary class to report a FutureWarning
+    
+    def __init__(self, iterable):
+        self.nodes = list(iterable)
+
+    def __getattr__(self, name):
+        msg = ("The iterable returned by Node.traverse()\n    "
+               "will become an iterator instead of a list in "
+               "Docutils > 0.16.")
+        warnings.warn(msg, FutureWarning, stacklevel=2)
+        return getattr(self.nodes, name)
+    
+    def __iter__(self):
+        return iter(self.nodes)
+    
+    def __len__(self):
+        # used in Python 2.7 when typecasting to `list` or `tuple`
+        return len(self.nodes)
+
+
 # ==============================
 #  Functional Node Base Classes
 # ==============================
@@ -254,7 +276,7 @@ class Node(object):
         # value, the implementation returned a list up to v. 0.15. Some 3rd
         # party code still relies on this (e.g. Sphinx as of 2019-09-07).
         # Therefore, let's return a list until this is sorted out:
-        return list(self._traverse(condition, include_self,
+        return _traversal_list(self._traverse(condition, include_self,
                                    descend, siblings, ascend))
 
     def _traverse(self, condition=None, include_self=True, descend=True,
diff --git a/docutils/docutils/transforms/universal.py b/docutils/docutils/transforms/universal.py
index aca1af3e4..e0d1c32ff 100644
--- a/docutils/docutils/transforms/universal.py
+++ b/docutils/docutils/transforms/universal.py
@@ -144,7 +144,7 @@ class FilterMessages(Transform):
     default_priority = 870
 
     def apply(self):
-        for node in list(self.document.traverse(nodes.system_message)):
+        for node in tuple(self.document.traverse(nodes.system_message)):
             if node['level'] < self.document.reporter.report_level:
                 node.parent.remove(node)
 
@@ -176,7 +176,7 @@ class StripComments(Transform):
 
     def apply(self):
         if self.document.settings.strip_comments:
-            for node in list(self.document.traverse(nodes.comment)):
+            for node in tuple(self.document.traverse(nodes.comment)):
                 node.parent.remove(node)
 
 
@@ -194,9 +194,9 @@ class StripClassesAndElements(Transform):
         if self.document.settings.strip_elements_with_classes:
             self.strip_elements = set(
                 self.document.settings.strip_elements_with_classes)
-            # Iterate over a list as removing the current node
+            # Iterate over a tuple as removing the current node
             # corrupts the iterator returned by `traverse`:
-            for node in list(self.document.traverse(self.check_classes)):
+            for node in tuple(self.document.traverse(self.check_classes)):
                 node.parent.remove(node)
 
         if not self.document.settings.strip_classes: