manim 0.17.0__py3-none-any.whl → 0.19.1__py3-none-any.whl

manim/utils/docbuild/manim_directive.py

@@ -26,7 +26,7 @@ render scenes that are defined within doctests, for example::
         >>> from manim import Create, Dot, RED, Scene
         >>> dot = Dot(color=RED)
         >>> dot.color
-        <Color #fc6255>
+        ManimColor('#FC6255')
         >>> class DirectiveDoctestExample(Scene):
         ...     def construct(self):
         ...         self.play(Create(dot))
@@ -77,25 +77,40 @@ directive:
         that is rendered in a reference block after the source code.
 
 """
+
 from __future__ import annotations
 
 import csv
 import itertools as it
-import os
 import re
 import shutil
 import sys
+import textwrap
 from pathlib import Path
 from timeit import timeit
+from typing import TYPE_CHECKING, Any, TypedDict
 
 import jinja2
 from docutils import nodes
-from docutils.parsers.rst import Directive, directives  # type: ignore
+from docutils.parsers.rst import Directive, directives
 from docutils.statemachine import StringList
 
 from manim import QUALITIES
+from manim import __version__ as manim_version
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+
+__all__ = ["ManimDirective"]
+
 
-classnamedict = {}
+classnamedict: dict[str, int] = {}
+
+
+class SetupMetadata(TypedDict):
+    parallel_read_safe: bool
+    parallel_write_safe: bool
 
 
 class SkipManimNode(nodes.Admonition, nodes.Element):
@@ -108,14 +123,16 @@ class SkipManimNode(nodes.Admonition, nodes.Element):
     pass
 
 
-def visit(self, node, name=""):
-    self.visit_admonition(node, name)
+def visit(self: SkipManimNode, node: nodes.Element, name: str = "") -> None:
+    # TODO: Parent classes don't have a visit_admonition() method.
+    self.visit_admonition(node, name)  # type: ignore[attr-defined]
     if not isinstance(node[0], nodes.title):
         node.insert(0, nodes.title("skip-manim", "Example Placeholder"))
 
 
-def depart(self, node):
-    self.depart_admonition(node)
+def depart(self: SkipManimNode, node: nodes.Element) -> None:
+    # TODO: Parent classes don't have a depart_admonition() method.
+    self.depart_admonition(node)  # type: ignore[attr-defined]
 
 
 def process_name_list(option_input: str, reference_type: str) -> list[str]:
@@ -141,6 +158,7 @@ class ManimDirective(Directive):
 
     See the module docstring for documentation.
     """
+
     has_content = True
     required_arguments = 1
     optional_arguments = 0
@@ -160,24 +178,33 @@ class ManimDirective(Directive):
     }
     final_argument_whitespace = True
 
-    def run(self):
+    def run(self) -> list[nodes.Element]:
         # Rendering is skipped if the tag skip-manim is present,
         # or if we are making the pot-files
         should_skip = (
-            "skip-manim" in self.state.document.settings.env.app.builder.tags.tags
+            "skip-manim" in self.state.document.settings.env.app.builder.tags
             or self.state.document.settings.env.app.builder.name == "gettext"
         )
         if should_skip:
+            clsname = self.arguments[0]
             node = SkipManimNode()
             self.state.nested_parse(
                 StringList(
                     [
-                        f"Placeholder block for ``{self.arguments[0]}``.",
+                        f"Placeholder block for ``{clsname}``.",
                         "",
                         ".. code-block:: python",
                         "",
                     ]
                     + ["    " + line for line in self.content]
+                    + [
+                        "",
+                        ".. raw:: html",
+                        "",
+                        f'    <pre data-manim-binder data-manim-classname="{clsname}">',
+                    ]
+                    + ["    " + line for line in self.content]
+                    + ["    </pre>"],
                 ),
                 self.content_offset,
                 node,
@@ -206,14 +233,10 @@ class ManimDirective(Directive):
             + self.options.get("ref_functions", [])
             + self.options.get("ref_methods", [])
         )
