intranges 0.2.0__py3-none-any.whl

intranges/__init__.py

@@ -0,0 +1,50 @@
+"""Typed two-way conversion between compact range strings and integers.
+
+``parse`` and ``compact`` convert between strings like ``"1-3,5,7-9"`` and lists of
+ints. ``IntRanges`` is a lazy, immutable set that never expands its ranges, and
+``parse_ranges``, ``count`` and ``normalize`` read strings into it. Named dialects cover
+printer page lists, Linux cpu lists, Slurm indexes and HTTP byte ranges.
+"""
+
+from __future__ import annotations
+
+from ._compact import compact
+from ._dialect import CPULIST, DEFAULT, DIALECTS, HTTP, PAGES, SLURM, Dialect
+from ._errors import (
+    DescendingRangeError,
+    RangeBoundsError,
+    RangeError,
+    RangeOrderError,
+    RangeOverlapError,
+    RangeSizeError,
+    RangeSyntaxError,
+)
+from ._intranges import IntRanges
+from ._parse import DEFAULT_MAX_SIZE, DEFAULT_MAX_SPANS, count, normalize, parse, parse_ranges
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "CPULIST",
+    "DEFAULT",
+    "DEFAULT_MAX_SIZE",
+    "DEFAULT_MAX_SPANS",
+    "DIALECTS",
+    "HTTP",
+    "PAGES",
+    "SLURM",
+    "DescendingRangeError",
+    "Dialect",
+    "IntRanges",
+    "RangeBoundsError",
+    "RangeError",
+    "RangeOrderError",
+    "RangeOverlapError",
+    "RangeSizeError",
+    "RangeSyntaxError",
+    "compact",
+    "count",
+    "normalize",
+    "parse",
+    "parse_ranges",
+]

intranges/_cli.py

