put-back-iterator 0.1.0a0__tar.gz → 0.1.0a1__tar.gz

{put_back_iterator-0.1.0a0 → put_back_iterator-0.1.0a1}/PKG-INFO

@@ -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.0a0 → put_back_iterator-0.1.0a1}/README.md

@@ -19,6 +19,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
@@ -41,7 +43,7 @@ print(list(it))  # [1, 2, 3]
 
 ### 1. **Parsing/Tokenizing**
 
-```python
+```
 tokens = PutBackIterator(tokenize(source_code))
 while tokens.has_next():
     token = next(tokens)
@@ -54,7 +56,7 @@ while tokens.has_next():
 
 ### 2. **Backtracking Algorithms**
 
-```python
+```
 def backtrack(it):
     item = next(it)
     if not is_valid(item):
@@ -64,7 +66,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.0a0 → put_back_iterator-0.1.0a1}/put_back_iterator.egg-info/PKG-INFO

@@ -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.0a0 → put_back_iterator-0.1.0a1}/put_back_iterator.egg-info/SOURCES.txt

@@ -6,4 +6,5 @@ setup.cfg
 put_back_iterator.egg-info/PKG-INFO
 put_back_iterator.egg-info/SOURCES.txt
 put_back_iterator.egg-info/dependency_links.txt
+put_back_iterator.egg-info/requires.txt
 put_back_iterator.egg-info/top_level.txt

put_back_iterator-0.1.0a1/put_back_iterator.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[:python_version < "3.5"]
+typing

put_back_iterator-0.1.0a1/put_back_iterator.py

@@ -0,0 +1,130 @@
+# 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')
+
+
+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):
+        # 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_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)
+            if element_or_sentinel is end_sentinel:
+                if default is DEFAULT_PLACEHOLDER:
+                    raise StopIteration
+                else:
+                    return default
+            else:
+                return element_or_sentinel
+
+    if sys.version_info < (3,):
+        next = next_implementation
+    else:
+        __next__ = next_implementation
+
+    def put_back(self, 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):
+        # 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()
+            element_or_sentinel = next(self, end_sentinel)
+            if element_or_sentinel is end_sentinel:
+                return False
+            else:
+                self.put_back_stack.append(element_or_sentinel)
+                return True

{put_back_iterator-0.1.0a0 → put_back_iterator-0.1.0a1}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools>=61.0"]
+requires = ["setuptools"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "put-back-iterator"
-version = "0.1.0a0"
+version = "0.1.0a1"
 description = "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."
 readme = "README.md"
 requires-python = ">=2"
@@ -18,6 +18,7 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
+    "typing; python_version < '3.5'"
 ]
 
 

put_back_iterator-0.1.0a0/put_back_iterator.py

@@ -1,47 +0,0 @@
-from __future__ import absolute_import, division, print_function
-import sys
-
-
-_DEFAULT_PLACEHOLDER = object()
-
-class PutBackIterator:
-    def __init__(self, iterable):
-        self._iterator = iter(iterable)
-        self._put_back_stack = []
-
-    def __iter__(self):
-        return self
-
-    def _next_impl(self, default=_DEFAULT_PLACEHOLDER):
-        if self._put_back_stack:
-            return self._put_back_stack.pop()
-        else:
-            end_sentinel = object()
-            element_or_sentinel = next(self._iterator, end_sentinel)
-            if element_or_sentinel is end_sentinel:
-                if default is _DEFAULT_PLACEHOLDER:
-                    raise StopIteration
-                else:
-                    return default
-            else:
-                return element_or_sentinel
-
-    if sys.version_info < (3,):
-        next = _next_impl
-    else:
-        __next__ = _next_impl
-
-    def put_back(self, element):
-        self._put_back_stack.append(element)
-
-    def has_next(self):
-        if self._put_back_stack:
-            return True
-        else:
-            end_sentinel = object()
-            element_or_sentinel = next(self, end_sentinel)
-            if element_or_sentinel is end_sentinel:
-                return False
-            else:
-                self._put_back_stack.append(element_or_sentinel)
-                return True