-        if ref_content:
-            ref_block = "References: " + " ".join(ref_content)
-
-        else:
-            ref_block = ""
+        ref_block = "References: " + " ".join(ref_content) if ref_content else ""
 
         if "quality" in self.options:
-            quality = f'{self.options["quality"]}_quality'
+            quality = f"{self.options['quality']}_quality"
         else:
             quality = "example_quality"
         frame_rate = QUALITIES[quality]["frame_rate"]
@@ -224,21 +247,28 @@ class ManimDirective(Directive):
         document = state_machine.document
 
         source_file_name = Path(document.attributes["source"])
-        source_rel_name = source_file_name.relative_to(setup.confdir)
+        source_rel_name = source_file_name.relative_to(setup.confdir)  # type: ignore[attr-defined]
         source_rel_dir = source_rel_name.parents[0]
-        dest_dir = Path(setup.app.builder.outdir, source_rel_dir).absolute()
+        dest_dir = Path(setup.app.builder.outdir, source_rel_dir).absolute()  # type: ignore[attr-defined]
         if not dest_dir.exists():
             dest_dir.mkdir(parents=True, exist_ok=True)
 
-        source_block = [
+        source_block_in = [
             ".. code-block:: python",
             "",
             "    from manim import *\n",
             *("    " + line for line in self.content),
+            "",
+            ".. raw:: html",
+            "",
+            f'    <pre data-manim-binder data-manim-classname="{clsname}">',
+            *("    " + line for line in self.content),
+            "",
+            "    </pre>",
         ]
-        source_block = "\n".join(source_block)
+        source_block = "\n".join(source_block_in)
 
-        config.media_dir = (Path(setup.confdir) / "media").absolute()
+        config.media_dir = (Path(setup.confdir) / "media").absolute()  # type: ignore[attr-defined]
         config.images_dir = "{media_dir}/images"
         config.video_dir = "{media_dir}/videos/{quality}"
         output_file = f"{clsname}-{classnamedict[clsname]}"
@@ -260,7 +290,7 @@ class ManimDirective(Directive):
         if save_as_gif:
             example_config["format"] = "gif"
 
-        user_code = self.content
+        user_code = list(self.content)
         if user_code[0].startswith(">>> "):  # check whether block comes from doctest
             user_code = [
                 line[4:] for line in user_code if line.startswith((">>> ", "... "))
@@ -272,10 +302,13 @@ class ManimDirective(Directive):
             f"{clsname}().render()",
         ]
 
-        with tempconfig(example_config):
-            run_time = timeit(lambda: exec("\n".join(code), globals()), number=1)
-            video_dir = config.get_dir("video_dir")
-            images_dir = config.get_dir("images_dir")
+        try:
+            with tempconfig(example_config):
+                run_time = timeit(lambda: exec("\n".join(code), globals()), number=1)
+                video_dir = config.get_dir("video_dir")
+                images_dir = config.get_dir("images_dir")
+        except Exception as e:
+            raise RuntimeError(f"Error while rendering example {clsname}") from e
 
         _write_rendering_stats(
             clsname,
@@ -301,7 +334,7 @@ class ManimDirective(Directive):
             clsname=clsname,
             clsname_lowercase=clsname.lower(),
             hide_source=hide_source,
-            filesrc_rel=Path(filesrc).relative_to(setup.confdir).as_posix(),
+            filesrc_rel=Path(filesrc).relative_to(setup.confdir).as_posix(),  # type: ignore[attr-defined]
             no_autoplay=no_autoplay,
             output_file=output_file,
             save_last_frame=save_last_frame,
@@ -320,18 +353,18 @@ class ManimDirective(Directive):
 rendering_times_file_path = Path("../rendering_times.csv")
 
 
-def _write_rendering_stats(scene_name, run_time, file_name):
+def _write_rendering_stats(scene_name: str, run_time: float, file_name: str) -> None:
     with rendering_times_file_path.open("a") as file:
         csv.writer(file).writerow(
             [
                 re.sub(r"^(reference\/)|(manim\.)", "", file_name),
                 scene_name,
-                "%.3f" % run_time,
+                f"{run_time:.3f}",
             ],
         )
 
 
-def _log_rendering_times(*args):
+def _log_rendering_times(*args: tuple[Any]) -> None:
     if rendering_times_file_path.exists():
         with rendering_times_file_path.open() as file:
             data = list(csv.reader(file))
@@ -340,10 +373,13 @@ def _log_rendering_times(*args):
 
         print("\nRendering Summary\n-----------------\n")
 
+        # filter out empty lists caused by csv reader
+        data = [row for row in data if row]
+
         max_file_length = max(len(row[0]) for row in data)
-        for key, group in it.groupby(data, key=lambda row: row[0]):
+        for key, group_iter in it.groupby(data, key=lambda row: row[0]):
             key = key.ljust(max_file_length + 1, ".")
-            group = list(group)
+            group = list(group_iter)
             if len(group) == 1:
                 row = group[0]
                 print(f"{key}{row[2].rjust(7, '.')}s {row[1]}")
@@ -353,28 +389,45 @@ def _log_rendering_times(*args):
                 f"{key}{f'{time_sum:.3f}'.rjust(7, '.')}s  => {len(group)} EXAMPLES",
             )
             for row in group:
-                print(f"{' '*(max_file_length)} {row[2].rjust(7)}s {row[1]}")
+                print(f"{' ' * max_file_length} {row[2].rjust(7)}s {row[1]}")
         print("")
 
 
-def _delete_rendering_times(*args):
+def _delete_rendering_times(*args: tuple[Any]) -> None:
     if rendering_times_file_path.exists():
         rendering_times_file_path.unlink()
 
 
-def setup(app):
-    app.add_node(SkipManimNode, html=(visit, depart))
+def setup(app: Sphinx) -> SetupMetadata:
+    app.add_node(
+        SkipManimNode,
+        html=(visit, depart),
+        latex=(lambda a, b: None, lambda a, b: None),
+    )
 
-    setup.app = app
-    setup.config = app.config
-    setup.confdir = app.confdir
+    setup.app = app  # type: ignore[attr-defined]
+    setup.config = app.config  # type: ignore[attr-defined]
+    setup.confdir = app.confdir  # type: ignore[attr-defined]
 
     app.add_directive("manim", ManimDirective)
 
     app.connect("builder-inited", _delete_rendering_times)
     app.connect("build-finished", _log_rendering_times)
 
-    metadata = {"parallel_read_safe": False, "parallel_write_safe": True}
+    app.add_js_file("manim-binder.min.js")
+    app.add_js_file(
+        None,
+        body=textwrap.dedent(
+            f"""\
+                window.initManimBinder({{branch: "v{manim_version}"}})
+            """
+        ).strip(),
+    )
+
+    metadata: SetupMetadata = {
+        "parallel_read_safe": False,
+        "parallel_write_safe": True,
+    }
     return metadata
 
 

manim/utils/docbuild/module_parsing.py

@@ -0,0 +1,245 @@
+"""Read and parse all the Manim modules and extract documentation from them."""
+
+from __future__ import annotations
+
+import ast
+import sys
+from ast import Attribute, Name, Subscript
+from pathlib import Path
+from typing import Any
+
+from typing_extensions import TypeAlias
+
+__all__ = ["parse_module_attributes"]
+
+
+AliasInfo: TypeAlias = dict[str, str]
+"""Dictionary with a `definition` key containing the definition of
+a :class:`TypeAlias` as a string, and optionally a `doc` key containing
+the documentation for that alias, if it exists.
+"""
+
+AliasCategoryDict: TypeAlias = dict[str, AliasInfo]
+"""Dictionary which holds an `AliasInfo` for every alias name in a same
+category.
+"""
+
+ModuleLevelAliasDict: TypeAlias = dict[str, AliasCategoryDict]
+"""Dictionary containing every :class:`TypeAlias` defined in a module,
+classified by category in different `AliasCategoryDict` objects.
+"""
+
+ModuleTypeVarDict: TypeAlias = dict[str, str]
+"""Dictionary containing every :class:`TypeVar` defined in a module."""
+
+
+AliasDocsDict: TypeAlias = dict[str, ModuleLevelAliasDict]
+"""Dictionary which, for every module in Manim, contains documentation
+about their module-level attributes which are explicitly defined as
+:class:`TypeAlias`, separating them from the rest of attributes.
+"""
+
+DataDict: TypeAlias = dict[str, list[str]]
+"""Type for a dictionary which, for every module, contains a list with
+the names of all their DOCUMENTED module-level attributes (identified
+by Sphinx via the ``data`` role, hence the name) which are NOT
+explicitly defined as :class:`TypeAlias`.
+"""
+
+TypeVarDict: TypeAlias = dict[str, ModuleTypeVarDict]
+"""A dictionary mapping module names to dictionaries of :class:`TypeVar` objects."""
+
+ALIAS_DOCS_DICT: AliasDocsDict = {}
+DATA_DICT: DataDict = {}
+TYPEVAR_DICT: TypeVarDict = {}
+
+MANIM_ROOT = Path(__file__).resolve().parent.parent.parent
+
+# In the following, we will use ``type(xyz) is xyz_type`` instead of
+# isinstance checks to make sure no subclasses of the type pass the
+# check
+# ruff: noqa: E721
+
+
+def parse_module_attributes() -> tuple[AliasDocsDict, DataDict, TypeVarDict]:
+    """Read all files, generate Abstract Syntax Trees from them, and
+    extract useful information about the type aliases defined in the
+    files: the category they belong to, their definition and their
+    description, separating them from the "regular" module attributes.
+
+    Returns
+    -------
+    ALIAS_DOCS_DICT : :class:`AliasDocsDict`
+        A dictionary containing the information from all the type
+        aliases in Manim. See :class:`AliasDocsDict` for more information.
+
+    DATA_DICT : :class:`DataDict`
+        A dictionary containing the names of all DOCUMENTED
+        module-level attributes which are not a :class:`TypeAlias`.
+
+    TYPEVAR_DICT : :class:`TypeVarDict`
+        A dictionary containing the definitions of :class:`TypeVar` objects,
+        organized by modules.
+    """
+    global ALIAS_DOCS_DICT
+    global DATA_DICT
+    global TYPEVAR_DICT
+
+    if ALIAS_DOCS_DICT or DATA_DICT or TYPEVAR_DICT:
+        return ALIAS_DOCS_DICT, DATA_DICT, TYPEVAR_DICT
+
+    for module_path in MANIM_ROOT.rglob("*.py"):
+        module_name_t1 = module_path.resolve().relative_to(MANIM_ROOT)
+        module_name_t2 = list(module_name_t1.parts)
+        module_name_t2[-1] = module_name_t2[-1].removesuffix(".py")
+        module_name = ".".join(module_name_t2)
+
+        module_content = module_path.read_text(encoding="utf-8")
+
+        # For storing TypeAliases
+        module_dict: ModuleLevelAliasDict = {}
+        category_dict: AliasCategoryDict | None = None
+        alias_info: AliasInfo | None = None
+
+        # For storing TypeVars
+        module_typevars: ModuleTypeVarDict = {}
+
+        # For storing regular module attributes
+        data_list: list[str] = []
+        data_name: str | None = None
+
+        for node in ast.iter_child_nodes(ast.parse(module_content)):
+            # If we encounter a string:
+            if (
+                type(node) is ast.Expr
+                and type(node.value) is ast.Constant
+                and type(node.value.value) is str
+            ):
+                string = node.value.value.strip()
+                # It can be the start of a category
+                section_str = "[CATEGORY]"
+                if string.startswith(section_str):
+                    category_name = string[len(section_str) :].strip()
+                    module_dict[category_name] = {}
+                    category_dict = module_dict[category_name]
+                    alias_info = None
+                # or a docstring of the alias defined before
+                elif alias_info:
+                    alias_info["doc"] = string
+                # or a docstring of the module attribute defined before
+                elif data_name:
+                    data_list.append(data_name)
+                continue
+
+            # if it's defined under if TYPE_CHECKING
+            # go through the body of the if statement
+            if (
+                # NOTE: This logic does not (and cannot)
+                # check if the comparison is against a
+                # variable called TYPE_CHECKING
+                # It also says that you cannot do the following
+                # import typing as foo
+                # if foo.TYPE_CHECKING:
+                #   BAR: TypeAlias = ...
+                type(node) is ast.If
+                and (
+                    (
+                        # if TYPE_CHECKING
+                        type(node.test) is ast.Name and node.test.id == "TYPE_CHECKING"
+                    )
+                    or (
+                        # if typing.TYPE_CHECKING
+                        type(node.test) is ast.Attribute
+                        and type(node.test.value) is ast.Name
+                        and node.test.value.id == "typing"
+                        and node.test.attr == "TYPE_CHECKING"
+                    )
+                )
+            ):
+                inner_nodes: list[Any] = node.body
+            else:
+                inner_nodes = [node]
+
+            for node in inner_nodes:
+                # Check if this node is a TypeAlias (type <name> = <value>)
+                # or an AnnAssign annotated as TypeAlias (<target>: TypeAlias = <value>).
+                is_type_alias = (
+                    sys.version_info >= (3, 12) and type(node) is ast.TypeAlias
+                )
+                is_annotated_assignment_with_value = (
+                    type(node) is ast.AnnAssign
+                    and type(node.annotation) is ast.Name
+                    and node.annotation.id == "TypeAlias"
+                    and type(node.target) is ast.Name
+                    and node.value is not None
+                )
+                if is_type_alias or is_annotated_assignment_with_value:
+                    # TODO: ast.TypeAlias does not exist before Python 3.12, and that
+                    # could be the reason why MyPy does not recognize these as
+                    # attributes of node.
+                    alias_name = node.name.id if is_type_alias else node.target.id
+                    definition_node = node.value
+
+                    # If the definition is a Union, replace with vertical bar notation.
+                    # Instead of "Union[Type1, Type2]", we'll have "Type1 | Type2".
+                    if (
+                        type(definition_node) is ast.Subscript
+                        and type(definition_node.value) is ast.Name
+                        and definition_node.value.id == "Union"
+                    ):
+                        union_elements = definition_node.slice.elts  # type: ignore[attr-defined]
+                        definition = " | ".join(
+                            ast.unparse(elem) for elem in union_elements
+                        )
+                    else:
+                        definition = ast.unparse(definition_node)
+
+                    definition = definition.replace("npt.", "")
+                    if category_dict is None:
+                        module_dict[""] = {}
+                        category_dict = module_dict[""]
+                    category_dict[alias_name] = {"definition": definition}
+                    alias_info = category_dict[alias_name]
+                    continue
+
+                # Check if it is a typing.TypeVar (<target> = TypeVar(...)).
+                elif (
+                    type(node) is ast.Assign
+                    and type(node.targets[0]) is ast.Name
+                    and type(node.value) is ast.Call
+                    and type(node.value.func) is ast.Name
+                    and node.value.func.id.endswith("TypeVar")
+                ):
+                    module_typevars[node.targets[0].id] = ast.unparse(
+                        node.value
+                    ).replace("_", r"\_")
+                    continue
+
+                # If here, the node is not a TypeAlias definition
+                alias_info = None
+
+                # It could still be a module attribute definition.
+                # Does the assignment have a target of type Name? Then
+                # it could be considered a definition of a module attribute.
+                if type(node) is ast.AnnAssign:
+                    target: Name | Attribute | Subscript | ast.expr | None = node.target
+                elif type(node) is ast.Assign and len(node.targets) == 1:
+                    target = node.targets[0]
+                else:
+                    target = None
+
+                if type(target) is ast.Name and not (
+                    type(node) is ast.Assign and target.id not in module_typevars
+                ):
+                    data_name = target.id
+                else:
+                    data_name = None
+
+        if len(module_dict) > 0:
+            ALIAS_DOCS_DICT[module_name] = module_dict
+        if len(data_list) > 0:
+            DATA_DICT[module_name] = data_list
+        if module_typevars:
+            TYPEVAR_DICT[module_name] = module_typevars
+
+    return ALIAS_DOCS_DICT, DATA_DICT, TYPEVAR_DICT

manim/utils/exceptions.py

@@ -1,5 +1,11 @@
 from __future__ import annotations
 
+__all__ = [
+    "EndSceneEarlyException",
+    "RerunSceneException",
+    "MultiAnimationOverrideException",
+]
+
 
 class EndSceneEarlyException(Exception):
     pass

manim/utils/family.py

@@ -1,17 +1,19 @@
 from __future__ import annotations
 
 import itertools as it
-from typing import Iterable
+from collections.abc import Iterable
 
 from ..mobject.mobject import Mobject
 from ..utils.iterables import remove_list_redundancies
 
+__all__ = ["extract_mobject_family_members"]
+
 
 def extract_mobject_family_members(
     mobjects: Iterable[Mobject],
-    use_z_index=False,
+    use_z_index: bool = False,
     only_those_with_points: bool = False,
-):
+) -> list[Mobject]:
     """Returns a list of the types of mobjects and their family members present.
     A "family" in this context refers to a mobject, its submobjects, and their
     submobjects, recursively.

manim/utils/family_ops.py

@@ -2,15 +2,26 @@ from __future__ import annotations
 
 import itertools as it
 
+from manim.mobject.mobject import Mobject
 
-def extract_mobject_family_members(mobject_list, only_those_with_points=False):
+__all__ = [
+    "extract_mobject_family_members",
+    "restructure_list_to_exclude_certain_family_members",
+]
+
+
+def extract_mobject_family_members(
+    mobject_list: list[Mobject], only_those_with_points: bool = False
+) -> list[Mobject]:
     result = list(it.chain(*(mob.get_family() for mob in mobject_list)))
     if only_those_with_points:
         result = [mob for mob in result if mob.has_points()]
     return result
 
 
-def restructure_list_to_exclude_certain_family_members(mobject_list, to_remove):
+def restructure_list_to_exclude_certain_family_members(
+    mobject_list: list[Mobject], to_remove: list[Mobject]
+) -> list[Mobject]:
     """
     Removes anything in to_remove from mobject_list, but in the event that one of
     the items to be removed is a member of the family of an item in mobject_list,
@@ -20,10 +31,12 @@ def restructure_list_to_exclude_certain_family_members(mobject_list, to_remove):
     but one of its submobjects is removed, e.g. scene.remove(m1), it's useful
     for the list of mobject_list to be edited to contain other submobjects, but not m1.
     """
-    new_list = []
+    new_list: list[Mobject] = []
     to_remove = extract_mobject_family_members(to_remove)
 
-    def add_safe_mobjects_from_list(list_to_examine, set_to_remove):
+    def add_safe_mobjects_from_list(
+        list_to_examine: list[Mobject], set_to_remove: set[Mobject]
+    ) -> None:
         for mob in list_to_examine:
             if mob in set_to_remove:
                 continue