Skip to content

Commit 1ffad43

Browse files
timhoffmtimhoffm
committed
DOC: Clarify and unify set_linestyle
Closes matplotlib#26784.
1 parent fdf8995 commit 1ffad43

File tree

4 files changed

+108
-54
lines changed

4 files changed

+108
-54
lines changed

‎lib/matplotlib/collections.py‎

Lines changed: 33 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -670,27 +670,43 @@ def set_linestyle(self, ls):
670670
"""
671671
Set the linestyle(s) for the collection.
672672
673-
=========================== =================
674-
linestyle description
675-
=========================== =================
676-
``'-'`` or ``'solid'`` solid line
677-
``'--'`` or ``'dashed'`` dashed line
678-
``'-.'`` or ``'dashdot'`` dash-dotted line
679-
``':'`` or ``'dotted'`` dotted line
680-
=========================== =================
673+
Parameters
674+
----------
675+
ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq) or list thereof
676+
If as list, the individual elements are assigned to the elements of the
677+
collection.
681678
682-
Alternatively a dash tuple of the following form can be provided::
679+
Possible values:
683680
684-
(offset, onoffseq),
681+
- A string:
685682
686-
where ``onoffseq`` is an even length tuple of on and off ink in points.
683+
======================================================= ================
684+
linestyle description
685+
======================================================= ================
686+
``'-'`` or ``'solid'`` solid line
687+
``'--'`` or ``'dashed'`` dashed line
688+
``'-.'`` or ``'dashdot'`` dash-dotted line
689+
``':'`` or ``'dotted'`` dotted line
690+
``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``) draw nothing
691+
======================================================= ================
687692
688-
Parameters
689-
----------
690-
ls : str or tuple or list thereof
691-
Valid values for individual linestyles include {'-', '--', '-.',
692-
':', '', (offset, on-off-seq)}. See `.Line2D.set_linestyle` for a
693-
complete description.
693+
- A tuple describing the start position and lengths of dashes and spaxces:
694+
695+
(offset, onoffseq)
696+
697+
where
698+
699+
- *offset* is a float specifying the offset (in points); i.e. how much
700+
is the dash pattern shifted.
701+
- *onoffseq* is a sequence of on and off ink in points. There can be
702+
arbitrary many pairs of on and off values.
703+
704+
Example: The tuple ``(0, (10, 5, 1, 5))`` means that the pattern starts
705+
at the beginning of the line. It draws a 10 point long dash,
706+
then a 5 point long space, then a 1 point long dash, followed by a 5 point
707+
long space, and then the pattern repeats.
708+
709+
For examples see :doc:`/gallery/lines_bars_and_markers/linestyles`.
694710
"""
695711
# get the list of raw 'unscaled' dash patterns
696712
self._us_linestyles = mlines._get_dash_patterns(ls)

‎lib/matplotlib/inset.py‎

Lines changed: 30 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -126,26 +126,40 @@ def set_linestyle(self, ls):
126126
"""
127127
Set the linestyle of the rectangle and the connectors.
128128
129-
======================================================= ================
130-
linestyle description
131-
======================================================= ================
132-
``'-'`` or ``'solid'`` solid line
133-
``'--'`` or ``'dashed'`` dashed line
134-
``'-.'`` or ``'dashdot'`` dash-dotted line
135-
``':'`` or ``'dotted'`` dotted line
136-
``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``) draw nothing
137-
======================================================= ================
129+
Parameters
130+
----------
131+
ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq)
132+
Possible values:
138133
139-
Alternatively a dash tuple of the following form can be provided::
134+
- A string:
140135
141-
(offset, onoffseq)
136+
======================================================= ================
137+
linestyle description
138+
======================================================= ================
139+
``'-'`` or ``'solid'`` solid line
140+
``'--'`` or ``'dashed'`` dashed line
141+
``'-.'`` or ``'dashdot'`` dash-dotted line
142+
``':'`` or ``'dotted'`` dotted line
143+
``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``) draw nothing
144+
======================================================= ================
142145
143-
where ``onoffseq`` is an even length tuple of on and off ink in points.
146+
- A tuple describing the start position and lengths of dashes and spaces:
144147
145-
Parameters
146-
----------
147-
ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
148-
The line style.
148+
(offset, onoffseq)
149+
150+
where
151+
152+
- *offset* is a float specifying the offset (in points); i.e. how much
153+
is the dash pattern shifted.
154+
- *onoffseq* is a sequence of on and off ink in points. There can be
155+
arbitrary many pairs of on and off values.
156+
157+
Example: The tuple ``(0, (10, 5, 1, 5))`` means that the pattern starts
158+
at the beginning of the line. It draws a 10 point long dash,
159+
then a 5 point long space, then a 1 point long dash, followed by a 5 point
160+
long space, and then the pattern repeats.
161+
162+
For examples see :doc:`/gallery/lines_bars_and_markers/linestyles`.
149163
"""
150164
self._shared_setter('linestyle', ls)
151165

