matplotlib#2899 almost final changes for adding wedge and text kwargs…

… to pie. needs feedback on generated pyplot

CHANGELOG

@@ -1,3 +1,7 @@
+2014-03-22 Added the keyword arguments wedgeprops and textprops to pie.
+           Users can control the wedge and text properties of the pie
+           in more detail, if they choose.
+
 2014-03-17 Bug was fixed in append_axes from the AxesDivider class would not
            append axes in the right location with respect to the reference
            locator axes

doc/users/whats_new.rst

@@ -131,6 +131,14 @@ specifically the Skew-T used in meteorology.
 
 .. plot:: mpl_examples/api/skewt.py
 
+Support for specifying properties of wedge and text in pie charts.
+``````````````````````````````````````````````````````````````
+Added the `kwargs` 'wedgeprops' and 'textprops' to :func:`~matplotlib.Axes.pie`
+to accept properties for wedge and text objects in a pie. For example, one can
+specify wedgeprops = {'linewidth':3} to specify the width of the borders of
+the wedges in the pie. For more properties that the user can specify, look at
+the docs for the wedge and text objects.
+
 
 Date handling
 -------------

lib/matplotlib/axes/_axes.py

@@ -2337,7 +2337,7 @@ def stem(self, *args, **kwargs):
     def pie(self, x, explode=None, labels=None, colors=None,
             autopct=None, pctdistance=0.6, shadow=False, labeldistance=1.1,
             startangle=None, radius=None, counterclock=True,
-            **kwargs):
+            wedgeprops=None, textprops=None):
         r"""
         Plot a pie chart.
 
@@ -2347,7 +2347,7 @@ def pie(self, x, explode=None, labels=None, colors=None,
               colors=('b', 'g', 'r', 'c', 'm', 'y', 'k', 'w'),
               autopct=None, pctdistance=0.6, shadow=False,
               labeldistance=1.1, startangle=None, radius=None,
-              wedgeargs={'linewidth':None}, textargs={},
+              counterclock=True, wedgeprops=None, textprops=None,
               )
 
         Make a pie chart of array *x*.  The fractional area of each
@@ -2396,6 +2396,15 @@ def pie(self, x, explode=None, labels=None, colors=None,
           *counterclock*: [ *False* | *True* ]
             Specify fractions direction, clockwise or counterclockwise.
 
+          *wedgeprops*: [ *None* | dict of key value pairs ]
+            Dict of arguments passed to the wedge objects making the pie.
+            For example, you can pass in wedgeprops = { 'linewidth' : 3 }
+            to set the width of the wedge border lines equal to 3.
+            For more details, look at the doc/arguments of the wedge object.
+
+          *textprops*: [ *None* | dict of key value pairs ]
+            Dict of arguments to pass to the text objects.
+
         The pie chart will probably look best if the figure and axes are
         square, or the Axes aspect is equal.  e.g.::
 
@@ -2448,8 +2457,8 @@ def pie(self, x, explode=None, labels=None, colors=None,
         else:
             theta1 = startangle / 360.0
 
-        wedgeargs = kwargs.get('wedgeargs', {})
-        textargs = kwargs.get('textargs', {})
+        wedgeprops = {} if (wedgeprops is None) else wedgeprops
+        textprops = {} if (textprops is None) else textprops
 
         texts = []
         slices = []
@@ -2466,7 +2475,7 @@ def pie(self, x, explode=None, labels=None, colors=None,
             w = mpatches.Wedge((x, y), radius, 360. * min(theta1, theta2),
                             360. * max(theta1, theta2),
                             facecolor=colors[i % len(colors)],
-                            **wedgeargs)
+                            **wedgeprops)
             slices.append(w)
             self.add_patch(w)
             w.set_label(label)
@@ -2491,7 +2500,7 @@ def pie(self, x, explode=None, labels=None, colors=None,
                           size=rcParams['xtick.labelsize'],
                           horizontalalignment=label_alignment,
                           verticalalignment='center',
-                          **textargs)
+                          **textprops)
 
             texts.append(t)
 
@@ -2506,13 +2515,10 @@ def pie(self, x, explode=None, labels=None, colors=None,
                     raise TypeError(
                         'autopct must be callable or a format string')
 
-                # code review request: not sure if we should pass the
-                # textargs to this call as well. Probably should, but
-                # someone who knows this better should comment.
                 t = self.text(xt, yt, s,
                               horizontalalignment='center',
                               verticalalignment='center',
-                              **textargs)
+                              **textprops)
 
 
                 autotexts.append(t)

lib/matplotlib/pyplot.py

@@ -2599,7 +2599,7 @@ def broken_barh(xranges, yrange, hold=None, **kwargs):
 # This function was autogenerated by boilerplate.py.  Do not edit as
 # changes will be lost
 @_autogen_docstring(Axes.boxplot)
-def boxplot(x, notch=False, sym='b+', vert=True, whis=1.5, positions=None,
+def boxplot(x, notch=False, sym=u'b+', vert=True, whis=1.5, positions=None,
             widths=None, patch_artist=False, bootstrap=None, usermedians=None,
             conf_intervals=None, meanline=False, showmeans=False, showcaps=True,
             showbox=True, showfliers=True, boxprops=None, labels=None,
@@ -2631,8 +2631,8 @@ def boxplot(x, notch=False, sym='b+', vert=True, whis=1.5, positions=None,
 # changes will be lost
 @_autogen_docstring(Axes.cohere)
 def cohere(x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
-           window=mlab.window_hanning, noverlap=0, pad_to=None, sides='default',
-           scale_by_freq=None, hold=None, **kwargs):
+           window=mlab.window_hanning, noverlap=0, pad_to=None,
+           sides=u'default', scale_by_freq=None, hold=None, **kwargs):
     ax = gca()
     # allow callers to override the hold state by passing hold=True|False
     washold = ax.ishold()
@@ -2729,7 +2729,7 @@ def csd(x, y, NFFT=None, Fs=None, Fc=None, detrend=None, window=None,
 # This function was autogenerated by boilerplate.py.  Do not edit as
 # changes will be lost
 @_autogen_docstring(Axes.errorbar)
-def errorbar(x, y, yerr=None, xerr=None, fmt='-', ecolor=None, elinewidth=None,
+def errorbar(x, y, yerr=None, xerr=None, fmt=u'-', ecolor=None, elinewidth=None,
              capsize=3, barsabove=False, lolims=False, uplims=False,
              xlolims=False, xuplims=False, errorevery=1, capthick=None,
              hold=None, **kwargs):
@@ -2754,9 +2754,9 @@ def errorbar(x, y, yerr=None, xerr=None, fmt='-', ecolor=None, elinewidth=None,
 # This function was autogenerated by boilerplate.py.  Do not edit as
 # changes will be lost
 @_autogen_docstring(Axes.eventplot)
-def eventplot(positions, orientation='horizontal', lineoffsets=1, linelengths=1,
-              linewidths=None, colors=None, linestyles='solid', hold=None,
-              **kwargs):
+def eventplot(positions, orientation=u'horizontal', lineoffsets=1,
+              linelengths=1, linewidths=None, colors=None, linestyles=u'solid',
+              hold=None, **kwargs):
     ax = gca()
     # allow callers to override the hold state by passing hold=True|False
     washold = ax.ishold()
@@ -2832,9 +2832,9 @@ def fill_betweenx(y, x1, x2=0, where=None, hold=None, **kwargs):
 # This function was autogenerated by boilerplate.py.  Do not edit as
 # changes will be lost
 @_autogen_docstring(Axes.hexbin)
-def hexbin(x, y, C=None, gridsize=100, bins=None, xscale='linear',
-           yscale='linear', extent=None, cmap=None, norm=None, vmin=None,
-           vmax=None, alpha=None, linewidths=None, edgecolors='none',
+def hexbin(x, y, C=None, gridsize=100, bins=None, xscale=u'linear',
+           yscale=u'linear', extent=None, cmap=None, norm=None, vmin=None,
+           vmax=None, alpha=None, linewidths=None, edgecolors=u'none',
            reduce_C_function=np.mean, mincnt=None, marginals=False, hold=None,
            **kwargs):
     ax = gca()
@@ -2860,7 +2860,7 @@ def hexbin(x, y, C=None, gridsize=100, bins=None, xscale='linear',
 # changes will be lost
 @_autogen_docstring(Axes.hist)
 def hist(x, bins=10, range=None, normed=False, weights=None, cumulative=False,
-         bottom=None, histtype='bar', align='mid', orientation='vertical',
+         bottom=None, histtype=u'bar', align=u'mid', orientation=u'vertical',
          rwidth=None, log=False, color=None, label=None, stacked=False,
          hold=None, **kwargs):
     ax = gca()
@@ -2904,8 +2904,8 @@ def hist2d(x, y, bins=10, range=None, normed=False, weights=None, cmin=None,
 # This function was autogenerated by boilerplate.py.  Do not edit as
 # changes will be lost
 @_autogen_docstring(Axes.hlines)
-def hlines(y, xmin, xmax, colors='k', linestyles='solid', label='', hold=None,
-           **kwargs):
+def hlines(y, xmin, xmax, colors=u'k', linestyles=u'solid', label=u'',
+           hold=None, **kwargs):
     ax = gca()
     # allow callers to override the hold state by passing hold=True|False
     washold = ax.ishold()
@@ -3046,7 +3046,7 @@ def phase_spectrum(x, Fs=None, Fc=None, window=None, pad_to=None, sides=None,
 @_autogen_docstring(Axes.pie)
 def pie(x, explode=None, labels=None, colors=None, autopct=None,
         pctdistance=0.6, shadow=False, labeldistance=1.1, startangle=None,
-        radius=None, hold=None):
+        radius=None, counterclock=True, linewidth=None, hold=None):
     ax = gca()
     # allow callers to override the hold state by passing hold=True|False
     washold = ax.ishold()
@@ -3057,7 +3057,8 @@ def pie(x, explode=None, labels=None, colors=None, autopct=None,
         ret = ax.pie(x, explode=explode, labels=labels, colors=colors,
                      autopct=autopct, pctdistance=pctdistance, shadow=shadow,
                      labeldistance=labeldistance, startangle=startangle,
-                     radius=radius)
+                     radius=radius, counterclock=counterclock,
+                     linewidth=linewidth)
         draw_if_interactive()
     finally:
         ax.hold(washold)
@@ -3085,7 +3086,7 @@ def plot(*args, **kwargs):
 # This function was autogenerated by boilerplate.py.  Do not edit as
 # changes will be lost
 @_autogen_docstring(Axes.plot_date)
-def plot_date(x, y, fmt='o', tz=None, xdate=True, ydate=False, hold=None,
+def plot_date(x, y, fmt=u'o', tz=None, xdate=True, ydate=False, hold=None,
               **kwargs):
     ax = gca()
     # allow callers to override the hold state by passing hold=True|False
@@ -3164,7 +3165,7 @@ def quiverkey(*args, **kw):
 # This function was autogenerated by boilerplate.py.  Do not edit as
 # changes will be lost
 @_autogen_docstring(Axes.scatter)
-def scatter(x, y, s=20, c='b', marker='o', cmap=None, norm=None, vmin=None,
+def scatter(x, y, s=20, c=u'b', marker=u'o', cmap=None, norm=None, vmin=None,
             vmax=None, alpha=None, linewidths=None, verts=None, hold=None,
             **kwargs):
     ax = gca()
@@ -3302,7 +3303,7 @@ def step(x, y, *args, **kwargs):
 # changes will be lost
 @_autogen_docstring(Axes.streamplot)
 def streamplot(x, y, u, v, density=1, linewidth=None, color=None, cmap=None,
-               norm=None, arrowsize=1, arrowstyle='-|>', minlength=0.1,
+               norm=None, arrowsize=1, arrowstyle=u'-|>', minlength=0.1,
                transform=None, zorder=1, hold=None):
     ax = gca()
     # allow callers to override the hold state by passing hold=True|False
@@ -3397,8 +3398,8 @@ def triplot(*args, **kwargs):
 # This function was autogenerated by boilerplate.py.  Do not edit as
 # changes will be lost
 @_autogen_docstring(Axes.vlines)
-def vlines(x, ymin, ymax, colors='k', linestyles='solid', label='', hold=None,
-           **kwargs):
+def vlines(x, ymin, ymax, colors=u'k', linestyles=u'solid', label=u'',
+           hold=None, **kwargs):
     ax = gca()
     # allow callers to override the hold state by passing hold=True|False
     washold = ax.ishold()
@@ -3463,7 +3464,7 @@ def cla():
 # This function was autogenerated by boilerplate.py.  Do not edit as
 # changes will be lost
 @docstring.copy_dedent(Axes.grid)
-def grid(b=None, which='major', axis='both', **kwargs):
+def grid(b=None, which=u'major', axis=u'both', **kwargs):
     ret = gca().grid(b=b, which=which, axis=axis, **kwargs)
     draw_if_interactive()
     return ret
@@ -3511,15 +3512,15 @@ def ticklabel_format(**kwargs):
 # This function was autogenerated by boilerplate.py.  Do not edit as
 # changes will be lost
 @docstring.copy_dedent(Axes.locator_params)
-def locator_params(axis='both', tight=None, **kwargs):
+def locator_params(axis=u'both', tight=None, **kwargs):
     ret = gca().locator_params(axis=axis, tight=tight, **kwargs)
     draw_if_interactive()
     return ret
 
 # This function was autogenerated by boilerplate.py.  Do not edit as
 # changes will be lost
 @docstring.copy_dedent(Axes.tick_params)
-def tick_params(axis='both', **kwargs):
+def tick_params(axis=u'both', **kwargs):
     ret = gca().tick_params(axis=axis, **kwargs)
     draw_if_interactive()
     return ret
@@ -3535,7 +3536,7 @@ def margins(*args, **kw):
 # This function was autogenerated by boilerplate.py.  Do not edit as
 # changes will be lost
 @docstring.copy_dedent(Axes.autoscale)
-def autoscale(enable=True, axis='both', tight=None):
+def autoscale(enable=True, axis=u'both', tight=None):
     ret = gca().autoscale(enable=enable, axis=axis, tight=tight)
     draw_if_interactive()
     return ret