light-ass 0.1.0__py3-none-any.whl

light_ass/__init__.py

@@ -0,0 +1,8 @@
+from . import tag_parser, subtitle, events, styles, script_info
+from .subtitle import *
+
+__all__ = [
+    "load",
+    "from_string",
+    "Subtitle",
+]

light_ass/constants.py

@@ -0,0 +1,24 @@
+import re
+
+
+class AssSectionHeader:
+    SCRIPT_INFO = "Script Info"
+    ASS_STYLE = "V4+ Styles"
+    EVENTS = "Events"
+    # AEGISUB_PROJECT = "Aegisub Project Garbage"
+    # AEGISUB_EXTRADATA = "Aegisub Extradata"
+    # FONTS = "Fonts"
+    # GRAPHICS = "Graphics"
+
+
+DEFAULT_STYLES_FORMAT = (
+    "Name", "Fontname", "Fontsize", "PrimaryColour", "SecondaryColour", "OutlineColour", "BackColour",
+    "Bold", "Italic", "Underline", "StrikeOut", "ScaleX", "ScaleY", "Spacing", "Angle", "BorderStyle",
+    "Outline", "Shadow", "Alignment", "MarginL", "MarginR", "MarginV", "Encoding",
+)
+
+DEFAULT_EVENTS_FORMAT = ("Layer", "Start", "End", "Style", "Name", "MarginL", "MarginR", "MarginV", "Effect", "Text")
+
+SECTION_PATTERN = re.compile(r"^\s*\[([^]]+)]\s*")
+
+OVERRIDE_BLOCK_PATTERN = re.compile(r"(?<!\\){([^}]*)}")

light_ass/events.py

@@ -0,0 +1,127 @@
+from collections.abc import Sequence
+
+from .ass_types.ass_time import AssTime
+from .constants import OVERRIDE_BLOCK_PATTERN
+from .tag_parser import Tag, parse_tags
+from .utils import validate_value
+
+
+class Dialog(dict):
+    _formats = {
+        "comment": bool,
+        "layer": int,
+        "start": AssTime,
+        "end": AssTime,
+        "style": str,
+        "name": str,
+        "margin_l": int,
+        "margin_r": int,
+        "margin_v": int,
+        "effect": str,
+        "text": str,
+    }
+    _alias = {
+        "commented": "comment",
+        "start_time": "start",
+        "end_time": "end",
+        "actor": "name",
+    }
+
+    comment: bool
+    layer: int
+    start: AssTime
+    end: AssTime
+    style: str
+    name: str
+    margin_l: int
+    margin_r: int
+    margin_v: int
+    effect: str
+    text: str
+    commented: bool
+    start_time: AssTime
+    end_time: AssTime
+    actor: str
+
+    def __init__(self, **kwargs) -> None:
+        if set(kwargs.keys()) != set(self._formats.keys()):
+            raise ValueError("Keys of kwargs must equal formats")
+        super().__init__()
+        for key, value in kwargs.items():
+            self[key] = self.validate_value(key, value)
+
+    def __getattr__(self, name: str):
+        if name in self._alias:
+            name = self._alias[name]
+        if name in self._formats:
+            return self[name]
+        else:
+            raise AttributeError(f"{name} is not a valid attribute")
+
+    def __setattr__(self, name: str, value):
+        if name in self._alias:
+            name = self._alias[name]
+        if name in self._formats:
+            self[name] = Dialog.validate_value(name, value)
+        else:
+            raise AttributeError(f"{name} is not a valid attribute")
+
+    def __repr__(self) -> str:
+        return "Dialog({})".format(
+            ",".join(f"{key}={value}" for key, value in self.items())
+        )
+
+    def __str__(self) -> str:
+        dialog_line = []
+        for key, value in self.items():
+            if key == "comment":
+                continue
+            if type(value) is float:
+                value = f"{value:g}"
+            dialog_line.append(str(value))
+        return "{}: {}".format("Comment" if self.comment else "Dialogue", ",".join(dialog_line))
+
+    def shift(self, ms: int) -> None:
+        self.start += ms
+        self.end += ms
+
+    def parse_tags(self) -> list[Tag]:
+        return parse_tags(self.text)
+
+    @property
+    def text_stripped(self) -> str:
+        return OVERRIDE_BLOCK_PATTERN.sub("", self.text)
+
+    @staticmethod
+    def validate_value(key, value):
+        if key in Dialog._alias:
+            key = Dialog._alias[key]
+        try:
+            return validate_value(Dialog._formats[key], value)
+        except ValueError:
+            raise ValueError(f"Invalid value for {key}: {value}")
+
+
+class Events(list[Dialog]):
+    def pop(self, index: int | Sequence[int] = -1):
+        if isinstance(index, int):
+            index = (index,)
+        for i in sorted(index, reverse=True):
+            super().pop(i)
+
+    def shift(self, ms: int, range_: Sequence[int] | None = None):
+        """
+        Shift the start and end time of events by milliseconds.
+        :param ms: The amount of milliseconds to shift the events by.
+        :param range_: The range of events to shift. If None, all events will be shifted.
+        :return: None
+        """
+        if range_ is None:
+            range_ = range(0, len(self))
+        for i in range_:
+            self[i].shift(ms)
+
+    def sort(self, *, key = None, reverse = False):
+        if key is None:
+            key = lambda x: x.start
+        super().sort(key = key, reverse = reverse)

light_ass/script_info.py

