trackparse 0.2.1__tar.gz → 0.3.2__tar.gz

{trackparse-0.2.1 → trackparse-0.3.2}/.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.2}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.5
 Name: trackparse
-Version: 0.2.1
-Summary: Spec-driven parser for music track titles: artists, feat, remixes, versions, junk, positions.
-Project-URL: Homepage, https://github.com/4matic/trackparse
+Version: 0.3.2
+Summary: Spec-driven parser for music track titles and tracklists: artists, feat, remixes, versions, junk, positions, times.
+Project-URL: Homepage, https://4matic.github.io/trackparse/
+Project-URL: Documentation, https://4matic.github.io/trackparse/guides/python/
 Project-URL: Repository, https://github.com/4matic/trackparse
 Project-URL: Issues, https://github.com/4matic/trackparse/issues
 Project-URL: Changelog, https://github.com/4matic/trackparse/blob/main/python/CHANGELOG.md
@@ -37,6 +38,8 @@ Description-Content-Type: text/markdown
 [![python](https://img.shields.io/github/actions/workflow/status/4matic/trackparse/python.yml?branch=main&label=tests&logo=github)](https://github.com/4matic/trackparse/actions/workflows/python.yml)
 [![license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/4matic/trackparse/blob/main/LICENSE)
 
+**[Documentation](https://4matic.github.io/trackparse/)** · **[Python guide](https://4matic.github.io/trackparse/guides/python/)** · **[Playground](https://4matic.github.io/trackparse/playground/)**
+
 **Turn messy track names into structured data: who made it, who's featured, who remixed it, and
 what's just noise.**
 
@@ -51,7 +54,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 +158,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 +199,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` |
@@ -229,7 +232,7 @@ parse("Queen - Bohemian Rhapsody (Live at Wembley 1986)").versions[0]
 ```
 
 Version types, junk kinds and warnings are listed in the
-[main README](https://github.com/4matic/trackparse#api) and typed as `Literal` aliases
+[API reference](https://4matic.github.io/trackparse/reference/parse/) and typed as `Literal` aliases
 (`VersionType`, `JunkKind`, `Warning`, `ArtistRole`, `ArtistSource`, `Mode`, `ModeOption`,
 `VersionDelimiter`).
 
@@ -238,8 +241,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 +341,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 +356,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
+[Tracklist API reference](https://4matic.github.io/trackparse/reference/tracklist/) 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
 
@@ -379,8 +495,11 @@ same spec rule IDs. Behaviour changes start in the spec, not here: see
 
 ## Links
 
+- [Documentation](https://4matic.github.io/trackparse/), with a [Python guide](https://4matic.github.io/trackparse/guides/python/) and a
+  [playground](https://4matic.github.io/trackparse/playground/) that runs the parser in your browser
 - [Spec](https://github.com/4matic/trackparse/blob/main/spec/SPEC.md)
-- [Project README](https://github.com/4matic/trackparse#readme), with a table of real outputs
+- [Project README](https://github.com/4matic/trackparse#readme)
+- [GitHub repository](https://github.com/4matic/trackparse)
 - [Changelog](https://github.com/4matic/trackparse/blob/main/python/CHANGELOG.md)
 - [npm package](https://www.npmjs.com/package/trackparse)
 

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

@@ -5,6 +5,8 @@
 [![python](https://img.shields.io/github/actions/workflow/status/4matic/trackparse/python.yml?branch=main&label=tests&logo=github)](https://github.com/4matic/trackparse/actions/workflows/python.yml)
 [![license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/4matic/trackparse/blob/main/LICENSE)
 
+**[Documentation](https://4matic.github.io/trackparse/)** · **[Python guide](https://4matic.github.io/trackparse/guides/python/)** · **[Playground](https://4matic.github.io/trackparse/playground/)**
+
 **Turn messy track names into structured data: who made it, who's featured, who remixed it, and
 what's just noise.**
 
@@ -19,7 +21,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 +125,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 +166,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` |
@@ -197,7 +199,7 @@ parse("Queen - Bohemian Rhapsody (Live at Wembley 1986)").versions[0]
 ```
 
 Version types, junk kinds and warnings are listed in the
-[main README](https://github.com/4matic/trackparse#api) and typed as `Literal` aliases
+[API reference](https://4matic.github.io/trackparse/reference/parse/) and typed as `Literal` aliases
 (`VersionType`, `JunkKind`, `Warning`, `ArtistRole`, `ArtistSource`, `Mode`, `ModeOption`,
 `VersionDelimiter`).
 
@@ -206,8 +208,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 +308,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 +323,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
+[Tracklist API reference](https://4matic.github.io/trackparse/reference/tracklist/) 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
 
@@ -347,8 +462,11 @@ same spec rule IDs. Behaviour changes start in the spec, not here: see
 
 ## Links
 
+- [Documentation](https://4matic.github.io/trackparse/), with a [Python guide](https://4matic.github.io/trackparse/guides/python/) and a
+  [playground](https://4matic.github.io/trackparse/playground/) that runs the parser in your browser
 - [Spec](https://github.com/4matic/trackparse/blob/main/spec/SPEC.md)
-- [Project README](https://github.com/4matic/trackparse#readme), with a table of real outputs
+- [Project README](https://github.com/4matic/trackparse#readme)
+- [GitHub repository](https://github.com/4matic/trackparse)
 - [Changelog](https://github.com/4matic/trackparse/blob/main/python/CHANGELOG.md)
 - [npm package](https://www.npmjs.com/package/trackparse)
 

{trackparse-0.2.1 → trackparse-0.3.2}/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.2"
+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"
@@ -44,7 +44,8 @@ classifiers = [
 dependencies = []
 
 [project.urls]
-Homepage = "https://github.com/4matic/trackparse"
+Homepage = "https://4matic.github.io/trackparse/"
+Documentation = "https://4matic.github.io/trackparse/guides/python/"
 Repository = "https://github.com/4matic/trackparse"
 Issues = "https://github.com/4matic/trackparse/issues"
 Changelog = "https://github.com/4matic/trackparse/blob/main/python/CHANGELOG.md"

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

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

{trackparse-0.2.1 → trackparse-0.3.2}/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.2"  # 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.2/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.2}/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"