trackparse 0.2.0__py3-none-any.whl

trackparse/_prefix.py

@@ -0,0 +1,143 @@
+"""R4: leading timestamp and track-position prefixes."""
+
+from __future__ import annotations
+
+from typing import NamedTuple, Optional
+
+from ._context import Ctx, match_known_at
+from ._scanner import has_spaced_dash, scan
+from ._words import char_at, is_digit
+
+
+class PrefixResult(NamedTuple):
+    rest: str
+    #: Absolute offset of ``rest`` (prefixes are ASCII, so code points == UTF-16 units).
+    base: int
+    timestamp: Optional[tuple[str, int]]
+    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
+    end: int
+
+
+def _match_time(s: str, at: int) -> Optional[_TimeMatch]:
+    """``H:MM:SS``, ``HH:MM:SS``, ``M:SS``, ``MM:SS`` starting at ``at``."""
+    lead = _digit_run(s, at)
+    if lead < 1 or lead > 2 or char_at(s, at + lead) != ":":
+        return None
+    first = int(s[at : at + lead])
+    mid = _two_digits_up_to_59(s, at + lead + 1)
+    if mid is None:
+        return None
+    after_mid = at + lead + 3
+    if char_at(s, after_mid) == ":":
+        sec = _two_digits_up_to_59(s, after_mid + 1)
+        if sec is not None:
+            end = after_mid + 3
+            return _TimeMatch(s[at:end], first * 3600 + mid * 60 + sec, end)
+    if lead == 2 and first > 59:
+        return None  # MM is 00–59
+    return _TimeMatch(s[at:after_mid], first * 60 + mid, after_mid)
+
+
+def _skip_space_and_dash(s: str, at: int) -> int:
+    """After a prefix: skip one space, then an optional ``- `` (spaced dash)."""
+    i = at
+    if char_at(s, i) == " ":
+        i += 1
+    if char_at(s, i) == "-" and char_at(s, i + 1) == " ":
+        i += 2
+    return i
+
+
+def _match_timestamp(s: str) -> Optional[tuple[tuple[str, int], int]]:
+    """R4.1"""
+    first = char_at(s, 0)
+    bracket = "]" if first == "[" else ")" if first == "(" else None
+    t = _match_time(s, 1 if bracket else 0)
+    if t is None:
+        return None
+    end = t.end
+    if bracket:
+        if char_at(s, end) != bracket:
+            return None
+        end += 1
+    if end < len(s) and s[end] != " ":
+        return None
+    return (t.raw, t.seconds), _skip_space_and_dash(s, end)
+
+
+def _contains_spaced_dash(s: str) -> bool:
+    return has_spaced_dash(scan(s).skel.text)
+
+
+def _match_position(s: str, mode: str) -> Optional[int]:
+    """R4.2: end offset of the position prefix, or None. Forms (a), (b), (c), (d)/(e)."""
+    n = _digit_run(s, 0)
+    if n < 1 or n > 3:
+        return None
+    c = char_at(s, n)
+    zero_padded = s[0] == "0" and n >= 2
+    # (a) `01. `, `1) `
+    if (c == "." or c == ")") and (char_at(s, n + 1) == " " or n + 1 == len(s)):
+        return _skip_space_and_dash(s, n + 1)
+    # (b) `01 `: a position in every mode.
+    if zero_padded and c == " ":
+        return _skip_space_and_dash(s, n)
+    # (c) `3 - Artist - Title`; in filename mode `N - ` is always a position (`311 - Amber.mp3`).
+    if c == " " and char_at(s, n + 1) == "-" and char_at(s, n + 2) == " ":
+        if mode == "filename" or _contains_spaced_dash(s[n + 3 :]):
+            return n + 3
+        return None
+    if mode == "filename":
+        # (e) `01-Track`, `03_name`, `01.Track`
+        nxt = char_at(s, n + 1)
+        if (c == "-" or c == "_" or c == ".") and nxt is not None and nxt != " ":
+            return n + 1
+        # (e) `3 My Song.mp3`: only when the remainder has no spaced dash.
+        if c == " " and not _contains_spaced_dash(s[n + 1 :]):
+            return _skip_space_and_dash(s, n)
+    # (d) `2 Unlimited`, `50 Cent`: never a position outside filename mode.
+    return None
+
+
+def strip_prefixes(s: str, base: int, mode: str, ctx: Ctx) -> PrefixResult:
+    rest = s
+    offset = base
+    timestamp: Optional[tuple[str, int]] = None
+    position: Optional[tuple[str, int]] = None
+
+    ts = _match_timestamp(rest)
+    if ts is not None:
+        timestamp = ts[0]
+        rest = rest[ts[1] :]
+        offset += ts[1]
+    if match_known_at(rest, 0, ctx, "-") == 0:
+        end = _match_position(rest, mode)
+        if end is not None and end < len(rest):
+            raw = rest[: _digit_run(rest, 0)]
+            position = (raw, int(raw))
+            rest = rest[end:]
+            offset += end
+    return PrefixResult(rest, offset, timestamp, position)