‎lib/matplotlib/lines.py‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1149,7 +1149,7 @@ def set_linestyle(self, ls):
11491149
11501150
Parameters
11511151
----------
1152-
ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
1152+
ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq)
11531153
Possible values:
11541154
11551155
- A string:
@@ -1164,13 +1164,23 @@ def set_linestyle(self, ls):
11641164
``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``) draw nothing
11651165
======================================================= ================
11661166
1167-
- Alternatively a dash tuple of the following form can be
1168-
provided::
1167+
- A tuple describing the start position and lengths of dashes and spaces:
11691168
11701169
(offset, onoffseq)
11711170
1172-
where ``onoffseq`` is an even length tuple of on and off ink
1173-
in points. See also :meth:`set_dashes`.
1171+
where
1172+
1173+
- *offset* is a float specifying the offset (in points); i.e. how much
1174+
is the dash pattern shifted.
1175+
- *onoffseq* is a sequence of on and off ink in points. There can be
1176+
arbitrary many pairs of on and off values.
1177+
1178+
Example: The tuple ``(0, (10, 5, 1, 5))`` means that the pattern starts
1179+
at the beginning of the line. It draws a 10 point long dash,
1180+
then a 5 point long space, then a 1 point long dash, followed by a 5 point
1181+
long space, and then the pattern repeats.
1182+
1183+
See also :meth:`set_dashes`.
11741184
11751185
For examples see :doc:`/gallery/lines_bars_and_markers/linestyles`.
11761186
"""

‎lib/matplotlib/patches.py‎

Lines changed: 30 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -468,26 +468,40 @@ def set_linestyle(self, ls):
468468
"""
469469
Set the patch linestyle.
470470
471-
======================================================= ================
472-
linestyle description
473-
======================================================= ================
474-
``'-'`` or ``'solid'`` solid line
475-
``'--'`` or ``'dashed'`` dashed line
476-
``'-.'`` or ``'dashdot'`` dash-dotted line
477-
``':'`` or ``'dotted'`` dotted line
478-
``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``) draw nothing
479-
======================================================= ================
471+
Parameters
472+
----------
473+
ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq)
474+
Possible values:
480475
481-
Alternatively a dash tuple of the following form can be provided::
476+
- A string:
482477
483-
(offset, onoffseq)
478+
======================================================= ================
479+
linestyle description
480+
======================================================= ================
481+
``'-'`` or ``'solid'`` solid line
482+
``'--'`` or ``'dashed'`` dashed line
483+
``'-.'`` or ``'dashdot'`` dash-dotted line
484+
``':'`` or ``'dotted'`` dotted line
485+
``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``) draw nothing
486+
======================================================= ================
484487
485-
where ``onoffseq`` is an even length tuple of on and off ink in points.
488+
- A tuple describing the start position and lengths of dashes and spaces:
486489
487-
Parameters
488-
----------
489-
ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
490-
The line style.
490+
(offset, onoffseq)
491+
492+
where
493+
494+
- *offset* is a float specifying the offset (in points); i.e. how much
495+
is the dash pattern shifted.
496+
- *onoffseq* is a sequence of on and off ink in points. There can be
497+
arbitrary many pairs of on and off values.
498+
499+
Example: The tuple ``(0, (10, 5, 1, 5))`` means that the pattern starts
500+
at the beginning of the line. It draws a 10 point long dash,
501+
then a 5 point long space, then a 1 point long dash, followed by a 5 point
502+
long space, and then the pattern repeats.
503+
504+
For examples see :doc:`/gallery/lines_bars_and_markers/linestyles`.
491505
"""
492506
if ls is None:
493507
ls = "solid"

0 commit comments

Comments
 (0)