slicecompose 0.1.0__py3-none-any.whl

slicecompose/__init__.py

@@ -0,0 +1,872 @@
+"""Exact composition of Python slices.
+
+``compose(s1, s2)`` returns a slice ``s3`` such that ``arr[s1][s2] == arr[s3]``
+for *every* sequence ``arr`` (equivalently, for every length ``n >= 0``), or
+``None`` if no such slice exists.  Both directions are exact:
+
+- soundness: a returned slice is equivalent for all ``n`` (not just tested ones),
+- completeness: ``None`` is returned only if no equivalent slice exists.
+
+``SliceChain(*slices)`` holds a sequence of slices applied in order and reduces
+adjacent pairs with ``compose`` until no adjacent pair merges.
+
+``SlicePlan`` (with the ready-made empty plan ``s_``) gathers slices lazily
+through ordinary bracket notation -- ``s_[2:][3:]`` -- and reduces its stored
+chain in place on first query.
+
+See EXPLANATION.md for the full soundness/completeness argument.  In brief:
+
+- The action of a slice on a length-``n`` sequence is the index progression
+  ``A(n) + k*j`` for ``j < L(n)``.  For a composition, ``A``/``L`` are, on each
+  of finitely many computable intervals of ``n`` ("stretches"), either affine,
+  an exact ceiling-division staircase, or affine plus a period-``|step1|``
+  sawtooth.  Single slices produce the same forms without the sawtooth.
+- Equality of two such functions on a stretch is decided exactly from a small
+  set of probe evaluations (endpoints, support/length thresholds, staircase
+  jump alignment) -- valid for arbitrarily large field values, no enumeration.
+- If an equivalent slice exists, its anchor structure (front/back for start
+  and stop, step sign) and its parameters are forced by the composition's tail
+  behavior, staircase jump phase, and support boundaries; the generator emits
+  the forced candidates (plus tolerance wiggles) and the verifier filters.
+
+Standard library only.
+"""
+
+from __future__ import annotations
+
+__all__ = ["compose", "SlicePlan", "s_", "SliceChain"]
+
+_INF = None  # sentinel for "unbounded stretch end"
+
+
+# --------------------------------------------------------------------------
+# Ground-truth evaluation (exact Python slice semantics, arbitrary ints)
+# --------------------------------------------------------------------------
+
+
+def _norm3(s):
+    """slice -> (start, stop, step) with step a nonzero int."""
+    if not isinstance(s, slice):
+        raise TypeError(f"expected a slice, got {type(s).__name__}")
+    a, b, k = s.start, s.stop, s.step
+    k = 1 if k is None else int(k)
+    if k == 0:
+        raise ValueError("slice step cannot be zero")
+    a = None if a is None else int(a)
+    b = None if b is None else int(b)
+    return a, b, k
+
+
+def _to_slice(t):
+    a, b, k = t
+    return slice(a, b, None if k == 1 else k)
+
+
+def _indices(t, n):
+    """Exact equivalent of slice(*t).indices(n) for arbitrary ints."""
+    a, b, k = t
+    if k > 0:
+        if a is None:
+            a2 = 0
+        elif a >= 0:
+            a2 = a if a < n else n
+        else:
+            a2 = a + n if a + n > 0 else 0
+        if b is None:
+            b2 = n
+        elif b >= 0:
+            b2 = b if b < n else n
+        else:
+            b2 = b + n if b + n > 0 else 0
+    else:
+        if a is None:
+            a2 = n - 1
+        elif a >= 0:
+            a2 = a if a < n else n - 1
+        else:
+            a2 = a + n if a + n > -1 else -1
+        if b is None:
+            b2 = -1
+        elif b >= 0:
+            b2 = b if b < n else n - 1
+        else:
+            b2 = b + n if b + n > -1 else -1
+    return a2, b2, k
+
+
+def _eval1(t, n):
+    """(first_index, step, length) of slice-triple t applied to length n."""
+    a, b, k = _indices(t, n)
+    if k > 0:
+        length = (b - a + k - 1) // k
+    else:
+        length = (b - a + k + 1) // k
+    return a, k, (length if length > 0 else 0)
+
+
+def _eval2(t1, t2, n):
+    """(first_index, step, length) of applying t1 then t2 to length n."""
+    a1, k1, m = _eval1(t1, n)
+    a2, k2, length = _eval1(t2, m)
+    return a1 + k1 * a2, k1 * k2, length
+
+
+def _pt_eq(x, y):
+    """Do two (first, step, length) actions select the same elements?"""
+    a1, k1, n1 = x
+    a2, k2, n2 = y
+    if n1 != n2:
+        return False
+    if n1 == 0:
+        return True
+    if a1 != a2:
+        return False
+    return n1 == 1 or k1 == k2
+
+
+# --------------------------------------------------------------------------
+# Mirror reduction:  arr[::-1][u] == arr[mirror(u)]  for every u and arr.
+# Mirroring start/stop fields is bitwise-not (None stays None), step negates.
+# Applying it to s1 reduces every problem to step1 >= 1:
+#   s1 = rev ; mirror(s1)   hence   s1 . s2  merges  iff  mirror(s1) . s2 does,
+# and the merged results correspond via mirror as well.
+# --------------------------------------------------------------------------
+
+
+def _mirror(t):
+    a, b, k = t
+    return (None if a is None else ~a, None if b is None else ~b, -k)
+
+
+# --------------------------------------------------------------------------
+# Monotone searches (predicates guaranteed monotone by the structure lemmas)
+# --------------------------------------------------------------------------
+
+
+def _first_true(lo, hi, pred):
+    """Smallest n in [lo, hi] with pred(n), else None; pred monotone F->T."""
+    if lo > hi:
+        return None
+    if pred(lo):
+        return lo
+    if not pred(hi):
+        return None
+    while hi - lo > 1:
+        mid = (lo + hi) // 2
+        if pred(mid):
+            hi = mid
+        else:
+            lo = mid
+    return hi
+
+
+def _last_true(lo, hi, pred):
+    """Largest n in [lo, hi] with pred(n), else None; pred monotone T->F."""
+    if lo > hi:
+        return None
+    if pred(hi):
+        return hi
+    if not pred(lo):
+        return None
+    while hi - lo > 1:
+        mid = (lo + hi) // 2
+        if pred(mid):
+            lo = mid
+        else:
+            hi = mid
+    return lo
+
+
+# --------------------------------------------------------------------------
+# Breakpoints and stretches.
+#
+# Every regime boundary of a slice's normalized (start, stop, length) as a
+# function of the sequence length is of the form  x + y (+/- 2 guard)  where
+# x, y range over {0, +-field values}: each boundary is one comparison between
+# two clamped anchor forms, each involving at most one field.  We therefore
+# take all pairwise combinations -- a generous, provably sufficient superset.
+#
+# For the composed map the intermediate length m(n) = len1(n) feeds slice s2,
+# so s2's critical values live in m-space and are pulled back to n-space by
+# monotone search (m is monotone between s1's own breakpoints, and changes by
+# at most 1 per step, so it cannot skip a critical value).
+# --------------------------------------------------------------------------
+
+
+def _combo_vals(t):
+    """Pairwise +-field combinations (with guards) for one slice triple."""
+    base = {0, 1, 2, 3}
+    for f in (t[0], t[1]):
+        if f is not None:
+            base.add(f)
+            base.add(-f)
+    vals = set()
+    for x in base:
+        for y in base:
+            for d in (-2, -1, 0, 1, 2):
+                vals.add(x + y + d)
+    return vals
+
+
+def _magnitude(t1, t2):
+    m = 8
+    for t in (t1, t2):
+        for f in t:
+            if f is not None:
+                m += abs(f)
+    return m
+
+
+def _pullback_breaks(t1, t2):
+    """n-space breakpoints of the composed action of (t1, t2), t1.step >= 1."""
+    q = t1[2]
+    n_breaks = {v for v in _combo_vals(t1) if v >= 0}
+    v_set = _combo_vals(t2)
+    v_max = max(abs(v) for v in v_set)
+    mag = _magnitude(t1, t2)
+    span = q * (v_max + 4) + 4 * mag + 64
+
+    def m_of(n):
+        return _eval1(t1, n)[2]
+
+    pieces = sorted(n_breaks | {0})
+    out = set(n_breaks)
+    for i, lo in enumerate(pieces):
+        hi = pieces[i + 1] - 1 if i + 1 < len(pieces) else lo + span
+        if hi < lo:
+            continue
+        m_lo, m_hi = m_of(lo), m_of(hi)
+        if m_lo == m_hi:
+            continue  # m constant on the piece: no crossings inside
+        inc = m_hi > m_lo
+        for v in v_set:
+            if inc:
+                if not (m_lo < v <= m_hi):
+                    continue
+                hit = _first_true(lo, hi, lambda n, v=v: m_of(n) >= v)
+            else:
+                if not (m_hi < v <= m_lo):
+                    continue
+                hit = _first_true(lo, hi, lambda n, v=v: m_of(n) < v)
+            if hit is not None:
+                out.update((hit - 2, hit - 1, hit, hit + 1, hit + 2))
+    return {v for v in out if v >= 0} | {0, 1, 2, 3}
+
+
+def _stretches(breaks, extra=()):
+    """Sorted breakpoints -> list of (u, v) closed integer stretches.
+
+    The last stretch is (u, _INF).  Regimes of all involved functions are
+    constant on each stretch.
+    """
+    pts = sorted(set(breaks) | {v for v in extra if v is not None and v >= 0} | {0})
+    out = []
+    for i, u in enumerate(pts):
+        if i + 1 < len(pts):
+            if pts[i + 1] - 1 >= u:
+                out.append((u, pts[i + 1] - 1))
+        else:
+            out.append((u, _INF))
+    return out
+
+
+# --------------------------------------------------------------------------
+# Exact verifier.
+#
+# On each stretch, both the composed action and a candidate slice have:
+#   length  L(n): constant, or an exact monotone staircase ceil((+-n + c)/D)
+#           clamped at 0 (composed D = step1 * |step2|, candidate D = |step3|);
+#   first index A(n): affine, or affine plus a period-step1 sawtooth (composed
+#           only; present only when s2's start is back-anchored, the
+#           intermediate length is non-constant on the stretch and step1 > 1).
+# Equality of such functions on a stretch follows from finitely many checks:
+#   - equal L-support thresholds (first/last n with L >= 1 and with L >= 2),
+#   - equal values at stretch endpoints / far probes,
+#   - equal first staircase-jump position plus equal step divisor D
+#     (two exact same-D monotone unit-jump staircases agreeing at a jump and
+#      in level are identical; divisors match because step3 must equal
+#      step1*step2 wherever some L >= 2 exists),
+#   - A: both sides affine -> two points suffice; a sawtooth with a wrap
+#     inside the checked span deviates from any affine by +-step1 at one of
+#     the checked points; spans >= step1 with an active sawtooth are rejected
+#     structurally (a full wrap makes A non-affine, no slice can match).
+# --------------------------------------------------------------------------
+
+
+def _l_range(evalf, u, v, lim):
+    """Contiguous {n in [u, v]: L(n) >= lim} for monotone-L stretch, or None.
+
+    Returns (w1, w2).  L is monotone on the stretch (structure lemma), so the
+    region is a prefix or suffix of [u, v].
+    """
+    lu = evalf(u)[2] >= lim
+    lv = evalf(v)[2] >= lim
+    if lu and lv:
+        return (u, v)
+    if not lu and not lv:
+        return None
+    if lv:  # increasing: suffix
+        w = _first_true(u, v, lambda n: evalf(n)[2] >= lim)
+        return (w, v)
+    w = _last_true(u, v, lambda n: evalf(n)[2] >= lim)
+    return (u, w)
+
+
+def _first_jump(evalf, w1, w2):
+    """First n in (w1, w2] where L(n) != L(w1); L monotone on [w1, w2]."""
+    l0 = evalf(w1)[2]
+    if evalf(w2)[2] == l0:
+        return None
+    return _first_true(w1 + 1, w2, lambda n: evalf(n)[2] != l0)
+
+
+def _check_stretch_finite(fc, fx, u, v, q, t2):
+    """Exact equality of composed fc and candidate fx on finite [u, v]."""
+
+    def same(n):
+        return _pt_eq(fc(n), fx(n))
+
+    pts = {u, u + 1, (u + v) // 2, v - 1, v}
+    # support thresholds (L >= 1) and step-relevance thresholds (L >= 2)
+    for lim in (1, 2):
+        rc = _l_range(fc, u, v, lim)
+        rx = _l_range(fx, u, v, lim)
+        if (rc is None) != (rx is None):
+            return False
+        if rc is None:
+            continue
+        if rc != rx:
+            return False
+        w1, w2 = rc
+        pts.update((w1, w1 + 1, (w1 + w2) // 2, w2 - 1, w2))
+        if lim == 2:
+            # staircase jump alignment inside the L>=2 region
+            jc = _first_jump(fc, w1, w2)
+            jx = _first_jump(fx, w1, w2)
+            if jc != jx:
+                return False
+            if jc is not None:
+                pts.update((jc - 1, jc, jc + 1))
+    # sawtooth wrap rejection for A on the L>=1 region
+    r1 = _l_range(fc, u, v, 1)
+    if r1 is not None:
+        w1, w2 = r1
+        if w2 - w1 + 1 >= max(q, 2) and _sawtooth_active(fc, w1, w2, q, t2):
+            return False
+    for n in pts:
+        if u <= n <= v and not same(n):
+            return False
+    return True
+
+
+def _sawtooth_active(fc, w1, w2, q, t2):
+    """Is the composed A of form affine + nontrivial sawtooth on [w1, w2]?
+
+    True iff step1 = q > 1, s2's start is effectively back-anchored on this
+    stretch (slope of a2 in m equals 1) and the intermediate length m is
+    non-constant here.  Regimes are constant per stretch, so endpoint
+    measurements are exact.
+    """
+    if q <= 1:
+        return False
+    m1 = fc.m(w1)
+    m2 = fc.m(w2)
+    if m1 == m2:
+        return False
+    a21 = _eval1(t2, m1)[0]
+    a22 = _eval1(t2, m2)[0]
+    # a2 is affine in m on the stretch with slope 0 or 1
+    return (a22 - a21) == (m2 - m1)
+
+
+class _ComposedEval:
+    """Composed ground-truth evaluator, also exposing the intermediate m."""
+
+    __slots__ = ("t1", "t2")
+
+    def __init__(self, t1, t2):
+        self.t1 = t1
+        self.t2 = t2
+
+    def __call__(self, n):
+        return _eval2(self.t1, self.t2, n)
+
+    def m(self, n):
+        return _eval1(self.t1, n)[2]
+
+
+def _check_stretch_inf(fc, fx, u, q, t2, dmax):
+    """Exact equality of fc and fx on [u, infinity).
+
+    On the final stretch both sides are constant or exactly-periodic
+    staircases with divisor <= dmax; all thresholds and the first jump lie
+    within u + 2*dmax + 5, and levels/growth are pinned by far probes.
+    """
+
+    def same(n):
+        return _pt_eq(fc(n), fx(n))
+
+    hi = u + 2 * dmax + 5
+    far = u + 3 * dmax + 7
+    for n in (u, u + 1, u + 2, hi, far, far + 1, far + dmax):
+        if not same(n):
+            return False
+    for lim in (1, 2):
+        rc = _l_range(fc, u, hi, lim)
+        rx = _l_range(fx, u, hi, lim)
+        if (rc is None) != (rx is None):
+            return False
+        if rc is None:
+            continue  # thresholds beyond hi impossible: growth shows by hi
+        if rc != rx:
+            return False
+        for n in (rc[0], rc[0] + 1, rc[1]):
+            if not same(n):
+                return False
+        if lim == 2:
+            jc = _first_jump(fc, rc[0], hi)
+            jx = _first_jump(fx, rc[0], hi)
+            if jc != jx:
+                return False
+            if jc is not None:
+                for n in (jc - 1, jc, jc + 1):
+                    if not same(n):
+                        return False
+    # A-sawtooth on the (infinite) support region: any active sawtooth wraps,
+    # making A non-affine there, which no single slice can match.
+    if fc(far)[2] >= 1 and _sawtooth_active(fc, u, far, q, t2):
+        return False
+    return True
+
+
+def _verify(t1, t2, cand, base_breaks):
+    """Exact check: does slice-triple cand equal the composition of t1, t2?"""
+    q = t1[2]
+    d_comp = q * abs(t2[2])
+    dmax = max(d_comp, abs(cand[2]), 1)
+    breaks = set(base_breaks) | {v for v in _combo_vals(cand) if v >= 0}
+    fc = _ComposedEval(t1, t2)
+
+    def fx(n):
+        return _eval1(cand, n)
+
+    for u, v in _stretches(breaks):
+        if v is _INF:
+            if not _check_stretch_inf(fc, fx, u, q, t2, dmax):
+                return False
+        else:
+            if not _check_stretch_finite(fc, fx, u, v, q, t2):
+                return False
+    return True
+
+
+# --------------------------------------------------------------------------
+# Profile: measured structural facts about the composed action, from which
+# candidate parameters are forced (see EXPLANATION.md for the forcing lemmas).
+# --------------------------------------------------------------------------
+
+_UNBOUNDED = float("inf")
+
+
+class _Profile:
+    __slots__ = (
+        "q",
+        "k2",
+        "K",
+        "D",
+        "breaks",
+        "stretches",
+        "fc",
+        "tail_mode",
+        "P",
+        "max_len",
+        "N0",
+        "N1",
+        "n_hat",
+        "A_hat",
+        "sigma",
+        "n_j",
+        "L_j",
+    )
+
+
+def _profile(t1, t2):
+    pro = _Profile()
+    pro.q = t1[2]
+    pro.k2 = t2[2]
+    pro.K = pro.q * pro.k2
+    pro.D = pro.q * abs(pro.k2)
+    pro.breaks = _pullback_breaks(t1, t2)
+    pro.stretches = _stretches(pro.breaks)
+    fc = pro.fc = _ComposedEval(t1, t2)
+    D = pro.D
+
+    # tail classification on the final (regime-settled) stretch
+    u_inf = pro.stretches[-1][0]
+    f1 = u_inf + 2 * D + 5
+    f2 = f1 + 2 * D + 5
+    l1, l2 = fc(f1)[2], fc(f2)[2]
+    if l2 > l1:
+        pro.tail_mode, pro.P = "grow", None
+    elif l1 == 0:
+        pro.tail_mode, pro.P = "empty", 0
+    elif l2 == l1:
+        pro.tail_mode, pro.P = "const", l1
+    else:  # decreasing final stretch: excluded by the structure lemmas
+        pro.tail_mode, pro.P = "shrink", None
+
+    # support bounds (first / last n with nonempty result)
+    pro.N0 = pro.N1 = None
+    for u, v in pro.stretches:
+        vv = f2 if v is _INF else v
+        r = _l_range(fc, u, vv, 1)
+        if r is not None:
+            if pro.N0 is None:
+                pro.N0 = r[0]
+            pro.N1 = r[1]
+    if pro.tail_mode in ("grow", "const"):
+        pro.N1 = _UNBOUNDED
+
+    # maximum result length over all n (monotone per stretch -> endpoints)
+    if pro.tail_mode == "grow":
+        pro.max_len = _UNBOUNDED
+    else:
+        best = 0
+        for u, v in pro.stretches:
+            vv = f2 if v is _INF else v
+            best = max(best, fc(u)[2], fc(vv)[2])
+        pro.max_len = best
+
+    # tail probes: first index A and its slope sigma at a settled point
+    pro.n_hat = f1
+    pro.A_hat = pro.sigma = pro.n_j = pro.L_j = None
+    if pro.tail_mode in ("grow", "const"):
+        pro.A_hat = fc(f1)[0]
+        pro.sigma = fc(f1 + 1)[0] - pro.A_hat
+    if pro.tail_mode == "grow":
+        lf1 = fc(f1)[2]
+        pro.n_j = _first_true(f1 + 1, f1 + D + 2, lambda n: fc(n)[2] != lf1)
+        pro.L_j = fc(pro.n_j)[2] if pro.n_j is not None else None
+    return pro
+
+
+# --------------------------------------------------------------------------
+# Candidate generation.  Anchor structure and parameters of any equivalent
+# slice are forced by the profile (tail anchors, staircase jump phase,
+# support boundaries); +-1 wiggles are included as convention armor and are
+# filtered by the exact verifier, so they never affect soundness.
+# --------------------------------------------------------------------------
+
+
+def _wig(v):
+    return (v - 1, v, v + 1)
+
+
+def _stop_pos(cands, s, e, k):
+    """Append (s, stop, k) for k > 0 families with back-anchored stop e <= 0."""
+    if e < 0:
+        cands.append((s, e, k))
+    elif e == 0:
+        cands.append((s, None, k))
+
+
+def _stop_negstep_front(cands, s, e, k):
+    """Append (s, stop, k) for k < 0 families with front-anchored stop e >= -1."""
+    if e >= 0:
+        cands.append((s, e, k))
+    elif e == -1:
+        cands.append((s, None, k))
+
+
+def _cand_grow(pro):
+    K, sig, a_hat, n_hat, n_j, l_j = (
+        pro.K,
+        pro.sigma,
+        pro.A_hat,
+        pro.n_hat,
+        pro.n_j,
+        pro.L_j,
+    )
+    cands = []
+    if n_j is None:
+        return cands
+    if sig == 0 and K > 0 and a_hat >= 0:
+        s = a_hat
+        for e in _wig(s + K * (l_j - 1) + 1 - n_j):
+            _stop_pos(cands, s, e, K)
+    elif sig == 1 and K < 0:
+        s = a_hat - n_hat
+        if s < 0:
+            for e in _wig(n_j + s + K * (l_j - 1) - 1):
+                _stop_negstep_front(cands, s, e, K)
+    return cands
+
+
+def _cand_window(pro):
+    K, P, sig, a_hat, n_hat, n0 = pro.K, pro.P, pro.sigma, pro.A_hat, pro.n_hat, pro.N0
+    cands = []
+    if sig == 0 and a_hat >= 0:
+        s = a_hat
+        if K > 0:
+            for e in (s + K * (P - 1) + 1, s + K * P):
+                if e > s:
+                    cands.append((s, e, K))
+        else:
+            # the support of [s:e:K] starts at e + 2 (at 1 for stop None),
+            # which pins e via the measured support start N0
+            for e in _wig(n0 - 2):
+                _stop_negstep_front(cands, s, e, K)
+    elif sig == 1:
+        s = a_hat - n_hat
+        if s < 0:
+            if K > 0:
+                for e in _wig(1 - n0):
+                    _stop_pos(cands, s, e, K)
+            else:
+                for e in (s + K * (P - 1) - 1, s + K * P):
+                    if e < s:
+                        cands.append((s, e, K))
+    return cands
+
+
+def _cand_single_tail(pro):
+    sig, n_hat, n0 = pro.sigma, pro.n_hat, pro.N0
+    e_val = pro.A_hat  # the single selected index at the tail probe
+    cands = []
+    if sig == 0 and e_val >= 0:
+        c = e_val
+        cands.append((c, c + 1, 1))
+        # "min-shape": select min(c, n-1) via a negative-step slice
+        for e in _wig(n0 - 2):
+            kappa = max(1, c - e)
+            _stop_negstep_front(cands, c, e, -kappa)
+    elif sig == 1:
+        s = e_val - n_hat
+        if s < 0:
+            if s + 1 < 0:
+                cands.append((s, s + 1, 1))
+            else:
+                cands.append((s, None, 1))
+            for e in _wig(1 - n0):
+                kappa = max(1, e - s)
+                _stop_pos(cands, s, e, kappa)
+    return cands
+
+
+def _cand_single_bounded(pro):
+    fc, n0, n1 = pro.fc, pro.N0, pro.N1
+    e0, e1 = fc(n0)[0], fc(n1)[0]
+    cands = []
+    # forward bump family: selects [n+s]+ while it stays below stop
+    for s in {e1 - n1, e0 - n0}:
+        if s < 0:
+            for e in _wig(n1 + s + 1):
+                if e >= 1:
+                    cands.append((s, e, max(1, e - s)))
+    # backward bump family: selects min(s', n-1) while it stays above stop
+    for sp in {e1, e0}:
+        if sp >= 0:
+            for ep in _wig(sp - n1 - 1):
+                if ep <= -1:
+                    cands.append((sp, ep, -max(1, sp + 1)))
+    return cands
+
+
+def _cand_bounded(pro):
+    K, fc, n0, n1 = pro.K, pro.fc, pro.N0, pro.N1
+    a0, a1 = fc(n0)[0], fc(n1)[0]
+    cands = []
+    if K > 0:
+        for s in {a1 - n1, a0 - n0}:
+            if s < 0:
+                for e in _wig(n1 + s + 1):
+                    if e >= 1:
+                        cands.append((s, e, K))
+    else:
+        for sp in {a1, a0}:
+            if sp >= 0:
+                for ep in _wig(sp - n1 - 1):
+                    if ep <= -1:
+                        cands.append((sp, ep, K))
+    return cands
+
+
+def _candidates(pro):
+    if pro.max_len == 0:
+        raw = [(0, 0, 1)]
+    elif pro.max_len == 1:
+        raw = _cand_single_tail(pro) if pro.N1 is _UNBOUNDED else _cand_single_bounded(pro)
+    elif pro.tail_mode == "grow":
+        raw = _cand_grow(pro)
+    elif pro.tail_mode == "const":
+        raw = _cand_window(pro)
+    elif pro.tail_mode == "empty":
+        raw = _cand_bounded(pro)
+    else:  # 'shrink': excluded by the structure lemmas
+        raw = []
+    out, seen = [], set()
+    for c in raw:
+        c = _prettify(c)
+        if c not in seen:
+            seen.add(c)
+            out.append(c)
+    return out
+
+
+def _prettify(t):
+    """Semantics-preserving cosmetic normalization of a slice triple."""
+    a, b, k = t
+    if k > 0 and a == 0:
+        a = None
+    if k < 0 and a == -1:
+        a = None
+    return (a, b, k)
+
+
+# --------------------------------------------------------------------------
+# Public API
+# --------------------------------------------------------------------------
+
+
+def compose(s1, s2):
+    """Return a slice s3 with arr[s1][s2] == arr[s3] for every sequence arr,
+    or None if no such slice exists.
+    """
+    t1, t2 = _norm3(s1), _norm3(s2)
+    if t1[2] < 0:
+        # arr[s1] == arr[::-1][mirror(s1)] with mirror(s1).step > 0, and
+        # rev-first compositions transfer exactly through mirroring.
+        r = _compose_triples(_mirror(t1), t2)
+        return None if r is None else _to_slice(_prettify(_mirror(r)))
+    r = _compose_triples(t1, t2)
+    return None if r is None else _to_slice(r)
+
+
+def _compose_triples(t1, t2):
+    pro = _profile(t1, t2)
+    for cand in _candidates(pro):
+        if _verify(t1, t2, cand, pro.breaks):
+            return cand
+    return None
+
+
+class SlicePlan:
+    """A lazily reduced chain of slices, built with bracket notation.
+
+    A plan gathers slices without doing any work: ``plan[1:][::2]`` returns
+    a new plan remembering both slices and leaves ``plan`` unchanged.  ``s_``
+    is the ready-made empty plan, so ``s_[2:][3:]`` builds a plan directly
+    from slicing syntax.  On first query (``slices``, ``slice``, ``apply``,
+    ``==`` or ``hash``) the stored chain is reduced like a
+    :class:`SliceChain` and replaced in place by the reduced form, and the
+    plan marks itself reduced, so the work happens at most once per batch
+    of gathered slices.  A plan derived from an already-reduced plan
+    inherits the collapsed prefix and only has its new tail to reduce;
+    because the reduction stack runs left to right, this yields the same
+    result as reducing the raw history, so query timing never affects the
+    outcome.  ``repr`` shows the stored chain as-is without triggering
+    reduction.
+    """
+
+    __slots__ = ("_slices", "_reduced")
+
+    def __init__(self, *slices):
+        self._slices = tuple(_to_slice(_prettify(_norm3(s))) for s in slices)
+        self._reduced = len(self._slices) <= 1
+
+    def __getitem__(self, item):
+        if not isinstance(item, slice):
+            raise TypeError("SlicePlan supports slice indices only")
+        return SlicePlan(*self._slices, item)
+
+    @property
+    def slices(self):
+        """The reduced tuple of slices; reduces (once) on first access."""
+        if not self._reduced:
+            self._slices = SliceChain(*self._slices).slices
+            self._reduced = True
+        return self._slices
+
+    @property
+    def slice(self):
+        """The single equivalent slice, or None if the chain does not
+        reduce to one.  The empty plan gives ``slice(None)``."""
+        red = self.slices
+        if len(red) > 1:
+            return None
+        return red[0] if red else slice(None)
+
+    def apply(self, seq):
+        """Apply the (reduced) slices to seq in order."""
+        for s in self.slices:
+            seq = seq[s]
+        return seq
+
+    def __eq__(self, other):
+        if not isinstance(other, SlicePlan):
+            return NotImplemented
+        return self.slices == other.slices
+
+    def __hash__(self):
+        return hash(tuple((s.start, s.stop, s.step) for s in self.slices))
+
+    def __repr__(self):
+        inner = ", ".join(repr(s) for s in self._slices)
+        return f"SlicePlan({inner})"
+
+
+s_ = SlicePlan()
+
+
+class SliceChain:
+    """A sequence of slices applied in order, e.g. seq[s0][s1]...[sk].
+
+    On construction, adjacent pairs are merged with :func:`compose` until no
+    adjacent pair merges (a merge is retried against the new left neighbor,
+    so cascading reductions are found).  ``apply`` works the same whether or
+    not any merging happened.
+    """
+
+    __slots__ = ("_slices",)
+
+    def __init__(self, *slices):
+        stack = []
+        for s in slices:
+            cur = _to_slice(_prettify(_norm3(s)))
+            while stack:
+                merged = compose(stack[-1], cur)
+                if merged is None:
+                    break
+                stack.pop()
+                cur = merged
+            stack.append(cur)
+        self._slices = tuple(stack)
+
+    @property
+    def slices(self):
+        """The reduced tuple of slices."""
+        return self._slices
+
+    def apply(self, seq):
+        """Apply the (reduced) slices to seq in order."""
+        for s in self._slices:
+            seq = seq[s]
+        return seq
+
+    def __len__(self):
+        return len(self._slices)
+
+    def __iter__(self):
+        return iter(self._slices)
+
+    def __eq__(self, other):
+        if not isinstance(other, SliceChain):
+            return NotImplemented
+        return self._slices == other._slices
+
+    def __hash__(self):
+        return hash(tuple((s.start, s.stop, s.step) for s in self._slices))
+
+    def __repr__(self):
+        inner = ", ".join(repr(s) for s in self._slices)
+        return f"SliceChain({inner})"

slicecompose/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

slicecompose-0.1.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: slicecompose
+Version: 0.1.0
+Summary: Exact composition of Python slices
+Author-email: István Sárándi <istvan.sarandi@uni-tuebingen.de>
+License: MIT License
+        
+        Copyright (c) 2026 István Sárándi
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/isarandi/slicecompose
+Project-URL: Repository, https://github.com/isarandi/slicecompose
+Project-URL: Issues, https://github.com/isarandi/slicecompose/issues
+Project-URL: Changelog, https://github.com/isarandi/slicecompose/releases
+Project-URL: Author, https://istvansarandi.com
+Keywords: slice,slicing,composition,indexing,sequences,lazy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Requires-Dist: pre-commit; extra == "lint"
+Provides-Extra: dev
+Requires-Dist: slicecompose[lint,test]; extra == "dev"
+Dynamic: license-file
+
+# slicecompose
+
+Exact composition of Python slices — pure Python, standard library only.
+
+`compose(s1, s2)` returns a slice `s3` such that `arr[s1][s2] == arr[s3]` for
+**every** sequence `arr` (every length, including 0), or `None` if no such
+slice exists. Both directions of the decision are exact:
+
+- **Sound** — a returned slice is equivalent for *all* lengths, not just
+  tested ones.
+- **Complete** — `None` is returned only when no equivalent single slice
+  exists.
+
+```python
+>>> from slicecompose import compose, SliceChain
+
+>>> compose(slice(2, None), slice(3, None))          # arr[2:][3:] == arr[5:]
+slice(5, None, None)
+
+>>> compose(slice(None, None, -1), slice(None, 1))   # arr[::-1][:1] == arr[-1:]
+slice(-1, None, None)
+
+>>> compose(slice(-2, None), slice(None, 1))         # arr[-2:][:1] == arr[-2::2]
+slice(-2, None, 2)
+
+>>> compose(slice(None, None, 2), slice(None, None, -1)) is None
+True
+```
+
+The last pair really has no equivalent: `arr[::2][::-1]` starts at index
+`n-1` for odd `n` but `n-2` for even `n`, and no fixed slice can depend on
+the parity of the length. The third example shows the opposite surprise: the
+result must select the single element at index `max(0, n-2)`, which no
+"obvious" candidate like `[-2:-1]` does (it is empty at `n == 1`) — but
+`[-2::2]` does, for every `n`.
+
+Why this is harder than plugging into `slice.indices()`: the answer must be
+a fixed slice that works *universally*, without knowing the length of the
+sequence it will be applied to. Clamping, negative indices, and the
+sign-dependent defaults make the composed selection a piecewise function of
+the length; `compose` decides exactly whether that function is realizable by
+a single slice.
+
+## API
+
+### `compose(s1, s2) -> slice | None`
+
+The core decision procedure described above. Accepts any valid slice
+objects, including huge field values (no ranges are ever materialized;
+everything is decided arithmetically).
+
+### `SliceChain(*slices)`
+
+Container for a sequence of slices applied in order, e.g.
+`seq[s0][s1]...[sk]`.
+
+- On construction, adjacent pairs are merged with `compose` until no
+  adjacent pair merges; a successful merge is retried against its new left
+  neighbor, so cascading reductions are found (e.g. `[::2], [::-1], [::-1]`
+  reduces to `[::2]` — the last two merge first).
+- `.slices` — the reduced tuple of slices.
+- `.apply(seq)` — applies the (reduced) slices in order; correct whether or
+  not any merging happened.
+
+```python
+>>> ch = SliceChain(slice(None, None, 2), slice(None, None, -1), slice(None, None, -1))
+>>> ch.slices
+(slice(None, None, 2),)
+>>> SliceChain(slice(2, None), slice(3, None)).apply("abcdefgh")
+'fgh'
+```
+
+Note that the reduced chain is *a* fixpoint of adjacent-pair merging, not
+necessarily the shortest one: pairwise reduction is not confluent, and there
+are chains whose total effect is a single slice even though no adjacent pair
+merges at all. See `EXPLANATION.md` §7 for verified examples and details.
+
+### `SlicePlan` / `s_`
+
+Lazy plan building with ordinary bracket notation. `s_` is the ready-made
+empty plan; slicing a plan returns a *new* plan (the original is unchanged),
+and nothing is computed while slices are gathered. On the first query —
+`.slices`, `.slice`, `.apply(seq)`, `==`/`hash` — the plan reduces its
+stored chain in place and remembers that it did, so the reduction runs at
+most once per batch of gathered slices.
+
+```python
+>>> from slicecompose import s_
+>>> s_[2:][3:].slice
+slice(5, None, None)
+>>> plan = s_[100:]
+>>> plan[::2].slices                  # branching; plan itself is unchanged
+(slice(100, None, 2),)
+>>> s_[::2][::-1].slice is None       # irreducible pairs stay a chain
+True
+>>> s_[::2][::-1].apply(tuple(range(9)))
+(8, 6, 4, 2, 0)
+```
+
+This is aimed at expensive media (video streams, remote arrays): build the
+access plan symbolically with normal slicing syntax, reduce it, and only
+then touch the data. A reduced slice needs no length to be executed — its
+anchors are only "offset from the front" and "offset from the end" — so the
+plan works even when the element count is unknown or unreliable.
+
+## Correctness
+
+`EXPLANATION.md` contains the full argument for why the implementation is
+sound and complete for every length — the infinite quantification over `n`
+is reduced to finitely many exact checks (regime breakpoints, per-stretch
+staircase/sawtooth normal forms, an exact verifier, and profile-forced
+candidate generation). Returned slices are always validated by the exact
+verifier, so soundness does not rest on the candidate generator.
+
+The test suite (`test_slicecompose.py`) additionally audits both failure
+modes empirically: exhaustive small-field grids checked for wrong merges by
+brute force and for missed merges against large candidate tables, huge-field
+randomized soundness checks, structural consistency probes, and the problem
+statement's examples.
+
+## Installation
+
+```bash
+pip install slicecompose      # from PyPI, once published
+pip install .                 # from a checkout
+```
+
+Pure Python, no dependencies.
+
+## Running the tests
+
+```bash
+pytest                        # quick tier, ~30 s
+SLICECOMPOSE_FULL=1 pytest    # exhaustive grids, ~35 min
+```
+
+`verify_examples.py` independently re-checks the examples claimed in
+`PROBLEM.md` by direct evaluation.
+
+## Files
+
+| file                         | contents                                                 |
+|------------------------------|----------------------------------------------------------|
+| `src/slicecompose/`          | the library (`compose`, `SlicePlan`/`s_`, `SliceChain`)  |
+| `tests/test_slicecompose.py` | test suite (quick and exhaustive tiers)                  |
+| `PROBLEM.md`                 | the problem statement                                    |
+| `EXPLANATION.md`             | soundness/completeness argument                          |
+| `verify_examples.py`         | standalone check of the problem's examples               |

slicecompose-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+slicecompose/__init__.py,sha256=Vs66wRek-2ezMIoYsVvx83L5Iw74kSNoLkh7Kz53hXA,28149
+slicecompose/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+slicecompose-0.1.0.dist-info/licenses/LICENSE,sha256=Yo-WMDNvrjL9OitVRBuKaYeo33FiSJLpONpT68bvA-s,1074
+slicecompose-0.1.0.dist-info/METADATA,sha256=2TyUJcOuUn-wWwI-b7dKJ_ydQfsgchy8vbbfmhl0N8w,8753
+slicecompose-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+slicecompose-0.1.0.dist-info/scm_file_list.json,sha256=etrWSXBGntF9qzj2pRZ43j2X3RjZJ3K9dLJigVy7uT8,289
+slicecompose-0.1.0.dist-info/scm_version.json,sha256=GBIDAdGgdV59UHaoI0hz1u_QOuisrSMw_jyTixf-Rpk,160
+slicecompose-0.1.0.dist-info/top_level.txt,sha256=nnony279CCiGALJDWZB3u4KZ9GeSHCeeUTbqyU92S28,13
+slicecompose-0.1.0.dist-info/RECORD,,

slicecompose-0.1.0.dist-info/WHEEL

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

slicecompose-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 István Sárándi
+
+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.

slicecompose-0.1.0.dist-info/scm_file_list.json

@@ -0,0 +1,15 @@
+{
+  "files": [
+    ".gitignore",
+    "README.md",
+    "EXPLANATION.md",
+    "CLAUDE.md",
+    "pyproject.toml",
+    "PROBLEM.md",
+    "LICENSE",
+    "verify_examples.py",
+    "src/slicecompose/__init__.py",
+    ".github/workflows/python-publish.yml",
+    "tests/test_slicecompose.py"
+  ]
+}

slicecompose-0.1.0.dist-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.1.0",
+  "distance": 0,
+  "node": "g933f131d8ec6bd93de56d5173807f6ed02281585",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-16"
+}

slicecompose-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+slicecompose