API reference

The supported application-facing API consists of rangeslib.Range, rangeslib.ranges, and rangeslib.views. Modules beginning with an underscore are private implementation details.

Core container

class rangeslib.Range(*args)

Bases: UserList, Generic

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.

copy()

Return a shallow Range copy without nesting the source range.

Return type:

Range[TypeVar(T)]

is_empty()

Return True when the range has no elements.

Return type:

bool

Generator facade

rangeslib.ranges.empty()

Create an empty integer range.

Return type:

Range[int]

rangeslib.ranges.indices(count)

Create zero-based indices up to, but excluding, count.

Return type:

Range[int]

rangeslib.ranges.iota(start, end)

Create integers from start up to, but excluding, end.

Return type:

Range[int]

rangeslib.ranges.repeat(value, count)

Create a range containing count copies of value.

Return type:

Range[TypeVar(T)]

rangeslib.ranges.single(value)

Create a range containing exactly value.

Return type:

Range[TypeVar(T)]

View facade

rangeslib.views.adjacent(width=2)

Return overlapping tuple windows of width values.

Return type:

_AdjacentView

rangeslib.views.adjacent_transform(func, width=2)

Call func for each overlapping window of width values.

Return type:

AdjacentTransform[Any, TypeVar(OutputT)]

rangeslib.views.all()

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 Range.

Return type:

_TypePreservingView

rangeslib.views.cartesian_product(*iterables)

Return the Cartesian product of the input and configured iterables.

Overloads:

  • → _CartesianProductView0

  • iterable (Iterable[OtherT]) → _CartesianProductView1[OtherT]

  • first (Iterable[OtherT]), second (Iterable[ThirdT]) → _CartesianProductView2[OtherT, ThirdT]

  • iterables (Iterable[Any]) → _VariadicCartesianProductView

Runtime calls may provide more than two configured iterables; precise public typing is provided for zero, one, and two configured iterables. Larger calls use a tuple-of-Any fallback type.

rangeslib.views.chunk(size)

Partition the input into non-overlapping Range chunks.

size must be positive. The final chunk may contain fewer values.

Return type:

_ChunkView

rangeslib.views.chunk_by(predicate)

Split whenever predicate(previous, current) returns False.

Return type:

ChunkBy[TypeVar(InputT)]

rangeslib.views.concat(*iterables)

Append configured iterables after the pipeline input.

Return type:

Concat[TypeVar(InputT)]

rangeslib.views.counted(count)

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 type:

_TypePreservingView

rangeslib.views.drop(count)

Drop values using Python slice-start semantics.

Negative counts behave like list(iterable)[count:] and therefore require complete input materialization.

Return type:

_TypePreservingView

rangeslib.views.drop_while(predicate)

Alias for dropwhile() using C++-style word separation.

Return type:

DropWhile[TypeVar(InputT)]

rangeslib.views.dropwhile(predicate)

Drop initial values while predicate remains True.

Return type:

DropWhile[TypeVar(InputT)]

rangeslib.views.elements(index)

Project integer-indexed field index from every input value.

Return type:

Elements[Any]

rangeslib.views.enumerate(start=0)

Pair each input value with a sequential integer index.

Return type:

_EnumerateView

rangeslib.views.filter(predicate)

Keep values for which predicate returns True.

Return type:

Filter[TypeVar(InputT)]

rangeslib.views.join()

Flatten one level of nested iterables.

Return type:

_JoinView

rangeslib.views.join_with(separator)

Flatten nested iterables with separator inserted between them.

Return type:

JoinWith[TypeVar(InputT)]

rangeslib.views.keys()

Project field 0 from every tuple-like input value.

Return type:

_KeysView

rangeslib.views.pairwise()

Return overlapping two-value tuples.

Return type:

_PairwiseView

rangeslib.views.pairwise_transform(func)

Call a binary func for each adjacent pair.

Return type:

PairwiseTransform[TypeVar(InputT), TypeVar(OutputT)]

rangeslib.views.reverse()

Reverse all input values and return an eager Range.

Return type:

_TypePreservingView

rangeslib.views.slide(width)

Return overlapping Range windows of exactly width values.

Return type:

_ChunkView

rangeslib.views.split(separator)

Split input wherever the separator pattern occurs.

Empty chunks are preserved. An empty separator raises ValueError when the adaptor is applied.

Return type:

Split[TypeVar(InputT)]

rangeslib.views.stride(step)

Select every step-th value, starting with the first.

step must be positive.

Return type:

_TypePreservingView

rangeslib.views.take(count)

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 type:

_TypePreservingView

rangeslib.views.take_while(predicate)

Alias for takewhile() using C++-style word separation.

Return type:

TakeWhile[TypeVar(InputT)]

rangeslib.views.takewhile(predicate)

Take initial values while predicate remains True.

Return type:

TakeWhile[TypeVar(InputT)]

rangeslib.views.to(target_type, /)

Convert the pipeline input with target_type.

Overloads:

  • target_type (type[str]) → To[str, str]

  • target_type (Callable[[Iterable[InputT]], OutputT]) → To[InputT, OutputT]

to is the only public adaptor that does not necessarily return Range; it returns exactly what the supplied callable produces. Passing the built-in str joins string elements without a separator.

rangeslib.views.transform(func)

Map every input value through func.

Return type:

Transform[TypeVar(InputT), TypeVar(OutputT)]

rangeslib.views.values()

Project field 1 from every tuple-like input value.

Return type:

_ValuesView

rangeslib.views.zip(*iterables)

Zip the pipeline input with configured iterables to the shortest length.

Overloads:

  • → _ZipView0

  • iterable (Iterable[OtherT]) → _ZipView1[OtherT]

  • first (Iterable[OtherT]), second (Iterable[ThirdT]) → _ZipView2[OtherT, ThirdT]

  • iterables (Iterable[Any]) → _VariadicZipView

Runtime calls may provide more than two configured iterables; precise public typing is provided for zero, one, and two configured iterables. Larger calls use a tuple-of-Any fallback type.

rangeslib.views.zip_transform(func, *iterables)

Zip corresponding values and call func for each group.

Return type:

ZipTransform[TypeVar(OutputT)]