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

manim/utils/bezier.py

@@ -261,13 +261,11 @@ def quadratic_bezier_remap(
 
 
 @overload
-def interpolate(start: float, end: float, alpha: float) -> float:
-    ...
+def interpolate(start: float, end: float, alpha: float) -> float: ...
 
 
 @overload
-def interpolate(start: Point3D, end: Point3D, alpha: float) -> Point3D:
-    ...
+def interpolate(start: Point3D, end: Point3D, alpha: float) -> Point3D: ...
 
 
 def interpolate(
@@ -321,13 +319,11 @@ def integer_interpolate(
 
 
 @overload
-def mid(start: float, end: float) -> float:
-    ...
+def mid(start: float, end: float) -> float: ...
 
 
 @overload
-def mid(start: Point3D, end: Point3D) -> Point3D:
-    ...
+def mid(start: Point3D, end: Point3D) -> Point3D: ...
 
 
 def mid(start: float | Point3D, end: float | Point3D) -> float | Point3D:
@@ -348,18 +344,15 @@ def mid(start: float | Point3D, end: float | Point3D) -> float | Point3D:
 
 
 @overload
-def inverse_interpolate(start: float, end: float, value: float) -> float:
-    ...
+def inverse_interpolate(start: float, end: float, value: float) -> float: ...
 
 
 @overload
-def inverse_interpolate(start: float, end: float, value: Point3D) -> Point3D:
-    ...
+def inverse_interpolate(start: float, end: float, value: Point3D) -> Point3D: ...
 
 
 @overload
-def inverse_interpolate(start: Point3D, end: Point3D, value: Point3D) -> Point3D:
-    ...
+def inverse_interpolate(start: Point3D, end: Point3D, value: Point3D) -> Point3D: ...
 
 
 def inverse_interpolate(
@@ -408,8 +401,7 @@ def match_interpolate(
     old_start: float,
     old_end: float,
     old_value: float,
-) -> float:
-    ...
+) -> float: ...
 
 
 @overload
@@ -419,8 +411,7 @@ def match_interpolate(
     old_start: float,
     old_end: float,
     old_value: Point3D,
-) -> Point3D:
-    ...
+) -> Point3D: ...
 
 
 def match_interpolate(

manim/utils/caching.py

@@ -5,6 +5,8 @@ from typing import Callable
 from .. import config, logger
 from ..utils.hashing import get_hash_from_play_call
 
+__all__ = ["handle_caching_play"]
+
 
 def handle_caching_play(func: Callable[..., None]):
     """Decorator that returns a wrapped version of func that will compute

manim/utils/color/BS381.py

@@ -24,6 +24,7 @@ in the standard:
 .. automanimcolormodule:: manim.utils.color.BS381
 
 """
+
 from .core import ManimColor
 
 BS381_101 = ManimColor("#94BFAC")

manim/utils/color/XKCD.py

@@ -23,6 +23,7 @@ taken from https://www.w3schools.com/colors/colors_xkcd.asp.
 .. automanimcolormodule:: manim.utils.color.XKCD
 
 """
+
 from .core import ManimColor
 
 ACIDGREEN = ManimColor("#8FFE09")

manim/utils/color/core.py

@@ -52,7 +52,6 @@ from ...utils.space_ops import normalize
 
 # import manim._config as _config
 
-
 re_hex = re.compile("((?<=#)|(?<=0x))[A-F0-9]{6,8}", re.IGNORECASE)
 
 
@@ -63,7 +62,7 @@ class ManimColor:
     It's internal representation is a 4 element array of floats corresponding
     to a [r,g,b,a] value where r,g,b,a can be between 0 to 1.
 
-    This is done in order to reduce the amount of color inconsitencies by constantly
+    This is done in order to reduce the amount of color inconsistencies by constantly
     casting between integers and floats which introduces errors.
 
     The class can accept any value of type :class:`ParsableManimColor` i.e.
@@ -75,19 +74,33 @@ class ManimColor:
     Be careful when passing strings to ManimColor it can create a big overhead for the color processing.
 
     If you want to parse a list of colors use the function :meth:`parse` in :class:`ManimColor` which assumes that
-    you are going to pass a list of color so arrays will not bei interpreted as a single color.
+    you are going to pass a list of color so arrays will not be interpreted as a single color.
 
     .. warning::
         If you pass an array of numbers to :meth:`parse` it will interpret the r,g,b,a numbers in that array as colors
         so instead of the expect singular color you get and array with 4 colors.
 
-    For conversion behaviors see the _internal functions for further documentation
+    For conversion behaviors see the ``_internal`` functions for further documentation
+
+    You can create a ``ManimColor`` instance via its classmethods. See the respective methods for more info.
+
+    .. code-block:: python
+
+        mycolor = ManimColor.from_rgb((0, 1, 0.4, 0.5))
+        myothercolor = ManimColor.from_rgb((153, 255, 255))
+
+    You can also convert between different color spaces:
+
+    .. code-block:: python
+
+        mycolor_hex = mycolor.to_hex()
+        myoriginalcolor = ManimColor.from_hex(mycolor_hex).to_hsv()
 
     Parameters
     ----------
     value
         Some representation of a color (e.g., a string or
-        a suitable tuple).
+        a suitable tuple). The default ``None`` is ``BLACK``.
     alpha
         The opacity of the color. By default, colors are
         fully opaque (value 1.0).
@@ -460,9 +473,13 @@ class ManimColor:
         str
             A hex string starting with a # with either 6 or 8 nibbles depending on your input, by default 6 i.e #XXXXXX
         """
-        tmp = f"#{int(self._internal_value[0]*255):02X}{int(self._internal_value[1]*255):02X}{int(self._internal_value[2]*255):02X}"
+        tmp = (
+            f"#{int(self._internal_value[0] * 255):02X}"
+            f"{int(self._internal_value[1] * 255):02X}"
+            f"{int(self._internal_value[2] * 255):02X}"
+        )
         if with_alpha:
-            tmp += f"{int(self._internal_value[3]*255):02X}"
+            tmp += f"{int(self._internal_value[3] * 255):02X}"
         return tmp
 
     def to_hsv(self) -> HSV_Array_Float:
@@ -615,8 +632,7 @@ class ManimColor:
         cls,
         color: ParsableManimColor | None,
         alpha: float = ...,
-    ) -> Self:
-        ...
+    ) -> Self: ...
 
     @overload
     @classmethod
@@ -624,8 +640,7 @@ class ManimColor:
         cls,
         color: Sequence[ParsableManimColor],
         alpha: float = ...,
-    ) -> list[Self]:
-        ...
+    ) -> list[Self]: ...
 
     @classmethod
     def parse(
@@ -715,14 +730,17 @@ ParsableManimColor: TypeAlias = Union[
     RGBA_Array_Int,
     RGBA_Array_Float,
 ]
-"""ParsableManimColor is the representation for all types that are parsable to a color in manim"""
+"""`ParsableManimColor` represents all the types which can be parsed
+to a color in Manim.
+"""
 
 
 ManimColorT = TypeVar("ManimColorT", bound=ManimColor)
 
 
 def color_to_rgb(color: ParsableManimColor) -> RGB_Array_Float:
-    """Helper function for use in functional style programming refer to :meth:`to_rgb` in :class:`ManimColor`
+    """Helper function for use in functional style programming.
+    Refer to :meth:`to_rgb` in :class:`ManimColor`.
 
     Parameters
     ----------

manim/utils/commands.py

@@ -14,7 +14,14 @@ __all__ = [
 
 
 def capture(command, cwd=None, command_input=None):
-    p = run(command, cwd=cwd, input=command_input, capture_output=True, text=True)
+    p = run(
+        command,
+        cwd=cwd,
+        input=command_input,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+    )
     out, err = p.stdout, p.stderr
     return out, err, p.returncode
 

manim/utils/debug.py

@@ -1,6 +1,5 @@
 """Debugging utilities."""
 
-
 from __future__ import annotations
 
 __all__ = ["print_family", "index_labels"]

manim/utils/deprecation.py

@@ -233,8 +233,9 @@ def deprecated_params(
     since: str | None = None,
     until: str | None = None,
     message: str | None = "",
-    redirections: None
-    | (Iterable[tuple[str, str] | Callable[..., dict[str, Any]]]) = None,
+    redirections: None | (
+        Iterable[tuple[str, str] | Callable[..., dict[str, Any]]]
+    ) = None,
 ) -> Callable:
     """Decorator to mark parameters of a callable as deprecated.
 

manim/utils/docbuild/__init__.py

@@ -0,0 +1,17 @@
+"""Utilities for building the Manim documentation.
+
+For more information about the Manim documentation building, see:
+
+-   :doc:`/contributing/development`, specifically the ``Documentation``
+    bullet point under :ref:`polishing-changes-and-submitting-a-pull-request`
+-   :doc:`/contributing/docs`
+
+.. autosummary::
+   :toctree: ../reference
+
+   autoaliasattr_directive
+   autocolor_directive
+   manim_directive
+   module_parsing
+
+"""

manim/utils/docbuild/autoaliasattr_directive.py

@@ -0,0 +1,197 @@
+"""A directive for documenting type aliases and other module-level attributes."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from docutils.statemachine import ViewList
+
+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_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()
+]
+
+
+def smart_replace(base: str, alias: str, substitution: str) -> str:
+    """Auxiliary function for substituting type aliases into a base
+    string, when there are overlaps between the aliases themselves.
+
+    Parameters
+    ----------
+    base
+        The string in which the type aliases will be located and
+        replaced.
+    alias
+        The substring to be substituted.
+    substitution
+        The string which will replace every occurrence of ``alias``.
+
+    Returns
+    -------
+    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 != "_"
+
+    start = 0
+    i = 0
+    while True:
+        i = base.find(alias, start)
+        if i == -1:
+            break
+        if (i == 0 or condition(base[i - 1])) and (
+            i + len_alias == len_base or condition(base[i + len_alias])
+        ):
+            occurrences.append(i)
+        start = i + len_alias
+
+    for o in occurrences[::-1]:
+        base = base[:o] + substitution + base[o + len_alias :]
+
+    return base
+
+
+def setup(app: Sphinx) -> None:
+    app.add_directive("autoaliasattr", AliasAttrDocumenter)
+
+
+class AliasAttrDocumenter(Directive):
+    """Directive which replaces Sphinx's Autosummary for module-level
+    attributes: instead, it manually crafts a new "Type Aliases"
+    section, where all the module-level attributes which are explicitly
+    annotated as :class:`TypeAlias` are considered as such, for their
+    use all around the Manim docs.
+
+    These type aliases are separated from the "regular" module-level
+    attributes, which get their traditional "Module Attributes"
+    section autogenerated with Sphinx's Autosummary under "Type
+    Aliases".
+
+    See ``docs/source/_templates/autosummary/module.rst`` to watch
+    this directive in action.
+
+    See :func:`~.parse_module_attributes` for more information on how
+    the modules are parsed to obtain the :class:`TypeAlias` information
+    and separate it from the other attributes.
+    """
+
+    objtype = "autoaliasattr"
+    required_arguments = 1
+    has_content = True
+
+    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)
+
+        content = nodes.container()
+
+        # Add "Type Aliases" section
+        if module_alias_dict is not None:
+            module_alias_section = nodes.section(ids=[f"{module_name}.alias"])
+            content += module_alias_section
+
+            # Use a rubric (title-like), just like in `module.rst`
+            module_alias_section += nodes.rubric(text="Type Aliases")
+
+            # category_name: str
+            # category_dict: AliasCategoryDict = dict[str, AliasInfo]
+            for category_name, category_dict in module_alias_dict.items():
+                category_section = nodes.section(
+                    ids=[category_name.lower().replace(" ", "_")]
+                )
+                module_alias_section += category_section
+                # category_name can be possibly "" for uncategorized aliases
+                if category_name:
+                    category_section += nodes.title(text=category_name)
+
+                category_alias_container = nodes.container()
+                category_section += category_alias_container
+
+                # alias_name: str
+                # alias_info: AliasInfo = dict[str, str]
+                #   Contains "definition": str
+                #   Can possibly contain "doc": str
+                for alias_name, alias_info in category_dict.items():
+                    # Replace all occurrences of type aliases in the
+                    # definition for automatic cross-referencing!
+                    alias_def = alias_info["definition"]
+                    for A in ALIAS_LIST:
+                        alias_def = smart_replace(alias_def, A, f":class:`~.{A}`")
+
+                    # Using the `.. class::` directive is CRUCIAL, since
+                    # function/method parameters are always annotated via
+                    # classes - therefore Sphinx expects a class
+                    unparsed = ViewList(
+                        [
+                            f".. class:: {alias_name}",
+                            "",
+                            "    .. parsed-literal::",
+                            "",
+                            f"        {alias_def}",
+                            "",
+                        ]
+                    )
+
+                    if "doc" in alias_info:
+                        # Replace all occurrences of type aliases in
+                        # the docs for automatic cross-referencing!
+                        alias_doc = alias_info["doc"]
+                        for A in ALIAS_LIST:
+                            alias_doc = alias_doc.replace(f"`{A}`", f":class:`~.{A}`")
+
+                        # 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")
+                        unparsed.extend(ViewList([f"    {line}" for line in doc_lines]))
+
+                    # Parse the reST text into a fresh container
+                    # https://www.sphinx-doc.org/en/master/extdev/markupapi.html#parsing-directive-content-as-rest
+                    alias_container = nodes.container()
+                    self.state.nested_parse(unparsed, 0, alias_container)
+                    category_alias_container += alias_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"])
+            content += module_attrs_section
+
+            # Use the same rubric (title-like) as in `module.rst`
+            module_attrs_section += nodes.rubric(text="Module Attributes")
+            # Let Sphinx Autosummary do its thing as always
+            # Add all the attribute names with 4 spaces behind, so that
+            # they're considered as INSIDE the `.. autosummary::` block
+            unparsed = ViewList(
+                [
+                    ".. autosummary::",
+                    *(f"    {attr}" for attr in module_attrs_list),
+                ]
+            )
+
+            # Parse the reST text into a fresh container
+            # https://www.sphinx-doc.org/en/master/extdev/markupapi.html#parsing-directive-content-as-rest
+            data_container = nodes.container()
+            self.state.nested_parse(unparsed, 0, data_container)
+            module_attrs_section += data_container
+
+        return [content]

manim/utils/docbuild/autocolor_directive.py

@@ -1,13 +1,20 @@
+"""A directive for documenting colors in Manim."""
+
 from __future__ import annotations
 
 import inspect
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 from docutils.parsers.rst import Directive
-from sphinx.application import Sphinx
 
 from manim import ManimColor
 
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+__all__ = ["ManimColorModuleDocumenter"]
+
 
 def setup(app: Sphinx) -> None:
     app.add_directive("automanimcolormodule", ManimColorModuleDocumenter)
@@ -21,9 +28,7 @@ class ManimColorModuleDocumenter(Directive):
     def add_directive_header(self, sig: str) -> None:
         super().add_directive_header(sig)
 
-    def run(
-        self,
-    ) -> None:
+    def run(self) -> list[nodes.Element]:
         module_name = self.arguments[0]
         try:
             import importlib

manim/utils/docbuild/manim_directive.py

@@ -77,6 +77,7 @@ directive:
         that is rendered in a reference block after the source code.
 
 """
+
 from __future__ import annotations
 
 import csv
@@ -88,6 +89,7 @@ import sys
 import textwrap
 from pathlib import Path
 from timeit import timeit
+from typing import TYPE_CHECKING, Any
 
 import jinja2
 from docutils import nodes
@@ -97,7 +99,13 @@ from docutils.statemachine import StringList
 from manim import QUALITIES
 from manim import __version__ as manim_version
 
-classnamedict = {}
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+__all__ = ["ManimDirective"]
+
+
+classnamedict: dict[str, int] = {}
 
 
 class SkipManimNode(nodes.Admonition, nodes.Element):
@@ -110,13 +118,13 @@ class SkipManimNode(nodes.Admonition, nodes.Element):
     pass
 
 
-def visit(self, node, name=""):
+def visit(self: SkipManimNode, node: nodes.Element, name: str = "") -> None:
     self.visit_admonition(node, name)
     if not isinstance(node[0], nodes.title):
         node.insert(0, nodes.title("skip-manim", "Example Placeholder"))
 
 
-def depart(self, node):
+def depart(self: SkipManimNode, node: nodes.Element) -> None:
     self.depart_admonition(node)
 
 
@@ -143,6 +151,7 @@ class ManimDirective(Directive):
 
     See the module docstring for documentation.
     """
+
     has_content = True
     required_arguments = 1
     optional_arguments = 0
@@ -162,7 +171,7 @@ 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 = (
@@ -341,7 +350,7 @@ 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: str, file_name: str) -> None:
     with rendering_times_file_path.open("a") as file:
         csv.writer(file).writerow(
             [
@@ -352,7 +361,7 @@ def _write_rendering_stats(scene_name, run_time, file_name):
         )
 
 
-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))
@@ -377,16 +386,16 @@ 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):
+def setup(app: Sphinx) -> dict[str, Any]:
     app.add_node(SkipManimNode, html=(visit, depart))
 
     setup.app = app