pycaption 2.3.1__tar.gz → 2.3.3__tar.gz

{pycaption-2.3.1/pycaption.egg-info → pycaption-2.3.3}/PKG-INFO

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

{pycaption-2.3.1 → pycaption-2.3.3}/pycaption/base.py

@@ -9,7 +9,7 @@ import os
 from datetime import timedelta
 from numbers import Number
 
-from .exceptions import CaptionReadError, CaptionReadTimingError
+from .exceptions import CaptionReadError, CaptionReadTimingError, InvalidInputError
 
 # `und` a special identifier for an undetermined language according to ISO 639-2
 DEFAULT_LANGUAGE_CODE = os.getenv("PYCAPTION_DEFAULT_LANG", "und")
@@ -26,7 +26,7 @@ class CaptionConverter:
     """
 
     def __init__(self, captions=None):
-        self.captions = captions if captions else []
+        self.captions = captions
 
     def read(self, content, caption_reader):
         """Parse caption content using the given reader.
@@ -35,10 +35,12 @@ class CaptionConverter:
         :param caption_reader: A BaseReader subclass instance.
         :returns: self (for chaining).
         """
-        try:
-            self.captions = caption_reader.read(content)
-        except AttributeError as e:
-            raise Exception(e)
+        if not hasattr(caption_reader, "read"):
+            raise InvalidInputError(
+                "The caption_reader must be a BaseReader instance "
+                "with a read() method."
+            )
+        self.captions = caption_reader.read(content)
         return self
 
     def write(self, caption_writer):
@@ -48,10 +50,12 @@ class CaptionConverter:
         :returns: The serialized caption string.
         :rtype: str
         """
-        try:
-            return caption_writer.write(self.captions)
-        except AttributeError as e:
-            raise Exception(e)
+        if not hasattr(caption_writer, "write"):
+            raise InvalidInputError(
+                "The caption_writer must be a BaseWriter instance "
+                "with a write() method."
+            )
+        return caption_writer.write(self.captions)
 
 
 class BaseReader:
@@ -60,6 +64,33 @@ class BaseReader:
     def __init__(self, *args, **kwargs):
         pass
 
+    @staticmethod
+    def _decode_content(content):
+        """Decode bytes to str (UTF-8 with BOM handling).
+
+        :param content: str or bytes input.
+        :returns: decoded str with BOM stripped.
+        :raises InvalidInputError: if content is not str/bytes, is empty
+            bytes, or is not valid UTF-8.
+        """
+        if isinstance(content, bytes):
+            if not content:
+                raise InvalidInputError("The content is empty.")
+            try:
+                content = content.decode("utf-8-sig")
+            except UnicodeDecodeError as e:
+                raise InvalidInputError(
+                    f"Content is not valid UTF-8: {e}"
+                ) from e
+        elif isinstance(content, str):
+            if content.startswith(""):
+                content = content[1:]
+        else:
+            raise InvalidInputError(
+                "The content must be a unicode string or UTF-8 bytes."
+            )
+        return content
+
     def detect(self, content):
         """Return True if content appears to be in this reader's format.
 
@@ -107,6 +138,28 @@ class BaseWriter:
         self.video_height = video_height
         self.fit_to_screen = fit_to_screen
 
+    @staticmethod
+    def _get_visual_alignment_default(caption_set):
+        """Return the source format's visual alignment default from a CaptionSet.
+
+        Per SMPTE RP 2052-10, caption formats have different implicit visual
+        defaults when no alignment is specified:
+        - CENTER: WebVTT, SRT, SCC, MicroDVD
+        - LEFT/START: DFXP/TTML, SAMI
+
+        When converting between formats with mismatched defaults, the source
+        default must be made explicit in the output to prevent visual
+        regression (e.g. centered text silently becoming left-aligned).
+
+        Readers declare their default via CaptionSet.visual_alignment_default.
+        Writers compare it to their own format's default to decide whether
+        to emit explicit alignment.
+
+        :type caption_set: CaptionSet
+        :rtype: HorizontalAlignmentEnum | None
+        """
+        return caption_set.visual_alignment_default if caption_set else None
+
     def _relativize_and_fit_to_screen(self, layout_info):
         """Apply relativization and fit-to-screen adjustments to a Layout.
 
@@ -124,13 +177,14 @@ class BaseWriter:
                 layout_info = layout_info.fit_to_screen()
         return layout_info
 
