manim 0.18.1__py3-none-any.whl → 0.19.0__py3-none-any.whl

manim/utils/docbuild/autoaliasattr_directive.py

@@ -12,17 +12,16 @@ from manim.utils.docbuild.module_parsing import parse_module_attributes
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
-    from typing_extensions import TypeAlias
 
 __all__ = ["AliasAttrDocumenter"]
 
 
-ALIAS_DOCS_DICT, DATA_DICT = parse_module_attributes()
+ALIAS_DOCS_DICT, DATA_DICT, TYPEVAR_DICT = parse_module_attributes()
 ALIAS_LIST = [
     alias_name
     for module_dict in ALIAS_DOCS_DICT.values()
     for category_dict in module_dict.values()
-    for alias_name in category_dict.keys()
+    for alias_name in category_dict
 ]
 
 
@@ -45,11 +44,12 @@ def smart_replace(base: str, alias: str, substitution: str) -> str:
     str
         The new string after the alias substitution.
     """
-
     occurrences = []
     len_alias = len(alias)
     len_base = len(base)
-    condition = lambda char: (not char.isalnum()) and char != "_"
+
+    def condition(char: str) -> bool:
+        return not char.isalnum() and char != "_"
 
     start = 0
     i = 0
@@ -99,10 +99,11 @@ class AliasAttrDocumenter(Directive):
 
     def run(self) -> list[nodes.Element]:
         module_name = self.arguments[0]
-        # Slice module_name[6:] to remove the "manim." prefix which is
         # not present in the keys of the DICTs
-        module_alias_dict = ALIAS_DOCS_DICT.get(module_name[6:], None)
-        module_attrs_list = DATA_DICT.get(module_name[6:], None)
+        module_name = module_name.removeprefix("manim.")
+        module_alias_dict = ALIAS_DOCS_DICT.get(module_name, None)
+        module_attrs_list = DATA_DICT.get(module_name, None)
+        module_typevars = TYPEVAR_DICT.get(module_name, None)
 
         content = nodes.container()
 
@@ -160,6 +161,11 @@ class AliasAttrDocumenter(Directive):
                         for A in ALIAS_LIST:
                             alias_doc = alias_doc.replace(f"`{A}`", f":class:`~.{A}`")
 
+                        # also hyperlink the TypeVars from that module
+                        if module_typevars is not None:
+                            for T in module_typevars:
+                                alias_doc = alias_doc.replace(f"`{T}`", f":class:`{T}`")
+
                         # Add all the lines with 4 spaces behind, to consider all the
                         # documentation as a paragraph INSIDE the `.. class::` block
                         doc_lines = alias_doc.split("\n")
@@ -171,6 +177,37 @@ class AliasAttrDocumenter(Directive):
                     self.state.nested_parse(unparsed, 0, alias_container)
                     category_alias_container += alias_container
 
+        # then add the module TypeVars section
+        if module_typevars is not None:
+            module_typevars_section = nodes.section(ids=[f"{module_name}.typevars"])
+            content += module_typevars_section
+
+            # Use a rubric (title-like), just like in `module.rst`
+            module_typevars_section += nodes.rubric(text="TypeVar's")
+
+            # name: str
+            # definition: TypeVarDict = dict[str, str]
+            for name, definition in module_typevars.items():
+                # Using the `.. class::` directive is CRUCIAL, since
+                # function/method parameters are always annotated via
+                # classes - therefore Sphinx expects a class
+                unparsed = ViewList(
+                    [
+                        f".. class:: {name}",
+                        "",
+                        "    .. parsed-literal::",
+                        "",
+                        f"        {definition}",
+                        "",
+                    ]
+                )
+
+                # Parse the reST text into a fresh container
+                # https://www.sphinx-doc.org/en/master/extdev/markupapi.html#parsing-directive-content-as-rest
+                typevar_container = nodes.container()
+                self.state.nested_parse(unparsed, 0, typevar_container)
+                module_typevars_section += typevar_container
+
         # Then, add the traditional "Module Attributes" section
         if module_attrs_list is not None:
             module_attrs_section = nodes.section(ids=[f"{module_name}.data"])

manim/utils/docbuild/autocolor_directive.py

@@ -26,7 +26,9 @@ class ManimColorModuleDocumenter(Directive):
     has_content = True
 
     def add_directive_header(self, sig: str) -> None:
-        super().add_directive_header(sig)
+        # TODO: The Directive class has no method named
+        # add_directive_header.
+        super().add_directive_header(sig)  # type: ignore[misc]
 
     def run(self) -> list[nodes.Element]:
         module_name = self.arguments[0]
@@ -37,8 +39,8 @@ class ManimColorModuleDocumenter(Directive):
         except ImportError:
             return [
                 nodes.error(
-                    None,
-                    nodes.paragraph(text="Failed to import module '%s'" % module_name),
+                    None,  # type: ignore[arg-type]
+                    nodes.paragraph(text=f"Failed to import module '{module_name}'"),
                 )
             ]
 
@@ -53,13 +55,13 @@ class ManimColorModuleDocumenter(Directive):
 
         # Create header rows for the table
         thead = nodes.thead()
-        row = nodes.row()
+        header_row = nodes.row()
         for _ in range(num_color_cols):
-            col1 = nodes.paragraph(text="Color Name")
-            col2 = nodes.paragraph(text="RGB Hex Code")
-            row += nodes.entry("", col1)
-            row += nodes.entry("", col2)
-        thead += row
+            header_col1 = nodes.paragraph(text="Color Name")
+            header_col2 = nodes.paragraph(text="RGB Hex Code")
+            header_row += nodes.entry("", header_col1)
+            header_row += nodes.entry("", header_col2)
+        thead += header_row
         tgroup += thead
 
         color_elements = []
@@ -69,10 +71,7 @@ class ManimColorModuleDocumenter(Directive):
                 luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b
 
                 # Choose the font color based on the background luminance
-                if luminance > 0.5:
-                    font_color = "black"
-                else:
-                    font_color = "white"
+                font_color = "black" if luminance > 0.5 else "white"
 
                 color_elements.append((member_name, member_obj.to_hex(), font_color))
 

manim/utils/docbuild/manim_directive.py

@@ -82,18 +82,17 @@ 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
+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
@@ -102,12 +101,18 @@ from manim import __version__ as manim_version
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
 
+
 __all__ = ["ManimDirective"]
 
 
 classnamedict: dict[str, int] = {}
 
 
+class SetupMetadata(TypedDict):
+    parallel_read_safe: bool
+    parallel_write_safe: bool
+
+
 class SkipManimNode(nodes.Admonition, nodes.Element):
     """Auxiliary node class that is used when the ``skip-manim`` tag is present
     or ``.pot`` files are being built.
