job-shop-lib 1.0.0a2__py3-none-any.whl → 1.0.0a4__py3-none-any.whl

job_shop_lib/visualization/_gantt_chart_creator.py

@@ -1,7 +1,6 @@
 """Home of the `GanttChartCreator` class and its configuration types."""
 
 from typing import TypedDict
-
 import matplotlib.pyplot as plt
 
 from job_shop_lib.dispatching import (
@@ -10,62 +9,92 @@ from job_shop_lib.dispatching import (
 )
 from job_shop_lib.visualization import (
     create_gantt_chart_video,
-    plot_gantt_chart_wrapper,
-    create_gif,
+    get_partial_gantt_chart_plotter,
+    create_gantt_chart_gif,
 )
 
 
-class GanttChartWrapperConfig(TypedDict, total=False):
-    """Configuration for creating the plot function with the
-    `plot_gantt_chart_wrapper` function."""
+class PartialGanttChartPlotterConfig(TypedDict, total=False):
+    """A dictionary with the configuration for creating the
+    :class:`PartialGanttChartPlotter` function.
+
+    .. seealso::
+
+        - :class:`PartialGanttChartPlotter`
+        - :func:`get_partial_gantt_chart_plotter`
+    """
 
     title: str | None
+    """The title of the Gantt chart."""
+
     cmap: str
+    """The colormap to use in the Gantt chart."""
+
     show_available_operations: bool
+    """Whether to show available operations in each step."""
 
 
-# We can't use Required here because it's not available in Python 3.10
-class _GifConfigRequired(TypedDict):
-    """Required configuration for creating the GIF."""
+class GifConfig(TypedDict, total=False):
+    """A dictionary with the configuration for creating the GIF using the
+    :func:`create_gantt_chart_gif` function.
 
-    gif_path: str | None
+    .. seealso::
 
+        :func:`create_gantt_chart_gif`
+    """
 
-class _GifConfigOptional(TypedDict, total=False):
-    """Optional configuration for creating the GIF."""
+    gif_path: str | None
+    """The path to save the GIF. It must end with '.gif'."""
 
     fps: int
+    """The frames per second of the GIF. Defaults to 1."""
+
     remove_frames: bool
-    frames_dir: str | None
-    plot_current_time: bool
+    """Whether to remove the frames after creating the GIF."""
 
+    frames_dir: str | None
+    """The directory to store the frames."""
 
-class GifConfig(_GifConfigRequired, _GifConfigOptional):
-    """Configuration for creating the GIF using the `create_gannt_chart_video`
-    function."""
+    plot_current_time: bool
+    """Whether to plot the current time in the Gantt chart."""
 
 
 class VideoConfig(TypedDict, total=False):
     """Configuration for creating the video using the
-    `create_gannt_chart_video` function."""
+    :func:`create_gantt_chart_video` function.
+
+    .. seealso::
+
+        :func:`create_gantt_chart_video`
+    """
 
     video_path: str | None
+    """The path to save the video. It must end with a valid video extension
+    (e.g., '.mp4')."""
+
     fps: int
+    """The frames per second of the video. Defaults to 1."""
+
     remove_frames: bool
+    """Whether to remove the frames after creating the video."""
+
     frames_dir: str | None
+    """The directory to store the frames."""
+
     plot_current_time: bool
+    """Whether to plot the current time in the Gantt chart."""
 
 
 class GanttChartCreator:
     """Facade class that centralizes the creation of Gantt charts, videos
     and GIFs.
 
-    It leverages a `HistoryObserver` to keep track of the operations being
-    scheduled and provides methods to plot the current state
-    of the schedule as a Gantt chart and to create a GIF that shows the
-    evolution of the schedule over time.
+    It leverages a :class:`HistoryObserver` to keep track of the operations
+    being scheduled and provides methods to plot the current state
+    of the schedule as a Gantt chart and to create a GIF or video that shows
+    the evolution of the schedule over time.
 
-    It adds a new `HistoryObserver` to the dispatcher if it does
+    It adds a new :class:`HistoryObserver` to the dispatcher if it does
     not have one already. Otherwise, it uses the observer already present.
 
     Attributes:
@@ -81,72 +110,80 @@ class GanttChartCreator:
             Configuration for creating the video.
         plot_function:
             The function used to plot the Gantt chart when creating the GIF
-            or video. Created using the `plot_gantt_chart_wrapper` function.
+            or video. Created using the :func:`get_partial_gantt_chart_plotter`
+            function.
+
+    Args:
+        dispatcher:
+            The :class:`Dispatcher` class that will be tracked using a
+            :class:`HistoryObserver`.
+        partial_gantt_chart_plotter_config:
+            Configuration for the Gantt chart wrapper function through the
+            :class:`PartialGanttChartPlotterConfig` class. Defaults to
+            ``None``. Valid keys are:
+
+            - title: The title of the Gantt chart.
+            - cmap: The name of the colormap to use.
+            - show_available_operations: Whether to show available
+                operations in each step.
+
+            If ``title`` or ``cmap`` are not provided here and
+            ``infer_gantt_chart_config`` is set to ``True``, the values from
+            ``gantt_chart_config`` will be used if they are present.
+
+            .. seealso::
+
+                - :class:`PartialGanttChartPlotterConfig`
+                - :func:`get_partial_gantt_chart_plotter`
+                - :class:`PartialGanttChartPlotter`
+
+        gif_config:
+            Configuration for creating the GIF. Defaults to ``None``.
+            Valid keys are:
+
+            - gif_path: The path to save the GIF.
+            - fps: The frames per second of the GIF.
+            - remove_frames: Whether to remove the frames after creating
+                the GIF.
+            - frames_dir: The directory to store the frames.
+            - plot_current_time: Whether to plot the current time in the
+                Gantt chart.
+        video_config:
+            Configuration for creating the video. Defaults to ``None``.
+            Valid keys are:
+
+            - video_path: The path to save the video.
+            - fps: The frames per second of the video.
+            - remove_frames: Whether to remove the frames after creating
+                the video.
+            - frames_dir: The directory to store the frames.
+            - plot_current_time: Whether to plot the current time in the
+                Gantt chart.
     """
 
     def __init__(
         self,
         dispatcher: Dispatcher,
-        gantt_chart_wrapper_config: GanttChartWrapperConfig | None = None,
+        partial_gantt_chart_plotter_config: (
+            PartialGanttChartPlotterConfig | None
+        ) = None,
         gif_config: GifConfig | None = None,
         video_config: VideoConfig | None = None,
     ):
-        """Initializes the GanttChartCreator with the given configurations
-        and history observer.
-
-        This class adds a new `HistoryObserver` to the dispatcher if it does
-        not have one already. Otherwise, it uses the observer already present.
-
-        Args:
-            dispatcher:
-                The `Dispatcher` class that will be tracked using a
-                `HistoryObserver`.
-            gantt_chart_wrapper_config:
-                Configuration for the Gantt chart wrapper function. Valid keys
-                are:
-                - title: The title of the Gantt chart.
-                - cmap: The name of the colormap to use.
-                - show_available_operations: Whether to show available
-                    operations in each step.
-
-                If `title` or `cmap` are not provided here and
-                `infer_gantt_chart_config` is set to True, the values from
-                `gantt_chart_config` will be used if they are present.
-            gif_config:
-                Configuration for creating the GIF. Defaults to None.
-                Valid keys are:
-                - gif_path: The path to save the GIF.
-                - fps: The frames per second of the GIF.
-                - remove_frames: Whether to remove the frames after creating
-                    the GIF.
-                - frames_dir: The directory to store the frames.
-                - plot_current_time: Whether to plot the current time in the
-                    Gantt chart.
-            video_config:
-                Configuration for creating the video. Defaults to None.
-                Valid keys are:
-                - video_path: The path to save the video.
-                - fps: The frames per second of the video.
-                - remove_frames: Whether to remove the frames after creating
-                    the video.
-                - frames_dir: The directory to store the frames.
-                - plot_current_time: Whether to plot the current time in the
-                    Gantt chart.
-        """
         if gif_config is None:
-            gif_config = {"gif_path": None}
-        if gantt_chart_wrapper_config is None:
-            gantt_chart_wrapper_config = {}
+            gif_config = {}
+        if partial_gantt_chart_plotter_config is None:
+            partial_gantt_chart_plotter_config = {}
         if video_config is None:
             video_config = {}
 
         self.gif_config = gif_config
-        self.gannt_chart_wrapper_config = gantt_chart_wrapper_config
+        self.gannt_chart_wrapper_config = partial_gantt_chart_plotter_config
         self.video_config = video_config
         self.history_observer: HistoryObserver = (
             dispatcher.create_or_get_observer(HistoryObserver)
         )
-        self.plot_function = plot_gantt_chart_wrapper(
+        self.partial_gantt_chart_plotter = get_partial_gantt_chart_plotter(
             **self.gannt_chart_wrapper_config
         )
 
@@ -169,37 +206,38 @@ class GanttChartCreator:
         """Plots the current Gantt chart of the schedule.
 
         Returns:
-            tuple[plt.Figure, plt.Axes]:
-                The figure and axes of the plotted Gantt chart.
+            The figure of the plotted Gantt chart.
         """
-        return self.plot_function(
+        a = self.partial_gantt_chart_plotter(
             self.schedule,
             None,
-            self.dispatcher.ready_operations(),
+            self.dispatcher.available_operations(),
             self.dispatcher.current_time(),
         )
+        return a
 
     def create_gif(self) -> None:
         """Creates a GIF of the schedule being built using the recorded
         history.
 
         This method uses the history of scheduled operations recorded by the
-        `HistoryTracker` to create a GIF that shows the progression of the
-        scheduling process.
+        :class:`HistoryTracker` to create a GIF that shows the progression of
+        the scheduling process.
 
         The GIF creation process involves:
+
         - Using the history of scheduled operations to generate frames for
             each step of the schedule.
         - Creating a GIF from these frames.
         - Optionally, removing the frames after the GIF is created.
 
         The configuration for the GIF creation can be customized through the
-        `gif_config` attribute.
+        ``gif_config`` attribute.
         """
-        create_gif(
+        create_gantt_chart_gif(
             instance=self.history_observer.dispatcher.instance,
             schedule_history=self.history_observer.history,
-            plot_function=self.plot_function,
+            plot_function=self.partial_gantt_chart_plotter,
             **self.gif_config
         )
 
@@ -208,12 +246,12 @@ class GanttChartCreator:
         history.
 
         This method uses the history of scheduled operations recorded by the
-        `HistoryTracker` to create a video that shows the progression of the
-        scheduling process.
+        :class:`HistoryTracker` to create a video that shows the progression
+        of the scheduling process.
         """
         create_gantt_chart_video(
             instance=self.history_observer.dispatcher.instance,
             schedule_history=self.history_observer.history,
-            plot_function=self.plot_function,
+            plot_function=self.partial_gantt_chart_plotter,
             **self.video_config
         )

job_shop_lib/visualization/_gantt_chart_video_and_gif_creation.py

@@ -3,8 +3,7 @@
 import os
 import pathlib
 import shutil
-from collections.abc import Callable
-from typing import Sequence
+from typing import Sequence, Protocol
 
 import imageio
 import matplotlib.pyplot as plt
@@ -23,19 +22,53 @@ from job_shop_lib.dispatching import (
     HistoryObserver,
 )
 from job_shop_lib.dispatching.rules import DispatchingRuleSolver
-from job_shop_lib.visualization._gantt_chart import plot_gantt_chart
-
-
-PlotFunction = Callable[
-    [Schedule, int | None, list[Operation] | None, int | None], Figure
-]
-
+from job_shop_lib.visualization._plot_gantt_chart import plot_gantt_chart
+
+
+# This class serves as a more meaningful type hint than simply:
+# PlotFunction = Callable[
+#     [Schedule, int | None, list[Operation] | None, int | None], Figure
+# ]
+# That's why it doesn't have more methods or attributes. It is a protocol
+# for functions, not for classes.
+# pylint: disable=too-few-public-methods
+class PartialGanttChartPlotter(Protocol):
+    """A protocol for a function that plots an uncompleted Gantt chart
+    for a schedule.
+
+    This kind of functions are created using the
+    :func:`plot_gantt_chart_wrapper` function.
+    """
 
-def plot_gantt_chart_wrapper(
+    def __call__(
+        self,
+        schedule: Schedule,
+        makespan: int | None = None,
+        available_operations: list[Operation] | None = None,
+        current_time: int | None = None,
+    ) -> Figure:
+        """Plots a Gantt chart for an unfinished schedule.
+
+        Args:
+            schedule:
+                The schedule to plot.
+            makespan:
+                The makespan of the schedule if known. Can be used to fix
+                the x-axis limits.
+            available_operations:
+                A list of available operations. If ``None``,
+                the available operations are not shown.
+            current_time:
+                The current time in the schedule. If provided, a red
+                vertical line is plotted at this time.
+        """
+
+
+def get_partial_gantt_chart_plotter(
     title: str | None = None,
     cmap: str = "viridis",
     show_available_operations: bool = False,
-) -> PlotFunction:
+) -> PartialGanttChartPlotter:
     """Returns a function that plots a Gantt chart for an unfinished schedule.
 
     Args:
@@ -47,12 +80,13 @@ def plot_gantt_chart_wrapper(
     Returns:
         A function that plots a Gantt chart for a schedule. The function takes
         the following arguments:
+
         - schedule: The schedule to plot.
         - makespan: The makespan of the schedule.
         - available_operations: A list of available operations. If None,
-            the available operations are not shown.
+          the available operations are not shown.
         - current_time: The current time in the schedule. If provided, a
-            red vertical line is plotted at this time.
+          red vertical line is plotted at this time.
 
     """
 
@@ -97,33 +131,30 @@ def plot_gantt_chart_wrapper(
 # Most of the arguments are optional with default values. There is no way to
 # reduce the number of arguments without losing functionality.
 # pylint: disable=too-many-arguments
-def create_gif(
-    gif_path: str | None,
+def create_gantt_chart_gif(
     instance: JobShopInstance,
+    gif_path: str | None = None,
     solver: DispatchingRuleSolver | None = None,
-    plot_function: PlotFunction | None = None,
+    plot_function: PartialGanttChartPlotter | None = None,
     fps: int = 1,
     remove_frames: bool = True,
     frames_dir: str | None = None,
     plot_current_time: bool = True,
     schedule_history: Sequence[ScheduledOperation] | None = None,
 ) -> None:
-    """Creates a GIF of the schedule being built by the given solver.
-
-    Deprecated since version 0.6.0: Use `create_gif_or_video` instead.
+    """Creates a GIF of the schedule being built.
 
     Args:
-        gif_path:
-            The path to save the GIF file. It should end with ".gif". If not
-            provided, the name of the instance is used. It will be made an
-            optional argument in version 1.0.0.
         instance:
             The instance of the job shop problem to be scheduled.
+        gif_path:
+            The path to save the GIF file. It should end with ".gif". If not
+            provided, the name of the instance is used.
         solver:
             The dispatching rule solver to use. If not provided, the history
             of scheduled operations should be provided.
         plot_function:
-            A function that plots a Gantt chart for a schedule. It
+            A :class:`PlotFunction` that plots a Gantt chart for a schedule. It
             should take a `Schedule` object and the makespan of the schedule as
             input and return a `Figure` object. If not provided, a default
             function is used.
@@ -133,7 +164,7 @@ def create_gif(
             Whether to remove the frames after creating the GIF.
         frames_dir:
             The directory to save the frames in. If not provided,
-            `gif_path.replace(".gif", "") + "_frames"` is used.
+            ``gif_path.replace(".gif", "") + "_frames"`` is used.
         plot_current_time:
             Whether to plot a vertical line at the current time.
         schedule_history:
@@ -144,7 +175,7 @@ def create_gif(
         gif_path = f"{instance.name}_gantt_chart.gif"
 
     if plot_function is None:
-        plot_function = plot_gantt_chart_wrapper()
+        plot_function = get_partial_gantt_chart_plotter()
 
     if frames_dir is None:
         # Use the name of the GIF file as the directory name
@@ -173,14 +204,14 @@ def create_gantt_chart_video(
     instance: JobShopInstance,
     video_path: str | None = None,
     solver: DispatchingRuleSolver | None = None,
-    plot_function: PlotFunction | None = None,
+    plot_function: PartialGanttChartPlotter | None = None,
     fps: int = 1,
     remove_frames: bool = True,
     frames_dir: str | None = None,
     plot_current_time: bool = True,
     schedule_history: Sequence[ScheduledOperation] | None = None,
 ) -> None:
-    """Creates a GIF of the schedule being built by the given solver.
+    """Creates a video of the schedule being built.
 
     Args:
         instance:
@@ -192,16 +223,16 @@ def create_gantt_chart_video(
             of scheduled operations should be provided.
         plot_function:
             A function that plots a Gantt chart for a schedule. It
-            should take a `Schedule` object and the makespan of the schedule as
-            input and return a `Figure` object. If not provided, a default
-            function is used.
+            should take a :class:`Schedule` object and the makespan of the
+            schedule as input and return a ``Figure`` object. If not provided,
+            a default function is used.
         fps:
-            The number of frames per second in the GIF.
+            The number of frames per second in the video.
         remove_frames:
-            Whether to remove the frames after creating the GIF.
+            Whether to remove the frames after creating the video.
         frames_dir:
             The directory to save the frames in. If not provided,
-            `name_without_the_extension` + "_frames"` is used.
+            ``name_without_the_extension + "_frames"`` is used.
         plot_current_time:
             Whether to plot a vertical line at the current time.
         schedule_history:
@@ -212,7 +243,7 @@ def create_gantt_chart_video(
         video_path = f"{instance.name}_gantt_chart.mp4"
 
     if plot_function is None:
-        plot_function = plot_gantt_chart_wrapper()
+        plot_function = get_partial_gantt_chart_plotter()
 
     if frames_dir is None:
         extension = video_path.split(".")[-1]
@@ -238,7 +269,7 @@ def create_gantt_chart_frames(
     frames_dir: str,
     instance: JobShopInstance,
     solver: DispatchingRuleSolver | None,
-    plot_function: PlotFunction,
+    plot_function: PartialGanttChartPlotter,
     plot_current_time: bool = True,
     schedule_history: Sequence[ScheduledOperation] | None = None,
 ) -> None:
@@ -295,7 +326,7 @@ def create_gantt_chart_frames(
         fig = plot_function(
             dispatcher.schedule,
             makespan,
-            dispatcher.ready_operations(),
+            dispatcher.available_operations(),
             current_time,
         )
         _save_frame(fig, frames_dir, i)