trackparse 0.2.0__py3-none-any.whl

trackparse/_mode.py

@@ -0,0 +1,204 @@
+"""R2: mode resolution, platform suffixes, filename handling and youtube pipes."""
+
+from __future__ import annotations
+
+from typing import NamedTuple, Optional
+
+from ._classify import junk_kind_of
+from ._context import Ctx, warn
+from ._scanner import (
+    Segment,
+    Skel,
+    groups_of,
+    has_spaced_dash,
+    render_skel,
+    scan,
+    slice_skel,
+    start_pos,
+)
+from ._words import ascii_lower, collapse_spaces, r0_trim, split_words, utf16_len, word_spans
+
+
+class PositionedJunk(NamedTuple):
+    raw: str
+    kind: str
+    pos: int
+
+
+class Piece(NamedTuple):
+    """A contiguous piece of the normalized string and its absolute offset."""
+
+    text: str
+    base: int
+
+
+class Prelude(NamedTuple):
+    mode: str
+    #: The working string (R2.4 step 2/4), or the artist piece in the `artist | title` case.
+    working: Piece
+    #: R2.4 step 3: the title piece when two dash-less pipe segments remain.
+    pipe_title: Optional[Piece]
+    junk: list[PositionedJunk]
+
+
+def _strip_platform_suffixes(s: str, ctx: Ctx, junk: list[PositionedJunk]) -> str:
+    """R2.2: strip trailing platform suffixes (longest first, repeatedly)."""
+    stripped = True
+    while stripped:
+        stripped = False
+        lower = ascii_lower(s)
+        for suffix in ctx.t.platform_suffixes:
+            if not lower.endswith(ascii_lower(suffix)):
+                continue
+            start = len(s) - len(suffix)
+            junk.append(PositionedJunk(s[start + 3 :], "platform", utf16_len(s[:start]) + 3))
+            s = s[:start]
+            stripped = True
+            break
+    return s
+
+
+def _extension_of(s: str, ctx: Ctx) -> Optional[str]:
+    dot = s.rfind(".")
+    if dot < 0:
+        return None
+    ext = ascii_lower(s[dot + 1 :])
+    return ext if ext in ctx.t.extensions else None
+
+
+def split_pipes(skel: Skel) -> list[Segment]:
+    """Top-level `` | `` / `` || `` separators on a skeleton → trimmed segment ranges."""
+    t = skel.text
+    n = len(t)
+    cuts: list[tuple[int, int]] = []
+    i = 1
+    while i < n:
+        if t[i - 1] == " " and t[i] == "|":
+            bars = 2 if i + 1 < n and t[i + 1] == "|" else 1
+            if i + bars < n and t[i + bars] == " ":
+                cuts.append((i - 1, i + bars + 1))
+                i += bars
+        i += 1
+    segments: list[Segment] = []
+    start = 0
+    for a, b in [*cuts, (n, n)]:
+        s = start
+        e = a
+        while s < e and t[s] == " ":
+            s += 1
+        while e > s and t[e - 1] == " ":
+            e -= 1
+        segments.append(Segment(slice_skel(skel, s, e), s, e))
+        start = b
+    return segments
+
+
+class TrailingJunk(NamedTuple):
+    start: int
+    kind: str
+
+
+def trailing_junk_phrase(text: str, ctx: Ctx) -> Optional[TrailingJunk]:
+    """R8.4 test: the skeleton ends with an unbracketed junk phrase (genres excluded)."""
+    spans = word_spans(text)
+    m = ctx.t.junk_phrases.match_ending([s.text for s in spans], len(spans))
+    if m is None:
+        return None
+    return TrailingJunk(spans[len(spans) - m.length].start, m.entry.value)
+
+
+def _is_junk_text(text: str, ctx: Ctx) -> Optional[str]:
+    words = split_words(text)
+    return junk_kind_of(words, ctx) if words else None
+
+
+def _looks_like_youtube(skel: Skel, ctx: Ctx) -> bool:
+    """R2.1 youtube signals (besides platform suffixes)."""
+    if len(split_pipes(skel)) > 1:
+        return True
+    for _, group in groups_of(skel):
+        kind = _is_junk_text(group.inner, ctx)
+        if kind and kind != "genre":
+            return True
+    return trailing_junk_phrase(skel.text, ctx) is not None
+
+
+def prelude(normalized: str, requested: object, ctx: Ctx) -> Prelude:
+    junk: list[PositionedJunk] = []
+    s = _strip_platform_suffixes(normalized, ctx, junk)
+    had_platform = len(junk) > 0
+
+    if requested in ("clean", "youtube", "filename"):
+        mode = str(requested)
+    elif _extension_of(s, ctx):
+        mode = "filename"
+    else:
+        mode = "clean"
+
+    if mode == "filename":
+        # R2.3: strip the extension, trim, then `_` → space when there is no space.
+        if _extension_of(s, ctx):
+            s = s[: s.rfind(".")]
+        s = r0_trim(s)
+        if " " not in s and "_" in s:
+            s = r0_trim(s.replace("_", " "))
+
+    skel, unbalanced = scan(s, 0)
+    if unbalanced:
+        warn(ctx, "unbalancedBrackets")
+    if (
+        (requested == "auto" or requested is None)
+        and mode == "clean"
+        and (had_platform or _looks_like_youtube(skel, ctx))
+    ):
+        mode = "youtube"
+
+    whole = Piece(s, 0)
+    if mode != "youtube":
+        return Prelude(mode, whole, None, junk)
+    working, pipe_title = _split_youtube_pipes(skel, ctx, junk)
+    return Prelude(mode, working, pipe_title, junk)
+
+
+def _piece_of(seg: Segment) -> Piece:
+    return Piece(render_skel(seg.skel), start_pos(seg.skel))
+
+
+def _split_youtube_pipes(
+    skel: Skel, ctx: Ctx, junk: list[PositionedJunk]
+) -> tuple[Piece, Optional[Piece]]:
+    """R2.4"""
+    segments = split_pipes(skel)
+    if len(segments) <= 1:
+        return Piece(render_skel(skel), 0), None
+
+    remaining: list[Segment] = []
+    for seg in segments:
+        text = collapse_spaces(render_skel(seg.skel))
+        # R2.4 step 1: a segment with a spaced dash is an artist/title candidate, never junk.
+        kind = None if has_spaced_dash(seg.skel.text) else _is_junk_text(text, ctx)
+        if kind:
+            junk.append(PositionedJunk(text, kind, start_pos(seg.skel)))
+        elif len(text) > 0:
+            remaining.append(seg)
+
+    def push_other(keep: Optional[Segment], title: Optional[Segment] = None) -> None:
+        for seg in remaining:
+            if seg is keep or seg is title:
+                continue
+            junk.append(
+                PositionedJunk(collapse_spaces(render_skel(seg.skel)), "other", start_pos(seg.skel))
+            )
+
+    with_dash = next((seg for seg in remaining if has_spaced_dash(seg.skel.text)), None)
+    if with_dash is not None:
+        push_other(with_dash)
+        return _piece_of(with_dash), None
+    if len(remaining) == 2:
+        warn(ctx, "ambiguousSeparator")
+        return _piece_of(remaining[0]), _piece_of(remaining[1])
+    if remaining:
+        push_other(remaining[0])
+        return _piece_of(remaining[0]), None
+    # Every segment was junk: nothing left to parse.
+    return Piece("", 0), None