@@ -0,0 +1,174 @@
+"""Command-line interface: ``intranges <command> ...``."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from collections.abc import Iterable, Sequence
+from itertools import islice
+from typing import NoReturn
+
+from . import __version__
+from ._compact import compact
+from ._dialect import DIALECTS, Dialect
+from ._errors import RangeBoundsError, RangeError, RangeSizeError
+from ._intranges import IntRanges
+from ._parse import DEFAULT_MAX_SIZE, parse, parse_ranges
+
+EXAMPLES = """\
+examples:
+  intranges expand "1-3,7"                        # 1 2 3 7, one per line
+  intranges expand "0-10:3" --dialect cpulist -d ,  # 0,3,6,9
+  seq 1 5 | intranges compress                    # 1-5
+  intranges compress 6 5 1 3 2                    # 1-3,5-6
+  intranges normalize "8, 1-3, 2, 4"              # 1-4,8
+  intranges count "0-10000000000"                 # 10000000001
+  intranges contains "0-3,8-11" 9 12              # 9 yes / 12 no, exit 2
+  intranges complement "0-3,8-11" --lower 0 --upper 15   # 4-7,12-15
+  intranges expand "900-" --dialect http --upper 999 -d ,
+  intranges expand -- "-3--1"                     # put -- before a text that starts with -
+
+exit codes: 0 success, 1 error (message on stderr), 2 a "contains" value is absent.
+"""
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        self.exit(1, f"{self.prog}: error: {message}\n")
+
+
+def _common(sub: argparse.ArgumentParser, text: bool = True) -> None:
+    if text:
+        sub.add_argument("text", help='range string, or "-" to read it from stdin')
+    sub.add_argument("--dialect", choices=sorted(DIALECTS), default="default")
+    sub.add_argument("--lower", type=int, help="smallest allowed value")
+    sub.add_argument("--upper", type=int, help='largest allowed value; end of "5-" and N')
+    sub.add_argument("--range-sep", help="override the range separator")
+    sub.add_argument("--list-sep", help="override the list separator")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Return the argument parser used by :func:`main`."""
+    parser = _Parser(
+        prog="intranges",
+        description="Expand, compress and query integer range strings like 1-3,5,7-9.",
+        epilog=EXAMPLES,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subs = parser.add_subparsers(dest="command", required=True, parser_class=_Parser)
+    sub = subs.add_parser("expand", help="print every value of a range string")
+    _common(sub)
+    sub.add_argument("-d", "--delimiter", default="\n", help="output separator (newline)")
+    sub.add_argument("--unique", action="store_true", help="sorted, without repeats")
+    sub.add_argument("--max-size", type=int, default=DEFAULT_MAX_SIZE, help="value cap; 0 lifts it")
+    sub = subs.add_parser("compress", help="turn integers into a canonical range string")
+    _common(sub, text=False)
+    sub.add_argument("values", nargs="*", help="integers; read from stdin when omitted")
+    sub.add_argument("--width", type=int, help="zero-pad numbers to this width")
+    sub = subs.add_parser("normalize", aliases=["normalise"], help="canonical form")
+    _common(sub)
+    sub.add_argument("--to", choices=sorted(DIALECTS), help="output dialect")
+    sub.add_argument("--width", type=int, help="zero-pad numbers to this width")
+    sub = subs.add_parser("count", help="number of distinct values")
+    _common(sub)
+    sub = subs.add_parser("contains", help="test membership; exit 2 if any is absent")
+    _common(sub)
+    sub.add_argument("values", nargs="+", type=int, help="integers to test")
+    sub = subs.add_parser("complement", help="values within --lower..--upper not listed")
+    _common(sub)
+    return parser
+
+
+def _dialect(args: argparse.Namespace) -> Dialect:
+    return DIALECTS[args.dialect].with_separators(args.range_sep, args.list_sep)
+
+
+def _text(args: argparse.Namespace) -> str:
+    return sys.stdin.read().strip() if args.text == "-" else str(args.text)
+
+
+def _ranges(args: argparse.Namespace) -> IntRanges:
+    return parse_ranges(_text(args), dialect=_dialect(args), lower=args.lower, upper=args.upper)
+
+
+def _emit(values: Iterable[int], delimiter: str) -> None:
+    """Stream values in chunks so a large expansion never builds one huge string."""
+    stream = iter(values)
+    lead = ""
+    while chunk := list(islice(stream, 4096)):
+        sys.stdout.write(lead + delimiter.join(map(str, chunk)))
+        lead = delimiter
+    sys.stdout.write("\n")
+
+
+def _run(args: argparse.Namespace) -> int:
+    out = sys.stdout
+    if args.command == "expand":
+        cap = args.max_size or None
+        if args.unique:
+            ranges = _ranges(args)
+            if cap is not None and ranges.count > cap:
+                raise RangeSizeError(f"expansion exceeds max_size={cap}")
+            values: Sequence[int] | IntRanges = ranges
+        else:
+            values = parse(
+                _text(args),
+                dialect=_dialect(args),
+                lower=args.lower,
+                upper=args.upper,
+                max_size=cap,
+            )
+        _emit(values, args.delimiter)
+    elif args.command == "compress":
+        raw = args.values or [t for t in re.split(r"[\s,]+", sys.stdin.read()) if t]
+        try:
+            ints = [int(token) for token in raw]
+        except ValueError as exc:
+            raise ValueError(f"not an integer: {exc}") from None
+        for value in ints:
+            if (args.lower is not None and value < args.lower) or (
+                args.upper is not None and value > args.upper
+            ):
+                raise RangeBoundsError(f"{value} is outside --lower/--upper")
+        out.write(compact(ints, dialect=_dialect(args), width=args.width) + "\n")
+    elif args.command in ("normalize", "normalise"):
+        target = DIALECTS[args.to] if args.to else _dialect(args)
+        out.write(_ranges(args).format(target, width=args.width) + "\n")
+    elif args.command == "count":
+        out.write(f"{_ranges(args).count}\n")
+    elif args.command == "contains":
+        ranges = _ranges(args)
+        found = [value in ranges for value in args.values]
+        for value, hit in zip(args.values, found, strict=True):
+            out.write(f"{value} {'yes' if hit else 'no'}\n")
+        return 0 if all(found) else 2
+    else:
+        if args.lower is None or args.upper is None:
+            raise ValueError("complement needs --lower and --upper")
+        complement = _ranges(args).complement(args.lower, args.upper)
+        out.write(complement.format(_dialect(args)) + "\n")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the CLI and return its exit code."""
+    args = build_parser().parse_args(argv)
+    try:
+        return _run(args)
+    except RangeError as exc:
+        print(f"intranges: error: {exc}", file=sys.stderr)
+        if exc.pointer():
+            print(exc.pointer(), file=sys.stderr)
+        return 1
+    except ValueError as exc:
+        print(f"intranges: error: {exc}", file=sys.stderr)
+        return 1
+    except BrokenPipeError:
+        return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

intranges/_compact.py

@@ -0,0 +1,72 @@
+"""Collapse integers into a canonical range string."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from . import _spans as sp
+from ._dialect import DEFAULT, Dialect
+from ._errors import RangeBoundsError
+
+
+def _number(value: int, width: int | None) -> str:
+    return str(value) if width is None else f"{value:0{width}d}"
+
+
+def format_spans(spans: sp.Spans, dialect: Dialect, width: int | None) -> str:
+    """Write canonical spans in ``dialect``; ``width`` zero-pads every number."""
+    if width is not None and width < 1:
+        raise ValueError(f"width must be at least 1, got {width}")
+    if spans:
+        low = spans[0][0]
+        if (low < 0 and not dialect.negatives) or (
+            dialect.minimum is not None and low < dialect.minimum
+        ):
+            raise RangeBoundsError(f"{low} cannot be written in the {dialect.name} dialect")
+    parts = []
+    for low, high in spans:
+        text = _number(low, width)
+        if high != low:
+            text += dialect.range_sep + _number(high, width)
+        parts.append(text)
+    body = dialect.list_sep.join(parts)
+    return dialect.prefix + body if body else ""
+
+
+def compact(
+    values: Iterable[int],
+    *,
+    range_sep: str | None = None,
+    list_sep: str | None = None,
+    dialect: Dialect = DEFAULT,
+    width: int | None = None,
+) -> str:
+    """Collapse integers into the canonical range string, such as ``"1-3,5-6"``.
+
+    The input is sorted and de-duplicated first, so unsorted or repeated values are
+    accepted. Runs of two or more consecutive values become ``low-high``. An empty input
+    yields an empty string. An :class:`IntRanges` or a step-1 ``range`` is written from
+    its spans without being expanded.
+
+    Args:
+        values: Integers in any order, an :class:`IntRanges` or a ``range``.
+        range_sep: Overrides ``dialect.range_sep``.
+        list_sep: Overrides ``dialect.list_sep``.
+        dialect: Output grammar. Its ``prefix`` (``"bytes="`` for ``HTTP``) is written.
+        width: Zero-pad every number to this many characters, as in Slurm hostlists
+            such as ``"001-010"``.
+
+    Raises:
+        RangeBoundsError: A value cannot be written in the dialect (negative where
+            negatives are off, or below the dialect minimum).
+        TypeError: A value is not an integer.
+
+    >>> compact([6, 5, 1, 3, 2])
+    '1-3,5-6'
+    >>> compact(range(1, 11), width=3)
+    '001-010'
+    """
+    from ._intranges import _spans_of
+
+    chosen = dialect.with_separators(range_sep, list_sep)
+    return format_spans(_spans_of(values), chosen, width)

intranges/_dialect.py

@@ -0,0 +1,108 @@
+"""Named range-string dialects and their documented sources."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+
+@dataclass(frozen=True)
+class Dialect:
+    """The grammar used to read and write a range string.
+
+    Attributes:
+        name: Short label used in messages and by the CLI.
+        range_sep: Separator between the two bounds of a range, ``"-"`` in ``"1-3"``.
+        list_sep: Separator between tokens, ``","`` in ``"1-3,5"``.
+        negatives: Accept a leading ``-`` on a bound as a sign.
+        stride: Separator introducing a step, ``":"`` in ``"0-10:2"``, or ``None``.
+        groups: Also accept the Linux kernel ``"a-b:used/group"`` form after ``stride``.
+        open_end: Accept ``"5-"`` meaning "5 to ``upper``" (``upper`` must be given).
+        suffix: Accept ``"-5"`` meaning "the last 5 values up to ``upper``" (HTTP style).
+            Requires ``negatives=False`` so the leading ``-`` is unambiguous.
+        clamp: Clip range ends above ``upper`` down to ``upper`` instead of raising.
+        brackets: Accept the whole list wrapped in ``[...]`` (Slurm hostlist style).
+        prefix: Optional leading unit such as ``"bytes="``; written back by ``compact``.
+        last_alias: Token standing for ``upper``, such as the kernel's ``"N"``.
+        all_alias: Token standing for ``lower..upper``, such as the kernel's ``"all"``.
+        minimum: Smallest value the dialect allows, or ``None`` for no floor.
+    """
+
+    name: str = "default"
+    range_sep: str = "-"
+    list_sep: str = ","
+    negatives: bool = True
+    stride: str | None = None
+    groups: bool = False
+    open_end: bool = True
+    suffix: bool = False
+    clamp: bool = False
+    brackets: bool = False
+    prefix: str = ""
+    last_alias: str | None = None
+    all_alias: str | None = None
+    minimum: int | None = None
+
+    def __post_init__(self) -> None:
+        if not self.range_sep:
+            raise ValueError("range_sep must not be empty")
+        if not self.list_sep:
+            raise ValueError("list_sep must not be empty")
+        seps = [self.range_sep, self.list_sep] + ([self.stride] if self.stride else [])
+        if len(set(seps)) != len(seps):
+            raise ValueError(f"separators must be distinct, got {seps!r}")
+        for sep in seps:
+            if any(ch.isdigit() for ch in sep):
+                raise ValueError(f"separator {sep!r} must not contain digits")
+        if self.stride == "":
+            raise ValueError("stride must be None or a non-empty string")
+        if self.groups and self.stride is None:
+            raise ValueError("groups=True needs a stride separator")
+        if self.suffix and self.negatives:
+            raise ValueError("suffix ranges need negatives=False to stay unambiguous")
+        for alias in (self.last_alias, self.all_alias):
+            if alias is not None and (not alias.isalpha()):
+                raise ValueError(f"alias {alias!r} must be alphabetic")
+
+    def with_separators(self, range_sep: str | None, list_sep: str | None) -> Dialect:
+        """Return a copy with the given separators replaced (``None`` keeps the current)."""
+        return replace(
+            self,
+            range_sep=self.range_sep if range_sep is None else range_sep,
+            list_sep=self.list_sep if list_sep is None else list_sep,
+        )
+
+
+DEFAULT = Dialect()
+"""Signed integers, ``-`` ranges, ``,`` lists, open ends when ``upper`` is given."""
+
+PAGES = Dialect(name="pages", negatives=False, open_end=False, minimum=1)
+"""Printer page lists such as CUPS ``-o page-ranges=1-4,7,9-12``. Pages start at 1."""
+
+CPULIST = Dialect(
+    name="cpulist",
+    negatives=False,
+    stride=":",
+    groups=True,
+    open_end=False,
+    last_alias="N",
+    all_alias="all",
+    minimum=0,
+)
+"""Linux cpu lists: ``0-3,8-11``, kernel ``100-2000:2/25``, taskset ``0-10:3``, ``16-N``."""
+
+SLURM = Dialect(name="slurm", negatives=False, stride=":", open_end=False, brackets=True, minimum=0)
+"""Slurm ``--array`` indexes such as ``0-15:4`` and hostlist numbers such as ``[1-3,5]``."""
+
+HTTP = Dialect(
+    name="http",
+    negatives=False,
+    open_end=True,
+    suffix=True,
+    clamp=True,
+    prefix="bytes=",
+    minimum=0,
+)
+"""RFC 9110 byte ranges: ``bytes=0-499,500-``, suffix ``-500``. ``upper`` is length - 1."""
+
+DIALECTS: dict[str, Dialect] = {d.name: d for d in (DEFAULT, PAGES, CPULIST, SLURM, HTTP)}
+"""Built-in dialects by name."""

intranges/_errors.py

@@ -0,0 +1,67 @@
+"""Error types raised by intranges.
+
+Every error is a :class:`RangeError`, which is itself a :class:`ValueError`, so existing
+``except ValueError`` handlers keep working. Errors raised while reading a string carry
+the full ``text``, the offending ``token`` and its character ``offset`` in ``text``.
+"""
+
+from __future__ import annotations
+
+
+class RangeError(ValueError):
+    """Raised when a range string or a set of integers cannot be handled.
+
+    Attributes:
+        text: The full input string, when the error came from parsing.
+        token: The offending token, stripped of surrounding whitespace.
+        offset: Zero-based index of ``token`` inside ``text``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        text: str | None = None,
+        token: str | None = None,
+        offset: int | None = None,
+    ) -> None:
+        if offset is not None:
+            message = f"{message} at offset {offset}"
+        super().__init__(message)
+        self.text = text
+        self.token = token
+        self.offset = offset
+
+    def pointer(self) -> str:
+        """Return ``text`` with a caret line under the offending token.
+
+        Returns an empty string when the error does not point into a string.
+        """
+        if self.text is None or self.offset is None:
+            return ""
+        width = max(1, len(self.token or ""))
+        return f"{self.text}\n{' ' * self.offset}{'^' * width}"
+
+
+class RangeSyntaxError(RangeError):
+    """A token does not match the grammar of the active dialect."""
+
+
+class DescendingRangeError(RangeError):
+    """A range runs from high to low, such as ``"5-1"``."""
+
+
+class RangeOverlapError(RangeError):
+    """A token overlaps or repeats an earlier one while ``on_overlap="reject"``."""
+
+
+class RangeOrderError(RangeError):
+    """A token starts below an earlier one while ``on_unsorted="reject"``."""
+
+
+class RangeBoundsError(RangeError):
+    """A value falls outside ``lower``/``upper`` or the dialect minimum."""
+
+
+class RangeSizeError(RangeError):
+    """Expanding the input would exceed ``max_size`` values or ``max_spans`` spans."""

