rangeslib 0.6.0__py3-none-any.whl

rangeslib/__init__.py

@@ -0,0 +1,8 @@
+from . import ranges, views
+from ._core import Range
+
+__all__ = [
+    "Range",
+    "ranges",
+    "views",
+]

rangeslib/_adaptors.py

@@ -0,0 +1,396 @@
+from __future__ import annotations
+
+from itertools import islice, product
+from typing import Callable, Iterable, Protocol, cast
+
+from ._core import Range, RangeAdaptor
+
+type Pattern[InputT] = InputT | Iterable[InputT]
+
+
+def _pattern_from[InputT](value: Pattern[InputT]) -> tuple[InputT, ...]:
+    try:
+        return tuple(cast(Iterable[InputT], value))
+    except TypeError:
+        return (cast(InputT, value),)
+
+
+def _starts_with[InputT](
+    values: list[InputT], index: int, pattern: tuple[InputT, ...]
+) -> bool:
+    return tuple(values[index : index + len(pattern)]) == pattern
+
+
+class SupportsGetItem(Protocol):
+    """Structural requirement for tuple-like indexed elements."""
+
+    def __getitem__(self, index: int, /) -> object: ...
+
+
+class All[InputT](RangeAdaptor[InputT, Range[InputT]]):
+    """Materialize any iterable as an eager ``Range``."""
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[InputT]:
+        return Range(*iterable)
+
+
+class To[InputT, OutputT](RangeAdaptor[InputT, OutputT]):
+    """Convert an iterable with a supplied collection or factory callable."""
+
+    def __init__(self, target_type: Callable[[Iterable[InputT]], OutputT]) -> None:
+        self.target_type = target_type
+
+    def __call__(self, iterable: Iterable[InputT]) -> OutputT:
+        return self.target_type(iterable)
+
+
+class Reverse[InputT](RangeAdaptor[InputT, Range[InputT]]):
+    """Return the input elements in reverse order."""
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[InputT]:
+        return Range(*reversed(list(iterable)))
+
+
+class Filter[InputT](RangeAdaptor[InputT, Range[InputT]]):
+    """Keep elements for which ``predicate`` returns true."""
+
+    def __init__(self, predicate: Callable[[InputT], bool]) -> None:
+        self.predicate = predicate
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[InputT]:
+        return Range(*filter(self.predicate, iterable))
+
+
+class Transform[InputT, OutputT](RangeAdaptor[InputT, Range[OutputT]]):
+    """Map each input element to a new value with ``func``."""
+
+    def __init__(self, func: Callable[[InputT], OutputT]) -> None:
+        self.func = func
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[OutputT]:
+        return Range(*map(self.func, iterable))
+
+
+class Take[InputT](RangeAdaptor[InputT, Range[InputT]]):
+    """Apply Python slice-stop semantics to the input."""
+
+    def __init__(self, n: int) -> None:
+        self.n = n
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[InputT]:
+        if self.n >= 0:
+            return Range(*islice(iterable, self.n))
+        return Range(*list(iterable)[: self.n])
+
+
+class TakeWhile[InputT](RangeAdaptor[InputT, Range[InputT]]):
+    """Keep the initial elements while ``predicate`` remains true."""
+
+    def __init__(self, predicate: Callable[[InputT], bool]) -> None:
+        self.predicate = predicate
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[InputT]:
+        result: list[InputT] = []
+        for value in iterable:
+            if not self.predicate(value):
+                break
+            result.append(value)
+        return Range(*result)
+
+
+class Drop[InputT](RangeAdaptor[InputT, Range[InputT]]):
+    """Apply Python slice-start semantics to the input."""
+
+    def __init__(self, n: int) -> None:
+        self.n = n
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[InputT]:
+        return Range(*list(iterable)[self.n :])
+
+
+class DropWhile[InputT](RangeAdaptor[InputT, Range[InputT]]):
+    """Discard the initial elements while ``predicate`` remains true."""
+
+    def __init__(self, predicate: Callable[[InputT], bool]) -> None:
+        self.predicate = predicate
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[InputT]:
+        result: list[InputT] = []
+        dropping = True
+        for value in iterable:
+            if dropping and not self.predicate(value):
+                dropping = False
+            if not dropping:
+                result.append(value)
+        return Range(*result)
+
+
+class Counted[InputT](RangeAdaptor[InputT, Range[InputT]]):
+    """Take a bounded prefix from the input's current iterator position."""
+
+    def __init__(self, count: int) -> None:
+        if count < 0:
+            raise ValueError("Counted count cannot be negative")
+        self.count = count
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[InputT]:
+        return Range(*islice(iterable, self.count))
+
+
+class Elements[OutputT](RangeAdaptor[SupportsGetItem, Range[OutputT]]):
+    """Project one integer-indexed field from each tuple-like element."""
+
+    def __init__(self, index: int) -> None:
+        self.index = index
+
+    def __call__(self, iterable: Iterable[SupportsGetItem]) -> Range[OutputT]:
+        return Range(*(cast(OutputT, value[self.index]) for value in iterable))
+
+
+class Keys[OutputT](Elements[OutputT]):
+    """Project index ``0`` from each tuple-like element."""
+
+    def __init__(self) -> None:
+        super().__init__(0)
+
+
+class Values[OutputT](Elements[OutputT]):
+    """Project index ``1`` from each tuple-like element."""
+
+    def __init__(self) -> None:
+        super().__init__(1)
+
+
+class Enumerate[InputT](RangeAdaptor[InputT, Range[tuple[int, InputT]]]):
+    """Pair each input value with its sequential index."""
+
+    def __init__(self, start: int = 0) -> None:
+        self.start = start
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[tuple[int, InputT]]:
+        return Range(*enumerate(iterable, self.start))
+
+
+class Concat[InputT](RangeAdaptor[InputT, Range[InputT]]):
+    """Append configured iterables after the piped input."""
+
+    def __init__(self, *iterables: Iterable[InputT]) -> None:
+        self.iterables = iterables
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[InputT]:
+        result: list[InputT] = list(iterable)
+        for additional_iterable in self.iterables:
+            result.extend(additional_iterable)
+        return Range(*result)
+
+
+class Zip[InputT](RangeAdaptor[InputT, Range[tuple[InputT, ...]]]):
+    """Zip the piped input with additional iterables to the shortest length."""
+
+    def __init__(self, *iterables: Iterable[InputT]) -> None:
+        self.iterables = iterables
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[tuple[InputT, ...]]:
+        return Range(*zip(iterable, *self.iterables))
+
+
+class ZipTransform[OutputT](RangeAdaptor[object, Range[OutputT]]):
+    """Apply a callable to corresponding values from several iterables."""
+
+    def __init__(
+        self, func: Callable[..., OutputT], *iterables: Iterable[object]
+    ) -> None:
+        self.func = func
+        self.iterables = iterables
+
+    def __call__(self, iterable: Iterable[object]) -> Range[OutputT]:
+        return Range(*(self.func(*values) for values in zip(iterable, *self.iterables)))
+
+
+class Adjacent[InputT](RangeAdaptor[InputT, Range[tuple[InputT, ...]]]):
+    """Return overlapping windows of ``width`` adjacent elements."""
+
+    def __init__(self, width: int = 2) -> None:
+        if width < 1:
+            raise ValueError("Adjacent width must be positive")
+        self.width = width
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[tuple[InputT, ...]]:
+        values = list(iterable)
+        return Range(
+            *(
+                tuple(values[index : index + self.width])
+                for index in range(len(values) - self.width + 1)
+            )
+        )
+
+
+class Pairwise[InputT](RangeAdaptor[InputT, Range[tuple[InputT, InputT]]]):
+    """Return overlapping two-element windows."""
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[tuple[InputT, InputT]]:
+        values = list(iterable)
+        return Range(
+            *((values[index], values[index + 1]) for index in range(len(values) - 1))
+        )
+
+
+class AdjacentTransform[InputT, OutputT](RangeAdaptor[InputT, Range[OutputT]]):
+    """Apply a callable to each overlapping adjacent window."""
+
+    def __init__(self, func: Callable[..., OutputT], width: int = 2) -> None:
+        if width < 1:
+            raise ValueError("AdjacentTransform width must be positive")
+        self.func = func
+        self.width = width
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[OutputT]:
+        values = list(iterable)
+        return Range(
+            *(
+                self.func(*values[index : index + self.width])
+                for index in range(len(values) - self.width + 1)
+            )
+        )
+
+
+class PairwiseTransform[InputT, OutputT](AdjacentTransform[InputT, OutputT]):
+    """Apply a binary callable to each pair of adjacent elements."""
+
+    def __init__(self, func: Callable[[InputT, InputT], OutputT]) -> None:
+        super().__init__(func, 2)
+
+
+class Chunk[InputT](RangeAdaptor[InputT, Range[Range[InputT]]]):
+    """Partition input into non-overlapping chunks of up to ``size`` elements."""
+
+    def __init__(self, size: int) -> None:
+        if size < 1:
+            raise ValueError("Chunk size must be positive")
+        self.size = size
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[Range[InputT]]:
+        values = list(iterable)
+        return Range(
+            *(
+                Range(*values[index : index + self.size])
+                for index in range(0, len(values), self.size)
+            )
+        )
+
+
+class Slide[InputT](RangeAdaptor[InputT, Range[Range[InputT]]]):
+    """Return overlapping windows of ``width`` elements."""
+
+    def __init__(self, width: int) -> None:
+        if width < 1:
+            raise ValueError("Slide width must be positive")
+        self.width = width
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[Range[InputT]]:
+        values = list(iterable)
+        return Range(
+            *(
+                Range(*values[index : index + self.width])
+                for index in range(len(values) - self.width + 1)
+            )
+        )
+
+
+class ChunkBy[InputT](RangeAdaptor[InputT, Range[Range[InputT]]]):
+    """Split input when the adjacent-value predicate returns false."""
+
+    def __init__(self, predicate: Callable[[InputT, InputT], bool]) -> None:
+        self.predicate = predicate
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[Range[InputT]]:
+        values = list(iterable)
+        if not values:
+            return Range()
+
+        chunks: list[Range[InputT]] = []
+        current_chunk = [values[0]]
+        for previous, value in zip(values, values[1:]):
+            if self.predicate(previous, value):
+                current_chunk.append(value)
+            else:
+                chunks.append(Range(*current_chunk))
+                current_chunk = [value]
+        chunks.append(Range(*current_chunk))
+        return Range(*chunks)
+
+
+class Stride[InputT](RangeAdaptor[InputT, Range[InputT]]):
+    """Select every ``step``-th input element, starting with the first."""
+
+    def __init__(self, step: int) -> None:
+        if step < 1:
+            raise ValueError("Stride step must be positive")
+        self.step = step
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[InputT]:
+        return Range(*islice(iterable, 0, None, self.step))
+
+
+class CartesianProduct[InputT](RangeAdaptor[InputT, Range[tuple[InputT, ...]]]):
+    """Return the Cartesian product of the input and configured iterables."""
+
+    def __init__(self, *iterables: Iterable[InputT]) -> None:
+        self.iterables = iterables
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[tuple[InputT, ...]]:
+        return Range(*product(iterable, *self.iterables))
+
+
+class Join[InputT](RangeAdaptor[Iterable[InputT], Range[InputT]]):
+    """Flatten one level of nested iterables."""
+
+    def __call__(self, iterable: Iterable[Iterable[InputT]]) -> Range[InputT]:
+        result: list[InputT] = []
+        for sub_iterable in iterable:
+            result.extend(sub_iterable)
+        return Range(*result)
+
+
+class JoinWith[InputT](RangeAdaptor[Iterable[InputT], Range[InputT]]):
+    """Flatten nested iterables with a separator pattern between them."""
+
+    def __init__(self, separator: Pattern[InputT]) -> None:
+        self.separator = _pattern_from(separator)
+
+    def __call__(self, iterable: Iterable[Iterable[InputT]]) -> Range[InputT]:
+        result: list[InputT] = []
+        first = True
+        for sub_iterable in iterable:
+            if not first:
+                result.extend(self.separator)
+            result.extend(sub_iterable)
+            first = False
+        return Range(*result)
+
+
+class Split[InputT](RangeAdaptor[InputT, Range[Range[InputT]]]):
+    """Split input into ranges wherever a separator pattern occurs."""
+
+    def __init__(self, separator: Pattern[InputT]) -> None:
+        self.separator = _pattern_from(separator)
+
+    def __call__(self, iterable: Iterable[InputT]) -> Range[Range[InputT]]:
+        separator_length = len(self.separator)
+        if separator_length == 0:
+            raise ValueError("Split separator cannot be empty")
+
+        values = list(iterable)
+        result: list[Range[InputT]] = []
+        current_chunk: list[InputT] = []
+        index = 0
+        while index < len(values):
+            if _starts_with(values, index, self.separator):
+                result.append(Range(*current_chunk))
+                current_chunk = []
+                index += separator_length
+            else:
+                current_chunk.append(values[index])
+                index += 1
+        result.append(Range(*current_chunk))
+        return Range(*result)

