Merge pull request matplotlib#26160 from saranti/axlinesetter

add setters and getters for _AxLine's xy1, xy2 and slope parameters

Author: story645

doc/api/lines_api.rst

@@ -17,6 +17,7 @@ Classes
 
    Line2D
    VertexSelector
+   AxLine
 
 Functions
 ---------

doc/users/next_whats_new/axline_setters.rst

@@ -0,0 +1,17 @@
+Axline setters and getters
+--------------------------
+
+The returned object from `.axes.Axes.axline` now supports getter and setter
+methods for its *xy1*, *xy2* and *slope* attributes:
+
+.. code-block:: python
+
+    line1.get_xy1()
+    line1.get_slope()
+    line2.get_xy2()
+
+.. code-block:: python
+
+    line1.set_xy1(.2, .3)
+    line1.set_slope(2.4)
+    line2.set_xy2(.1, .6)

lib/matplotlib/axes/_axes.py

@@ -920,7 +920,7 @@ def axline(self, xy1, xy2=None, *, slope=None, **kwargs):
             # data limits should not be adjusted.
             datalim = []
 
-        line = mlines._AxLine(xy1, xy2, slope, **kwargs)
+        line = mlines.AxLine(xy1, xy2, slope, **kwargs)
         # Like add_line, but correctly handling data limits.
         self._set_artist_props(line)
         if line.get_clip_path() is None:

lib/matplotlib/lines.py

@@ -1464,13 +1464,24 @@ def is_dashed(self):
         return self._linestyle in ('--', '-.', ':')
 
 
-class _AxLine(Line2D):
+class AxLine(Line2D):
     """
     A helper class that implements `~.Axes.axline`, by recomputing the artist
     transform at draw time.
     """
 
     def __init__(self, xy1, xy2, slope, **kwargs):
+        """
+        Parameters
+        ----------
+        xy1 : (float, float)
+            The first set of (x, y) coordinates for the line to pass through.
+        xy2 : (float, float) or None
+            The second set of (x, y) coordinates for the line to pass through.
+            Either *xy2* or *slope* has to be given.
+        slope : float or None
+            The slope of the line. Either *xy2* or *slope* has to be given.
+        """
         super().__init__([0, 1], [0, 1], **kwargs)
 
         if (xy2 is None and slope is None or
@@ -1527,6 +1538,65 @@ def draw(self, renderer):
         self._transformed_path = None  # Force regen.
         super().draw(renderer)
 
+    def get_xy1(self):
+        """
+        Return the *xy1* value of the line.
+        """
+        return self._xy1
+
+    def get_xy2(self):
+        """
+        Return the *xy2* value of the line.
+        """
+        return self._xy2
+
+    def get_slope(self):
+        """
+        Return the *slope* value of the line.
+        """
+        return self._slope
+
+    def set_xy1(self, x, y):
+        """
+        Set the *xy1* value of the line.
+
+        Parameters
+        ----------
+        x, y : float
+            Points for the line to pass through.
+        """
+        self._xy1 = x, y
+
+    def set_xy2(self, x, y):
+        """
+        Set the *xy2* value of the line.
+
+        Parameters
+        ----------
+        x, y : float
+            Points for the line to pass through.
+        """
+        if self._slope is None:
+            self._xy2 = x, y
+        else:
+            raise ValueError("Cannot set an 'xy2' value while 'slope' is set;"
+                             " they differ but their functionalities overlap")
+
+    def set_slope(self, slope):
+        """
+        Set the *slope* value of the line.
+
+        Parameters
+        ----------
+        slope : float
+            The slope of the line.
+        """
+        if self._xy2 is None:
+            self._slope = slope
+        else:
+            raise ValueError("Cannot set a 'slope' value while 'xy2' is set;"
+                             " they differ but their functionalities overlap")
+
 
 class VertexSelector:
     """

lib/matplotlib/lines.pyi

@@ -120,14 +120,20 @@ class Line2D(Artist):
     def get_solid_capstyle(self) -> Literal["butt", "projecting", "round"]: ...
     def is_dashed(self) -> bool: ...
 
-class _AxLine(Line2D):
+class AxLine(Line2D):
     def __init__(
         self,
         xy1: tuple[float, float],
         xy2: tuple[float, float] | None,
         slope: float | None,
         **kwargs
     ) -> None: ...
+    def get_xy1(self) -> tuple[float, float] | None: ...
+    def get_xy2(self) -> tuple[float, float] | None: ...
+    def get_slope(self) -> float: ...
+    def set_xy1(self, x: float, y: float) -> None: ...
+    def set_xy2(self, x: float, y: float) -> None: ...
+    def set_slope(self, slope: float) -> None: ...
 
 class VertexSelector:
     axes: Axes

lib/matplotlib/tests/test_lines.py

@@ -409,3 +409,30 @@ def test_markevery_prop_cycle(fig_test, fig_ref):
     ax = fig_test.add_subplot()
     for i, _ in enumerate(cases):
         ax.plot(y - i, 'o-')
+
+
+def test_axline_setters():
+    fig, ax = plt.subplots()
+    line1 = ax.axline((.1, .1), slope=0.6)
+    line2 = ax.axline((.1, .1), (.8, .4))
+    # Testing xy1, xy2 and slope setters.
+    # This should not produce an error.
+    line1.set_xy1(.2, .3)
+    line1.set_slope(2.4)
+    line2.set_xy1(.3, .2)
+    line2.set_xy2(.6, .8)
+    # Testing xy1, xy2 and slope getters.
+    # Should return the modified values.
+    assert line1.get_xy1() == (.2, .3)
+    assert line1.get_slope() == 2.4
+    assert line2.get_xy1() == (.3, .2)
+    assert line2.get_xy2() == (.6, .8)
+    # Testing setting xy2 and slope together.
+    # These test should raise a ValueError
+    with pytest.raises(ValueError,
+                       match="Cannot set an 'xy2' value while 'slope' is set"):
+        line1.set_xy2(.2, .3)
+
+    with pytest.raises(ValueError,
+                       match="Cannot set a 'slope' value while 'xy2' is set"):
+        line2.set_slope(3)