[azfoo]

🤖 Claude

Adds tilia_core.rules, the one set of rules for a valid component. It covers the kinds the importers create: marker, hierarchy, range, harmony, mode, PDF marker and beat. The importers call it for each row, and later so will bulk edits and the .tla reader and writer. None of them keeps a rule of its own.

Rebased onto v1-prerelease after #731 (set up the importers) merged. The rules files are unchanged by the rebase.

What changed

• importers/_rules.py moves to tilia_core/rules.py. It held TiLiA's creation rules only, and becomes the full set. Its tests move to tests/test_rules.py.
• One function per kind: marker, beat, pdf_marker (with page_count), harmony, mode, hierarchy, range_ (with the timeline's rows). Each takes the media length, the timeline's other components and the attributes to check. It returns the first broken rule as (False, reason), or (True, ""). The result is an Outcome, a 2-tuple whose others holds the ids of the other components involved: the one at the same time, the hierarchies it crosses, the next range. It is true when no rule is broken, so if rules.marker(...): reads as "keeps to the rules", and it still unpacks as ok, reason.
• The rules are the strictest of TiLiA's checks. That means validate_creation, the components' validators in set_data, the editing operations, and the format's schema. So the core refuses some values that TiLiA's importers accept:
  • a time of nan;
  • a hierarchy that starts before 0, has a level below 1, has a pre_start outside 0 to its start or a post_end outside its end to the media length, or crosses another hierarchy (as get_boundary_conflicts defines it);
  • a range whose pre_start is after its start or whose post_end is before its end, or whose joined_right isn't the next range in its row;
  • harmony and mode values that set_data refuses (step, accidental, level, display mode, font type, quality, inversion, mode type);
  • a label, comments or custom text that isn't text, and a color Qt can't read.
• Reasons are TiLiA's, word for word, where TiLiA has one, with two exceptions:
  • A negative time is shown with a minus sign (Time can't be negative. Got '-00:01.0'), not wrapped around an hour as format_media_time does today.
  • A value that isn't one has one reason for every kind: <value> is not a valid <attribute>.. Examples are nan is not a valid start., 1.5 is not a valid level. and notacolor is not a valid color.. TiLiA's importers word this differently for each kind. not_valid(attribute, value) gives the text, so the importers can give the same one for a value they can't read.
• Colors are checked without Qt. color() accepts the default (None or ""), the hex forms QColor accepts, and its names, in any case, without spaces or tabs, the way Qt reads them. The names are CSS 3's, read from webcolors (webcolors.names("css3")), plus Qt's transparent: the core keeps no copy of them. webcolors>=24.8.0 (pure Python, BSD-3-Clause, no dependencies) becomes tilia-core's second dependency; music21 already installs it. A test compares color() with QColor.isValid() for every name and for a set of edge cases, when PySide6 is installed.
• Harmony qualities, inversions and mode types come from the installed music21, as TiLiA reads them: CHORD_TYPES and modeSharpsAlter. music21 is imported only when a harmony or a mode is checked. Without it, the other rules are still checked. If none of them is broken, CantCheck is raised, naming pip install "tilia-core[harmony]".
• range_rows checks a range timeline's rows: their ids, names and colors. Two rows with the same id give There is already a row with the id Ab12Cd..

The texts for the cases TiLiA has none for were settled in TimeLineAnnotator/project-management#298 (texts for the rules that have none). That issue also settled two behaviours. Text that isn't in NFC isn't refused, since it is stored in NFC. A join to a range that isn't the next one in its row is refused, and when several ranges share the next start, a join to any of them is valid.

Fixes from review

The commits after b0ada534 fix what three code reviews found, one commit per fix. From the first review:

• The color is checked last, for every kind and for a range timeline's rows. An importer replaces a bad color with the default and keeps the row, so a bad color must not hide another broken rule.
• Copies and pickles: an Outcome keeps its reason and its others through copy, deepcopy and pickle, and CantCheck keeps its message through pickle.
• Huge integers: an integer too large for a float is not a valid time, instead of raising OverflowError.
• Levels written as floats: a hierarchy crosses another whose level is written 1.0.
• Rounding: a time is rounded to tenths before its minutes are counted, so 59.96 s shows as 01:00.0, not 00:60.0 (TimeLineAnnotator/project-management#304 fixes the same in TiLiA).
• Row ids: ROW_ID_LENGTH and ROW_ID_CHARACTERS are public, and _commit.new_row_id makes ids with them instead of its own copy.
• Tests: they no longer assert that TiLiA's creation rules accept values those rules don't take.
• A music21 that won't import, for example against a numpy it can't use, gives CantCheck, with the ImportError as its cause, instead of raising that error.
• The harmony extra is declared (harmony = ["music21>=9.1"]), so the command CantCheck names, pip install "tilia-core[harmony]", installs music21. The default install still has no music21.

From the second review:

• A bad color can't hide that a harmony or a key couldn't be checked. Without music21, a bad color gave the color's reason, not CantCheck, so an importer would have kept the component unchecked. One helper, _kept, now runs a kind's rules in order, then decides on music21, then checks the color, so every kind gets that order from one place. A step that gives a kept outcome no longer ends the checks.
• A music21 that fails to import in any way gives CantCheck, not only on ImportError.
• A hierarchy whose level is a huge integer can be crossed.
• An outcome's truth is a bool, whatever ok was given as.

From the third review:

• CantCheck's message, when music21 is found but won't import, gives the reason and the install command, and doesn't claim music21 is installed: checking a harmony needs music21, which can't be imported (ModuleNotFoundError: …): pip install "tilia-core[harmony]". A half-removed music21 (a leftover folder, a missing dependency) gives the same error, and the command fixes it. The text for a missing extra is unchanged.
• No failed import is kept for the session (a revert of the second review's 735d4945). A kept failure went stale when a missing dependency was installed, held the failed import's frames, and made the tests depend on their order. check_timeline will look music21 up once per call instead.
• A CantCheck copies and pickles whatever its error is. The error isn't carried; its text is in the message.
• An outcome's ok is a bool however it's read, including when unpacked.
• A hierarchy's start and end are compared at any integer size, as its level is.
• _kept takes a ready CantCheck, and the docstrings say that CantCheck comes before the color.
• Tests: the broken-install test checks the message; the test of _kept's private guard goes.

Tests

Run from the worktree's root after uv sync --all-packages:

• uv run --package tilia-core pytest packages/tilia-core/tests/test_rules.py: 267 passed, music21 and PySide6 installed.
• uv run --package tilia-core pytest packages/tilia-core -q: 547 passed before the rebase; 703 after it, on v1-prerelease with feat(core): set up the importers: CSV reading, results and commit #731 in; 731 with the fixes from the three reviews.
• python scripts/check_packages.py: all package checks passed, again after the rebase on Python 3.10 and 3.13, and again with the fixes from review. This is a fresh install without Qt or music21, where the harmony, mode and Qt tests skip.
• tests/test_rules.py on Python 3.10, without music21 or Qt: 207 passed, 64 skipped (before the last commit, which changed only texts).

Each rule the core adds that TiLiA's creation rules look at (times, levels, pre_start, post_end, nesting) has a test showing that those rules accept the value. Hierarchy nesting is also compared with a copy of get_boundary_conflicts for every pair of hierarchies with times from 0 to 4 and levels from 1 to 8. A wider run, levels up to 1000 and fractional times, found no disagreement either.

What removing each piece of code did to test_rules.py:

Removed	Failed
Outcome.__bool__	2
the colour names from webcolors (only transparent left)	7
the finite-number check on times	19
a hierarchy's start ≥ 0	2
a hierarchy's level ≥ 1	2
pre_start ≤ start	2
post_end ≥ end	2
hierarchies nest	11
the color check	3
CantCheck without music21 (returning OK instead)	2
a harmony's applied_to	1
the minus sign on negative times	8
joined_right is the next range	4
unique row ids	1
Qt's end of a color name at a character beyond Latin-1	1
the color checked last (marker)	2
row colors checked after ids and names	1
Outcome.__getnewargs__	3
CantCheck.__reduce__	1
an integer too large for a float	1
a level written as a float crosses	1
rounding before the minutes	2
CantCheck for a music21 that won't import	2
the harmony extra declared	1
_kept: music21 decided before the color, and a kept step doesn't end the checks	3
CantCheck for any import failure	2
the message for a music21 that won't import	2
a huge integer level can be crossed	1
bool(self[0])	1
the message with the reason and the install command	4
CantCheck.__reduce__ keeping the message, not the error	1
bool(ok) in Outcome.__new__	1
a huge integer start compared	1

Part of TimeLineAnnotator/project-management#291

🤖 Generated with Claude Code

[azfoo]

🤖 Claude

Thanks for the review. The bug and the two differences from dev are fixed in three commits, each with its test written first. The decisions behind them are on TimeLineAnnotator/project-management#291 (Anne, 2026-10-19), and the rules' contract now names dev's commits in TimeLineAnnotator/project-management#329.

• 494518cb: an integer too long to show. not_valid and the level's reason show a value through _shown. It names an integer that Python won't turn into text as "an integer too long to show", instead of raising. So rules.marker(60.0, [], {"time": 10**5000}) gives (False, "an integer too long to show is not a valid time."). The test sets Python's limit to its default, 4,300 digits, and uses 10**5000 for a marker's time and a hierarchy's level. Long values that do convert, such as a long list given as a label, still show whole.
• 3cd8e4fa: hierarchy boundaries a few ulps apart meet. _cross compares boundaries as dev's get_boundary_conflicts does since 2ceec157, through _lt, _le and _times_close (math.isclose with abs_tol=1e-9). An integer too large for a float is close only to itself. The test's copy of get_boundary_conflicts is now dev's. A new sweep compares the two on every pair of spans from 1 to 4 s at levels 1 to 3, with each boundary moved by up to 1e-13, four draws per pair. Your example, a hierarchy at 1.0 - 1e-13 next to one ending at 1.0, has its own test.
• 01eb2c75: TiLiA's added-tone qualities. ADDED_TONE_QUALITIES and split_added_tone come into the core, as dev has them since 43a61224 and 28539120. The 13 qualities are accepted, and their inversions are counted from the base quality. Each quality has a test of its base, its tone and its inversions. TiLiA is to take the list from the core once it checks with the rules.

OK.others can still be reassigned (your fourth point). It isn't changed in this push.

Tests: test_rules.py 312 passed; the package 748 passed; python scripts/check_packages.py passed on Python 3.10 and 3.11. Each new test failed before its fix: 1, 2 and 14 failures.