@@ -0,0 +1,97 @@
+from typing import Any, Self, Literal
+
+from .utils import validate_value
+
+ScriptInfoKeys = Literal[
+    "Title",
+    "Original Script",
+    "Original Translation",
+    "Original Editing",
+    "Original Timing",
+    "Synch Point",
+    "Script Updated By",
+    "ScriptType",
+    "Update Details",
+    "PlayResX",
+    "PlayResY",
+    "PlayDepth",
+    "ScaledBorderAndShadow",
+    "WrapStyle",
+    "YCbCr Matrix",
+    "Collisions",
+    "Timer",
+    "LayoutResX",
+    "LayoutResY",
+    # libass extensions
+    "Kerning",
+    "Language",
+]
+
+
+class ScriptInfo(dict):
+    _formats = {
+        "Title": str,
+        "Original Script": str,
+        "Original Translation": str,
+        "Original Editing": str,
+        "Original Timing": str,
+        "Synch Point": str,
+        "Script Updated By": str,
+        "ScriptType": str,
+        "Update Details": str,
+        "PlayResX": int,
+        "PlayResY": int,
+        "PlayDepth": int,
+        "ScaledBorderAndShadow": {"yes": True, "no": False},
+        "WrapStyle": (0, 1, 2, 3),
+        "YCbCr Matrix": ("None", "TV.601", "PC.601", "TV.709", "PC.709", "TV.FCC", "PC.FCC", "TV.240M", "PC.240M"),
+        "Collisions": ("Normal", "Reverse"),
+        "Timer": float,
+        "LayoutResX": int,
+        "LayoutResY": int,
+        # libass extensions
+        "Kerning": {"yes": True, "no": False},
+        "Language": str,
+    }
+
+    def __init__(self, info: Self | dict[str, Any] | None = None):
+        super().__init__()
+        if isinstance(info, dict):
+            for key, value in info.items():
+                self[key] = value
+
+    def sort(self):
+        mapping = {key: i for i, key in enumerate(self._formats.keys())}
+        new = sorted(self.items(), key=lambda x: mapping.get(x[0], 99))
+        self.clear()
+        self.update(new)
+
+    def __getitem__(self, key: ScriptInfoKeys | str):
+        return super().__getitem__(key)
+
+    def __setitem__(self, key: ScriptInfoKeys | str, value):
+        if value is None:
+            self.pop(key)
+        else:
+            super().__setitem__(key, self.validate_value(key, value))
+
+    def __repr__(self) -> str:
+        return f"ScriptInfo({super().__repr__()})"
+
+    def __str__(self) -> str:
+        infos = []
+        for key, value in self.items():
+            if isinstance(self._formats[key], dict):
+                rev_dict = {v: k for k, v in self._formats[key].items()}
+                value = rev_dict[value]
+            infos.append(f"{key}: {value}")
+        return "\n".join(infos)
+
+    @staticmethod
+    def validate_value(key, value):
+        if key not in ScriptInfo._formats:
+            return value
+        try:
+            return validate_value(ScriptInfo._formats[key], value)
+        except ValueError:
+            raise ValueError(f"Invalid value for {key}: {value}")

light_ass/styles.py