trackparse/_normalize.py

@@ -0,0 +1,107 @@
+"""R1: normalization."""
+
+from __future__ import annotations
+
+import unicodedata
+
+from ._words import is_whitespace
+
+# R1.2 invisible characters removed outright. ZWNJ/ZWJ (U+200C/U+200D) are kept (ZWJ emoji).
+# R1.2: U+E000 is reserved as the R3.4 group placeholder, so it can never occur in input.
+_REMOVED = frozenset(["​", "⁠", "", "­", ""])
+
+# R1.3 brackets, R1.4 quotes, R1.5 dashes → ASCII.
+_CHAR_MAP: dict[str, str] = {
+    "（": "(",
+    "）": ")",
+    "［": "[",
+    "【": "[",
+    "〔": "[",
+    "］": "]",
+    "】": "]",
+    "〕": "]",
+    "｛": "{",
+    "｝": "}",
+    "“": '"',
+    "”": '"',
+    "„": '"',
+    "«": '"',
+    "»": '"',
+    "「": '"',
+    "」": '"',
+    "『": '"',
+    "』": '"',
+    "＂": '"',
+    "‘": "'",
+    "’": "'",
+    "‚": "'",
+    "`": "'",
+    "´": "'",
+    "−": "-",
+    "﹘": "-",
+    "﹣": "-",
+    "－": "-",
+}
+# R1.5: U+2010–U+2015 → "-".
+for _cp in range(0x2010, 0x2016):
+    _CHAR_MAP[chr(_cp)] = "-"
+
+
+def _collapse_spaced_dash_runs(chars: list[str]) -> list[str]:
+    """R1.5 (second half): a run of 2+ ``-`` with whitespace on both sides becomes one ``-``."""
+    out: list[str] = []
+    i = 0
+    n = len(chars)
+    while i < n:
+        if chars[i] != "-":
+            out.append(chars[i])
+            i += 1
+            continue
+        j = i
+        while j < n and chars[j] == "-":
+            j += 1
+        spaced = (
+            j - i >= 2
+            and i > 0
+            and j < n
+            and is_whitespace(chars[i - 1])
+            and is_whitespace(chars[j])
+        )
+        if spaced:
+            out.append("-")
+        else:
+            out.extend("-" * (j - i))
+        i = j
+    return out
+
+
+def _collapse_whitespace(chars: list[str]) -> str:
+    """R1.6: every whitespace code point → one space, runs collapsed, trimmed."""
+    out: list[str] = []
+    pending = False
+    for ch in chars:
+        if is_whitespace(ch):
+            pending = len(out) > 0
+            continue
+        if pending:
+            out.append(" ")
+        pending = False
+        out.append(ch)
+    return "".join(out)
+
+
+def normalize(input: str) -> str:
+    """R1: normalize a track string. Idempotent; total on any ``str``.
+
+    Raises ``TypeError`` when ``input`` is not a ``str``.
+    """
+    if not isinstance(input, str):
+        raise TypeError(f"normalize() expects str, got {type(input).__name__}")
+    chars: list[str] = []
+    for ch in unicodedata.normalize("NFC", input):
+        if ch in _REMOVED:
+            continue
+        chars.append(_CHAR_MAP.get(ch, ch))
+    # R1.8: removing invisibles can leave a decomposed sequence behind; re-compose so that
+    # normalize() stays idempotent.
+    return unicodedata.normalize("NFC", _collapse_whitespace(_collapse_spaced_dash_runs(chars)))

