matplotlib · tacaswell · Oct 31, 2024 · Oct 11, 2024 · Oct 23, 2024 · Oct 31, 2024
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -657,6 +657,7 @@
             self.clear()
         else:
             self.converter = None
+            self._converter_is_explicit = False
             self.units = None
 
         self._autoscale_on = True
@@ -887,6 +888,7 @@
         self.reset_ticks()
 
         self.converter = None
+        self._converter_is_explicit = False
         self.units = None
         self.stale = True
 
@@ -1741,12 +1743,16 @@
         ``axis.converter`` instance if necessary. Return *True*
         if *data* is registered for unit conversion.
         """
-        converter = munits.registry.get_converter(data)
+        if not self._converter_is_explicit:
+            converter = munits.registry.get_converter(data)
+        else:
+            converter = self.converter
+
         if converter is None:
             return False
 
         neednew = self.converter != converter
-        self.converter = converter
+        self._set_converter(converter)
         default = self.converter.default_units(data, self)
         if default is not None and self.units is None:
             self.set_units(default)
@@ -1799,7 +1805,7 @@
             return x
 
         if self.converter is None:
-            self.converter = munits.registry.get_converter(x)
+            self._set_converter(munits.registry.get_converter(x))
 
         if self.converter is None:
             return x
@@ -1810,6 +1816,39 @@
                                          f'units: {x!r}') from e
         return ret
 
+    def get_converter(self):
+        """
+        Get the unit converter for axis.
+
+        Returns
+        -------
+        `~matplotlib.units.ConversionInterface` or None
+        """
+        return self.converter
+
+    def set_converter(self, converter):
+        """
+        Set the unit converter for axis.
+
+        Parameters
+        ----------
+        converter : `~matplotlib.dates.ConversionInterface`
+        """
+        self._set_converter(converter)
+        self._converter_is_explicit = True
+
+    def _set_converter(self, converter):
+        if self.converter == converter:
+            return
+        if self._converter_is_explicit:
+            raise RuntimeError("Axis already has an explicit converter set")
+        elif self.converter is not None:
+            _api.warn_external(
+                "This axis already has an converter set and "
+                "is updating to a potentially incompatible converter"
+            )
+        self.converter = converter
+
     def set_units(self, u):
         """
         Set the units for axis.

diff --git a/lib/matplotlib/axis.pyi b/lib/matplotlib/axis.pyi
@@ -15,6 +15,7 @@ from matplotlib.text import Text
 from matplotlib.ticker import Locator, Formatter
 from matplotlib.transforms import Transform, Bbox
 from matplotlib.typing import ColorType
+from matplotlib.units import ConversionInterface
 
 
 GRIDLINE_INTERPOLATION_STEPS: int
@@ -207,6 +208,8 @@ class Axis(martist.Artist):
     def update_units(self, data): ...
     def have_units(self) -> bool: ...
     def convert_units(self, x): ...
+    def get_converter(self) -> ConversionInterface | None: ...
+    def set_converter(self, converter: ConversionInterface) -> None: ...
     def set_units(self, u) -> None: ...
     def get_units(self): ...
     def set_label_text(

diff --git a/lib/matplotlib/tests/test_units.py b/lib/matplotlib/tests/test_units.py
@@ -5,7 +5,7 @@
 import matplotlib.pyplot as plt
 from matplotlib.testing.decorators import check_figures_equal, image_comparison
 import matplotlib.units as munits
-from matplotlib.category import UnitData
+from matplotlib.category import StrCategoryConverter, UnitData
 import numpy as np
 import pytest
 
@@ -236,6 +236,32 @@ def test_shared_axis_categorical():
     assert "c" in ax2.xaxis.get_units()._mapping.keys()
 
 
+def test_explicit_converter():
+    d1 = {"a": 1, "b": 2}
+    str_cat_converter = StrCategoryConverter()
+    str_cat_converter_2 = StrCategoryConverter()
+
+    # Explicit is set
+    fig1, ax1 = plt.subplots()
+    ax1.xaxis.set_converter(str_cat_converter)
+    assert ax1.xaxis.converter == str_cat_converter
+    # Explicit not overridden by implicit
+    ax1.plot(d1.keys(), d1.values())
+    assert ax1.xaxis.converter == str_cat_converter
+    # No error when called twice with equivalent input
+    ax1.xaxis.set_converter(str_cat_converter)
+    # Error when explicit called twice
+    with pytest.raises(RuntimeError):
+        ax1.xaxis.set_converter(str_cat_converter_2)
+
+    # Warn when implicit overridden
+    fig2, ax2 = plt.subplots()
+    ax2.plot(d1.keys(), d1.values())
+
+    with pytest.warns():
+        ax2.xaxis.set_converter(str_cat_converter)
+
+
 def test_empty_default_limits(quantity_converter):
     munits.registry[Quantity] = quantity_converter
     fig, ax1 = plt.subplots()