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

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  # type: ignore[attr-defined]
+                    definition_node = node.value  # type: ignore[attr-defined]
+
+                    # 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

manim/utils/file_ops.py

@@ -28,6 +28,8 @@ from shutil import copyfile
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
+    from manim.typing import StrPath
+
     from ..scene.scene_file_writer import SceneFileWriter
 
 from manim import __version__, config, logger
@@ -45,7 +47,8 @@ def is_mp4_format() -> bool:
         ``True`` if format is set as mp4
 
     """
-    return config["format"] == "mp4"
+    val: bool = config["format"] == "mp4"
+    return val
 
 
 def is_gif_format() -> bool:
@@ -58,7 +61,8 @@ def is_gif_format() -> bool:
         ``True`` if format is set as gif
 
     """
-    return config["format"] == "gif"
+    val: bool = config["format"] == "gif"
+    return val
 
 
 def is_webm_format() -> bool:
@@ -71,7 +75,8 @@ def is_webm_format() -> bool:
         ``True`` if format is set as webm
 
     """
-    return config["format"] == "webm"
+    val: bool = config["format"] == "webm"
+    return val
 
 
 def is_mov_format() -> bool:
@@ -84,7 +89,8 @@ def is_mov_format() -> bool:
         ``True`` if format is set as mov
 
     """
-    return config["format"] == "mov"
+    val: bool = config["format"] == "mov"
+    return val
 
 
 def is_png_format() -> bool:
@@ -97,7 +103,8 @@ def is_png_format() -> bool:
         ``True`` if format is set as png
 
     """
-    return config["format"] == "png"
+    val: bool = config["format"] == "png"
+    return val
 
 
 def write_to_movie() -> bool:
@@ -124,7 +131,7 @@ def write_to_movie() -> bool:
 
 def ensure_executable(path_to_exe: Path) -> bool:
     if path_to_exe.parent == Path("."):
-        executable = shutil.which(path_to_exe.stem)
+        executable: StrPath | None = shutil.which(path_to_exe.stem)
         if executable is None:
             return False
     else:
@@ -159,7 +166,7 @@ def guarantee_empty_existence(path: Path) -> Path:
 
 
 def seek_full_path_from_defaults(
-    file_name: str, default_dir: Path, extensions: list[str]
+    file_name: StrPath, default_dir: Path, extensions: list[str]
 ) -> Path:
     possible_paths = [Path(file_name).expanduser()]
     possible_paths += [
@@ -186,10 +193,12 @@ def modify_atime(file_path: str) -> None:
     os.utime(file_path, times=(time.time(), Path(file_path).stat().st_mtime))
 
 
-def open_file(file_path, in_browser=False):
+def open_file(file_path: Path, in_browser: bool = False) -> None:
     current_os = platform.system()
     if current_os == "Windows":
-        os.startfile(file_path if not in_browser else file_path.parent)
+        # The method os.startfile is only available in Windows,
+        # ignoring type error caused by this.
+        os.startfile(file_path if not in_browser else file_path.parent)  # type: ignore[attr-defined]
     else:
         if current_os == "Linux":
             commands = ["xdg-open"]
@@ -198,14 +207,15 @@ def open_file(file_path, in_browser=False):
             commands = ["cygstart"]
             file_path = file_path if not in_browser else file_path.parent
         elif current_os == "Darwin":
-            if is_gif_format():
-                commands = ["ffplay", "-loglevel", config["ffmpeg_loglevel"].lower()]
-            else:
-                commands = ["open"] if not in_browser else ["open", "-R"]
+            commands = ["open"] if not in_browser else ["open", "-R"]
         else:
             raise OSError("Unable to identify your operating system...")
-        commands.append(file_path)
-        sp.Popen(commands)
+
+        # check after so that file path is set correctly
+        if config.preview_command:
+            commands = [config.preview_command]
+        commands.append(str(file_path))
+        sp.run(commands)
 
 
 def open_media_file(file_writer: SceneFileWriter) -> None:
@@ -248,7 +258,7 @@ def get_template_path() -> Path:
     return Path.resolve(Path(__file__).parent.parent / "templates")
 
 
-def add_import_statement(file: Path):
+def add_import_statement(file: Path) -> None:
     """Prepends an import statement in a file
 
     Parameters

manim/utils/hashing.py

@@ -14,15 +14,17 @@ from typing import Any
 
 import numpy as np
 
-from manim.animation.animation import Animation
-from manim.camera.camera import Camera
-from manim.mobject.mobject import Mobject
-
-from .. import config, logger
+from manim._config import config, logger
 
 if typing.TYPE_CHECKING:
+    from manim.animation.animation import Animation
+    from manim.camera.camera import Camera
+    from manim.mobject.mobject import Mobject
+    from manim.opengl.opengl_renderer import OpenGLCamera
     from manim.scene.scene import Scene
 