rangeslib/_core.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections import UserList
+from typing import Callable, Iterable, SupportsIndex, overload
+
+
+class RangeAdaptor[InputT, OutputT](ABC):
+    """Base contract for callable transformations over iterable values.
+
+    Adaptors can be called directly or placed on the right side of ``|``.
+    The reflected operator lets built-in iterables such as ``list``, ``str``,
+    and ``range`` start a pipeline even though they cannot be modified.
+    """
+
+    def __ror__(self, iterable: Iterable[InputT]) -> OutputT:
+        return self(iterable)
+
+    def __or__[NextOutputT](
+        self, adaptor: Callable[[OutputT], NextOutputT], /
+    ) -> RangeAdaptor[InputT, NextOutputT]:
+        return _ComposedRangeAdaptor(self, adaptor)
+
+    @abstractmethod
+    def __call__(self, iterable: Iterable[InputT]) -> OutputT:
+        raise NotImplementedError
+
+
+class _ComposedRangeAdaptor[InputT, MiddleT, OutputT](RangeAdaptor[InputT, OutputT]):
+    def __init__(
+        self,
+        first: Callable[[Iterable[InputT]], MiddleT],
+        second: Callable[[MiddleT], OutputT],
+    ) -> None:
+        self.first = first
+        self.second = second
+
+    def __call__(self, iterable: Iterable[InputT]) -> OutputT:
+        return self.second(self.first(iterable))
+
+
+class RangeGenerator(ABC):
+    """Marker base class for objects that construct :class:`Range` values."""
+
+
+class Range[T](UserList[T]):
+    """A list-backed, typed container used as the library's pipeline value.
+
+    ``Range`` is eager: constructing or applying an adaptor stores the result
+    immediately. Construction uses positional values, so ``Range(1, 2, 3)``
+    contains three elements. Standard list-like operations preserve ``Range``
+    as the result type.
+    """
+
+    def __init__(self, *args: T) -> None:
+        super().__init__(args)
+
+    def __repr__(self) -> str:
+        return f"Range({', '.join(repr(x) for x in self.data)})"
+
+    def __str__(self) -> str:
+        return f"[{', '.join(str(x) for x in self.data)}]"
+
+    def __or__[OutputT](self, adaptor: Callable[[Iterable[T]], OutputT], /) -> OutputT:
+        return adaptor(self)
+
+    @overload
+    def __getitem__(self, index: SupportsIndex) -> T: ...
+
+    @overload
+    def __getitem__(self, index: slice[SupportsIndex | None]) -> Range[T]: ...
+
+    def __getitem__(
+        self, index: SupportsIndex | slice[SupportsIndex | None]
+    ) -> T | Range[T]:
+        if isinstance(index, slice):
+            return Range(*self.data[index])
+        return self.data[index]
+
+    def __add__(self, other: Iterable[T]) -> Range[T]:
+        return Range(*self.data, *other)
+
+    def __radd__(self, other: Iterable[T]) -> Range[T]:
+        return Range(*other, *self.data)
+
+    def __mul__(self, count: int) -> Range[T]:
+        return Range(*(self.data * count))
+
+    def __rmul__(self, count: int) -> Range[T]:
+        return self * count
+
+    def copy(self) -> Range[T]:
+        """Return a shallow ``Range`` copy without nesting the source range."""
+        return Range(*self.data)
+
+    def is_empty(self) -> bool:
+        """Return ``True`` when the range has no elements."""
+        return not self.data

