[Doc]: Clarify default capstyle #21979

Activity

1. StefRe

   added

   Documentation

   on Dec 16, 2021
2. timhoffm commented on Dec 16, 2021

   

   timhoffm

   on Dec 16, 2021

   Member

   More actions

   If we mention the Line2D default, we should also mention the PathPatch default.

   I'm undecided whether that's still reasonable in the plot or whether we should discuss defaults in a dedicated section. I tend to go with the latter.

   Joinstyle is also different (#18597). While at it, it should be addressed in the same fashion.
3. StefRe commented on Dec 16, 2021

   

   StefRe

   on Dec 16, 2021

   ContributorAuthor

   More actions

   whether we should discuss defaults in a dedicated section

   maybe just document the default capstyle in set_capstyle:
   

   matplotlib/lib/matplotlib/patches.py

   Lines 473 to 475 in be35409

   	def set_capstyle(self, s):
   	"""
   	Set the `.CapStyle`.

   
   

   matplotlib/lib/matplotlib/collections.py

   Lines 632 to 634 in 092f833

   	def set_capstyle(self, cs):
   	"""
   	Set the `.CapStyle` for the collection (for all its elements).

   
   

   matplotlib/lib/matplotlib/lines.py

   Lines 1343 to 1346 in 092f833

   	def set_solid_capstyle(self, s):
   	"""
   	How to draw the end caps if the line is solid (not `~Line2D.is_dashed`)

   
   

   matplotlib/lib/matplotlib/lines.py

   Lines 1329 to 1331 in 092f833

   	def set_dash_capstyle(self, s):
   	"""
   	How to draw the end caps if the line is `~Line2D.is_dashed`.

   In addition to that we could determine the default capstyle programmatically in the demo, so that it's always up-to-date, even if one forgets about the demo when changing the default sometime in the future:

   import matplotlib as mpl
   
   fig = mpl.pyplot.figure(figsize=(4, 1.2))
   ax = fig.add_axes([0.1, 0, 0.8, 0.8])
   ax.set_axis_off()
   ax.set(title='Cap style', ylim=(-.5, 1.5))
   
   default_l2d = mpl.lines.Line2D([], []).get_solid_capstyle()
   default_pp = mpl.patches.PathPatch(mpl.path.Path([[0, 0], [0, 0]])).get_capstyle().name
   
   for x, style in enumerate(['butt', 'round', 'projecting']):
       if style == default_l2d == default_pp:
           default = '(default)'
       elif style == default_l2d:
           default = '(default for Line2D)'
       elif style == default_pp:
           default = '(default for PathPatch)'
       else:
           default = ''
       ax.text(x+0.25, 0.85, f'{style}\n{default}'.strip(), ha='center', va='center')
       xx = [x, x+0.5]
       yy = [0, 0]
       ax.plot(xx, yy, lw=12, color='tab:blue', solid_capstyle=style)
       ax.plot(xx, yy, lw=1, color='black')
       ax.plot(xx, yy, 'o', color='tab:red', markersize=3) 
   

   

   (the same for joinstyle)
4. StefRe commented on Dec 16, 2021

   

   StefRe

   on Dec 16, 2021

   Last edited by StefRe

   ContributorAuthor

   More actions

   While making the example I noticed the following inconsistency:
   

   matplotlib/lib/matplotlib/patches.py

   Lines 485 to 487 in be35409

   	def get_capstyle(self):
   	"""Return the capstyle."""
   	return self._capstyle

   and
   

   matplotlib/lib/matplotlib/markers.py

   Lines 327 to 328 in f6e0ee4

   	def get_capstyle(self):
   	return self._capstyle

   
   return a CapStyle object while the other 3 methods return a string (i.e. ...capstyle.name).

   Is this something a separate issue should be opened for? (at least it should be documented which type is returned in each case).
5. StefRe commented on Dec 17, 2021

   

   StefRe

   on Dec 17, 2021

   ContributorAuthor

   More actions

   There's another exception (which is, however, correctly documented #13647):
   

   matplotlib/lib/matplotlib/patches.py

   Lines 4277 to 4282 in 1535cdc

   	In contrast to other patches, the default ``capstyle`` and
   	``joinstyle`` for `FancyArrowPatch` are set to ``"round"``.
   	"""
   	# Traditionally, the cap- and joinstyle for FancyArrowPatch are round
   	kwargs.setdefault("joinstyle", JoinStyle.round)
   	kwargs.setdefault("capstyle", CapStyle.round)
6. StefRe commented on Dec 17, 2021

   

   StefRe

   on Dec 17, 2021

   ContributorAuthor

   More actions

   And the last one:
   

   matplotlib/lib/matplotlib/markers.py

   Line 288 in f6e0ee4

   self._capstyle = self._user_capstyle or CapStyle.butt

   Also not documented:
   

   matplotlib/lib/matplotlib/markers.py

   Lines 249 to 250 in f6e0ee4

   	capstyle : CapStyle, default: None
   	Cap style that will override the default cap style of the marker.
7. StefRe commented on Dec 17, 2021

   

   StefRe

   on Dec 17, 2021

   ContributorAuthor

   More actions

   In total we seem to have the following defaults (hope that I didn't overlook anything) :

   • 'projecting' for Line2D
   • 'round' for FancyArrowPatch
   • 'butt' for all other

   So maybe it's indeed not so good an idea to give the defaults in the demo but rather document them with their classes.

   👍React with 👍1Reacted by Tim Hoffmann
8. timhoffm

   closed this as completedin #22053on Jan 11, 2022
9. QuLogic

   added this to the v3.5.2 milestone on Jan 12, 2022