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

put_back_iterator-0.1.0a0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: put-back-iterator
+Version: 0.1.0a0
+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
+Project-URL: Homepage, https://github.com/jifengwu2k/put-back-iterator
+Project-URL: Bug Tracker, https://github.com/jifengwu2k/put-back-iterator/issues
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=2
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# `put-back-iterator`
+
+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.
+
+## Why Use This?
+
+Python's built-in iterators don't support pushing items back, forcing workarounds like:
+
+- Rebuilding iterators with `itertools.chain`
+- Using lists/deques as buffers
+- Complex state tracking
+
+This package solves it with:
+
+- ✅ **Simple API**: `.put_back(item)` and `.has_next()`
+- ✅ **Compatibility with `iter(iterable)`**: Works with any iterable (`str`, `list`, generators, etc.)
+- ✅ **Python 2/3 compatible**
+
+## Quick Start
+
+```python
+from put_back_iterator import PutBackIterator
+
+# Wrap any iterable
+it = PutBackIterator([1, 2, 3])
+
+# Consume an item
+print(next(it))  # 1
+
+# Put it back for later
+it.put_back(1)
+
+# Check if more items exist (without consuming)
+print(it.has_next())  # True
+
+# Iterate as usual
+print(list(it))  # [1, 2, 3]
+```
+
+## Use Cases
+
+### 1. **Parsing/Tokenizing**
+
+```python
+tokens = PutBackIterator(tokenize(source_code))
+while tokens.has_next():
+    token = next(tokens)
+    if token == 'IF':
+        # Peek ahead without consuming
+        if tokens.has_next() and next(tokens) == 'EOF':
+            tokens.put_back('EOF')
+            handle_incomplete_if()
+```
+
+### 2. **Backtracking Algorithms**
+
+```python
+def backtrack(it):
+    item = next(it)
+    if not is_valid(item):
+        it.put_back(item)  # Try alternative path
+        return fallback()
+```
+
+### 3. **Stream Processing**
+
+```python
+for chunk in PutBackIterator(stream):
+    if needs_retry(chunk):
+        chunk = modify(chunk)
+        it.put_back(chunk)  # Reprocess
+```
+
+## API Reference
+
+### **`PutBackIterator(iterable)`** Wraps an iterable.,Compatible with `iter(iterable)`.
+
+### Methods
+
+- **`.put_back(item: T) -> None`** Pushes an item back into the iterator (LIFO order).
+- **`.has_next() -> bool`** Returns `True` if more items exist (peeks without consuming).
+- **`.__iter__()` and `.__next__()` / `.next()`** Compatible with Python 2/3 iterator protocol.
+
+## Contributing
+
+Contributions are welcome! Please submit pull requests or open issues on the GitHub repository.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

put_back_iterator-0.1.0a0.dist-info/RECORD

@@ -0,0 +1,6 @@
+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,,

put_back_iterator-0.1.0a0.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any
+

put_back_iterator-0.1.0a0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jifeng Wu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

put_back_iterator-0.1.0a0.dist-info/top_level.txt

@@ -0,0 +1 @@
+put_back_iterator

put_back_iterator.py

@@ -0,0 +1,47 @@
+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