put-back-iterator 0.1.0a0__py2.py3-none-any.whl → 0.1.0a1__py2.py3-none-any.whl

{put_back_iterator-0.1.0a0.dist-info → put_back_iterator-0.1.0a1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: put-back-iterator
-Version: 0.1.0a0
+Version: 0.1.0a1
 Summary: A drop-in replacement for `iter(iterable)` that allows **putting items back** after consuming them. Ideal for parsing, lexing, and other scenarios requiring lookahead or backtracking.
 Author-email: Jifeng Wu <jifengwu2k@gmail.com>
 License-Expression: MIT
@@ -12,6 +12,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=2
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: typing; python_version < "3.5"
 Dynamic: license-file
 
 # `put-back-iterator`
@@ -35,6 +36,8 @@ This package solves it with:
 ## Quick Start
 
 ```python
+# coding=utf-8
+from __future__ import print_function
 from put_back_iterator import PutBackIterator
 
 # Wrap any iterable
@@ -57,7 +60,7 @@ print(list(it))  # [1, 2, 3]
 
 ### 1. **Parsing/Tokenizing**
 
-```python
+```
 tokens = PutBackIterator(tokenize(source_code))
 while tokens.has_next():
     token = next(tokens)
@@ -70,7 +73,7 @@ while tokens.has_next():
 
 ### 2. **Backtracking Algorithms**
 
-```python
+```
 def backtrack(it):
     item = next(it)
     if not is_valid(item):
@@ -80,7 +83,7 @@ def backtrack(it):
 
 ### 3. **Stream Processing**
 
-```python
+```
 for chunk in PutBackIterator(stream):
     if needs_retry(chunk):
         chunk = modify(chunk)

put_back_iterator-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,6 @@
+put_back_iterator.py,sha256=YaWSHy7WdrMHkfKudP6sCyBN8KwwfxwzIIqrt2x3Pfo,4336
+put_back_iterator-0.1.0a1.dist-info/licenses/LICENSE,sha256=FZ9XWedK_wQ4wfqVanrQVQpArRHDkxwxic2rgii1pZg,1066
+put_back_iterator-0.1.0a1.dist-info/METADATA,sha256=oEMOGzBHbBlJJY5WTmoIHnWaEqso180qX1jKQZmXxYM,3089
+put_back_iterator-0.1.0a1.dist-info/WHEEL,sha256=JNWh1Fm1UdwIQV075glCn4MVuCRs0sotJIq-J6rbxCU,109
+put_back_iterator-0.1.0a1.dist-info/top_level.txt,sha256=8XJh5rF6eOPUkwrmXZutOmEHGnbXK6VqPPp6mrvkrs4,18
+put_back_iterator-0.1.0a1.dist-info/RECORD,,

put_back_iterator.py

@@ -1,25 +1,87 @@
-from __future__ import absolute_import, division, print_function
+# coding=utf-8
+# Copyright (c) 2025 Jifeng Wu
+# Licensed under the MIT License. See LICENSE file in the project root for full license information.
 import sys
+from typing import Iterable, Iterator, List, TypeVar
 
+DEFAULT_PLACEHOLDER = object()
+T = TypeVar('T')
 
-_DEFAULT_PLACEHOLDER = object()
 
-class PutBackIterator:
+class PutBackIterator(Iterator[T]):
+    """A drop-in replacement for built-in iterators that supports putting items back.
+
+    This iterator wraps any iterable and provides additional functionality to
+    push consumed items back into the iterator for later consumption. Ideal for
+    parsing, lexing, and other scenarios requiring lookahead or backtracking.
+
+    Args:
+        iterable: Any iterable object (list, string, generator, etc.) to wrap.
+
+    Example:
+        >>> it = PutBackIterator([1, 2, 3])
+        >>> next(it)
+        1
+        >>> it.put_back(1)
+        >>> list(it)
+        [1, 2, 3]
+
+    Attributes:
+        iterator (Iterator[T]): The underlying iterator
+        put_back_stack (List[T]): Stack for items that have been put back
+    """
+    __slots__ = (
+        'iterator',
+        'put_back_stack'
+    )
+
     def __init__(self, iterable):
-        self._iterator = iter(iterable)
-        self._put_back_stack = []
+        # type: (Iterable[T]) -> None
+        """Initialize the PutBackIterator with an iterable.
+
+        Args:
+            iterable: Any object that can be iterated over
+        """
+        self.iterator = iter(iterable)  # type: Iterator[T]
+        self.put_back_stack = []  # type: List[T]
 
     def __iter__(self):
+        # type: () -> PutBackIterator[T]
+        """
+        Return the iterator object itself.
+
+        Returns:
+            PutBackIterator[T]: The current iterator instance.
+
+        This makes PutBackIterator compatible with the iterator protocol,
+        so it can be used directly in for-loops and other iterable contexts.
+        """
         return self
 
-    def _next_impl(self, default=_DEFAULT_PLACEHOLDER):
-        if self._put_back_stack:
-            return self._put_back_stack.pop()
+    def next_implementation(self, default=DEFAULT_PLACEHOLDER):
+        """
+        Return the next item from the iterator, considering any put-back items.
+
+        Args:
+            default: Optional; a value to return if the iterator is exhausted.
+                     If not provided and no items remain, raises StopIteration.
+
+        Returns:
+            T: The next item from the put-back stack (if not empty), or the underlying iterator.
+
+        Raises:
+            StopIteration: If there are no more items and no default is provided.
+
+        Notes:
+            This method underlies both the Python 2 and 3 iterator protocol methods.
+        """
+        if self.put_back_stack:
+            return self.put_back_stack.pop()
         else:
             end_sentinel = object()
-            element_or_sentinel = next(self._iterator, end_sentinel)
+            element_or_sentinel = next(self.iterator, end_sentinel)
             if element_or_sentinel is end_sentinel:
-                if default is _DEFAULT_PLACEHOLDER:
+                if default is DEFAULT_PLACEHOLDER:
                     raise StopIteration
                 else:
                     return default
@@ -27,15 +89,36 @@ class PutBackIterator:
                 return element_or_sentinel
 
     if sys.version_info < (3,):
-        next = _next_impl
+        next = next_implementation
     else:
-        __next__ = _next_impl
+        __next__ = next_implementation
 
     def put_back(self, element):
-        self._put_back_stack.append(element)
+        # type: (T) -> None
+        """
+        Put an item back into the iterator to be returned on the next call to `next()`.
+
+        Args:
+            element (T): The item to put back onto the iterator.
+
+        Notes:
+            Items are put back in a last-in, first-out (LIFO) order. Calling `put_back()` multiple times will return those items in reverse order of addition.
+        """
+        self.put_back_stack.append(element)
 
     def has_next(self):
-        if self._put_back_stack:
+        # type: () -> bool
+        """
+        Check whether the iterator has at least one more item to yield, without consuming it.
+
+        Returns:
+            bool: True if there is another item available, False otherwise.
+
+        Notes:
+            If there is no item in the put-back stack, this method advances
+            the underlying iterator once for lookahead, puts the value back if found, and then returns the result.
+        """
+        if self.put_back_stack:
             return True
         else:
             end_sentinel = object()
@@ -43,5 +126,5 @@ class PutBackIterator:
             if element_or_sentinel is end_sentinel:
                 return False
             else:
-                self._put_back_stack.append(element_or_sentinel)
+                self.put_back_stack.append(element_or_sentinel)
                 return True

put_back_iterator-0.1.0a0.dist-info/RECORD

@@ -1,6 +0,0 @@
-put_back_iterator.py,sha256=2ME12t-aK1xpCMwAae0yVTrFYIWQPBdNC3emHUpt7JI,1365
-put_back_iterator-0.1.0a0.dist-info/licenses/LICENSE,sha256=FZ9XWedK_wQ4wfqVanrQVQpArRHDkxwxic2rgii1pZg,1066
-put_back_iterator-0.1.0a0.dist-info/METADATA,sha256=GGca8R3UzTev5VB4uBbewobeaql8BeVC6SXrYVxXhLc,3008
-put_back_iterator-0.1.0a0.dist-info/WHEEL,sha256=JNWh1Fm1UdwIQV075glCn4MVuCRs0sotJIq-J6rbxCU,109
-put_back_iterator-0.1.0a0.dist-info/top_level.txt,sha256=8XJh5rF6eOPUkwrmXZutOmEHGnbXK6VqPPp6mrvkrs4,18
-put_back_iterator-0.1.0a0.dist-info/RECORD,,