refdef 0.1.0__tar.gz → 0.2.0__tar.gz

{refdef-0.1.0 → refdef-0.2.0}/.gitignore

@@ -9,3 +9,4 @@ dist/
 .site-src/
 .site/
 .refdef/
+.cache/

refdef-0.2.0/.python-version

@@ -0,0 +1 @@
+3.15.1

{refdef-0.1.0 → refdef-0.2.0}/DESIGN.md

@@ -4,7 +4,7 @@ refdef is a small Python library for reference designations: the tags that name
 
 ## Purpose
 
-A designation names an occurrence of a thing by its place in one or more trees: what it does (function, `=`), what it is (product, `-`) and where it sits (location, `+`). Every electrical engineer who scripts, generates or checks drawings, lists and PLC configurations in Python meets these tags, and every tool passes them around as strings and then re-splits, re-sorts and re-checks them in slightly different ways. refdef gives the tag one structured value, one strict way to print it, one lenient way to read it, and the operations a tool needs on top: relative paths, common prefixes, free-number allocation, natural sort, a class-code table and a check that reports issues. It has no runtime dependency, does no I/O and holds no global state.
+A designation names an occurrence of a thing by its place in one or more trees: what it does (function, `=`), what it is (product, `-`) and where it sits (location, `+`). Every electrical engineer who scripts, generates or checks drawings, lists and PLC configurations in Python meets these tags, and every tool passes them around as strings and then re-splits, re-sorts and re-checks them in slightly different ways. refdef gives the tag one structured value, one strict way to print it, one lenient way to read it, and the operations a tool needs on top: relative paths, common prefixes, free-number allocation, natural sort, a class-code table and a check that reports issues. It also numbers any run of positive integers, such as terminals on a rail, cores of a cable or screw positions, by the same lowest-free rule. It has no runtime dependency, does no I/O and holds no global state.
 
 ## The family
 
@@ -24,13 +24,13 @@ symdef draws a thing, elecdef says what it is, refdef says what it is called; an
 
 **Designation.** A frozen tuple of levels and an optional top node (printed `<...>`). The empty designation is the root. Level order is kept as given; nothing re-sorts aspects. The builder is the constructor taking levels and `child(aspect, code, number, label)`, and nothing else: two designations are joined through their levels, `Designation(tag.levels + d.levels)`, and no operator builds a value. It is viewed with `only(*aspects)`, `parent(aspect)` and `last`. A top node, when given, is stripped, non-empty and holds none of `> : ; &`.
 