@@ -119,13 +124,15 @@ class SkipManimNode(nodes.Admonition, nodes.Element):
 
 
 def visit(self: SkipManimNode, node: nodes.Element, name: str = "") -> None:
-    self.visit_admonition(node, name)
+    # 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: SkipManimNode, node: nodes.Element) -> None:
-    self.depart_admonition(node)
+    # 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]:
@@ -175,7 +182,7 @@ class ManimDirective(Directive):
         # 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:
@@ -226,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"]
@@ -244,13 +247,13 @@ 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",
@@ -263,13 +266,13 @@ class ManimDirective(Directive):
             "",
             "    </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,assignment]
         config.images_dir = "{media_dir}/images"
         config.video_dir = "{media_dir}/videos/{quality}"
         output_file = f"{clsname}-{classnamedict[clsname]}"
-        config.assets_dir = Path("_static")
+        config.assets_dir = Path("_static")  # type: ignore[assignment]
         config.progress_bar = "none"
         config.verbosity = "WARNING"
 
@@ -287,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((">>> ", "... "))
@@ -331,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,
@@ -350,13 +353,13 @@ class ManimDirective(Directive):
 rendering_times_file_path = Path("../rendering_times.csv")
 
 
-def _write_rendering_stats(scene_name: str, run_time: str, file_name: str) -> None:
+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}",
             ],
         )
 
@@ -374,9 +377,9 @@ def _log_rendering_times(*args: tuple[Any]) -> None:
         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]}")
