trackparse 0.2.0__py3-none-any.whl

trackparse/__init__.py

@@ -0,0 +1,119 @@
+"""trackparse: spec-driven parser for music track strings.
+
+Behaviour is defined by spec/SPEC.md (https://github.com/4matic/trackparse/blob/main/spec/SPEC.md);
+rule IDs (R6.2…) in comments refer to it. Results are frozen dataclasses with snake_case
+attributes; ``to_dict()`` gives the spec's canonical camelCase JSON.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Optional
+
+from ._data import SPEC_VERSION
+from ._format import all_artists, format_track
+from ._normalize import normalize
+from ._parser import Parser, default_parser
+from .options import FormatOptions, KeywordOptions, ParseOptions
+from .types import (
+    Artist,
+    ArtistRole,
+    ArtistSource,
+    Flags,
+    Junk,
+    JunkKind,
+    Mode,
+    ModeOption,
+    ParsedTrack,
+    Position,
+    Timestamp,
+    Version,
+    VersionDelimiter,
+    VersionType,
+    Warning,
+)
+
+__version__ = "0.2.0"  # x-release-please-version
+
+__all__ = [
+    "SPEC_VERSION",
+    "Artist",
+    "ArtistRole",
+    "ArtistSource",
+    "Flags",
+    "FormatOptions",
+    "Junk",
+    "JunkKind",
+    "KeywordOptions",
+    "Mode",
+    "ModeOption",
+    "ParseOptions",
+    "ParsedTrack",
+    "Parser",
+    "Position",
+    "Timestamp",
+    "Version",
+    "VersionDelimiter",
+    "VersionType",
+    "Warning",
+    "__version__",
+    "all_artists",
+    "create_parser",
+    "format_track",
+    "normalize",
+    "parse",
+    "parse_artists",
+]
+
+
+def parse(
+    input: str,
+    *,
+    mode: ModeOption = "auto",
+    uploader: Optional[str] = None,
+    known_artists: Sequence[str] = (),
+    split_and: str = "auto",
+    keywords: Optional[KeywordOptions] = None,
+) -> ParsedTrack:
+    """Parse a track string into a :class:`ParsedTrack`.
+
+    Total for any ``str`` (never raises on string input); raises ``TypeError`` for non-``str``.
+    """
+    return default_parser().parse(
+        input,
+        mode=mode,
+        uploader=uploader,
+        known_artists=known_artists,
+        split_and=split_and,
+        keywords=keywords,
+    )
+
+
+def parse_artists(
+    input: str,
+    *,
+    mode: ModeOption = "auto",
+    uploader: Optional[str] = None,
+    known_artists: Sequence[str] = (),
+    split_and: str = "auto",
+    keywords: Optional[KeywordOptions] = None,
+) -> list[Artist]:
+    """Split an artist string into credits (R10). Every result has ``source == "artist"``."""
+    return default_parser().parse_artists(
+        input,
+        mode=mode,
+        uploader=uploader,
+        known_artists=known_artists,
+        split_and=split_and,
+        keywords=keywords,
+    )
+
+
+def create_parser(**options: Any) -> Parser:
+    """A :class:`Parser` with ``keywords`` compiled once.
+
+    Accepts the same keyword arguments as :func:`parse`. Per-call options passed to
+    ``Parser.parse`` / ``Parser.parse_artists`` are merged over these; ``None`` does not
+    override, and per-call ``keywords`` are merged with the base ones.
+    """
+    return Parser(**options)

trackparse/_artists.py

@@ -0,0 +1,101 @@
+"""R7: the artist side."""
+
+from __future__ import annotations
+
+from typing import NamedTuple, Optional
+
+from ._classify import Feat, Flag, Junk, Producer, Site, Year, classify
+from ._context import Ctx
+from ._credits import Credit, ListOptions, PositionedYear, split_credits
+from ._mode import PositionedJunk
+from ._scanner import PH, Skel, groups_of, remove_groups, slice_skel, trim_skel
+from ._words import char_at, word_spans
+
+
+class ArtistSideResult:
+    __slots__ = ("clean", "credits", "explicit", "junk", "unknown_artist", "years")
+
+    def __init__(self) -> None:
+        self.credits: list[Credit] = []
+        self.junk: list[PositionedJunk] = []
+        self.years: list[PositionedYear] = []
+        self.unknown_artist = False
+        #: R7.1: artist-side Flag groups.
+        self.explicit = False
+        self.clean = False
+
+
+class FeatMarker(NamedTuple):
+    start: int
+    end: int
+    marker: str
+
+
+def find_feat_marker(s: Skel, ctx: Ctx, frm: int = 0) -> Optional[FeatMarker]:
+    """R7.2: leftmost unbracketed feat marker with a space (or placeholder) left and a space
+    right."""
+    spans = word_spans(s.text)
+    words = [w.text for w in spans]
+    for i, span in enumerate(spans):
+        if span.start < frm:
+            continue
+        before = char_at(s.text, span.start - 1)
+        if before != " " and before != PH:
+            continue
+        m = ctx.t.feat_markers.match_at(words, i)
+        if m is None:
+            continue
+        last = spans[i + m.length - 1]
+        if char_at(s.text, last.end) != " ":
+            continue
+        return FeatMarker(span.start, last.end, s.text[span.start : last.end])
+    return None
+
+
+def parse_artist_side(side: Skel, ctx: Ctx) -> ArtistSideResult:
+    """R7.1–R7.5 over an artist-side skeleton."""
+    result = ArtistSideResult()
+    removed: set[int] = set()
+
+    # R7.1
+    for _, group in groups_of(side):
+        c = classify(group.inner, Site("artist", group.open, group.pos), ctx)
+        if isinstance(c, (Feat, Producer)):
+            result.credits.extend(c.credits)
+            result.years.extend(c.years)
+            if c.unknown:
+                result.unknown_artist = True
+        elif isinstance(c, Flag):
+            if c.flag == "explicit":
+                result.explicit = True
+            else:
+                result.clean = True
+        elif isinstance(c, Year):
+            result.years.append(PositionedYear(c.year, group.pos))
+        elif isinstance(c, Junk):
+            result.junk.append(PositionedJunk(group.inner, c.junk_kind, group.pos))
+        else:
+            continue
+        removed.add(group.pos)
+    text = remove_groups(side, removed)
+
+    # R7.2
+    feat = find_feat_marker(text, ctx)
+    main = trim_skel(slice_skel(text, 0, feat.start)) if feat is not None else trim_skel(text)
+    main_list = split_credits(main, ListOptions("primary", "artist", None, True, False), ctx)
+    result.credits.extend(main_list.credits)
+    result.years.extend(main_list.years)
+    if main_list.unknown:
+        result.unknown_artist = True
+    if feat is not None:
+        featured = split_credits(
+            trim_skel(slice_skel(text, feat.end)),
+            ListOptions("featured", "artist", feat.marker, False, True),
+            ctx,
+        )
+        result.credits.extend(featured.credits)
+        result.years.extend(featured.years)
+        if featured.unknown:
+            result.unknown_artist = True
+    result.credits.sort(key=lambda c: c.pos)
+    return result

trackparse/_assemble.py

@@ -0,0 +1,141 @@
+"""R9: assembly and dedup."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Optional, Protocol, TypeVar, cast
+
+from ._classify import VersionDraft
+from ._credits import Credit
+from ._words import dedup_key
+from .types import Artist, ArtistRole, ArtistSource, Version, VersionDelimiter, VersionType
+
+_PRECEDENCE = {"primary": 2, "featured": 1, "producer": 0, "remixer": 0}
+
+
+def to_artist(c: Credit) -> Artist:
+    return Artist(
+        name=c.name,
+        role=cast(ArtistRole, c.role),
+        joiner=c.joiner,
+        source=cast(ArtistSource, c.source),
+    )
+
+
+class _Entry:
+    __slots__ = ("alive", "joiner", "list", "name", "role", "source")
+
+    def __init__(self, c: Credit) -> None:
+        self.name = c.name
+        self.role = c.role
+        self.joiner = c.joiner
+        self.source = c.source
+        self.list = c.list
+        self.alive = True
+
+
+class _Lists:
+    """Alive members of every credit list, in entry order (R7.6 bookkeeping)."""
+
+    def __init__(self, entries: list[_Entry]) -> None:
+        self._members: dict[int, list[_Entry]] = {}
+        for e in entries:
+            self._members.setdefault(e.list, []).append(e)
+
+    def pass_joiner(self, e: _Entry, joiner: Optional[str]) -> None:
+        """R7.6: ``e`` leaves its list. If it was the list's first remaining name, the next
+        remaining name of that list takes ``joiner``."""
+        members = [x for x in self._members.get(e.list, []) if x.alive]
+        if not members or members[0] is not e:
+            return
+        if len(members) > 1:
+            members[1].joiner = joiner
+
+    def move(self, e: _Entry, new_list: int, entries: list[_Entry]) -> None:
+        """``e`` joins ``new_list`` (kept in global entry order, like the JS filter)."""
+        old = self._members.get(e.list, [])
+        if e in old:
+            old.remove(e)
+        e.list = new_list
+        order = {id(x): i for i, x in enumerate(entries)}
+        lst = self._members.setdefault(new_list, [])
+        lst.append(e)
+        lst.sort(key=lambda x: order[id(x)])
+
+
+def dedup_artists(credits: Sequence[Credit]) -> list[Artist]:
+    """R9.2: keep the first occurrence. A later lower/equal-precedence duplicate is removed
+    (R7.6 joiner inheritance); a later higher-precedence duplicate (role upgrade) gives the kept
+    entry its role, joiner and source, and the kept entry moves into that occurrence's list."""
+    entries = [_Entry(c) for c in credits]
+    lists = _Lists(entries)
+    index: dict[str, _Entry] = {}
+    for e in entries:
+        # R9.2: producers are a separate credit class, deduped only among themselves.
+        key = ("p:" if e.role == "producer" else "c:") + dedup_key(e.name)
+        kept = index.get(key)
+        if kept is None:
+            index[key] = e
+            continue
+        if _PRECEDENCE.get(e.role, 0) > _PRECEDENCE.get(kept.role, 0):
+            lists.pass_joiner(kept, kept.joiner)
+            kept.role = e.role
+            kept.joiner = e.joiner
+            kept.source = e.source
+            e.alive = False
+            lists.move(kept, e.list, entries)
+        else:
+            lists.pass_joiner(e, e.joiner)
+            e.alive = False
+    return [
+        Artist(
+            name=e.name,
+            role=cast(ArtistRole, e.role),
+            joiner=e.joiner,
+            source=cast(ArtistSource, e.source),
+        )
+        for e in entries
+        if e.alive
+    ]
+
+
+def to_version(v: VersionDraft) -> Version:
+    return Version(
+        type=cast(VersionType, v.type),
+        raw=v.raw,
+        artists=tuple(to_artist(a) for a in v.artists),
+        modifiers=tuple(v.modifiers),
+        descriptor=v.descriptor,
+        year=v.year,
+        unknown_artist=v.unknown_artist,
+        delimiter=cast(VersionDelimiter, v.delimiter),
+    )
+
+
+def render_version(raw: str, delimiter: str) -> str:
+    """R9.4: a version rendered with its delimiter."""
+    if delimiter == "(":
+        return f"({raw})"
+    if delimiter == "[":
+        return f"[{raw}]"
+    if delimiter == "{":
+        return f"{{{raw}}}"
+    return f"- {raw}"
+
+
+def full_title_of(title: str, versions: Sequence[Version]) -> str:
+    parts = [title, *(render_version(v.raw, v.delimiter) for v in versions)]
+    return " ".join(p for p in parts if len(p) > 0)
+
+
+class _HasPos(Protocol):
+    @property
+    def pos(self) -> int: ...
+
+
+T = TypeVar("T", bound=_HasPos)
+
+
+def by_pos(items: Sequence[T]) -> list[T]:
+    """Stable sort by the ``pos`` attribute (like the JS sort)."""
+    return sorted(items, key=lambda x: x.pos)