1 files changed, 36 insertions, 0 deletions
diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py
index ec48009f4..a434f3a82 100644
--- a/sphinx/util/__init__.py
+++ b/sphinx/util/__init__.py
@@ -19,6 +19,7 @@ import posixpath
 import traceback
 from os import path
 from codecs import open
+from collections import deque
 
 import docutils
 from docutils.utils import relative_path
@@ -297,3 +298,38 @@ def format_exception_cut_frames(x=1):
     res += tbres[-x:]
     res += traceback.format_exception_only(typ, val)
     return ''.join(res)
+
+class PeekableIterator(object):
+    """
+    An iterator which wraps any iterable and makes it possible to peek to see
+    what's the next item.
+    """
+    def __init__(self, iterable):
+        self.remaining = deque()
+        self._iterator = iter(iterable)
+
+    def __iter__(self):
+        return self
+
+    def next(self):
+        """
+        Returns the next item from the iterator.
+        """
+        if self.remaining:
+            return self.remaining.popleft()
+        return self._iterator.next()
+
+    def push(self, item):
+        """
+        Pushes the `item` on the internal stack, it will be returned on the
+        next :meth:`next` call.
+        """
+        self.remaining.append(item)
+
+    def peek(self):
+        """
+        Returns the next item without changing the state of the iterator.
+        """
+        item = self.next()
+        self.push(item)
+        return item