from typing import Optional
import io


class FormatBase:
    """
    Base class for subtitle format implementations.

    How to implement a new subtitle format:

    1. Create a subclass of FormatBase and override the methods you want to support.
    2. Decide on a format identifier, like the ``"srt"`` or ``"microdvd"`` already used in the library.
    3. Add your identifier and class to :data:`pysubs2.formats.FORMAT_IDENTIFIER_TO_FORMAT_CLASS`.
    4. (optional) Add your file extension and class to :data:`pysubs2.formats.FILE_EXTENSION_TO_FORMAT_IDENTIFIER`.

    After finishing these steps, you can call :meth:`SSAFile.load()` and :meth:`SSAFile.save()` with your
    format, including autodetection from content and file extension (if you provided these).

    """
    @classmethod
    def from_file(cls, subs, fp: io.TextIOBase, format_: str, **kwargs):
        """
        Load subtitle file into an empty SSAFile.

        If the parser autodetects framerate, set it as ``subs.fps``.

        Arguments:
            subs (SSAFile): An empty :class:`SSAFile`.
            fp (file object): Text file object, the subtitle file.
            format_ (str): Format identifier. Used when one format class
                implements multiple formats (see :class:`SubstationFormat`).
            kwargs: Extra options, eg. `fps`.

        Returns:
            None

        Raises:
            pysubs2.exceptions.UnknownFPSError: Framerate was not provided and cannot
                be detected.
        """
        raise NotImplementedError("Parsing is not supported for this format")

    @classmethod
    def to_file(cls, subs, fp: io.TextIOBase, format_: str, **kwargs):
        """
        Write SSAFile into a file.

        If you need framerate and it is not passed in keyword arguments,
        use ``subs.fps``.

        Arguments:
            subs (SSAFile): Subtitle file to write.
            fp (file object): Text file object used as output.
            format_ (str): Format identifier of desired output format.
                Used when one format class implements multiple formats
                (see :class:`SubstationFormat`).
            kwargs: Extra options, eg. `fps`.

        Returns:
            None

        Raises:
            pysubs2.exceptions.UnknownFPSError: Framerate was not provided and
                ``subs.fps is None``.
        """
        raise NotImplementedError("Writing is not supported for this format")

    @classmethod
    def guess_format(self, text: str) -> Optional[str]:
        """
        Return format identifier of recognized format, or None.

        Arguments:
            text (str): Content of subtitle file. When the file is long,
                this may be only its first few thousand characters.

        Returns:
            format identifier (eg. ``"srt"``) or None (unknown format)
        """
        return None