trackparse/_scanner.py

@@ -0,0 +1,240 @@
+"""R3: top-level group scanner and skeleton.
+
+A ``Skel`` is a skeleton string plus, for every code point, its absolute offset in the
+normalized input. Groups are looked up by the offset of their placeholder, so any slice of a
+skeleton still knows which groups it contains. Offsets also give every extracted item (junk,
+versions, credits) its position for the "order of appearance" rules.
+
+Offsets are counted in UTF-16 units (an astral code point advances by 2) so that every
+ordering comparison is identical to the JS reference; indices into ``text`` are code points.
+"""
+
+from __future__ import annotations
+
+from typing import NamedTuple, Optional
+
+from ._words import char_at, collapse_spaces, is_whitespace
+
+#: R3.4 placeholder code point.
+PH = ""
+
+_CLOSER = {"(": ")", "[": "]", "{": "}"}
+
+
+class Group:
+    __slots__ = ("closed", "end", "inner", "open", "pos", "raw")
+
+    def __init__(self, open: str, inner: str, raw: str, closed: bool, pos: int, end: int) -> None:
+        self.open = open
+        #: R3.5: inner text, trimmed and whitespace-collapsed.
+        self.inner = inner
+        #: The group exactly as written, brackets included.
+        self.raw = raw
+        self.closed = closed
+        #: Absolute offset of the opener.
+        self.pos = pos
+        #: Absolute offset just past the group.
+        self.end = end
+
+
+class Skel:
+    __slots__ = ("groups", "pos", "text")
+
+    def __init__(self, text: str, pos: list[int], groups: dict[int, Group]) -> None:
+        self.text = text
+        self.pos = pos
+        self.groups = groups
+
+
+class ScanResult(NamedTuple):
+    skel: Skel
+    unbalanced: bool
+
+
+def scan(s: str, base: int = 0) -> ScanResult:
+    """R3.1–R3.5: scan ``s`` (whose first unit sits at absolute offset ``base``)."""
+    text: list[str] = []
+    pos: list[int] = []
+    groups: dict[int, Group] = {}
+    stack: list[str] = []
+    group_start = -1
+    group_off = 0
+    # Absolute UTF-16 offset of each code point of `s` (plus the end), for group bookkeeping.
+    offs: list[int] = []
+    off = base
+    for ch in s:
+        offs.append(off)
+        off += 2 if ch > "￿" else 1
+    offs.append(off)
+    for i, ch in enumerate(s):
+        if not stack:
+            if ch in _CLOSER:
+                stack.append(_CLOSER[ch])
+                group_start = i
+                group_off = offs[i]
+            else:
+                text.append(ch)
+                pos.append(offs[i])
+            continue
+        if ch in _CLOSER:
+            stack.append(_CLOSER[ch])
+        elif ch == stack[-1]:
+            stack.pop()
+            if not stack:
+                _add_group(s, group_start, i + 1, True, offs, groups)
+                text.append(PH)
+                pos.append(group_off)
+        # R3.2: a non-matching closer is literal text inside the group.
+    unbalanced = len(stack) > 0
+    if unbalanced:
+        # R3.3: the group runs to the end of the string.
+        _add_group(s, group_start, len(s), False, offs, groups)
+        text.append(PH)
+        pos.append(group_off)
+    return ScanResult(Skel("".join(text), pos, groups), unbalanced)
+
+
+def _add_group(
+    s: str, start: int, end: int, closed: bool, offs: list[int], groups: dict[int, Group]
+) -> None:
+    inner = s[start + 1 : end - 1 if closed else end]
+    groups[offs[start]] = Group(
+        s[start], collapse_spaces(inner), s[start:end], closed, offs[start], offs[end]
+    )
+
+
+# ---------------------------------------------------------------------------
+# Skeleton operations
+
+
+def slice_skel(s: Skel, start: int, end: Optional[int] = None) -> Skel:
+    n = len(s.text)
+    if end is None:
+        end = n
+    a = max(0, min(start, n))
+    b = max(a, min(end, n))
+    return Skel(s.text[a:b], s.pos[a:b], s.groups)
+
+
+def trim_skel(s: Skel) -> Skel:
+    t = s.text
+    a = 0
+    b = len(t)
+    while a < b and is_whitespace(t[a]):
+        a += 1
+    while b > a and is_whitespace(t[b - 1]):
+        b -= 1
+    return slice_skel(s, a, b)
+
+
+def concat_skel(a: Skel, b: Skel) -> Skel:
+    return Skel(a.text + b.text, a.pos + b.pos, a.groups)
+
+
+def cut_skel(s: Skel, start: int, end: int) -> Skel:
+    """Remove the code points in [start, end)."""
+    return concat_skel(slice_skel(s, 0, start), slice_skel(s, end))
+
+
+def group_at(s: Skel, index: int) -> Optional[Group]:
+    """The group behind the placeholder at ``index``, if it is one."""
+    if char_at(s.text, index) != PH:
+        return None
+    return s.groups.get(s.pos[index])
+
+
+def groups_of(s: Skel) -> list[tuple[int, Group]]:
+    """Groups in the skeleton, left to right, with their index."""
+    out: list[tuple[int, Group]] = []
+    if PH not in s.text:
+        return out
+    for i, ch in enumerate(s.text):
+        if ch == PH:
+            g = s.groups.get(s.pos[i])
+            if g is not None:
+                out.append((i, g))
+    return out
+
+
+def has_group(s: Skel) -> bool:
+    return PH in s.text
+
+
+def render_skel(s: Skel) -> str:
+    """Substitute groups back (R3.4 reassembly). Whitespace is not touched."""
+    if PH not in s.text:
+        return s.text
+    out: list[str] = []
+    for i, ch in enumerate(s.text):
+        g = s.groups.get(s.pos[i]) if ch == PH else None
+        out.append(g.raw if g is not None else ch)
+    return "".join(out)
+
+
+def start_pos(s: Skel, fallback: int = 0) -> int:
+    """Absolute offset of the first code point (or ``fallback`` for an empty skeleton)."""
+    return s.pos[0] if s.pos else fallback
+
+
+def remove_groups(s: Skel, remove: set[int]) -> Skel:
+    """Remove the placeholders of the given groups."""
+    if not remove:
+        return s
+    text: list[str] = []
+    pos: list[int] = []
+    for ch, p in zip(s.text, s.pos):
+        if ch == PH and p in remove:
+            continue
+        text.append(ch)
+        pos.append(p)
+    return Skel("".join(text), pos, s.groups)
+
+
+def is_spaced_dash_at(text: str, i: int) -> bool:
+    """R6.1: ``-`` with a space immediately on both sides."""
+    return 0 < i < len(text) - 1 and text[i] == "-" and text[i - 1] == " " and text[i + 1] == " "
+
+
+def has_spaced_dash(text: str) -> bool:
+    return " - " in text
+
+
+class Segment:
+    __slots__ = ("end", "skel", "start")
+
+    def __init__(self, skel: Skel, start: int, end: int) -> None:
+        self.skel = skel
+        #: Trimmed range inside the parent skeleton.
+        self.start = start
+        self.end = end
+
+
+def _trimmed_segment(s: Skel, start: int, end: int) -> Segment:
+    t = s.text
+    a = start
+    b = max(start, end)
+    while a < b and is_whitespace(char_at(t, a)):
+        a += 1
+    while b > a and is_whitespace(char_at(t, b - 1)):
+        b -= 1
+    return Segment(slice_skel(s, a, b), a, b)
+
+
+def split_at_spaced_dashes(s: Skel, allow_leading: bool = False) -> list[Segment]:
+    """R6.1 / R8.2: split a skeleton at every spaced dash into trimmed segments. With
+    ``allow_leading``, a string starting with ``- `` yields an empty first segment (R6.3)."""
+    segments: list[Segment] = []
+    t = s.text
+    start = 0
+    if allow_leading and t[:2] == "- ":
+        segments.append(Segment(slice_skel(s, 0, 0), 0, 0))
+        start = 2
+    i = max(start, 1)
+    n = len(t)
+    while i < n - 1:
+        if t[i] == "-" and t[i - 1] == " " and t[i + 1] == " ":
+            segments.append(_trimmed_segment(s, start, i - 1))
+            start = i + 2
+        i += 1
+    segments.append(_trimmed_segment(s, start, n))
+    return segments

