pycaption 2.3.9__tar.gz → 2.3.12__tar.gz

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

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

{pycaption-2.3.9 → pycaption-2.3.12}/pycaption/__init__.py

@@ -21,6 +21,7 @@ from .srt import SRTReader, SRTWriter
 from .transcript import TranscriptWriter
 from .webvtt import WebVTTReader, WebVTTWriter
 
+
 __all__ = [
     "CaptionConverter",
     "DFXPReader",

{pycaption-2.3.9 → pycaption-2.3.12}/pycaption/base.py

@@ -7,11 +7,13 @@ CaptionConverter orchestrator and base classes for readers/writers.
 
 import logging
 import os
+
 from datetime import timedelta
 from numbers import Number
 
 from .exceptions import CaptionReadError, CaptionReadTimingError, InvalidInputError
 
+
 logger = logging.getLogger(__name__)
 
 # `und` a special identifier for an undetermined language according to ISO 639-2
@@ -40,8 +42,7 @@ class CaptionConverter:
         """
         if not hasattr(caption_reader, "read"):
             raise InvalidInputError(
-                "The caption_reader must be a BaseReader instance "
-                "with a read() method."
+                "The caption_reader must be a BaseReader instance with a read() method."
             )
         self.captions = caption_reader.read(content)
         return self

{pycaption-2.3.9 → pycaption-2.3.12}/pycaption/dfxp/constants.py

@@ -8,6 +8,7 @@ import re
 
 from ..geometry import Alignment, HorizontalAlignmentEnum, Layout, VerticalAlignmentEnum
 
+
 DFXP_BASE_MARKUP = """
 <tt xmlns="http://www.w3.org/ns/ttml"
     xmlns:tts="http://www.w3.org/ns/ttml#styling">

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

@@ -13,6 +13,7 @@ from ..base import BaseWriter, CaptionNode, merge_concurrent_captions
 from .constants import DFXP_DEFAULT_REGION
 from .writer import DFXPWriter
 
+
 LEGACY_DFXP_BASE_MARKUP = """
 <tt xmlns="http://www.w3.org/ns/ttml"
     xmlns:tts="http://www.w3.org/ns/ttml#styling">
@@ -255,7 +256,7 @@ class LegacyDFXPWriter(BaseWriter):
 
         return line
 
-    def _recreate_style(self, content, dfxp):
+    def _recreate_style(self, content, dfxp):  # noqa: C901
         """Convert an internal style dict to DFXP/TTS attributes.
 
         :type content: dict

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

@@ -47,6 +47,7 @@ from .constants import (
     VERTICAL_ALIGNMENT_TO_DFXP,
 )
 
+
 _LEADING_WHITESPACE_RE = re.compile("^(?:[\n\r]+\\s*)?(.+)")
 
 _DFXP_WRITING_MODE_MAP = {
@@ -147,7 +148,8 @@ class DFXPReader(BaseReader):
                     style_dict[id_] = self._convert_style(style)
 
         caption_set = CaptionSet(
-            caption_dict, styles=style_dict,
+            caption_dict,
+            styles=style_dict,
             visual_alignment_default=HorizontalAlignmentEnum.START,
         )
 
@@ -179,8 +181,7 @@ class DFXPReader(BaseReader):
             tickrate = float(tt_attrs["ttp:tickrate"])
         except ValueError:
             raise CaptionReadSyntaxError(
-                f"ttp:tickRate must be a number, "
-                f"got '{tt_attrs['ttp:tickrate']}'"
+                f"ttp:tickRate must be a number, got '{tt_attrs['ttp:tickrate']}'"
             )
         if tickrate <= 0:
             raise CaptionReadSyntaxError(
@@ -203,8 +204,7 @@ class DFXPReader(BaseReader):
             framerate_int = int(framerate_str)
         except ValueError:
             raise CaptionReadSyntaxError(
-                f"ttp:frameRate must be a positive integer, "
-                f"got '{framerate_str}'"
+                f"ttp:frameRate must be a positive integer, got '{framerate_str}'"
             )
         self.tickrate = float(framerate_int * sub_framerate)
 
@@ -396,7 +396,7 @@ class DFXPReader(BaseReader):
                 self._convert_tag_to_node(a)
 
     @staticmethod
-    def _convert_style(tag):
+    def _convert_style(tag):  # noqa: C901
         """Convert DFXP/TTS style attributes on a tag to an internal style dict.
 
         Maps tts:fontStyle, tts:fontWeight, tts:textDecoration, tts:textAlign,

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

@@ -5,6 +5,7 @@ including style elements, region-based positioning, and writing direction.
 """
 
 import re
+
 from copy import deepcopy
 from xml.sax.saxutils import escape
 
@@ -26,6 +27,7 @@ from .constants import (
     _create_external_alignment,
 )
 
+
 _WRITING_DIRECTION_TO_DFXP = {
     WritingDirectionEnum.VERTICAL_RL: "tbrl",
     WritingDirectionEnum.VERTICAL_LR: "tblr",
@@ -213,39 +215,278 @@ class DFXPWriter(BaseWriter):
 
         return p
 
-    def _recreate_text(self, caption, dfxp, caption_set=None, lang=None):
+    def _recreate_text(self, caption, dfxp, caption_set=None, lang=None):  # noqa: C901
         """Serialize all nodes of a caption into DFXP inline markup.
 
-        Handles text nodes, line breaks (<br/>), and style spans.
+        Handles text nodes, line breaks (<br/>), and style spans.  Nodes are
+        first split into runs sharing one region; a run whose region is not
+        the one already in effect is wrapped in a <span> carrying it, so text
+        renders at its own position instead of inheriting the one on the
+        enclosing <p>, and a <br/> between two nodes of one region stays
+        inside that region.  A run holding no visible text takes no wrapper:
+        there is nothing for the region to place.
 
         :rtype: str
         """
         line = ""
         self._span_stack = []
+        paragraph = self.region_creator.get_positioning_info(lang, caption_set, caption)
+        paragraph_region, _ = paragraph
+
+        for region_id, region_attribs, nodes, wrappable in self._group_nodes_by_region(
+            caption, paragraph, caption_set, lang
+        ):
+            wrap = (
+                wrappable
+                and region_id != self._innermost_region(paragraph_region)
+                and self._holds_visible_text(nodes)
+            )
+            if wrap:
+                attrs = {"region": region_id}
+                if self.write_inline_positioning:
+                    attrs.update(region_attribs)
+                attr_str = " ".join(f'{k}="{v}"' for k, v in attrs.items())
+                line += f"<span {attr_str}>"
 
-        for node in caption.nodes:
-            if node.type_ == CaptionNode.TEXT:
-                line += escape(node.content)
+            for node in nodes:
+                if node.type_ == CaptionNode.TEXT:
+                    line += escape(node.content)
 
-            elif node.type_ == CaptionNode.BREAK:
-                line = line.rstrip() + "<br/>\n    "
+                elif node.type_ == CaptionNode.BREAK:
+                    line = line.rstrip() + "<br/>\n    "
+
+                elif node.type_ == CaptionNode.STYLE:
+                    line = self._recreate_span(
+                        line, node, dfxp, caption_set, caption, lang
+                    )
 
-            elif node.type_ == CaptionNode.STYLE:
-                line = self._recreate_span(line, node, dfxp, caption_set, caption, lang)
+            if wrap:
+                line = line.rstrip() + "</span> "
 
         while self._span_stack:
-            line = line.rstrip() + "</span> "
-            self._span_stack.pop()
+            emitted, _ = self._span_stack.pop()
+            if emitted:
+                line = line.rstrip() + "</span> "
 
         return line.rstrip()
 
+    def _group_nodes_by_region(self, caption, paragraph, caption_set, lang):
+        """Split a caption's nodes into consecutive runs sharing one region.
+
+        Line breaks are neutral: a run absorbs one only when it continues
+        past it, so a break between two nodes of the same region ends up
+        inside that region's span rather than outside it.  Breaks left over
+        between two runs form a run of their own, which is never wrapped.
+        A run is split again around any style tag whose partner falls
+        outside it, so one such tag costs only itself a wrapper.
+
+        :param paragraph: (region_id, positioning attributes) of the enclosing <p>
+        :return: (region_id, positioning_attributes, nodes, wrappable) per run
+        :rtype: list[tuple[str | None, dict, list[CaptionNode], bool]]
+        """
+        resolved, partners = self._resolve_node_regions(
+            caption, paragraph, caption_set, lang
+        )
+
+        groups = []
+        current = None
+        pending = []
+
+        for index, (region_id, region_attribs) in enumerate(resolved):
+            if region_id is None:
+                pending.append(index)
+                continue
+
+            if current and region_id == current[0]:
+                current[2].extend(pending)
+            else:
+                if current:
+                    groups.append(current)
+                if pending:
+                    groups.append((None, {}, pending))
+                current = [region_id, region_attribs, []]
+            pending = []
+            current[2].append(index)
+
+        if current:
+            groups.append(current)
+        if pending:
+            groups.append((None, {}, pending))
+
+        return [
+            (
+                region_id,
+                region_attribs,
+                [caption.nodes[index] for index in segment],
+                region_id is not None
+                and self._is_wrappable(segment, partners, caption.nodes),
+            )
+            for region_id, region_attribs, indices in groups
+            for segment in self._split_at_crossing_styles(
+                indices, partners, caption.nodes
+            )
+        ]
+
+    @staticmethod
+    def _holds_visible_text(nodes):
+        """Check whether a run has any text for a region to place.
+
+        A run of nothing but style tags and breaks renders nothing, so a
+        wrapper carrying its region would be an empty span.
+
+        :rtype: bool
+        """
+        return any(
+            node.type_ == CaptionNode.TEXT and node.content.strip() for node in nodes
+        )
+
+    @staticmethod
+    def _crosses_run(index, partners, nodes, run):
+        """Check whether the node at an index leaves the run it belongs to.
+
+        A style tag whose partner sits outside the run does: a span wrapping
+        it would cross that tag's own span and produce invalid XML.  A
+        closing tag with no partner at all is the exception — nothing was
+        opened for it, so it writes no tag and crosses nothing.
+
+        :param run: the indices making up the run
+        :type run: set[int]
+        :rtype: bool
+        """
+        node = nodes[index]
+        if node.type_ != CaptionNode.STYLE:
+            return False
+
+        if not node.start and index not in partners:
+            return False
+
+        return partners.get(index) not in run
+
+    @classmethod
+    def _split_at_crossing_styles(cls, indices, partners, nodes):
+        """Split a run around style tags whose partner sits outside it.
+
+        A span wrapping such a tag would cross another span and produce
+        invalid XML, but only that tag is in the way — the nodes beside it
+        still deserve their own region, so they come back as runs of their
+        own instead of losing their position along with it.
+
+        :rtype: list[list[int]]
+        """
+        run = set(indices)
+        segments = [[]]
+
+        for index in indices:
+            if cls._crosses_run(index, partners, nodes, run):
+                segments += [[index], []]
+            else:
+                segments[-1].append(index)
+
+        return [segment for segment in segments if segment]
+
+    def _resolve_node_regions(self, caption, paragraph, caption_set, lang):
+        """Resolve the region every node of a caption belongs to.
+
+        A node's own layout wins; lacking one it takes the region in effect
+        around it — the innermost enclosing style span's, else the
+        paragraph's.  For a closing style node that is its own opener's
+        region, so a span is never separated from its own end tag.  Line
+        breaks belong to no region and resolve to None, as does a closing
+        tag with nothing open — it writes no tag at all.  A region travels
+        with the attributes that describe it, so a span reinstating one can
+        also write it inline.
+
+        :param paragraph: (region_id, positioning attributes) of the <p>
+        :return: a (region_id, positioning_attributes) pair per node, plus a
+            map pairing the index of each style tag with its partner's
+        :rtype: tuple[list[tuple[str | None, dict]], dict]
+        """
+        creator = self.region_creator
+        resolved = []
+        partners = {}
+        open_styles = []
+
+        for index, node in enumerate(caption.nodes):
+            in_effect = open_styles[-1][1] if open_styles else paragraph
+
+            if node.type_ == CaptionNode.BREAK:
+                resolved.append((None, {}))
+
+            elif node.type_ == CaptionNode.TEXT:
+                own = (None, {})
+                if node.content.strip():
+                    own = creator.get_node_positioning_info(node.layout_info)
+                resolved.append(own if own[0] else in_effect)
+
+            elif node.start:
+                if node.layout_info:
+                    region = creator.get_positioning_info(
+                        lang, caption_set, caption, node
+                    )
+                else:
+                    region = in_effect
+                open_styles.append((index, region))
+                resolved.append(region)
+
+            elif open_styles:
+                opener, _ = open_styles.pop()
+                partners[opener] = index
+                partners[index] = opener
+                resolved.append(in_effect)
+
+            else:
+                resolved.append((None, {}))
+
+        return resolved, partners
+
+    @classmethod
+    def _is_wrappable(cls, indices, partners, nodes):
+        """Check whether a run of nodes can take a <span> holding its region.
+
+        No style tag in the run may leave it, or the wrapping span would
+        cross a style span and produce invalid XML — which is what rules out
+        a tag split off on its own.  A run that is nothing but one style span
+        already writes any region of its own on that span, so it needs no
+        wrapper.
+
+        :rtype: bool
+        """
+        run = set(indices)
+        for index in indices:
+            if cls._crosses_run(index, partners, nodes, run):
+                return False
+
+        first = nodes[indices[0]]
+
+        return not (
+            first.type_ == CaptionNode.STYLE
+            and first.start
+            and partners.get(indices[0]) == indices[-1]
+        )
+
+    def _innermost_region(self, default):
+        """Return the region in effect at the current point in the caption.
+
+        The innermost open span carrying a region wins; with no such span,
+        the region on the enclosing <p> applies.
+
+        :param default: region of the enclosing <p>
+        :rtype: str
+        """
+        for _, region_id in reversed(self._span_stack):
+            if region_id:
+                return region_id
+
+        return default
+
     def _recreate_span(
         self, line, node, dfxp, caption_set=None, caption=None, lang=None
     ):
         """Open or close a <span> element for a style node.
 
         Supports nested spans via a stack.  Opening pushes onto the stack;
-        closing pops the most recent span.
+        closing pops the most recent span.  Each entry records whether a tag
+        was actually emitted and which region it carries, if any.
 
         :param line: the accumulated markup string so far
         :type line: str
@@ -254,6 +495,7 @@ class DFXPWriter(BaseWriter):
         """
         if node.start:
             attrs = _recreate_style(node.content, dfxp)
+            region_id = None
             if node.layout_info:
                 region_id, region_attribs = self.region_creator.get_positioning_info(
                     lang, caption_set, caption, node
@@ -265,13 +507,13 @@ class DFXPWriter(BaseWriter):
             if attrs:
                 attr_str = " ".join(f'{k}="{v}"' for k, v in attrs.items())
                 line += f"<span {attr_str}>"
-                self._span_stack.append(True)
+                self._span_stack.append((True, region_id))
             else:
-                self._span_stack.append(False)
+                self._span_stack.append((False, None))
 
         else:
             if self._span_stack:
-                had_span = self._span_stack.pop()
+                had_span, _ = self._span_stack.pop()
                 if had_span:
                     line = line.rstrip() + "</span> "
 
@@ -331,7 +573,12 @@ class RegionCreator:
         """Create <region> tags in the <layout> section for each Layout.
 
         Skips Layout objects that have no positioning data (no origin,
-        extent, padding, alignment, or writing_direction).
+        extent, padding, alignment, or writing_direction).  A line alignment
+        on its own is not positioning data: it is what a WebVTT ``line``
+        setting leaves behind when its value yields no line to place the cue
+        at — ``line:auto,start``, or a value the grammar discards outright —
+        so the cue keeps the default placement rather than taking a vertical
+        one from the qualifier alone.
 
         :param unique_layouts: iterable of geometry.Layout instances
         :type dfxp: BeautifulSoup
@@ -450,6 +697,26 @@ class RegionCreator:
 
         return region_id, positioning_attributes
 
+    def get_node_positioning_info(self, layout_info):
+        """Return (region_id, positioning_attributes) for a node's own layout.
+
+        Unlike get_positioning_info, this neither cascades to the caption and
+        the caption set nor falls back to the default region: a layout without
+        a region of its own yields (None, {}).
+
+        :type layout_info: geometry.Layout | None
+        :rtype: tuple[str | None, dict]
+        """
+        region_id = self._region_map.get(layout_info)
+        if not region_id:
+            return None, {}
+
+        self._assigned_region_ids.add(region_id)
+
+        return region_id, _convert_layout_to_attributes(
+            layout_info, self._fallback_alignment
+        )
+
     def cleanup_regions(self):
         """Remove <region> tags that were never assigned to any element."""
         layout_tag = self._dfxp.find("layout")
@@ -491,7 +758,7 @@ def _text_shadow_to_outline(value):
     return thickness
 
 
-def _recreate_style(content, dfxp):
+def _recreate_style(content, dfxp):  # noqa: C901
     """Convert an internal style dict to DFXP/TTS style attributes.
 
     Maps pycaption's internal keys (class, italics, bold, underline, color,
@@ -542,7 +809,7 @@ def _recreate_style(content, dfxp):
     return dfxp_style
 
 
-def _convert_layout_to_attributes(layout, fallback_alignment=None):
+def _convert_layout_to_attributes(layout, fallback_alignment=None):  # noqa: C901
     """Convert a Layout object to a dict of DFXP region attributes.
 
     Maps origin, extent, padding, alignment, and writing_direction to their

{pycaption-2.3.9 → pycaption-2.3.12}/pycaption/geometry.py

@@ -7,12 +7,15 @@ CONVENTIONS:
   responsible for the recalculation should return a new object with the
   necessary modifications.
 """
+
 import re
+
 from enum import Enum
 from functools import total_ordering
 
 from .exceptions import CaptionReadSyntaxError, RelativizationError
 
+
 _UNIT_MISMATCH_MSG = "The sizes should have the same measure units."
 
 

{pycaption-2.3.9 → pycaption-2.3.12}/pycaption/microdvd.py

@@ -5,6 +5,7 @@ A special line {0}{0}fps_value sets the framerate (default 25 fps).
 """
 
 import re
+
 from copy import deepcopy
 
 from .base import (

{pycaption-2.3.9 → pycaption-2.3.12}/pycaption/sami/constants.py

@@ -10,6 +10,7 @@ from cssutils import log
 
 from ..geometry import HorizontalAlignmentEnum
 
+
 log.setLevel(FATAL)
 
 SAMI_BASE_MARKUP = """

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

@@ -11,6 +11,7 @@ from ..exceptions import CaptionReadNoCaptions, CaptionReadTimingError
 from ..geometry import Alignment, HorizontalAlignmentEnum, Layout, Padding, Size
 from .parser import SAMIParser
 
+
 _TAG_TO_STYLE = {"i": "italics", "b": "bold", "u": "underline"}
 
 

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

@@ -13,6 +13,7 @@ from ..base import BaseWriter, CaptionNode
 from ..geometry import HorizontalAlignmentEnum
 from .constants import HORIZONTAL_ALIGNMENT_MAP, SAMI_BASE_MARKUP
 
+
 _NON_CSS_KEYS = frozenset(
     {
         "classes",

{pycaption-2.3.9 → pycaption-2.3.12}/pycaption/scc/__init__.py

@@ -3,4 +3,5 @@
 from .reader import SCCReader
 from .writer import SCC_TOKENS_PER_CAPTION_MAX, SCCWriter
 
+
 __all__ = ["SCCReader", "SCCWriter", "SCC_TOKENS_PER_CAPTION_MAX"]

{pycaption-2.3.9 → pycaption-2.3.12}/pycaption/scc/constants.py

@@ -7,8 +7,10 @@ background color codes, and derived inverse lookup tables.
 """
 
 import re as _re
+
 from itertools import product
 
+
 COMMANDS = {
     "9420": "",
     "9429": "",
@@ -1317,6 +1319,9 @@ SPECIAL_OR_EXTENDED_CHAR_TO_CODE = {
 SPECIAL_OR_EXTENDED_CHAR_TO_CODE.update(
     {character: code for code, character in SPECIAL_CHARS.items()}
 )
+# A non-breaking space is what CEA-608's transparent space is: a blank column
+# that is not a break opportunity. Unmapped, it fell back to the pound sign.
+SPECIAL_OR_EXTENDED_CHAR_TO_CODE["\xa0"] = "91b9"
 
 # Time to transmit a single codeword = 1 second / 29.97
 MICROSECONDS_PER_CODEWORD = 1000.0 * 1000.0 / (30.0 * 1000.0 / 1001.0)

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

@@ -78,6 +78,7 @@ http://www.theneitherworld.com/mcpoodle/SCC_TOOLS/DOCS/SCC_FORMAT.HTML
 """
 
 import re
+
 from collections import deque
 from copy import deepcopy
 
@@ -108,6 +109,7 @@ from .specialized_collections import (
 )
 from .state_machines import DefaultProvidingPositionTracker
 
+
 _TIMECODE_RE = re.compile(r"\d{2}:\d{2}:\d{2}[:;](\d{1,2})")
 
 
@@ -242,7 +244,7 @@ class SCCReader(BaseReader):
     def _validate_line_lengths(self):
         """Raise CaptionLineLengthError if any line exceeds 32 characters."""
         violations = [
-            f"around {cap.format_start()} - {line} - Length {len(line)}"
+            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
@@ -253,6 +255,19 @@ class SCCReader(BaseReader):
                 "Lines longer than 32:\n" + "\n".join(violations)
             )
 
+    @staticmethod
+    def _describe_line_length(line):
+        """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.
+        """
+        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)}"
+        )
+
     @staticmethod
     def _fix_last_captions_without_ending(caption_list):
         """Set end = start + 4s for trailing captions that were never ended."""
@@ -364,7 +379,11 @@ class SCCReader(BaseReader):
         if self._is_doubled_type(word) and word == self.last_command:
             if word in CUE_STARTING_COMMAND:
                 self.double_starter = True
-            self.last_command = ""
+            # A doubled PAC stays on record so that a Tab Offset following it is
+            # still recognised as belonging to a PAC and applied; clearing it
+            # would leave the offset looking like a stray duplicate and drop the
+            # indentation it carries.
+            self.last_command = word if self._is_pac_command(word) else ""
             return True
 
         if self._is_pac_command(word) and word in self.last_command: