trackparse 0.2.1__tar.gz → 0.3.1__tar.gz

{trackparse-0.2.1 → trackparse-0.3.1}/.gitignore

@@ -25,3 +25,6 @@ rust/Cargo.lock
 .idea/
 .vscode/
 *.swp
+
+# Real-world corpora (platform data, not redistributable)
+spec/corpus/

{trackparse-0.2.1 → trackparse-0.3.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: trackparse
-Version: 0.2.1
-Summary: Spec-driven parser for music track titles: artists, feat, remixes, versions, junk, positions.
+Version: 0.3.1
+Summary: Spec-driven parser for music track titles and tracklists: artists, feat, remixes, versions, junk, positions, times.
 Project-URL: Homepage, https://github.com/4matic/trackparse
 Project-URL: Repository, https://github.com/4matic/trackparse
 Project-URL: Issues, https://github.com/4matic/trackparse/issues
@@ -51,7 +51,7 @@ doesn't recognise stays in the title, word for word.
 
 This is the Python port of [trackparse](https://github.com/4matic/trackparse). Its behaviour is
 defined by a [shared spec](https://github.com/4matic/trackparse/blob/main/spec/SPEC.md) and pinned
-by 11,891 fixtures. It passes all of them, and for every fixture input its output is byte-identical
+by 12,965 fixtures. It passes all of them, and for every fixture input its output is byte-identical
 to the JavaScript package.
 
 - Python 3.9 to 3.14
@@ -155,7 +155,7 @@ SPEC_VERSION, __version__
 
 | Option | Default | |
 |---|---|---|
-| `mode` | `"auto"` | `"clean"`, `"youtube"`, `"filename"`, or `"auto"` to detect from the string |
+| `mode` | `"auto"` | `"clean"`, `"youtube"`, `"filename"`, `"tracklist"`, or `"auto"` to detect from the string |
 | `uploader` | `None` | YouTube channel name, used as the artist when there's no separator (`- Topic` and `VEVO` are dropped) |
 | `known_artists` | `()` | Names that are never split. There is no built-in list |
 | `split_and` | `"auto"` | `"auto"` splits on `and` only after a comma (`A, B and C`), so `Simon and Garfunkel` stays whole. Also `"always"`, `"never"` |
@@ -196,7 +196,7 @@ the defaults. Passing something that isn't a `str` raises `TypeError`.
 | Attribute | Type | |
 |---|---|---|
 | `input` | `str` | The original string, untouched |
-| `mode` | `"clean" \| "youtube" \| "filename"` | Resolved mode |
+| `mode` | `"clean" \| "youtube" \| "filename" \| "tracklist"` | Resolved mode |
 | `position` | `Position \| None` | Track number: `Position(raw='01', number=1)` |
 | `timestamp` | `Timestamp \| None` | Leading cue time: `[12:34]` gives `Timestamp(raw='12:34', seconds=754)` |
 | `artists` | `tuple[Artist, ...]` | Primary, featured and producer credits. Remixers live in `versions` |
@@ -238,8 +238,8 @@ Version types, junk kinds and warnings are listed in the
 Every result class has `to_dict()`, which returns plain dicts and lists matching
 [`parsed-track.schema.json`](https://github.com/4matic/trackparse/blob/main/spec/schema/parsed-track.schema.json)
 (`fullTitle`, `unknownArtist`, ...). With `json.dumps(track.to_dict(), separators=(",", ":"),
-ensure_ascii=False)` the bytes are the same as `JSON.stringify(parse(s))` in JS. The `from_dict()`
-classmethod goes the other way:
+ensure_ascii=False)` the bytes are the same as `JSON.stringify(parse(s))` in JS. The single-track classes
+(`ParsedTrack`, `Artist`, ...) also have a `from_dict()` classmethod that goes the other way:
 
 ```python
 ParsedTrack.from_dict(track.to_dict()) == track  # True
@@ -338,6 +338,7 @@ released together and always share one version number.
 | `youtube` | Video titles, scrobbles | Pipe segments, `"Title" by Artist`, `Artist: "Title"`, unspaced dashes, trailing junk, uploader fallback |
 | `filename` | Files | Strips the extension, `_` becomes a space, `01-Track` numbering |
 | `auto` | Anything | `filename` for known extensions, `youtube` when it sees junk, pipes or platform suffixes, `clean` otherwise |
+| `tracklist` | One line of a tracklist | The first spaced dash always separates; `_-_` too. Never picked by `auto` |
 
 ```python
 t = parse('"Numb" by Linkin Park', mode="youtube")
@@ -352,12 +353,124 @@ parse("Shelter", mode="youtube", uploader="Porter Robinson").artists
 # (Artist(name='Porter Robinson', role='primary', joiner=None, source='artist'),)
 ```
 
+## Tracklists
+
+`trackparse.tracklist` parses a whole tracklist, one entry per line, and checks it. Each entry
+keeps its line exactly as written plus its own line ending, so `"".join(e.raw + e.eol for e in
+tl.entries)` is always the input, CRLF or not.
+
+```python
+from trackparse.tracklist import apply_edits, parse_tracklist
+
+text = "\r\n".join(
+    [
+        "Hour 2",
+        "48:20 Noisia - Stigma",
+        "52:47 Mefjus & Kasra - Bandwagon (Phace Remix)",
+        "56:05 Black Sun Empire - ID",
+        "59:31 Alix Perez - Fade Away",
+        "01:03:10 Interview with Hybris",
+        "01:07:44 Imanu - Sacrifice",
+        "00:11:02 Current Value feat. Teddy Killerz - Payload",  # typo for 01:11:02
+        "01:15:36 Hybris - Spinning Top",
+    ]
+)
+
+tl = parse_tracklist(text)
+
+[e.kind for e in tl.entries]
+# ['header', 'track', 'track', 'track', 'track', 'marker', 'track', 'track', 'track']
+
+e = tl.entries[2]
+e.time  # TimeValue(raw='52:47', seconds=3167)
+e.parts  # Parts(lead='', time='52:47', gap=' ', rest='Mefjus & Kasra - Bandwagon (Phace Remix)')
+[a.name for a in e.track.artists], e.track.title, e.track.versions[0].type
+# (['Mefjus', 'Kasra'], 'Bandwagon', 'remix')
+tl.entries[3].track.flags.unknown_title  # True (the ID)
+
+tl.warnings
+# (TracklistWarning(code='no-start-at-zero', line=2, severity='info', suggestion=None),
+#  TracklistWarning(code='time-out-of-order', line=8, severity='warning',
+#                   suggestion=Suggestion(line=8, raw='01:11:02', seconds=4262)))
+
+tl.stats
+# Stats(lines=9, tracks=7, markers=1, timed=8, first_time=2900, last_time=4536)
+```
+
+The suggestion exists because exactly one time, one digit away from `00:11:02`, fits between its
+neighbours. With several candidates or none, `suggestion` is `None`.
+
+`apply_edits` takes a list of dicts with the spec's keys (`op`, `line`, `seconds`, `lines`, `from`,
+`after`, `text`, `rest`) and only rewrites the lines they name:
+
+```python
+fix = tl.warnings[1].suggestion
+r = apply_edits(
+    text,
+    [
+        {"op": "set-time", "line": fix.line, "seconds": fix.seconds},
+        {"op": "shift", "seconds": 45, "from": 5},
+    ],
+)
+
+r.changed  # (5, 6, 7, 8, 9)
+r.warnings  # (EditWarning(code='style-upgraded', edit=1, line=5),)
+r.text.split("\r\n")[4]  # '01:00:16 Alix Perez - Fade Away'  (was 59:31)
+
+apply_edits(text, [{"op": "shift", "seconds": -3000, "lines": [2, 3]}]).warnings
+# (EditWarning(code='time-clamped', edit=0, line=2),)
+```
+
+A rewritten time keeps its line's style: `52:47` stays `MM:SS`, and a time that crosses the hour
+gets hours like the rest of the list, with a `style-upgraded` warning. A bad edit changes nothing
+and warns `edit-invalid`. Neither function raises on `str` input.
+
+```python
+parse_tracklist(text, *, mode="tracklist", known_artists=(), keywords=None, split_and="auto",
+                audio_seconds=None, marker_words=()) -> Tracklist
+apply_edits(text, edits, *, <same options>) -> EditResult
+```
+
+| Result | Fields |
+|---|---|
+| `Tracklist` | `spec_version`, `entries`, `warnings`, `stats` |
+| `TracklistEntry` | `line` (1-based), `kind` (`track`, `marker`, `header`, `link`, `note`, `blank`), `eol`, `raw`, `parts`, `time`, `track` (`ParsedTrack` or `None`) |
+| `Parts` | `lead`, `time`, `gap`, `rest`, joined they give `raw` |
+| `TracklistWarning` | `code`, `line`, `severity` (`info` or `warning`), `suggestion` |
+| `TimeValue` | `raw`, `seconds` (`entry.time`, or `None` on untimed lines) |
+| `Suggestion` | `line`, `raw`, `seconds` (`warning.suggestion`, or `None`) |
+| `Stats` | `lines`, `tracks`, `markers`, `timed`, `first_time`, `last_time` |
+| `EditResult` | `text`, `changed`, `warnings` (`EditWarning(code, edit, line)`) |
+
+Warning codes: `time-missing`, `time-out-of-order`, `time-duplicate`, `no-start-at-zero`,
+`time-after-audio-end` (needs `audio_seconds`), `invalid-time`, `position-gap`,
+`position-duplicate`, `line-unparsed`. Edits: `set-time {line, seconds}`, `shift {seconds, lines? | from?}`
+(all timed lines when neither is given), `sort-by-time {}`, `set-rest {line, rest}`,
+`insert {after, text}` (`after: 0` inserts at the top), `delete {line}`. The
+[main README](https://github.com/4matic/trackparse#tracklist-api) explains each one.
+`to_dict()` gives the camelCase JSON from
+[`tracklist.schema.json`](https://github.com/4matic/trackparse/blob/main/spec/schema/tracklist.schema.json),
+byte-identical to the JS package's output.
+
+Every line is parsed with `mode="tracklist"`, where the first spaced dash always separates artist
+and title. `parse()` accepts it too:
+
+```python
+parse("Electrosoul System - Liquid Metal").junk
+# (Junk(raw='Liquid Metal', kind='genre'),)
+parse("Electrosoul System - Liquid Metal", mode="tracklist").title
+# 'Liquid Metal'
+```
+
 ## Typing
 
 The package ships `py.typed` and passes `mypy --strict`. `ParsedTrack`, `Artist`, `Version`,
-`Junk`, `Flags`, `Position` and `Timestamp` are frozen dataclasses with snake_case attributes.
+`Junk`, `Flags`, `Position` and `Timestamp` are frozen dataclasses with snake_case attributes, and
+so are the tracklist results in `trackparse.tracklist`.
 Sequences are tuples, so results are immutable and hashable and can go in sets or be used as dict
-keys. Option dicts have `TypedDict` types (`ParseOptions`, `KeywordOptions`, `FormatOptions`).
+keys. Option dicts have `TypedDict` types (`ParseOptions`, `KeywordOptions`, `FormatOptions`);
+tracklist edits are plain dicts. `trackparse.tracklist` also exports the `Literal` aliases
+`EntryKind`, `Eol`, `Severity`, `TracklistWarningCode` and `EditWarningCode`.
 
 ## Development
 

{trackparse-0.2.1 → trackparse-0.3.1}/README.md

@@ -19,7 +19,7 @@ doesn't recognise stays in the title, word for word.
 
 This is the Python port of [trackparse](https://github.com/4matic/trackparse). Its behaviour is
 defined by a [shared spec](https://github.com/4matic/trackparse/blob/main/spec/SPEC.md) and pinned
-by 11,891 fixtures. It passes all of them, and for every fixture input its output is byte-identical
+by 12,965 fixtures. It passes all of them, and for every fixture input its output is byte-identical
 to the JavaScript package.
 
 - Python 3.9 to 3.14
@@ -123,7 +123,7 @@ SPEC_VERSION, __version__
 
 | Option | Default | |
 |---|---|---|
-| `mode` | `"auto"` | `"clean"`, `"youtube"`, `"filename"`, or `"auto"` to detect from the string |
+| `mode` | `"auto"` | `"clean"`, `"youtube"`, `"filename"`, `"tracklist"`, or `"auto"` to detect from the string |
 | `uploader` | `None` | YouTube channel name, used as the artist when there's no separator (`- Topic` and `VEVO` are dropped) |
 | `known_artists` | `()` | Names that are never split. There is no built-in list |
 | `split_and` | `"auto"` | `"auto"` splits on `and` only after a comma (`A, B and C`), so `Simon and Garfunkel` stays whole. Also `"always"`, `"never"` |
@@ -164,7 +164,7 @@ the defaults. Passing something that isn't a `str` raises `TypeError`.
 | Attribute | Type | |
 |---|---|---|
 | `input` | `str` | The original string, untouched |
-| `mode` | `"clean" \| "youtube" \| "filename"` | Resolved mode |
+| `mode` | `"clean" \| "youtube" \| "filename" \| "tracklist"` | Resolved mode |
 | `position` | `Position \| None` | Track number: `Position(raw='01', number=1)` |
 | `timestamp` | `Timestamp \| None` | Leading cue time: `[12:34]` gives `Timestamp(raw='12:34', seconds=754)` |
 | `artists` | `tuple[Artist, ...]` | Primary, featured and producer credits. Remixers live in `versions` |
@@ -206,8 +206,8 @@ Version types, junk kinds and warnings are listed in the
 Every result class has `to_dict()`, which returns plain dicts and lists matching
 [`parsed-track.schema.json`](https://github.com/4matic/trackparse/blob/main/spec/schema/parsed-track.schema.json)
 (`fullTitle`, `unknownArtist`, ...). With `json.dumps(track.to_dict(), separators=(",", ":"),
-ensure_ascii=False)` the bytes are the same as `JSON.stringify(parse(s))` in JS. The `from_dict()`
-classmethod goes the other way:
+ensure_ascii=False)` the bytes are the same as `JSON.stringify(parse(s))` in JS. The single-track classes
+(`ParsedTrack`, `Artist`, ...) also have a `from_dict()` classmethod that goes the other way:
 
 ```python
 ParsedTrack.from_dict(track.to_dict()) == track  # True
@@ -306,6 +306,7 @@ released together and always share one version number.
 | `youtube` | Video titles, scrobbles | Pipe segments, `"Title" by Artist`, `Artist: "Title"`, unspaced dashes, trailing junk, uploader fallback |
 | `filename` | Files | Strips the extension, `_` becomes a space, `01-Track` numbering |
 | `auto` | Anything | `filename` for known extensions, `youtube` when it sees junk, pipes or platform suffixes, `clean` otherwise |
+| `tracklist` | One line of a tracklist | The first spaced dash always separates; `_-_` too. Never picked by `auto` |
 
 ```python
 t = parse('"Numb" by Linkin Park', mode="youtube")
@@ -320,12 +321,124 @@ parse("Shelter", mode="youtube", uploader="Porter Robinson").artists
 # (Artist(name='Porter Robinson', role='primary', joiner=None, source='artist'),)
 ```
 
+## Tracklists
+
+`trackparse.tracklist` parses a whole tracklist, one entry per line, and checks it. Each entry
+keeps its line exactly as written plus its own line ending, so `"".join(e.raw + e.eol for e in
+tl.entries)` is always the input, CRLF or not.
+
+```python
+from trackparse.tracklist import apply_edits, parse_tracklist
+
+text = "\r\n".join(
+    [
+        "Hour 2",
+        "48:20 Noisia - Stigma",
+        "52:47 Mefjus & Kasra - Bandwagon (Phace Remix)",
+        "56:05 Black Sun Empire - ID",
+        "59:31 Alix Perez - Fade Away",
+        "01:03:10 Interview with Hybris",
+        "01:07:44 Imanu - Sacrifice",
+        "00:11:02 Current Value feat. Teddy Killerz - Payload",  # typo for 01:11:02
+        "01:15:36 Hybris - Spinning Top",
+    ]
+)
+
+tl = parse_tracklist(text)
+
+[e.kind for e in tl.entries]
+# ['header', 'track', 'track', 'track', 'track', 'marker', 'track', 'track', 'track']
+
+e = tl.entries[2]
+e.time  # TimeValue(raw='52:47', seconds=3167)
+e.parts  # Parts(lead='', time='52:47', gap=' ', rest='Mefjus & Kasra - Bandwagon (Phace Remix)')
+[a.name for a in e.track.artists], e.track.title, e.track.versions[0].type
+# (['Mefjus', 'Kasra'], 'Bandwagon', 'remix')
+tl.entries[3].track.flags.unknown_title  # True (the ID)
+
+tl.warnings
+# (TracklistWarning(code='no-start-at-zero', line=2, severity='info', suggestion=None),
+#  TracklistWarning(code='time-out-of-order', line=8, severity='warning',
+#                   suggestion=Suggestion(line=8, raw='01:11:02', seconds=4262)))
+
+tl.stats
+# Stats(lines=9, tracks=7, markers=1, timed=8, first_time=2900, last_time=4536)
+```
+
+The suggestion exists because exactly one time, one digit away from `00:11:02`, fits between its
+neighbours. With several candidates or none, `suggestion` is `None`.
+
+`apply_edits` takes a list of dicts with the spec's keys (`op`, `line`, `seconds`, `lines`, `from`,
+`after`, `text`, `rest`) and only rewrites the lines they name:
+
+```python
+fix = tl.warnings[1].suggestion
+r = apply_edits(
+    text,
+    [
+        {"op": "set-time", "line": fix.line, "seconds": fix.seconds},
+        {"op": "shift", "seconds": 45, "from": 5},
+    ],
+)
+
+r.changed  # (5, 6, 7, 8, 9)
+r.warnings  # (EditWarning(code='style-upgraded', edit=1, line=5),)
+r.text.split("\r\n")[4]  # '01:00:16 Alix Perez - Fade Away'  (was 59:31)
+
+apply_edits(text, [{"op": "shift", "seconds": -3000, "lines": [2, 3]}]).warnings
+# (EditWarning(code='time-clamped', edit=0, line=2),)
+```
+
+A rewritten time keeps its line's style: `52:47` stays `MM:SS`, and a time that crosses the hour
+gets hours like the rest of the list, with a `style-upgraded` warning. A bad edit changes nothing
+and warns `edit-invalid`. Neither function raises on `str` input.
+
+```python
+parse_tracklist(text, *, mode="tracklist", known_artists=(), keywords=None, split_and="auto",
+                audio_seconds=None, marker_words=()) -> Tracklist
+apply_edits(text, edits, *, <same options>) -> EditResult
+```
+
+| Result | Fields |
+|---|---|
+| `Tracklist` | `spec_version`, `entries`, `warnings`, `stats` |
+| `TracklistEntry` | `line` (1-based), `kind` (`track`, `marker`, `header`, `link`, `note`, `blank`), `eol`, `raw`, `parts`, `time`, `track` (`ParsedTrack` or `None`) |
+| `Parts` | `lead`, `time`, `gap`, `rest`, joined they give `raw` |
+| `TracklistWarning` | `code`, `line`, `severity` (`info` or `warning`), `suggestion` |
+| `TimeValue` | `raw`, `seconds` (`entry.time`, or `None` on untimed lines) |
+| `Suggestion` | `line`, `raw`, `seconds` (`warning.suggestion`, or `None`) |
+| `Stats` | `lines`, `tracks`, `markers`, `timed`, `first_time`, `last_time` |
+| `EditResult` | `text`, `changed`, `warnings` (`EditWarning(code, edit, line)`) |
+
+Warning codes: `time-missing`, `time-out-of-order`, `time-duplicate`, `no-start-at-zero`,
+`time-after-audio-end` (needs `audio_seconds`), `invalid-time`, `position-gap`,
+`position-duplicate`, `line-unparsed`. Edits: `set-time {line, seconds}`, `shift {seconds, lines? | from?}`
+(all timed lines when neither is given), `sort-by-time {}`, `set-rest {line, rest}`,
+`insert {after, text}` (`after: 0` inserts at the top), `delete {line}`. The
+[main README](https://github.com/4matic/trackparse#tracklist-api) explains each one.
+`to_dict()` gives the camelCase JSON from
+[`tracklist.schema.json`](https://github.com/4matic/trackparse/blob/main/spec/schema/tracklist.schema.json),
+byte-identical to the JS package's output.
+
+Every line is parsed with `mode="tracklist"`, where the first spaced dash always separates artist
+and title. `parse()` accepts it too:
+
+```python
+parse("Electrosoul System - Liquid Metal").junk
+# (Junk(raw='Liquid Metal', kind='genre'),)
+parse("Electrosoul System - Liquid Metal", mode="tracklist").title
+# 'Liquid Metal'
+```
+
 ## Typing
 
 The package ships `py.typed` and passes `mypy --strict`. `ParsedTrack`, `Artist`, `Version`,
-`Junk`, `Flags`, `Position` and `Timestamp` are frozen dataclasses with snake_case attributes.
+`Junk`, `Flags`, `Position` and `Timestamp` are frozen dataclasses with snake_case attributes, and
+so are the tracklist results in `trackparse.tracklist`.
 Sequences are tuples, so results are immutable and hashable and can go in sets or be used as dict
-keys. Option dicts have `TypedDict` types (`ParseOptions`, `KeywordOptions`, `FormatOptions`).
+keys. Option dicts have `TypedDict` types (`ParseOptions`, `KeywordOptions`, `FormatOptions`);
+tracklist edits are plain dicts. `trackparse.tracklist` also exports the `Literal` aliases
+`EntryKind`, `Eol`, `Severity`, `TracklistWarningCode` and `EditWarningCode`.
 
 ## Development
 

{trackparse-0.2.1 → trackparse-0.3.1}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "trackparse"
-version = "0.2.1"
-description = "Spec-driven parser for music track titles: artists, feat, remixes, versions, junk, positions."
+version = "0.3.1"
+description = "Spec-driven parser for music track titles and tracklists: artists, feat, remixes, versions, junk, positions, times."
 readme = "README.md"
 requires-python = ">=3.9"
 license = "MIT"

{trackparse-0.2.1 → trackparse-0.3.1}/src/trackparse/__init__.py

@@ -33,7 +33,7 @@ from .types import (
     Warning,
 )
 
-__version__ = "0.2.1"  # x-release-please-version
+__version__ = "0.3.1"  # x-release-please-version
 
 __all__ = [
     "SPEC_VERSION",

{trackparse-0.2.1 → trackparse-0.3.1}/src/trackparse/_data.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 
 from typing import Any
 
-SPEC_VERSION = "0.2.1"  # x-release-please-version
+SPEC_VERSION = "0.3.1"  # x-release-please-version
 
 # spec/data/descriptors.json
 DESCRIPTORS_DATA: dict[str, Any] = {
@@ -179,6 +179,23 @@ GENRES_DATA: dict[str, Any] = {
     ],
 }
 
+# spec/data/header-words.json
+HEADER_WORDS_DATA: dict[str, Any] = {
+    "words": [
+        "tracklist",
+        "setlist",
+        "playlist",
+        "part",
+        "hour",
+        "cd",
+        "disc",
+        "side",
+        "chapter",
+        "segment",
+        "set",
+    ],
+}
+
 # spec/data/joiners.json
 JOINERS_DATA: dict[str, Any] = {
     "spaced": [
@@ -333,6 +350,33 @@ JUNK_DATA: dict[str, Any] = {
     ],
 }
 
+# spec/data/marker-words.json
+MARKER_WORDS_DATA: dict[str, Any] = {
+    "words": [
+        "intro",
+        "outro",
+        "break",
+        "interlude",
+        "intermission",
+        "jingle",
+        "ad",
+        "advert",
+        "advertisement",
+        "talk",
+        "interview",
+        "speech",
+        "announcement",
+        "shoutout",
+        "shout-out",
+        "pause",
+        "start",
+        "end",
+        "silence",
+        "applause",
+        "skit",
+    ],
+}
+
 # spec/data/no-split-before.json
 NO_SPLIT_BEFORE_DATA: dict[str, Any] = {
     "words": [

trackparse-0.3.1/src/trackparse/_digits.py

@@ -0,0 +1,27 @@
+"""ASCII digit scanning shared by R4.1 (_prefix.py) and the tracklist time scanner (R13.2)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ._words import char_at, is_digit
+
+
+def digit_run(s: str, frm: int) -> int:
+    """Length of the run of ASCII digits starting at ``frm``."""
+    i = frm
+    while is_digit(char_at(s, i)):
+        i += 1
+    return i - frm
+
+
+def two_digits_up_to_59(s: str, at: int) -> Optional[int]:
+    """Exactly two digits (not followed by a third) with a value of at most 59, else None."""
+    if (
+        not is_digit(char_at(s, at))
+        or not is_digit(char_at(s, at + 1))
+        or is_digit(char_at(s, at + 2))
+    ):
+        return None
+    n = int(s[at : at + 2])
+    return n if n <= 59 else None

{trackparse-0.2.1 → trackparse-0.3.1}/src/trackparse/_mode.py

@@ -128,7 +128,8 @@ def prelude(normalized: str, requested: object, ctx: Ctx) -> Prelude:
     s = _strip_platform_suffixes(normalized, ctx, junk)
     had_platform = len(junk) > 0
 
-    if requested in ("clean", "youtube", "filename"):
+    # R13.6: tracklist is explicit only; R2.3/R2.4 do not run.
+    if requested in ("clean", "youtube", "filename", "tracklist"):
         mode = str(requested)
     elif _extension_of(s, ctx):
         mode = "filename"

{trackparse-0.2.1 → trackparse-0.3.1}/src/trackparse/_parser.py

@@ -4,15 +4,15 @@ from __future__ import annotations
 
 from collections.abc import Mapping, Sequence
 from dataclasses import replace
-from typing import Any, Optional, cast
+from typing import Any, NamedTuple, Optional, cast
 
 from ._artists import parse_artist_side
 from ._assemble import by_pos, dedup_artists, full_title_of, to_version
 from ._context import Ctx, warn
-from ._mode import Piece, prelude
+from ._mode import Piece, Prelude, prelude
 from ._normalize import normalize
-from ._prefix import strip_prefixes
-from ._scanner import Skel, scan, trim_skel
+from ._prefix import PrefixResult, strip_prefixes
+from ._scanner import Skel, scan, split_at_spaced_dashes, trim_skel
 from ._separator import find_separator
 from ._tables import Tables, js_entries, tables_for
 from ._title import Extracted, add_peeled, parse_title_side
@@ -74,7 +74,20 @@ def _empty_track(inp: str, mode: str) -> ParsedTrack:
     )
 
 
-def _run(inp: str, options: Mapping[str, Any], t: Tables) -> ParsedTrack:
+class _Staged(NamedTuple):
+    """The R1, R2 and R4 stage of ``_run``, kept so the tracklist probe's work is not redone."""
+
+    inp: str
+    options: Mapping[str, Any]
+    ctx: Ctx
+    pre: Prelude
+    #: None when the input is empty after R1 (R9.5).
+    prefix: Optional[PrefixResult]
+    #: The skeleton after R4; None when the input is empty after R1.
+    working: Optional[Skel]
+
+
+def _stage(inp: str, options: Mapping[str, Any], t: Tables) -> _Staged:
     ctx = Ctx(t, options)
     norm = normalize(inp)
     requested = options.get("mode")
@@ -82,11 +95,25 @@ def _run(inp: str, options: Mapping[str, Any], t: Tables) -> ParsedTrack:
         requested = "auto"
     pre = prelude(norm, requested, ctx)
     if len(norm) == 0:
-        return _empty_track(inp, pre.mode)  # R9.5
+        return _Staged(inp, options, ctx, pre, None, None)  # R9.5
 
     # R4
     prefix = strip_prefixes(pre.working.text, pre.working.base, pre.mode, ctx)
     working = _skel_of(Piece(prefix.rest, prefix.base), ctx)
+    return _Staged(inp, options, ctx, pre, prefix, working)
+
+
+def _run(
+    inp: str, options: Mapping[str, Any], t: Tables, list_context: bool = False
+) -> ParsedTrack:
+    return _finish(_stage(inp, options, t), list_context)
+
+
+def _finish(st: _Staged, list_context: bool) -> ParsedTrack:
+    """R6–R9 on a staged input. Each staged value is finished at most once."""
+    inp, options, ctx, pre, prefix, working = st
+    if prefix is None or working is None:
+        return _empty_track(inp, pre.mode)  # R9.5
 
     out = Extracted()
     artist_skel: Optional[Skel]
@@ -96,7 +123,9 @@ def _run(inp: str, options: Mapping[str, Any], t: Tables) -> ParsedTrack:
         title_skel = _skel_of(pre.pipe_title, ctx)
         relaxed = artist_skel is not None
     else:
-        sep = find_separator(working, pre.mode, _uploader_skel(options.get("uploader")), ctx)
+        sep = find_separator(
+            working, pre.mode, _uploader_skel(options.get("uploader")), ctx, list_context
+        )
         add_peeled(out, sep.peeled)
         artist_skel = sep.artist
         title_skel = sep.title
@@ -141,6 +170,54 @@ def _run(inp: str, options: Mapping[str, Any], t: Tables) -> ParsedTrack:
     )
 
 
+class LineProbe:
+    """Facts about a line's prefix and separator search, for the tracklist module (R13.4.2,
+    R13.5). :meth:`finish` completes the parse from the same stage, so a probed line is not
+    normalized twice."""
+
+    __slots__ = ("_staged", "empty", "position", "spaced_dash")
+
+    def __init__(self, staged: _Staged) -> None:
+        self._staged = staged
+        prefix = staged.prefix
+        working = staged.working
+        #: R4.2 took a position.
+        self.position = prefix is not None and prefix.position is not None
+        #: The skeleton R6 searches (after R2 and R4) has a spaced dash (R6.1).
+        self.spaced_dash = (
+            working is not None
+            and staged.pre.pipe_title is None
+            and len(split_at_spaced_dashes(working, True)) >= 2
+        )
+        #: The input is empty after R1.
+        self.empty = working is None
+
+    def finish(self, list_context: bool) -> ParsedTrack:
+        """The parse of the probed input (R6–R9 only; call at most once)."""
+        return _finish(self._staged, list_context)
+
+
+def _probe(inp: str, options: Mapping[str, Any], t: Tables) -> LineProbe:
+    """R1, R2 and R4 only, as ``_run`` does them: no artist/title parsing."""
+    return LineProbe(_stage(inp, options, t))
+
+
+class ListParser:
+    """Internal (not exported from the package root): parsing hooks for the tracklist module,
+    with the base options compiled once."""
+
+    def __init__(self, options: Mapping[str, Any]) -> None:
+        self._options = _safe_options(options)
+        self._tables = tables_for(self._options.get("keywords"))
+
+    def parse(self, inp: str, list_context: bool) -> ParsedTrack:
+        """``parse`` with the R13.4.2 list-context flag (it only matters in tracklist mode)."""
+        return _run(inp, self._options, self._tables, list_context)
+
+    def probe(self, inp: str) -> LineProbe:
+        return _probe(inp, self._options, self._tables)
+
+
 def _run_artists(inp: str, options: Mapping[str, Any], t: Tables) -> list[Artist]:
     ctx = Ctx(t, options)
     norm = normalize(inp)

{trackparse-0.2.1 → trackparse-0.3.1}/src/trackparse/_prefix.py

@@ -5,8 +5,10 @@ from __future__ import annotations
 from typing import NamedTuple, Optional
 
 from ._context import Ctx, match_known_at
+from ._digits import digit_run as _digit_run
+from ._digits import two_digits_up_to_59 as _two_digits_up_to_59
 from ._scanner import has_spaced_dash, scan
-from ._words import char_at, is_digit
+from ._words import char_at
 
 
 class PrefixResult(NamedTuple):
@@ -17,24 +19,6 @@ class PrefixResult(NamedTuple):
     position: Optional[tuple[str, int]]
 
 
-def _digit_run(s: str, frm: int) -> int:
-    i = frm
-    while is_digit(char_at(s, i)):
-        i += 1
-    return i - frm
-
-
-def _two_digits_up_to_59(s: str, at: int) -> Optional[int]:
-    if (
-        not is_digit(char_at(s, at))
-        or not is_digit(char_at(s, at + 1))
-        or is_digit(char_at(s, at + 2))
-    ):
-        return None
-    n = int(s[at : at + 2])
-    return n if n <= 59 else None
-
-
 class _TimeMatch(NamedTuple):
     raw: str
     seconds: int