intranges/_intranges.py

@@ -0,0 +1,199 @@
+"""A lazy, immutable set of integers stored as spans."""
+
+from __future__ import annotations
+
+from bisect import bisect_right
+from collections.abc import Iterable, Iterator, Set
+from operator import index
+from typing import Any
+
+from . import _spans as sp
+from ._dialect import DEFAULT, Dialect
+
+
+class IntRanges(Set[int]):
+    """An immutable set of integers that never expands its ranges.
+
+    Values are kept as sorted, disjoint, inclusive spans, so ``IntRanges(range(10**12))``
+    holds two integers. Membership is a binary search, :attr:`count` is arithmetic and
+    iteration streams values in ascending order. Set operators (``|``, ``&``, ``-``,
+    ``^``, ``<=``, ``<``, ``>=``, ``>``) work span by span when both sides are
+    ``IntRanges``; any other iterable of ints is converted first. ``==`` and ``hash``
+    compare ``IntRanges`` with ``IntRanges`` only, so the hash contract holds. ``in``
+    accepts any ``__index__`` integer. ``len()`` stops at ``sys.maxsize``; use ``count``.
+
+    >>> r = IntRanges.parse("1-3,10-12")
+    >>> 11 in r, r.count, str(r | IntRanges([4]))
+    (True, 6, '1-4,10-12')
+    """
+
+    __slots__ = ("_spans",)
+    _spans: sp.Spans
+
+    def __init__(self, values: Iterable[int] = ()) -> None:
+        """Build from any iterable of ints; a ``range`` with step 1 is not expanded."""
+        if isinstance(values, IntRanges):
+            self._spans = values._spans
+        else:
+            self._spans = sp.from_ints(values)
+
+    @classmethod
+    def from_spans(cls, spans: Iterable[tuple[int, int]]) -> IntRanges:
+        """Build from inclusive ``(low, high)`` pairs in any order, overlapping or not.
+
+        Raises :class:`ValueError` when a pair has ``low > high`` and :class:`TypeError`
+        when a bound is not an integer.
+        """
+        pairs = [(index(low), index(high)) for low, high in spans]
+        for low, high in pairs:
+            if low > high:
+                raise ValueError(f"span ({low}, {high}) has low greater than high")
+        return cls._wrap(sp.coalesce(pairs))
+
+    @classmethod
+    def parse(cls, text: str, **options: Any) -> IntRanges:
+        """Read a range string; keyword options are those of :func:`parse_ranges`."""
+        from ._parse import parse_ranges
+
+        return parse_ranges(text, **options)
+
+    @classmethod
+    def _wrap(cls, spans: sp.Spans) -> IntRanges:
+        obj = cls.__new__(cls)
+        obj._spans = spans
+        return obj
+
+    @property
+    def spans(self) -> tuple[tuple[int, int], ...]:
+        """The canonical inclusive ``(low, high)`` spans, ascending and non-adjacent."""
+        return self._spans
+
+    @property
+    def count(self) -> int:
+        """Number of values, as an unbounded int."""
+        return sp.count(self._spans)
+
+    @property
+    def first(self) -> int:
+        """Smallest value. Raises :class:`ValueError` when empty."""
+        if not self._spans:
+            raise ValueError("first of an empty IntRanges")
+        return self._spans[0][0]
+
+    @property
+    def last(self) -> int:
+        """Largest value. Raises :class:`ValueError` when empty."""
+        if not self._spans:
+            raise ValueError("last of an empty IntRanges")
+        return self._spans[-1][1]
+
+    def __contains__(self, value: object) -> bool:
+        try:
+            value = index(value)  # type: ignore[arg-type]
+        except TypeError:
+            return False
+        i = bisect_right(self._spans, value, key=lambda span: span[0]) - 1
+        return i >= 0 and value <= self._spans[i][1]
+
+    def __iter__(self) -> Iterator[int]:
+        for low, high in self._spans:
+            yield from range(low, high + 1)
+
+    def __reversed__(self) -> Iterator[int]:
+        for low, high in reversed(self._spans):
+            yield from range(high, low - 1, -1)
+
+    def __len__(self) -> int:
+        return self.count
+
+    def __bool__(self) -> bool:
+        return bool(self._spans)
+
+    def __hash__(self) -> int:
+        return hash((IntRanges, self._spans))
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, IntRanges):
+            return self._spans == other._spans
+        return NotImplemented
+
+    def __repr__(self) -> str:
+        return f"IntRanges({self.format()!r})"
+
+    def __str__(self) -> str:
+        return self.format()
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (type(self).from_spans, (self._spans,))
+
+    def format(self, dialect: Dialect = DEFAULT, *, width: int | None = None) -> str:
+        """Write the canonical range string; see :func:`compact` for the options."""
+        from ._compact import format_spans
+
+        return format_spans(self._spans, dialect, width)
+
+    def complement(self, lower: int, upper: int) -> IntRanges:
+        """Values in ``lower..upper`` (inclusive) that are not in this set."""
+        return self._wrap(sp.complement(self._spans, lower, upper))
+
+    def union(self, *others: Iterable[int]) -> IntRanges:
+        spans = self._spans
+        for other in others:
+            spans = sp.union(spans, _spans_of(other))
+        return self._wrap(spans)
+
+    def intersection(self, *others: Iterable[int]) -> IntRanges:
+        spans = self._spans
+        for other in others:
+            spans = sp.intersection(spans, _spans_of(other))
+        return self._wrap(spans)
+
+    def difference(self, *others: Iterable[int]) -> IntRanges:
+        spans = self._spans
+        for other in others:
+            spans = sp.difference(spans, _spans_of(other))
+        return self._wrap(spans)
+
+    def symmetric_difference(self, other: Iterable[int]) -> IntRanges:
+        theirs = _spans_of(other)
+        mine = self._spans
+        return self._wrap(sp.union(sp.difference(mine, theirs), sp.difference(theirs, mine)))
+
+    def issubset(self, other: Iterable[int]) -> bool:
+        return sp.is_subset(self._spans, _spans_of(other))
+
+    def issuperset(self, other: Iterable[int]) -> bool:
+        return sp.is_subset(_spans_of(other), self._spans)
+
+    def isdisjoint(self, other: Iterable[int]) -> bool:
+        return not sp.intersection(self._spans, _spans_of(other))
+
+    __or__ = __ror__ = union  # type: ignore[assignment]
+    __and__ = __rand__ = intersection
+    __xor__ = __rxor__ = symmetric_difference  # type: ignore[assignment]
+    __sub__ = difference
+
+    def __rsub__(self, other: Iterable[int]) -> IntRanges:
+        return self._wrap(sp.difference(_spans_of(other), self._spans))
+
+    def __le__(self, other: Any) -> bool:
+        return self.issubset(other) if isinstance(other, Set) else NotImplemented
+
+    def __ge__(self, other: Any) -> bool:
+        return self.issuperset(other) if isinstance(other, Set) else NotImplemented
+
+    def __lt__(self, other: Any) -> bool:
+        if not isinstance(other, Set):
+            return NotImplemented
+        theirs = _spans_of(other)
+        return sp.is_subset(self._spans, theirs) and sp.count(self._spans) < sp.count(theirs)
+
+    def __gt__(self, other: Any) -> bool:
+        if not isinstance(other, Set):
+            return NotImplemented
+        theirs = _spans_of(other)
+        return sp.is_subset(theirs, self._spans) and sp.count(theirs) < sp.count(self._spans)
+
+
+def _spans_of(values: Iterable[int]) -> sp.Spans:
+    return values._spans if isinstance(values, IntRanges) else sp.from_ints(values)

