manim 0.18.0.post0__py3-none-any.whl → 0.19.0__py3-none-any.whl

manim/utils/testing/frames_comparison.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import functools
 import inspect
 from pathlib import Path
-from typing import Callable
+from typing import Any, Callable
 
 import cairo
 import pytest
@@ -14,7 +14,9 @@ from manim._config import tempconfig
 from manim._config.utils import ManimConfig
 from manim.camera.three_d_camera import ThreeDCamera
 from manim.renderer.cairo_renderer import CairoRenderer
+from manim.renderer.opengl_renderer import OpenGLRenderer
 from manim.scene.three_d_scene import ThreeDScene
+from manim.typing import StrPath
 
 from ._frames_testers import _ControlDataWriter, _FramesTester
 from ._test_class_makers import (
@@ -31,13 +33,13 @@ MIN_CAIRO_VERSION = 11800
 
 
 def frames_comparison(
-    func=None,
+    func: Callable | None = None,
     *,
     last_frame: bool = True,
-    renderer_class=CairoRenderer,
-    base_scene=Scene,
-    **custom_config,
-):
+    renderer_class: type[CairoRenderer | OpenGLRenderer] = CairoRenderer,
+    base_scene: type[Scene] = Scene,
+    **custom_config: Any,
+) -> Callable:
     """Compares the frames generated by the test with control frames previously registered.
 
     If there is no control frames for this test, the test will fail. To generate
@@ -60,7 +62,7 @@ def frames_comparison(
         If the scene has a moving animation, then the test must set last_frame to False.
     """
 