@@ -0,0 +1,191 @@
+from collections.abc import Iterable
+from typing import Self, Literal
+
+from .ass_types.ass_color import AssColor
+from .utils import validate_value
+
+StyleKeys = Literal[
+    "name",
+    "fontname",
+    "fontsize",
+    "primary_colour",
+    "secondary_colour",
+    "outline_colour",
+    "back_colour",
+    "bold",
+    "italic",
+    "underline",
+    "strike_out",
+    "scale_x",
+    "scale_y",
+    "spacing",
+    "angle",
+    "border_style",
+    "outline",
+    "shadow",
+    "alignment",
+    "margin_l",
+    "margin_r",
+    "margin_v",
+    "encoding",
+    "color1",
+    "color2",
+    "color3",
+    "color4",
+    "align",
+]
+
+
+class Style(dict):
+    _formats = {
+        "name": str,
+        "fontname": str,
+        "fontsize": float,
+        "primary_colour": AssColor,
+        "secondary_colour": AssColor,
+        "outline_colour": AssColor,
+        "back_colour": AssColor,
+        "bold": {"0": False, "-1": True},
+        "italic": {"0": False, "-1": True},
+        "underline": {"0": False, "-1": True},
+        "strike_out": {"0": False, "-1": True},
+        "scale_x": float,
+        "scale_y": float,
+        "spacing": float,
+        "angle": float,
+        "border_style": (1, 3, 4),  # 4 for libass
+        "outline": float,
+        "shadow": float,
+        "alignment": (1, 2, 3, 4, 5, 6, 7, 8, 9),
+        "margin_l": int,
+        "margin_r": int,
+        "margin_v": int,
+        "encoding": int,
+    }
+    _alias = {
+        "color1": "primary_colour",
+        "color2": "secondary_colour",
+        "color3": "outline_colour",
+        "color4": "back_colour",
+        "align": "alignment",
+    }
+
+    name: str
+    fontname: str
+    fontsize: float
+    primary_colour: AssColor
+    secondary_colour: AssColor
+    outline_colour: AssColor
+    back_colour: AssColor
+    bold: bool
+    italic: bool
+    underline: bool
+    strike_out: bool
+    scale_x: float
+    scale_y: float
+    spacing: float
+    angle: float
+    border_style: int
+    outline: float
+    shadow: float
+    alignment: int
+    margin_l: int
+    margin_r: int
+    margin_v: int
+    encoding: int
+
+    color1: AssColor
+    color2: AssColor
+    color3: AssColor
+    color4: AssColor
+    align: int
+
+    def __init__(self, from_: dict | Iterable | None = None, **kwargs):
+        if from_ is not None:
+            kwargs = dict(from_)
+        if set(kwargs.keys()) != set(self._formats.keys()):
+            raise ValueError("Keys of kwargs must equal formats")
+        super().__init__({k: self.validate_value(k, v) for k, v in kwargs.items() if k != "name"})
+        self._name = kwargs["name"]
+
+    @property
+    def name(self):
+        return self._name
+
+    def __getitem__(self, key: StyleKeys | str):
+        if key in self._alias:
+            key = self._alias[key]
+        return super().__getitem__(key)
+
+    def __setitem__(self, key: StyleKeys | str, value):
+        if key in self._alias:
+            key = self._alias[key]
+        if key in self._formats:
+            super().__setitem__(key, self.validate_value(key, value))
+        else:
+            raise KeyError(f"{key} is not a valid key")
+
+    def __getattr__(self, key: str):
+        return self[key]
+
+    def __setattr__(self, key: str, value) -> None:
+        if key.startswith("_"):
+            super().__setattr__(key, value)
+        else:
+            self[key] = value
+
+    def __repr__(self) -> str:
+        return "Style({})".format(",".join(f"{key}={value}" for key, value in self.items()))
+
+    def __str__(self) -> str:
+        style_line = [self.name]
+        for key, value in self.items():
+            if isinstance(self._formats[key], dict):
+                rev_dict = {v: k for k, v in self._formats[key].items()}
+                value = rev_dict[value]
+            elif type(value) is float:
+                value = "{:g}".format(value)
+            style_line.append(str(value))
+        return f"Style: {','.join(style_line)}"
+
+    @staticmethod
+    def validate_value(key, value):
+        if key in Style._alias:
+            key = Style._alias[key]
+        try:
+            return validate_value(Style._formats[key], value)
+        except ValueError:
+            raise ValueError(f"Invalid value for {key}: {value}")
+
+
+class Styles(dict[str, Style]):
+    def __init__(self, from_: Self | dict[str, Style] | None = None):
+        if from_ is None:
+            super().__init__()
+        else:
+            super().__init__(from_)
+
+    def __setitem__(self, key, value):
+        if isinstance(value, Style):
+            value._name = key
+            super().__setitem__(key, value)
+        else:
+            raise TypeError("value must be a Style")
+
+    def __repr__(self):
+        return f"Styles({", ".join(self.keys())})"
+
+    def __str__(self):
+        return "\n".join((str(style) for style in self.values()))
+
+    def set(self, style: Style):
+        self[style.name] = style
+
+    def rename(self, old_name: str, new_name: str):
+        if old_name not in self:
+            raise KeyError(f"{old_name} is not a valid style name")
+        if new_name in self:
+            raise KeyError(f"{new_name} is already a style name")
+        style = self.pop(old_name)
+        style._name = new_name
+        self[new_name] = style

light_ass/subtitle.py