trackparse/_separator.py

@@ -0,0 +1,209 @@
+"""R6: artist/title separator, including R6.2 suffix peeling (shared with R8.2)."""
+
+from __future__ import annotations
+
+from typing import NamedTuple, Optional, Union
+
+from ._classify import (
+    UNKNOWN,
+    Classification,
+    Flag,
+    Junk,
+    Site,
+    Versions,
+    Year,
+    classify,
+)
+from ._context import Ctx, is_known_artist, warn
+from ._scanner import (
+    PH,
+    Segment,
+    Skel,
+    concat_skel,
+    has_group,
+    render_skel,
+    slice_skel,
+    split_at_spaced_dashes,
+    start_pos,
+    trim_skel,
+)
+from ._words import (
+    char_at,
+    collapse_spaces,
+    in_vocab,
+    is_letter,
+    is_whitespace,
+    split_words,
+    year_of,
+)
+
+Peelable = Union[Junk, Flag, Year, Versions]
+
+
+class Peeled(NamedTuple):
+    cls: Peelable
+    raw: str
+    pos: int
+
+
+def _classify_segment(seg: Skel, ctx: Ctx) -> Classification:
+    """R6.2 classification of a bare dash segment: placeholders make it Unknown."""
+    if has_group(seg):
+        return UNKNOWN
+    text = collapse_spaces(seg.text)
+    return classify(text, Site("title", "-", start_pos(seg)), ctx)
+
+
+def peel_suffixes(
+    segments: list[Segment], relaxed: bool, ctx: Ctx
+) -> tuple[list[Segment], list[Peeled]]:
+    """R6.2 / R8.2: peel classifiable suffixes off the right end. ``relaxed`` drops conditions
+    (i)–(iv) (R8.2 with an artist side). Returns the remaining segments and the peeled
+    suffixes, left to right."""
+    remaining = list(segments)
+    peeled: list[Peeled] = []
+    while len(remaining) >= 2:
+        last = remaining[-1]
+        cls = _classify_segment(last.skel, ctx)
+        if not isinstance(cls, (Junk, Flag, Year, Versions)):
+            break
+        words = split_words(last.skel.text)
+        # (ii) does not apply to prefix-form versions (`Andy C b2b Hedex - Live at Printworks`).
+        prefix_form = isinstance(cls, Versions) and all(v.prefix_form for v in cls.versions)
+        ok = (
+            relaxed
+            or len(remaining) - 1 >= 2
+            or (len(words) >= 2 and not prefix_form)
+            or any(year_of(w) is not None for w in words)
+            or isinstance(cls, Junk)
+        )
+        if not ok:
+            break
+        peeled.insert(0, Peeled(cls, collapse_spaces(last.skel.text), start_pos(last.skel)))
+        remaining.pop()
+    return remaining, peeled
+
+
+class SeparatorResult(NamedTuple):
+    artist: Optional[Skel]
+    title: Skel
+    #: A separator split the string (R6.3–R6.7): R8.2 peels without conditions.
+    split: bool
+    peeled: list[Peeled]
+
+
+def _non_empty(s: Skel) -> Optional[Skel]:
+    t = trim_skel(s)
+    return t if len(t.text) > 0 else None
+
+
+def _split_at(s: Skel, cut_start: int, cut_end: int) -> tuple[Optional[Skel], Skel]:
+    return _non_empty(slice_skel(s, 0, cut_start)), trim_skel(slice_skel(s, cut_end))
+
+
+def find_separator(skel: Skel, mode: str, uploader: Optional[Skel], ctx: Ctx) -> SeparatorResult:
+    segments = split_at_spaced_dashes(skel, True)
+    remaining, peeled = peel_suffixes(segments, False, ctx)
+
+    # R6.3
+    if len(remaining) >= 2:
+        first = remaining[0]
+        second = remaining[1]
+        last_seg = remaining[-1]
+        artist = first.skel if len(first.skel.text) > 0 else None
+        title = slice_skel(skel, second.start, last_seg.end)
+        return SeparatorResult(artist, title, artist is not None, peeled)
+
+    rest = remaining[0].skel
+    other = _split_without_spaced_dash(rest, mode, ctx)
+    if other is not None:
+        return SeparatorResult(other[0], other[1], other[0] is not None, peeled)
+
+    # R6.8: the uploader fallback does not warn noSeparator.
+    artist = uploader if mode == "youtube" else None
+    if len(rest.text) > 0 and artist is None:
+        warn(ctx, "noSeparator")
+    return SeparatorResult(artist, rest, False, peeled)
+
+
+def _split_without_spaced_dash(
+    s: Skel, mode: str, ctx: Ctx
+) -> Optional[tuple[Optional[Skel], Skel]]:
+    asym = _asymmetric_dash(s.text)
+    if asym >= 0:
+        warn(ctx, "asymmetricDashSplit")
+        return _split_at(s, asym, asym + 1)
+    if mode == "youtube":
+        quoted = _quoted_title(s)
+        if quoted is not None:
+            warn(ctx, "quotedTitleSplit")
+            return quoted
+        by = _by_split(s, ctx)
+        if by >= 0:
+            warn(ctx, "bySplit")
+            left, right = _split_at(s, by, by + 4)
+            return (right if len(right.text) > 0 else None, left if left is not None else s)
+    if mode == "youtube" or mode == "filename":
+        dash = _unspaced_dash(s, ctx)
+        if dash >= 0:
+            warn(ctx, "unspacedDashSplit")
+            return _split_at(s, dash, dash + 1)
+    return None
+
+
+def _asymmetric_dash(t: str) -> int:
+    """R6.4: the first ``-`` with a space on exactly one side."""
+    for i in range(1, len(t) - 1):
+        if t[i] != "-":
+            continue
+        if is_whitespace(t[i - 1]) != is_whitespace(t[i + 1]):
+            return i
+    return -1
+
+
+def _quoted_title(s: Skel) -> Optional[tuple[Optional[Skel], Skel]]:
+    """R6.5: ``Artist "Title" (extra)``."""
+    t = s.text
+    open_ = t.find('"')
+    if open_ <= 0:
+        return None
+    close = t.find('"', open_ + 1)
+    if close < 0:
+        return None
+    artist = trim_skel(slice_skel(s, 0, open_))
+    last = artist.text[-1:]
+    if last == ":" or last == "-":
+        artist = trim_skel(slice_skel(artist, 0, len(artist.text) - 1))
+    title = trim_skel(concat_skel(slice_skel(s, open_ + 1, close), slice_skel(s, close + 1)))
+    return (artist if len(artist.text) > 0 else None, title)
+
+
+def _by_split(s: Skel, ctx: Ctx) -> int:
+    """R6.6: index of the space before the last usable `` by ``. The right side must be
+    non-empty and not a single stopword (``Stand by Me``)."""
+    t = s.text
+    i = t.rfind(" by ")
+    while i > 0:
+        # Placeholder-only words (groups such as `(Official Video)`) don't count here.
+        right = [w for w in split_words(t[i + 4 :]) if w != PH]
+        if right and not (len(right) == 1 and in_vocab(right[0], ctx.t.stopwords)):
+            return i
+        # JS lastIndexOf(" by ", i - 1): the last occurrence starting at or before i - 1.
+        i = t.rfind(" by ", 0, i - 1 + 4) if i - 1 >= 0 else -1
+    return -1
+
+
+def _unspaced_dash(s: Skel, ctx: Ctx) -> int:
+    """R6.7: ``Jay-Z-Numb`` → the chosen unspaced dash index."""
+    t = s.text
+    last_candidate = -1
+    for i in range(1, len(t) - 1):
+        if t[i] != "-" or is_whitespace(t[i - 1]) or is_whitespace(t[i + 1]):
+            continue
+        nxt = char_at(t, i + 1)
+        if not (nxt == '"' or is_letter(nxt)):
+            continue
+        if ctx.known_keys and is_known_artist(render_skel(slice_skel(s, 0, i)), ctx):
+            return i
+        last_candidate = i
+    return last_candidate