diff --git a/doc/api/next_api_changes/deprecations/21056-AL.rst b/doc/api/next_api_changes/deprecations/21056-AL.rst new file mode 100644 index 000000000000..1b169ae49d2b --- /dev/null +++ b/doc/api/next_api_changes/deprecations/21056-AL.rst @@ -0,0 +1,3 @@ +Calling ``MarkerStyle()`` with no arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +... is deprecated; use ``MarkerStyle("")`` to construct an empty marker style. diff --git a/lib/matplotlib/markers.py b/lib/matplotlib/markers.py index be1f81ca3b1e..43fabef2eb6c 100644 --- a/lib/matplotlib/markers.py +++ b/lib/matplotlib/markers.py @@ -63,9 +63,9 @@ rotated by ``angle``. ============================== ====== ========================================= -``None`` is the default which means 'nothing', however this table is -referred to from other docs for the valid inputs from marker inputs and in -those cases ``None`` still means 'default'. +``None`` also means 'nothing' when directly constructing a `.MarkerStyle`, but +note that there are other contexts where ``marker=None`` instead means "the +default marker" (e.g. :rc:`scatter.marker` for `.Axes.scatter`). Note that special symbols can be defined via the :doc:`STIX math font `, @@ -127,6 +127,7 @@ """ from collections.abc import Sized +import inspect import numpy as np @@ -216,14 +217,16 @@ class MarkerStyle: # TODO: Is this ever used as a non-constant? _point_size_reduction = 0.5 - def __init__(self, marker=None, fillstyle=None): + _unset = object() # For deprecation of MarkerStyle(). + + def __init__(self, marker=_unset, fillstyle=None): """ Parameters ---------- - marker : str, array-like, Path, MarkerStyle, or None, default: None + marker : str, array-like, Path, MarkerStyle, or None - Another instance of *MarkerStyle* copies the details of that ``marker``. - - *None* means no marker. + - *None* means no marker. This is the deprecated default. - For other possible marker values see the module docstring `matplotlib.markers`. @@ -232,8 +235,19 @@ def __init__(self, marker=None, fillstyle=None): """ self._marker_function = None self._set_fillstyle(fillstyle) + # Remove _unset and signature rewriting after deprecation elapses. + if marker is self._unset: + marker = "" + _api.warn_deprecated( + "3.6", message="Calling MarkerStyle() with no parameters is " + "deprecated since %(since)s; support will be removed " + "%(removal)s. Use MarkerStyle('') to construct an empty " + "MarkerStyle.") self._set_marker(marker) + __init__.__signature__ = inspect.signature( # Only for deprecation period. + lambda self, marker, fillstyle=None: None) + def _recache(self): if self._marker_function is None: return diff --git a/lib/matplotlib/tests/test_marker.py b/lib/matplotlib/tests/test_marker.py index f85d4ff467ef..5576faddd2cc 100644 --- a/lib/matplotlib/tests/test_marker.py +++ b/lib/matplotlib/tests/test_marker.py @@ -1,6 +1,7 @@ import numpy as np import matplotlib.pyplot as plt from matplotlib import markers +from matplotlib._api.deprecation import MatplotlibDeprecationWarning from matplotlib.path import Path from matplotlib.testing.decorators import check_figures_equal @@ -32,7 +33,6 @@ def test_marker_fillstyle(): (5, 0, 10), # a pentagon, rotated by 10 degrees (7, 1, 10), # a 7-pointed star, rotated by 10 degrees (5, 2, 10), # asterisk, rotated by 10 degrees - markers.MarkerStyle(), markers.MarkerStyle('o'), ]) def test_markers_valid(marker): @@ -40,6 +40,12 @@ def test_markers_valid(marker): markers.MarkerStyle(marker) +def test_deprecated_marker_noargs(): + with pytest.warns(MatplotlibDeprecationWarning): + ms = markers.MarkerStyle() + markers.MarkerStyle(ms) # No warning on copy. + + @pytest.mark.parametrize('marker', [ 'square', # arbitrary string np.array([[-0.5, 0, 1, 2, 3]]), # 1D array