rangeslib/_generators.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+# These private factory classes intentionally construct Range instances.
+# Mypy otherwise requires __new__ to return an instance of each factory class.
+# mypy: disable-error-code=misc
+
+from ._core import Range, RangeGenerator
+
+
+class Empty(RangeGenerator):
+    """Create an empty integer ``Range``."""
+
+    def __new__(cls) -> Range[int]:
+        return Range()
+
+
+class Single(RangeGenerator):
+    """Create a ``Range`` containing one value."""
+
+    def __new__[T](cls, value: T) -> Range[T]:
+        return Range(value)
+
+
+class Iota(RangeGenerator):
+    """Create integers from ``start`` up to, but excluding, ``end``."""
+
+    def __new__(cls, start: int, end: int) -> Range[int]:
+        return Range(*range(start, end))
+
+
+class Indices(RangeGenerator):
+    """Create zero-based indices from ``0`` up to, but excluding, ``n``."""
+
+    def __new__(cls, n: int) -> Range[int]:
+        return Iota(0, n)
+
+
+class Repeat(RangeGenerator):
+    """Create a ``Range`` containing ``n`` copies of a value."""
+
+    def __new__[T](cls, value: T, n: int) -> Range[T]:
+        return Range(*[value] * n)

rangeslib/ranges.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from ._core import Range
+from ._generators import Empty, Indices, Iota, Repeat, Single
+
+
+def empty() -> Range[int]:
+    """Create an empty integer range."""
+    return Empty()
+
+
+def single[T](value: T) -> Range[T]:
+    """Create a range containing exactly ``value``."""
+    return Single(value)
+
+
+def iota(start: int, end: int) -> Range[int]:
+    """Create integers from ``start`` up to, but excluding, ``end``."""
+    return Iota(start, end)
+
+
+def indices(count: int) -> Range[int]:
+    """Create zero-based indices up to, but excluding, ``count``."""
+    return Indices(count)
+
+
+def repeat[T](value: T, count: int) -> Range[T]:
+    """Create a range containing ``count`` copies of ``value``."""
+    return Repeat(value, count)
+
+
+__all__ = ["empty", "single", "iota", "indices", "repeat"]