@@ -0,0 +1,215 @@
+import copy
+import pathlib
+from collections import defaultdict
+
+from .constants import SECTION_PATTERN, AssSectionHeader, DEFAULT_STYLES_FORMAT, DEFAULT_EVENTS_FORMAT
+from .events import Dialog, Events
+from .script_info import ScriptInfo
+from .styles import Styles, Style
+from .utils import to_snake_case, detect_file_encoding
+
+__all__ = [
+    "Subtitle",
+    "load",
+    "from_string",
+]
+
+
+class Subtitle:
+    def __init__(self):
+        self.messages = []
+        self.info = ScriptInfo()
+        self.styles = Styles()
+        self.events = Events()
+        self.other_sections = defaultdict(list)
+        self.path: pathlib.Path | None = None
+
+    @classmethod
+    def load(cls, path: pathlib.Path | str, encoding: str | None = None, strict: bool = True,
+             drop_unknown_sections: bool = True) -> "Subtitle":
+        """
+        Load subtitle from file.
+        :param path: Where the subtitle file is located.
+        :param encoding: The encoding of the file. If None, the encoding will be detected.
+        :param strict: If false, ignore warnings.
+        :param drop_unknown_sections: If false, store unknown sections as is.
+        :return: A Subtitle object.
+        """
+        if encoding is None:
+            encoding = detect_file_encoding(str(path)) or "utf-8-sig"
+        doc = cls()
+        doc.path = pathlib.Path(path)
+        with open(path, "r", encoding=encoding) as f:
+            doc._init_from_ass_text(f.read(), strict, drop_unknown_sections)
+        return doc
+
+    @classmethod
+    def from_string(cls, ass_text: str, strict: bool = True, drop_unknown_sections: bool = True) -> "Subtitle":
+        """
+        Load subtitle from an ASS string.
+        :param ass_text: An ASS formatted string.
+        :param strict: If false, ignore warnings.
+        :param drop_unknown_sections: If false, store unknown sections as is.
+        :return: A Subtitle object.
+        """
+        doc = cls()
+        doc._init_from_ass_text(ass_text, strict, drop_unknown_sections)
+        return doc
+
+    def _init_from_ass_text(self, ass_text: str, strict: bool, drop_unknown_sections: bool) -> None:
+        def process_info_line(line: str):
+            if line.startswith((";", "!:")):
+                line = line.removeprefix(";").removeprefix("!:").strip()
+                self.messages.append(line)
+            else:
+                key, _, value = map(str.strip, line.partition(":"))
+                self.info[key] = value
+
+        def parse_format_line(line: str, default):
+            if strict and formats.get(section):
+                raise ValueError(f"{section} Format line already declared")
+            _, _, format_ = line.partition(":")
+            formats[section] = map(str.strip, format_.split(",", len(default)))
+            formats[section] = list(map(to_snake_case, formats[section]))
+
+        def check_format():
+            if not formats.get(section):
+                if strict:
+                    raise ValueError(f"{section} Format line not declare")
+                else:
+                    return False
+            return True
+
+        def process_styles_line(line: str):
+            if line.startswith("Format:"):
+                parse_format_line(line, DEFAULT_STYLES_FORMAT)
+            elif line.startswith("Style:"):
+                if not check_format():
+                    formats[section] = DEFAULT_STYLES_FORMAT
+                _, _, value = map(str.strip, line.partition(":"))
+                self.styles.set(Style(zip(formats[section], value.split(",", len(formats[section]) - 1))))
+            elif strict:
+                raise ValueError(f"Invalid Style line: {line}")
+
+        def process_events_line(line: str):
+            if line.startswith("Format:"):
+                parse_format_line(line, DEFAULT_EVENTS_FORMAT)
+                if formats[section][-1] != "text":
+                    raise ValueError("Text must be the last column in Event format.")
+            elif line.startswith(("Dialogue:", "Comment:")):
+                if not check_format():
+                    formats[section] = DEFAULT_EVENTS_FORMAT
+                _, _, value = map(str.strip, line.partition(":"))
+                event_data = dict(zip(formats[section], value.split(",", len(formats[section]) - 1)))
+                self.events.append(Dialog(comment=line.startswith("Comment:"), **event_data))
+            elif strict:
+                raise ValueError(f"Invalid Event line: {line}")
+
+        def process_other_sections_line(line: str):
+            if not drop_unknown_sections:
+                self.other_sections[section].append(line)
+
+        handlers = {
+            AssSectionHeader.SCRIPT_INFO: process_info_line,
+            AssSectionHeader.ASS_STYLE: process_styles_line,
+            AssSectionHeader.EVENTS: process_events_line,
+        }
+        section = ""
+        formats = {}
+        for line in ass_text.splitlines():
+            line = line.lstrip(" ")
+            if not line:
+                continue
+            if match := SECTION_PATTERN.match(line):
+                section = match.group(1).title()
+            else:
+                handlers.get(section, process_other_sections_line)(line)
+
+        default_info = {
+            "ScaledBorderAndShadow": True,
+            "YCbCr Matrix": "TV.601",
+            "PlayResX": self.info.get("LayoutResX", None) or 1920,
+            "PlayResY": self.info.get("LayoutResY", None) or 1080,
+            "LayoutResX": self.info.get("PlayResX", None) or 1920,
+            "LayoutResY": self.info.get("PlayResY", None) or 1080,
+        }
+        self.info |= default_info | self.info
+
+    def rename_style(self, old_name: str, new_name: str):
+        self.styles.rename(old_name, new_name)
+        for event in self.events:
+            if event.style == old_name:
+                event.style = new_name
+            # tags = event.parse_tags()
+            # flag = False
+            # for tag in tags:
+            #     if tag.name == "r" and tag.value == old_name:
+            #         tag.value = new_name
+            #         flag = True
+            # if flag:
+            #     event.text = "".join(str(tag) for tag in tags)
+
+    def to_string(self) -> str:
+        """
+        Convert the Subtitle object to an ASS formatted string.
+        :return: An ASS formatted string.
+        """
+        lines = ["[Script Info]"]
+        if self.messages:
+            lines.append("\n".join(f"; {message}" for message in self.messages))
+        lines += [str(self.info), "\n[V4+ Styles]",
+                  "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, "
+                  "Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, "
+                  "Shadow, Alignment, MarginL, MarginR, MarginV, Encoding", str(self.styles), "\n[Events]",
+                  "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text"]
+
+        for event in self.events:
+            lines.append(str(event))
+
+        for name, content in self.other_sections.items():
+            lines.append(f"\n[{name}]")
+            lines.extend(content)
+
+        return "\n".join(lines)
+
+    def save(self, path: pathlib.Path | str, encoding: str = "utf-8-sig") -> None:
+        """
+        Save the Subtitle object to the path with the given encoding.
+        :param path: The path to save the subtitle to.
+        :param encoding: The encoding to use when saving the file.
+        :return: None
+        """
+        with open(path, "w", encoding=encoding) as f:
+            f.write(self.to_string())
+
+    def copy(self):
+        """
+        Create a deep copy of the Subtitle object.
+        :return: A deep copy of the Subtitle object.
+        """
+        return copy.deepcopy(self)
+
+    def __repr__(self) -> str:
+        return f"Subtitle(with {len(self.events)} events)"
+
+    def __setattr__(self, key, value):
+        if key == "info":
+            if isinstance(value, ScriptInfo):
+                super().__setattr__(key, value)
+            elif isinstance(value, dict):
+                super().__setattr__(key, ScriptInfo(value))
+            else:
+                raise TypeError(f"Invalid type for info: {type(value)}")
+        elif key == "styles":
+            if isinstance(value, Styles):
+                super().__setattr__(key, value)
+            elif isinstance(value, dict):
+                super().__setattr__(key, Styles(value))
+            else:
+                raise TypeError(f"Invalid type for styles: {type(value)}")
+        else:
+            super().__setattr__(key, value)
+
+
+load = Subtitle.load
+from_string = Subtitle.from_string