-    def write(self, content):
+    def write(self, caption_set, **kwargs):
         """Serialize a CaptionSet. Subclasses override this.
 
-        :type content: CaptionSet
+        :type caption_set: CaptionSet
+        :param kwargs: Format-specific options (e.g. force, lang).
         :rtype: str
         """
-        return content
+        return caption_set
 
 
 class CaptionNode:
@@ -146,8 +200,6 @@ class CaptionNode:
     """
 
     TEXT = 1
-    # When and if this is extended, it might be better to turn it into a
-    # property of the node, not a type of node itself.
     STYLE = 2
     BREAK = 3
 
@@ -216,9 +268,9 @@ class Caption:
         """
         Initialize the Caption object
         :param start: The start time in microseconds
-        :type start: Number
+        :type start: int
         :param end: The end time in microseconds
-        :type end: Number
+        :type end: int
         :param nodes: A list of CaptionNodes
         :type nodes: list
         :param style: A dictionary with CSS-like styling rules
@@ -242,10 +294,8 @@ class Caption:
         self.nodes = nodes
         self.style = style or {}
         self.layout_info = layout_info
-
-    def is_empty(self):
-        """Return True if this caption has no nodes."""
-        return not self.nodes
+        self.caption_mode = None
+        self.roll_up_rows = None
 
     def format_start(self, msec_separator=None):
         """Format start time as HH:MM:SS.mmm string.
@@ -273,33 +323,30 @@ class Caption:
 
         :rtype: list[str]
         """
-        result = []
-        for node in self.nodes:
-            if node.type_ == CaptionNode.TEXT:
-                result.append(node.content)
-            elif node.type_ == CaptionNode.BREAK:
-                result.append("\n")
-        return result
+        return [
+            node.content if node.type_ == CaptionNode.TEXT else "\n"
+            for node in self.nodes
+            if node.type_ in (CaptionNode.TEXT, CaptionNode.BREAK)
+        ]
 
     def get_text(self):
         """Return the plain text content of this caption (no markup).
 
         :rtype: str
         """
-        text_nodes = self.get_text_nodes()
-        return "".join(text_nodes).strip()
+        return "".join(self.get_text_nodes()).strip()
 
-    def _format_timestamp(self, microseconds, msec_separator=None):
+    @staticmethod
+    def _format_timestamp(microseconds, msec_separator=None):
         """Convert microseconds to HH:MM:SS{sep}mmm string."""
         duration = timedelta(microseconds=microseconds)
         hours, rem = divmod(duration.seconds, 3600)
         minutes, seconds = divmod(rem, 60)
