Reference

This page lists all the features provided by the library.

The `RingSeq` class

RingSeq[T] wraps any Iterable[T], storing it internally as an immutable tuple. The class is generic, hashable, orderable, and implements the Python Sequence protocol — with all built-in operations (len, indexing, slicing, iteration, containment) made circular.

Instances are built with the constructor:

>>> from ring_seq import RingSeq
>>> RingSeq('ABC')
RingSeq(('A', 'B', 'C'))

Equality is positional and is agnostic to the input iterable kind used at construction:

>>> RingSeq('ABC') == RingSeq(['A', 'B', 'C']) == RingSeq(('A', 'B', 'C'))
True

Use to_list(), to_tuple(), or to_str() to unwrap at the boundary:

>>> RingSeq('ABC').rotate_left(1).to_str()
'BCA'
>>> RingSeq([1, 2, 3]).reflect_at().to_list()
[1, 3, 2]

Methods

Methods fall into the following categories:

Native sequence protocol (circular)

__getitem__ — circular indexing and slicing, e.g. rs[-1], rs[30001], rs[1:10]
__len__, __iter__, __contains__ — inherited from collections.abc.Sequence
__eq__, __lt__, __le__, __hash__ — positional comparison and hashing
index — circular element lookup

Unwrap

Indexing helper

index_from

Rotation and reflection

Slicing primitives

Iterators

Comparisons

Symmetry

Canonical forms (necklace / bracelet)

canonical_index — starting index of the lexicographically smallest rotation (Booth's algorithm, O(n))
canonical — the lex-smallest rotation; useful for hashing/deduplicating equivalent rings
bracelet — the lex-smallest representative under both rotation and reflection