light_ass/tag_parser.py

@@ -0,0 +1,413 @@
+from itertools import takewhile, dropwhile
+from typing import Sequence, Any
+
+from .ass_types import AssColor, AssAlpha, AssDrawing
+from .constants import OVERRIDE_BLOCK_PATTERN
+from .utils import parse_int32, parse_positive_int32, parse_float, parse_positive_float, \
+    parse_ass_color, parse_ass_alpha
+
+__all__ = [
+    "Tag",
+    "parse_tags",
+    "join_tags",
+    "is_simple_tag",
+    "is_complex_tag",
+    "is_line_tag",
+    "is_unknown_tag"
+]
+
+_int = parse_int32
+_positive_int = parse_positive_int32
+_float = parse_float
+_positive_float = parse_positive_float
+_ass_color = parse_ass_color
+_ass_alpha = parse_ass_alpha
+
+
+class FallbackError(Exception):
+    pass
+
+
+class InvalidArgError(Exception):
+    pass
+
+
+def is_simple_tag(name: str) -> bool:
+    simple_tags = (
+        "xbord", "ybord", "xshad", "yshad", "fax", "fay", "blur", "fscx", "fscy", "fsc", "fsp", "fs", "bord", "frx",
+        "fry", "frz", "fr", "fn", "alpha", "an", "a", "c", "1c", "2c", "3c", "4c", "1a", "2a", "3a", "4a", "r", "be",
+        "b", "i", "kt", "kf", "K", "ko", "k", "shad", "s", "u", "pbo", "p", "q", "fe"
+    )
+    return name in simple_tags
+
+
+def is_complex_tag(name: str) -> bool:
+    complex_tags = ("t", "clip", "iclip", "move", "fade", "fad", "pos", "org")
+    return name in complex_tags
+
+
+def is_line_tag(name: str) -> bool:
+    line_tags = ("clip", "iclip", "move", "fade", "fad", "pos", "org", "an", "a")
+    return name in line_tags
+
+
+def is_special_tag(name: str) -> bool:
+    special_tags = ("Comment", "Drawing", "Text")
+    return name in special_tags
+
+
+def is_unknown_tag(name: str) -> bool:
+    return not is_special_tag(name) and name not in tag_args
+
+
+def is_nestable_tag(name: str) -> bool:
+    nestable_tags = (
+        "xbord", "ybord", "xshad", "yshad", "fax", "fay", "blur", "fscx", "fscy", "fsp", "fs", "bord", "frx",
+        "fry", "frz", "fr", "alpha", "c", "1c", "2c", "3c", "4c", "1a", "2a", "3a", "4a", "be", "shad", "clip", "iclip"
+    )
+    return name in nestable_tags
+
+
+def format_arg(arg) -> str:
+    match arg:
+        case float():
+            arg = f"{arg:g}"
+        case list():
+            return "".join(map(lambda t: t.to_string(), arg))
+        case AssAlpha():
+            arg = arg.format()
+        case AssColor():
+            arg = arg.format("&H{B}{G}{R}&")
+        case _:
+            arg = str(arg).strip()
+    return arg
+
+
+class Tag:
+    def __init__(self, name: str, args, valid: bool | None = None):
+        self.name = name
+        self.args, self.valid = self.validate_args(name, args)
+        if valid is not None:
+            self.valid = valid
+
+    def __eq__(self, other):
+        return self.name == other.name and self.args == other.args
+
+    def __repr__(self):
+        return f"Tag(name={self.name}, with {len(self.args)} {"arg" if len(self.args) == 1 else "args"})"
+
+    def __str__(self):
+        return self.to_string()
+
+    def to_string(self):
+        if self.is_special_tag:
+            return self.args[0]
+        if len(self.args) == 0:
+            return f"\\{self.name}"
+        elif self.is_simple_tag and len(self.args) == 1:
+            return f"\\{self.name}{format_arg(self.args[0])}"
+        else:
+            return f"\\{self.name}({','.join(map(lambda s: format_arg(s), self.args))})"
+
+    @property
+    def is_simple_tag(self) -> bool:
+        return is_simple_tag(self.name)
+
+    @property
+    def is_complex_tag(self) -> bool:
+        return is_complex_tag(self.name)
+
+    @property
+    def is_line_tag(self) -> bool:
+        return is_line_tag(self.name)
+
+    @property
+    def is_special_tag(self) -> bool:
+        return is_special_tag(self.name)
+
+    @property
+    def is_unknown_tag(self) -> bool:
+        return is_unknown_tag(self.name)
+
+    @staticmethod
+    def _validate_args(name: str, args: Sequence[str]) -> tuple[tuple, bool]:
+        args = tuple(args)
+        validators = None
+        for typ in tag_args[name]:
+            if len(args) == len(typ):
+                validators = typ
+                break
+        if validators is None:
+            return args, False
+        try:
+            args = tuple(func(arg.strip()) for arg, func in zip(args, validators))
+            return args, True
+        except FallbackError:
+            return tuple(), True
+        except InvalidArgError:
+            return tuple(), False
+        except ValueError:
+            return args, False
+
+    @staticmethod
+    def validate_args(name: str, args: Sequence[Any]) -> tuple[tuple, bool]:
+        if is_special_tag(name):
+            return tuple(args), True
+        valid = False
+        args = tuple(map(str, args))
+        if is_simple_tag(name) and len(args) > 1:
+            args = (args[0])
+        if name == "t":
+            if args:
+                last = split_tags(args[-1], True)
+                args, valid = Tag._validate_args(name, args[:-1])
+                args = list(args)
+                args.append(last)
+        elif name in tag_args:
+            args, valid = Tag._validate_args(name, args)
+        return tuple(args), valid
+
+
+def join_tags(tags: list[Tag], skip_comment: bool = False) -> str:
+    """
+    Join tags into text.
+    :param tags: The tags to join.
+    :param skip_comment: Whether to skip comments.
+    :return: The joined text.
+    """
+    if any(not isinstance(tag, Tag) for tag in tags):
+        raise TypeError("All elements must be of type Tag")
+    text = ""
+    in_tag = False
+    for tag in filter(lambda x: not skip_comment or x.name != "Comment", tags):
+        if tag.name in ("Drawing", "Text"):
+            if in_tag:
+                text += "}"
+            text += tag.args[0]
+            in_tag = False
+        else:
+            if not in_tag:
+                text += "{"
+            text += tag.to_string()
+            in_tag = True
+    if in_tag:
+        text += "}"
+    return text
+
+
+def _parse_fs_arg(s: str) -> float | str:
+    if not s:
+        return 0
+    if s.startswith(("+", "-")):
+        return s
+    else:
+        return float(s)
+
+
+def _parse_fn_arg(s: str) -> str:
+    if s == "0":
+        raise FallbackError
+    return s
+
+
+def _parse_an_arg(s: str) -> int:
+    try:
+        val = int(s)
+        if 1 <= val <= 9:
+            return val
+        raise InvalidArgError
+    except ValueError:
+        raise InvalidArgError
+
+
+def _parse_a_arg(s: str) -> int:
+    try:
+        val = int(s)
+        if 1 <= val <= 11:
+            return val if (val & 3) != 0 else 5
+        raise InvalidArgError
+    except ValueError:
+        raise InvalidArgError
+
+
+def _parse_be_arg(s: str) -> int:
+    return max(0, int(parse_float(s) + 0.5))
+
+
+def _parse_b_arg(s: str) -> int:
+    val = parse_int32(s)
+    if val == 0 or val == 1 or val >= 100:
+        return val
+    raise FallbackError
+
+
+def _parse_boolean_arg(s: str) -> int:
+    val = parse_int32(s)
+    if val == 0 or val == 1:
+        return val
+    raise FallbackError
+
+
+def _parse_kx_arg(s: str) -> float:
+    val = parse_float(s)
+    return int(val * 10) / 10
+
+
+# def parse_k_arg(s: str) -> float:
+#     val = parse_float(s)
+#     if val == 100:
+#         raise FallbackError
+#     return int(val * 10) / 10
+
+
+def _parse_q_arg(s: str) -> int:
+    val = parse_int32(s)
+    if 0 <= val <= 3:
+        return val
+    raise InvalidArgError
+
+
+tag_args = {
+    "xbord": ((_positive_float,), ()),
+    "ybord": ((_positive_float,), ()),
+    "xshad": ((_float,), ()),
+    "yshad": ((_float,), ()),
+    "fax": ((_float,), ()),
+    "fay": ((_float,), ()),
+    "iclip": ((_int, _int, _int, _int), (AssDrawing,)),
+    "blur": ((_positive_float,), ()),
+    "fscx": ((_positive_float,), ()),
+    "fscy": ((_positive_float,), ()),
+    "fsc": ((),),
+    "fsp": ((_float,),),
+    "fs": ((_parse_fs_arg,), ()),
+    "bord": ((_float,), ()),
+    "move": ((_float, _float, _float, _float), (_float, _float, _float, _float, _int, _int)),
+    "frx": ((_float,), ()),
+    "fry": ((_float,), ()),
+    "frz": ((_float,), ()),
+    "fr": ((_float,), ()),
+    "fn": ((_parse_fn_arg,), ()),
+    "alpha": ((AssAlpha,), ()),
+    "an": ((_int,),),
+    "a": ((_int,),),
+    "pos": ((_float, _float),),
+    "fade": ((_int, _int), (AssAlpha, AssAlpha, AssAlpha, _int, _int, _int, _int)),
+    "fad": ((_int, _int), (AssAlpha, AssAlpha, AssAlpha, _int, _int, _int, _int)),
+    "org": ((_float, _float),),
+    "clip": ((_int, _int, _int, _int), (AssDrawing,)),
+    "c": ((_ass_color,), ()),
+    "1c": ((_ass_color,), ()),
+    "2c": ((_ass_color,), ()),
+    "3c": ((_ass_color,), ()),
+    "4c": ((_ass_color,), ()),
+    "1a": ((AssAlpha,), ()),
+    "2a": ((AssAlpha,), ()),
+    "3a": ((AssAlpha,), ()),
+    "4a": ((AssAlpha,), ()),
+    "r": ((str,), ()),
+    "be": ((_parse_be_arg,), ()),
+    "b": ((_parse_b_arg,), ()),
+    "i": ((_parse_boolean_arg,), ()),
+    "kt": ((_parse_kx_arg,),),
+    "kf": ((_parse_kx_arg,),),
+    "K": ((_parse_kx_arg,),),
+    "ko": ((_parse_kx_arg,),),
+    "k": ((_parse_kx_arg,),),
+    "shad": ((_positive_float,), ()),
+    "s": ((_parse_boolean_arg,), ()),
+    "u": ((_parse_boolean_arg,), ()),
+    "pbo": ((_float,),),
+    "p": ((_positive_int,), ()),
+    "q": ((_parse_q_arg,), ()),
+    "fe": ((_int,), ()),
+
+    "t": ((_float,), (_int, _int), (_int, _int, _float)),
+}
+
+
+def split_tags(block, nested=False):
+    result = []
+    while block:
+        comment = "".join(takewhile(lambda x: x != "\\", block))
+        if comment:
+            result.append(Tag("Comment", [comment]))
+        block = block[len(comment):]
+        block = block.lstrip("\\")
+        if not block:
+            break
+        name = "".join(takewhile(lambda x: x not in "(\\", block))
+        if not name:
+            continue
+        block = block[len(name):]
+        args = []
+        if block.startswith("("):
+            block = block[1:]
+            while True:
+                block = "".join(dropwhile(lambda x: x in " \t", block))
+                arg = "".join(takewhile(lambda x: x not in ",)\\", block))
+                block = block[len(arg):]
+                if block.startswith(","):
+                    if arg:
+                        args.append(arg)
+                    block = block[1:]
+                else:
+                    if block.startswith("\\"):
+                        arg = block[:block.find(")")] if block.find(")") != -1 else block
+                        block = block[len(arg):]
+                    if arg:
+                        args.append(arg)
+                    if block:
+                        block = block[1:]
+                    break
+
+        for tag in tag_args:
+            if name.startswith(tag):
+                if name != tag and is_simple_tag(tag):
+                    args.append(name[len(tag):])
+                name = tag
+                break
+        if name not in tag_args and not args:  # deals with unknown simple tags
+            flag = False
+            tag_name = ""
+            for ch in name:
+                if ch.isdigit() and not flag:
+                    tag_name += ch
+                elif ch.islower():
+                    flag = True
+                    tag_name += ch
+                else:
+                    break
+            if name != tag_name:
+                args.append(name[len(tag_name):])
+            name = tag_name
+        tag = Tag(name, args)
+        if nested and not is_nestable_tag(name):
+            tag.valid = False
+        result.append(tag)
+
+    return result
+
+
+def parse_tags(text: str) -> list[Tag]:
+    """
+    Parse tags from text.
+    :param text: The text to parse.
+    :return: A list of Tag objects.
+    """
+    result = []
+    splits = OVERRIDE_BLOCK_PATTERN.split(text)
+    drawing_mode = False
+    for i, block in enumerate(splits):
+        if i % 2 == 1:
+            tags = split_tags(block)
+            result.extend(tags)
+            for tag in tags:
+                if tag.name == "p" and tag.valid:
+                    drawing_mode = tag.args and tag.args[0] > 0
+        elif block:
+            if drawing_mode:
+                result.append(Tag("Drawing", [AssDrawing(block)]))
+            else:
+                result.append(Tag("Text", [block]))
+    return result

