IterProxy: Extended Iterable API

Warnings

• gotcha IterProxy methods, like other Python iterators, consume elements from the underlying iterable. Subsequent calls to methods such as `.one()`, `.many()`, or `.all()` on the same `IterProxy` instance will continue from where the last operation left off. If the iterable is fully consumed, further calls will yield no results or raise `StopIteration`.
  Fix: If you need to re-process the original sequence from the beginning, re-create the `IterProxy` instance from the original iterable or a fresh copy of it (e.g., `IterProxy(list(original_data))`).
• gotcha Calling `.one()` on an `IterProxy` that is empty or has been fully consumed will raise a `StopIteration` error. This is standard Python iterator behavior but can be unexpected if not handled.
  Fix: To gracefully handle cases where no element might be available, use `.one_or_none()` which returns `None` instead of raising `StopIteration` when the iterable is exhausted. Alternatively, wrap `.one()` calls in a `try-except StopIteration` block.
• gotcha When using the `.filter()` method, passing multiple filter functions to a single `.filter()` call (e.g., `proxy.filter(func1, func2)`) applies them with an implicit logical `AND` operation. This means all functions must return `True` for an item to pass the filter. Users expecting an `OR` operation or more complex logic might encounter unexpected results.
  Fix: For `OR` logic or more complex boolean combinations, define a single custom filter function that encapsulates the desired logic, or chain multiple `.filter()` calls if each applies a simple `AND` that aligns with the intended logic.

Install

• pip install iterproxy Install with pip

Imports

• IterProxy

  from iterproxy import IterProxy

Quickstart

This example demonstrates how to wrap a standard Python iterable with `IterProxy` and use its extended API for accessing elements, including `.one()`, `.many()`, `.skip()`, `.all()`, and `.one_or_none()`. It also shows how to chain multiple filter operations or combine them in a single call.

from iterproxy import IterProxy

# Create an IterProxy from any iterable
my_list = list(range(10))
proxy = IterProxy(my_list)

# Access elements using ORM-like API
print(f"First element: {proxy.one()}") # Output: First element: 0
print(f"Next three elements: {proxy.many(3)}") # Output: Next three elements: [1, 2, 3]

# Skip elements and get subsequent ones
# Note: This operates on the *remaining* elements after previous calls
print(f"Skip 2, get next 2: {proxy.skip(2).many(2)}") # Output: Skip 2, get next 2: [6, 7]

# Get all remaining elements
print(f"All remaining elements: {proxy.all()}") # Output: All remaining elements: [8, 9]

# Handle potentially empty results gracefully
empty_proxy = IterProxy([])
print(f"One or none from empty: {empty_proxy.one_or_none()}") # Output: One or none from empty: None

# Chaining filter operations
def is_odd(x): return x % 2 == 1
def gte_5(x): return x >= 5

# Re-create proxy for fresh iteration
proxy_for_filter = IterProxy(range(10))
filtered_items = proxy_for_filter.filter(is_odd).filter(gte_5).all()
print(f"Filtered (odd and >=5): {filtered_items}") # Output: Filtered (odd and >=5): [5, 7, 9]

# Multiple filter functions in one call (implicit AND logic)
proxy_combined_filter = IterProxy(range(10))
combined_filtered_items = proxy_combined_filter.filter(is_odd, gte_5).all()
print(f"Combined filter (odd and >=5): {combined_filtered_items}") # Output: Combined filter (odd and >=5): [5, 7, 9]