lemony-lrc-parser 0.3.0__py3-none-any.whl

lemony_lrc_parser/__init__.py

@@ -0,0 +1,85 @@
+"""lemony-lrc-parser —— 简洁的 Python LRC 歌词解析器.
+
+公共 API 分成三层:
+
+1. **面向对象入口** (推荐) : :class:`Lyrics` 及其 :meth:`~Lyrics.loads` /
+   :meth:`~Lyrics.dumps` 方法.
+
+   .. code-block:: python
+
+       from lemony_lrc_parser import Lyrics
+
+       lyrics = Lyrics.loads(lrc_text)
+       for line in lyrics:
+           print(line.start, line.text)
+       lrc_out = lyrics.dumps()
+
+2. **顶层便捷函数** (等价于 :class:`Lyrics` 的方法) : :func:`loads` /
+   :func:`dumps`, 风格对齐 ``json`` / ``pickle``.
+
+   .. code-block:: python
+
+       import lemony_lrc_parser as llp
+
+       lyrics = llp.loads(lrc_text)
+       out = llp.dumps(lyrics)
+
+3. **底层函数与工具**: :func:`parse_lrc` / :func:`parse_line` / :func:`dump_lrc`
+   以及时间标签工具 :func:`format_timetag` / :func:`parse_timetag`.
+"""
+
+from __future__ import annotations
+
+from .exceptions import (
+    InvalidLyricsError,
+    LyricsParserError,
+    ProgrammingError,
+    TimestampUnderflowError,
+)
+from .models import (
+    BasicLyricLine,
+    LyricLine,
+    Lyrics,
+    LyricToken,
+    ParseOptions,
+    SerializationOptions,
+)
+from .parser import parse_line, parse_lrc
+from .serializer import dump_lrc
+from .timetag import format_timetag, parse_timetag
+
+__all__ = [
+    "BasicLyricLine",
+    "LyricLine",
+    "LyricToken",
+    "Lyrics",
+    "InvalidLyricsError",
+    "LyricsParserError",
+    "ProgrammingError",
+    "TimestampUnderflowError",
+    "ParseOptions",
+    "SerializationOptions",
+    "dumps",
+    "loads",
+    "dump_lrc",
+    "parse_line",
+    "parse_lrc",
+    "format_timetag",
+    "parse_timetag",
+]
+
+
+def loads(s: str, *, options: ParseOptions | None = None) -> Lyrics:
+    """从 LRC 字符串解析出一份 :class:`Lyrics`.
+
+    等价于 :meth:`Lyrics.loads`.
+    """
+    return Lyrics.loads(s, options=options)
+
+
+def dumps(lyrics: Lyrics, *, options: SerializationOptions | None = None) -> str:
+    """把 :class:`Lyrics` 序列化为 LRC 字符串.
+
+    等价于 ``lyrics.dumps(options=options)``
+    """
+    return lyrics.dumps(options=options)

lemony_lrc_parser/exceptions.py

@@ -0,0 +1,14 @@
+class LyricsParserError(Exception):
+    pass
+
+
+class InvalidLyricsError(LyricsParserError):
+    pass
+
+
+class TimestampUnderflowError(LyricsParserError):
+    pass
+
+
+class ProgrammingError(LyricsParserError):
+    pass

lemony_lrc_parser/models.py

