yashuatla · yashuatla · May 18, 2025 · May 26, 2025 · May 31, 2025 · May 31, 2025
diff --git a/doc/api/bezier_api.rst b/doc/api/bezier_api.rst
@@ -5,4 +5,5 @@
 .. automodule:: matplotlib.bezier
    :members:
    :undoc-members:
+   :special-members: __call__
    :show-inheritance:
diff --git a/doc/api/next_api_changes/deprecations/30070-OG.rst b/doc/api/next_api_changes/deprecations/30070-OG.rst
@@ -0,0 +1,4 @@
+``BezierSegment.point_at_t``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+... is deprecated. Instead, it is possible to call the BezierSegment with an argument.
diff --git a/doc/api/next_api_changes/removals/30004-DS.rst b/doc/api/next_api_changes/removals/30004-DS.rst
@@ -0,0 +1,10 @@
+``apply_theta_transforms`` option in ``PolarTransform``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Applying theta transforms in `~matplotlib.projections.polar.PolarTransform` and
+`~matplotlib.projections.polar.InvertedPolarTransform` has been removed, and
+the ``apply_theta_transforms`` keyword argument removed from both classes.
+
+If you need to retain the behaviour where theta values
+are transformed, chain the ``PolarTransform`` with a `~matplotlib.transforms.Affine2D`
+transform that performs the theta shift and/or sign shift.
diff --git a/doc/api/next_api_changes/removals/xxxxxx-DS.rst b/doc/api/next_api_changes/removals/xxxxxx-DS.rst
diff --git a/doc/devel/document.rst b/doc/devel/document.rst
@@ -537,6 +537,10 @@ understandable by humans. If the possible types are too complex use a
 simplification for the type description and explain the type more
 precisely in the text.
 
+We do not use formal type annotation syntax for type descriptions in
+docstrings; e.g. we use ``list of str`` rather than  ``list[str]``; we
+use ``int or str`` rather than ``int | str`` or ``Union[int, str]``.
+
 Generally, the `numpydoc docstring guide`_ conventions apply. The following
 rules expand on them where the numpydoc conventions are not specific.
 