light_ass/utils.py

@@ -0,0 +1,139 @@
+import re
+from collections.abc import Callable
+from itertools import takewhile
+
+INT32_MIN = -2_147_483_648
+INT32_MAX = 2_147_483_647
+
+
+def clamp(val: int, min_: int, max_: int) -> int:
+    return min(max(val, min_), max_)
+
+
+def to_snake_case(text: str) -> str:
+    return re.sub(r"(?<!^)(?=[A-Z])", "_", text).lower()
+
+
+def detect_file_encoding(file_path: str, sample_size: int = 1024) -> str | None:
+    import codecs
+
+    bom_map = {
+        codecs.BOM_UTF8: "utf-8-sig",
+        codecs.BOM_UTF16_LE: "utf-16-le",
+        codecs.BOM_UTF16_BE: "utf-16-be",
+        codecs.BOM_UTF32_LE: "utf-32-le",
+        codecs.BOM_UTF32_BE: "utf-32-be",
+    }
+
+    with open(file_path, "rb") as f:
+        sample = f.read(sample_size)
+
+    for bom, encoding in bom_map.items():
+        if sample.startswith(bom):
+            return encoding
+
+    test_encodings = ["utf-8", "gb18030", "big5", "shift_jis", "euc-kr", "iso-8859-1", "cp1252"]
+
+    for encoding in test_encodings:
+        try:
+            sample.decode(encoding, errors="strict")
+            return encoding
+        except UnicodeDecodeError:
+            continue
+
+    return None
+
+
+def validate_value(validator: Callable | tuple | dict, value: str):
+    match validator:
+        case validator if callable(validator):
+            return validator(value)
+        case tuple():
+            typ_ = type(validator[0])
+            if typ_(value) in validator:
+                return typ_(value)
+        case dict():
+            if value in validator:
+                return validator[value]
+            if value in validator.values():
+                return value
+        case _:
+            pass
+    raise ValueError(f"Invalid value")
+
+
+def parse_int32(s: str) -> int:
+    s = s.lstrip(" \t")
+    if not s:
+        return 0
+
+    sgn = 1
+    if s[0] in "+-":
+        sgn = 1 if s[0] == "+" else -1
+        s = s[1:]
+
+    num_str = "".join(takewhile(lambda x: x.isdigit(), s))
+    num = sgn * int(num_str) if num_str else 0
+    return clamp(num, INT32_MIN, INT32_MAX)
+
+
+def parse_positive_int32(s: str) -> int:
+    num = parse_int32(s)
+    return num if num > 0 else 0
+
+
+def parse_float(s: str) -> float:
+    s = s.lstrip(" \t")
+    if not s:
+        return 0.0
+
+    sgn = 1
+    if s[0] in "+-":
+        sgn = 1 if s[0] == "+" else -1
+        s = s[1:]
+
+    num_str = ".".join(
+        map(
+            lambda x: "".join(takewhile(lambda ch: ch.isdigit(), x)),
+            s.split(".", 1)
+        )
+    )
+
+    if num_str.startswith("."):
+        num_str = "0" + num_str
+
+    return sgn * float(num_str) if num_str and num_str else 0.0
+
+
+def parse_positive_float(s: str) -> float:
+    num = parse_float(s)
+    return num if num > 0 else 0.0
+
+
+def parse_ass_color(s: str):
+    from .ass_types import AssColor
+
+    s = s.lstrip("&H").lstrip(" \t")
+    if s.startswith("+"):
+        s = s[1:]
+    if not tuple(takewhile(lambda x: x in "0123456789ABCDEF", s)):
+        return AssColor(0, 0, 0)
+    color = AssColor(s)
+    rev_value = (color.a << 24) | (color.b << 16) | (color.g << 8) | color.r
+    if rev_value >= INT32_MAX:
+        color = AssColor(255, 255, 255)
+    color.a = 0
+    return color
+
+
+def parse_ass_alpha(s: str):
+    from .ass_types import AssAlpha
+
+    s = s.lstrip("&H").lstrip(" \t")
+    if s.startswith("+"):
+        s = s[1:]
+    num_str = "".join(takewhile(lambda x: x in "0123456789ABCDEF", s))
+    if not num_str:
+        return AssAlpha(0)
+    val = int(num_str, 16) & 0xFF
+    return AssAlpha(val)

