matplotlib · tacaswell · May 14, 2015 · Jul 15, 2014 · Jul 29, 2014 · Nov 8, 2014
diff --git a/doc/api/api_changes/2014-11-11_ELF_split_lsmapper.rst b/doc/api/api_changes/2014-11-11_ELF_split_lsmapper.rst
@@ -0,0 +1,9 @@
+Split `matplotlib.cbook.ls_mapper` in two
+`````````````````````````````````````````
+
+The `matplotlib.cbook.ls_mapper` dictionary is split into two now to
+distinguish between qualified linestyle used by backends and
+unqualified ones. `ls_mapper` now maps from the short symbols
+(e.g. `"--"`) to qualified names (`"solid"`). The new ls_mapper_r is
+the reversed mapping.
+
diff --git a/doc/users/whats_new/linestyles.rst b/doc/users/whats_new/linestyles.rst
@@ -0,0 +1,8 @@
+Mostly unified linestyles for Lines, Patches and Collections
+````````````````````````````````````````````````````````````
+
+The handling of linestyles for Lines, Patches and Collections has been
+unified.  Now they all support defining linestyles with short symbols,
+like `"--"`, as well as with full names, like `"dashed"`. Also the
+definition using a dash pattern (`(0., [3., 3.])`) is supported for all
+methods using Lines, Patches or Collections.
diff --git a/lib/matplotlib/cbook.py b/lib/matplotlib/cbook.py
@@ -2134,7 +2134,10 @@ def unmasked_index_ranges(mask, compressed=True):
                (':', 'dotted')]
 
 ls_mapper = dict(_linestyles)
-ls_mapper.update([(ls[1], ls[0]) for ls in _linestyles])
+# The ls_mapper maps short codes for line style to their full name used
+# by backends
+# The reverse mapper is for mapping full names to short ones
+ls_mapper_r = dict([(ls[1], ls[0]) for ls in _linestyles])
 
 
 def align_iterators(func, *iterables):

diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
@@ -482,27 +482,43 @@ def set_linestyle(self, ls):
         """
         Set the linestyle(s) for the collection.
 
-        ACCEPTS: ['solid' | 'dashed', 'dashdot', 'dotted' |
-        (offset, on-off-dash-seq) ]
+        ===========================   =================
+        linestyle                     description
+        ===========================   =================
+        ``'-'`` or ``'solid'``        solid line
+        ``'--'`` or  ``'dashed'``     dashed line
+        ``'-.'`` or  ``'dash_dot'``   dash-dotted line
+        ``':'`` or ``'dotted'``       dotted line
+        ===========================   =================
+
+        Alternatively a dash tuple of the following form can be provided::
+
+            (offset, onoffseq),
+
+        where ``onoffseq`` is an even length tuple of on and off ink
+        in points.
+
+        Parameters
+        ----------
+        ls : { '-',  '--', '-.', ':'} and more see description
+            The line style.
         """
         try:
             dashd = backend_bases.GraphicsContextBase.dashd
             if cbook.is_string_like(ls):
+                ls = cbook.ls_mapper.get(ls, ls)
                 if ls in dashd:
                     dashes = [dashd[ls]]
-                elif ls in cbook.ls_mapper:
-                    dashes = [dashd[cbook.ls_mapper[ls]]]
                 else:
                     raise ValueError()
             elif cbook.iterable(ls):
                 try:
                     dashes = []
                     for x in ls:
                         if cbook.is_string_like(x):
+                            x = cbook.ls_mapper.get(x, x)
                             if x in dashd:
                                 dashes.append(dashd[x])
-                            elif x in cbook.ls_mapper:
-                                dashes.append(dashd[cbook.ls_mapper[x]])
                             else:
                                 raise ValueError()
                         elif cbook.iterable(x) and len(x) == 2:
@@ -511,7 +527,7 @@ def set_linestyle(self, ls):
                             raise ValueError()
                 except ValueError:
                     if len(ls) == 2:
-                        dashes = ls
+                        dashes = [ls]
                     else:
                         raise ValueError()
             else:

diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py
@@ -16,7 +16,7 @@
 from matplotlib import verbose
 from . import artist
 from .artist import Artist
-from .cbook import iterable, is_string_like, is_numlike, ls_mapper
+from .cbook import iterable, is_string_like, is_numlike, ls_mapper_r
 from .colors import colorConverter
 from .path import Path
 from .transforms import Bbox, TransformedPath, IdentityTransform
@@ -921,55 +921,74 @@ def set_linewidth(self, w):
         """
         self._linewidth = w
 
-    def set_linestyle(self, linestyle):
+    def set_linestyle(self, ls):
         """
-        Set the linestyle of the line (also accepts drawstyles)
+        Set the linestyle of the line (also accepts drawstyles,
+        e.g., ``'steps--'``)
 
 
-        ================    =================
-        linestyle           description
-        ================    =================
-        ``'-'``             solid
-        ``'--'``            dashed
-        ``'-.'``            dash_dot
-        ``':'``             dotted
-        ``'None'``          draw nothing
-        ``' '``             draw nothing
-        ``''``              draw nothing
-        ================    =================
+        ===========================   =================
+        linestyle                     description
+        ===========================   =================
+        ``'-'`` or ``'solid'``        solid line
+        ``'--'`` or  ``'dashed'``     dashed line
+        ``'-.'`` or  ``'dash_dot'``   dash-dotted line
+        ``':'`` or ``'dotted'``       dotted line
+        ``'None'``                    draw nothing
+        ``' '``                       draw nothing
+        ``''``                        draw nothing
+        ===========================   =================
 
         'steps' is equivalent to 'steps-pre' and is maintained for
         backward-compatibility.
 
+        Alternatively a dash tuple of the following form can be provided::
+
+            (offset, onoffseq),
+
+        where ``onoffseq`` is an even length tuple of on and off ink
+        in points.
+
         .. seealso::
 
             :meth:`set_drawstyle`
                To set the drawing style (stepping) of the plot.
 
-        ACCEPTS: [``'-'`` | ``'--'`` | ``'-.'`` | ``':'`` | ``'None'`` |
-                  ``' '`` | ``''``]
-
-        and any drawstyle in combination with a linestyle, e.g., ``'steps--'``.
+        Parameters
+        ----------
+        ls : { '-',  '--', '-.', ':'} and more see description
+            The line style.
         """
+        if not is_string_like(ls):
+            if len(ls) != 2:
+                raise ValueError()
+
+            self.set_dashes(ls[1])
+            self._linestyle = "--"
+            return
 
         for ds in self.drawStyleKeys:  # long names are first in the list
-            if linestyle.startswith(ds):
+            if ls.startswith(ds):
                 self.set_drawstyle(ds)
-                if len(linestyle) > len(ds):
-                    linestyle = linestyle[len(ds):]
+                if len(ls) > len(ds):
+                    ls = ls[len(ds):]
                 else:
-                    linestyle = '-'
+                    ls = '-'
                 break
 
-        if linestyle not in self._lineStyles:
-            if linestyle in ls_mapper:
-                linestyle = ls_mapper[linestyle]
-            else:
-                verbose.report('Unrecognized line style %s, %s' %
-                               (linestyle, type(linestyle)))
-        if linestyle in [' ', '']:
-            linestyle = 'None'
-        self._linestyle = linestyle
+        if ls in [' ', '', 'none']:
+            ls = 'None'
+
+        if ls not in self._lineStyles:
+            try:
+                ls = ls_mapper_r[ls]
+            except KeyError:
+                raise ValueError(("You passed in an invalid linestyle, "
+                                  "`{}`.  See "
+                                  "docs of Line2D.set_linestyle for "
+                                  "valid values.").format(ls))
+
+        self._linestyle = ls
 
     @docstring.dedent_interpd
     def set_marker(self, marker):

diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -344,10 +344,31 @@ def set_linestyle(self, ls):
         """
         Set the patch linestyle
 
-        ACCEPTS: ['solid' | 'dashed' | 'dashdot' | 'dotted']
+        ===========================   =================
+        linestyle                     description
+        ===========================   =================
+        ``'-'`` or ``'solid'``        solid line
+        ``'--'`` or  ``'dashed'``     dashed line
+        ``'-.'`` or  ``'dash_dot'``   dash-dotted line
+        ``':'`` or ``'dotted'``       dotted line
+        ===========================   =================
+
+        Alternatively a dash tuple of the following form can be provided::
+
+            (offset, onoffseq),
+
+        where ``onoffseq`` is an even length tuple of on and off ink
+        in points.
+
+        Parameters
+        ----------
+        ls : { '-',  '--', '-.', ':'} and more see description
+            The line style.
         """
         if ls is None:
             ls = "solid"
+
+        ls = cbook.ls_mapper.get(ls, ls)
         self._linestyle = ls
 
     def set_ls(self, ls):

diff --git a/lib/matplotlib/tests/baseline_images/test_collections/EventCollection_plot__set_ls_dash.pdf b/lib/matplotlib/tests/baseline_images/test_collections/EventCollection_plot__set_ls_dash.pdf
diff --git a/...ib/tests/baseline_images/test_collections/EventCollection_plot__set_ls_dash.png b/...ib/tests/baseline_images/test_collections/EventCollection_plot__set_ls_dash.png