intranges/_parse.py

@@ -0,0 +1,189 @@
+"""Read range strings into lists, lazy sets, counts and canonical strings."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from . import _spans as sp
+from ._dialect import DEFAULT, Dialect
+from ._errors import RangeError, RangeOrderError, RangeOverlapError, RangeSizeError
+from ._intranges import IntRanges
+from ._tokens import Piece, scan
+
+DEFAULT_MAX_SIZE = 10_000_000
+"""Default cap on the number of values :func:`parse` will put in a list."""
+
+DEFAULT_MAX_SPANS = 1_000_000
+"""Default cap on the number of separate spans a strided input may create."""
+
+OverlapPolicy = Literal["merge", "reject"]
+OrderPolicy = Literal["allow", "reject"]
+
+
+def _fail(kind: type[RangeError], message: str, text: str, piece: Piece) -> RangeError:
+    return kind(message, text=text, token=piece.token, offset=piece.offset)
+
+
+def parse(
+    text: str,
+    *,
+    range_sep: str | None = None,
+    list_sep: str | None = None,
+    dialect: Dialect = DEFAULT,
+    lower: int | None = None,
+    upper: int | None = None,
+    max_size: int | None = DEFAULT_MAX_SIZE,
+) -> list[int]:
+    """Expand a range string such as ``"1-5,8,10-12"`` into a list of ints.
+
+    Values come out in input order and repeats are kept, so ``parse("3,1-2,2")`` is
+    ``[3, 1, 2, 2]``. Use :func:`parse_ranges` for set semantics without expansion.
+    Whitespace around tokens and separators is ignored. An empty string gives ``[]``.
+
+    Args:
+        text: The range string.
+        range_sep: Overrides ``dialect.range_sep`` (default ``"-"``).
+        list_sep: Overrides ``dialect.list_sep`` (default ``","``).
+        dialect: Grammar to read, such as ``CPULIST`` or ``HTTP``.
+        lower: Smallest allowed value; also the start of an ``all`` alias.
+        upper: Largest allowed value; also the end of ``"5-"``, ``"-5"`` and ``N``.
+        max_size: Refuse to build more values than this (checked before allocating);
+            ``None`` lifts the cap.
+
+    Raises:
+        RangeSyntaxError: A token does not match the dialect grammar.
+        DescendingRangeError: A range runs high to low, such as ``"5-1"``.
+        RangeBoundsError: A value is outside ``lower``/``upper`` or the dialect minimum.
+        RangeSizeError: The expansion would exceed ``max_size``.
+        ValueError: The separators are empty or clash, or ``lower > upper``.
+
+    >>> parse("1-3,7")
+    [1, 2, 3, 7]
+    >>> parse("0-10:3", dialect=CPULIST)
+    [0, 3, 6, 9]
+    """
+    chosen = dialect.with_separators(range_sep, list_sep)
+    pieces = scan(text, chosen, lower, upper)
+    total = 0
+    for piece in pieces:
+        total += piece.size()
+        if max_size is not None and total > max_size:
+            raise _fail(RangeSizeError, f"expansion exceeds max_size={max_size}", text, piece)
+    result: list[int] = []
+    for piece in pieces:
+        for low, high in piece.spans():
+            result.extend(range(low, high + 1))
+    return result
+
+
+def parse_ranges(
+    text: str,
+    *,
+    range_sep: str | None = None,
+    list_sep: str | None = None,
+    dialect: Dialect = DEFAULT,
+    lower: int | None = None,
+    upper: int | None = None,
+    on_overlap: OverlapPolicy = "merge",
+    on_unsorted: OrderPolicy = "allow",
+    max_spans: int | None = DEFAULT_MAX_SPANS,
+) -> IntRanges:
+    """Read a range string into a lazy :class:`IntRanges` without expanding it.
+
+    ``parse_ranges("0-10000000000")`` costs two integers. Overlapping, repeated and
+    unsorted tokens are merged by default.
+
+    Args:
+        on_overlap: ``"merge"`` unions overlapping or repeated tokens; ``"reject"``
+            raises :class:`RangeOverlapError` naming the later of the two tokens.
+        on_unsorted: ``"allow"`` accepts tokens in any order; ``"reject"`` raises
+            :class:`RangeOrderError` when a token starts below the previous token.
+        max_spans: Cap on separate spans created by strides such as ``"0-10:2"``;
+            ``None`` lifts it.
+        Other options are those of :func:`parse`.
+
+    >>> parse_ranges("5,1-3,2").spans
+    ((1, 3), (5, 5))
+    """
+    if on_overlap not in ("merge", "reject"):
+        raise ValueError(f"on_overlap must be 'merge' or 'reject', got {on_overlap!r}")
+    if on_unsorted not in ("allow", "reject"):
+        raise ValueError(f"on_unsorted must be 'allow' or 'reject', got {on_unsorted!r}")
+    chosen = dialect.with_separators(range_sep, list_sep)
+    pieces = scan(text, chosen, lower, upper)
+    total = 0
+    for index, piece in enumerate(pieces):
+        total += piece.span_count()
+        if max_spans is not None and total > max_spans:
+            raise _fail(RangeSizeError, f"input exceeds max_spans={max_spans}", text, piece)
+        if on_unsorted == "reject" and index and piece.start < pieces[index - 1].start:
+            raise _fail(RangeOrderError, "token starts below the previous token", text, piece)
+    tagged = sorted(
+        (low, high, index) for index, piece in enumerate(pieces) for low, high in piece.spans()
+    )
+    if on_overlap == "reject":
+        _reject_overlaps(tagged, pieces, text)
+    return IntRanges._wrap(sp.coalesce((low, high) for low, high, _ in tagged))
+
+
+def _reject_overlaps(tagged: list[tuple[int, int, int]], pieces: list[Piece], text: str) -> None:
+    reach, owner = None, -1
+    for low, high, index in tagged:
+        if reach is not None and low <= reach:
+            later = pieces[max(index, owner)]
+            raise _fail(RangeOverlapError, "token overlaps an earlier token", text, later)
+        if reach is None or high > reach:
+            reach, owner = high, index
+
+
+def count(
+    text: str,
+    *,
+    range_sep: str | None = None,
+    list_sep: str | None = None,
+    dialect: Dialect = DEFAULT,
+    lower: int | None = None,
+    upper: int | None = None,
+    max_spans: int | None = DEFAULT_MAX_SPANS,
+) -> int:
+    """Number of distinct values in a range string, computed without expanding it.
+
+    Options are those of :func:`parse_ranges`.
+
+    >>> count("1-1000000,500000-2000000")
+    2000000
+    """
+    return parse_ranges(
+        text,
+        range_sep=range_sep,
+        list_sep=list_sep,
+        dialect=dialect,
+        lower=lower,
+        upper=upper,
+        max_spans=max_spans,
+    ).count
+
+
+def normalize(
+    text: str,
+    *,
+    range_sep: str | None = None,
+    list_sep: str | None = None,
+    dialect: Dialect = DEFAULT,
+    lower: int | None = None,
+    upper: int | None = None,
+    output: Dialect | None = None,
+    width: int | None = None,
+) -> str:
+    """Rewrite a range string in canonical form: sorted, merged, minimal.
+
+    ``output`` picks the dialect to write (default: the input dialect with the given
+    separators) and ``width`` zero-pads numbers. Other options are those of
+    :func:`parse_ranges`.
+
+    >>> normalize("8, 1-3, 2, 4")
+    '1-4,8'
+    """
+    chosen = dialect.with_separators(range_sep, list_sep)
+    ranges = parse_ranges(text, dialect=chosen, lower=lower, upper=upper)
+    return ranges.format(output if output is not None else chosen, width=width)

intranges/_spans.py

@@ -0,0 +1,81 @@
+"""Algebra on canonical spans: sorted, disjoint, non-adjacent, inclusive ``(low, high)``."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from operator import index
+
+Span = tuple[int, int]
+Spans = tuple[Span, ...]
+
+
+def coalesce(spans: Iterable[Span]) -> Spans:
+    """Sort spans and merge every overlapping or adjacent pair."""
+    out: list[Span] = []
+    for low, high in sorted(spans):
+        if out and low <= out[-1][1] + 1:
+            if high > out[-1][1]:
+                out[-1] = (out[-1][0], high)
+        else:
+            out.append((low, high))
+    return tuple(out)
+
+
+def from_ints(values: Iterable[int]) -> Spans:
+    """Build canonical spans from integers, in any order, with repeats.
+
+    Raises :class:`TypeError` for a value that is not an integer.
+    """
+    if isinstance(values, range) and values.step == 1:
+        return ((values.start, values.stop - 1),) if values.start < values.stop else ()
+    return coalesce((value, value) for value in map(index, values))
+
+
+def union(a: Spans, b: Spans) -> Spans:
+    return coalesce(a + b)
+
+
+def intersection(a: Spans, b: Spans) -> Spans:
+    out: list[Span] = []
+    i = j = 0
+    while i < len(a) and j < len(b):
+        low = max(a[i][0], b[j][0])
+        high = min(a[i][1], b[j][1])
+        if low <= high:
+            out.append((low, high))
+        if a[i][1] < b[j][1]:
+            i += 1
+        else:
+            j += 1
+    return tuple(out)
+
+
+def difference(a: Spans, b: Spans) -> Spans:
+    out: list[Span] = []
+    j = 0
+    for low, high in a:
+        while j < len(b) and b[j][1] < low:
+            j += 1
+        k = j
+        while k < len(b) and b[k][0] <= high:
+            if b[k][0] > low:
+                out.append((low, b[k][0] - 1))
+            low = max(low, b[k][1] + 1)
+            k += 1
+        if low <= high:
+            out.append((low, high))
+    return tuple(out)
+
+
+def complement(a: Spans, lower: int, upper: int) -> Spans:
+    if lower > upper:
+        raise ValueError(f"lower {lower} is greater than upper {upper}")
+    return difference(((lower, upper),), a)
+
+
+def is_subset(a: Spans, b: Spans) -> bool:
+    return not difference(a, b)
+
+
+def count(a: Spans) -> int:
+    return sum(high - low + 1 for low, high in a)