light_ass-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ming
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

light_ass-0.1.0.dist-info/METADATA

@@ -0,0 +1,51 @@
+Metadata-Version: 2.2
+Name: light-ass
+Version: 0.1.0
+Summary: A lightweight library for handling ASS subtitles
+Author-email: Oborozuki <oborozuk1@qq.com>
+License: MIT License
+Project-URL: Homepage, https://github.com/oborozuk1/light-ass
+Project-URL: Repository, https://github.com/oborozuk1/light-ass.git
+Project-URL: Bug Tracker, https://github.com/oborozuk1/light-ass/issues
+Keywords: subtitle,ass
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Video
+Classifier: Development Status :: 3 - Alpha
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# light-ass
+A lightweight library for handling Advanced SubStation Alpha (ASS) subtitles.
+
+## Features
+- Parse ASS subtitles effortlessly
+- Check the validity of field types
+- Parse ASS override tags (partial)
+
+## Installation
+```
+pip install light-ass
+```
+
+## Usage
+```python
+import light_ass
+
+document = light_ass.load("example.ass")
+print(document.info)
+print(document.styles)
+print(document.events)
+```
+
+## TODO
+- Support for more sections
+- More methods for ASS shapes
+- ASS minifier
+- Support for VSFilterMod tags
+
+## License
+MIT License

