tools: added docstrings/typing annotations

Author: PierreRaybaut

plotpy/tools/annotation.py

@@ -1,4 +1,9 @@
-# -*- coding: utf-8 -*-
+# -*- coding: utf-8 -*-# -*- coding: utf-8 -*-
+#
+# Licensed under the terms of the BSD 3-Clause
+# (see plotpy/LICENSE for details)
+
+from __future__ import annotations
 
 from plotpy.items import (
     AnnotatedCircle,
@@ -19,45 +24,79 @@
 
 
 class AnnotatedRectangleTool(RectangleTool):
-    def create_shape(self):
+    """
+    Tool for creating annotated rectangle shapes.
+
+    This tool extends the RectangleTool to create AnnotatedRectangle objects.
+    """
+
+    def create_shape(self) -> tuple[AnnotatedRectangle, int, int]:
         """
+        Create an annotated rectangle shape.
 
-        :return:
+        Returns:
+            A tuple containing the AnnotatedRectangle object and its handle indices.
         """
         annotation = AnnotatedRectangle(0, 0, 1, 1)
         self.set_shape_style(annotation)
         return annotation, 0, 2
 
 
 class AnnotatedObliqueRectangleTool(ObliqueRectangleTool):
-    AVOID_NULL_SHAPE = True
+    """
+    Tool for creating annotated oblique rectangle shapes.
+
+    This tool extends the ObliqueRectangleTool to create
+    AnnotatedObliqueRectangle objects.
+    """
 
-    def create_shape(self):
+    AVOID_NULL_SHAPE: bool = True
+
+    def create_shape(self) -> tuple[AnnotatedObliqueRectangle, int, int]:
         """
+        Create an annotated oblique rectangle shape.
 
-        :return:
+        Returns:
+            A tuple containing the AnnotatedObliqueRectangle object
+            and its handle indices.
         """
         annotation = AnnotatedObliqueRectangle(0, 0, 1, 0, 1, 1, 0, 1)
         self.set_shape_style(annotation)
         return annotation, 0, 2
 
 
 class AnnotatedCircleTool(CircleTool):
-    def create_shape(self):
+    """
+    Tool for creating annotated circle shapes.
+
+    This tool extends the CircleTool to create AnnotatedCircle objects.
+    """
+
+    def create_shape(self) -> tuple[AnnotatedCircle, int, int]:
         """
+        Create an annotated circle shape.
 
-        :return:
+        Returns:
+            A tuple containing the AnnotatedCircle object and its handle indices.
         """
         annotation = AnnotatedCircle(0, 0, 1, 1)
         self.set_shape_style(annotation)
         return annotation, 0, 1
 
 
 class AnnotatedEllipseTool(EllipseTool):
-    def create_shape(self):
+    """
+    Tool for creating annotated ellipse shapes.
+
+    This tool extends the EllipseTool to create AnnotatedEllipse objects.
+    """
+
+    def create_shape(self) -> tuple[AnnotatedEllipse, int, int]:
         """
+        Create an annotated ellipse shape.
 
-        :return:
+        Returns:
+            A tuple containing the AnnotatedEllipse object and its handle indices.
         """
         annotation = AnnotatedEllipse(0, 0, 1, 1)
         annotation.shape.switch_to_circle()
@@ -66,21 +105,37 @@ def create_shape(self):
 
 
 class AnnotatedPointTool(PointTool):
-    def create_shape(self):
+    """
+    Tool for creating annotated point shapes.
+
+    This tool extends the PointTool to create AnnotatedPoint objects.
+    """
+
+    def create_shape(self) -> tuple[AnnotatedPoint, int, int]:
         """
+        Create an annotated point shape.
 
-        :return:
+        Returns:
+            A tuple containing the AnnotatedPoint object and its handle indices.
         """
         annotation = AnnotatedPoint(0, 0)
         self.set_shape_style(annotation)
         return annotation, 0, 0
 
 
 class AnnotatedSegmentTool(SegmentTool):
-    def create_shape(self):
+    """
+    Tool for creating annotated segment shapes.
+
+    This tool extends the SegmentTool to create AnnotatedSegment objects.
+    """
+
+    def create_shape(self) -> tuple[AnnotatedSegment, int, int]:
         """
+        Create an annotated segment shape.
 
-        :return:
+        Returns:
+            A tuple containing the AnnotatedSegment object and its handle indices.
         """
         annotation = AnnotatedSegment(0, 0, 1, 1)
         self.set_shape_style(annotation)

plotpy/tools/axes.py

@@ -1,4 +1,11 @@
-# -*- coding: utf-8 -*-
+# -*- coding: utf-8 -*-# -*- coding: utf-8 -*-
+#
+# Licensed under the terms of the BSD 3-Clause
+# (see plotpy/LICENSE for details)
+
+"""Axes tools"""
+
+from __future__ import annotations
 
 from guidata.configtools import get_icon
 from guidata.qthelpers import add_actions
@@ -11,16 +18,35 @@
 
 
 class AxisScaleTool(CommandTool):
-    """ """
+    """
+    A tool for changing the scale of plot axes.
+
+    This tool provides options to switch between linear and logarithmic scales
+    for both x and y axes.
+    """
 
     def __init__(self, manager):
+        """
+        Initialize the AxisScaleTool.
+
+        Args:
+            manager: The plot manager.
+        """
         super().__init__(
             manager, _("Scale"), icon=get_icon("log_log.png"), tip=None, toolbar_id=None
         )
         self.action.setEnabled(True)
 
-    def create_action_menu(self, manager):
-        """Create and return menu for the tool's action"""
+    def create_action_menu(self, manager) -> QW.QMenu:
+        """
+        Create and return menu for the tool's action.
+
+        Args:
+            manager: The plot manager.
+
+        Returns:
+            A QMenu object containing scale options.
+        """
         menu = QW.QMenu()
         group = QW.QActionGroup(manager.get_main())
         lin_lin = manager.create_action(
@@ -53,10 +79,12 @@ def create_action_menu(self, manager):
             add_actions(obj, (lin_lin, lin_log, log_lin, log_log))
         return menu
 
-    def update_status(self, plot):
+    def update_status(self, plot) -> None:
         """
+        Update the status of scale actions based on the current plot scales.
 
-        :param plot:
+        Args:
+            plot: The current plot object.
         """
         item = plot.get_active_item()
         active_scale = ("lin", "lin")
@@ -74,13 +102,14 @@ def update_status(self, plot):
                 else:
                     scale_action.setChecked(False)
 
-    def set_scale(self, checked, xscale, yscale):
+    def set_scale(self, checked: bool, xscale: str, yscale: str) -> None:
         """
+        Set the scale of the active plot.
 
-        :param checked:
-        :param xscale:
-        :param yscale:
-        :return:
+        Args:
+            checked: Whether the action is checked.
+            xscale: The scale for the x-axis ('lin' or 'log').
+            yscale: The scale for the y-axis ('lin' or 'log').
         """
         if not checked:
             return
@@ -92,14 +121,23 @@ def set_scale(self, checked, xscale, yscale):
 
 
 class PlaceAxesTool(RectangularShapeTool):
-    TITLE = _("Axes")
-    ICON = "gtaxes.png"
-    SHAPE_STYLE_KEY = "shape/axes"
+    """
+    A tool for placing axes on the plot.
+
+    This tool allows users to draw a rectangular shape to define
+    the position and size of the axes on the plot.
+    """
+
+    TITLE: str = _("Axes")
+    ICON: str = "gtaxes.png"
+    SHAPE_STYLE_KEY: str = "shape/axes"
 
-    def create_shape(self):
+    def create_shape(self) -> tuple[Axes, int, int]:
         """
+        Create an Axes shape.
 
-        :return:
+        Returns:
+            A tuple containing the Axes object and its handle indices.
         """
         shape = Axes((0, 1), (1, 1), (0, 0))
         self.set_shape_style(shape)