@@ -395,12 +398,12 @@ def _delete_rendering_times(*args: tuple[Any]) -> None:
         rendering_times_file_path.unlink()
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> SetupMetadata:
     app.add_node(SkipManimNode, html=(visit, depart))
 
-    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)
 
@@ -417,7 +420,10 @@ def setup(app: Sphinx) -> dict[str, Any]:
         ).strip(),
     )
 
-    metadata = {"parallel_read_safe": False, "parallel_write_safe": True}
+    metadata: SetupMetadata = {
+        "parallel_read_safe": False,
+        "parallel_write_safe": True,
+    }
     return metadata
 
 

manim/utils/docbuild/module_parsing.py

@@ -3,7 +3,10 @@
 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
 
@@ -26,6 +29,10 @@ ModuleLevelAliasDict: TypeAlias = dict[str, AliasCategoryDict]
 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
@@ -39,17 +46,22 @@ 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]:
+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
@@ -57,25 +69,30 @@ def parse_module_attributes() -> tuple[AliasDocsDict, DataDict]:
 
     Returns
     -------
-    ALIAS_DOCS_DICT : `AliasDocsDict`
+    ALIAS_DOCS_DICT : :class:`AliasDocsDict`
         A dictionary containing the information from all the type
-        aliases in Manim. See `AliasDocsDict` for more information.
+        aliases in Manim. See :class:`AliasDocsDict` for more information.
 
-    DATA_DICT : `DataDict`
+    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:
-        return ALIAS_DOCS_DICT, DATA_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 = module_path.resolve().relative_to(MANIM_ROOT)
-        module_name = list(module_name.parts)
-        module_name[-1] = module_name[-1].removesuffix(".py")
-        module_name = ".".join(module_name)
+        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")
 
@@ -84,6 +101,9 @@ def parse_module_attributes() -> tuple[AliasDocsDict, DataDict]:
         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
@@ -125,8 +145,7 @@ def parse_module_attributes() -> tuple[AliasDocsDict, DataDict]:
                 and (
                     (
                         # if TYPE_CHECKING
-                        type(node.test) is ast.Name
-                        and node.test.id == "TYPE_CHECKING"
+                        type(node.test) is ast.Name and node.test.id == "TYPE_CHECKING"
                     )
                     or (
                         # if typing.TYPE_CHECKING
@@ -137,32 +156,43 @@ def parse_module_attributes() -> tuple[AliasDocsDict, DataDict]:
                     )
                 )
             ):
-                inner_nodes = node.body
+                inner_nodes: list[Any] = node.body
             else:
                 inner_nodes = [node]
 
             for node in inner_nodes:
-                # If we encounter an assignment annotated as "TypeAlias":
-                if (
+                # 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
-                ):
-                    alias_name = node.target.id
-                    def_node = node.value
-                    # If it's an Union, replace it with vertical bar notation
+                )
+                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(def_node) is ast.Subscript
-                        and type(def_node.value) is ast.Name
-                        and def_node.value.id == "Union"
+                        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 def_node.slice.elts
+                            ast.unparse(elem) for elem in union_elements
                         )
                     else:
-                        definition = ast.unparse(def_node)
+                        definition = ast.unparse(definition_node)
 
                     definition = definition.replace("npt.", "")
                     if category_dict is None:
@@ -172,6 +202,19 @@ def parse_module_attributes() -> tuple[AliasDocsDict, DataDict]:
                     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
 
@@ -179,13 +222,15 @@ def parse_module_attributes() -> tuple[AliasDocsDict, DataDict]:
                 # 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 = node.target
+                    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:
+                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
@@ -194,5 +239,7 @@ def parse_module_attributes() -> tuple[AliasDocsDict, DataDict]:
             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
+    return ALIAS_DOCS_DICT, DATA_DICT, TYPEVAR_DICT

manim/utils/family.py

@@ -1,7 +1,7 @@
 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
@@ -11,9 +11,9 @@ __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,20 +2,26 @@ from __future__ import annotations
 
 import itertools as it
 
+from manim.mobject.mobject import Mobject
+
 __all__ = [
     "extract_mobject_family_members",
     "restructure_list_to_exclude_certain_family_members",
 ]
 
 
-def extract_mobject_family_members(mobject_list, only_those_with_points=False):
+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,
@@ -25,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