@@ -0,0 +1,269 @@
+"""数据模型.
+
+定义 LRC 歌词的核心数据结构: :class:`LyricToken`、:class:`LyricLine` 和
+作为顶层容器的 :class:`Lyrics`.
+
+本模块只承载数据层语义; 解析 (LRC 文本 → :class:`Lyrics`) 与序列化
+ (:class:`Lyrics` → LRC 文本) 的实现分别位于 :mod:`.parser` 与
+:mod:`.serializer`, 这里仅通过延迟导入把它们暴露成 :class:`Lyrics` 的方法.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from copy import deepcopy
+from dataclasses import dataclass, field
+from typing import overload
+
+from .exceptions import ProgrammingError, TimestampUnderflowError
+
+__all__ = [
+    "BasicLyricLine",
+    "LyricLine",
+    "LyricToken",
+    "Lyrics",
+    "ParseOptions",
+    "SerializationOptions",
+]
+
+
+@dataclass
+class ParseOptions:
+    """解析选项.
+
+    Attributes:
+        fill_implicit_line_end: 若为 ``True``, 则当某行没有显式结束时间时,
+            自动用下一行的开始时间作为其结束时间.
+    """
+
+    fill_implicit_line_end: bool = False
+
+
+@dataclass
+class SerializationOptions:
+    """序列化选项.
+
+    Attributes:
+        with_metadata: 是否输出 metadata 段.
+        use_bracket_for_byword_tag: 逐字标签使用 ``[...]`` 而非 ``<...>``. 在 foobar2000 等老式播放器上可能会有用.
+        line_tag_decimal_length: 行标签毫秒位数 (默认 2).
+        word_tag_decimal_length: 逐字标签毫秒位数 (默认 2).
+    """
+
+    with_metadata: bool = True
+    use_bracket_for_byword_tag: bool = False
+    line_tag_decimal_length: int = 2
+    word_tag_decimal_length: int = 2
+
+    def __post_init__(self) -> None:
+        """校验参数合法性."""
+        from .timetag import MAX_TAIL_DIGITS, MIN_TAIL_DIGITS
+
+        for f in ("line_tag_decimal_length", "word_tag_decimal_length"):
+            val = getattr(self, f)
+            if not MIN_TAIL_DIGITS <= val <= MAX_TAIL_DIGITS:
+                raise ProgrammingError(
+                    f"{f} must be between {MIN_TAIL_DIGITS} and {MAX_TAIL_DIGITS}, got {val}"
+                )
+
+
+@dataclass
+class LyricToken:
+    """一个歌词词元 (可以是一个字、一个词, 或整行纯文本) .
+
+    Attributes:
+        content: 词元的文本内容.
+        start: 开始时间 (毫秒) , 未知时为 ``None``.
+        end: 结束时间 (毫秒) , 未知时为 ``None``.
+    """
+
+    content: str = ""
+    start: int | None = None
+    end: int | None = None
+
+
+#: 一行歌词主体 (由若干 :class:`LyricToken` 组成的线性序列) .
+#:
+#: 对于单段整行歌词, 此列表长度通常为 1; 对于逐字歌词, 长度为各词元数量.
+BasicLyricLine = list[LyricToken]
+
+
+@dataclass
+class LyricLine:
+    """一行歌词.
+
+    Attributes:
+        start: 行开始时间 (毫秒) .
+        end: 行结束时间 (毫秒) .
+        content: 主语言行内容, 见 :data:`BasicLyricLine`.
+        reference_lines: 参考行列表, 常用于存放翻译/音译等辅助行.
+    """
+
+    start: int | None = None
+    end: int | None = None
+    content: BasicLyricLine = field(default_factory=list)
+    reference_lines: list[BasicLyricLine] = field(default_factory=list)
+
+    @property
+    def text(self) -> str:
+        """拼接整行主语言的纯文本 (便于日志与简单展示) ."""
+        return "".join(word.content for word in self.content)
+
+
+@dataclass
+class Lyrics:
+    """一份完整的歌词.
+
+    Attributes:
+        lines: 按时间顺序排列的歌词行.
+        metadata: 元数据键值对 (如 ``ti``、``ar``、``offset`` 等) .
+
+    :class:`Lyrics` 同时是序列容器, 可直接 ``for line in lyrics`` 迭代、
+    ``len(lyrics)`` 取行数, 或通过下标/切片访问具体行.
+    """
+
+    lines: list[LyricLine] = field(default_factory=list)
+    metadata: dict[str, str] = field(default_factory=dict)
+
+    def __iter__(self) -> Iterator[LyricLine]:
+        return iter(self.lines)
+
+    def __len__(self) -> int:
+        return len(self.lines)
+
+    @overload
+    def __getitem__(self, index: int) -> LyricLine: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list[LyricLine]: ...
+
+    def __getitem__(self, index: int | slice) -> LyricLine | list[LyricLine]:
+        return self.lines[index]
+
+    def __add__(self, other: Lyrics) -> Lyrics:
+        if not isinstance(other, Lyrics):
+            return NotImplemented
+        return self.combine(other)
+
+    def combine(self, other: Lyrics, *, other_as_refline_only: bool = True) -> Lyrics:
+        """将另一份 :class:`Lyrics` 合并进当前对象, 返回新实例.
+
+        常见用途是把翻译版本合并到主歌词: 翻译的每一行会被挂在 ``self`` 中
+        同 ``start`` 行的 :attr:`LyricLine.reference_lines` 列表里.
+
+        Args:
+            other: 要合并进来的另一份歌词.
+            other_as_refline_only: 若为 ``True`` (默认) , ``other`` 中在
+                ``self`` 里找不到对应时间点的行会被丢弃; 若为 ``False``,
+                这些行会被保留为新行.
+
+        Returns:
+            合并后的新 :class:`Lyrics` 对象; ``self`` 与 ``other`` 均不受影响.
+        """
+        new = Lyrics()
+        # metadata 以 self 为准, other 作为补充
+        new.metadata.update(other.metadata)
+        new.metadata.update(self.metadata)
+
+        pool: dict[int, LyricLine] = {}
+        for line in self.lines:
+            if line.start is None:
+                continue
+            # 深拷贝 self 的行, 避免污染原始对象
+            pool[line.start] = deepcopy(line)
+        for line in other.lines:
+            if line.start is None:
+                continue
+            if line.start in pool:
+                # 深拷贝 other 的行内容, 避免共享引用
+                pool[line.start].reference_lines.append(deepcopy(line.content))
+                pool[line.start].reference_lines.extend(
+                    deepcopy(rl) for rl in line.reference_lines
+                )
+            elif not other_as_refline_only:
+                pool[line.start] = deepcopy(line)
+
+        new.lines = sorted(pool.values(), key=lambda line: line.start or 0)
+        return new
+
+    @classmethod
+    def loads(cls, s: str, *, options: ParseOptions | None = None) -> Lyrics:
+        """从 LRC 字符串解析出一份 :class:`Lyrics`.
+
+        Args:
+            s: LRC 源文本.
+            options: 解析选项.
+        """
+        from .parser import parse_lrc
+
+        return parse_lrc(s, options=options)
+
+    def dumps(self, *, options: SerializationOptions | None = None) -> str:
+        """把当前对象序列化为 LRC 字符串.
+
+        Args:
+            options: 序列化选项.
+        """
+        from .serializer import dump_lrc
+
+        return dump_lrc(self, options=options)
+
+    def apply_delta(self, ms: int) -> Lyrics:
+        """深拷贝当前对象并在新副本上应用时间偏移, 返回新对象.
+
+        该方法**不修改**原始对象, 而是返回一个时间戳已被整体偏移的新
+        :class:`Lyrics`.
+
+        这里的 ms 直接加在时间戳上, 所以用了 delta 这个词而不是 offset.
+
+        若偏移后存在任何时间戳 < 0, 直接抛出 :class:`TimestampUnderflowError`,
+        由调用方自行处理 (例如先从 ``metadata.offset`` 读取值再传入).
+
+        Args:
+            ms: 要加到每个时间戳上的毫秒数.
+
+        Returns:
+            应用了偏移后的新 :class:`Lyrics` 对象.
+
+        Raises:
+            TimestampUnderflowError: 偏移后会导致某个时间戳变为负数.
+        """
+        from .offset import apply_delta, iter_all_timestamps
+
+        if ms == 0:
+            return deepcopy(self)
+
+        # 先做下溢检测, 避免异常路径上的 deepcopy 浪费
+        all_times = list(iter_all_timestamps(self))
+        if all_times:
+            min_time = min(all_times)
+            if min_time + ms < 0:
+                raise TimestampUnderflowError(
+                    f"Applying offset={ms}ms would make minimum "
+                    f"timestamp {min_time}ms negative"
+                )
+
+        result = deepcopy(self)
+        apply_delta(result, ms)
+        return result
+
+    def __lshift__(self, ms: int) -> Lyrics:
+        """左移运算符: ``lyrics << ms`` 等价于 ``lyrics.apply_delta(-ms)``.
+
+        语义: 正数 → 歌词提前出现.
+        """
+        if not isinstance(ms, int):
+            return NotImplemented
+        return self.apply_delta(-ms)
+
+    def __rshift__(self, ms: int) -> Lyrics:
+        """右移运算符: ``lyrics >> ms`` 等价于 ``lyrics.apply_delta(ms)``.
+
+        语义: 正数 → 歌词延后出现.
+        """
+        if not isinstance(ms, int):
+            return NotImplemented
+        return self.apply_delta(ms)
+
+    def __str__(self) -> str:
+        return self.dumps()

lemony_lrc_parser/offset.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from .models import BasicLyricLine, Lyrics
+
+__all__ = [
+    "apply_delta",
+    "iter_all_timestamps",
+]
+
+
+def apply_delta(lyrics: Lyrics, delta: int) -> None:
+    """将所有时间戳增加 ``delta`` ms
+
+    注意此处为底层函数没有下溢保护, 且为原地修改"""
+    for line in lyrics.lines:
+        if line.start is not None:
+            line.start += delta
+        if line.end is not None:
+            line.end += delta
+        _apply_word_delta(line.content, delta)
+        for refline in line.reference_lines:
+            _apply_word_delta(refline, delta)
+
+
+def _apply_word_delta(words: BasicLyricLine, delta: int) -> None:
+    for word in words:
+        if word.start is not None:
+            word.start += delta
+        if word.end is not None:
+            word.end += delta
+
+
+def iter_all_timestamps(lyrics: Lyrics) -> Iterator[int]:
+    """迭代 :class:`Lyrics` 中出现过的所有时间戳 (含参考行)."""
+    for line in lyrics.lines:
+        if line.start is not None:
+            yield line.start
+        if line.end is not None:
+            yield line.end
+        yield from _iter_word_timestamps(line.content)
+        for refline in line.reference_lines:
+            yield from _iter_word_timestamps(refline)
+
+
+def _iter_word_timestamps(words: BasicLyricLine) -> Iterator[int]:
+    """从一个 word 序列中迭代出所有非空时间戳."""
+    for word in words:
+        if word.start is not None:
+            yield word.start
+        if word.end is not None:
+            yield word.end