light_ass-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+light_ass/__init__.py,sha256=PKjryp5HDXk_1LCTawdntnW_7A8ayHAtfNbpLANx-TY,150
+light_ass/constants.py,sha256=mjwUZSHiLU7LZKSE1rj2HKpubCAdJ-zQ3fAkl0TathE,813
+light_ass/events.py,sha256=bB3b0PMR3bdHtJdtNTf9oO2-uCSK2YFW5s3324x47h4,3668
+light_ass/script_info.py,sha256=4RhNMStYPoDnhOsPGROTtaYNf3iKrjH16bvJ-YtWZlg,2794
+light_ass/styles.py,sha256=8by8sk8t_TM1aJUS-SChQPIx0EpvkyK84zo65V_QSvU,5188
+light_ass/subtitle.py,sha256=cj7txdmTZBXrEXrHX08dPA-i2_-Mc3KB5raJsxcA-Lg,8640
+light_ass/tag_parser.py,sha256=dVDQFi8dRR8oqaS6vlfDBoRPE4suRkRrcuDYt4QcJ7E,12027
+light_ass/utils.py,sha256=UqjPyWvHgKjOerR3nSPHnH2UxFb18Jom_4P1sK_5r14,3465
+light_ass-0.1.0.dist-info/LICENSE,sha256=QF-xOWlFl6tTZv5kdXO-tSlyfPPpB7PjOrnvfrfAf1E,1061
+light_ass-0.1.0.dist-info/METADATA,sha256=dCd2b7pDy5s_JHPJpy_eV1lWDWMcT4pexHgl6Z8PZCw,1335
+light_ass-0.1.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+light_ass-0.1.0.dist-info/top_level.txt,sha256=h0CIOYC-ay25jfy-w68BC_vo0iIipbSROMiq9rdmZys,10
+light_ass-0.1.0.dist-info/RECORD,,

light_ass-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

light_ass-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+light_ass