Merge pull request #20405 from jklymak/enh-expose-make_norm_from_scale

jklymak · web-flow · commit 739252bdfabc · 2021-07-19T11:11:40.000-07:00
ENH: expose make_norm_from_scale
diff --git a/doc/api/colors_api.rst b/doc/api/colors_api.rst
@@ -52,3 +52,4 @@ Functions
    is_color_like
    same_color
    get_named_colors_mapping
+   make_norm_from_scale
diff --git a/doc/api/next_api_changes/behavior/20405-JMK.rst b/doc/api/next_api_changes/behavior/20405-JMK.rst
@@ -0,0 +1,8 @@
+Make norm from scale now public
+===============================
+
+Downstream libraries can take advantage of `.colors.make_norm_from_scale` 
+to create a `~.colors.Normalize` subclass directly from an existing scale.  
+Usually norms have a scale, and the advantage of having a  `~.scale.ScaleBase` 
+attached to a norm is to provide a scale, and associated tick locators and 
+formatters, for the colorbar.
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -1415,13 +1415,14 @@ def __call__(self, value, clip=None):
         return super().__call__(value, clip=clip)
 
 
-def _make_norm_from_scale(scale_cls, base_norm_cls=None, *, init=None):
+def make_norm_from_scale(scale_cls, base_norm_cls=None, *, init=None):
     """
-    Decorator for building a `.Normalize` subclass from a `.Scale` subclass.
+    Decorator for building a `.Normalize` subclass from a `~.scale.ScaleBase`
+    subclass.
 
     After ::
 
-        @_make_norm_from_scale(scale_cls)
+        @make_norm_from_scale(scale_cls)
         class norm_cls(Normalize):
             ...
 
@@ -1436,7 +1437,7 @@ class norm_cls(Normalize):
     a dummy axis).
 
     If the *scale_cls* constructor takes additional parameters, then *init*
-    should be passed to `_make_norm_from_scale`.  It is a callable which is
+    should be passed to `make_norm_from_scale`.  It is a callable which is
     *only* used for its signature.  First, this signature will become the
     signature of *norm_cls*.  Second, the *norm_cls* constructor will bind the
     parameters passed to it using this signature, extract the bound *vmin*,
@@ -1446,7 +1447,7 @@ class norm_cls(Normalize):
     """
 
     if base_norm_cls is None:
-        return functools.partial(_make_norm_from_scale, scale_cls, init=init)
+        return functools.partial(make_norm_from_scale, scale_cls, init=init)
 
     if init is None:
         def init(vmin=None, vmax=None, clip=False): pass
@@ -1509,7 +1510,7 @@ def inverse(self, value):
     return Norm
 
 
-@_make_norm_from_scale(
+@make_norm_from_scale(
     scale.FuncScale,
     init=lambda functions, vmin=None, vmax=None, clip=False: None)
 class FuncNorm(Normalize):
@@ -1542,7 +1543,7 @@ def forward(values: array-like) -> array-like
     """
 
 
-@_make_norm_from_scale(functools.partial(scale.LogScale, nonpositive="mask"))
+@make_norm_from_scale(functools.partial(scale.LogScale, nonpositive="mask"))
 class LogNorm(Normalize):
     """Normalize a given value to the 0-1 range on a log scale."""
 
@@ -1555,7 +1556,7 @@ def autoscale_None(self, A):
         super().autoscale_None(np.ma.array(A, mask=(A <= 0)))
 
 
-@_make_norm_from_scale(
+@make_norm_from_scale(
     scale.SymmetricalLogScale,
     init=lambda linthresh, linscale=1., vmin=None, vmax=None, clip=False, *,
                 base=10: None)