+__all__ = ["KEYS_TO_FILTER_OUT", "get_hash_from_play_call", "get_json"]
+
 # Sometimes there are elements that are not suitable for hashing (too long or
 # run-dependent).  This is used to filter them out.
 KEYS_TO_FILTER_OUT = {
@@ -221,7 +223,7 @@ class _CustomEncoder(json.JSONEncoder):
             # We return the repr and not a list to avoid the JsonEncoder to iterate over it.
             return repr(obj)
         elif hasattr(obj, "__dict__"):
-            temp = getattr(obj, "__dict__")
+            temp = obj.__dict__
             # MappingProxy is scene-caching nightmare. It contains all of the object methods and attributes. We skip it as the mechanism will at some point process the object, but instantiated.
             # Indeed, there is certainly no case where scene-caching will receive only a non instancied object, as this is never used in the library or encouraged to be used user-side.
             if isinstance(temp, MappingProxyType):
@@ -322,7 +324,7 @@ def get_json(obj: dict):
 
 def get_hash_from_play_call(
     scene_object: Scene,
-    camera_object: Camera,
+    camera_object: Camera | OpenGLCamera,
     animations_list: typing.Iterable[Animation],
     current_mobjects_list: typing.Iterable[Mobject],
 ) -> str:

manim/utils/images.py

@@ -9,16 +9,22 @@ __all__ = [
     "change_to_rgba_array",
 ]
 
-from pathlib import Path
+from pathlib import Path, PurePath
+from typing import TYPE_CHECKING
 
 import numpy as np
 from PIL import Image
 
+from manim.typing import RGBPixelArray
+
 from .. import config
 from ..utils.file_ops import seek_full_path_from_defaults
 
+if TYPE_CHECKING:
+    pass
+
 
-def get_full_raster_image_path(image_file_name: str) -> Path:
+def get_full_raster_image_path(image_file_name: str | PurePath) -> Path:
     return seek_full_path_from_defaults(
         image_file_name,
         default_dir=config.get_dir("assets_dir"),
@@ -26,7 +32,7 @@ def get_full_raster_image_path(image_file_name: str) -> Path:
     )
 
 
-def get_full_vector_image_path(image_file_name: str) -> Path:
+def get_full_vector_image_path(image_file_name: str | PurePath) -> Path:
     return seek_full_path_from_defaults(
         image_file_name,
         default_dir=config.get_dir("assets_dir"),
@@ -49,7 +55,7 @@ def invert_image(image: np.array) -> Image:
     return Image.fromarray(arr)
 
 
-def change_to_rgba_array(image, dtype="uint8"):
+def change_to_rgba_array(image: RGBPixelArray, dtype: str = "uint8") -> RGBPixelArray:
     """Converts an RGB array into RGBA with the alpha value opacity maxed."""
     pa = image
     if len(pa.shape) == 2:

manim/utils/ipython_magic.py

@@ -3,18 +3,19 @@
 from __future__ import annotations
 
 import mimetypes
-import os
 import shutil
 from datetime import datetime
 from pathlib import Path
 from typing import Any
 
-from manim import Group, config, logger, tempconfig
+from manim import config, logger, tempconfig
 from manim.__main__ import main
 from manim.renderer.shader import shader_program_cache
 
 from ..constants import RendererType
 
+__all__ = ["ManimMagic"]
+
 try:
     from IPython import get_ipython
     from IPython.core.interactiveshell import InteractiveShell
@@ -33,15 +34,15 @@ else:
     class ManimMagic(Magics):
         def __init__(self, shell: InteractiveShell) -> None:
             super().__init__(shell)
-            self.rendered_files = {}
+            self.rendered_files: dict[Path, Path] = {}
 
         @needs_local_scope
         @line_cell_magic
         def manim(
             self,
             line: str,
-            cell: str = None,
-            local_ns: dict[str, Any] = None,
+            cell: str | None = None,
+            local_ns: dict[str, Any] | None = None,
         ) -> None:
             r"""Render Manim scenes contained in IPython cells.
             Works as a line or cell magic.
@@ -126,8 +127,9 @@ else:
 
             modified_args = self.add_additional_args(args)
             args = main(modified_args, standalone_mode=False, prog_name="manim")
+            assert isinstance(local_ns, dict)
             with tempconfig(local_ns.get("config", {})):
-                config.digest_args(args)
+                config.digest_args(args)  # type: ignore[arg-type]
 
                 renderer = None
                 if config.renderer == RendererType.OPENGL:
@@ -166,8 +168,9 @@ else:
                 shutil.copy(local_path, tmpfile)
 
                 file_type = mimetypes.guess_type(config["output_file"])[0]
+                assert isinstance(file_type, str)
                 embed = config["media_embed"]
-                if embed is None:
+                if not embed:
                     # videos need to be embedded when running in google colab.
                     # do this automatically in case config.media_embed has not been
                     # set explicitly.
@@ -193,4 +196,7 @@ else:
 
 
 def _generate_file_name() -> str:
-    return config["scene_names"][0] + "@" + datetime.now().strftime("%Y-%m-%d@%H-%M-%S")
+    val: str = (
+        config["scene_names"][0] + "@" + datetime.now().strftime("%Y-%m-%d@%H-%M-%S")
+    )
+    return val