rangeable 1.0.0__tar.gz

rangeable-1.0.0/.gitignore

@@ -0,0 +1,33 @@
+# Byte-compiled / optimised
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Build artefacts
+wheelhouse/

rangeable-1.0.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-05-10
+
+Initial public release of the Python reference implementation of the
+[Rangeable RFC](https://github.com/ZhgChgLi/RangeableRFC).
+
+### Added
+- `Rangeable[E]` generic container with the full RFC §3 API:
+  `insert`, `__getitem__` / `active_at`, `get_range`, `transitions`,
+  `copy`, iteration over `(element, ranges)` pairs, `len`, `__bool__`,
+  `version`, `count`, `empty`.
+- `Interval`, `Slot`, `TransitionEvent`, `TransitionKind` value types
+  (frozen dataclasses with slots).
+- `RangeableError` (subclass of `ValueError`) and
+  `InvalidIntervalError` (subclass of `RangeableError`).
+- PEP 561 `py.typed` marker for downstream type checkers.
+
+### Verified
+- 23 RFC §10 contract tests.
+- 86 cross-language probes against the shared 160-op fixture (sha256
+  `316ac8619fd632174b2374ed2137348e8d744e3904b002761d0dbdce38ea2edf`,
+  byte-identical to the Ruby and Swift fixtures).
+- Property test against a brute-force oracle over 1000 random ops.

rangeable-1.0.0/LICENSE

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

rangeable-1.0.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: rangeable
+Version: 1.0.0
+Summary: Hashable-element interval set with first-insert ordered active queries.
+Project-URL: Homepage, https://github.com/ZhgChgLi/PythonRangeable
+Project-URL: Source, https://github.com/ZhgChgLi/PythonRangeable
+Project-URL: Documentation, https://github.com/ZhgChgLi/RangeableRFC/blob/main/RFC.md
+Project-URL: Issues, https://github.com/ZhgChgLi/PythonRangeable/issues
+Project-URL: Changelog, https://github.com/ZhgChgLi/PythonRangeable/blob/main/CHANGELOG.md
+Author-email: ZhgChgLi <zhgchgli@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: boundary-events,interval,merge,range,rfc
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PythonRangeable
+
+[![PyPI](https://img.shields.io/pypi/v/rangeable.svg)](https://pypi.org/project/rangeable/)
+[![Python](https://img.shields.io/pypi/pyversions/rangeable.svg)](https://pypi.org/project/rangeable/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Reference Python implementation of [`Rangeable<Element>`](https://github.com/ZhgChgLi/RangeableRFC) — a generic, integer-coordinate, closed-interval set container with first-insert ordered active queries.
+
+## Installation
+
+```bash
+pip install rangeable
+```
+
+## Usage
+
+```python
+from dataclasses import dataclass
+from rangeable import Rangeable
+
+@dataclass(frozen=True, slots=True)
+class Strong: pass
+
+@dataclass(frozen=True, slots=True)
+class Italic: pass
+
+@dataclass(frozen=True, slots=True)
+class Link:
+    url: str
+
+r: Rangeable = Rangeable()
+r.insert(Strong(), start=2, end=5)
+r.insert(Strong(), start=3, end=7)        # merges with [2, 5] → [2, 7]
+r.insert(Strong(), start=9, end=11)       # disjoint
+r.insert(Italic(), start=3, end=8)
+
+r.get_range(Strong())   # [(2, 7), (9, 11)]
+r.get_range(Italic())   # [(3, 8)]
+
+r[4].objs               # (Strong(), Italic())   first-insert order
+r[8].objs               # (Italic(),)
+r[10].objs              # (Strong(),)
+```
+
+### Sweep iteration via transitions
+
+```python
+for event in r.transitions(lo=0, hi=15):
+    print(event.coordinate, event.kind.value, event.element)
+```
+
+## API
+
+| Member | Returns | Notes |
+|---|---|---|
+| `Rangeable()` | constructor | empty container |
+| `r.insert(e, *, start, end)` | `Rangeable` (chainable) | raises `InvalidIntervalError` on `start > end` |
+| `r[i]` | `Slot[E]` | `Slot.objs` is the active-set tuple |
+| `r.get_range(e)` | `list[tuple[int, int]]` | merged disjoint ranges |
+| `r.transitions(*, lo, hi)` | `list[TransitionEvent[E]]` | `hi=None` means +∞ |
+| `r.count` / `len(r)` | `int` | distinct elements |
+| `r.empty` / `bool(r)` | `bool` | |
+| `iter(r)` | `Iterator[(E, list[(int, int)])]` | first-insert order |
+| `r.copy()` | `Rangeable[E]` | deep copy |
+| `r.version` | `int` | unchanged on idempotent insert |
+
+## Semantics
+
+- **End is inclusive**: `[a, b]` covers `a..=b`, both ends.
+- **Same-element merging**: equal elements (by `__eq__` + `__hash__`) merge on overlap or integer adjacency. `[2, 4] ∪ [5, 7] = [2, 7]`.
+- **Idempotent insert**: re-inserting a contained interval does not bump `version`.
+- **Out-of-order rejected**: `r.insert(e, start=5, end=2)` raises `InvalidIntervalError`.
+- **Active-set ordering**: deterministic — first-insert order of the element.
+- **Coordinate sentinel**: a close event for an interval ending at the optional `int_max` sentinel carries `coordinate is None` (None == +∞ per RFC §4.7). Python ints are unbounded, so this only matters when integrating with bounded-int languages; the fixture does not exercise it.
+
+See [RangeableRFC](https://github.com/ZhgChgLi/RangeableRFC) § 4 for normative semantics and § 10 for the 23-case test contract.
+
+## Cross-language consistency
+
+This Python implementation, the [Ruby implementation](https://github.com/ZhgChgLi/RubyRangeable), and the [Swift implementation](https://github.com/ZhgChgLi/SwiftRangeable) share a 160-op / 86-probe JSON fixture; all three produce byte-identical outputs.
+
+## See also
+
+- **[RangeableRFC](https://github.com/ZhgChgLi/RangeableRFC)** — normative specification.
+- **[RubyRangeable](https://github.com/ZhgChgLi/RubyRangeable)** — sibling Ruby reference implementation, published as the `rangeable` gem.
+- **[SwiftRangeable](https://github.com/ZhgChgLi/SwiftRangeable)** — sibling Swift reference implementation.
+- **[JSRangeable](https://github.com/ZhgChgLi/JSRangeable)** — sibling TypeScript reference implementation, published as the `rangeable-js` npm package.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -q
+```
+
+The suite covers the full RFC § 10 contract, the cross-language fixture replay, and a property test against a brute-force oracle.
+
+## License
+
+MIT (c) ZhgChgLi

rangeable-1.0.0/README.md

@@ -0,0 +1,100 @@
+# PythonRangeable
+
+[![PyPI](https://img.shields.io/pypi/v/rangeable.svg)](https://pypi.org/project/rangeable/)
+[![Python](https://img.shields.io/pypi/pyversions/rangeable.svg)](https://pypi.org/project/rangeable/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Reference Python implementation of [`Rangeable<Element>`](https://github.com/ZhgChgLi/RangeableRFC) — a generic, integer-coordinate, closed-interval set container with first-insert ordered active queries.
+
+## Installation
+
+```bash
+pip install rangeable
+```
+
+## Usage
+
+```python
+from dataclasses import dataclass
+from rangeable import Rangeable
+
+@dataclass(frozen=True, slots=True)
+class Strong: pass
+
+@dataclass(frozen=True, slots=True)
+class Italic: pass
+
+@dataclass(frozen=True, slots=True)
+class Link:
+    url: str
+
+r: Rangeable = Rangeable()
+r.insert(Strong(), start=2, end=5)
+r.insert(Strong(), start=3, end=7)        # merges with [2, 5] → [2, 7]
+r.insert(Strong(), start=9, end=11)       # disjoint
+r.insert(Italic(), start=3, end=8)
+
+r.get_range(Strong())   # [(2, 7), (9, 11)]
+r.get_range(Italic())   # [(3, 8)]
+
+r[4].objs               # (Strong(), Italic())   first-insert order
+r[8].objs               # (Italic(),)
+r[10].objs              # (Strong(),)
+```
+
+### Sweep iteration via transitions
+
+```python
+for event in r.transitions(lo=0, hi=15):
+    print(event.coordinate, event.kind.value, event.element)
+```
+
+## API
+
+| Member | Returns | Notes |
+|---|---|---|
+| `Rangeable()` | constructor | empty container |
+| `r.insert(e, *, start, end)` | `Rangeable` (chainable) | raises `InvalidIntervalError` on `start > end` |
+| `r[i]` | `Slot[E]` | `Slot.objs` is the active-set tuple |
+| `r.get_range(e)` | `list[tuple[int, int]]` | merged disjoint ranges |
+| `r.transitions(*, lo, hi)` | `list[TransitionEvent[E]]` | `hi=None` means +∞ |
+| `r.count` / `len(r)` | `int` | distinct elements |
+| `r.empty` / `bool(r)` | `bool` | |
+| `iter(r)` | `Iterator[(E, list[(int, int)])]` | first-insert order |
+| `r.copy()` | `Rangeable[E]` | deep copy |
+| `r.version` | `int` | unchanged on idempotent insert |
+
+## Semantics
+
+- **End is inclusive**: `[a, b]` covers `a..=b`, both ends.
+- **Same-element merging**: equal elements (by `__eq__` + `__hash__`) merge on overlap or integer adjacency. `[2, 4] ∪ [5, 7] = [2, 7]`.
+- **Idempotent insert**: re-inserting a contained interval does not bump `version`.
+- **Out-of-order rejected**: `r.insert(e, start=5, end=2)` raises `InvalidIntervalError`.
+- **Active-set ordering**: deterministic — first-insert order of the element.
+- **Coordinate sentinel**: a close event for an interval ending at the optional `int_max` sentinel carries `coordinate is None` (None == +∞ per RFC §4.7). Python ints are unbounded, so this only matters when integrating with bounded-int languages; the fixture does not exercise it.
+
+See [RangeableRFC](https://github.com/ZhgChgLi/RangeableRFC) § 4 for normative semantics and § 10 for the 23-case test contract.
+
+## Cross-language consistency
+
+This Python implementation, the [Ruby implementation](https://github.com/ZhgChgLi/RubyRangeable), and the [Swift implementation](https://github.com/ZhgChgLi/SwiftRangeable) share a 160-op / 86-probe JSON fixture; all three produce byte-identical outputs.
+
+## See also
+
+- **[RangeableRFC](https://github.com/ZhgChgLi/RangeableRFC)** — normative specification.
+- **[RubyRangeable](https://github.com/ZhgChgLi/RubyRangeable)** — sibling Ruby reference implementation, published as the `rangeable` gem.
+- **[SwiftRangeable](https://github.com/ZhgChgLi/SwiftRangeable)** — sibling Swift reference implementation.
+- **[JSRangeable](https://github.com/ZhgChgLi/JSRangeable)** — sibling TypeScript reference implementation, published as the `rangeable-js` npm package.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -q
+```
+
+The suite covers the full RFC § 10 contract, the cross-language fixture replay, and a property test against a brute-force oracle.
+
+## License
+
+MIT (c) ZhgChgLi

rangeable-1.0.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rangeable"
+version = "1.0.0"
+description = "Hashable-element interval set with first-insert ordered active queries."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "ZhgChgLi", email = "zhgchgli@gmail.com" }]
+keywords = ["interval", "range", "merge", "boundary-events", "rfc"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage      = "https://github.com/ZhgChgLi/PythonRangeable"
+Source        = "https://github.com/ZhgChgLi/PythonRangeable"
+Documentation = "https://github.com/ZhgChgLi/RangeableRFC/blob/main/RFC.md"
+Issues        = "https://github.com/ZhgChgLi/PythonRangeable/issues"
+Changelog     = "https://github.com/ZhgChgLi/PythonRangeable/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build>=1.2", "twine>=5"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rangeable"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/rangeable/**/*.py",
+  "src/rangeable/py.typed",
+  "README.md",
+  "CHANGELOG.md",
+  "LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

rangeable-1.0.0/src/rangeable/__init__.py

@@ -0,0 +1,26 @@
+"""Rangeable — hashable-element interval set with first-insert ordered active queries.
+
+Reference Python implementation of the language-neutral Rangeable spec.
+See https://github.com/ZhgChgLi/RangeableRFC for the normative document.
+"""
+
+from __future__ import annotations
+
+from ._core import Rangeable
+from ._errors import InvalidIntervalError, RangeableError
+from ._interval import Interval
+from ._slot import Slot
+from ._transition import TransitionEvent, TransitionKind
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Rangeable",
+    "Interval",
+    "Slot",
+    "TransitionEvent",
+    "TransitionKind",
+    "RangeableError",
+    "InvalidIntervalError",
+    "__version__",
+]

rangeable-1.0.0/src/rangeable/_boundary_index.py

@@ -0,0 +1,210 @@
+"""Lazy boundary-event index per RFC §5.2 / §6.3."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Generic, Hashable, TypeVar
+
+from ._transition import TransitionEvent, TransitionKind
+
+E = TypeVar("E", bound=Hashable)
+
+
+@dataclass(frozen=True, slots=True)
+class _RawEvent(Generic[E]):
+    """Internal event carrying the ord tiebreaker. Public API exposes
+    :class:`TransitionEvent` (without ord)."""
+
+    coordinate: int | None
+    kind: TransitionKind
+    element: E
+    ord: int
+
+
+@dataclass(frozen=True, slots=True)
+class Segment(Generic[E]):
+    """One maximal run of integers over which the active set is constant."""
+
+    lo: int
+    hi: int
+    active: tuple[E, ...]
+
+
+def _compare_coord(a: int | None, b: int | None) -> int:
+    """Total order over coordinates: ``None`` (== +∞) is greater than any
+    finite int. Returns -1 / 0 / +1.
+    """
+    if a is None and b is None:
+        return 0
+    if a is None:
+        return 1
+    if b is None:
+        return -1
+    if a < b:
+        return -1
+    if a > b:
+        return 1
+    return 0
+
+
+def _coord_le(coord: int | None, upper: int | None) -> bool:
+    return _compare_coord(coord, upper) <= 0
+
+
+def _coord_ge(coord: int | None, threshold: int | None) -> bool:
+    return _compare_coord(coord, threshold) >= 0
+
+
+class BoundaryIndex(Generic[E]):
+    """Built from a snapshot of the per-element interval map plus the
+    insertion-order map ``ord``. Carries:
+
+    * ``events``   — sorted tuple of :class:`TransitionEvent` under §4.5
+      ordering (without the internal ``ord`` field).
+    * ``segments`` — sorted, disjoint tuple of :class:`Segment` covering
+      every coordinate at which the active set is non-empty. Active sets
+      are sorted by ``ord(e)`` ascending.
+    * ``version``  — snapshot of :class:`Rangeable` version at build time.
+
+    The owner :class:`Rangeable` invalidates the index by setting its
+    reference to ``None`` on any mutation; reads compare versions to
+    decide whether to rebuild (T3 mutex pattern, §11).
+    """
+
+    __slots__ = ("events", "segments", "version", "_raw_events")
+
+    def __init__(
+        self,
+        events: tuple[TransitionEvent[E], ...],
+        segments: tuple[Segment[E], ...],
+        version: int,
+        raw_events: tuple[_RawEvent[E], ...],
+    ) -> None:
+        self.events = events
+        self.segments = segments
+        self.version = version
+        self._raw_events = raw_events
+
+    def segment_at(self, coord: int) -> Segment[E] | None:
+        """Find the segment containing ``coord``, or ``None`` if none.
+        O(log |segments|). ``coord`` must be a finite int.
+        """
+        segs = self.segments
+        lo, hi = 0, len(segs)
+        while lo < hi:
+            mid = (lo + hi) // 2
+            if segs[mid].hi >= coord:
+                hi = mid
+            else:
+                lo = mid + 1
+        if lo >= len(segs):
+            return None
+        seg = segs[lo]
+        return seg if seg.lo <= coord else None
+
+    def events_in_range(
+        self, lo: int, upper_coord: int | None
+    ) -> list[TransitionEvent[E]]:
+        """Returns events whose coordinate falls in ``[lo, upper_coord]``.
+        ``upper_coord`` may be ``None`` to mean +∞.
+        """
+        events = self.events
+        n = len(events)
+        # Binary search for first index i where events[i].coordinate >= lo.
+        l, r = 0, n
+        while l < r:
+            m = (l + r) // 2
+            if _coord_ge(events[m].coordinate, lo):
+                r = m
+            else:
+                l = m + 1
+        result: list[TransitionEvent[E]] = []
+        i = l
+        while i < n and _coord_le(events[i].coordinate, upper_coord):
+            result.append(events[i])
+            i += 1
+        return result
+
+    @classmethod
+    def build(
+        cls,
+        intervals: dict,  # element -> DisjointSet
+        ord_map: dict,  # element -> int
+        snapshot_version: int,
+        int_max_sentinel: int | None = None,
+    ) -> "BoundaryIndex[E]":
+        """Build a fresh index. ``int_max_sentinel`` (default ``None``) lets
+        the caller opt into "treat ``hi == sentinel`` as +∞" semantics for
+        cross-language fixture parity with bounded-int languages.
+        """
+        raw: list[_RawEvent] = []
+        for element, ds in intervals.items():
+            element_ord = ord_map[element]
+            for iv in ds:
+                raw.append(
+                    _RawEvent(iv.lo, TransitionKind.OPEN, element, element_ord)
+                )
+                if int_max_sentinel is not None and iv.hi == int_max_sentinel:
+                    close_coord: int | None = None
+                else:
+                    close_coord = iv.hi + 1
+                raw.append(
+                    _RawEvent(close_coord, TransitionKind.CLOSE, element, element_ord)
+                )
+
+        # Sort: coord ascending (None > finite); same-coord opens before
+        # closes; same-coord-and-kind opens by ord asc, closes by ord desc.
+        def sort_key(ev: _RawEvent) -> tuple:
+            # First component: (1, 0) for None (treat as greater than any
+            # finite); (0, coord) for finite. Tuple comparison handles it.
+            if ev.coordinate is None:
+                coord_key: tuple = (1, 0)
+            else:
+                coord_key = (0, ev.coordinate)
+            kind_key = 0 if ev.kind == TransitionKind.OPEN else 1
+            ord_tiebreak = ev.ord if ev.kind == TransitionKind.OPEN else -ev.ord
+            return (coord_key, kind_key, ord_tiebreak)
+
+        raw.sort(key=sort_key)
+
+        public_events = tuple(
+            TransitionEvent(ev.coordinate, ev.kind, ev.element) for ev in raw
+        )
+        segments = cls._materialise_segments(raw)
+        return cls(public_events, segments, snapshot_version, tuple(raw))
+
+    @staticmethod
+    def _materialise_segments(events: list[_RawEvent]) -> tuple[Segment, ...]:
+        """Sweep events linearly, materialising a Segment for every maximal
+        run of integers over which the active set is constant. Per RFC §6.3
+        we do not emit a segment whose active set is empty.
+        """
+        segments: list[Segment] = []
+        active_by_ord: dict[int, object] = {}
+        prev_coord: int | None = None
+        i = 0
+        n = len(events)
+        while i < n:
+            coord = events[i].coordinate
+
+            # Emit segment for [prev_coord, coord-1] before processing
+            # events at this coord, if the active set is non-empty.
+            if prev_coord is not None and active_by_ord and coord is not None:
+                seg_hi = coord - 1
+                snapshot = tuple(
+                    active_by_ord[o] for o in sorted(active_by_ord.keys())
+                )
+                segments.append(Segment(prev_coord, seg_hi, snapshot))
+
+            # Apply every event at this coord.
+            while i < n and events[i].coordinate == coord:
+                ev_i = events[i]
+                if ev_i.kind == TransitionKind.OPEN:
+                    active_by_ord[ev_i.ord] = ev_i.element
+                else:
+                    active_by_ord.pop(ev_i.ord, None)
+                i += 1
+
+            prev_coord = coord
+
+        return tuple(segments)

rangeable-1.0.0/src/rangeable/_core.py

@@ -0,0 +1,179 @@
+"""Main Rangeable container."""
+
+from __future__ import annotations
+
+from typing import Generic, Hashable, Iterator, TypeVar
+
+from ._boundary_index import BoundaryIndex
+from ._disjoint_set import DisjointSet, InsertResult
+from ._errors import InvalidIntervalError
+from ._slot import Slot
+from ._transition import TransitionEvent
+
+E = TypeVar("E", bound=Hashable)
+
+_EMPTY_OBJS: tuple = ()
+
+
+class Rangeable(Generic[E]):
+    """Generic, integer-coordinate, closed-interval set container.
+
+    Pairs hashable elements with their merged disjoint integer ranges
+    and supports three query families:
+
+    * by-element via :meth:`get_range`
+    * by-position via ``r[i]`` / :meth:`active_at`
+    * by-range via :meth:`transitions`
+
+    See `RFC §3 <https://github.com/ZhgChgLi/RangeableRFC>`_ for the
+    full normative API surface.
+    """
+
+    __slots__ = (
+        "_intervals",
+        "_insertion_order",
+        "_ord",
+        "_version",
+        "_event_index",
+    )
+
+    def __init__(self) -> None:
+        self._intervals: dict[E, DisjointSet] = {}
+        self._insertion_order: list[E] = []
+        self._ord: dict[E, int] = {}
+        self._version: int = 0
+        self._event_index: BoundaryIndex[E] | None = None
+
+    @classmethod
+    def empty(cls) -> "Rangeable[E]":
+        """Sugar matching the RFC §3.1 ``Rangeable.empty()`` alias."""
+        return cls()
+
+    @property
+    def version(self) -> int:
+        return self._version
+
+    def insert(self, element: E, *, start: int, end: int) -> "Rangeable[E]":
+        """Insert ``element`` covering the closed interval ``[start, end]``.
+
+        Idempotent per RFC §3.2: re-inserting a sub-range that is already
+        fully contained leaves the container unchanged and does NOT bump
+        :attr:`version`.
+
+        Raises :class:`InvalidIntervalError` if ``start > end``.
+
+        Returns ``self`` for chaining.
+        """
+        if start > end:
+            raise InvalidIntervalError(f"start ({start}) > end ({end})")
+
+        ds = self._intervals.get(element)
+        if ds is None:
+            ds = DisjointSet()
+            self._intervals[element] = ds
+            self._insertion_order.append(element)
+            self._ord[element] = len(self._insertion_order)
+
+        result = ds.insert(start, end)
+        if result == InsertResult.MUTATED:
+            self._version += 1
+            self._event_index = None
+        return self
+
+    def __getitem__(self, i: int) -> Slot[E]:
+        """Active-element list at ``i``. RFC §3.3.
+
+        O(log |segments| + r) once the index is built. Returns an empty
+        :class:`Slot` for coordinates outside every segment.
+        """
+        self._ensure_event_index_fresh()
+        assert self._event_index is not None
+        seg = self._event_index.segment_at(i)
+        if seg is None:
+            return Slot(_EMPTY_OBJS)
+        return Slot(seg.active)
+
+    def active_at(self, *, index: int) -> Slot[E]:
+        """Same as ``self[index]``, named to match RFC §3.3."""
+        return self[index]
+
+    def get_range(self, element: E) -> list[tuple[int, int]]:
+        """Merged ranges for ``element`` as ``[(lo, hi), ...]``. RFC §3.4.
+
+        Returns an empty list when the element has never been inserted.
+        """
+        ds = self._intervals.get(element)
+        if ds is None:
+            return []
+        return ds.to_pairs()
+
+    def transitions(self, *, lo: int, hi: int | None) -> list[TransitionEvent[E]]:
+        """Open / close events within the inclusive coordinate range
+        ``[lo, hi]``. RFC §3.5.
+
+        ``hi=None`` means +∞ (include all events through the upper bound).
+
+        Raises :class:`InvalidIntervalError` if ``lo > hi`` or ``lo`` is
+        ``None``.
+        """
+        if lo is None:
+            raise InvalidIntervalError("transitions: lo must not be None")
+        if hi is not None and lo > hi:
+            raise InvalidIntervalError(f"lo ({lo}) > hi ({hi})")
+
+        self._ensure_event_index_fresh()
+        assert self._event_index is not None
+        upper = None if hi is None else hi + 1
+        return self._event_index.events_in_range(lo, upper)
+
+    def __len__(self) -> int:
+        """Number of distinct equivalence-class elements ever inserted."""
+        return len(self._insertion_order)
+
+    @property
+    def count(self) -> int:
+        return len(self._insertion_order)
+
+    @property
+    def empty(self) -> bool:
+        return not self._insertion_order
+
+    def __bool__(self) -> bool:
+        return bool(self._insertion_order)
+
+    def __iter__(self) -> Iterator[tuple[E, list[tuple[int, int]]]]:
+        """Yield ``(element, ranges)`` pairs in insertion-order ascending."""
+        for element in self._insertion_order:
+            yield element, self._intervals[element].to_pairs()
+
+    def copy(self) -> "Rangeable[E]":
+        """Deep copy. Mutation on the copy MUST NOT affect this instance,
+        and vice versa.
+        """
+        dup = Rangeable[E]()
+        for element in self._insertion_order:
+            dup._replant(element, self._intervals[element], self._ord[element])
+        dup._version = self._version
+        return dup
+
+    def __copy__(self) -> "Rangeable[E]":
+        return self.copy()
+
+    def __deepcopy__(self, memo: dict) -> "Rangeable[E]":
+        return self.copy()
+
+    def _ensure_event_index_fresh(self) -> None:
+        if self._event_index is not None and self._event_index.version == self._version:
+            return
+        v_start = self._version
+        rebuilt = BoundaryIndex.build(self._intervals, self._ord, v_start)
+        if self._version == v_start:
+            self._event_index = rebuilt
+
+    def _replant(self, element: E, source_set: DisjointSet, source_ord: int) -> None:
+        new_set = DisjointSet()
+        for iv in source_set:
+            new_set.insert(iv.lo, iv.hi)
+        self._intervals[element] = new_set
+        self._insertion_order.append(element)
+        self._ord[element] = source_ord

rangeable-1.0.0/src/rangeable/_disjoint_set.py

@@ -0,0 +1,104 @@
+"""Sorted, disjoint, non-adjacent merged-interval list for one element."""
+
+from __future__ import annotations
+
+import bisect
+from enum import Enum
+from typing import Iterator
+
+from ._errors import InvalidIntervalError
+from ._interval import Interval
+
+
+class InsertResult(Enum):
+    """Outcome of :meth:`DisjointSet.insert`. The owning :class:`Rangeable`
+    bumps its version counter only on ``MUTATED``; ``IDEMPOTENT`` means the
+    insert was absorbed and the canonical state is unchanged (RFC Test #21,
+    Lemma 6.5.B).
+    """
+
+    MUTATED = "mutated"
+    IDEMPOTENT = "idempotent"
+
+
+class DisjointSet:
+    """Maintains the RFC §5.1 (I1) invariant for one element:
+
+    * sorted by ``lo`` strictly ascending
+    * any two adjacent entries ``(lo1, hi1), (lo2, hi2)`` satisfy
+      ``hi1 + 1 < lo2`` (no overlap, no integer adjacency)
+    * ``lo <= hi`` for every entry
+
+    Mirrors the Ruby reference implementation line-for-line, including
+    the §6.1 cleaner-variant containment fast-path.
+    """
+
+    __slots__ = ("_entries",)
+
+    def __init__(self) -> None:
+        self._entries: list[Interval] = []
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def __iter__(self) -> Iterator[Interval]:
+        return iter(self._entries)
+
+    @property
+    def empty(self) -> bool:
+        return not self._entries
+
+    def to_pairs(self) -> list[tuple[int, int]]:
+        """Snapshot the merged intervals as ``[(lo, hi), ...]``."""
+        return [(iv.lo, iv.hi) for iv in self._entries]
+
+    def insert(self, lo: int, hi: int) -> InsertResult:
+        """Insert ``[lo, hi]`` into the set, performing union-with-merge per
+        RFC §6.1.
+
+        Returns :attr:`InsertResult.MUTATED` if the canonical state changed
+        (caller should bump version), :attr:`InsertResult.IDEMPOTENT` if the
+        insert was absorbed by an existing entry (caller MUST NOT bump
+        version, per Test #21 and Lemma 6.5.B).
+        """
+        if lo > hi:
+            raise InvalidIntervalError(f"lo ({lo}) > hi ({hi})")
+
+        # Step 4 of §6.1: bsearch for the leftmost touch candidate.
+        # Predicate: ``iv.hi + 1 >= lo``. We use ``iv.hi + 1`` (not
+        # ``lo - 1``) to avoid Integer underflow at ``lo == Int.min``
+        # boundaries (§4.7 C5). Python ints are unbounded but we mirror
+        # the Ruby form for cross-language byte parity.
+        i0 = bisect.bisect_left(
+            self._entries, lo, key=lambda iv: iv.hi + 1
+        )
+
+        # Step 5: collect contiguous touch entries while
+        # ``entries[i].lo <= hi + 1``.
+        to_merge_end = i0
+        n = len(self._entries)
+        while to_merge_end < n and self._entries[to_merge_end].lo <= hi + 1:
+            to_merge_end += 1
+        merge_count = to_merge_end - i0
+
+        # Step 6: containment idempotent fast-path. If we touch exactly one
+        # existing entry that fully covers [lo, hi], this insert is a no-op.
+        # MUST NOT mutate, MUST NOT bump version.
+        if merge_count == 1:
+            existing = self._entries[i0]
+            if existing.lo <= lo and hi <= existing.hi:
+                return InsertResult.IDEMPOTENT
+
+        # Step 7: real mutation path. Compute merged bounds, splice in.
+        new_lo = lo
+        new_hi = hi
+        if merge_count > 0:
+            first = self._entries[i0]
+            last = self._entries[to_merge_end - 1]
+            if first.lo < new_lo:
+                new_lo = first.lo
+            if last.hi > new_hi:
+                new_hi = last.hi
+        merged = Interval(new_lo, new_hi)
+        self._entries[i0:to_merge_end] = [merged]
+        return InsertResult.MUTATED

rangeable-1.0.0/src/rangeable/_errors.py

@@ -0,0 +1,15 @@
+"""Error types for Rangeable."""
+
+from __future__ import annotations
+
+
+class RangeableError(ValueError):
+    """Base class for Rangeable errors. Subclasses ValueError so callers can
+    catch generic value-related issues alongside Rangeable-specific ones.
+    """
+
+
+class InvalidIntervalError(RangeableError):
+    """Raised when an interval is malformed (start > end), or a transitions
+    query range is malformed (lo > hi, or lo is None). RFC §3.7 / §3.2 / §3.5.
+    """

rangeable-1.0.0/src/rangeable/_interval.py

@@ -0,0 +1,29 @@
+"""Closed integer interval [lo, hi]."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ._errors import InvalidIntervalError
+
+
+@dataclass(frozen=True, slots=True)
+class Interval:
+    """Immutable closed integer interval [lo, hi].
+
+    Both ends are inclusive, matching RFC §4.1. ``lo > hi`` raises
+    :class:`InvalidIntervalError` at construction time.
+    """
+
+    lo: int
+    hi: int
+
+    def __post_init__(self) -> None:
+        if self.lo > self.hi:
+            raise InvalidIntervalError(f"lo ({self.lo}) > hi ({self.hi})")
+
+    def __contains__(self, coord: int) -> bool:
+        return self.lo <= coord <= self.hi
+
+    def to_tuple(self) -> tuple[int, int]:
+        return (self.lo, self.hi)

rangeable-1.0.0/src/rangeable/_slot.py

@@ -0,0 +1,33 @@
+"""Active-element list returned by ``Rangeable[i]``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Generic, Iterator, TypeVar
+
+E = TypeVar("E")
+
+
+@dataclass(frozen=True, slots=True)
+class Slot(Generic[E]):
+    """Wraps the ordered tuple of elements active at a coordinate.
+
+    ``objs`` is sorted by first-insertion order ascending (RFC §4.5).
+    The same coordinate within an unmutated container always returns
+    an equal ``Slot``.
+    """
+
+    objs: tuple[E, ...]
+
+    def __len__(self) -> int:
+        return len(self.objs)
+
+    def __iter__(self) -> Iterator[E]:
+        return iter(self.objs)
+
+    def __bool__(self) -> bool:
+        return bool(self.objs)
+
+    @property
+    def empty(self) -> bool:
+        return not self.objs

rangeable-1.0.0/src/rangeable/_transition.py

@@ -0,0 +1,41 @@
+"""Transition events emitted by ``Rangeable.transitions``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Generic, TypeVar
+
+E = TypeVar("E")
+
+
+class TransitionKind(str, Enum):
+    """Kind of a boundary event. Inherits from ``str`` so cross-language
+    JSON fixtures can compare directly against ``"open"`` / ``"close"``.
+    """
+
+    OPEN = "open"
+    CLOSE = "close"
+
+
+@dataclass(frozen=True, slots=True)
+class TransitionEvent(Generic[E]):
+    """A single boundary event in coordinate-sorted order.
+
+    ``coordinate`` is normally an :class:`int`; it is ``None`` for close
+    events whose underlying interval ends at the implementation's +∞
+    sentinel (RFC §4.7 C4). Comparison treats ``None`` as greater than
+    any finite int.
+    """
+
+    coordinate: int | None
+    kind: TransitionKind
+    element: E
+
+    @property
+    def is_open(self) -> bool:
+        return self.kind == TransitionKind.OPEN
+
+    @property
+    def is_close(self) -> bool:
+        return self.kind == TransitionKind.CLOSE