trackparse/_parser.py

@@ -0,0 +1,257 @@
+"""Pipeline: R1 → R2 → R4 → R3/R6 → R7 → R8 → R9, plus R10 parse_artists."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import replace
+from typing import Any, 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 ._normalize import normalize
+from ._prefix import strip_prefixes
+from ._scanner import Skel, scan, trim_skel
+from ._separator import find_separator
+from ._tables import Tables, js_entries, tables_for
+from ._title import Extracted, add_peeled, parse_title_side
+from ._words import r0_trim_end
+from .options import KeywordOptions
+from .types import (
+    Artist,
+    Flags,
+    Junk,
+    JunkKind,
+    Mode,
+    ParsedTrack,
+    Position,
+    Timestamp,
+    Warning,
+)
+
+#: Offset used for uploader text so it sorts before everything from the input.
+_UPLOADER_BASE = -1_000_000_000
+
+_OPTION_KEYS = ("mode", "uploader", "known_artists", "split_and", "keywords")
+
+
+def _skel_of(piece: Piece, ctx: Ctx) -> Skel:
+    r = scan(piece.text, piece.base)
+    if r.unbalanced:
+        warn(ctx, "unbalancedBrackets")
+    return trim_skel(r.skel)
+
+
+def _uploader_skel(uploader: object) -> Optional[Skel]:
+    """R6.8: uploader minus a trailing `` - Topic`` and ``VEVO``."""
+    if not isinstance(uploader, str):
+        return None
+    u = normalize(uploader)
+    if u.endswith(" - Topic"):
+        u = u[: -len(" - Topic")]
+    if u.endswith("VEVO"):
+        u = r0_trim_end(u[: -len("VEVO")])
+    if len(u) == 0:
+        return None
+    return scan(u, _UPLOADER_BASE).skel
+
+
+def _empty_track(inp: str, mode: str) -> ParsedTrack:
+    return ParsedTrack(
+        input=inp,
+        mode=cast(Mode, mode),
+        position=None,
+        timestamp=None,
+        artists=(),
+        title="",
+        full_title="",
+        versions=(),
+        year=None,
+        flags=Flags(),
+        junk=(),
+        warnings=(),
+    )
+
+
+def _run(inp: str, options: Mapping[str, Any], t: Tables) -> ParsedTrack:
+    ctx = Ctx(t, options)
+    norm = normalize(inp)
+    requested = options.get("mode")
+    if requested is None:
+        requested = "auto"
+    pre = prelude(norm, requested, ctx)
+    if len(norm) == 0:
+        return _empty_track(inp, pre.mode)  # R9.5
+
+    # R4
+    prefix = strip_prefixes(pre.working.text, pre.working.base, pre.mode, ctx)
+    working = _skel_of(Piece(prefix.rest, prefix.base), ctx)
+
+    out = Extracted()
+    artist_skel: Optional[Skel]
+    if pre.pipe_title is not None:
+        # R2.4 step 3: `artist | title`, R6 skipped.
+        artist_skel = working if len(working.text) > 0 else None
+        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)
+        add_peeled(out, sep.peeled)
+        artist_skel = sep.artist
+        title_skel = sep.title
+        relaxed = sep.split
+
+    artist_side = parse_artist_side(artist_skel, ctx) if artist_skel is not None else None
+    title_side = parse_title_side(title_skel, relaxed, pre.mode == "youtube", out, ctx)
+
+    # R9
+    versions = by_pos(out.versions)
+    for v in versions:
+        if v.ambiguous_mix:
+            warn(ctx, "ambiguousMixCredit")
+    artist_credits = artist_side.credits if artist_side is not None else []
+    artists = dedup_artists([*artist_credits, *by_pos(out.credits)])
+    final_versions = tuple(to_version(v) for v in versions)
+    # R9.6: the first year in text order.
+    years = by_pos([*(artist_side.years if artist_side is not None else []), *out.years])
+    junk = by_pos([*pre.junk, *(artist_side.junk if artist_side is not None else []), *out.junk])
+    flags = Flags(
+        explicit=out.explicit or (artist_side is not None and artist_side.explicit),
+        clean=out.clean or (artist_side is not None and artist_side.clean),
+        unknown_artist=(artist_side is not None and artist_side.unknown_artist)
+        or out.unknown_artist,
+        unknown_title=title_side.unknown_title,
+    )
+    ts = prefix.timestamp
+    pos = prefix.position
+    return ParsedTrack(
+        input=inp,
+        mode=cast(Mode, pre.mode),
+        position=None if pos is None else Position(raw=pos[0], number=pos[1]),
+        timestamp=None if ts is None else Timestamp(raw=ts[0], seconds=ts[1]),
+        artists=tuple(artists),
+        title=title_side.title,
+        full_title=full_title_of(title_side.title, final_versions),
+        versions=final_versions,
+        year=years[0].year if years else None,
+        flags=flags,
+        junk=tuple(Junk(raw=j.raw, kind=cast(JunkKind, j.kind)) for j in junk),
+        warnings=cast(tuple[Warning, ...], tuple(ctx.warnings)),
+    )
+
+
+def _run_artists(inp: str, options: Mapping[str, Any], t: Tables) -> list[Artist]:
+    ctx = Ctx(t, options)
+    norm = normalize(inp)
+    if len(norm) == 0:
+        return []
+    side = parse_artist_side(scan(norm, 0).skel, ctx)
+    return [replace(a, source="artist") for a in dedup_artists(side.credits)]
+
+
+def _check_input(inp: object, fn: str) -> str:
+    if not isinstance(inp, str):
+        raise TypeError(f"{fn}() expects str input, got {type(inp).__name__}")
+    return inp
+
+
+def _safe_options(options: Mapping[str, Any]) -> dict[str, Any]:
+    # A `None` per-call value must not override a create_parser() base option.
+    return {k: v for k, v in options.items() if k in _OPTION_KEYS and v is not None}
+
+
+def _merge_keywords(a: Mapping[str, Any], b: Mapping[str, Any]) -> dict[str, Any]:
+    """Like the JS mergeKeywords: maps merged (later wins), lists concatenated."""
+
+    def kw(o: Mapping[str, Any]) -> Mapping[str, Any]:
+        k = o.get("keywords")
+        return k if isinstance(k, Mapping) else {}
+
+    def as_map(v: Any) -> dict[str, Any]:
+        return dict(js_entries(v)) if isinstance(v, Mapping) else {}
+
+    def as_list(v: Any) -> list[Any]:
+        return list(v) if isinstance(v, (list, tuple)) else []
+
+    x = kw(a)
+    y = kw(b)
+    return {
+        "version_heads": {**as_map(x.get("version_heads")), **as_map(y.get("version_heads"))},
+        "descriptors": [*as_list(x.get("descriptors")), *as_list(y.get("descriptors"))],
+        "genres": [*as_list(x.get("genres")), *as_list(y.get("genres"))],
+        "junk": {**as_map(x.get("junk")), **as_map(y.get("junk"))},
+        "feat_markers": [*as_list(x.get("feat_markers")), *as_list(y.get("feat_markers"))],
+    }
+
+
+class Parser:
+    """A parser with ``keywords`` compiled once. Per-call options are merged over the base
+    options; a per-call ``None`` does not override a base value."""
+
+    def __init__(self, **options: Any) -> None:
+        self._base = _safe_options(options)
+        self._tables = tables_for(self._base.get("keywords"))
+
+    def _resolve(self, call: Mapping[str, Any]) -> tuple[dict[str, Any], Tables]:
+        per_call = _safe_options(call)
+        merged = {**self._base, **per_call}
+        if per_call.get("keywords"):
+            return merged, tables_for(_merge_keywords(self._base, per_call))
+        return merged, self._tables
+
+    def parse(
+        self,
+        input: str,
+        *,
+        mode: Optional[str] = None,
+        uploader: Optional[str] = None,
+        known_artists: Optional[Sequence[str]] = None,
+        split_and: Optional[str] = None,
+        keywords: Optional[KeywordOptions] = None,
+    ) -> ParsedTrack:
+        """Parse one track string (see :func:`trackparse.parse`)."""
+        inp = _check_input(input, "parse")
+        merged, tables = self._resolve(
+            {
+                "mode": mode,
+                "uploader": uploader,
+                "known_artists": known_artists,
+                "split_and": split_and,
+                "keywords": keywords,
+            }
+        )
+        return _run(inp, merged, tables)
+
+    def parse_artists(
+        self,
+        input: str,
+        *,
+        mode: Optional[str] = None,
+        uploader: Optional[str] = None,
+        known_artists: Optional[Sequence[str]] = None,
+        split_and: Optional[str] = None,
+        keywords: Optional[KeywordOptions] = None,
+    ) -> list[Artist]:
+        """Split an artist string into credits (R10)."""
+        inp = _check_input(input, "parse_artists")
+        merged, tables = self._resolve(
+            {
+                "mode": mode,
+                "uploader": uploader,
+                "known_artists": known_artists,
+                "split_and": split_and,
+                "keywords": keywords,
+            }
+        )
+        return _run_artists(inp, merged, tables)
+
+
+_default_parser: Optional[Parser] = None
+
+
+def default_parser() -> Parser:
+    global _default_parser
+    if _default_parser is None:
+        _default_parser = Parser()
+    return _default_parser