intranges 0.2.0__tar.gz

intranges-0.2.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

intranges-0.2.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+buy_me_a_coffee: jlianesglrs

intranges-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

intranges-0.2.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0]
+
+### Added
+
+- `IntRanges`, an immutable `collections.abc.Set[int]` stored as spans. Membership,
+  `count`, iteration, union, intersection, difference, symmetric difference, subset
+  tests and `complement(lower, upper)` never expand values.
+- `parse_ranges`, `count` and `normalize` read strings into spans, with
+  `on_overlap="merge" | "reject"` and `on_unsorted="allow" | "reject"` policies.
+- `Dialect` and the presets `DEFAULT`, `PAGES`, `CPULIST`, `SLURM` and `HTTP`, plus the
+  `DIALECTS` registry: kernel `:used/group` and taskset `:N` strides, `N` and `all`,
+  Slurm steps and bracketed hostlist numbers, RFC 9110 open ends, suffix ranges and
+  clamping.
+- Open-ended ranges such as `5-` when `upper=` is given; `lower=` and `upper=` bounds.
+- Typed errors `RangeSyntaxError`, `DescendingRangeError`, `RangeOverlapError`,
+  `RangeOrderError`, `RangeBoundsError` and `RangeSizeError`. `RangeError` now carries
+  `text`, `token` and `offset` and offers `pointer()`.
+- `parse` gains `dialect`, `lower`, `upper` and `max_size`; `compact` gains `dialect` and
+  `width`, and writes an `IntRanges` or a step-1 `range` without expanding it.
+- `DEFAULT_MAX_SIZE` and `DEFAULT_MAX_SPANS`.
+- The `intranges` command with `expand`, `compress`, `normalize`, `count`, `contains`
+  and `complement`.
+- `docs/GUIDE.md`.
+
+### Changed
+
+- `parse` refuses to build more than 10,000,000 values unless `max_size` is raised or
+  set to `None`, so a string like `0-10000000000` fails fast instead of exhausting
+  memory.
+- `compact` now rejects values that are not integers (such as floats) with `TypeError`
+  instead of writing them as text.
+- Separators containing digits raise `ValueError`, since they make tokens ambiguous.
+
+## [0.1.0]
+
+- First release.
+- `parse` expands a compact range string into a list of ints, with support for single
+  values, ranges, negatives, whitespace and configurable separators.
+- `compact` collapses an iterable of ints into a range string, sorting and de-duplicating
+  the input first.
+- `RangeError` is raised for malformed or descending tokens.

intranges-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Thanks for taking the time. This project keeps a small, predictable shape.
+
+## Setup
+
+```
+pip install -r requirements-dev.txt
+```
+
+## Before you open a pull request
+
+- Keep public API in `src/intranges/__init__.py`; internals live in `_`-prefixed modules.
+- Add a test for the behaviour you change. Tests inject time, disk and network; they
+  never touch the real thing.
+- Run `scripts/check.ps1` (format, lint, types, tests) and make sure it passes.
+- One logical change per commit, imperative subject line.
+
+Open an issue first if the change is large or shifts the public API.

intranges-0.2.0/IMPROVEMENTS-round.md

@@ -0,0 +1,44 @@
+# Improvement round: ranked plan
+
+Ranked by user value. Every item is additive: `parse`, `compact` and `RangeError` keep
+their signatures and their documented behaviour.
+
+1. **Lazy `IntRanges` set type.** An immutable `collections.abc.Set[int]` stored as sorted,
+   disjoint, inclusive spans. Membership is a binary search, `count` is arithmetic, and
+   iteration is streamed, so `"0-10000000000"` costs two integers. Union, intersection,
+   difference, symmetric difference, subset tests and `complement(lower, upper)` work on
+   spans and never expand values.
+2. **Size guards.** `parse` refuses to build a list larger than `max_size` values
+   (default 10,000,000) and checks the total before allocating anything. Strided input
+   that would create more than `max_spans` spans raises too. Both raise
+   `RangeSizeError`.
+3. **Typed errors that point at the bad token.** `RangeError` gains `text`, `token` and
+   `offset` attributes, and specific subclasses: `RangeSyntaxError`,
+   `DescendingRangeError`, `RangeOverlapError`, `RangeOrderError`, `RangeBoundsError`,
+   `RangeSizeError`.
+   All stay `ValueError` subclasses.
+4. **Named dialects grounded in documented syntaxes.** A frozen `Dialect` dataclass plus
+   presets: `DEFAULT`, `PAGES` (CUPS `page-ranges`), `CPULIST` (Linux kernel cpu lists
+   with `:used/group`, util-linux `taskset` stride `:N`, `N` for the last CPU and `all`),
+   `SLURM` (sbatch `--array` step `:N`, optional hostlist brackets) and `HTTP`
+   (RFC 9110 byte ranges, open ends, suffix ranges, clamping). Custom dialects are a
+   `Dialect(...)` call away.
+5. **Unambiguous negative-number rule.** A `-` directly before a digit at the start of a
+   bound is a sign; the separator is the first `-` after the first bound. Dialects that
+   disallow negatives reject `-3` with a clear message instead of guessing.
+6. **Open-ended ranges with explicit bounds.** `"5-"` means "5 to the upper bound" and is
+   only accepted when the caller supplies `upper=`. Without it the error says so.
+7. **Overlap and order policy.** `parse_ranges(..., on_overlap="merge" | "reject",
+   on_unsorted="allow" | "reject")`. Rejection names the offending token.
+8. **Canonical compression and round trip.** `normalize(text)` returns the canonical
+   string; `compact` accepts an `IntRanges` without expanding it, a `dialect` and a
+   zero-pad `width`. `parse_ranges(compact(x)) == IntRanges(x)` for every finite set.
+9. **`count(text)` without materialising** and bound checks via `lower=` / `upper=`.
+10. **CLI** `intranges` with `expand`, `compress`, `normalize`, `count`, `contains` and
+    `complement`, dialect and bound options, runnable `--help` examples, errors on stderr
+    with exit code 1.
+11. **Docs.** Docstrings on every public name, a `docs/GUIDE.md` covering grammar,
+    dialects, policies and recipes, and README sources for every dialect.
+12. **Contracts and end-to-end tests.** A contract test over every public name, a
+    seeded property test against a brute-force `set` model, and a real wheel install
+    driving the console script.

