chore!: Move subtitle format implementations into pysubs2.formats s…

…ubpackage

This shouldn't affect most users as variables exported from
`pysubs2` as well as `pysubs2.formats` are the same.

It only concerns the implementation modules, eg.
`pysubs2.substation.parse_tags()` is now found in
`pysubs2.formats.substation.parse_tags()`.

docs/api-reference.rst

@@ -85,10 +85,10 @@ Misc methods
 ``pysubs2.formats`` --- subtitle format implementations
 -------------------------------------------------------
 
-.. note:: This submodule contains pysubs2 internals. It's mostly of interest if you're looking to implement
+.. note:: This subpackage contains pysubs2 internals. It's mostly of interest if you're looking to implement
           a subtitle format not supported by the library. In that case, have a look at :class:`pysubs2.formats.FormatBase`.
 
-.. autofunction:: pysubs2.substation.parse_tags
+.. autofunction:: pysubs2.formats.substation.parse_tags
 
 .. automodule:: pysubs2.formats
    :members:
@@ -111,31 +111,31 @@ Here you can find specific details regarding support of the individual subtitle
    These are used to customize the parser/writer behaviour.
 
 
-.. autoclass:: pysubs2.substation.SubstationFormat
+.. autoclass:: pysubs2.formats.substation.SubstationFormat
    :members:
    :show-inheritance:
 
-.. autoclass:: pysubs2.subrip.SubripFormat
+.. autoclass:: pysubs2.formats.subrip.SubripFormat
    :members:
    :show-inheritance:
 
-.. autoclass:: pysubs2.mpl2.MPL2Format
+.. autoclass:: pysubs2.formats.mpl2.MPL2Format
    :members:
    :show-inheritance:
 
-.. autoclass:: pysubs2.tmp.TmpFormat
+.. autoclass:: pysubs2.formats.tmp.TmpFormat
    :members:
    :show-inheritance:
 
-.. autoclass:: pysubs2.webvtt.WebVTTFormat
+.. autoclass:: pysubs2.formats.webvtt.WebVTTFormat
    :members:
    :show-inheritance:
 
-.. autoclass:: pysubs2.microdvd.MicroDVDFormat
+.. autoclass:: pysubs2.formats.microdvd.MicroDVDFormat
    :members:
    :show-inheritance:
 
-.. autoclass:: pysubs2.jsonformat.JSONFormat
+.. autoclass:: pysubs2.formats.jsonformat.JSONFormat
    :members:
    :show-inheritance:
 

pysubs2/__init__.py

@@ -1,24 +1,11 @@
-# ruff: noqa: F401 F403
-
 from .ssafile import SSAFile
 from .ssaevent import SSAEvent
 from .ssastyle import SSAStyle
-from . import time, formats, cli, whisper, exceptions
-from .exceptions import *
+from . import time, formats, cli, exceptions
+from .formats import whisper
+from .exceptions import *  # noqa: F403
 from .common import Color, Alignment, VERSION
 
-#: Alias for :meth:`SSAFile.load()`.
-load = SSAFile.load
-
-#: Alias for :meth:`pysubs2.whisper.load_from_whisper()`.
-load_from_whisper = whisper.load_from_whisper
-
-#: Alias for :meth:`pysubs2.time.make_time()`.
-make_time = time.make_time
-
-#: Alias for `pysubs2.common.VERSION`.
-__version__ = VERSION
-
 __all__ = [
     "SSAFile",
     "SSAEvent",
@@ -35,3 +22,15 @@
     "load_from_whisper",
     "make_time",
 ]
+
+#: Alias for :meth:`SSAFile.load()`.
+load = SSAFile.load
+
+#: Alias for :meth:`pysubs2.whisper.load_from_whisper()`.
+load_from_whisper = whisper.load_from_whisper
+
+#: Alias for :meth:`pysubs2.time.make_time()`.
+make_time = time.make_time
+
+#: Alias for `pysubs2.common.VERSION`.
+__version__ = VERSION

pysubs2/exceptions.py

@@ -1,6 +1,15 @@
 from typing import List
 
 
+__all__ = [
+    "Pysubs2Error",
+    "UnknownFPSError",
+    "UnknownFileExtensionError",
+    "UnknownFormatIdentifierError",
+    "FormatAutodetectionError",
+]
+
+
 class Pysubs2Error(Exception):
     """Base class for pysubs2 exceptions."""
 

