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

manim/utils/docbuild/module_parsing.py

@@ -0,0 +1,198 @@
+"""Read and parse all the Manim modules and extract documentation from them."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+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.
+"""
+
+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`.
+"""
+
+ALIAS_DOCS_DICT: AliasDocsDict = {}
+DATA_DICT: DataDict = {}
+
+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
+
+
+def parse_module_attributes() -> tuple[AliasDocsDict, DataDict]:
+    """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 : `AliasDocsDict`
+        A dictionary containing the information from all the type
+        aliases in Manim. See `AliasDocsDict` for more information.
+
+    DATA_DICT : `DataDict`
+        A dictionary containing the names of all DOCUMENTED
+        module-level attributes which are not a :class:`TypeAlias`.
+    """
+    global ALIAS_DOCS_DICT
+    global DATA_DICT
+
+    if ALIAS_DOCS_DICT or DATA_DICT:
+        return ALIAS_DOCS_DICT, DATA_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_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 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 = node.body
+            else:
+                inner_nodes = [node]
+
+            for node in inner_nodes:
+                # If we encounter an assignment annotated as "TypeAlias":
+                if (
+                    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 (
+                        type(def_node) is ast.Subscript
+                        and type(def_node.value) is ast.Name
+                        and def_node.value.id == "Union"
+                    ):
+                        definition = " | ".join(
+                            ast.unparse(elem) for elem in def_node.slice.elts
+                        )
+                    else:
+                        definition = ast.unparse(def_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
+
+                # 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 = 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:
+                    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
+
+    return ALIAS_DOCS_DICT, DATA_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

@@ -6,6 +6,8 @@ from typing 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],

manim/utils/family_ops.py

@@ -2,6 +2,11 @@ from __future__ import annotations
 
 import itertools as it
 
+__all__ = [
+    "extract_mobject_family_members",
+    "restructure_list_to_exclude_certain_family_members",
+]
+
 
 def extract_mobject_family_members(mobject_list, only_those_with_points=False):
     result = list(it.chain(*(mob.get_family() for mob in mobject_list)))

manim/utils/file_ops.py

@@ -32,7 +32,7 @@ if TYPE_CHECKING:
 
 from manim import __version__, config, logger
 
-from .. import console
+from .. import config, console
 
 
 def is_mp4_format() -> bool:
@@ -204,8 +204,12 @@ def open_file(file_path, in_browser=False):
                 commands = ["open"] if not in_browser else ["open", "-R"]
         else:
             raise OSError("Unable to identify your operating system...")
+
+        # check after so that file path is set correctly
+        if config.preview_command:
+            commands = [config.preview_command]
         commands.append(file_path)
-        sp.Popen(commands)
+        sp.run(commands)
 
 
 def open_media_file(file_writer: SceneFileWriter) -> None:

manim/utils/hashing.py

@@ -23,6 +23,8 @@ from .. import config, logger
 if typing.TYPE_CHECKING:
     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 = {

manim/utils/ipython_magic.py

@@ -15,6 +15,8 @@ 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

manim/utils/module_ops.py

@@ -12,6 +12,8 @@ from pathlib import Path
 from .. import config, console, constants, logger
 from ..scene.scene_file_writer import SceneFileWriter
 
+__all__ = ["scene_classes_from_file"]
+
 
 def get_module(file_name: Path):
     if str(file_name) == "-":

manim/utils/opengl.py

@@ -7,6 +7,20 @@ from .. import config
 
 depth = 20
 
+__all__ = [
+    "matrix_to_shader_input",
+    "orthographic_projection_matrix",
+    "perspective_projection_matrix",
+    "translation_matrix",
+    "x_rotation_matrix",
+    "y_rotation_matrix",
+    "z_rotation_matrix",
+    "rotate_in_place_matrix",
+    "rotation_matrix",
+    "scale_matrix",
+    "view_matrix",
+]
+
 
 def matrix_to_shader_input(matrix):
     return tuple(matrix.T.ravel())

manim/utils/parameter_parsing.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from types import GeneratorType
+from typing import Iterable, TypeVar
+
+T = TypeVar("T")
+
+
+def flatten_iterable_parameters(
+    args: Iterable[T | Iterable[T] | GeneratorType],
+) -> list[T]:
+    """Flattens an iterable of parameters into a list of parameters.
+
+    Parameters
+    ----------
+    args
+        The iterable of parameters to flatten.
+        [(generator), [], (), ...]
+
+    Returns
+    -------
+    :class:`list`
+        The flattened list of parameters.
+    """
+    flattened_parameters = []
+    for arg in args:
+        if isinstance(arg, (Iterable, GeneratorType)):
+            flattened_parameters.extend(arg)
+        else:
+            flattened_parameters.append(arg)
+    return flattened_parameters

manim/utils/paths.py

@@ -10,28 +10,22 @@ __all__ = [
 ]
 
 
-from typing import Callable
+from typing import TYPE_CHECKING
 
 import numpy as np
 
 from ..constants import OUT
 from ..utils.bezier import interpolate
-from ..utils.deprecation import deprecated_params
 from ..utils.space_ops import rotation_matrix
 
-STRAIGHT_PATH_THRESHOLD = 0.01
+if TYPE_CHECKING:
+    from manim.typing import PathFuncType, Vector3D
+
 
-PATH_FUNC_TYPE = Callable[[np.ndarray, np.ndarray, float], np.ndarray]
+STRAIGHT_PATH_THRESHOLD = 0.01
 
 
-# Remove `*args` and the `if` inside the functions when removing deprecation
-@deprecated_params(
-    params="start_points, end_points, alpha",
-    since="v0.14",
-    until="v0.15",
-    message="Straight path is now returning interpolating function to make it consistent with other path functions. Use straight_path()(a,b,c) instead of straight_path(a,b,c).",
-)
-def straight_path(*args) -> PATH_FUNC_TYPE:
+def straight_path():
     """Simplest path function. Each point in a set goes in a straight path toward its destination.
 
     Examples
@@ -74,14 +68,12 @@ def straight_path(*args) -> PATH_FUNC_TYPE:
                 self.wait()
 
     """
-    if len(args) > 0:
-        return interpolate(*args)
     return interpolate
 
 
 def path_along_circles(
-    arc_angle: float, circles_centers: np.ndarray, axis: np.ndarray = OUT
-) -> PATH_FUNC_TYPE:
+    arc_angle: float, circles_centers: np.ndarray, axis: Vector3D = OUT
+) -> PathFuncType:
     """This function transforms each point by moving it roughly along a circle, each with its own specified center.
 
     The path may be seen as each point smoothly changing its orbit from its starting position to its destination.
@@ -158,7 +150,7 @@ def path_along_circles(
     return path
 
 
-def path_along_arc(arc_angle: float, axis: np.ndarray = OUT) -> PATH_FUNC_TYPE:
+def path_along_arc(arc_angle: float, axis: Vector3D = OUT) -> PathFuncType:
     """This function transforms each point by moving it along a circular arc.
 
     Parameters
@@ -225,7 +217,7 @@ def path_along_arc(arc_angle: float, axis: np.ndarray = OUT) -> PATH_FUNC_TYPE:
     return path
 
 
-def clockwise_path() -> PATH_FUNC_TYPE:
+def clockwise_path() -> PathFuncType:
     """This function transforms each point by moving clockwise around a half circle.
 
     Examples
@@ -271,7 +263,7 @@ def clockwise_path() -> PATH_FUNC_TYPE:
     return path_along_arc(-np.pi)
 
 
-def counterclockwise_path() -> PATH_FUNC_TYPE:
+def counterclockwise_path() -> PathFuncType:
     """This function transforms each point by moving counterclockwise around a half circle.
 
     Examples
@@ -317,7 +309,7 @@ def counterclockwise_path() -> PATH_FUNC_TYPE:
     return path_along_arc(np.pi)
 
 
-def spiral_path(angle: float, axis: np.ndarray = OUT) -> PATH_FUNC_TYPE:
+def spiral_path(angle: float, axis: Vector3D = OUT) -> PathFuncType:
     """This function transforms each point by moving along a spiral to its destination.
 
     Parameters

manim/utils/rate_functions.py

@@ -83,7 +83,6 @@ There are primarily 3 kinds of standard easing functions:
             self.wait()
 """
 
-
 from __future__ import annotations
 
 __all__ = [
@@ -179,13 +178,12 @@ def smoothererstep(t: float) -> float:
     The 1st, 2nd and 3rd derivatives (speed, acceleration and jerk) are zero at the endpoints.
     https://en.wikipedia.org/wiki/Smoothstep
     """
-    return (
-        0
-        if t <= 0
-        else 35 * t**4 - 84 * t**5 + 70 * t**6 - 20 * t**7
-        if t < 1
-        else 1
-    )
+    alpha = 0
+    if 0 < t < 1:
+        alpha = 35 * t**4 - 84 * t**5 + 70 * t**6 - 20 * t**7
+    elif t >= 1:
+        alpha = 1
+    return alpha
 
 
 @unit_interval

manim/utils/space_ops.py

@@ -2,7 +2,26 @@
 
 from __future__ import annotations
 
-from manim.typing import Point3D_Array, Vector
+import itertools as it
+from typing import TYPE_CHECKING, Sequence
+
+import numpy as np
+from mapbox_earcut import triangulate_float32 as earcut
+from scipy.spatial.transform import Rotation
+
+from manim.constants import DOWN, OUT, PI, RIGHT, TAU, UP, RendererType
+from manim.utils.iterables import adjacent_pairs
+
+if TYPE_CHECKING:
+    import numpy.typing as npt
+
+    from manim.typing import (
+        ManimFloat,
+        Point3D_Array,
+        Vector2D,
+        Vector2D_Array,
+        Vector3D,
+    )
 
 __all__ = [
     "quaternion_mult",
@@ -38,21 +57,20 @@ __all__ = [
 ]
 
 
-import itertools as it
-from typing import Sequence
-
-import numpy as np
-from mapbox_earcut import triangulate_float32 as earcut
-from scipy.spatial.transform import Rotation
-
-from ..constants import DOWN, OUT, PI, RIGHT, TAU, UP, RendererType
-from ..utils.iterables import adjacent_pairs
-
-
 def norm_squared(v: float) -> float:
     return np.dot(v, v)
 
 
+def cross(v1: Vector3D, v2: Vector3D) -> Vector3D:
+    return np.array(
+        [
+            v1[1] * v2[2] - v1[2] * v2[1],
+            v1[2] * v2[0] - v1[0] * v2[2],
+            v1[0] * v2[1] - v1[1] * v2[0],
+        ]
+    )
+
+
 # Quaternions
 # TODO, implement quaternion type
 
@@ -104,7 +122,7 @@ def quaternion_from_angle_axis(
 
     Returns
     -------
-    List[float]
+    list[float]
         Gives back a quaternion from the angle and axis
     """
     if not axis_normalized:
@@ -273,12 +291,12 @@ def z_to_vector(vector: np.ndarray) -> np.ndarray:
     (normalized) vector provided as an argument
     """
     axis_z = normalize(vector)
-    axis_y = normalize(np.cross(axis_z, RIGHT))
-    axis_x = np.cross(axis_y, axis_z)
+    axis_y = normalize(cross(axis_z, RIGHT))
+    axis_x = cross(axis_y, axis_z)
     if np.linalg.norm(axis_y) == 0:
         # the vector passed just so happened to be in the x direction.
-        axis_x = normalize(np.cross(UP, axis_z))
-        axis_y = -np.cross(axis_x, axis_z)
+        axis_x = normalize(cross(UP, axis_z))
+        axis_y = -cross(axis_x, axis_z)
 
     return np.array([axis_x, axis_y, axis_z]).T
 
@@ -359,7 +377,7 @@ def normalize_along_axis(array: np.ndarray, axis: np.ndarray) -> np.ndarray:
     return array
 
 
-def get_unit_normal(v1: np.ndarray, v2: np.ndarray, tol: float = 1e-6) -> np.ndarray:
+def get_unit_normal(v1: Vector3D, v2: Vector3D, tol: float = 1e-6) -> Vector3D:
     """Gets the unit normal of the vectors.
 
     Parameters
@@ -376,16 +394,37 @@ def get_unit_normal(v1: np.ndarray, v2: np.ndarray, tol: float = 1e-6) -> np.nda
     np.ndarray
         The normal of the two vectors.
     """
-    v1, v2 = (normalize(i) for i in (v1, v2))
-    cp = np.cross(v1, v2)
-    cp_norm = np.linalg.norm(cp)
-    if cp_norm < tol:
-        # Vectors align, so find a normal to them in the plane shared with the z-axis
-        cp = np.cross(np.cross(v1, OUT), v1)
-        cp_norm = np.linalg.norm(cp)
-        if cp_norm < tol:
+    # Instead of normalizing v1 and v2, just divide by the greatest
+    # of all their absolute components, which is just enough
+    div1, div2 = max(np.abs(v1)), max(np.abs(v2))
+    if div1 == 0.0:
+        if div2 == 0.0:
             return DOWN
-    return normalize(cp)
+        u = v2 / div2
+    elif div2 == 0.0:
+        u = v1 / div1
+    else:
+        # Normal scenario: v1 and v2 are both non-null
+        u1, u2 = v1 / div1, v2 / div2
+        cp = cross(u1, u2)
+        cp_norm = np.sqrt(norm_squared(cp))
+        if cp_norm > tol:
+            return cp / cp_norm
+        # Otherwise, v1 and v2 were aligned
+        u = u1
+
+    # If you are here, you have an "unique", non-zero, unit-ish vector u
+    # If it's also too aligned to the Z axis, just return DOWN
+    if abs(u[0]) < tol and abs(u[1]) < tol:
+        return DOWN
+    # Otherwise rotate u in the plane it shares with the Z axis,
+    # 90° TOWARDS the Z axis. This is done via (u x [0, 0, 1]) x u,
+    # which gives [-xz, -yz, x²+y²] (slightly scaled as well)
+    cp = np.array([-u[0] * u[2], -u[1] * u[2], u[0] * u[0] + u[1] * u[1]])
+    cp_norm = np.sqrt(norm_squared(cp))
+    # Because the norm(u) == 0 case was filtered in the beginning,
+    # there is no need to check if the norm of cp is 0
+    return cp / cp_norm
 
 
 ###
@@ -529,8 +568,8 @@ def line_intersection(
         np.pad(np.array(i)[:, :2], ((0, 0), (0, 1)), constant_values=1)
         for i in (line1, line2)
     )
-    line1, line2 = (np.cross(*i) for i in padded)
-    x, y, z = np.cross(line1, line2)
+    line1, line2 = (cross(*i) for i in padded)
+    x, y, z = cross(line1, line2)
 
     if z == 0:
         raise ValueError(
@@ -558,7 +597,7 @@ def find_intersection(
     result = []
 
     for p0, v0, p1, v1 in zip(*[p0s, v0s, p1s, v1s]):
-        normal = np.cross(v1, np.cross(v0, v1))
+        normal = cross(v1, cross(v0, v1))
         denom = max(np.dot(v0, normal), threshold)
         result += [p0 + np.dot(p1 - p0, normal) / denom * v0]
     return result
@@ -623,8 +662,9 @@ def shoelace_direction(x_y: np.ndarray) -> str:
 
 
 def cross2d(
-    a: Sequence[Vector] | Vector, b: Sequence[Vector] | Vector
-) -> Sequence[float] | float:
+    a: Vector2D | Vector2D_Array,
+    b: Vector2D | Vector2D_Array,
+) -> ManimFloat | npt.NDArray[ManimFloat]:
     """Compute the determinant(s) of the passed
     vector (sequences).
 
@@ -715,9 +755,14 @@ def earclip_triangulation(verts: np.ndarray, ring_ends: list) -> list:
 
         # Move the ring which j belongs to from the
         # attached list to the detached list
-        new_ring = next(filter(lambda ring: ring[0] <= j < ring[-1], detached_rings))
-        detached_rings.remove(new_ring)
-        attached_rings.append(new_ring)
+        new_ring = next(
+            (ring for ring in detached_rings if ring[0] <= j < ring[-1]), None
+        )
+        if new_ring is not None:
+            detached_rings.remove(new_ring)
+            attached_rings.append(new_ring)
+        else:
+            raise Exception("Could not find a ring to attach")
 
     # Setup linked list
     after = []
@@ -814,6 +859,6 @@ def perpendicular_bisector(
     """
     p1 = line[0]
     p2 = line[1]
-    direction = np.cross(p1 - p2, norm_vector)
+    direction = cross(p1 - p2, norm_vector)
     m = midpoint(p1, p2)
     return [m + direction, m - direction]

manim/utils/testing/__init__.py

@@ -0,0 +1,17 @@
+"""Utilities for Manim tests using `pytest <https://pytest.org>`_.
+
+For more information about Manim testing, see:
+
+-   :doc:`/contributing/development`, specifically the ``Tests`` bullet
+    point under :ref:`polishing-changes-and-submitting-a-pull-request`
+-   :doc:`/contributing/testing`
+
+.. autosummary::
+   :toctree: ../reference
+
+   frames_comparison
+   _frames_testers
+   _show_diff
+   _test_class_makers
+
+"""