intranges/_tokens.py

@@ -0,0 +1,180 @@
+"""Split a range string into validated pieces, one per token, without expanding them."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Iterator
+from functools import cache
+from typing import NamedTuple, NoReturn
+
+from ._dialect import Dialect
+from ._errors import DescendingRangeError, RangeBoundsError, RangeError, RangeSyntaxError
+
+
+class Piece(NamedTuple):
+    """One token: groups of ``used`` values every ``step`` from ``start`` up to ``end``."""
+
+    token: str
+    offset: int
+    start: int
+    end: int
+    step: int = 1
+    used: int = 1
+
+    def size(self) -> int:
+        if self.step == 1:
+            return self.end - self.start + 1
+        full, rest = divmod(self.end - self.start + 1, self.step)
+        return full * self.used + min(rest, self.used)
+
+    def span_count(self) -> int:
+        return 1 if self.step == 1 else (self.end - self.start) // self.step + 1
+
+    def last(self) -> int:
+        if self.step == 1:
+            return self.end
+        first_of_last = self.start + (self.end - self.start) // self.step * self.step
+        return min(first_of_last + self.used - 1, self.end)
+
+    def spans(self) -> Iterator[tuple[int, int]]:
+        if self.step == 1:
+            yield (self.start, self.end)
+            return
+        for low in range(self.start, self.end + 1, self.step):
+            yield (low, min(low + self.used - 1, self.end))
+
+
+@cache
+def _pattern(dialect: Dialect) -> re.Pattern[str]:
+    num = r"-?\d+" if dialect.negatives else r"\d+"
+    if dialect.last_alias:
+        num = rf"(?:{num}|{re.escape(dialect.last_alias)})"
+    stride = ""
+    if dialect.stride:
+        stride = rf"(?:\s*{re.escape(dialect.stride)}\s*(?P<step>\d+)(?:\s*/\s*(?P<grp>\d+))?)?"
+    sep = re.escape(dialect.range_sep)
+    return re.compile(rf"(?P<lo>{num})?(?:\s*(?P<sep>{sep})\s*(?P<hi>{num})?)?{stride}")
+
+
+def _strip_frame(text: str, dialect: Dialect) -> tuple[str, int]:
+    """Drop an optional unit prefix and enclosing brackets, returning body and offset."""
+    body, base = text, 0
+    lead = len(body) - len(body.lstrip())
+    if dialect.prefix and body[lead:].lower().startswith(dialect.prefix.lower()):
+        base = lead + len(dialect.prefix)
+        body = text[base:]
+    if dialect.brackets:
+        inner = body.strip()
+        if inner.startswith("[") and inner.endswith("]"):
+            base += body.index("[") + 1
+            body = inner[1:-1]
+    return body, base
+
+
+def _chunks(body: str, base: int, sep: str) -> Iterator[tuple[str, int]]:
+    pos = 0
+    while True:
+        cut = body.find(sep, pos)
+        chunk = body[pos:] if cut < 0 else body[pos:cut]
+        yield chunk.strip(), base + pos + len(chunk) - len(chunk.lstrip())
+        if cut < 0:
+            return
+        pos = cut + len(sep)
+
+
+def scan(text: str, dialect: Dialect, lower: int | None, upper: int | None) -> list[Piece]:
+    """Return one validated :class:`Piece` per token of ``text``, in input order."""
+    if lower is not None and upper is not None and lower > upper:
+        raise ValueError(f"lower {lower} is greater than upper {upper}")
+    body, base = _strip_frame(text, dialect)
+    if not body.strip():
+        return []
+    return [
+        _read(token, offset, text, dialect, lower, upper)
+        for token, offset in _chunks(body, base, dialect.list_sep)
+    ]
+
+
+Fail = Callable[[type[RangeError], str], NoReturn]
+
+
+def _read(
+    token: str, offset: int, text: str, d: Dialect, lower: int | None, upper: int | None
+) -> Piece:
+    def fail(kind: type[RangeError], message: str) -> NoReturn:
+        raise kind(message, text=text, token=token, offset=offset)
+
+    if not token:
+        fail(RangeSyntaxError, "empty range token")
+    floor = _floor(lower, d.minimum)
+    if d.all_alias and token.lower() == d.all_alias.lower():
+        if floor is None or upper is None:
+            fail(RangeBoundsError, f"{token!r} needs lower and upper bounds")
+        if floor > upper:
+            fail(RangeBoundsError, f"{token!r} is empty: lower {floor} exceeds upper {upper}")
+        return Piece(token, offset, floor, upper)
+    match = _pattern(d).fullmatch(token)
+    if match is None or (match["lo"] is None and match["sep"] is None):
+        fail(RangeSyntaxError, f"invalid range token {token!r} for the {d.name} dialect")
+
+    def value(raw: str) -> int:
+        if raw == d.last_alias:
+            if upper is None:
+                fail(RangeBoundsError, f"{raw!r} needs an upper bound")
+            return upper
+        return int(raw)
+
+    lo, hi = match["lo"], match["hi"]
+    step = int(match["step"]) if d.stride and match["step"] else None
+    if match["sep"] is None:
+        if step is not None:
+            fail(RangeSyntaxError, f"a stride needs a range in {token!r}")
+        start = end = value(lo)
+    elif lo is None:
+        if not d.suffix or upper is None:
+            hint = "needs an upper bound" if d.suffix else "is not allowed"
+            fail(RangeSyntaxError, f"suffix range {token!r} {hint}")
+        if hi is None or not hi.isdigit() or int(hi) == 0:
+            fail(RangeSyntaxError, f"suffix range {token!r} needs a positive length")
+        start, end = upper - int(hi) + 1, upper
+        if d.clamp and d.minimum is not None:
+            start = max(start, d.minimum)
+        if start > end:
+            fail(RangeBoundsError, f"suffix range {token!r} is unsatisfiable")
+    elif hi is None:
+        if not d.open_end:
+            fail(RangeSyntaxError, f"open-ended range {token!r} is not allowed")
+        if upper is None:
+            fail(RangeBoundsError, f"open-ended range {token!r} needs an upper bound")
+        start, end = value(lo), upper
+        if start > end:
+            fail(RangeBoundsError, f"{start} is above the upper bound {upper}")
+    else:
+        start, end = value(lo), value(hi)
+    if end < start:
+        fail(DescendingRangeError, f"descending range {token!r}")
+    if d.clamp and upper is not None and start <= upper < end:
+        end = upper
+    piece = Piece(token, offset, start, end, *_stride(step, match.groupdict().get("grp"), d, fail))
+    if floor is not None and piece.start < floor:
+        fail(RangeBoundsError, f"{piece.start} is below the lower bound {floor}")
+    if upper is not None and piece.last() > upper:
+        fail(RangeBoundsError, f"{piece.last()} is above the upper bound {upper}")
+    return piece
+
+
+def _floor(lower: int | None, minimum: int | None) -> int | None:
+    if lower is None or minimum is None:
+        return minimum if lower is None else lower
+    return max(lower, minimum)
+
+
+def _stride(step: int | None, grp: str | None, d: Dialect, fail: Fail) -> tuple[int, int]:
+    if step is None:
+        return 1, 1
+    if grp is not None and not d.groups:
+        fail(RangeSyntaxError, "used/group strides are not allowed")
+    used, size = (1, step) if grp is None else (step, int(grp))
+    if size == 0 or used == 0 or used > size:
+        fail(RangeSyntaxError, "stride must satisfy 0 < used <= group")
+    return (1, 1) if used == size else (size, used)

intranges-0.2.0.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.5
+Name: intranges
+Version: 0.2.0
+Summary: Typed conversion between range strings like 1-3,5 and ints, with a lazy set type, dialects and a CLI
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/intranges
+Project-URL: Issues, https://github.com/JaviLianes8/intranges/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/intranges/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,compact,cpulist,integers,intervals,page-ranges,parse,range-string,ranges
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# intranges
+
+Typed, zero-dependency conversion between range strings like `1-3,5,7-9` and integers,
+with a lazy set type that never expands huge ranges, named dialects for real-world
+syntaxes, typed errors that point at the bad token, and a command-line tool.
+
+## Install
+
+```
+pip install intranges
+```
+
+## Usage
+
+```python
+from intranges import compact, parse
+
+parse("1-5,8,10-12")
+# [1, 2, 3, 4, 5, 8, 10, 11, 12]
+
+compact([6, 5, 1, 1, 3, 2])
+# "1-3,5-6"
+
+parse("-3--1, 0, 2")
+# [-3, -2, -1, 0, 2]
+
+parse("1..3;6", range_sep="..", list_sep=";")
+# [1, 2, 3, 6]
+```
+
+`parse` keeps input order and repeats. It refuses to build more than 10,000,000 values
+by default (`max_size=`), and it checks that before allocating anything.
+
+### A set that never expands
+
+```python
+from intranges import IntRanges, parse_ranges, count, normalize
+
+r = parse_ranges("0-10000000000,5")  # two spans, not ten billion ints
+r.count  # 10000000001
+7_000_000_000 in r  # True, binary search
+r.spans  # ((0, 10000000000),)
+
+free = IntRanges.parse("0-3,8-11").complement(0, 15)
+str(free)  # "4-7,12-15"
+
+a, b = IntRanges.parse("1-10"), IntRanges.parse("5-15")
+str(a & b), str(a - b), str(a ^ b)  # ("5-10", "1-4", "1-4,11-15")
+
+count("1-1000000,500000-2000000")  # 2000000
+normalize("8, 1-3, 2, 4")  # "1-4,8"
+```
+
+`IntRanges` is an immutable `collections.abc.Set[int]`: `in`, iteration (ascending and
+`reversed`), `len`, `|`, `&`, `-`, `^`, subset tests, `first`, `last`, `complement`,
+hashing and pickling all work on spans.
+
+### Dialects
+
+| Dialect   | Example                        | Source |
+|-----------|--------------------------------|--------|
+| `DEFAULT` | `-3--1,5,9-` (with `upper=`)   | this library |
+| `PAGES`   | `1-4,7,9-12`                   | CUPS `-o page-ranges=1-4,7,9-12`, [Command-Line Printing and Options](https://www.cups.org/doc/options.html) |
+| `CPULIST` | `0-3,8-11`, `100-2000:2/25`, `16-N`, `all` | Linux kernel, [kernel-parameters: CPU lists](https://docs.kernel.org/admin-guide/kernel-parameters.html) |
+| `CPULIST` | `0-10:3` (stride)              | util-linux [taskset(1)](https://man7.org/linux/man-pages/man1/taskset.1.html): "0-10:3 is interpreted as 0,3,6,9" |
+| `SLURM`   | `0-15:4`, `[1-3,5]`, `001-010` | [sbatch `--array`](https://slurm.schedmd.com/sbatch.html), hostlist numbers as in `tux[1-3]` from [scontrol](https://slurm.schedmd.com/scontrol.html) |
+| `HTTP`    | `bytes=0-499,9500-`, `-500`    | [RFC 9110 section 14.1.2, Byte Ranges](https://www.rfc-editor.org/rfc/rfc9110#section-14.1.2) |
+
+```python
+from intranges import CPULIST, HTTP, SLURM, parse, parse_ranges, compact
+
+parse("100-200:2/25", dialect=CPULIST)  # [100, 101, 125, 126, 150, 151, 175, 176, 200]
+parse("16-N", dialect=CPULIST, upper=19)  # [16, 17, 18, 19]
+parse("0-15:4", dialect=SLURM)  # [0, 4, 8, 12]
+parse_ranges("bytes=-500", dialect=HTTP, upper=9999).spans  # ((9500, 9999),)
+compact(range(1, 11), dialect=SLURM, width=3)  # "001-010"
+```
+
+Open ends such as `"5-"` are accepted only when you pass `upper=`. Unsupported parts of
+a source syntax are rejected rather than guessed, for example Slurm's `%` throttle
+suffix. The HTTP dialect clamps ends past `upper` as RFC 9110 describes; `upper` is the
+representation length minus one.
+
+### Errors
+
+Every error is a `RangeError`, a `ValueError` subclass, carrying `text`, `token` and
+`offset`:
+
+```python
+from intranges import RangeError, parse
+
+try:
+    parse("1-3, 5, x-9")
+except RangeError as err:
+    print(err)
+    print(err.pointer())
+```
+
+prints
+
+```text
+invalid range token 'x-9' for the default dialect at offset 8
+1-3, 5, x-9
+        ^^^
+```
+
+Subclasses: `RangeSyntaxError`, `DescendingRangeError`, `RangeOverlapError`,
+`RangeOrderError`, `RangeBoundsError`, `RangeSizeError`. Overlapping and unsorted tokens
+are merged by default; pass `on_overlap="reject"` or `on_unsorted="reject"` to
+`parse_ranges` to refuse them.
+
+## Command line
+
+```
+intranges expand "1-3,7"                          # 1 2 3 7, one per line
+intranges expand "0-10:3" --dialect cpulist -d ,  # 0,3,6,9
+seq 1 5 | intranges compress                      # 1-5
+intranges normalize "8, 1-3, 2, 4"                # 1-4,8
+intranges count "0-10000000000"                   # 10000000001
+intranges contains "0-3,8-11" 9 12                # 9 yes, 12 no; exit code 2
+intranges complement "0-3,8-11" --lower 0 --upper 15   # 4-7,12-15
+```
+
+Errors go to stderr with exit code 1. Put `--` before a range string that starts with
+`-`. See `intranges --help` and [the guide](docs/GUIDE.md) for everything else.
+
+## Why
+
+Expressing a set of integers as a compact string like `1-5,8,10-12` is common in page
+selectors, CPU affinity, job arrays and config files, but converting it back and forth
+usually ends up reimplemented in each project. `intspan` covers the idea with a
+set-like class, yet it is untyped (it ships no `py.typed`) and expands its ranges in
+memory. `intranges` is strictly typed, keeps ranges as spans, and follows documented
+syntaxes instead of inventing new ones.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

intranges-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+intranges/__init__.py,sha256=F0GqUHgnFDZ5HJyBIYcYsCf39_3t2LqFIGqp-E6RfyY,1297
+intranges/_cli.py,sha256=g3XJ_Yxqct7fkF8CjfhROyLyE4Y2mLJfPkwN7cjiA1U,7274
+intranges/_compact.py,sha256=rM7d4rycUri_tivN60_v0mkd-hRR-hL7VOhl1hPItUc,2597
+intranges/_dialect.py,sha256=vUOXP6Nw4BDuqmvflCBeV5o7Qzzj7ULo-tmCoF5qFzw,4436
+intranges/_errors.py,sha256=nMOKJr5UPwepi6lJLL8cVYOm9AisrOrU5Z4-MMKoVEk,2120
+intranges/_intranges.py,sha256=SaUF9IASFDPuQQoMkg0X_OwT5YwLBL64yH6BwqRSi6E,7289
+intranges/_parse.py,sha256=HIr84P7muFV-069R2Y6byY92L5Ozm19J5e5gt8u3uxE,7003
+intranges/_spans.py,sha256=MEg3FyiPwZPPGv1PxSLqInz_8zImGPsyD5tXySurAU0,2254
+intranges/_tokens.py,sha256=J4iGOfc8VC-mdYSekZOo1OsSrcXLIBkcTqDuW04Eqjc,7046
+intranges/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+intranges-0.2.0.dist-info/METADATA,sha256=gO3s5yYFYHBNBbCVnx1cgiNUN0JOLSM2AtcPkvsITOQ,6423
+intranges-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+intranges-0.2.0.dist-info/entry_points.txt,sha256=1wdROgR9jXqFjx8In01wHdboqYSSMLyk7XpOy6J0q8s,50
+intranges-0.2.0.dist-info/licenses/LICENSE,sha256=_WmABlQG__oqlx4Rzp-qDJ10xND5KCLScftbhXbLC_c,1070
+intranges-0.2.0.dist-info/RECORD,,

intranges-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

intranges-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+intranges = intranges._cli:main

intranges-0.2.0.dist-info/licenses/LICENSE

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