fixed docstring copying

Author: adamklein

pandas/core/frame.py

@@ -32,7 +32,7 @@
 from pandas.core.series import Series
 from pandas.util import py3compat
 from pandas.util.terminal import get_terminal_size
-from pandas.util.decorators import deprecate, Appender
+from pandas.util.decorators import deprecate, Appender, Substitution
 
 from pandas.core.format import DataFrameFormatter, docstring_to_string
 
@@ -162,19 +162,12 @@
 merged : DataFrame
 """
 
-def _add_stat_doc(f, name, shortname, na_action=_doc_exclude_na,
-                  extras=''):
-    doc = _stat_doc % {'name' : name,
-                       'shortname' : shortname,
-                       'na_action' : na_action,
-                       'extras' : extras}
-    f.__doc__ = doc
-
 
 #----------------------------------------------------------------------
 # Factory helper methods
 
 def _arith_method(func, name, default_axis='columns'):
+    @Appender(_arith_doc % name)
     def f(self, other, axis=default_axis, level=None, fill_value=None):
         if isinstance(other, DataFrame):    # Another DataFrame
             return self._combine_frame(other, func, fill_value, level)
@@ -184,12 +177,12 @@ def f(self, other, axis=default_axis, level=None, fill_value=None):
             return self._combine_const(other, func)
 
     f.__name__ = name
-    f.__doc__ = _arith_doc % name
 
     return f
 
 
 def comp_method(func, name):
+    @Appender('Wrapper for comparison method %s' % name)
     def f(self, other):
         if isinstance(other, DataFrame):    # Another DataFrame
             return self._compare_frame(other, func)
@@ -199,7 +192,6 @@ def f(self, other):
             return self._combine_const(other, func)
 
     f.__name__ = name
-    f.__doc__ = 'Wrapper for comparison method %s' % name
 
     return f
 
@@ -2844,6 +2836,8 @@ def _join_compat(self, other, on=None, how='left', lsuffix='', rsuffix=''):
             return concat([self] + list(other), axis=1, join=how,
                           join_axes=join_axes, verify_integrity=True)
 
+    @Substitution('')
+    @Appender(_merge_doc, indents=2)
     def merge(self, right, how='inner', on=None, left_on=None, right_on=None,
               left_index=False, right_index=False, sort=True,
               suffixes=('.x', '.y'), copy=True):
@@ -2852,7 +2846,6 @@ def merge(self, right, how='inner', on=None, left_on=None, right_on=None,
                      left_on=left_on, right_on=right_on,
                      left_index=left_index, right_index=right_index, sort=sort,
                      suffixes=suffixes, copy=copy)
-    if __debug__: merge.__doc__ = _merge_doc % ''
 
     #----------------------------------------------------------------------
     # Statistical methods, etc.
@@ -3061,56 +3054,71 @@ def _count_level(self, level, axis=0, numeric_only=False):
         else:
             return result
 
+    @Substitution(name='sum', shortname='sum', na_action=_doc_exclude_na,
+                  extras=_numeric_only_doc)
+    @Appender(_stat_doc)
     def sum(self, axis=0, numeric_only=None, skipna=True, level=None):
         if level is not None:
             return self._agg_by_level('sum', axis=axis, level=level,
                                       skipna=skipna)
         return self._reduce(nanops.nansum, axis=axis, skipna=skipna,
                             numeric_only=numeric_only)
-    _add_stat_doc(sum, 'sum', 'sum', extras=_numeric_only_doc)
 
+    @Substitution(name='mean', shortname='mean', na_action=_doc_exclude_na,
+                  extras='')
+    @Appender(_stat_doc)
     def mean(self, axis=0, skipna=True, level=None):
         if level is not None:
             return self._agg_by_level('mean', axis=axis, level=level,
                                       skipna=skipna)
         return self._reduce(nanops.nanmean, axis=axis, skipna=skipna,
                             numeric_only=None)
-    _add_stat_doc(mean, 'mean', 'mean')
 
+    @Substitution(name='minimum', shortname='min', na_action=_doc_exclude_na,
+                  extras='')
+    @Appender(_stat_doc)
     def min(self, axis=0, skipna=True, level=None):
         if level is not None:
             return self._agg_by_level('min', axis=axis, level=level,
                                       skipna=skipna)
         return self._reduce(nanops.nanmin, axis=axis, skipna=skipna,
                             numeric_only=None)
-    _add_stat_doc(min, 'minimum', 'min')
 
+    @Substitution(name='maximum', shortname='max', na_action=_doc_exclude_na,
+                  extras='')
+    @Appender(_stat_doc)
     def max(self, axis=0, skipna=True, level=None):
         if level is not None:
             return self._agg_by_level('max', axis=axis, level=level,
                                       skipna=skipna)
         return self._reduce(nanops.nanmax, axis=axis, skipna=skipna,
                             numeric_only=None)
-    _add_stat_doc(max, 'maximum', 'max')
 
+    @Substitution(name='product', shortname='product',
+                  na_action='NA/null values are treated as 1', extras='')
+    @Appender(_stat_doc)
     def prod(self, axis=0, skipna=True, level=None):
         if level is not None:
             return self._agg_by_level('prod', axis=axis, level=level,
                                       skipna=skipna)
         return self._reduce(nanops.nanprod, axis=axis, skipna=skipna,
                             numeric_only=None)
-    _add_stat_doc(prod, 'product', 'product',
-                  na_action='NA/null values are treated as 1')
+
     product = prod
 
+    @Substitution(name='median', shortname='median', na_action=_doc_exclude_na,
+                  extras='')
+    @Appender(_stat_doc)
     def median(self, axis=0, skipna=True, level=None):
         if level is not None:
             return self._agg_by_level('median', axis=axis, level=level,
                                       skipna=skipna)
         return self._reduce(nanops.nanmedian, axis=axis, skipna=skipna,
                             numeric_only=None)
-    _add_stat_doc(median, 'median', 'median')
 
+    @Substitution(name='median absolute deviation', shortname='mad', 
+                  na_action=_doc_exclude_na, extras='')
+    @Appender(_stat_doc)
     def mad(self, axis=0, skipna=True, level=None):
         if level is not None:
             return self._agg_by_level('mad', axis=axis, level=level,
@@ -3123,30 +3131,35 @@ def mad(self, axis=0, skipna=True, level=None):
         else:
             demeaned = frame.sub(frame.mean(axis=1), axis=0)
         return np.abs(demeaned).mean(axis=axis, skipna=skipna)
-    _add_stat_doc(mad, 'mean absolute deviation', 'mad')
 
+    @Substitution(name='unbiased variance', shortname='var',
+                  na_action=_doc_exclude_na, extras='')
+    @Appender(_stat_doc)
     def var(self, axis=0, skipna=True, level=None):
         if level is not None:
             return self._agg_by_level('var', axis=axis, level=level,
                                       skipna=skipna)
         return self._reduce(nanops.nanvar, axis=axis, skipna=skipna,
                             numeric_only=None)
-    _add_stat_doc(var, 'unbiased variance', 'var')
 
+    @Substitution(name='unbiased standard deviation', shortname='std',
+                  na_action=_doc_exclude_na, extras='')
+    @Appender(_stat_doc)
     def std(self, axis=0, skipna=True, level=None):
         if level is not None:
             return self._agg_by_level('std', axis=axis, level=level,
                                       skipna=skipna)
         return np.sqrt(self.var(axis=axis, skipna=skipna))
-    _add_stat_doc(std, 'unbiased standard deviation', 'std')
 
+    @Substitution(name='unbiased skewness', shortname='skew',
+                  na_action=_doc_exclude_na, extras='')
+    @Appender(_stat_doc)
     def skew(self, axis=0, skipna=True, level=None):
         if level is not None:
             return self._agg_by_level('skew', axis=axis, level=level,
                                       skipna=skipna)
         return self._reduce(nanops.nanskew, axis=axis, skipna=skipna,
                             numeric_only=None)
-    _add_stat_doc(skew, 'unbiased skewness', 'skew')
 
     def _agg_by_level(self, name, axis=0, level=0, skipna=True):
         grouped = self.groupby(level=level, axis=axis)

pandas/core/groupby.py

@@ -9,7 +9,7 @@
 from pandas.core.internals import BlockManager
 from pandas.core.series import Series
 from pandas.core.panel import Panel
-from pandas.util.decorators import cache_readonly
+from pandas.util.decorators import cache_readonly, Appender
 import pandas._tseries as lib
 
 
@@ -472,6 +472,7 @@ def _generator_factory(self):
                                            axis=self.axis,
                                            factory=factory)
 
+@Appender(GroupBy.__doc__)
 def groupby(obj, by, **kwds):
     if isinstance(obj, Series):
         klass = SeriesGroupBy
@@ -481,7 +482,6 @@ def groupby(obj, by, **kwds):
         raise TypeError('invalid type: %s' % type(obj))
 
     return klass(obj, by, **kwds)
-groupby.__doc__ = GroupBy.__doc__
 
 def _get_axes(group):
     if isinstance(group, Series):

pandas/core/panel.py

@@ -16,7 +16,7 @@
 from pandas.core.frame import DataFrame
 from pandas.core.generic import NDFrame
 from pandas.util import py3compat
-from pandas.util.decorators import deprecate
+from pandas.util.decorators import deprecate, Appender, Substitution
 import pandas.core.common as com
 import pandas.core.nanops as nanops
 import pandas._tseries as lib
@@ -97,6 +97,7 @@ def f(self, other):
     return f
 
 def _panel_arith_method(op, name):
+    @Substitution(op)
     def f(self, other, axis='items'):
         """
         Wrapper method for %s