rangeslib/views.py

@@ -0,0 +1,349 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Iterable, Protocol, cast
+
+from ._adaptors import (
+    Adjacent,
+    AdjacentTransform,
+    All,
+    CartesianProduct,
+    Chunk,
+    ChunkBy,
+    Concat,
+    Counted,
+    Drop,
+    DropWhile,
+    Elements,
+    Enumerate,
+    Filter,
+    Join,
+    JoinWith,
+    Keys,
+    Pairwise,
+    PairwiseTransform,
+    Reverse,
+    Slide,
+    Split,
+    Stride,
+    Take,
+    TakeWhile,
+    To,
+    Transform,
+    Values,
+    Zip,
+    ZipTransform,
+)
+from ._core import Range
+
+
+class _TypePreservingView(Protocol):
+    def __call__[T](self, iterable: Iterable[T], /) -> Range[T]: ...
+
+    def __ror__[T](self, iterable: Iterable[T], /) -> Range[T]: ...
+
+
+class _EnumerateView(Protocol):
+    def __call__[T](self, iterable: Iterable[T], /) -> Range[tuple[int, T]]: ...
+
+    def __ror__[T](self, iterable: Iterable[T], /) -> Range[tuple[int, T]]: ...
+
+
+class _AdjacentView(Protocol):
+    def __call__[T](self, iterable: Iterable[T], /) -> Range[tuple[T, ...]]: ...
+
+    def __ror__[T](self, iterable: Iterable[T], /) -> Range[tuple[T, ...]]: ...
+
+
+class _PairwiseView(Protocol):
+    def __call__[T](self, iterable: Iterable[T], /) -> Range[tuple[T, T]]: ...
+
+    def __ror__[T](self, iterable: Iterable[T], /) -> Range[tuple[T, T]]: ...
+
+
+class _ChunkView(Protocol):
+    def __call__[T](self, iterable: Iterable[T], /) -> Range[Range[T]]: ...
+
+    def __ror__[T](self, iterable: Iterable[T], /) -> Range[Range[T]]: ...
+
+
+class _JoinView(Protocol):
+    def __call__[T](self, iterable: Iterable[Iterable[T]], /) -> Range[T]: ...
+
+    def __ror__[T](self, iterable: Iterable[Iterable[T]], /) -> Range[T]: ...
+
+
+class _KeysView(Protocol):
+    def __call__[KeyT, ValueT](
+        self, iterable: Iterable[tuple[KeyT, ValueT]], /
+    ) -> Range[KeyT]: ...
+
+    def __ror__[KeyT, ValueT](
+        self, iterable: Iterable[tuple[KeyT, ValueT]], /
+    ) -> Range[KeyT]: ...
+
+
+class _ValuesView(Protocol):
+    def __call__[KeyT, ValueT](
+        self, iterable: Iterable[tuple[KeyT, ValueT]], /
+    ) -> Range[ValueT]: ...
+
+    def __ror__[KeyT, ValueT](
+        self, iterable: Iterable[tuple[KeyT, ValueT]], /
+    ) -> Range[ValueT]: ...
+
+
+class _ZipView[OtherT](Protocol):
+    def __call__[InputT](
+        self, iterable: Iterable[InputT], /
+    ) -> Range[tuple[InputT, OtherT]]: ...
+
+    def __ror__[InputT](
+        self, iterable: Iterable[InputT], /
+    ) -> Range[tuple[InputT, OtherT]]: ...
+
+
+class _CartesianProductView[OtherT](Protocol):
+    def __call__[InputT](
+        self, iterable: Iterable[InputT], /
+    ) -> Range[tuple[InputT, OtherT]]: ...
+
+    def __ror__[InputT](
+        self, iterable: Iterable[InputT], /
+    ) -> Range[tuple[InputT, OtherT]]: ...
+
+
+def all() -> _TypePreservingView:
+    """Materialize an existing iterable as an eager ``Range``.
+
+    This mirrors C++ ``views::all`` at the public API level. Python does not
+    expose borrowed-range or view ownership categories, so this implementation
+    always returns a reusable, materialized :class:`~rangeslib.Range`.
+    """
+    return cast(_TypePreservingView, All[object]())
+
+
+def to[InputT, OutputT](
+    target_type: Callable[[Iterable[InputT]], OutputT],
+) -> To[InputT, OutputT]:
+    """Convert the pipeline input with ``target_type``.
+
+    ``to`` is the only public adaptor that does not necessarily return
+    :class:`~rangeslib.Range`; it returns exactly what the supplied callable
+    produces.
+    """
+    return To(target_type)
+
+
+def reverse() -> _TypePreservingView:
+    """Reverse all input values and return an eager ``Range``."""
+    return cast(_TypePreservingView, Reverse[object]())
+
+
+def filter[InputT](predicate: Callable[[InputT], bool]) -> Filter[InputT]:
+    """Keep values for which ``predicate`` returns ``True``."""
+    return Filter(predicate)
+
+
+def transform[InputT, OutputT](
+    func: Callable[[InputT], OutputT],
+) -> Transform[InputT, OutputT]:
+    """Map every input value through ``func``."""
+    return Transform(func)
+
+
+def take(count: int) -> _TypePreservingView:
+    """Take values using Python slice-stop semantics.
+
+    Positive and zero counts select a prefix. Negative counts behave like
+    ``list(iterable)[:count]`` and therefore require complete input
+    materialization.
+    """
+    return cast(_TypePreservingView, Take[object](count))
+
+
+def takewhile[InputT](predicate: Callable[[InputT], bool]) -> TakeWhile[InputT]:
+    """Take initial values while ``predicate`` remains ``True``."""
+    return TakeWhile(predicate)
+
+
+def take_while[InputT](predicate: Callable[[InputT], bool]) -> TakeWhile[InputT]:
+    """Alias for :func:`takewhile` using C++-style word separation."""
+    return takewhile(predicate)
+
+
+def drop(count: int) -> _TypePreservingView:
+    """Drop values using Python slice-start semantics.
+
+    Negative counts behave like ``list(iterable)[count:]`` and therefore
+    require complete input materialization.
+    """
+    return cast(_TypePreservingView, Drop[object](count))
+
+
+def dropwhile[InputT](predicate: Callable[[InputT], bool]) -> DropWhile[InputT]:
+    """Drop initial values while ``predicate`` remains ``True``."""
+    return DropWhile(predicate)
+
+
+def drop_while[InputT](predicate: Callable[[InputT], bool]) -> DropWhile[InputT]:
+    """Alias for :func:`dropwhile` using C++-style word separation."""
+    return dropwhile(predicate)
+
+
+def counted(count: int) -> _TypePreservingView:
+    """Consume at most ``count`` values from the current iterator position.
+
+    Unlike ``take``, ``counted`` does not first materialize the entire input.
+    ``count`` must be non-negative.
+    """
+    return cast(_TypePreservingView, Counted[object](count))
+
+
+def elements(index: int) -> Elements[Any]:
+    """Project integer-indexed field ``index`` from every input value."""
+    return Elements[Any](index)
+
+
+def keys() -> _KeysView:
+    """Project field ``0`` from every tuple-like input value."""
+    return cast(_KeysView, Keys[Any]())
+
+
+def values() -> _ValuesView:
+    """Project field ``1`` from every tuple-like input value."""
+    return cast(_ValuesView, Values[Any]())
+
+
+def enumerate(start: int = 0) -> _EnumerateView:
+    """Pair each input value with a sequential integer index."""
+    return cast(_EnumerateView, Enumerate[object](start))
+
+
+def concat[InputT](*iterables: Iterable[InputT]) -> Concat[InputT]:
+    """Append configured iterables after the pipeline input."""
+    return Concat(*iterables)
+
+
+def zip[OtherT](*iterables: Iterable[OtherT]) -> _ZipView[OtherT]:
+    """Zip the pipeline input with configured iterables to the shortest length."""
+    return cast(_ZipView[OtherT], Zip[Any](*iterables))
+
+
+def zip_transform[OutputT](
+    func: Callable[..., OutputT], *iterables: Iterable[Any]
+) -> ZipTransform[OutputT]:
+    """Zip corresponding values and call ``func`` for each group."""
+    return ZipTransform(func, *iterables)
+
+
+def adjacent(width: int = 2) -> _AdjacentView:
+    """Return overlapping tuple windows of ``width`` values."""
+    return cast(_AdjacentView, Adjacent[object](width))
+
+
+def pairwise() -> _PairwiseView:
+    """Return overlapping two-value tuples."""
+    return cast(_PairwiseView, Pairwise[object]())
+
+
+def adjacent_transform[OutputT](
+    func: Callable[..., OutputT], width: int = 2
+) -> AdjacentTransform[Any, OutputT]:
+    """Call ``func`` for each overlapping window of ``width`` values."""
+    return AdjacentTransform[Any, OutputT](func, width)
+
+
+def pairwise_transform[InputT, OutputT](
+    func: Callable[[InputT, InputT], OutputT],
+) -> PairwiseTransform[InputT, OutputT]:
+    """Call a binary ``func`` for each adjacent pair."""
+    return PairwiseTransform(func)
+
+
+def chunk(size: int) -> _ChunkView:
+    """Partition the input into non-overlapping ``Range`` chunks.
+
+    ``size`` must be positive. The final chunk may contain fewer values.
+    """
+    return cast(_ChunkView, Chunk[object](size))
+
+
+def slide(width: int) -> _ChunkView:
+    """Return overlapping ``Range`` windows of exactly ``width`` values."""
+    return cast(_ChunkView, Slide[object](width))
+
+
+def chunk_by[InputT](
+    predicate: Callable[[InputT, InputT], bool],
+) -> ChunkBy[InputT]:
+    """Split whenever ``predicate(previous, current)`` returns ``False``."""
+    return ChunkBy(predicate)
+
+
+def stride(step: int) -> _TypePreservingView:
+    """Select every ``step``-th value, starting with the first.
+
+    ``step`` must be positive.
+    """
+    return cast(_TypePreservingView, Stride[object](step))
+
+
+def cartesian_product[InputT](
+    *iterables: Iterable[InputT],
+) -> _CartesianProductView[InputT]:
+    """Return the Cartesian product of the input and configured iterables."""
+    return cast(_CartesianProductView[InputT], CartesianProduct[Any](*iterables))
+
+
+def join() -> _JoinView:
+    """Flatten one level of nested iterables."""
+    return cast(_JoinView, Join[object]())
+
+
+def join_with[InputT](separator: InputT | Iterable[InputT]) -> JoinWith[InputT]:
+    """Flatten nested iterables with ``separator`` inserted between them."""
+    return JoinWith(separator)
+
+
+def split[InputT](separator: InputT | Iterable[InputT]) -> Split[InputT]:
+    """Split input wherever the separator pattern occurs.
+
+    Empty chunks are preserved. An empty separator raises ``ValueError`` when
+    the adaptor is applied.
+    """
+    return Split(separator)
+
+
+__all__ = [
+    "adjacent",
+    "adjacent_transform",
+    "all",
+    "cartesian_product",
+    "chunk",
+    "chunk_by",
+    "concat",
+    "counted",
+    "drop",
+    "drop_while",
+    "dropwhile",
+    "elements",
+    "enumerate",
+    "filter",
+    "join",
+    "join_with",
+    "keys",
+    "pairwise",
+    "pairwise_transform",
+    "reverse",
+    "slide",
+    "split",
+    "stride",
+    "take",
+    "take_while",
+    "takewhile",
+    "to",
+    "transform",
+    "values",
+    "zip",
+    "zip_transform",
+]