intranges-0.2.0/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.

intranges-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,144 @@
+# 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/docs/GUIDE.md

@@ -0,0 +1,148 @@
+# intranges guide
+
+This guide covers the grammar, the dialects, the policies and a few recipes. The README
+has the short version.
+
+## Grammar
+
+A range string is a list of tokens joined by `list_sep` (default `,`). Whitespace
+around tokens and around separators is ignored. An empty or blank string is the empty
+set. An empty token, as in `1,,2` or a trailing `1,2,`, is a `RangeSyntaxError`.
+
+| Token         | Meaning                                    | Needs                       |
+|---------------|--------------------------------------------|-----------------------------|
+| `7`           | the single value 7                         |                             |
+| `1-5`         | 1 to 5 inclusive                           |                             |
+| `5-`          | 5 to `upper`                               | `upper=`, `open_end`        |
+| `-5`          | the last 5 values up to `upper` (HTTP)     | `upper=`, `suffix`          |
+| `0-15:4`      | every 4th value: 0, 4, 8, 12               | `stride`                    |
+| `0-99:2/25`   | 2 values from the start of every group of 25 | `stride`, `groups`        |
+| `N`           | `upper` (kernel cpu lists)                 | `upper=`, `last_alias`      |
+| `all`         | `lower` (or the dialect minimum) to `upper` | `upper=`, `all_alias`      |
+
+A range must run low to high: `5-1` is a `DescendingRangeError`.
+
+### Negative numbers and the dash
+
+When a dialect allows negatives (only `DEFAULT` among the presets), a `-` that starts a
+bound and is followed by a digit is a sign. The range separator is the first `-` after
+the first bound. So `-3--1` is -3 to -1, `-2-2` is -2 to 2, `-5` is the single value -5
+and `5-` is an open end. `1--3` reads as 1 to -3 and is rejected as descending. `--3`
+and `+3` are syntax errors. Dialects without negatives reject `-3` instead of guessing,
+except `HTTP`, where a leading `-` is a suffix range as RFC 9110 defines it.
+
+### Bounds
+
+`lower=` and `upper=` restrict every value and supply the meaning of open ends, suffix
+ranges, `N` and `all`. A value outside them is a `RangeBoundsError`. A dialect may also
+set a `minimum` (1 for pages, 0 for cpu lists, Slurm indexes and bytes). When both are
+given the stricter floor wins. `lower > upper` is a plain `ValueError`.
+
+## Dialects
+
+Each preset follows a documented syntax. Anything outside it is rejected.
+
+- `PAGES`: CUPS `-o page-ranges=1-4,7,9-12`. Pages start at 1. CUPS prints pages in
+  ascending order whatever the input order, which matches `parse_ranges`. The open
+  forms `-4` and `9-` are not part of this preset; build a `Dialect` with
+  `open_end=True` and pass `upper=` when you need `9-`.
+- `CPULIST`: the Linux kernel cpu list format, `0-3,8-11`, with the kernel's
+  `a-b:used/group` form (`100-2000:2/25` is 100, 101, 125, 126, ...), `N` for the last
+  CPU and `all`. It also accepts the util-linux `taskset` stride `a-b:N`, which equals
+  `a-b:1/N`.
+- `SLURM`: `sbatch --array` indexes such as `0,6,16-32` and the step form `0-15:4`.
+  The numeric part of a hostlist may be wrapped in brackets (`[1-3,5]`) and zero-padded
+  (`001-010`). The `%` throttle suffix is not part of the index set and is rejected.
+- `HTTP`: RFC 9110 byte ranges. The `bytes=` unit is optional on input and written on
+  output. `500-` runs to `upper`, `-500` is the last 500 bytes, and ends past `upper` are
+  clamped. A start past `upper` is unsatisfiable and raises `RangeBoundsError`. A user
+  `lower=` is a hard bound, not a clamp target. Pass `upper=length - 1`.
+
+Build your own with `Dialect(...)`; incoherent settings, such as two equal separators
+or suffix ranges together with negatives, raise `ValueError` at construction.
+
+```python
+from intranges import Dialect, parse
+
+dots = Dialect(name="dots", range_sep="..", list_sep=";", stride="by")
+parse("1..9by4;20", dialect=dots)  # [1, 5, 9, 20]
+```
+
+## Lists versus sets
+
+| Function        | Returns     | Order and repeats       | Memory                     |
+|-----------------|-------------|-------------------------|----------------------------|
+| `parse`         | `list[int]` | input order, repeats kept | one int per value, capped by `max_size` |
+| `parse_ranges`  | `IntRanges` | sorted, merged          | one pair per span          |
+| `count`         | `int`       | distinct values         | one pair per span          |
+| `normalize`     | `str`       | canonical               | one pair per span          |
+
+Strides create one span per selected group, so `parse_ranges` caps them with
+`max_spans` (default 1,000,000).
+
+## Policies
+
+`parse_ranges` merges overlapping, repeated and unsorted tokens by default.
+
+- `on_overlap="reject"` raises `RangeOverlapError` naming the later of two overlapping
+  tokens. Adjacent tokens such as `1-2,3-4` do not overlap.
+- `on_unsorted="reject"` raises `RangeOrderError` when a token starts below the start of
+  the token before it.
+
+## Canonical form
+
+`compact` and `IntRanges.format` write the canonical string: ascending, merged, with a
+run of two or more consecutive values written as `low-high` and single values alone.
+For any finite set of ints, `parse_ranges(compact(values)) == IntRanges(values)` and
+`normalize(compact(values)) == compact(values)`.
+
+## Errors
+
+All errors subclass `RangeError`, which subclasses `ValueError`. Parse errors carry
+`text`, `token` and `offset`, and `err.pointer()` draws a caret line under the token.
+
+## Recipes
+
+Free CPUs on a 16-CPU machine:
+
+```python
+from intranges import CPULIST, parse_ranges
+
+busy = parse_ranges("0-3,8-11", dialect=CPULIST)
+busy.complement(0, 15).format(CPULIST)  # "4-7,12-15"
+```
+
+Validate a user page selection for a 12-page document:
+
+```python
+from intranges import PAGES, RangeError, parse_ranges
+
+try:
+    pages = parse_ranges(user_input, dialect=PAGES, upper=12)
+except RangeError as err:
+    show_error(str(err), err.pointer())
+```
+
+Merge byte ranges of a request against a 10,000-byte file:
+
+```python
+from intranges import HTTP, parse_ranges
+
+parse_ranges("bytes=0-99,50-199,-100", dialect=HTTP, upper=9999).spans
+# ((0, 199), (9900, 9999))
+```
+
+## Command line
+
+```
+intranges expand TEXT [-d DELIM] [--unique] [--max-size N]   # N=0 lifts the cap
+intranges compress [VALUES ...] [--width W]       # values from stdin when omitted;
+                                                  # --lower/--upper validate them
+intranges normalize TEXT [--to DIALECT] [--width W]
+intranges count TEXT
+intranges contains TEXT VALUE [VALUE ...]         # exit 2 if any value is absent
+intranges complement TEXT --lower L --upper U
+```
+
+Every command takes `--dialect`, `--lower`, `--upper`, `--range-sep` and `--list-sep`.
+`TEXT` may be `-` to read from stdin. Errors go to stderr with exit code 1.

intranges-0.2.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "intranges"
+version = "0.2.0"
+description = "Typed conversion between range strings like 1-3,5 and ints, with a lazy set type, dialects and a CLI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Javier Lianes", email = "javier@lianes8studio.com" }]
+keywords = ["ranges", "integers", "parse", "compact", "range-string", "cpulist", "page-ranges", "intervals", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+    "Environment :: Console",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.scripts]
+intranges = "intranges._cli:main"
+
+[project.optional-dependencies]
+dev = ["ruff", "mypy", "pytest", "build", "twine"]
+
+[project.urls]
+Homepage = "https://lianes8studio.com"
+Repository = "https://github.com/JaviLianes8/intranges"
+Issues = "https://github.com/JaviLianes8/intranges/issues"
+Changelog = "https://github.com/JaviLianes8/intranges/blob/main/CHANGELOG.md"
+LinkedIn = "https://www.linkedin.com/in/jlianes/"
+Funding = "https://buymeacoffee.com/jlianesglrs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/intranges"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-q"