@@ -114,9 +115,6 @@ def f(self, other, axis='items'):
         return self._combine(other, op, axis=axis)
 
     f.__name__ = name
-    if __debug__:
-        f.__doc__ = f.__doc__ % str(op)
-
     return f
 
 
@@ -141,11 +139,6 @@ def f(self, other, axis='items'):
 If all values are NA, result will be NA"""
 
 
-def _add_docs(method, desc, outname):
-    doc = _agg_doc % {'desc' : desc,
-                      'outname' : outname}
-    method.__doc__ = doc
-
 class Panel(NDFrame):
     _AXIS_NUMBERS = {
         'items' : 0,
@@ -982,45 +975,55 @@ def count(self, axis='major'):
 
         return self._wrap_result(result, axis)
 
+    @Substitution(desc='sum', outname='sum')
+    @Appender(_agg_doc)
     def sum(self, axis='major', skipna=True):
         return self._reduce(nanops.nansum, axis=axis, skipna=skipna)
-    _add_docs(sum, 'sum', 'sum')
 
+    @Substitution(desc='mean', outname='mean')
+    @Appender(_agg_doc)
     def mean(self, axis='major', skipna=True):
         return self._reduce(nanops.nanmean, axis=axis, skipna=skipna)
-    _add_docs(mean, 'mean', 'mean')
 
+    @Substitution(desc='unbiased variance', outname='variance')
+    @Appender(_agg_doc)
     def var(self, axis='major', skipna=True):
         return self._reduce(nanops.nanvar, axis=axis, skipna=skipna)
-    _add_docs(var, 'unbiased variance', 'variance')
 
+    @Substitution(desc='unbiased standard deviation', outname='stdev')
+    @Appender(_agg_doc)
     def std(self, axis='major', skipna=True):
         return self.var(axis=axis, skipna=skipna).apply(np.sqrt)
-    _add_docs(std, 'unbiased standard deviation', 'stdev')
 
+    @Substitution(desc='unbiased skewness', outname='skew')
+    @Appender(_agg_doc)
     def skew(self, axis='major', skipna=True):
         return self._reduce(nanops.nanskew, axis=axis, skipna=skipna)
-    _add_docs(std, 'unbiased skewness', 'skew')
 
+    @Substitution(desc='product', outname='prod')
+    @Appender(_agg_doc)
     def prod(self, axis='major', skipna=True):
         return self._reduce(nanops.nanprod, axis=axis, skipna=skipna)
-    _add_docs(prod, 'product', 'prod')
 
+    @Substitution(desc='compounded percentage', outname='compounded')
+    @Appender(_agg_doc)
     def compound(self, axis='major', skipna=True):
         return (1 + self).prod(axis=axis, skipna=skipna) - 1
-    _add_docs(compound, 'compounded percentage', 'compounded')
 
+    @Substitution(desc='median', outname='median')
+    @Appender(_agg_doc)
     def median(self, axis='major', skipna=True):
         return self._reduce(nanops.nanmedian, axis=axis, skipna=skipna)
-    _add_docs(median, 'median', 'median')
 
+    @Substitution(desc='maximum', outname='maximum')
+    @Appender(_agg_doc)
     def max(self, axis='major', skipna=True):
         return self._reduce(nanops.nanmax, axis=axis, skipna=skipna)
-    _add_docs(max, 'maximum', 'maximum')
 
+    @Substitution(desc='minimum', outname='minimum')
+    @Appender(_agg_doc)
     def min(self, axis='major', skipna=True):
         return self._reduce(nanops.nanmin, axis=axis, skipna=skipna)
-    _add_docs(min, 'minimum', 'minimum')
 
     def shift(self, lags, axis='major'):
         """