-    def decorator_maker(tested_scene_construct):
+    def decorator_maker(tested_scene_construct: Callable) -> Callable:
         if (
             SCENE_PARAMETER_NAME
             not in inspect.getfullargspec(tested_scene_construct).args
@@ -79,11 +81,14 @@ def frames_comparison(
                 "There is no module test name indicated for the graphical unit test. You have to declare __module_test__ in the test file.",
             )
         module_name = tested_scene_construct.__globals__.get("__module_test__")
+        assert isinstance(module_name, str)
         test_name = tested_scene_construct.__name__[len("test_") :]
 
         @functools.wraps(tested_scene_construct)
         # The "request" parameter is meant to be used as a fixture by pytest. See below.
-        def wrapper(*args, request: FixtureRequest, tmp_path, **kwargs):
+        def wrapper(
+            *args: Any, request: FixtureRequest, tmp_path: StrPath, **kwargs: Any
+        ) -> None:
             # check for cairo version
             if (
                 renderer_class is CairoRenderer
@@ -146,13 +151,13 @@ def frames_comparison(
                 inspect.Parameter("tmp_path", inspect.Parameter.KEYWORD_ONLY),
             ]
         new_sig = old_sig.replace(parameters=parameters)
-        wrapper.__signature__ = new_sig
+        wrapper.__signature__ = new_sig  # type: ignore[attr-defined]
 
         # Reach a bit into pytest internals to hoist the marks from our wrapped
         # function.
-        setattr(wrapper, "pytestmark", [])
+        wrapper.pytestmark = []  # type: ignore[attr-defined]
         new_marks = getattr(tested_scene_construct, "pytestmark", [])
-        wrapper.pytestmark = new_marks
+        wrapper.pytestmark = new_marks  # type: ignore[attr-defined]
         return wrapper
 
     # Case where the decorator is called with and without parentheses.
@@ -192,9 +197,10 @@ def _make_test_comparing_frames(
     Callable[[], None]
         The pytest test.
     """
-
     if is_set_test_data_test:
-        frames_tester = _ControlDataWriter(file_path, size_frame=size_frame)
+        frames_tester: _FramesTester = _ControlDataWriter(
+            file_path, size_frame=size_frame
+        )
     else:
         frames_tester = _FramesTester(file_path, show_diff=show_diff)
 
@@ -205,7 +211,7 @@ def _make_test_comparing_frames(
     )
     testRenderer = _make_test_renderer_class(renderer_class)
 
-    def real_test():
+    def real_test() -> None:
         with frames_tester.testing():
             sceneTested = _make_test_scene_class(
                 base_scene=base_scene,
@@ -214,11 +220,13 @@ def _make_test_comparing_frames(
                 # If you pass a custom renderer to the Scene, the Camera class given as an argument in the Scene
                 # is not passed to the renderer. See __init__ of Scene.
                 # This potentially prevents OpenGL testing.
-                test_renderer=testRenderer(file_writer_class=file_writer_class)
-                if base_scene is not ThreeDScene
-                else testRenderer(
-                    file_writer_class=file_writer_class,
-                    camera_class=ThreeDCamera,
+                test_renderer=(
+                    testRenderer(file_writer_class=file_writer_class)
+                    if base_scene is not ThreeDScene
+                    else testRenderer(
+                        file_writer_class=file_writer_class,
+                        camera_class=ThreeDCamera,
+                    )
                 ),  # testRenderer(file_writer_class=file_writer_class),
             )
             scene_tested = sceneTested(skip_animations=True)

manim/utils/tex.py

@@ -4,162 +4,135 @@ from __future__ import annotations
 
 __all__ = [
     "TexTemplate",
-    "TexTemplateFromFile",
 ]
 
 import copy
-import os
 import re
+import warnings
+from dataclasses import dataclass, field
 from pathlib import Path
+from typing import TYPE_CHECKING, Any
 
+if TYPE_CHECKING:
+    from typing_extensions import Self
 
-class TexTemplate:
-    """TeX templates are used for creating Tex() and MathTex() objects.
-
-    Parameters
-    ----------
-    tex_compiler
-        The TeX compiler to be used, e.g. ``latex``, ``pdflatex`` or ``lualatex``
-    output_format
-        The output format resulting from compilation, e.g. ``.dvi`` or ``.pdf``
-    documentclass
-        The command defining the documentclass, e.g. ``\\documentclass[preview]{standalone}``
-    preamble
-        The document's preamble, i.e. the part between ``\\documentclass`` and ``\\begin{document}``
-    placeholder_text
-        Text in the document that will be replaced by the expression to be rendered
-    post_doc_commands
-        Text (definitions, commands) to be inserted at right after ``\\begin{document}``, e.g. ``\\boldmath``
-
-    Attributes
-    ----------
-    tex_compiler : :class:`str`
-        The TeX compiler to be used, e.g. ``latex``, ``pdflatex`` or ``lualatex``
-    output_format : :class:`str`
-        The output format resulting from compilation, e.g. ``.dvi`` or ``.pdf``
-    documentclass : :class:`str`
-        The command defining the documentclass, e.g. ``\\documentclass[preview]{standalone}``
-    preamble : :class:`str`
-        The document's preamble, i.e. the part between ``\\documentclass`` and ``\\begin{document}``
-    placeholder_text : :class:`str`
-        Text in the document that will be replaced by the expression to be rendered
-    post_doc_commands : :class:`str`
-        Text (definitions, commands) to be inserted at right after ``\\begin{document}``, e.g. ``\\boldmath``
-    """
+    from manim.typing import StrPath
 
-    default_documentclass = r"\documentclass[preview]{standalone}"
-    default_preamble = r"""
-\usepackage[english]{babel}
+_DEFAULT_PREAMBLE = r"""\usepackage[english]{babel}
 \usepackage{amsmath}
-\usepackage{amssymb}
-"""
-    default_placeholder_text = "YourTextHere"
-    default_tex_compiler = "latex"
-    default_output_format = ".dvi"
-    default_post_doc_commands = ""
-
-    def __init__(
-        self,
-        tex_compiler: str | None = None,
-        output_format: str | None = None,
-        documentclass: str | None = None,
-        preamble: str | None = None,
-        placeholder_text: str | None = None,
-        post_doc_commands: str | None = None,
-        **kwargs,
-    ):
-        self.tex_compiler = (
-            tex_compiler
-            if tex_compiler is not None
-            else TexTemplate.default_tex_compiler
-        )
-        self.output_format = (
-            output_format
-            if output_format is not None
-            else TexTemplate.default_output_format
-        )
-        self.documentclass = (
-            documentclass
-            if documentclass is not None
-            else TexTemplate.default_documentclass
-        )
-        self.preamble = (
-            preamble if preamble is not None else TexTemplate.default_preamble
-        )
-        self.placeholder_text = (
-            placeholder_text
-            if placeholder_text is not None
-            else TexTemplate.default_placeholder_text
-        )
-        self.post_doc_commands = (
-            post_doc_commands
-            if post_doc_commands is not None
-            else TexTemplate.default_post_doc_commands
-        )
-        self._rebuild()
-
-    def __eq__(self, other: TexTemplate) -> bool:
-        return (
-            self.body == other.body
-            and self.tex_compiler == other.tex_compiler
-            and self.output_format == other.output_format
-            and self.post_doc_commands == other.post_doc_commands
-        )
+\usepackage{amssymb}"""
+
+_BEGIN_DOCUMENT = r"\begin{document}"
+_END_DOCUMENT = r"\end{document}"
+
 
-    def _rebuild(self):
-        """Rebuilds the entire TeX template text from ``\\documentclass`` to ``\\end{document}`` according to all settings and choices."""
-        self.body = (
-            self.documentclass
-            + "\n"
-            + self.preamble
-            + "\n"
-            + r"\begin{document}"
-            + "\n"
-            + self.post_doc_commands
-            + "\n"
-            + self.placeholder_text
-            + "\n"
-            + "\n"
-            + r"\end{document}"
-            + "\n"
+@dataclass(eq=True)
+class TexTemplate:
+    """TeX templates are used to create ``Tex`` and ``MathTex`` objects."""
+
+    _body: str = field(default="", init=False)
+    """A custom body, can be set from a file."""
+
+    tex_compiler: str = "latex"
+    """The TeX compiler to be used, e.g. ``latex``, ``pdflatex`` or ``lualatex``."""
+
+    description: str = ""
+    """A description of the template"""
+
+    output_format: str = ".dvi"
+    """The output format resulting from compilation, e.g. ``.dvi`` or ``.pdf``."""
+
+    documentclass: str = r"\documentclass[preview]{standalone}"
+    r"""The command defining the documentclass, e.g. ``\documentclass[preview]{standalone}``."""
+
+    preamble: str = _DEFAULT_PREAMBLE
+    r"""The document's preamble, i.e. the part between ``\documentclass`` and ``\begin{document}``."""
+
+    placeholder_text: str = "YourTextHere"
+    """Text in the document that will be replaced by the expression to be rendered."""
+
+    post_doc_commands: str = ""
+    r"""Text (definitions, commands) to be inserted at right after ``\begin{document}``, e.g. ``\boldmath``."""
+
+    @property
+    def body(self) -> str:
+        """The entire TeX template."""
+        return self._body or "\n".join(
+            filter(
+                None,
+                [
+                    self.documentclass,
+                    self.preamble,
+                    _BEGIN_DOCUMENT,
+                    self.post_doc_commands,
+                    self.placeholder_text,
+                    _END_DOCUMENT,
+                ],
+            )
         )
 
-    def add_to_preamble(self, txt: str, prepend: bool = False):
-        """Adds stuff to the TeX template's preamble (e.g. definitions, packages). Text can be inserted at the beginning or at the end of the preamble.
+    @body.setter
+    def body(self, value: str) -> None:
+        self._body = value
+
+    @classmethod
+    def from_file(cls, file: StrPath = "tex_template.tex", **kwargs: Any) -> Self:
+        """Create an instance by reading the content of a file.
+
+        Using the ``add_to_preamble`` and ``add_to_document`` methods on this instance
+        will have no effect, as the body is read from the file.
+        """
+        instance = cls(**kwargs)
+        instance.body = Path(file).read_text(encoding="utf-8")
+        return instance
+
+    def add_to_preamble(self, txt: str, prepend: bool = False) -> Self:
+        r"""Adds text to the TeX template's preamble (e.g. definitions, packages). Text can be inserted at the beginning or at the end of the preamble.
 
         Parameters
         ----------
         txt
-            String containing the text to be added, e.g. ``\\usepackage{hyperref}``
+            String containing the text to be added, e.g. ``\usepackage{hyperref}``.
         prepend
-            Whether the text should be added at the beginning of the preamble, i.e. right after ``\\documentclass``. Default is to add it at the end of the preamble, i.e. right before ``\\begin{document}``
+            Whether the text should be added at the beginning of the preamble, i.e. right after ``\documentclass``.
+            Default is to add it at the end of the preamble, i.e. right before ``\begin{document}``.
         """
+        if self._body:
+            warnings.warn(
+                "This TeX template was created with a fixed body, trying to add text the preamble will have no effect.",
+                UserWarning,
+                stacklevel=2,
+            )
         if prepend:
             self.preamble = txt + "\n" + self.preamble
         else:
             self.preamble += "\n" + txt
-        self._rebuild()
         return self
 
-    def add_to_document(self, txt: str):
-        """Adds txt to the TeX template just after \\begin{document}, e.g. ``\\boldmath``
+    def add_to_document(self, txt: str) -> Self:
+        r"""Adds text to the TeX template just after \begin{document}, e.g. ``\boldmath``.
 
         Parameters
         ----------
         txt
             String containing the text to be added.
         """
-        self.post_doc_commands += "\n" + txt + "\n"
-        self._rebuild()
+        if self._body:
+            warnings.warn(
+                "This TeX template was created with a fixed body, trying to add text the document will have no effect.",
+                UserWarning,
+                stacklevel=2,
+            )
+        self.post_doc_commands += txt
         return self
 
-    def get_texcode_for_expression(self, expression: str):
-        """Inserts expression verbatim into TeX template.
+    def get_texcode_for_expression(self, expression: str) -> str:
+        r"""Inserts expression verbatim into TeX template.
 
         Parameters
         ----------
         expression
-            The string containing the expression to be typeset, e.g. ``$\\sqrt{2}$``
+            The string containing the expression to be typeset, e.g. ``$\sqrt{2}$``
 
         Returns
         -------
@@ -168,102 +141,59 @@ class TexTemplate:
         """
         return self.body.replace(self.placeholder_text, expression)
 
-    def _texcode_for_environment(self, environment: str):
-        """Processes the tex_environment string to return the correct ``\\begin{environment}[extra]{extra}`` and
-        ``\\end{environment}`` strings
-
-        Parameters
-        ----------
-        environment
-            The tex_environment as a string. Acceptable formats include:
-            ``{align*}``, ``align*``, ``{tabular}[t]{cccl}``, ``tabular}{cccl``, ``\\begin{tabular}[t]{cccl}``.
-
-        Returns
-        -------
-        Tuple[:class:`str`, :class:`str`]
-            A pair of strings representing the opening and closing of the tex environment, e.g.
-            ``\\begin{tabular}{cccl}`` and ``\\end{tabular}``
-        """
-
-        # If the environment starts with \begin, remove it
-        if environment[0:6] == r"\begin":
-            environment = environment[6:]
-
-        # If environment begins with { strip it
-        if environment[0] == r"{":
-            environment = environment[1:]
-
-        # The \begin command takes everything and closes with a brace
-        begin = r"\begin{" + environment
-        if (
-            begin[-1] != r"}" and begin[-1] != r"]"
-        ):  # If it doesn't end on } or ], assume missing }
-            begin += r"}"
-
-        # While the \end command terminates at the first closing brace
-        split_at_brace = re.split(r"}", environment, 1)
-        end = r"\end{" + split_at_brace[0] + r"}"
-
-        return begin, end
-
-    def get_texcode_for_expression_in_env(self, expression: str, environment: str):
-        r"""Inserts expression into TeX template wrapped in \begin{environment} and \end{environment}
+    def get_texcode_for_expression_in_env(
+        self, expression: str, environment: str
+    ) -> str:
+        r"""Inserts expression into TeX template wrapped in ``\begin{environment}`` and ``\end{environment}``.
 
         Parameters
         ----------
         expression
-            The string containing the expression to be typeset, e.g. ``$\\sqrt{2}$``
+            The string containing the expression to be typeset, e.g. ``$\sqrt{2}$``.
         environment
-            The string containing the environment in which the expression should be typeset, e.g. ``align*``
+            The string containing the environment in which the expression should be typeset, e.g. ``align*``.
 
         Returns
         -------
         :class:`str`
             LaTeX code based on template, containing the given expression inside its environment, ready for typesetting
         """
-        begin, end = self._texcode_for_environment(environment)
-        return self.body.replace(self.placeholder_text, f"{begin}\n{expression}\n{end}")
+        begin, end = _texcode_for_environment(environment)
+        return self.body.replace(
+            self.placeholder_text, "\n".join([begin, expression, end])
+        )
 
-    def copy(self) -> TexTemplate:
+    def copy(self) -> Self:
+        """Create a deep copy of the TeX template instance."""
         return copy.deepcopy(self)
 
 
-class TexTemplateFromFile(TexTemplate):
-    """A TexTemplate object created from a template file (default: tex_template.tex)
+def _texcode_for_environment(environment: str) -> tuple[str, str]:
+    r"""Processes the tex_environment string to return the correct ``\begin{environment}[extra]{extra}`` and
+    ``\end{environment}`` strings.
 
     Parameters
     ----------
-    tex_filename
-        Path to a valid TeX template file
-    kwargs
-        Arguments for :class:`~.TexTemplate`.
-
-    Attributes
-    ----------
-    template_file : :class:`str`
-        Path to a valid TeX template file
-    body : :class:`str`
-        Content of the TeX template file
-    tex_compiler : :class:`str`
-        The TeX compiler to be used, e.g. ``latex``, ``pdflatex`` or ``lualatex``
-    output_format : :class:`str`
-        The output format resulting from compilation, e.g. ``.dvi`` or ``.pdf``
+    environment
+        The tex_environment as a string. Acceptable formats include:
+        ``{align*}``, ``align*``, ``{tabular}[t]{cccl}``, ``tabular}{cccl``, ``\begin{tabular}[t]{cccl}``.
+
+    Returns
+    -------
+    Tuple[:class:`str`, :class:`str`]
+        A pair of strings representing the opening and closing of the tex environment, e.g.
+        ``\begin{tabular}{cccl}`` and ``\end{tabular}``
     """
+    environment.removeprefix(r"\begin").removeprefix("{")
 
-    def __init__(
-        self, *, tex_filename: str | os.PathLike = "tex_template.tex", **kwargs
-    ):
-        self.template_file = Path(tex_filename)
-        super().__init__(**kwargs)
-
-    def _rebuild(self):
-        self.body = self.template_file.read_text()
-
-    def file_not_mutable(self):
-        raise Exception("Cannot modify TexTemplate when using a template file.")
+    # The \begin command takes everything and closes with a brace
+    begin = r"\begin{" + environment
+    # If it doesn't end on } or ], assume missing }
+    if not begin.endswith(("}", "]")):
+        begin += "}"
 
-    def add_to_preamble(self, txt, prepend=False):
-        self.file_not_mutable()
+    # While the \end command terminates at the first closing brace
+    split_at_brace = re.split("}", environment, maxsplit=1)
+    end = r"\end{" + split_at_brace[0] + "}"
 
-    def add_to_document(self, txt):
-        self.file_not_mutable()
+    return begin, end