rangeslib-0.6.0.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: rangeslib
+Version: 0.6.0
+Summary: Composable, typed Python ranges and iterable adaptors
+Author: Aaryan Banerjee
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/TheUltimateOrion/RangesLib
+Project-URL: Documentation, https://theultimateorion.github.io/RangesLib/
+Project-URL: Repository, https://github.com/TheUltimateOrion/RangesLib.git
+Project-URL: Issues, https://github.com/TheUltimateOrion/RangesLib/issues
+Keywords: ranges,iterables,pipelines,functional,typing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: docs
+Requires-Dist: myst-parser>=4; extra == "docs"
+Requires-Dist: sphinx>=8; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=3; extra == "docs"
+Provides-Extra: test
+Requires-Dist: coverage[toml]>=7.6; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: coverage[toml]>=7.6; extra == "dev"
+Requires-Dist: mypy>=1.15; extra == "dev"
+Requires-Dist: myst-parser>=4; extra == "dev"
+Requires-Dist: pre-commit>=4.0; extra == "dev"
+Requires-Dist: pyright>=1.1.400; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: sphinx>=8; extra == "dev"
+Requires-Dist: sphinx-autodoc-typehints>=3; extra == "dev"
+Dynamic: license-file
+
+# rangeslib
+
+[![Tests and quality](https://github.com/TheUltimateOrion/RangesLib/actions/workflows/tests.yml/badge.svg)](https://github.com/TheUltimateOrion/RangesLib/actions/workflows/tests.yml)
+[![Documentation](https://github.com/TheUltimateOrion/RangesLib/actions/workflows/docs.yml/badge.svg)](https://theultimateorion.github.io/RangesLib/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+`rangeslib` is a typed Python library for eager, C++-inspired range pipelines.
+The public API is intentionally small:
+
+```python
+from rangeslib import ranges, views
+```
+
+The mental model is:
+
+```text
+ranges creates values
+views transforms values
+views.to converts the final result
+```
+
+## Quick Start
+
+```python
+from rangeslib import ranges, views
+
+result = (
+    ranges.iota(1, 11)
+    | views.filter(lambda value: value % 2 == 0)
+    | views.transform(lambda value: value * 10)
+    | views.take(3)
+    | views.to(list)
+)
+
+assert result == [20, 40, 60]
+```
+
+`Range` values are eager and reusable. Most adaptors return another `Range`; the
+terminal `views.to(...)` adaptor returns whatever collection or factory you ask
+for.
+
+## Existing Iterables
+
+Ordinary Python iterables can start pipelines too:
+
+```python
+from rangeslib import views
+
+text = "abcdef" | views.take(3) | views.to("".join)
+assert text == "abc"
+
+chars = "abc" | views.all()
+assert list(chars) == ["a", "b", "c"]
+```
+
+`views.all()` is the eager Python counterpart to C++ `views::all`: it adapts an
+existing iterable into a reusable `Range`.
+
+## Reusable Pipelines
+
+Adaptors can be composed before data is supplied:
+
+```python
+from rangeslib import views
+
+first_three_even = views.filter(lambda value: value % 2 == 0) | views.take(3)
+
+assert list([1, 2, 3, 4, 5, 6] | first_three_even) == [2, 4, 6]
+assert list([10, 11, 12, 14] | first_three_even) == [10, 12, 14]
+```
+
+## Sources And Views
+
+The `ranges` facade creates source ranges:
+
+```python
+from rangeslib import ranges
+
+ranges.empty()
+ranges.single("value")
+ranges.iota(1, 5)
+ranges.indices(3)
+ranges.repeat("x", 3)
+```
+
+The `views` facade contains transformations such as:
+
+```text
+all, reverse, filter, transform, take, drop, counted,
+elements, keys, values, enumerate, concat, zip, cartesian_product,
+adjacent, pairwise, chunk, slide, stride, join, split, to
+```
+
+See [docs/usage.md](docs/usage.md) for the full API catalog.
+
+## C++ Ranges Correspondence
+
+`rangeslib` borrows naming and broad behavior from C++20/23/26 ranges, but it
+is not a lazy C++ view implementation. The most important differences are:
+
+- Python iterables replace C++ iterator/sentinel pairs.
+- `Range` stores eager values instead of reference-like lazy views.
+- Tuple results are ordinary Python tuples, not tuples of references.
+- Python type checking is useful but cannot express every C++ tuple-like rule.
+
+See [docs/cpp-comparison.md](docs/cpp-comparison.md) for details.
+
+## Installation
+
+Python 3.12 or newer is required.
+
+```bash
+python -m pip install .
+```
+
+For development:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+`rangeslib` has no runtime dependencies.
+
+## Development
+
+Useful commands live in `scripts/`:
+
+```bash
+./scripts/run_tests.sh       # tests only
+./scripts/typecheck.sh       # mypy + Pyright
+./scripts/check.sh           # Ruff, typing, tests, coverage
+./scripts/check_all.sh       # check.sh + strict Sphinx docs
+./scripts/check_package.sh   # sdist/wheel build and install smoke test
+./scripts/run_playground.sh  # manual playground
+```
+
+Before a release commit, run:
+
+```bash
+./scripts/check_all.sh
+./scripts/check_package.sh
+```
+
+## Documentation
+
+Build the Sphinx site with:
+
+```bash
+./scripts/generate_docs.sh
+```
+
+Generated HTML is written to `docs/_build/html/` and published to GitHub Pages
+after CI succeeds on `main`.
+
+## Releases
+
+Changing `[project].version` in `pyproject.toml` on `main` automatically runs
+the complete quality and package checks, then creates the matching Git tag and
+GitHub Release. Published GitHub Releases trigger PyPI publishing through
+Trusted Publishing after the PyPI project is configured.
+
+For future work, prefer opening or collecting issues before adding more adaptors
+immediately. See [docs/roadmap.md](docs/roadmap.md).
+
+See [docs/publishing.md](docs/publishing.md) for the PyPI setup checklist.

rangeslib-0.6.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+rangeslib/__init__.py,sha256=ICZfHAQmeueQKKJZfPNOd5-4uQIu7qMCkQ3-fpv_VAI,108
+rangeslib/_adaptors.py,sha256=sxUuvJ7VbOFUTM1ZCu7e_e6HAaneYs-Y4VBOjuZT-Ic,13448
+rangeslib/_core.py,sha256=3abc6w6HSwfzModY2hsnIPF2BedZM6Oob8OSDB5Zpng,3198
+rangeslib/_generators.py,sha256=fP26T0i_r-xCUSGFNtwh7ew4wtz6d4HWuW8lxOlzOyM,1127
+rangeslib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rangeslib/ranges.py,sha256=qfC7fJ-UbMIeWNvitSltFqW_zW-WVr7L7vu1K3_NsaI,826
+rangeslib/views.py,sha256=INxSEanBhxX1g3teKE2tp9gbhUJxRpbnoyzBgAkAl-Y,9798
+rangeslib-0.6.0.dist-info/licenses/LICENSE,sha256=UAvw4k0gMkbpVv5MiD7icihSYrcoy-Zsb-CDtbc1MsE,1072
+rangeslib-0.6.0.dist-info/METADATA,sha256=tV7x5pw0sEQI-wflTMcCBF39iFTk2Z_3SEKBiD9iGHE,6013
+rangeslib-0.6.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rangeslib-0.6.0.dist-info/top_level.txt,sha256=4BNUUUJHbKIq--KOxgHOksvjcI6Ph_0sRM0oE6S06aQ,10
+rangeslib-0.6.0.dist-info/RECORD,,

rangeslib-0.6.0.dist-info/WHEEL

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

rangeslib-0.6.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaryan Banerjee
+
+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.

rangeslib-0.6.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rangeslib