pycaption 2.3.12__tar.gz → 2.3.14__tar.gz

{pycaption-2.3.12/pycaption.egg-info → pycaption-2.3.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycaption
-Version: 2.3.12
+Version: 2.3.14
 Summary: Closed caption converter
 Author: Joe Norton
 Author-email: joey@nortoncrew.com

{pycaption-2.3.12 → pycaption-2.3.14}/pycaption/dfxp/extras.py

@@ -10,6 +10,7 @@ from xml.sax.saxutils import escape
 from bs4 import BeautifulSoup
 
 from ..base import BaseWriter, CaptionNode, merge_concurrent_captions
+from ..utils import encode_leading_nbsp
 from .constants import DFXP_DEFAULT_REGION
 from .writer import DFXPWriter
 
@@ -204,7 +205,7 @@ class LegacyDFXPWriter(BaseWriter):
         start = caption.format_start()
         end = caption.format_end()
         p = dfxp.new_tag("p", begin=start, end=end)
-        p.string = self._recreate_text(caption, dfxp)
+        p.string = encode_leading_nbsp(self._recreate_text(caption, dfxp))
 
         if dfxp.find("style", {"xml:id": "p"}):
             p["style"] = "p"

{pycaption-2.3.12 → pycaption-2.3.14}/pycaption/dfxp/reader.py

@@ -48,7 +48,8 @@ from .constants import (
 )
 
 
-_LEADING_WHITESPACE_RE = re.compile("^(?:[\n\r]+\\s*)?(.+)")
+# Pretty-print indentation only: \s would also eat U+00A0 line indentation.
+_LEADING_WHITESPACE_RE = re.compile("^(?:[\n\r]+[ \t\n\r]*)?(.+)")
 
 _DFXP_WRITING_MODE_MAP = {
     "tbrl": WritingDirectionEnum.VERTICAL_RL,

{pycaption-2.3.12 → pycaption-2.3.14}/pycaption/dfxp/writer.py

@@ -13,6 +13,7 @@ from bs4 import BeautifulSoup
 
 from ..base import BaseWriter, CaptionNode
 from ..geometry import HorizontalAlignmentEnum, LineAlignmentEnum, WritingDirectionEnum
+from ..utils import encode_leading_nbsp
 from .constants import (
     DFXP_ATTR_XML_ID,
     DFXP_ATTR_XML_LANG,
@@ -206,7 +207,9 @@ class DFXPWriter(BaseWriter):
         start = caption.format_start()
         end = caption.format_end()
         p = dfxp.new_tag("p", begin=start, end=end)
-        p.string = self._recreate_text(caption, dfxp, caption_set, lang)
+        p.string = encode_leading_nbsp(
+            self._recreate_text(caption, dfxp, caption_set, lang)
+        )
 
         if dfxp.find("style", {DFXP_ATTR_XML_ID: "p"}):
             p["style"] = "p"

{pycaption-2.3.12 → pycaption-2.3.14}/pycaption/sami/reader.py

@@ -4,6 +4,8 @@ Parses SAMI documents into pycaption CaptionSet objects, handling CSS
 styles, margin-based positioning, and multi-language content.
 """
 
+import re
+
 from bs4 import BeautifulSoup, NavigableString
 
 from ..base import BaseReader, Caption, CaptionList, CaptionNode, CaptionSet
@@ -14,6 +16,9 @@ from .parser import SAMIParser
 
 _TAG_TO_STYLE = {"i": "italics", "b": "bold", "u": "underline"}
 
+# A line break plus the pretty-print indentation of the closing tag.
+_TRAILING_WHITESPACE_RE = re.compile("[\n\r][ \t\n\r]*$")
+
 
 class SAMIReader(BaseReader):
     """Reads SAMI caption files into a CaptionSet.
@@ -203,8 +208,9 @@ class SAMIReader(BaseReader):
         if isinstance(tag, NavigableString):
             tag_text = str(tag)
             if tag_text and tag_text[0] in "\n\r":
-                tag_text = tag_text.lstrip()
-            tag_text = tag_text.rstrip("\n\r")
+                # Not a bare lstrip(): U+00A0 is line indentation, not markup.
+                tag_text = tag_text.lstrip(" \t\n\r")
+            tag_text = _TRAILING_WHITESPACE_RE.sub("", tag_text)
             if not tag_text:
                 return
             self.line.append(CaptionNode.create_text(tag_text, inherit_from))

{pycaption-2.3.12 → pycaption-2.3.14}/pycaption/sami/writer.py

@@ -11,6 +11,7 @@ from bs4 import BeautifulSoup
 
 from ..base import BaseWriter, CaptionNode
 from ..geometry import HorizontalAlignmentEnum
+from ..utils import encode_leading_nbsp
 from .constants import HORIZONTAL_ALIGNMENT_MAP, SAMI_BASE_MARKUP
 
 
@@ -36,7 +37,6 @@ class SAMIWriter(BaseWriter):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self._span_stack = []
-        self.last_time = None
         self._promote_center = False
 
     def write(self, caption_set, **kwargs):
@@ -50,13 +50,8 @@ class SAMIWriter(BaseWriter):
             caption_set.layout_info
         )
 
-        primary = None
-
+        timelines = {}
         for lang in caption_set.get_languages():
-            self.last_time = None
-            if primary is None:
-                primary = lang
-
             caption_set.set_layout_info(
                 lang,
                 self._relativize_and_fit_to_screen(caption_set.get_layout_info(lang)),
@@ -71,12 +66,11 @@ class SAMIWriter(BaseWriter):
                     node.layout_info = self._relativize_and_fit_to_screen(
                         node.layout_info
                     )
-                sami = self._recreate_p_tag(caption, sami, lang, primary, caption_set)
+            cues = self._build_timeline(captions)
+            if cues:
+                timelines[lang] = cues
 
-            if self.last_time and captions:
-                sami = self._recreate_blank_tag(
-                    sami, captions[-1], lang, primary, caption_set
-                )
+        self._recreate_syncs(sami, timelines, caption_set)
 
         stylesheet = self._recreate_stylesheet(caption_set)
         sami.find("style").append(stylesheet)
@@ -85,17 +79,64 @@ class SAMIWriter(BaseWriter):
         caption_content = "\n".join(a[1:])
         return caption_content
 
-    def _recreate_p_tag(self, caption, sami, lang, primary, captions):
-        """Build a <sync><p> block for a single caption with styling and alignment."""
-        time = int(caption.start // 1000)
-
-        if self.last_time and time != self.last_time:
-            sami = self._recreate_blank_tag(sami, caption, lang, primary, captions)
-
-        self.last_time = int(caption.end // 1000)
+    @staticmethod
+    def _build_timeline(captions):
+        """Return (start_ms, end_ms, caption) cues sorted by start.
 
-        sami, sync = self._recreate_sync(sami, lang, primary, time)
+        Zero-length cues are never on screen, so they are dropped.
+        """
+        cues = []
+        for caption in captions:
+            start = int(caption.start // 1000)
+            end = int(caption.end // 1000)
+            if end > start:
+                cues.append((start, end, caption))
+        cues.sort(key=lambda cue: cue[0])
+        return cues
+
+    def _recreate_syncs(self, sami, timelines, captions):
+        """Append one <sync> per time at which any language's visible cues change.
+
+        Overlapping cues of a language are merged: a <sync> repeats every cue
+        of that language still on screen, so start times never decrease and
+        no cue is cleared early.
+        """
+        times = sorted(
+            {time for cues in timelines.values() for cue in cues for time in cue[:2]}
+        )
+        shown = {lang: [] for lang in timelines}
+        pending = {lang: 0 for lang in timelines}
+
+        for time in times:
+            sync = None
+            for lang, cues in timelines.items():
+                active = [i for i in shown[lang] if cues[i][1] > time]
+                while pending[lang] < len(cues) and cues[pending[lang]][0] <= time:
+                    active.append(pending[lang])
+                    pending[lang] += 1
+                if active == shown[lang]:
+                    continue
+                shown[lang] = active
+
+                if sync is None:
+                    sync = sami.new_tag("sync", start=time)
+                    sami.body.append(sync)
+
+                if active:
+                    for i in active:
+                        sync.append(
+                            self._recreate_p_tag(cues[i][2], sami, lang, captions)
+                        )
+                else:
+                    # The blank takes the class of the next cue, or of the
+                    # last cue once the language has no cues left.
+                    upcoming = cues[min(pending[lang], len(cues) - 1)][2]
+                    sync.append(
+                        self._recreate_blank_tag(upcoming, sami, lang, captions)
+                    )
 
+    def _recreate_p_tag(self, caption, sami, lang, captions):
+        """Build a <p> for a single caption with styling and alignment."""
         p = sami.new_tag("p")
 
         p_style = self._build_p_style(caption)
@@ -104,11 +145,9 @@ class SAMIWriter(BaseWriter):
             p["style"] = p_style
 
         p["class"] = self._recreate_p_lang(caption, lang, captions)
-        p.string = self._recreate_text(caption.nodes)
+        p.string = encode_leading_nbsp(self._recreate_text(caption.nodes))
 
-        sync.append(p)
-
-        return sami
+        return p
 
     def _build_p_style(self, caption):
         """Build the inline CSS style string for a <p> element."""
@@ -157,45 +196,13 @@ class SAMIWriter(BaseWriter):
 
         return HORIZONTAL_ALIGNMENT_MAP.get(h)
 
-    def _recreate_sync(self, sami, lang, primary, time):
-        """Find or create a <sync> tag at the given millisecond timestamp."""
-        if lang == primary:
-            sync = sami.new_tag("sync", start=time)
-            sami.body.append(sync)
-        else:
-            sync = sami.find("sync", start=time)
-            if sync is None:
-                sami, sync = self._find_closest_sync(sami, time)
-
-        return sami, sync
-
-    @staticmethod
-    def _find_closest_sync(sami, time):
-        """Insert a new <sync> tag in chronological order among existing syncs."""
-        sync = sami.new_tag("sync", start=time)
-
-        earlier = sami.find_all("sync", start=lambda x: int(x) < time)
-        if earlier:
-            last_sync = earlier[-1]
-            last_sync.insert_after(sync)
-        else:
-            later = sami.find_all("sync", start=lambda x: int(x) > time)
-            if later:
-                last_sync = later[0]
-                last_sync.insert_before(sync)
-        return sami, sync
-
-    def _recreate_blank_tag(self, sami, caption, lang, primary, captions):
-        """Insert an &nbsp; paragraph to clear the previous caption at its end time."""
-        sami, sync = self._recreate_sync(sami, lang, primary, self.last_time)
-
+    def _recreate_blank_tag(self, caption, sami, lang, captions):
+        """Build an &nbsp; <p> that clears the language's previous caption."""
         p = sami.new_tag("p")
         p["class"] = self._recreate_p_lang(caption, lang, captions)
         p.string = "&nbsp;"
 
-        sync.append(p)
-
-        return sami
+        return p
 
     @staticmethod
     def _recreate_p_lang(caption, lang, captions):

{pycaption-2.3.12 → pycaption-2.3.14}/pycaption/scc/reader.py

@@ -112,6 +112,10 @@ from .state_machines import DefaultProvidingPositionTracker
 
 _TIMECODE_RE = re.compile(r"\d{2}:\d{2}:\d{2}[:;](\d{1,2})")
 
+# Appended to a too-long line whose text kept going on the row with no PAC or
+# row change of its own. Matched downstream, so the wording is part of the API.
+ROW_CONTINUATION_SUFFIX = " (continues on the row without a row change)"
+
 
 class SCCReader(BaseReader):
     """Converts a given unicode string to a CaptionSet.
@@ -243,12 +247,18 @@ class SCCReader(BaseReader):
 
     def _validate_line_lengths(self):
         """Raise CaptionLineLengthError if any line exceeds 32 characters."""
-        violations = [
-            f"around {cap.format_start()} - {self._describe_line_length(line)}"
-            for cap in (c.to_real_caption() for c in self.caption_stash._collection)
-            for line in cap.get_text().split("\n")
-            if len(line) > 32
-        ]
+        violations = []
+        for precap in self.caption_stash._collection:
+            cap = precap.to_real_caption()
+            raw = "".join(cap.get_text_nodes())
+            # get_text() strips the caption, dropping any lines it opens with
+            skipped = raw[: len(raw) - len(raw.lstrip())].count("\n")
+            for index, line in enumerate(cap.get_text().split("\n")):
+                if len(line) > 32:
+                    description = self._describe_line_length(
+                        line, (index + skipped) in precap.continued_rows
+                    )
+                    violations.append(f"around {cap.format_start()} - {description}")
         if violations:
             raise CaptionLineLengthError(
                 "32 character limit for caption cue in scc file.\n"
@@ -256,17 +266,23 @@ class SCCReader(BaseReader):
             )
 
     @staticmethod
-    def _describe_line_length(line):
+    def _describe_line_length(line, continues_row=False):
         """Describe a line too long for the row, separating the text from the
-        indentation that places it, which can be what pushes it off the row.
+        indentation that places it, which can be what pushes it off the row,
+        and naming a missing PAC or row change when that is what joined it.
         """
         text = line.lstrip("\xa0")
         indent = len(line) - len(text)
         if not indent:
-            return f"{line} - Length {len(line)}"
-        return (
-            f"{text} - Length {len(text)} plus a {indent}-column indent = {len(line)}"
-        )
+            description = f"{line} - Length {len(line)}"
+        else:
+            description = (
+                f"{text} - Length {len(text)} plus a {indent}-column indent "
+                f"= {len(line)}"
+            )
+        if continues_row:
+            description += ROW_CONTINUATION_SUFFIX
+        return description
 
     @staticmethod
     def _fix_last_captions_without_ending(caption_list):
@@ -312,6 +328,7 @@ class SCCReader(BaseReader):
         parts = r.findall(line.lower())
 
         self.time_translator.start_at(parts[0][0])
+        self.position_tracker.start_burst()
         word_list = parts[0][2].split(" ")
 
         for idx, word in enumerate(word_list):

{pycaption-2.3.12 → pycaption-2.3.14}/pycaption/scc/specialized_collections.py

@@ -53,6 +53,9 @@ class PreCaption:
         self.nodes = []
         self.style = {}
         self.layout_info = None
+        # Indices of the lines whose text continued on the row without a PAC
+        # or row change, for the line length check to name the cause
+        self.continued_rows = set()
 
     def to_real_caption(self):
         """Convert this mutable holder into an immutable Caption instance.
@@ -274,6 +277,7 @@ class CaptionCreator:
             _leftmost_line_starts(instructions) if caption_mode == "pop_on" else []
         )
         cue_index = 0
+        line_index = 0
         indenter = _LineIndenter(enabled=bool(leftmost_columns))
 
         for instruction in instructions:
@@ -289,8 +293,14 @@ class CaptionCreator:
                 self._still_editing.append(caption)
                 cue_index += 1
                 indenter.start_cue()
+                line_index = 0
                 continue
 
+            if instruction.is_explicit_break():
+                line_index += 1
+            elif instruction.continues_row:
+                caption.continued_rows.add(line_index)
+
             text = indenter.text_for(instruction, position)
             _append_caption_node(caption, instruction, text, position)
 
@@ -381,17 +391,39 @@ class InstructionNodeCreator:
             self._collection.append(node)
             self._position_tracer.acknowledge_position_changed()
 
+        # Where a continuation is recorded: on the overwrite marker if the text
+        # lands on columns a PAC pointed back over, so a row sent again in full
+        # can drop it without dropping one of text arriving later
+        continued = node
         overlap = self._position_tracer.consume_pending_overlap()
         if overlap and self._mark_overwrite(overlap, current_position):
+            continued = self._collection[-1]
             node = _InstructionNode.create_text(current_position)
             self._collection.append(node)
 
+        # The tracker is shared by the buffers, so the row it saw text on may
+        # be another buffer's: only this buffer's own text can be continued
+        if self._position_tracer.consume_row_continuation() and self._line_has_text():
+            continued.continues_row = True
+
         padding = self._position_tracer.consume_pending_padding()
         if padding:
             node.add_chars(" " * padding)
         node.add_chars(*chars)
         self._position_tracer.advance_cursor(len("".join(chars)))
 
+    def _line_has_text(self):
+        """Whether the line being written in this buffer already holds text
+
+        :rtype: bool
+        """
+        for node in reversed(self._collection):
+            if _ends_line(node):
+                return False
+            if node.is_text_node() and node.text:
+                return True
+        return False
+
     def _settle_line_start(self):
         """Record on the break opening this line the column it now starts at
 
@@ -645,7 +677,11 @@ class InstructionNodeCreator:
         for idx, stash in enumerate(stash_list):
             # Resolved per stash: each is a row of its own, so an overwrite
             # is measured against its row rather than the rows joined together
-            new_collection.extend(_resolve_overwrites(stash._collection))
+            new_collection.extend(
+                _clear_continuations_of_fitting_rows(
+                    _resolve_overwrites(stash._collection)
+                )
+            )
 
             # use space to separate the stashes, but don't add final space
             if idx < len(stash_list) - 1:
@@ -878,6 +914,10 @@ class _InstructionNode:
         # only place a later line's own column survives
         self.line_start = line_start
         self.columns = columns
+        # For text, whether it continued a row already holding text, with no
+        # PAC or row change of its own; for an overwrite, whether the text
+        # after it did
+        self.continues_row = False
 
     def add_chars(self, *args):
         """This being a text node, add characters to it.
@@ -1099,7 +1139,10 @@ def _resolve_line_overwrites(line, line_start):
     """
     if not any(node.is_overwrite() for node in line):
         return line
-    line = [copy.copy(node) if node.is_text_node() else node for node in line]
+    line = [
+        copy.copy(node) if node.is_text_node() or node.is_overwrite() else node
+        for node in line
+    ]
     if line_start is None:
         line_start = next(
             (
@@ -1120,9 +1163,24 @@ def _resolve_line_overwrites(line, line_start):
                 arriving += len(node.text)
         if line_start + _line_length(line) > 32 and arriving >= marker.columns:
             _drop_last_columns(line[:index], marker.columns)
+            if not _line_length(line[:index]):
+                # The row was sent again in full: nothing is left of it for
+                # the text arriving to have continued
+                _clear_continuations(line[: index + 1])
     return _join_across_markers(line)
 
 
+def _clear_continuations(nodes):
+    """Clear the row continuation of the text and overwrite nodes, the line's
+    own copies
+
+    :type nodes: list[_InstructionNode]
+    """
+    for node in nodes:
+        if node.is_text_node() or node.is_overwrite():
+            node.continues_row = False
+
+
 def _join_across_markers(line):
     """Drop the overwrite markers, joining the text nodes each one split
 
@@ -1138,7 +1196,11 @@ def _join_across_markers(line):
     for node in line:
         if node.is_overwrite():
             after_marker = True
+            continued = node.continues_row
             continue
+        if after_marker and node.is_text_node():
+            # The text the marker opened, a copy, takes on its continuation
+            node.continues_row |= continued
         if (
             after_marker
             and node.is_text_node()
@@ -1147,12 +1209,38 @@ def _join_across_markers(line):
         ):
             if node.text:
                 joined[-1].add_chars(node.text)
+            joined[-1].continues_row |= node.continues_row
         else:
             joined.append(node)
         after_marker = False
     return joined
 
 
+def _clear_continuations_of_fitting_rows(collection):
+    """Clear the row continuation of every line that fits the row
+
+    Simulated roll-up joins its rows onto one line, which can run past column
+    32 although no row did. The continuation has to be judged on its own row,
+    before the join, or it would take the blame for a length it did not cause.
+
+    The nodes are cleared in place, not copied: the row's nodes are shared with
+    the stash it is re-read from, and a row that fits keeps fitting.
+
+    :type collection: list[_InstructionNode]
+    :rtype: list[_InstructionNode]
+    """
+    line = []
+    for node in collection + [None]:
+        if node is not None and not _ends_line(node):
+            line.append(node)
+            continue
+        if _line_length(line) <= 32:
+            for line_node in line:
+                line_node.continues_row = False
+        line = []
+    return collection
+
+
 def _drop_last_columns(line, columns):
     """Drop the last ``columns`` columns of text from the nodes of a line
 

{pycaption-2.3.12 → pycaption-2.3.14}/pycaption/scc/state_machines.py

@@ -43,6 +43,10 @@ class _PositioningTracker:
         self._pending_padding = 0
         # Columns a PAC pointed back over, not yet known to be an overwrite.
         self._pending_overlap = 0
+        # Text written next lands on a row that already holds text, reached
+        # with no PAC or row change of its own: a same-row PAC, or a later
+        # line of the file picking up where the row left off.
+        self._row_continued = False
 
     def update_positioning(
         self, positioning, column_jump_forces_reposition=False, is_offset=False
@@ -171,6 +175,7 @@ class _PositioningTracker:
             self._pending_overlap = 0
             self._pending_padding = 0
             self._line_has_text = False
+            self._row_continued = False
         # A skipped row, or a row+1 jump with a large paint-on column jump:
         # use repositioning (new cue)
         else:
@@ -218,6 +223,10 @@ class _PositioningTracker:
             self._last_column = new_col
             self._cursor_column = new_col
         else:
+            if not is_offset and self._line_has_text:
+                # A PAC on the row being written moves on along it instead of
+                # opening a row of its own
+                self._row_continued = True
             overlap = cursor - new_col
             if overlap < 0:
                 # The columns between the text and the PAC are blank
@@ -258,6 +267,7 @@ class _PositioningTracker:
         # and its text is no longer in front of the cursor to be overwritten
         self._pending_padding = 0
         self._pending_overlap = 0
+        self._row_continued = False
 
     def advance_cursor(self, count):
         """Notify the tracker that ``count`` columns of text were written.
@@ -295,6 +305,22 @@ class _PositioningTracker:
         overlap, self._pending_overlap = self._pending_overlap, 0
         return overlap
 
+    def start_burst(self):
+        """Note that a new line of the file starts: text it writes before any
+        positioning command continues the row the previous line left off on.
+        """
+        if self._line_has_text:
+            self._row_continued = True
+
+    def consume_row_continuation(self):
+        """Return and clear whether the text arriving next continues a row
+        without a PAC or row change of its own.
+
+        :rtype: bool
+        """
+        continued, self._row_continued = self._row_continued, False
+        return continued
+
     def cancel_pending_overlap(self):
         """Drop the overlap, the column the PAC pointed at being taken by a
         command rather than by text.
@@ -361,6 +387,7 @@ class _PositioningTracker:
         self._line_has_text = False
         self._pending_padding = 0
         self._pending_overlap = 0
+        self._row_continued = False
         # Reset positions to None so the next PAC sets position fresh
         self._positions = [None]
 
@@ -405,9 +432,19 @@ class DefaultProvidingPositionTracker(_PositioningTracker):
         :param positioning: a tuple of ints (row, col)
         :type positioning: tuple[int]
         """
+        # Text written before any PAC was placed on the default row
+        unplaced_row = (
+            self.default[0]
+            if self._line_has_text and not any(self._positions)
+            else None
+        )
         if positioning:
             self.default = positioning
 
         super().update_positioning(
             positioning, column_jump_forces_reposition, is_offset
         )
+        if not is_offset and positioning and positioning[0] == unplaced_row:
+            # The PAC names the row that text already took, so the text after
+            # it carries on along the row instead of opening one of its own
+            self._row_continued = True

pycaption-2.3.14/pycaption/utils.py

@@ -0,0 +1,26 @@
+"""Shared utility functions for pycaption."""
+
+
+def is_leaf(element):
+    """Return True if element is a BeautifulSoup leaf (NavigableString or <br>).
+
+    :param element: A BeautifulSoup Tag or NavigableString.
+    :rtype: bool
+    """
+    name = getattr(element, "name", None)
+    if not name or name == "br":
+        return True
+    return False
+
+
+def encode_leading_nbsp(text):
+    """Write the leading non-breaking spaces of text as &#160; entities.
+
+    prettify() strips the ends of a paragraph's text, and Python counts U+00A0
+    as whitespace, so the indentation of a cue's first line would be lost.
+
+    :type text: str
+    :rtype: str
+    """
+    stripped = text.lstrip("\xa0")
+    return "&#160;" * (len(text) - len(stripped)) + stripped