-        milliseconds = f"{duration.microseconds // 1000:03d}"
-        timestamp = (
+        milliseconds = duration.microseconds // 1000
+        return (
             f"{hours:02d}:{minutes:02d}:{seconds:02d}"
-            f"{msec_separator or '.'}{milliseconds:.3s}"
+            f"{msec_separator or '.'}{milliseconds:03d}"
         )
-        return timestamp
 
 
 class CaptionList(list):
@@ -320,14 +367,14 @@ class CaptionList(list):
             return item
         return CaptionList(item, layout_info=self.layout_info)
 
-    def __add__(self, other):
+    def __add__(self, value):
         add_is_safe = (
-            not hasattr(other, "layout_info")
-            or not other.layout_info
-            or self.layout_info == other.layout_info
+            not hasattr(value, "layout_info")
+            or not value.layout_info
+            or self.layout_info == value.layout_info
         )
         if add_is_safe:
-            return CaptionList(list.__add__(self, other), layout_info=self.layout_info)
+            return CaptionList(list.__add__(self, value), layout_info=self.layout_info)
         else:
             raise ValueError(
                 "Cannot add CaptionList objects with different layout_info"
@@ -348,17 +395,27 @@ class CaptionSet:
     by all the children.
     """
 
-    def __init__(self, captions, styles=None, layout_info=None, regions=None):
+    def __init__(
+        self, captions, styles=None, layout_info=None, regions=None,
+        visual_alignment_default=None,
+    ):
         """
         :param captions: A dictionary of the format {'language': CaptionList}
         :param styles: A dictionary with CSS-like styling rules
         :param Layout layout_info: A Layout object with the positioning info
         :param regions: A dictionary mapping region id to raw settings dict
+        :param visual_alignment_default: The source format's implicit text
+            alignment when no explicit alignment is specified. Per SMPTE
+            RP 2052-10, writers targeting a format with a different visual
+            default must emit this alignment explicitly to prevent visual
+            regression. Use HorizontalAlignmentEnum values.
+        :type visual_alignment_default: HorizontalAlignmentEnum | None
         """
         self._captions = captions
         self._styles = styles or {}
         self._regions = regions or {}
         self.layout_info = layout_info
+        self.visual_alignment_default = visual_alignment_default
 
     def set_captions(self, lang, captions):
         """Replace the caption list for a given language.
@@ -429,7 +486,10 @@ class CaptionSet:
 
     def is_empty(self):
         """Return True if no language contains any captions."""
-        return all([len(captions) == 0 for captions in list(self._captions.values())])
+        for captions in self._captions.values():
+            if len(captions) > 0:
+                return False
+        return True
 
     def set_layout_info(self, lang, layout_info):
         """Set the layout_info on the CaptionList for a given language.
@@ -469,44 +529,46 @@ class CaptionSet:
             self.set_captions(lang, out_captions)
 
 
-# Functions
 def merge_concurrent_captions(caption_set):
     """Merge captions that have the same start and end times"""
     for lang in caption_set.get_languages():
         captions = caption_set.get_captions(lang)
-        last_caption = None
-        concurrent_captions = CaptionList()
-        merged_captions = CaptionList()
-        for caption in captions:
-            if last_caption:
-                last_timespan = last_caption.start, last_caption.end
-                current_timespan = caption.start, caption.end
-                if current_timespan == last_timespan:
-                    concurrent_captions.append(caption)
-                    last_caption = caption
-                    continue
-                else:
-                    merged_captions.append(merge(concurrent_captions))
-            concurrent_captions = [caption]
-            last_caption = caption
-
-        if concurrent_captions:
-            merged_captions.append(merge(concurrent_captions))
-        if merged_captions:
-            caption_set.set_captions(lang, merged_captions)
+        merged = merge_caption_list(captions)
+        if merged:
+            caption_set.set_captions(lang, merged)
     return caption_set
 
 
-def merge(captions):
-    """
-    Merge list of captions into one caption. The start/end times from the first
-    caption are kept.
-    """
+def merge_caption_list(captions):
+    """Merge consecutive captions with identical start/end times into one."""
+    if not captions:
+        return CaptionList()
+    last_caption = None
+    concurrent_captions = CaptionList()
+    merged_captions = CaptionList()
+    for caption in captions:
+        if last_caption:
+            last_timespan = last_caption.start, last_caption.end
+            current_timespan = caption.start, caption.end
+            if current_timespan == last_timespan:
+                concurrent_captions.append(caption)
+                last_caption = caption
+                continue
+            else:
+                merged_captions.append(_merge_group(concurrent_captions))
+        concurrent_captions = [caption]
+        last_caption = caption
+
+    if concurrent_captions:
+        merged_captions.append(_merge_group(concurrent_captions))
+    return merged_captions
+
+
+def _merge_group(captions):
+    """Merge a group of captions into one, keeping the first caption's timing."""
     new_nodes = []
     for caption in captions:
         if new_nodes:
             new_nodes.append(CaptionNode.create_break())
-        for node in caption.nodes:
-            new_nodes.append(node)
-    caption = Caption(captions[0].start, captions[0].end, new_nodes, captions[0].style)
-    return caption
+        new_nodes.extend(caption.nodes)
+    return Caption(captions[0].start, captions[0].end, new_nodes, captions[0].style)

{pycaption-2.3.1 → pycaption-2.3.3}/pycaption/dfxp/constants.py

@@ -25,10 +25,22 @@ DFXP_DEFAULT_STYLE = {
     "font-size": "1c",
 }
 
+# Reader default: DFXP spec mandates START/BOTTOM for round-trip fidelity.
 DFXP_DEFAULT_REGION = Layout(
     alignment=Alignment(HorizontalAlignmentEnum.START, VerticalAlignmentEnum.BOTTOM)
 )
 
+# Writer fallback alignment used when layout is None or SCC positional.
+DFXP_WRITER_FALLBACK_ALIGNMENT = Alignment(
+    HorizontalAlignmentEnum.CENTER, VerticalAlignmentEnum.BOTTOM
+)
+
+# Writer default region for sources without positioning (VTT/SRT);
+# uses CENTER per RP 2052-10 rather than the spec's START default.
+DFXP_WRITER_DEFAULT_REGION = Layout(
+    alignment=Alignment(HorizontalAlignmentEnum.CENTER, VerticalAlignmentEnum.BOTTOM)
+)
+
 DFXP_DEFAULT_STYLE_ID = "default"
 DFXP_DEFAULT_REGION_ID = "bottom"
 

{pycaption-2.3.1 → pycaption-2.3.3}/pycaption/dfxp/extras.py

@@ -46,18 +46,19 @@ class SinglePositioningDFXPWriter(DFXPWriter):
         super().__init__(*args, **kwargs)
         self.default_positioning = default_positioning
 
-    def write(self, captions_set, force=""):
+    def write(self, captions_set, **kwargs):
         """Writes a DFXP file using the positioning provided in the initializer
 
         :type captions_set: pycaption.base.CaptionSet
-        :param force: only write this language, if available in the CaptionSet
+        :param kwargs:
+            force (str): only write this language, if available in the CaptionSet
         :rtype: str
         """
         captions_set = self._create_single_positioning_caption_set(
             captions_set, self.default_positioning
         )
 
-        return super().write(captions_set, force)  # noqa
+        return super().write(captions_set, **kwargs)
 
     @staticmethod
     def _create_single_positioning_caption_set(caption_set, positioning):
@@ -98,13 +99,15 @@ class LegacyDFXPWriter(BaseWriter):
     def __init__(self, *args, **kw):
         self.open_span = False
 
-    def write(self, caption_set, force=""):
+    def write(self, caption_set, **kwargs):
         """Serialize a CaptionSet into legacy DFXP format.
 
         :type caption_set: CaptionSet
-        :param force: if set, output only this language (falls back to last)
+        :param kwargs:
+            force (str): if set, output only this language (falls back to last)
         :rtype: str
         """
+        force = kwargs.get("force", "")
         caption_set = deepcopy(caption_set)
         caption_set = merge_concurrent_captions(caption_set)
 

{pycaption-2.3.1 → pycaption-2.3.3}/pycaption/dfxp/reader.py

@@ -21,10 +21,10 @@ from ..exceptions import (
     CaptionReadNoCaptions,
     CaptionReadSyntaxError,
     CaptionReadTimingError,
-    InvalidInputError,
 )
 from ..geometry import (
     Alignment,
+    HorizontalAlignmentEnum,
     Layout,
     Padding,
     Point,
@@ -107,9 +107,10 @@ class DFXPReader(BaseReader):
     def detect(self, content):
         """Return True if content looks like a DFXP/TTML document.
 
-        :type content: str
+        :type content: str or bytes
         :rtype: bool
         """
+        content = self._decode_content(content)
         lowered = content.lower()
         return bool(re.search(r"<tt[\s>]", lowered)) and "</tt>" in lowered
 
@@ -121,52 +122,14 @@ class DFXPReader(BaseReader):
         :raises InvalidInputError: if content is not a string
         :raises CaptionReadNoCaptions: if no captions are found
         """
-        if not isinstance(content, str):
-            raise InvalidInputError("The content is not a unicode string.")
+        content = self._decode_content(content)
 
         dfxp_document = LayoutAwareDFXPParser(
             content, read_invalid_positioning=self.read_invalid_positioning
         )
 
         tt_attrs = dfxp_document.tt.attrs if dfxp_document.tt else {}
-        framerate_str = tt_attrs.get("ttp:framerate", str(DFXP_DEFAULT_FRAMERATE))
-        multiplier_str = tt_attrs.get(
-            "ttp:frameratemultiplier", DFXP_DEFAULT_FRAMERATE_MULTIPLIER
-        )
-        self.framerate = self._get_effective_framerate(framerate_str, multiplier_str)
-
-        if "ttp:tickrate" in tt_attrs:
-            try:
-                tickrate = float(tt_attrs["ttp:tickrate"])
-            except ValueError:
-                raise CaptionReadSyntaxError(
-                    f"ttp:tickRate must be a number, "
-                    f"got '{tt_attrs['ttp:tickrate']}'"
-                )
-            if tickrate <= 0:
-                raise CaptionReadSyntaxError(
-                    f"ttp:tickRate must be positive, got '{tt_attrs['ttp:tickrate']}'"
-                )
-            self.tickrate = tickrate
-        else:
-            # TTML spec 8.2.12: default tickRate = frameRate × subFrameRate
-            try:
-                sub_framerate = int(
-                    tt_attrs.get("ttp:subframerate", DFXP_DEFAULT_SUBFRAMERATE)
-                )
-            except ValueError:
-                raise CaptionReadSyntaxError(
-                    f"ttp:subFrameRate must be a positive integer, "
-                    f"got '{tt_attrs['ttp:subframerate']}'"
-                )
-            try:
-                framerate_int = int(framerate_str)
-            except ValueError:
-                raise CaptionReadSyntaxError(
-                    f"ttp:frameRate must be a positive integer, "
-                    f"got '{framerate_str}'"
-                )
-            self.tickrate = float(framerate_int * sub_framerate)
+        self._resolve_timing_parameters(tt_attrs)
 
         caption_dict = {}
         style_dict = {}
@@ -180,18 +143,71 @@ class DFXPReader(BaseReader):
         for style in dfxp_document.find_all("style"):
             id_ = style.attrs.get(DFXP_ATTR_XML_ID) or style.attrs.get("id")
             if id_:
-                # Styles nested inside <region> tags are region-scoped and
-                # should not appear as document-level styles.
                 if "region" not in [parent_.name for parent_ in style.parents]:
                     style_dict[id_] = self._convert_style(style)
 
-        caption_set = CaptionSet(caption_dict, styles=style_dict)
+        caption_set = CaptionSet(
+            caption_dict, styles=style_dict,
+            visual_alignment_default=HorizontalAlignmentEnum.START,
+        )
 
         if caption_set.is_empty():
             raise CaptionReadNoCaptions("empty caption file")
 
         return caption_set
 
+    def _resolve_timing_parameters(self, tt_attrs):
+        """Extract framerate and tickrate from <tt> attributes.
+
+        Sets self.framerate and self.tickrate per TTML spec sections 8.2.8,
+        8.2.11, and 8.2.12.
+        """
+        framerate_str = tt_attrs.get("ttp:framerate", str(DFXP_DEFAULT_FRAMERATE))
+        multiplier_str = tt_attrs.get(
+            "ttp:frameratemultiplier", DFXP_DEFAULT_FRAMERATE_MULTIPLIER
+        )
+        self.framerate = self._get_effective_framerate(framerate_str, multiplier_str)
+
+        if "ttp:tickrate" in tt_attrs:
+            self._resolve_explicit_tickrate(tt_attrs)
+        else:
+            self._resolve_default_tickrate(tt_attrs, framerate_str)
+
+    def _resolve_explicit_tickrate(self, tt_attrs):
+        """Parse an explicit ttp:tickRate attribute."""
+        try:
+            tickrate = float(tt_attrs["ttp:tickrate"])
+        except ValueError:
+            raise CaptionReadSyntaxError(
+                f"ttp:tickRate must be a number, "
+                f"got '{tt_attrs['ttp:tickrate']}'"
+            )
+        if tickrate <= 0:
+            raise CaptionReadSyntaxError(
+                f"ttp:tickRate must be positive, got '{tt_attrs['ttp:tickrate']}'"
+            )
+        self.tickrate = tickrate
+
+    def _resolve_default_tickrate(self, tt_attrs, framerate_str):
+        """Compute default tickRate = frameRate × subFrameRate (TTML 8.2.12)."""
+        try:
+            sub_framerate = int(
+                tt_attrs.get("ttp:subframerate", DFXP_DEFAULT_SUBFRAMERATE)
+            )
+        except ValueError:
+            raise CaptionReadSyntaxError(
+                f"ttp:subFrameRate must be a positive integer, "
+                f"got '{tt_attrs['ttp:subframerate']}'"
+            )
+        try:
+            framerate_int = int(framerate_str)
+        except ValueError:
+            raise CaptionReadSyntaxError(
+                f"ttp:frameRate must be a positive integer, "
+                f"got '{framerate_str}'"
+            )
+        self.tickrate = float(framerate_int * sub_framerate)
+
     def _convert_div_to_caption_list(self, div):
         """Convert a <div> element into a CaptionList for one language.