diff --git a/galleries/examples/axisartist/demo_axis_direction.py b/galleries/examples/axisartist/demo_axis_direction.py
@@ -22,7 +22,7 @@ def setup_axes(fig, rect):
     grid_helper = GridHelperCurveLinear(
         (
             Affine2D().scale(np.pi/180., 1.) +
-            PolarAxes.PolarTransform(apply_theta_transforms=False)
+            PolarAxes.PolarTransform()
         ),
         extreme_finder=angle_helper.ExtremeFinderCycle(
             20, 20,

diff --git a/galleries/examples/axisartist/demo_curvelinear_grid.py b/galleries/examples/axisartist/demo_curvelinear_grid.py
@@ -54,8 +54,7 @@ def curvelinear_test2(fig):
 
     # PolarAxes.PolarTransform takes radian. However, we want our coordinate
     # system in degree
-    tr = Affine2D().scale(np.pi/180, 1) + PolarAxes.PolarTransform(
-        apply_theta_transforms=False)
+    tr = Affine2D().scale(np.pi/180, 1) + PolarAxes.PolarTransform()
     # Polar projection, which involves cycle, and also has limits in
     # its coordinates, needs a special method to find the extremes
     # (min, max of the coordinate within the view).

diff --git a/galleries/examples/axisartist/demo_floating_axes.py b/galleries/examples/axisartist/demo_floating_axes.py
@@ -54,7 +54,7 @@ def setup_axes2(fig, rect):
     With custom locator and formatter.
     Note that the extreme values are swapped.
     """
-    tr = PolarAxes.PolarTransform(apply_theta_transforms=False)
+    tr = PolarAxes.PolarTransform()
-    tr = PolarAxes.PolarTransform()
+    tr = PolarAxes.PolarTransform(apply_theta_transforms=False)
-    tr = PolarAxes.PolarTransform()
+    tr = PolarAxes.PolarTransform(apply_theta_transforms=False)
 
     pi = np.pi
     angle_ticks = [(0, r"$0$"),
@@ -99,8 +99,7 @@ def setup_axes3(fig, rect):
     # scale degree to radians
     tr_scale = Affine2D().scale(np.pi/180., 1.)
 
-    tr = tr_rotate + tr_scale + PolarAxes.PolarTransform(
-        apply_theta_transforms=False)
+    tr = tr_rotate + tr_scale + PolarAxes.PolarTransform()
 
     grid_locator1 = angle_helper.LocatorHMS(4)
     tick_formatter1 = angle_helper.FormatterHMS()

diff --git a/galleries/examples/axisartist/demo_floating_axis.py b/galleries/examples/axisartist/demo_floating_axis.py
@@ -22,8 +22,7 @@
 def curvelinear_test2(fig):
     """Polar projection, but in a rectangular box."""
     # see demo_curvelinear_grid.py for details
-    tr = Affine2D().scale(np.pi / 180., 1.) + PolarAxes.PolarTransform(
-        apply_theta_transforms=False)
+    tr = Affine2D().scale(np.pi / 180., 1.) + PolarAxes.PolarTransform()
 
     extreme_finder = angle_helper.ExtremeFinderCycle(20,
                                                      20,

diff --git a/galleries/examples/axisartist/simple_axis_pad.py b/galleries/examples/axisartist/simple_axis_pad.py
@@ -21,8 +21,7 @@ def setup_axes(fig, rect):
     """Polar projection, but in a rectangular box."""
 
     # see demo_curvelinear_grid.py for details
-    tr = Affine2D().scale(np.pi/180., 1.) + PolarAxes.PolarTransform(
-        apply_theta_transforms=False)
+    tr = Affine2D().scale(np.pi/180., 1.) + PolarAxes.PolarTransform()
 
     extreme_finder = angle_helper.ExtremeFinderCycle(20, 20,
                                                      lon_cycle=360,

diff --git a/galleries/examples/images_contours_and_fields/multi_image.py b/galleries/examples/images_contours_and_fields/multi_image.py
@@ -11,15 +11,17 @@
 value *x* in the image).
 
 If we want one colorbar to be representative for multiple images, we have
-to explicitly ensure consistent data coloring by using the same data
-normalization for all the images. We ensure this by explicitly creating a
-``norm`` object that we pass to all the image plotting methods.
+to explicitly ensure consistent data coloring by using the same
+data-to-color pipeline for all the images. We ensure this by explicitly
+creating a `matplotlib.colorizer.Colorizer` object that we pass to all
+the image plotting methods.
 """
 
 import matplotlib.pyplot as plt
 import numpy as np
 
-from matplotlib import colors
+import matplotlib.colorizer as mcolorizer
+import matplotlib.colors as mcolors
 
 np.random.seed(19680801)
 
@@ -31,12 +33,13 @@
 fig, axs = plt.subplots(2, 2)
 fig.suptitle('Multiple images')
 
-# create a single norm to be shared across all images
-norm = colors.Normalize(vmin=np.min(datasets), vmax=np.max(datasets))
+# create a colorizer with a predefined norm to be shared across all images
+norm = mcolors.Normalize(vmin=np.min(datasets), vmax=np.max(datasets))
+colorizer = mcolorizer.Colorizer(norm=norm)
 
 images = []
 for ax, data in zip(axs.flat, datasets):
-    images.append(ax.imshow(data, norm=norm))
+    images.append(ax.imshow(data, colorizer=colorizer))
 
 fig.colorbar(images[0], ax=axs, orientation='horizontal', fraction=.1)
 
@@ -45,30 +48,10 @@
 # %%
 # The colors are now kept consistent across all images when changing the
 # scaling, e.g. through zooming in the colorbar or via the "edit axis,
-# curves and images parameters" GUI of the Qt backend. This is sufficient
-# for most practical use cases.
-#
-# Advanced: Additionally sync the colormap
-# ----------------------------------------
-#
-# Sharing a common norm object guarantees synchronized scaling because scale
-# changes modify the norm object in-place and thus propagate to all images
-# that use this norm. This approach does not help with synchronizing colormaps
-# because changing the colormap of an image (e.g. through the "edit axis,
-# curves and images parameters" GUI of the Qt backend) results in the image
-# referencing the new colormap object. Thus, the other images are not updated.
-#
-# To update the other images, sync the
-# colormaps using the following code::
-#
-#     def sync_cmaps(changed_image):
-#         for im in images:
-#             if changed_image.get_cmap() != im.get_cmap():
-#                 im.set_cmap(changed_image.get_cmap())
-#
-#     for im in images:
-#         im.callbacks.connect('changed', sync_cmaps)
-#
+# curves and images parameters" GUI of the Qt backend. Additionally,
+# if the colormap of the colorizer is changed, (e.g. through the "edit
+# axis, curves and images parameters" GUI of the Qt backend) this change
+# propagates to the other plots and the colorbar.
 #
 # .. admonition:: References
 #
@@ -77,6 +60,5 @@
 #
 #    - `matplotlib.axes.Axes.imshow` / `matplotlib.pyplot.imshow`
 #    - `matplotlib.figure.Figure.colorbar` / `matplotlib.pyplot.colorbar`
+#    - `matplotlib.colorizer.Colorizer`
 #    - `matplotlib.colors.Normalize`
-#    - `matplotlib.cm.ScalarMappable.set_cmap`
-#    - `matplotlib.cbook.CallbackRegistry.connect`
diff --git a/galleries/users_explain/colors/colorbar_only.py b/galleries/users_explain/colors/colorbar_only.py
@@ -8,10 +8,12 @@
 This tutorial shows how to build and customize standalone colorbars, i.e.
 without an attached plot.
 
-A `~.Figure.colorbar` needs a "mappable" (`matplotlib.cm.ScalarMappable`)
-object (typically, an image) which indicates the colormap and the norm to be
-used.  In order to create a colorbar without an attached image, one can instead
-use a `.ScalarMappable` with no associated data.
+A `~.Figure.colorbar` requires a `matplotlib.colorizer.ColorizingArtist` which
+contains a `matplotlib.colorizer.Colorizer` that holds the data-to-color pipeline
+(norm and colormap). To create a colorbar without an attached plot one can
+directly instantiate the base class `.ColorizingArtist`, which has no associated
+data.
+
 """
 
 import matplotlib.pyplot as plt
@@ -23,17 +25,21 @@
 # -------------------------
 # Here, we create a basic continuous colorbar with ticks and labels.
 #
-# The arguments to the `~.Figure.colorbar` call are the `.ScalarMappable`
-# (constructed using the *norm* and *cmap* arguments), the axes where the
-# colorbar should be drawn, and the colorbar's orientation.
+# The arguments to the `~.Figure.colorbar` call are a `.ColorizingArtist`,
+# the axes where the colorbar should be drawn, and the colorbar's orientation.
+# To crate a `.ColorizingArtist` one must first make `.Colorizer` that holds the
+# desired *norm* and *cmap*.
+#
 #
 # For more information see the `~matplotlib.colorbar` API.
 
 fig, ax = plt.subplots(figsize=(6, 1), layout='constrained')
 
 norm = mpl.colors.Normalize(vmin=5, vmax=10)
 
-fig.colorbar(mpl.cm.ScalarMappable(norm=norm, cmap="cool"),
+colorizer = mpl.colorizer.Colorizer(norm=norm, cmap="cool")
+
+fig.colorbar(mpl.colorizer.ColorizingArtist(colorizer),
              cax=ax, orientation='horizontal', label='Some Units')
 
 # %%
@@ -47,7 +53,9 @@
 
 fig, ax = plt.subplots(layout='constrained')
 
-fig.colorbar(mpl.cm.ScalarMappable(norm=mpl.colors.Normalize(0, 1), cmap='magma'),
+colorizer = mpl.colorizer.Colorizer(norm=mpl.colors.Normalize(0, 1), cmap='magma')
+
+fig.colorbar(mpl.colorizer.ColorizingArtist(colorizer),
              ax=ax, orientation='vertical', label='a colorbar label')
 
 # %%
@@ -65,7 +73,9 @@
 bounds = [-1, 2, 5, 7, 12, 15]
 norm = mpl.colors.BoundaryNorm(bounds, cmap.N, extend='both')
 
-fig.colorbar(mpl.cm.ScalarMappable(norm=norm, cmap="viridis"),
+colorizer = mpl.colorizer.Colorizer(norm=norm, cmap='viridis')
+
+fig.colorbar(mpl.colorizer.ColorizingArtist(colorizer),
              cax=ax, orientation='horizontal',
              label="Discrete intervals with extend='both' keyword")
 
@@ -94,8 +104,10 @@
 bounds = [1, 2, 4, 7, 8]
 norm = mpl.colors.BoundaryNorm(bounds, cmap.N)
 
+colorizer = mpl.colorizer.Colorizer(norm=norm, cmap=cmap)
+
 fig.colorbar(
-    mpl.cm.ScalarMappable(cmap=cmap, norm=norm),
+    mpl.colorizer.ColorizingArtist(colorizer),
     cax=ax, orientation='horizontal',
     extend='both',
     spacing='proportional',
@@ -116,8 +128,10 @@
 bounds = [-1.0, -0.5, 0.0, 0.5, 1.0]
 norm = mpl.colors.BoundaryNorm(bounds, cmap.N)
 
+colorizer = mpl.colorizer.Colorizer(norm=norm, cmap=cmap)
+
 fig.colorbar(
-    mpl.cm.ScalarMappable(cmap=cmap, norm=norm),
+    mpl.colorizer.ColorizingArtist(colorizer),
     cax=ax, orientation='horizontal',
     extend='both', extendfrac='auto',
     spacing='uniform',