pycaption 2.2.28__tar.gz → 2.3.0__tar.gz

{pycaption-2.2.28/pycaption.egg-info → pycaption-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycaption
-Version: 2.2.28
+Version: 2.3.0
 Summary: Closed caption converter
 Author: Joe Norton
 Author-email: joey@nortoncrew.com
@@ -27,7 +27,7 @@ Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-lazy-fixture; extra == "dev"
 Provides-Extra: transcript
-Requires-Dist: nltk==3.9.4; extra == "transcript"
+Requires-Dist: nltk==3.10.0; extra == "transcript"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier

{pycaption-2.2.28 → pycaption-2.3.0}/pycaption/__init__.py

@@ -1,10 +1,17 @@
+"""pycaption — closed caption reading/writing library.
+
+Reads captions from DFXP/TTML, SRT, SAMI, SCC, WebVTT, and MicroDVD into
+a common intermediate representation (CaptionSet), and writes them back
+to any supported format.
+"""
+
 from .base import Caption, CaptionConverter, CaptionList, CaptionNode, CaptionSet
 from .dfxp import DFXPReader, DFXPWriter
 from .exceptions import (
-    CaptionLineLengthError,
     CaptionReadError,
     CaptionReadNoCaptions,
     CaptionReadSyntaxError,
+    CaptionReadWarning,
 )
 from .microdvd import MicroDVDReader, MicroDVDWriter
 from .sami import SAMIReader, SAMIWriter
@@ -32,6 +39,7 @@ __all__ = [
     "CaptionReadError",
     "CaptionReadNoCaptions",
     "CaptionReadSyntaxError",
+    "CaptionReadWarning",
     "detect_format",
     "CaptionNode",
     "Caption",
@@ -51,10 +59,15 @@ SUPPORTED_READERS = (
 
 
 def detect_format(caps):
-    """
-    Detect the format of the provided caption string.
+    """Detect the caption format of the provided string.
+
+    Tries each reader's ``detect()`` method in order and returns the
+    first matching reader class, or None if no format matches.
 
-    :returns: the reader class for the detected format.
+    :param caps: Raw caption file content.
+    :returns: The reader class for the detected format, or None.
+    :rtype: type | None
+    :raises CaptionReadNoCaptions: if caps is empty.
     """
     if not len(caps):
         raise CaptionReadNoCaptions("Empty caption file")

{pycaption-2.2.28 → pycaption-2.3.0}/pycaption/base.py

@@ -1,5 +1,11 @@
+"""Core data model for pycaption.
+
+Defines the intermediate representation used by all readers and writers:
+CaptionSet -> CaptionList -> Caption -> CaptionNode.  Also provides the
+CaptionConverter orchestrator and base classes for readers/writers.
+"""
+
 import os
-from collections import defaultdict
 from datetime import timedelta
 from numbers import Number
 
@@ -9,20 +15,26 @@ from .exceptions import CaptionReadError, CaptionReadTimingError
 DEFAULT_LANGUAGE_CODE = os.getenv("PYCAPTION_DEFAULT_LANG", "und")
 
 
-def force_byte_string(content):
-    try:
-        return content.encode("UTF-8")
-    except UnicodeEncodeError:
-        raise RuntimeError("Invalid content encoding")
-    except UnicodeDecodeError:
-        return content
+class CaptionConverter:
+    """High-level orchestrator: read content with a reader, write with a writer.
 
+    Usage::
+
+        converter = CaptionConverter()
+        converter.read(srt_content, SRTReader())
+        output = converter.write(WebVTTWriter())
+    """
 
-class CaptionConverter:
     def __init__(self, captions=None):
         self.captions = captions if captions else []
 
     def read(self, content, caption_reader):
+        """Parse caption content using the given reader.
+
+        :param content: Raw caption file content (string).
+        :param caption_reader: A BaseReader subclass instance.
+        :returns: self (for chaining).
+        """
         try:
             self.captions = caption_reader.read(content)
         except AttributeError as e:
@@ -30,6 +42,12 @@ class CaptionConverter:
         return self
 
     def write(self, caption_writer):
+        """Serialize the stored CaptionSet using the given writer.
+
+        :param caption_writer: A BaseWriter subclass instance.
+        :returns: The serialized caption string.
+        :rtype: str
+        """
         try:
             return caption_writer.write(self.captions)
         except AttributeError as e:
@@ -37,20 +55,31 @@ class CaptionConverter:
 
 
 class BaseReader:
+    """Abstract base class for caption format readers."""
+
     def __init__(self, *args, **kwargs):
         pass
 
     def detect(self, content):
-        if content:
-            return True
-        else:
-            return False
+        """Return True if content appears to be in this reader's format.
+
+        :param content: Raw caption file content.
+        :rtype: bool
+        """
+        return bool(content)
 
     def read(self, content):
+        """Parse content into a CaptionSet.
+
+        :param content: Raw caption file content.
+        :rtype: CaptionSet
+        """
         return CaptionSet({DEFAULT_LANGUAGE_CODE: []})
 
 
 class BaseWriter:
+    """Abstract base class for caption format writers."""
+
     def __init__(
         self, relativize=True, video_width=None, video_height=None, fit_to_screen=True
     ):
@@ -79,6 +108,11 @@ class BaseWriter:
         self.fit_to_screen = fit_to_screen
 
     def _relativize_and_fit_to_screen(self, layout_info):
+        """Apply relativization and fit-to-screen adjustments to a Layout.
+
+        :param layout_info: A Layout instance (or None).
+        :rtype: Layout | None
+        """
         if layout_info:
             if self.relativize:
                 # Transform absolute values (e.g. px) into percentages
@@ -91,12 +125,12 @@ class BaseWriter:
         return layout_info
 
     def write(self, content):
-        return content
-
+        """Serialize a CaptionSet. Subclasses override this.
 
-class Style:
-    def __init__(self):
-        pass
+        :type content: CaptionSet
+        :rtype: str
+        """
+        return content
 
 
 class CaptionNode:
@@ -146,6 +180,7 @@ class CaptionNode:
 
     @staticmethod
     def create_text(text, layout_info=None, position=None):
+        """Create a TEXT node with the given content string."""
         return CaptionNode(
             type_=CaptionNode.TEXT,
             layout_info=layout_info,
@@ -155,6 +190,7 @@ class CaptionNode:
 
     @staticmethod
     def create_style(start, content, layout_info=None):
+        """Create a STYLE node (start=True opens, start=False closes)."""
         return CaptionNode(
             type_=CaptionNode.STYLE,
             layout_info=layout_info,
@@ -164,6 +200,7 @@ class CaptionNode:
 
     @staticmethod
     def create_break(layout_info=None, content=None):
+        """Create a BREAK (line-break) node."""
         return CaptionNode(
             type_=CaptionNode.BREAK, layout_info=layout_info, content=content
         )
@@ -175,7 +212,7 @@ class Caption:
     for its display.
     """
 
-    def __init__(self, start, end, nodes, style={}, layout_info=None):
+    def __init__(self, start, end, nodes, style=None, layout_info=None):
         """
         Initialize the Caption object
         :param start: The start time in microseconds
@@ -192,35 +229,39 @@ class Caption:
         """
         if not isinstance(start, Number):
             raise CaptionReadTimingError(
-                "Captions must be initialized with a" " valid start time"
+                "Captions must be initialized with a valid start time"
             )
         if not isinstance(end, Number):
             raise CaptionReadTimingError(
-                "Captions must be initialized with a" " valid end time"
+                "Captions must be initialized with a valid end time"
             )
         if not nodes:
             raise CaptionReadError("Node list cannot be empty")
         self.start = start
         self.end = end
         self.nodes = nodes
-        self.style = style
+        self.style = style or {}
         self.layout_info = layout_info
 
     def is_empty(self):
-        return len(self.nodes) == 0
+        """Return True if this caption has no nodes."""
+        return not self.nodes
 
     def format_start(self, msec_separator=None):
-        """
-        Format the start time value in milliseconds into a string
-        value suitable for some of the supported output formats (ex.
-        SRT, DFXP).
+        """Format start time as HH:MM:SS.mmm string.
+
+        :param msec_separator: Character between seconds and milliseconds
+            (default '.').
+        :rtype: str
         """
         return self._format_timestamp(self.start, msec_separator)
 
     def format_end(self, msec_separator=None):
-        """
-        Format the end time value in milliseconds into a string value suitable
-        for some of the supported output formats (ex. SRT, DFXP).
+        """Format end time as HH:MM:SS.mmm string.
+
+        :param msec_separator: Character between seconds and milliseconds
+            (default '.').
+        :rtype: str
         """
         return self._format_timestamp(self.end, msec_separator)
 
@@ -228,24 +269,28 @@ class Caption:
         return repr(f"{self.format_start()} --> {self.format_end()}\n{self.get_text()}")
 
     def get_text_nodes(self):
-        """
-        Get the text of the caption.
-        """
+        """Return list of text content strings (with '\\n' for breaks).
 
-        def get_text_for_node(node):
+        :rtype: list[str]
+        """
+        result = []
+        for node in self.nodes:
             if node.type_ == CaptionNode.TEXT:
-                return node.content
-            if node.type_ == CaptionNode.BREAK:
-                return "\n"
-            return ""
-
-        return [get_text_for_node(node) for node in self.nodes]
+                result.append(node.content)
+            elif node.type_ == CaptionNode.BREAK:
+                result.append("\n")
+        return result
 
     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()
 
     def _format_timestamp(self, 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)
@@ -269,9 +314,6 @@ class CaptionList(list):
         args = [iterable] if iterable else []
         super().__init__(*args)
 
-    def __getslice__(self, i, j):
-        return CaptionList(list.__getslice__(self, i, j), layout_info=self.layout_info)
-
     def __getitem__(self, y):
         item = list.__getitem__(self, y)
         if isinstance(item, Caption):
@@ -306,23 +348,39 @@ class CaptionSet:
     by all the children.
     """
 
-    def __init__(self, captions, styles={}, layout_info=None):
+    def __init__(self, captions, styles=None, layout_info=None, regions=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
         """
         self._captions = captions
-        self._styles = styles
+        self._styles = styles or {}
+        self._regions = regions or {}
         self.layout_info = layout_info
 
     def set_captions(self, lang, captions):
+        """Replace the caption list for a given language.
+
+        :param lang: Language code (e.g. 'en-US').
+        :param captions: A CaptionList instance.
+        """
         self._captions[lang] = captions
 
     def get_languages(self):
+        """Return list of language codes in this caption set.
+
+        :rtype: list[str]
+        """
         return list(self._captions.keys())
 
     def get_captions(self, lang):
+        """Return the CaptionList for the given language, or empty list.
+
+        :param lang: Language code.
+        :rtype: CaptionList | list
+        """
         return self._captions.get(lang, [])
 
     def add_style(self, selector, rules):
@@ -342,18 +400,51 @@ class CaptionSet:
         return self._styles.get(selector, {})
 
     def get_styles(self):
+        """Return all styles as sorted (selector, rules) pairs.
+
+        :rtype: list[tuple[str, dict]]
+        """
         return sorted(self._styles.items())
 
     def set_styles(self, styles):
+        """Replace all styles with the given dictionary.
+
+        :param styles: dict mapping selectors to rule dictionaries.
+        """
         self._styles = styles
 
+    def get_regions(self):
+        """Return raw region definitions for the writer to re-emit.
+
+        :rtype: dict[str, dict[str, str]]
+        """
+        return self._regions
+
+    def set_regions(self, regions):
+        """Replace all region definitions.
+
+        :param regions: dict mapping region id to settings dict.
+        """
+        self._regions = regions
+
     def is_empty(self):
+        """Return True if no language contains any captions."""
         return all([len(captions) == 0 for captions in list(self._captions.values())])
 
     def set_layout_info(self, lang, layout_info):
+        """Set the layout_info on the CaptionList for a given language.
+
+        :param lang: Language code.
+        :param layout_info: A Layout instance.
+        """
         self._captions[lang].layout_info = layout_info
 
     def get_layout_info(self, lang):
+        """Return the layout_info for a given language's CaptionList.
+
+        :param lang: Language code.
+        :rtype: Layout | None
+        """
         caption_list = self._captions.get(lang)
         if caption_list:
             return caption_list.layout_info

pycaption-2.3.0/pycaption/dfxp/__init__.py

@@ -0,0 +1,22 @@
+"""DFXP/TTML caption format reader and writer package.
+
+Provides DFXPReader for parsing DFXP/TTML files into CaptionSet objects,
+DFXPWriter for serializing CaptionSet objects to DFXP/TTML, and legacy/
+single-positioning writer variants.
+"""
+
+from .constants import (  # noqa: F401
+    DFXP_ATTR_XML_ID,
+    DFXP_ATTR_XML_LANG,
+    DFXP_BASE_MARKUP,
+    DFXP_DEFAULT_LANGUAGE_CODE,
+    DFXP_DEFAULT_REGION,
+    DFXP_DEFAULT_REGION_ID,
+    DFXP_DEFAULT_STYLE,
+    DFXP_DEFAULT_STYLE_ID,
+    HORIZONTAL_ALIGNMENT_TO_DFXP,
+    VERTICAL_ALIGNMENT_TO_DFXP,
+)
+from .extras import LegacyDFXPWriter, SinglePositioningDFXPWriter  # noqa: F401
+from .reader import DFXPReader  # noqa: F401
+from .writer import DFXPWriter  # noqa: F401

pycaption-2.3.0/pycaption/dfxp/constants.py

@@ -0,0 +1,96 @@
+"""Constants for the DFXP/TTML reader and writer.
+
+Defines default styles, regions, time-expression patterns, alignment
+mappings, and frame-rate defaults used throughout the DFXP package.
+"""
+
+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">
+    <head>
+        <styling/>
+        <layout/>
+    </head>
+    <body/>
+</tt>
+"""
+
+DFXP_DEFAULT_STYLE = {
+    "color": "white",
+    "font-family": "monospace",
+    "font-size": "1c",
+}
+
+DFXP_DEFAULT_REGION = Layout(
+    alignment=Alignment(HorizontalAlignmentEnum.START, VerticalAlignmentEnum.BOTTOM)
+)
+
+DFXP_DEFAULT_STYLE_ID = "default"
+DFXP_DEFAULT_REGION_ID = "bottom"
+
+CLOCK_TIME_PATTERN = (
+    r"(?P<clock_time>(?P<hours>\d+):(?P<minutes>\d{2}):(?P<seconds>\d{2})"
+    r"(:(?P<frames>\d{2})|\.(?P<sub_frames>\d+))?)"
+)
+OFFSET_TIME_PATTERN = (
+    r"(?P<offset_time>(?P<time_count>\d+(\.\d+)?)" r"(?P<metric>h|m|s|ms|f|t))"
+)
+TIME_EXPRESSION_PATTERN = re.compile(rf"^({CLOCK_TIME_PATTERN}|{OFFSET_TIME_PATTERN})$")
+
+MICROSECONDS_PER_UNIT = {
+    "hours": 3600000000,
+    "minutes": 60000000,
+    "seconds": 1000000,
+    "milliseconds": 1000,
+}
+
+DFXP_DEFAULT_LANGUAGE_CODE = "en"
+
+DFXP_ATTR_XML_LANG = "xml:lang"
+DFXP_ATTR_XML_ID = "xml:id"
+
+HORIZONTAL_ALIGNMENT_TO_DFXP = {
+    HorizontalAlignmentEnum.LEFT: "left",
+    HorizontalAlignmentEnum.CENTER: "center",
+    HorizontalAlignmentEnum.RIGHT: "right",
+    HorizontalAlignmentEnum.START: "start",
+    HorizontalAlignmentEnum.END: "end",
+}
+
+VERTICAL_ALIGNMENT_TO_DFXP = {
+    VerticalAlignmentEnum.TOP: "before",
+    VerticalAlignmentEnum.CENTER: "center",
+    VerticalAlignmentEnum.BOTTOM: "after",
+}
+
+DFXP_DEFAULT_FRAMERATE = 30
+DFXP_DEFAULT_FRAMERATE_MULTIPLIER = "1 1"
+DFXP_DEFAULT_SUBFRAMERATE = 1
+DFXP_DEFAULT_TICKRATE = DFXP_DEFAULT_FRAMERATE * DFXP_DEFAULT_SUBFRAMERATE
+
+
+def _create_external_alignment(alignment):
+    """Convert an Alignment object to a dict of DFXP attributes.
+
+    :type alignment: Alignment
+    :rtype: dict
+    """
+    result = {}
+    if not alignment:
+        return result
+    if not (alignment.horizontal or alignment.vertical):
+        return result
+
+    horizontal = HORIZONTAL_ALIGNMENT_TO_DFXP.get(alignment.horizontal)
+    if horizontal:
+        result["tts:textAlign"] = horizontal
+
+    vertical = VERTICAL_ALIGNMENT_TO_DFXP.get(alignment.vertical)
+    if vertical:
+        result["tts:displayAlign"] = vertical
+
+    return result