-**Scheme.** A frozen value passed to every check: the aspects that are on, a `LetterRule` (letter count, letters that never appear) and a `ClassTable`. `STANDARD` is the shipped scheme. `scheme.extend(*entries, aspects=...)` returns a new scheme with project classes overlaid and further aspects on; a project that uses `J` for its board connectors adds `ClassEntry("J", "board connector")` this way.
+**Scheme.** A frozen value passed to every check: the aspects that are on, a `LetterRule` (letter count, letters that never appear) and a `ClassTable`. `STANDARD` is the shipped scheme. `scheme.extend(*entries, aspects=..., never=...)` returns a new scheme with project classes overlaid and further aspects on; a project that uses `J` for its board connectors adds `ClassEntry("J", "board connector")` this way. `never=` bars further letters on top of the scheme's own; a project whose letter rule also bars `A` writes `STANDARD.extend(never={"A"})`. `never` is any iterable of single A-Z letters, stored as a frozenset; a bare `str` or a non-letter is a `TypeError`.
 
 **Parse and render.** `str(d)` prints strictly: every level with its sign, no padding, no separators. `render(d, pad=, dotted=, bare=)` adds the dialects a caller may want: `pad={"W": 4}` prints `-W0001`; `dotted=(Aspect.PRODUCT,)` prints a number-only sub-level as `-W25.1`; `bare=True` drops the first sign. `parse(text, bare=)` reads leniently and returns `Parsed(value, issues)`: lower-case code letters are raised, leading zeros dropped, a dot read as a sub-level, text before the first sign taken as the aspect the caller names in `bare` (a required keyword: which aspect a signless tag means is the caller's convention), anything that is not letters and a number kept verbatim as a label, each with a named issue. Nothing is coerced to a default letter or number, and nothing raises for content. `parse` knows shape only; `check(designations, scheme)` holds every scheme rule: an aspect that is off, a letter count, a letter that never appears, an unknown class, a duplicate. An `Issue` is a code from a closed enum of 21 (16 from `parse` and `parse_address`, 5 from `check`, listed in R6), a subject and a message; the caller decides what is fatal. A digit run of zero or over nine digits reads as a label with an issue.
 
 **Tree arithmetic.** Every operation works per aspect. `d.within(root)` holds when, for each aspect both share, the root's levels are a head of `d`'s; an aspect missing from either side constrains nothing; a root with a top node matches only that top. `d.relative_to(root)` drops the matched heads and keeps the rest in order, so `=U1=P1+ER+C1-K1` relative to the unit root `=U1+ER` is `=P1+C1-K1`, and a cable `=U1-W1` with no location prints `-W1` inside that unit. `Designation.common(*ds)` is the longest shared head per aspect, ordered as the first argument; every argument is within it. Units as atoms is this: a unit's own document prints each tag relative to the unit's root.
 
-**Numbering.** `allocate(aspect, code, taken, reserved, first=1)` returns the lowest free number: the first `n` from `first` whose level is in neither collection. Gaps refill unless the caller lists them as reserved. `number_group(aspect, codes, taken, reserved)` numbers a sequence of codes in one go and feeds each result back into `taken`. refdef owns no store of retired numbers; what forms a sibling group and what stays reserved are the caller's facts.
+**Numbering.** `allocate(aspect, code, taken, reserved, first=1)` returns the lowest free number: the first `n` from `first` whose level is in neither collection. Gaps refill unless the caller lists them as reserved. `lowest_free(taken, reserved=(), *, first=1)` is the same rule over plain ints: the first `n` from `first` in neither collection. `reserved` holds numbers never handed out, retired or kept back, and the caller stores them; refdef stores none. `number_group(aspect, codes, taken, reserved)` numbers a sequence of codes in one go and feeds each result back into `taken`. refdef owns no store of retired numbers; what forms a sibling group and what stays reserved are the caller's facts.
 
 **Sorting.** `natural_key(text, case_sensitive=True)` orders digit runs by value and text runs as text, numbers first, with the raw text as the last tie-break (`X01` before `X1`). `sort_key(d, aspects=, case_sensitive=True)` is one pair per level, aspect rank then the natural key of the level text; `aspects` is a required keyword, since the order of aspects is the caller's convention, and an unlisted aspect ranks after the listed ones.
 
@@ -46,7 +46,7 @@ The table has its own version line, independent of the library version. A moved,
 
 ## The public surface
 
-`refdef.__all__`: `Aspect`, `Level`, `Designation`, `Terminal`, `Signal`, `Scheme`, `ClassEntry`, `STANDARD`, `parse`, `Parsed`, `render`, `check`, `Issue`, `IssueCode`, `allocate`, `number_group`, `natural_key`, `sort_key`. `refdef.plc.__all__`: `Memory`, `Size`, `Address`, `ChannelTag`, `parse_address`. `ClassTable` and `LetterRule` are reached through `Scheme`. An application imports these names and nothing below them. Every surface name has a docstring of one summary line and at most two lines of why, an entry in the generated API reference and a runnable example in the guide (family rule F9). No surface class overloads an operator; one spelling builds, one reads, one prints (F15). `python -m refdef api` prints the two `__all__` tuples with every surface signature; `docs/api-snapshot.txt` holds that output byte for byte, and a change to it is a reviewed design change (family rules F8 and F12).
+`refdef.__all__`: `Aspect`, `Level`, `Designation`, `Terminal`, `Signal`, `Scheme`, `ClassEntry`, `STANDARD`, `parse`, `Parsed`, `render`, `check`, `Issue`, `IssueCode`, `allocate`, `lowest_free`, `number_group`, `natural_key`, `sort_key`. `refdef.plc.__all__`: `Memory`, `Size`, `Address`, `ChannelTag`, `parse_address`. `ClassTable` and `LetterRule` are reached through `Scheme`. An application imports these names and nothing below them. Every surface name has a docstring of one summary line and at most two lines of why, an entry in the generated API reference and a runnable example in the guide (family rule F9). No surface class overloads an operator; one spelling builds, one reads, one prints (F15). `python -m refdef api` prints the two `__all__` tuples with every surface signature; `docs/api-snapshot.txt` holds that output byte for byte, and a change to it is a reviewed design change (family rules F8 and F12).
 
 ## Docs and agents
 
@@ -54,6 +54,10 @@ The docs site is GitHub Pages, built with Zensical from `docs/`, with the API re
 
 Two files are written for agents (family rule F16). `llms.txt` at the docs site root lists, in plain text, what refdef is, the URL of each docs page, the surface names with one line each, and the rules in one line each. `AGENTS.md` in the repository root names the docs site, the surface command (`python -m refdef api`) and snapshot (`docs/api-snapshot.txt`), the guide, `DESIGN.md` and `RULES.md`; it says which files change only with a design review (`DESIGN.md`, `RULES.md`, `docs/api-snapshot.txt`, `src/refdef/tables/`, `tests/corpus/`) and that a need the surface does not meet is a reviewed design change and never a workaround. The docs build is a gate: a surface name without an example, or an example that does not run, fails it (F9).
 
+## 0.2.0 surface (2026-10-23)
+
+`lowest_free(taken, reserved=(), *, first=1)` is the lowest free number over plain ints; a `first` below 1 is a `TypeError`. `Scheme.extend(never=...)` bars further letters as a union with the scheme's own and lifts none; it takes any iterable of single A-Z letters and stores a frozenset. A bare `str` (so "IO" never splits quietly) and any non-letter raise `TypeError`.
+
 ## Out of scope
 
 refdef does not hold: the meaning of a pin or terminal number, a device's recommended class code, a drawing of anything, a store of retired numbers or a numbering file, document designations and their kind codes, signal-name rules, wire-number rules, vendor PLC dialects, the three-letter class level, other code sets, translations. Each is either another library's fact or a later, reviewed addition.

{refdef-0.1.0 → refdef-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: refdef
-Version: 0.1.0
+Version: 0.2.0
 Summary: Reference designations as strict, typed, immutable Python values: parse, check, print, number and order
 Project-URL: Repository, https://github.com/OleJBondahl/refdef
 Author: Ole Johan Bondahl

{refdef-0.1.0 → refdef-0.2.0}/RULES.md

@@ -8,10 +8,10 @@ These rules bind every implementation and every later change of refdef. The fami
 - **R2. The shapes that construct.** A `Level` has upper-case letters with a number, a number alone, or a stripped non-empty label without `= - + % # : ; & < > .`; a number is an `int` from 1 to 999_999_999; a label is never shaped like a code (ASCII letters, then digits worth 1 to 999_999_999, such as `K1`, `k01` or `7`), because `-K1` must read back as a coded level (`K0` and `K1234567890` are labels); a `Designation.top` is empty or stripped, non-empty and without `> : ; &`; a `Terminal` has at least one pin, each stripped, non-empty and without `:`; a `Signal.name` is stripped and non-empty, and a `Signal.of` is `None` or a designation with at least one level or a top (an empty `Signal.of` is refused, because `;N` must read back to the same value); any other shape is malformed and raises `TypeError` at construction (F3). GATE: `tests/test_malformed.py` holds one fixture per clause (the labels `K1`, `k01` and `7`, the numbers 0 and 1_000_000_000, and an empty `Signal.of` among them) and asserts `TypeError`; `tests/test_level.py` asserts every value that constructs prints and parses back to itself (R1).
 - **R3. Strict render.** `str()` prints every level with its sign and never pads, dots or drops a sign; every dialect (`pad`, `dotted`, `bare`) is an explicit `render` option, and a change to any printed form moves the golden. GATE: `tests/test_render.py` asserts `str(v) == render(v)` over the round-trip corpus, compares `render` of `tests/corpus/strings.txt` under each option to `tests/corpus/render.txt` line by line, and asserts each option changes only the documented characters; `scripts/design_guard.py` watches `tests/corpus/` (F12).
 - **R4. Lenient parse with issues.** `parse` and `parse_address` return a value and an issue tuple for any string, every lenient repair (case, leading zero, dot, missing sign, free label, unsupported suffix) is matched by an issue with its code, and no default letter or number is ever substituted; a digit run that is zero or longer than nine digits (the bound of R2) reads as a label with an issue. GATE: `tests/test_parse.py` feeds a fuzz corpus (random text, every sign alone, empty, whitespace) and asserts no exception, and asserts one issue per repair against a table of input, value and codes.
-- **R5. Shape in parse, scheme in check.** `parse` takes no scheme, every rule that needs one (aspect on, letter count, never-letters, unknown class by `code[:depth]`, duplicate) lives in `check`, and no function reads a scheme or table other than through its argument. GATE: `tests/test_parse.py` asserts `parse`'s signature has no `scheme` parameter; `tests/test_check.py` has one case per check-family `IssueCode`, asserts `parse` never emits them, and an AST test in it fails the name `STANDARD` or an import from `refdef.tables` anywhere under `src/refdef` outside `scheme.py` and `__init__.py`.
+- **R5. Shape in parse, scheme in check.** `parse` takes no scheme, every rule that needs one (aspect on, letter count, never-letters (`Scheme.extend(never=)` takes any iterable of single A-Z letters and refuses a bare `str`), unknown class by `code[:depth]`, duplicate) lives in `check`, and no function reads a scheme or table other than through its argument. GATE: `tests/test_parse.py` asserts `parse`'s signature has no `scheme` parameter; `tests/test_check.py` has one case per check-family `IssueCode`, asserts `parse` never emits them, and an AST test in it fails the name `STANDARD` or an import from `refdef.tables` anywhere under `src/refdef` outside `scheme.py` and `__init__.py`.
 - **R6. An issue is a code, a subject and a message.** `Issue` has exactly these three fields, no severity, and `IssueCode` is a closed enum of exactly 21 codes that every emitted issue uses: the parse family (16) `EMPTY`, `NO_SIGN`, `EMPTY_LEVEL`, `EMPTY_TOP`, `WHITESPACE`, `LOWER_CASE`, `LEADING_ZERO`, `ZERO_NUMBER`, `NUMBER_TOO_LARGE`, `FREE_LABEL`, `BAD_LABEL`, `DOT_LEVEL`, `EMPTY_PIN`, `EMPTY_NAME`, `UNSUPPORTED_SUFFIX`, `NOT_ADDRESS` (the last only from `parse_address`), and the check family (5) `ASPECT_OFF`, `LETTER_COUNT`, `NEVER_LETTER`, `UNKNOWN_CLASS`, `DUPLICATE`; the values are the lower-case names. GATE: `tests/test_check.py` asserts the field names of `Issue`, that the `IssueCode` names equal these 21, and that every issue any test produces has a code in `IssueCode`.
 - **R7. Per-aspect tree arithmetic.** `within`, `relative_to` (on `Designation`, `Terminal` and `Signal`) and `common` follow the rule in `DESIGN.md` exactly, and every argument is within `common(*ds)`. GATE: `tests/test_tree.py` holds the unit-root, cable, mixed-order and top-node cases for all three types, and a property test asserting `a.within(common(a, b))`, `len(b.relative_to(common(a, b)).levels) == len(b.levels) - len(common(a, b).levels)` and `Terminal(d, p).relative_to(r).of == d.relative_to(r)` for random values.
-- **R8. Numbering is pure.** `allocate` returns the lowest free number from `first` given `taken` and `reserved`, `number_group` equals `allocate` applied in sequence with each result added to `taken`, and refdef holds no numbering store. GATE: `tests/test_numbering.py` asserts `allocate` against a brute-force search and `number_group` against the sequential fold, for random inputs.
+- **R8. Numbering is pure.** `allocate` returns the lowest free number from `first` given `taken` and `reserved`, `lowest_free` does the same over plain ints, `number_group` equals `allocate` applied in sequence with each result added to `taken`, and refdef holds no numbering store. GATE: `tests/test_numbering.py` asserts `allocate` and `lowest_free` against a brute-force search, `lowest_free` against `allocate` over one class, and `number_group` against the sequential fold, for random inputs.
 - **R9. One natural order.** `natural_key` orders digit runs by value and text runs as text, numbers before text, with the raw text as the last tie-break; `sort_key` is one `(aspect rank, natural_key(level.text))` pair per level, with the aspect order a required keyword and an unlisted aspect ranked after the listed ones in enum order. GATE: `tests/test_order.py` asserts the fixed cases (`-W2 < -W10`, `X01 < X1`, numbers before text), a property test that `sorted` by `sort_key` is a total order consistent with `natural_key` on single-level designations, and that `sort_key` has no default for `aspects`.
 - **R10. The class table is versioned.** `ClassTable.version` is refdef's own line, bumps whenever the entry tuple changes, and the changelog names each moved code. GATE: `tests/test_table_version.py` hashes the entry tuple and compares it with the hash stored beside `version`, failing when the entries change and the version does not; the changelog line is review.
 - **R11. One PLC grammar in the core.** `refdef.plc` holds only the direct-address form (`%` + memory area + optional size + dotted path, `*` for incomplete), with `as_bit` the one normalisation, and every vendor dialect is its own module behind its own type. GATE: `tests/test_plc.py` round-trips `tests/corpus/addresses.txt` through `parse_address` and `str`, asserts `as_bit` changes only a size-less dotted address, and `tests/test_boundary.py` fails a vendor name (`siemens`, `rockwell`, `omron`, `mitsubishi`, `beckhoff`) in `plc.py`.

{refdef-0.1.0 → refdef-0.2.0}/docs/CHANGELOG.md

@@ -5,6 +5,11 @@ Every change to the public surface gets a line under Unreleased until the releas
 
 ## Unreleased
 
+## 0.2.0 (2026-10-23)
+
+- Add `lowest_free(taken, reserved=(), *, first=1)`: the lowest free number over plain ints.
+- `Scheme.extend` takes `never`: letters barred in addition to the scheme's own, as any iterable of A-Z letters (a bare `str` is a `TypeError`).
+
 ## 0.1.0 (2026-10-22)
 
 - Add `Aspect`, `Level`, `Designation`, `Terminal`, `Signal`, `Issue`, `IssueCode`, `Parsed` and `render`.

{refdef-0.1.0 → refdef-0.2.0}/docs/api-snapshot.txt

@@ -56,6 +56,11 @@ check(designations: 'Iterable[Designation]', scheme: 'Scheme') -> 'tuple[Issue,
 
     Terminals and signals are not checked: pass their `of`.
 
+lowest_free(taken: 'Collection[int]', reserved: 'Collection[int]' = (), *, first: 'int' = 1) -> 'int'
+    The smallest number from `first` that is in neither `taken` nor `reserved`.
+
+    `reserved` is never handed out; the caller stores it. `first` below 1 is a TypeError.
+
 natural_key(text: 'str', *, case_sensitive: 'bool' = True) -> 'tuple[Any, ...]'
     A sort key: digit runs by value, text runs as text, numbers first, then the raw text.
 

{refdef-0.1.0 → refdef-0.2.0}/docs/guide/class-table.md

@@ -25,3 +25,11 @@ P = Aspect.PRODUCT
 print(check([parse("-J1", bare=P).value], j))   # ()
 print([i.code.value for i in check([parse("-J1", bare=P).value], STANDARD)])   # ['unknown_class']
 ```
+
+`never` bars further letters on top of the scheme's own: the new set is the union, so `I` and `O`
+stay barred and `extend` never lifts a letter. Any iterable of letters works; a bare `str` is a `TypeError`.
+
+```python
+strict = STANDARD.extend(never={"A"})
+print([i.code.value for i in check([parse("-A1", bare=P).value], strict)])   # ['never_letter', 'unknown_class']
+```

{refdef-0.1.0 → refdef-0.2.0}/docs/guide/number.md

@@ -16,3 +16,14 @@ print([level.text for level in group])
 ```
 
 `first` is at least 1. A reserved level is skipped like a taken one.
+
+`lowest_free` is the same rule over plain positive integers, such as terminals on a rail, cores of
+a cable or screw positions.
+
+```python
+from refdef import lowest_free
+print(lowest_free({1, 2}, reserved={3}))                                         # 4
+print(lowest_free({1, 2}, first=10))                                             # 10
+```
+
+A reserved number is skipped like a taken one; the caller keeps the reserved set.

{refdef-0.1.0 → refdef-0.2.0}/docs/llms.txt

@@ -30,10 +30,10 @@ R1. For every designation, terminal or signal value `v`, `parse(str(v), bare=a).
 R2. A `Level` has upper-case letters with a number, a number alone, or a stripped non-empty label without `= - + % # : ; & < > .`; a number is an `int` from 1 to 999_999_999; a label is never shaped like a code (ASCII letters, then digits worth 1 to 999_999_999, such as `K1`, `k01` or `7`), because `-K1` must read back as a coded level (`K0` and `K1234567890` are labels); a `Designation.top` is empty or stripped, non-empty and without `> : ; &`; a `Terminal` has at least one pin, each stripped, non-empty and without `:`; a `Signal.name` is stripped and non-empty, and a `Signal.of` is `None` or a designation with at least one level or a top (an empty `Signal.of` is refused, because `;N` must read back to the same value); any other shape is malformed and raises `TypeError` at construction (F3).
 R3. `str()` prints every level with its sign and never pads, dots or drops a sign; every dialect (`pad`, `dotted`, `bare`) is an explicit `render` option, and a change to any printed form moves the golden.
 R4. `parse` and `parse_address` return a value and an issue tuple for any string, every lenient repair (case, leading zero, dot, missing sign, free label, unsupported suffix) is matched by an issue with its code, and no default letter or number is ever substituted; a digit run that is zero or longer than nine digits (the bound of R2) reads as a label with an issue.
-R5. `parse` takes no scheme, every rule that needs one (aspect on, letter count, never-letters, unknown class by `code[:depth]`, duplicate) lives in `check`, and no function reads a scheme or table other than through its argument.
+R5. `parse` takes no scheme, every rule that needs one (aspect on, letter count, never-letters (`Scheme.extend(never=)` takes any iterable of single A-Z letters and refuses a bare `str`), unknown class by `code[:depth]`, duplicate) lives in `check`, and no function reads a scheme or table other than through its argument.
 R6. `Issue` has exactly these three fields, no severity, and `IssueCode` is a closed enum of exactly 21 codes that every emitted issue uses: the parse family (16) `EMPTY`, `NO_SIGN`, `EMPTY_LEVEL`, `EMPTY_TOP`, `WHITESPACE`, `LOWER_CASE`, `LEADING_ZERO`, `ZERO_NUMBER`, `NUMBER_TOO_LARGE`, `FREE_LABEL`, `BAD_LABEL`, `DOT_LEVEL`, `EMPTY_PIN`, `EMPTY_NAME`, `UNSUPPORTED_SUFFIX`, `NOT_ADDRESS` (the last only from `parse_address`), and the check family (5) `ASPECT_OFF`, `LETTER_COUNT`, `NEVER_LETTER`, `UNKNOWN_CLASS`, `DUPLICATE`; the values are the lower-case names.
 R7. `within`, `relative_to` (on `Designation`, `Terminal` and `Signal`) and `common` follow the rule in `DESIGN.md` exactly, and every argument is within `common(*ds)`.
-R8. `allocate` returns the lowest free number from `first` given `taken` and `reserved`, `number_group` equals `allocate` applied in sequence with each result added to `taken`, and refdef holds no numbering store.
+R8. `allocate` returns the lowest free number from `first` given `taken` and `reserved`, `lowest_free` does the same over plain ints, `number_group` equals `allocate` applied in sequence with each result added to `taken`, and refdef holds no numbering store.
 R9. `natural_key` orders digit runs by value and text runs as text, numbers before text, with the raw text as the last tie-break; `sort_key` is one `(aspect rank, natural_key(level.text))` pair per level, with the aspect order a required keyword and an unlisted aspect ranked after the listed ones in enum order.
 R10. `ClassTable.version` is refdef's own line, bumps whenever the entry tuple changes, and the changelog names each moved code.
 R11. `refdef.plc` holds only the direct-address form (`%` + memory area + optional size + dotted path, `*` for incomplete), with `as_bit` the one normalisation, and every vendor dialect is its own module behind its own type.
@@ -49,6 +49,7 @@ Parsed: a value read from text together with its issues.
 parse: reads text leniently into a value and the issues of each repair, and never raises for content.
 render: the strict printer with the explicit options pad, dotted and bare.
 allocate: the lowest free number of a class given what is taken and reserved; stores nothing.
+lowest_free: the lowest free plain int from first given taken and reserved; stores nothing.
 number_group: levels for several codes, each numbered after the earlier ones; taken is not changed.
 natural_key: a sort key with digit runs by value, numbers before text, ties on the raw text.
 sort_key: a designation's key, one pair per level; the aspect order is a required keyword.
@@ -57,7 +58,7 @@ Size: the access size of a direct PLC address (refdef.plc): none, bit, byte, wor
 Address: a direct PLC address printed %IX0.0, %QW4 or %I* (refdef.plc); as_bit() adds the bit size to a size-less dotted address.
 ChannelTag: a terminal with an optional address (refdef.plc), printed as the terminal alone.
 parse_address: reads a direct PLC address (refdef.plc), repairing outer whitespace and leading zeros with an issue each; text that is not one gives None and a NOT_ADDRESS issue.
-Scheme: what check tests against: the aspects that are on, a letter rule and a class table; extend returns a new scheme with project classes and aspects.
+Scheme: what check tests against: the aspects that are on, a letter rule and a class table; extend returns a new scheme with project classes, aspects and further barred letters (never: any iterable of A-Z letters, not a str).
 ClassEntry: one class code with its title, the typical device of the class.
 STANDARD: the shipped scheme (function, product and location on, one to three letters without I and O, the versioned standard class table).
 check: tests designations against a scheme and returns an issue for each finding, in order; it reads nothing but its scheme argument.

{refdef-0.1.0 → refdef-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "refdef"
-version = "0.1.0"
+version = "0.2.0"
 description = "Reference designations as strict, typed, immutable Python values: parse, check, print, number and order"
 readme = "README.md"
 requires-python = ">=3.14"

{refdef-0.1.0 → refdef-0.2.0}/src/refdef/__init__.py

@@ -6,7 +6,7 @@ from refdef._render import render
 from refdef.designation import Designation
 from refdef.issues import Issue, IssueCode, Parsed
 from refdef.level import Aspect, Level
-from refdef.numbering import allocate, number_group
+from refdef.numbering import allocate, lowest_free, number_group
 from refdef.order import natural_key, sort_key
 from refdef.scheme import STANDARD, ClassEntry, Scheme
 from refdef.terminal import Signal, Terminal
@@ -25,6 +25,7 @@ __all__ = [
     "Terminal",
     "allocate",
     "check",
+    "lowest_free",
     "natural_key",
     "number_group",
     "parse",

{refdef-0.1.0 → refdef-0.2.0}/src/refdef/numbering.py

@@ -5,6 +5,12 @@ from collections.abc import Collection, Sequence
 from refdef.level import Aspect, Level
 
 
+def _check_first(first: int) -> None:
+    if not isinstance(first, int) or isinstance(first, bool) or first < 1:
+        msg = "first must be an int of at least 1"
+        raise TypeError(msg)
+
+
 def allocate(
     aspect: Aspect,
     code: str,
@@ -17,15 +23,25 @@ def allocate(
 
     `first` below 1 is a TypeError. Nothing is stored: the caller passes what is taken.
     """
-    if not isinstance(first, int) or isinstance(first, bool) or first < 1:
-        msg = "first must be an int of at least 1"
-        raise TypeError(msg)
+    _check_first(first)
     number = first
     while Level(aspect, code, number) in taken or Level(aspect, code, number) in reserved:
         number += 1
     return number
 
 
+def lowest_free(taken: Collection[int], reserved: Collection[int] = (), *, first: int = 1) -> int:
+    """The smallest number from `first` that is in neither `taken` nor `reserved`.
+
+    `reserved` is never handed out; the caller stores it. `first` below 1 is a TypeError.
+    """
+    _check_first(first)
+    number = first
+    while number in taken or number in reserved:
+        number += 1
+    return number
+
+
 def number_group(
     aspect: Aspect,
     codes: Sequence[str],

{refdef-0.1.0 → refdef-0.2.0}/src/refdef/scheme.py

@@ -44,6 +44,16 @@ class ClassTable:
         return self.index.get(code[: self.depth])
 
 
+def _check_never(never: Iterable[str]) -> frozenset[str]:
+    letters = None if isinstance(never, str) else frozenset(never)
+    if letters is None or not all(
+        isinstance(c, str) and len(c) == 1 and "A" <= c <= "Z" for c in letters
+    ):
+        msg = "never must be an iterable of upper-case ASCII letters, not a str"
+        raise TypeError(msg)
+    return letters
+
+
 @dataclass(frozen=True)
 class Scheme:
     """What `check` tests against: aspects on, a letter rule and a class table.
@@ -56,11 +66,23 @@ class Scheme:
     letters: LetterRule
     classes: ClassTable
 
-    def extend(self, *entries: ClassEntry, aspects: Iterable[Aspect] = ()) -> Scheme:
-        """A new scheme with `entries` overlaid by code (later wins) and `aspects` turned on."""
+    def extend(
+        self,
+        *entries: ClassEntry,
+        aspects: Iterable[Aspect] = (),
+        never: Iterable[str] = (),
+    ) -> Scheme:
+        """A new scheme with `entries` overlaid by code (later wins) and `aspects` turned on.
+
+        `never`: any iterable of A-Z letters (not a str) barred on top of the scheme's own.
+        """
+        barred = _check_never(never)
         merged = {entry.code: entry for entry in (*self.classes.entries, *entries)}
         table = replace(self.classes, entries=tuple(merged.values()))
-        return replace(self, aspects=self.aspects | frozenset(aspects), classes=table)
+        letters = replace(self.letters, never=self.letters.never | barred)
+        return replace(
+            self, aspects=self.aspects | frozenset(aspects), letters=letters, classes=table
+        )
 
 
 _TABLE = ClassTable(

{refdef-0.1.0 → refdef-0.2.0}/tests/test_check.py

@@ -139,6 +139,68 @@ def test_r5_check_reads_the_scheme_it_is_given():
     assert _codes("-J1") == ["unknown_class"]
 
 
+def _never_codes(scheme, text="-A1"):
+    value = parse(text, bare=P).value
+    assert isinstance(value, Designation)
+    return [i.code for i in check([value], scheme)]
+
+
+def test_r5_extend_never_bars_a_further_letter():
+    """R5: `extend(never=)` makes `check` report the letter; STANDARD does not."""
+    strict = STANDARD.extend(never=frozenset("A"))
+    assert IssueCode.NEVER_LETTER in _never_codes(strict)
+    assert IssueCode.NEVER_LETTER not in _never_codes(STANDARD)
+
+
+def test_r5_extend_never_is_a_union_and_leaves_the_scheme_alone():
+    """R5: I and O stay barred, A is added, and the scheme extended is unchanged."""
+    strict = STANDARD.extend(never=frozenset("A"))
+    assert strict.letters.never == frozenset("IOA")
+    assert strict.letters.min_count == STANDARD.letters.min_count
+    assert strict.letters.max_count == STANDARD.letters.max_count
+    assert STANDARD.letters.never == frozenset("IO")
+    assert IssueCode.NEVER_LETTER in _never_codes(strict, "-I1")
+
+
+def test_r5_extend_never_composes_with_entries_and_aspects():
+    """R5: entries and aspects overlay as before when `never` is also given."""
+    scheme = STANDARD.extend(
+        ClassEntry("J", "board connector"), aspects=(Aspect.TYPE,), never=frozenset("A")
+    )
+    assert Aspect.TYPE in scheme.aspects
+    assert scheme.classes.get("J") == ClassEntry("J", "board connector")
+    assert scheme.letters.never == frozenset("IOA")
+
+
+def test_r5_extend_default_never_keeps_the_letter_rule():
+    """R5: no `never` gives the same letter rule."""
+    assert STANDARD.extend().letters == STANDARD.letters
+
+
+def test_r5_extend_never_accepts_a_set_and_a_tuple():
+    """R5: a set and a tuple of letters give the same Scheme as a frozenset."""
+    want = STANDARD.extend(never=frozenset("QA"))
+    assert STANDARD.extend(never={"Q", "A"}) == want
+    assert STANDARD.extend(never=("Q", "A")) == want
+    assert want.letters.never == frozenset("IOQA")
+
+
+def test_r5_extend_never_refuses_a_bare_str():
+    """R5: "IO" is a TypeError, not two letters; a one-letter str is refused too."""
+    for text in ("IO", "A"):
+        with pytest.raises(TypeError):
+            STANDARD.extend(never=text)
+
+
+@pytest.mark.parametrize(
+    "never", [frozenset({"a"}), frozenset({"AB"}), frozenset({1}), ["a"], ("AB",), 5]
+)
+def test_r5_extend_never_refuses_non_letters(never):
+    """R5: a `never` holding anything but single A-Z letters is a TypeError."""
+    with pytest.raises(TypeError):
+        STANDARD.extend(never=never)
+
+
 def test_r5_check_type_errors():
     """R5: a non-Scheme scheme or a non-Designation item is a TypeError, not an issue."""
     with pytest.raises(TypeError):

{refdef-0.1.0 → refdef-0.2.0}/tests/test_llms.py

@@ -44,4 +44,10 @@ def test_a_missing_name_and_a_changed_rule_are_found():
     assert missing_names("parse: x\nSize: y\n", [("m", "parse"), ("m", "Memory")]) == ["m.Memory"]
     rules = "- **R1. Title.** Body one. GATE: x\n- **R2. Other.** Body two.\n"
     assert missing_rules("R1. Body one.\nR2. Body 2.\n", rules) == ["R2"]
-    assert len(RULE.findall(_read("RULES.md"))) == 12
+
+
+def test_every_rule_heading_parses_and_the_ids_run_from_one():
+    rules = _read("RULES.md")
+    ids = [rid for rid, _ in RULE.findall(rules)]
+    assert len(ids) == len(re.findall(r"^- \*\*R\d+", rules, re.M))
+    assert ids == [f"R{n}" for n in range(1, len(ids) + 1)]

{refdef-0.1.0 → refdef-0.2.0}/tests/test_numbering.py

@@ -5,7 +5,7 @@ from itertools import count
 
 import pytest
 
-from refdef import Aspect, Level, allocate, number_group
+from refdef import Aspect, Level, allocate, lowest_free, number_group
 
 P = Aspect.PRODUCT
 
@@ -66,3 +66,47 @@ def test_allocate_refuses_a_first_below_one_or_not_an_int(first):
     """R8: `first` is an int of at least 1, else TypeError."""
     with pytest.raises(TypeError):
         allocate(P, "K", (), first=first)
+
+
+def test_lowest_free_equals_brute_force_over_500_random_inputs():
+    """R8: lowest_free is the first n from `first` in neither collection; inputs are unchanged."""
+    rng = _rng(10)
+    for _ in range(500):
+        taken = {n for n in range(1, 12) if rng.random() < 0.6}
+        reserved = {n for n in range(1, 12) if rng.random() < 0.4}
+        first = rng.randint(1, 6)
+        expected = next(n for n in count(first) if n not in taken | reserved)
+        before = (set(taken), set(reserved))
+        assert lowest_free(taken, reserved, first=first) == expected
+        assert (taken, reserved) == before
+
+
+def test_lowest_free_equals_allocate_over_one_class():
+    """R8: over one aspect and code, lowest_free of the numbers is allocate of the levels."""
+    rng = _rng(11)
+    for _ in range(500):
+        taken = _levels(rng, P, "K", 12)
+        reserved = _levels(rng, P, "K", 12)
+        first = rng.randint(1, 6)
+        numbers = ({lv.number for lv in s if lv.number is not None} for s in (taken, reserved))
+        got = lowest_free(*numbers, first=first)
+        assert got == allocate(P, "K", taken, reserved, first=first)
+
+
+def test_lowest_free_skips_a_reserved_number_like_a_taken_one():
+    """R8: a reserved number leaves a gap."""
+    assert lowest_free({1, 2}, {3}) == 4
+    assert lowest_free(set(), {1}) == 2
+
+
+def test_lowest_free_of_nothing_is_first():
+    """R8: empty input gives `first`."""
+    assert lowest_free(()) == 1
+    assert lowest_free((), first=10) == 10
+
+
+@pytest.mark.parametrize("first", [0, -1, True, 1.0, "1"])
+def test_lowest_free_refuses_a_first_below_one_or_not_an_int(first):
+    """R8: `first` is an int of at least 1, else TypeError."""
+    with pytest.raises(TypeError):
+        lowest_free((), first=first)

{refdef-0.1.0 → refdef-0.2.0}/uv.lock

@@ -321,7 +321,7 @@ wheels = [
 
 [[package]]
 name = "refdef"
-version = "0.1.0"
+version = "0.2.0"
 source = { editable = "." }
 
 [package.dev-dependencies]

refdef-0.1.0/.python-version

@@ -1 +0,0 @@
-3.15.0