pysubs2/formats.py → pysubs2/formats/__init__.py

@@ -1,14 +1,14 @@
 from typing import Dict, Type
 
-from .formatbase import FormatBase
+from .base import FormatBase
 from .microdvd import MicroDVDFormat
 from .subrip import SubripFormat
 from .jsonformat import JSONFormat
 from .substation import SubstationFormat
 from .mpl2 import MPL2Format
 from .tmp import TmpFormat
 from .webvtt import WebVTTFormat
-from .exceptions import UnknownFormatIdentifierError, UnknownFileExtensionError, FormatAutodetectionError
+from ..exceptions import UnknownFormatIdentifierError, UnknownFileExtensionError, FormatAutodetectionError
 
 #: Dict mapping file extensions to format identifiers.
 FILE_EXTENSION_TO_FORMAT_IDENTIFIER: Dict[str, str] = {

pysubs2/formatbase.py → pysubs2/formats/base.py

@@ -1,6 +1,5 @@
-from typing import Optional, TYPE_CHECKING, Any, TextIO
-if TYPE_CHECKING:
-    from .ssafile import SSAFile
+from typing import Optional, Any, TextIO
+from ..ssafile import SSAFile
 
 
 class FormatBase:

pysubs2/jsonformat.py → pysubs2/formats/jsonformat.py

@@ -1,13 +1,12 @@
 import dataclasses
 import json
-from typing import Any, Optional, TextIO, TYPE_CHECKING
+from typing import Any, Optional, TextIO
 
-from .common import Color
-from .ssaevent import SSAEvent
-from .ssastyle import SSAStyle
-from .formatbase import FormatBase
-if TYPE_CHECKING:
-    from .ssafile import SSAFile
+from ..common import Color
+from ..ssaevent import SSAEvent
+from ..ssastyle import SSAStyle
+from .base import FormatBase
+from ..ssafile import SSAFile
 
 
 # We're using Color dataclass

pysubs2/microdvd.py → pysubs2/formats/microdvd.py

@@ -1,15 +1,14 @@
 from functools import partial
 import re
-from typing import Optional, TextIO, Any, Match, TYPE_CHECKING
+from typing import Optional, TextIO, Any, Match
 
-from .exceptions import UnknownFPSError
-from .ssaevent import SSAEvent
-from .ssastyle import SSAStyle
-from .formatbase import FormatBase
+from ..exceptions import UnknownFPSError
+from ..ssaevent import SSAEvent
+from ..ssastyle import SSAStyle
+from .base import FormatBase
 from .substation import parse_tags
-from .time import ms_to_frames, frames_to_ms
-if TYPE_CHECKING:
-    from .ssafile import SSAFile
+from ..time import ms_to_frames, frames_to_ms
+from ..ssafile import SSAFile
 
 
 #: Matches a MicroDVD line.

pysubs2/mpl2.py → pysubs2/formats/mpl2.py

@@ -1,10 +1,9 @@
 import re
-from typing import Optional, Any, TextIO, TYPE_CHECKING
-from .time import times_to_ms
-from .formatbase import FormatBase
-from .ssaevent import SSAEvent
-if TYPE_CHECKING:
-    from .ssafile import SSAFile
+from typing import Optional, Any, TextIO
+from ..time import times_to_ms
+from .base import FormatBase
+from ..ssaevent import SSAEvent
+from ..ssafile import SSAFile
 
 
 # thanks to http://otsaloma.io/gaupol/doc/api/aeidon.files.mpl2_source.html

pysubs2/subrip.py → pysubs2/formats/subrip.py

@@ -1,14 +1,13 @@
 import re
 import warnings
-from typing import List, Sequence, Optional, TextIO, Any, Tuple, TYPE_CHECKING
+from typing import List, Sequence, Optional, TextIO, Any, Tuple
 
-from .formatbase import FormatBase
-from .ssaevent import SSAEvent
-from .ssastyle import SSAStyle
+from .base import FormatBase
+from ..ssaevent import SSAEvent
+from ..ssastyle import SSAStyle
 from .substation import parse_tags
-from .time import ms_to_times, make_time, TIMESTAMP, timestamp_to_ms
-if TYPE_CHECKING:
-    from .ssafile import SSAFile
+from ..time import ms_to_times, make_time, TIMESTAMP, timestamp_to_ms
+from ..ssafile import SSAFile
 
 
 #: Largest timestamp allowed in SubRip, ie. 99:59:59,999.

pysubs2/substation.py → pysubs2/formats/substation.py

@@ -2,15 +2,14 @@
 import re
 import warnings
 from numbers import Number
-from typing import Any, Union, Optional, Dict, Tuple, List, TextIO, TYPE_CHECKING
-
-from .formatbase import FormatBase
-from .ssaevent import SSAEvent
-from .ssastyle import SSAStyle
-from .common import Color, Alignment, SSA_ALIGNMENT
-from .time import make_time, ms_to_times, timestamp_to_ms, TIMESTAMP, TIMESTAMP_SHORT
-if TYPE_CHECKING:
-    from .ssafile import SSAFile
+from typing import Any, Union, Optional, Dict, Tuple, List, TextIO
+
+from .base import FormatBase
+from ..ssaevent import SSAEvent
+from ..ssastyle import SSAStyle
+from ..common import Color, Alignment, SSA_ALIGNMENT
+from ..time import make_time, ms_to_times, timestamp_to_ms, TIMESTAMP, TIMESTAMP_SHORT
+from ..ssafile import SSAFile
 
 
 def ass_to_ssa_alignment(i: int) -> int:

pysubs2/tmp.py → pysubs2/formats/tmp.py

@@ -1,14 +1,13 @@
 import re
 import warnings
-from typing import Optional, TextIO, Any, TYPE_CHECKING
+from typing import Optional, TextIO, Any
 
-from .formatbase import FormatBase
-from .ssaevent import SSAEvent
-from .ssastyle import SSAStyle
+from .base import FormatBase
+from ..ssaevent import SSAEvent
+from ..ssastyle import SSAStyle
 from .substation import parse_tags
-from .time import ms_to_times, make_time, TIMESTAMP_SHORT, timestamp_to_ms
-if TYPE_CHECKING:
-    from .ssafile import SSAFile
+from ..time import ms_to_times, make_time, TIMESTAMP_SHORT, timestamp_to_ms
+from ..ssafile import SSAFile
 
 
 #: Pattern that matches TMP line

pysubs2/webvtt.py → pysubs2/formats/webvtt.py

@@ -1,18 +1,17 @@
 import re
-from typing import List, Sequence, Optional, TextIO, Any, TYPE_CHECKING
+from typing import List, Sequence, Optional, TextIO, Any
 
-from .ssaevent import SSAEvent
+from ..ssaevent import SSAEvent
 from .subrip import SubripFormat
-from .time import make_time
-if TYPE_CHECKING:
-    from .ssafile import SSAFile
+from ..time import make_time
+from ..ssafile import SSAFile
 
 
 class WebVTTFormat(SubripFormat):
     """
     Web Video Text Tracks (WebVTT) subtitle format implementation
 
-    Currently, this shares implementation with :class:`pysubs2.subrip.SubripFormat`.
+    Currently, this shares implementation with :class:`pysubs2.formats.subrip.SubripFormat`.
     """
     TIMESTAMP = re.compile(r"(\d{0,4}:)?(\d{2}):(\d{2})\.(\d{2,3})")
 
@@ -42,7 +41,7 @@ def guess_format(cls, text: str) -> Optional[str]:
     @classmethod
     def to_file(cls, subs: "SSAFile", fp: TextIO, format_: str, **kwargs: Any) -> None:  # type: ignore[override]
         """
-        See :meth:`pysubs2.SubripFormat.to_file()`, additional SRT options are supported by VTT as well
+        See :meth:`pysubs2.formats.SubripFormat.to_file()`, additional SRT options are supported by VTT as well
         """
         print("WEBVTT\n", file=fp)
         return super(WebVTTFormat, cls).to_file(

pysubs2/whisper.py → pysubs2/formats/whisper.py

@@ -5,9 +5,9 @@
 
 """
 
-from .ssaevent import SSAEvent
-from .ssafile import SSAFile
-from .time import make_time
+from ..ssaevent import SSAEvent
+from ..ssafile import SSAFile
+from ..time import make_time
 from typing import Union, List, Dict, Any
 
 

pysubs2/ssaevent.py

@@ -83,7 +83,7 @@ def is_comment(self, value: bool) -> None:
     @property
     def is_drawing(self) -> bool:
         """Returns True if line is SSA drawing tag (ie. not text)"""
-        from .substation import parse_tags
+        from .formats.substation import parse_tags
         return any(sty.drawing for _, sty in parse_tags(self.text))
 
     @property

pysubs2/ssafile.py

@@ -6,8 +6,6 @@
 from typing import Optional, List, Dict, Iterable, Any, overload, Iterator, TextIO, Tuple, MutableSequence
 
 from .common import IntOrFloat
-from .formats import autodetect_format, get_format_class, get_format_identifier
-from .substation import is_valid_field_content
 from .ssaevent import SSAEvent
 from .ssastyle import SSAStyle
 from .time import make_time, ms_to_str
@@ -62,7 +60,7 @@ def load(cls, path: str, encoding: str = "utf-8", format_: Optional[str] = None,
         See also:
             Specific formats may implement additional loading options,
             please refer to documentation of the implementation classes
-            (eg. :meth:`pysubs2.subrip.SubripFormat.from_file()`)
+            (eg. :meth:`pysubs2.formats.subrip.SubripFormat.from_file()`)
 
         Arguments:
             path (str): Path to subtitle file.
@@ -193,7 +191,7 @@ def save(self, path: str, encoding: str = "utf-8", format_: Optional[str] = None
         See also:
             Specific formats may implement additional saving options,
             please refer to documentation of the implementation classes
-            (eg. :meth:`pysubs2.subrip.SubripFormat.to_file()`)
+            (eg. :meth:`pysubs2.formats.subrip.SubripFormat.to_file()`)
 
         Arguments:
             path (str): Path to subtitle file.
@@ -331,6 +329,8 @@ def rename_style(self, old_name: str, new_name: str) -> None:
                 or new_name is taken.
 
         """
+        from .formats.substation import is_valid_field_content
+
         if old_name not in self.styles:
             raise KeyError(f"Style {old_name!r} not found")
         if new_name in self.styles:
@@ -558,3 +558,6 @@ def insert(self, index: int, value: SSAEvent) -> None:
             self.events.insert(index, value)
         else:
             raise TypeError("SSAFile.events must contain only SSAEvent objects")
+
+
+from .formats import autodetect_format, get_format_class, get_format_identifier  # noqa: E402

pysubs2/time.py

@@ -1,6 +1,7 @@
 import re
 from typing import Optional, Sequence, NamedTuple
-from pysubs2.common import IntOrFloat
+
+from .common import IntOrFloat
 
 #: Pattern that matches both SubStation and SubRip timestamps.
 TIMESTAMP = re.compile(r"(\d{1,2}):(\d{1,2}):(\d{1,2})[.,](\d{1,3})")

tests/test_subrip.py → tests/formats/test_subrip.py

@@ -7,7 +7,7 @@
 import pytest
 
 from pysubs2 import SSAFile, SSAEvent, make_time
-from pysubs2.subrip import MAX_REPRESENTABLE_TIME
+from pysubs2.formats.subrip import MAX_REPRESENTABLE_TIME
 
 
 def test_simple_write() -> None:

tests/test_substation.py → tests/formats/test_substation.py

@@ -5,7 +5,7 @@
 import typing
 from textwrap import dedent
 from pysubs2 import SSAFile, SSAEvent, SSAStyle, make_time, Color, Alignment
-from pysubs2.substation import color_to_ass_rgba, color_to_ssa_rgb, rgba_to_color, MAX_REPRESENTABLE_TIME, SubstationFormat
+from pysubs2.formats.substation import color_to_ass_rgba, color_to_ssa_rgb, rgba_to_color, MAX_REPRESENTABLE_TIME, SubstationFormat
 import pytest
 
 

tests/test_tmp.py → tests/formats/test_tmp.py

@@ -7,7 +7,7 @@
 import pytest
 
 from pysubs2 import SSAFile, SSAEvent, make_time
-from pysubs2.tmp import MAX_REPRESENTABLE_TIME
+from pysubs2.formats.tmp import MAX_REPRESENTABLE_TIME
 
 
 def test_simple_write() -> None: