We are currently solving the following issue within our repository. Here is the issue text:
--- BEGIN ISSUE ---
pandas.core.groupby.SeriesGroupBy.hist doesn't take kwargs
I'd like to pass certain kwargs to the hist function of a SeriesGroupBy object (alpha, legend, etc). The plot function provides more kwargs (e.g. legend, but not alpha) but no **kwargs to forward to matplotlib. The documentation (viewed with ? in ipython) suggests that there should be a kwds argument, but in reality this is not the case.


--- END ISSUE ---

Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
--- BEGIN FILES ---
Path: `pandas/util/decorators.py`
Content:
```
1 from pandas.compat import StringIO, callable
2 from pandas.lib import cache_readonly
3 import sys
4 import warnings
5 from functools import wraps
6 
7 
8 def deprecate(name, alternative, alt_name=None):
9     alt_name = alt_name or alternative.__name__
10 
11     def wrapper(*args, **kwargs):
12         warnings.warn("%s is deprecated. Use %s instead" % (name, alt_name),
13                       FutureWarning)
14         return alternative(*args, **kwargs)
15     return wrapper
16 
17 
18 def deprecate_kwarg(old_arg_name, new_arg_name, mapping=None):
19     """Decorator to deprecate a keyword argument of a function
20 
21     Parameters
22     ----------
23     old_arg_name : str
24         Name of argument in function to deprecate
25     new_arg_name : str
26         Name of prefered argument in function
27     mapping : dict or callable
28         If mapping is present, use it to translate old arguments to
29         new arguments.  A callable must do its own value checking;
30         values not found in a dict will be forwarded unchanged.
31 
32     Examples
33     --------
34     The following deprecates 'cols', using 'columns' instead
35 
36     >>> @deprecate_kwarg(old_arg_name='cols', new_arg_name='columns')
37     ... def f(columns=''):
38     ...     print(columns)
39     ...
40     >>> f(columns='should work ok')
41     should work ok
42     >>> f(cols='should raise warning')
43     FutureWarning: cols is deprecated, use columns instead
44       warnings.warn(msg, FutureWarning)
45     should raise warning
46     >>> f(cols='should error', columns="can't pass do both")
47     TypeError: Can only specify 'cols' or 'columns', not both
48     >>> @deprecate_kwarg('old', 'new', {'yes': True, 'no', False})
49     ... def f(new=False):
50     ...     print('yes!' if new else 'no!')
51     ...
52     >>> f(old='yes')
53     FutureWarning: old='yes' is deprecated, use new=True instead
54       warnings.warn(msg, FutureWarning)
55     yes!
56 
57     """
58     if mapping is not None and not hasattr(mapping, 'get') and \
59             not callable(mapping):
60         raise TypeError("mapping from old to new argument values "
61                         "must be dict or callable!")
62     def _deprecate_kwarg(func):
63         @wraps(func)
64         def wrapper(*args, **kwargs):
65             old_arg_value = kwargs.pop(old_arg_name, None)
66             if old_arg_value is not None:
67                 if mapping is not None:
68                     if hasattr(mapping, 'get'):
69                         new_arg_value = mapping.get(old_arg_value,
70                                                     old_arg_value)
71                     else:
72                         new_arg_value = mapping(old_arg_value)
73                     msg = "the %s=%r keyword is deprecated, " \
74                           "use %s=%r instead" % \
75                           (old_arg_name, old_arg_value,
76                            new_arg_name, new_arg_value)
77                 else:
78                     new_arg_value = old_arg_value
79                     msg = "the '%s' keyword is deprecated, " \
80                           "use '%s' instead" % (old_arg_name, new_arg_name)
81                 warnings.warn(msg, FutureWarning)
82                 if kwargs.get(new_arg_name, None) is not None:
83                     msg = "Can only specify '%s' or '%s', not both" % \
84                       (old_arg_name, new_arg_name)
85                     raise TypeError(msg)
86                 else:
87                     kwargs[new_arg_name] = new_arg_value
88             return func(*args, **kwargs)
89         return wrapper
90     return _deprecate_kwarg
91 
92 
93 # Substitution and Appender are derived from matplotlib.docstring (1.1.0)
94 # module http://matplotlib.sourceforge.net/users/license.html
95 
96 
97 class Substitution(object):
98     """
99     A decorator to take a function's docstring and perform string
100     substitution on it.
101 
102     This decorator should be robust even if func.__doc__ is None
103     (for example, if -OO was passed to the interpreter)
104 
105     Usage: construct a docstring.Substitution with a sequence or
106     dictionary suitable for performing substitution; then
107     decorate a suitable function with the constructed object. e.g.
108 
109     sub_author_name = Substitution(author='Jason')
110 
111     @sub_author_name
112     def some_function(x):
113         "%(author)s wrote this function"
114 
115     # note that some_function.__doc__ is now "Jason wrote this function"
116 
117     One can also use positional arguments.
118 
119     sub_first_last_names = Substitution('Edgar Allen', 'Poe')
120 
121     @sub_first_last_names
122     def some_function(x):
123         "%s %s wrote the Raven"
124     """
125     def __init__(self, *args, **kwargs):
126         if (args and kwargs):
127             raise AssertionError( "Only positional or keyword args are allowed")
128 
129         self.params = args or kwargs
130 
131     def __call__(self, func):
132         func.__doc__ = func.__doc__ and func.__doc__ % self.params
133         return func
134 
135     def update(self, *args, **kwargs):
136         "Assume self.params is a dict and update it with supplied args"
137         self.params.update(*args, **kwargs)
138 
139     @classmethod
140     def from_params(cls, params):
141         """
142         In the case where the params is a mutable sequence (list or dictionary)
143         and it may change before this class is called, one may explicitly use a
144         reference to the params rather than using *args or **kwargs which will
145         copy the values and not reference them.
146         """
147         result = cls()
148         result.params = params
149         return result
150 
151 
152 class Appender(object):
153     """
154     A function decorator that will append an addendum to the docstring
155     of the target function.
156 
157     This decorator should be robust even if func.__doc__ is None
158     (for example, if -OO was passed to the interpreter).
159 
160     Usage: construct a docstring.Appender with a string to be joined to
161     the original docstring. An optional 'join' parameter may be supplied
162     which will be used to join the docstring and addendum. e.g.
163 
164     add_copyright = Appender("Copyright (c) 2009", join='\n')
165 
166     @add_copyright
167     def my_dog(has='fleas'):
168         "This docstring will have a copyright below"
169         pass
170     """
171     def __init__(self, addendum, join='', indents=0):
172         if indents > 0:
173             self.addendum = indent(addendum, indents=indents)
174         else:
175             self.addendum = addendum
176         self.join = join
177 
178     def __call__(self, func):
179         func.__doc__ = func.__doc__ if func.__doc__ else ''
180         self.addendum = self.addendum if self.addendum else ''
181         docitems = [func.__doc__, self.addendum]
182         func.__doc__ = self.join.join(docitems)
183         return func
184 
185 
186 def indent(text, indents=1):
187     if not text or not isinstance(text, str):
188         return ''
189     jointext = ''.join(['\n'] + ['    '] * indents)
190     return jointext.join(text.split('\n'))
191 
192 
193 def suppress_stdout(f):
194     def wrapped(*args, **kwargs):
195         try:
196             sys.stdout = StringIO()
197             f(*args, **kwargs)
198         finally:
199             sys.stdout = sys.__stdout__
200 
201     return wrapped
202 
203 
204 class KnownFailureTest(Exception):
205     '''Raise this exception to mark a test as a known failing test.'''
206     pass
207 
208 
209 def knownfailureif(fail_condition, msg=None):
210     """
211     Make function raise KnownFailureTest exception if given condition is true.
212 
213     If the condition is a callable, it is used at runtime to dynamically
214     make the decision. This is useful for tests that may require costly
215     imports, to delay the cost until the test suite is actually executed.
216 
217     Parameters
218     ----------
219     fail_condition : bool or callable
220         Flag to determine whether to mark the decorated test as a known
221         failure (if True) or not (if False).
222     msg : str, optional
223         Message to give on raising a KnownFailureTest exception.
224         Default is None.
225 
226     Returns
227     -------
228     decorator : function
229         Decorator, which, when applied to a function, causes SkipTest
230         to be raised when `skip_condition` is True, and the function
231         to be called normally otherwise.
232 
233     Notes
234     -----
235     The decorator itself is decorated with the ``nose.tools.make_decorator``
236     function in order to transmit function name, and various other metadata.
237 
238     """
239     if msg is None:
240         msg = 'Test skipped due to known failure'
241 
242     # Allow for both boolean or callable known failure conditions.
243     if callable(fail_condition):
244         fail_val = fail_condition
245     else:
246         fail_val = lambda: fail_condition
247 
248     def knownfail_decorator(f):
249         # Local import to avoid a hard nose dependency and only incur the
250         # import time overhead at actual test-time.
251         import nose
252 
253         def knownfailer(*args, **kwargs):
254             if fail_val():
255                 raise KnownFailureTest(msg)
256             else:
257                 return f(*args, **kwargs)
258         return nose.tools.make_decorator(f)(knownfailer)
259 
260     return knownfail_decorator
261 
262 def make_signature(func) :
263     """
264     Returns a string repr of the arg list of a func call, with any defaults
265 
266     Examples
267     --------
268 
269     >>> def f(a,b,c=2) :
270     >>>     return a*b*c
271     >>> print(_make_signature(f))
272     a,b,c=2
273     """
274     from inspect import getargspec
275     spec = getargspec(func)
276     if spec.defaults == None :
277         n_wo_defaults = len(spec.args)
278         defaults = ('',) * n_wo_defaults
279     else :
280         n_wo_defaults = len(spec.args) - len(spec.defaults)
281         defaults = ('',) * n_wo_defaults + spec.defaults
282     args = []
283     for i, (var, default) in enumerate(zip(spec.args, defaults)) :
284         args.append(var if default=='' else var+'='+repr(default))
285     return args, spec.args
286 
287
```
--- END FILES ---

Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.

Here is an example:

```diff
diff --git a/examples/server_async.py b/examples/server_async.py
--- a/examples/server_async.py
+++ b/examples/server_async.py
@@ -313,4 +313,4 @@
 
 
 if __name__ == "__main__":
-    asyncio.run(run_async_server("."), debug=True)
+    asyncio.run(run_async_server(), debug=True)
diff --git a/examples/server_sync.py b/examples/server_sync.py
--- a/examples/server_sync.py
+++ b/examples/server_sync.py
@@ -313,5 +313,5 @@
 
 
 if __name__ == "__main__":
-    server = run_sync_server(".")
+    server = run_sync_server()
     server.shutdown()

```

diff --git a/pandas/util/decorators.py b/pandas/util/decorators.py
--- a/pandas/util/decorators.py
+++ b/pandas/util/decorators.py
@@ -282,5 +282,9 @@
     args = []
     for i, (var, default) in enumerate(zip(spec.args, defaults)) :
         args.append(var if default=='' else var+'='+repr(default))
+    if spec.varargs:
+        args.append('*' + spec.varargs)
+    if spec.keywords:
+        args.append('**' + spec.keywords)
     return args, spec.args

{"golden_diff": "diff --git a/pandas/util/decorators.py b/pandas/util/decorators.py\n--- a/pandas/util/decorators.py\n+++ b/pandas/util/decorators.py\n@@ -282,5 +282,9 @@\n     args = []\n     for i, (var, default) in enumerate(zip(spec.args, defaults)) :\n         args.append(var if default=='' else var+'='+repr(default))\n+    if spec.varargs:\n+        args.append('*' + spec.varargs)\n+    if spec.keywords:\n+        args.append('**' + spec.keywords)\n     return args, spec.args\n", "issue": "pandas.core.groupby.SeriesGroupBy.hist doesn't take kwargs\nI'd like to pass certain kwargs to the hist function of a SeriesGroupBy object (alpha, legend, etc). The plot function provides more kwargs (e.g. legend, but not alpha) but no **kwargs to forward to matplotlib. The documentation (viewed with ? in ipython) suggests that there should be a kwds argument, but in reality this is not the case.\n\n", "before_files": [{"content": "from pandas.compat import StringIO, callable\nfrom pandas.lib import cache_readonly\nimport sys\nimport warnings\nfrom functools import wraps\n\n\ndef deprecate(name, alternative, alt_name=None):\n    alt_name = alt_name or alternative.__name__\n\n    def wrapper(*args, **kwargs):\n        warnings.warn(\"%s is deprecated. Use %s instead\" % (name, alt_name),\n                      FutureWarning)\n        return alternative(*args, **kwargs)\n    return wrapper\n\n\ndef deprecate_kwarg(old_arg_name, new_arg_name, mapping=None):\n    \"\"\"Decorator to deprecate a keyword argument of a function\n\n    Parameters\n    ----------\n    old_arg_name : str\n        Name of argument in function to deprecate\n    new_arg_name : str\n        Name of prefered argument in function\n    mapping : dict or callable\n        If mapping is present, use it to translate old arguments to\n        new arguments.  A callable must do its own value checking;\n        values not found in a dict will be forwarded unchanged.\n\n    Examples\n    --------\n    The following deprecates 'cols', using 'columns' instead\n\n    >>> @deprecate_kwarg(old_arg_name='cols', new_arg_name='columns')\n    ... def f(columns=''):\n    ...     print(columns)\n    ...\n    >>> f(columns='should work ok')\n    should work ok\n    >>> f(cols='should raise warning')\n    FutureWarning: cols is deprecated, use columns instead\n      warnings.warn(msg, FutureWarning)\n    should raise warning\n    >>> f(cols='should error', columns=\"can't pass do both\")\n    TypeError: Can only specify 'cols' or 'columns', not both\n    >>> @deprecate_kwarg('old', 'new', {'yes': True, 'no', False})\n    ... def f(new=False):\n    ...     print('yes!' if new else 'no!')\n    ...\n    >>> f(old='yes')\n    FutureWarning: old='yes' is deprecated, use new=True instead\n      warnings.warn(msg, FutureWarning)\n    yes!\n\n    \"\"\"\n    if mapping is not None and not hasattr(mapping, 'get') and \\\n            not callable(mapping):\n        raise TypeError(\"mapping from old to new argument values \"\n                        \"must be dict or callable!\")\n    def _deprecate_kwarg(func):\n        @wraps(func)\n        def wrapper(*args, **kwargs):\n            old_arg_value = kwargs.pop(old_arg_name, None)\n            if old_arg_value is not None:\n                if mapping is not None:\n                    if hasattr(mapping, 'get'):\n                        new_arg_value = mapping.get(old_arg_value,\n                                                    old_arg_value)\n                    else:\n                        new_arg_value = mapping(old_arg_value)\n                    msg = \"the %s=%r keyword is deprecated, \" \\\n                          \"use %s=%r instead\" % \\\n                          (old_arg_name, old_arg_value,\n                           new_arg_name, new_arg_value)\n                else:\n                    new_arg_value = old_arg_value\n                    msg = \"the '%s' keyword is deprecated, \" \\\n                          \"use '%s' instead\" % (old_arg_name, new_arg_name)\n                warnings.warn(msg, FutureWarning)\n                if kwargs.get(new_arg_name, None) is not None:\n                    msg = \"Can only specify '%s' or '%s', not both\" % \\\n                      (old_arg_name, new_arg_name)\n                    raise TypeError(msg)\n                else:\n                    kwargs[new_arg_name] = new_arg_value\n            return func(*args, **kwargs)\n        return wrapper\n    return _deprecate_kwarg\n\n\n# Substitution and Appender are derived from matplotlib.docstring (1.1.0)\n# module http://matplotlib.sourceforge.net/users/license.html\n\n\nclass Substitution(object):\n    \"\"\"\n    A decorator to take a function's docstring and perform string\n    substitution on it.\n\n    This decorator should be robust even if func.__doc__ is None\n    (for example, if -OO was passed to the interpreter)\n\n    Usage: construct a docstring.Substitution with a sequence or\n    dictionary suitable for performing substitution; then\n    decorate a suitable function with the constructed object. e.g.\n\n    sub_author_name = Substitution(author='Jason')\n\n    @sub_author_name\n    def some_function(x):\n        \"%(author)s wrote this function\"\n\n    # note that some_function.__doc__ is now \"Jason wrote this function\"\n\n    One can also use positional arguments.\n\n    sub_first_last_names = Substitution('Edgar Allen', 'Poe')\n\n    @sub_first_last_names\n    def some_function(x):\n        \"%s %s wrote the Raven\"\n    \"\"\"\n    def __init__(self, *args, **kwargs):\n        if (args and kwargs):\n            raise AssertionError( \"Only positional or keyword args are allowed\")\n\n        self.params = args or kwargs\n\n    def __call__(self, func):\n        func.__doc__ = func.__doc__ and func.__doc__ % self.params\n        return func\n\n    def update(self, *args, **kwargs):\n        \"Assume self.params is a dict and update it with supplied args\"\n        self.params.update(*args, **kwargs)\n\n    @classmethod\n    def from_params(cls, params):\n        \"\"\"\n        In the case where the params is a mutable sequence (list or dictionary)\n        and it may change before this class is called, one may explicitly use a\n        reference to the params rather than using *args or **kwargs which will\n        copy the values and not reference them.\n        \"\"\"\n        result = cls()\n        result.params = params\n        return result\n\n\nclass Appender(object):\n    \"\"\"\n    A function decorator that will append an addendum to the docstring\n    of the target function.\n\n    This decorator should be robust even if func.__doc__ is None\n    (for example, if -OO was passed to the interpreter).\n\n    Usage: construct a docstring.Appender with a string to be joined to\n    the original docstring. An optional 'join' parameter may be supplied\n    which will be used to join the docstring and addendum. e.g.\n\n    add_copyright = Appender(\"Copyright (c) 2009\", join='\\n')\n\n    @add_copyright\n    def my_dog(has='fleas'):\n        \"This docstring will have a copyright below\"\n        pass\n    \"\"\"\n    def __init__(self, addendum, join='', indents=0):\n        if indents > 0:\n            self.addendum = indent(addendum, indents=indents)\n        else:\n            self.addendum = addendum\n        self.join = join\n\n    def __call__(self, func):\n        func.__doc__ = func.__doc__ if func.__doc__ else ''\n        self.addendum = self.addendum if self.addendum else ''\n        docitems = [func.__doc__, self.addendum]\n        func.__doc__ = self.join.join(docitems)\n        return func\n\n\ndef indent(text, indents=1):\n    if not text or not isinstance(text, str):\n        return ''\n    jointext = ''.join(['\\n'] + ['    '] * indents)\n    return jointext.join(text.split('\\n'))\n\n\ndef suppress_stdout(f):\n    def wrapped(*args, **kwargs):\n        try:\n            sys.stdout = StringIO()\n            f(*args, **kwargs)\n        finally:\n            sys.stdout = sys.__stdout__\n\n    return wrapped\n\n\nclass KnownFailureTest(Exception):\n    '''Raise this exception to mark a test as a known failing test.'''\n    pass\n\n\ndef knownfailureif(fail_condition, msg=None):\n    \"\"\"\n    Make function raise KnownFailureTest exception if given condition is true.\n\n    If the condition is a callable, it is used at runtime to dynamically\n    make the decision. This is useful for tests that may require costly\n    imports, to delay the cost until the test suite is actually executed.\n\n    Parameters\n    ----------\n    fail_condition : bool or callable\n        Flag to determine whether to mark the decorated test as a known\n        failure (if True) or not (if False).\n    msg : str, optional\n        Message to give on raising a KnownFailureTest exception.\n        Default is None.\n\n    Returns\n    -------\n    decorator : function\n        Decorator, which, when applied to a function, causes SkipTest\n        to be raised when `skip_condition` is True, and the function\n        to be called normally otherwise.\n\n    Notes\n    -----\n    The decorator itself is decorated with the ``nose.tools.make_decorator``\n    function in order to transmit function name, and various other metadata.\n\n    \"\"\"\n    if msg is None:\n        msg = 'Test skipped due to known failure'\n\n    # Allow for both boolean or callable known failure conditions.\n    if callable(fail_condition):\n        fail_val = fail_condition\n    else:\n        fail_val = lambda: fail_condition\n\n    def knownfail_decorator(f):\n        # Local import to avoid a hard nose dependency and only incur the\n        # import time overhead at actual test-time.\n        import nose\n\n        def knownfailer(*args, **kwargs):\n            if fail_val():\n                raise KnownFailureTest(msg)\n            else:\n                return f(*args, **kwargs)\n        return nose.tools.make_decorator(f)(knownfailer)\n\n    return knownfail_decorator\n\ndef make_signature(func) :\n    \"\"\"\n    Returns a string repr of the arg list of a func call, with any defaults\n\n    Examples\n    --------\n\n    >>> def f(a,b,c=2) :\n    >>>     return a*b*c\n    >>> print(_make_signature(f))\n    a,b,c=2\n    \"\"\"\n    from inspect import getargspec\n    spec = getargspec(func)\n    if spec.defaults == None :\n        n_wo_defaults = len(spec.args)\n        defaults = ('',) * n_wo_defaults\n    else :\n        n_wo_defaults = len(spec.args) - len(spec.defaults)\n        defaults = ('',) * n_wo_defaults + spec.defaults\n    args = []\n    for i, (var, default) in enumerate(zip(spec.args, defaults)) :\n        args.append(var if default=='' else var+'='+repr(default))\n    return args, spec.args\n\n", "path": "pandas/util/decorators.py"}], "after_files": [{"content": "from pandas.compat import StringIO, callable\nfrom pandas.lib import cache_readonly\nimport sys\nimport warnings\nfrom functools import wraps\n\n\ndef deprecate(name, alternative, alt_name=None):\n    alt_name = alt_name or alternative.__name__\n\n    def wrapper(*args, **kwargs):\n        warnings.warn(\"%s is deprecated. Use %s instead\" % (name, alt_name),\n                      FutureWarning)\n        return alternative(*args, **kwargs)\n    return wrapper\n\n\ndef deprecate_kwarg(old_arg_name, new_arg_name, mapping=None):\n    \"\"\"Decorator to deprecate a keyword argument of a function\n\n    Parameters\n    ----------\n    old_arg_name : str\n        Name of argument in function to deprecate\n    new_arg_name : str\n        Name of prefered argument in function\n    mapping : dict or callable\n        If mapping is present, use it to translate old arguments to\n        new arguments.  A callable must do its own value checking;\n        values not found in a dict will be forwarded unchanged.\n\n    Examples\n    --------\n    The following deprecates 'cols', using 'columns' instead\n\n    >>> @deprecate_kwarg(old_arg_name='cols', new_arg_name='columns')\n    ... def f(columns=''):\n    ...     print(columns)\n    ...\n    >>> f(columns='should work ok')\n    should work ok\n    >>> f(cols='should raise warning')\n    FutureWarning: cols is deprecated, use columns instead\n      warnings.warn(msg, FutureWarning)\n    should raise warning\n    >>> f(cols='should error', columns=\"can't pass do both\")\n    TypeError: Can only specify 'cols' or 'columns', not both\n    >>> @deprecate_kwarg('old', 'new', {'yes': True, 'no', False})\n    ... def f(new=False):\n    ...     print('yes!' if new else 'no!')\n    ...\n    >>> f(old='yes')\n    FutureWarning: old='yes' is deprecated, use new=True instead\n      warnings.warn(msg, FutureWarning)\n    yes!\n\n    \"\"\"\n    if mapping is not None and not hasattr(mapping, 'get') and \\\n            not callable(mapping):\n        raise TypeError(\"mapping from old to new argument values \"\n                        \"must be dict or callable!\")\n    def _deprecate_kwarg(func):\n        @wraps(func)\n        def wrapper(*args, **kwargs):\n            old_arg_value = kwargs.pop(old_arg_name, None)\n            if old_arg_value is not None:\n                if mapping is not None:\n                    if hasattr(mapping, 'get'):\n                        new_arg_value = mapping.get(old_arg_value,\n                                                    old_arg_value)\n                    else:\n                        new_arg_value = mapping(old_arg_value)\n                    msg = \"the %s=%r keyword is deprecated, \" \\\n                          \"use %s=%r instead\" % \\\n                          (old_arg_name, old_arg_value,\n                           new_arg_name, new_arg_value)\n                else:\n                    new_arg_value = old_arg_value\n                    msg = \"the '%s' keyword is deprecated, \" \\\n                          \"use '%s' instead\" % (old_arg_name, new_arg_name)\n                warnings.warn(msg, FutureWarning)\n                if kwargs.get(new_arg_name, None) is not None:\n                    msg = \"Can only specify '%s' or '%s', not both\" % \\\n                      (old_arg_name, new_arg_name)\n                    raise TypeError(msg)\n                else:\n                    kwargs[new_arg_name] = new_arg_value\n            return func(*args, **kwargs)\n        return wrapper\n    return _deprecate_kwarg\n\n\n# Substitution and Appender are derived from matplotlib.docstring (1.1.0)\n# module http://matplotlib.sourceforge.net/users/license.html\n\n\nclass Substitution(object):\n    \"\"\"\n    A decorator to take a function's docstring and perform string\n    substitution on it.\n\n    This decorator should be robust even if func.__doc__ is None\n    (for example, if -OO was passed to the interpreter)\n\n    Usage: construct a docstring.Substitution with a sequence or\n    dictionary suitable for performing substitution; then\n    decorate a suitable function with the constructed object. e.g.\n\n    sub_author_name = Substitution(author='Jason')\n\n    @sub_author_name\n    def some_function(x):\n        \"%(author)s wrote this function\"\n\n    # note that some_function.__doc__ is now \"Jason wrote this function\"\n\n    One can also use positional arguments.\n\n    sub_first_last_names = Substitution('Edgar Allen', 'Poe')\n\n    @sub_first_last_names\n    def some_function(x):\n        \"%s %s wrote the Raven\"\n    \"\"\"\n    def __init__(self, *args, **kwargs):\n        if (args and kwargs):\n            raise AssertionError( \"Only positional or keyword args are allowed\")\n\n        self.params = args or kwargs\n\n    def __call__(self, func):\n        func.__doc__ = func.__doc__ and func.__doc__ % self.params\n        return func\n\n    def update(self, *args, **kwargs):\n        \"Assume self.params is a dict and update it with supplied args\"\n        self.params.update(*args, **kwargs)\n\n    @classmethod\n    def from_params(cls, params):\n        \"\"\"\n        In the case where the params is a mutable sequence (list or dictionary)\n        and it may change before this class is called, one may explicitly use a\n        reference to the params rather than using *args or **kwargs which will\n        copy the values and not reference them.\n        \"\"\"\n        result = cls()\n        result.params = params\n        return result\n\n\nclass Appender(object):\n    \"\"\"\n    A function decorator that will append an addendum to the docstring\n    of the target function.\n\n    This decorator should be robust even if func.__doc__ is None\n    (for example, if -OO was passed to the interpreter).\n\n    Usage: construct a docstring.Appender with a string to be joined to\n    the original docstring. An optional 'join' parameter may be supplied\n    which will be used to join the docstring and addendum. e.g.\n\n    add_copyright = Appender(\"Copyright (c) 2009\", join='\\n')\n\n    @add_copyright\n    def my_dog(has='fleas'):\n        \"This docstring will have a copyright below\"\n        pass\n    \"\"\"\n    def __init__(self, addendum, join='', indents=0):\n        if indents > 0:\n            self.addendum = indent(addendum, indents=indents)\n        else:\n            self.addendum = addendum\n        self.join = join\n\n    def __call__(self, func):\n        func.__doc__ = func.__doc__ if func.__doc__ else ''\n        self.addendum = self.addendum if self.addendum else ''\n        docitems = [func.__doc__, self.addendum]\n        func.__doc__ = self.join.join(docitems)\n        return func\n\n\ndef indent(text, indents=1):\n    if not text or not isinstance(text, str):\n        return ''\n    jointext = ''.join(['\\n'] + ['    '] * indents)\n    return jointext.join(text.split('\\n'))\n\n\ndef suppress_stdout(f):\n    def wrapped(*args, **kwargs):\n        try:\n            sys.stdout = StringIO()\n            f(*args, **kwargs)\n        finally:\n            sys.stdout = sys.__stdout__\n\n    return wrapped\n\n\nclass KnownFailureTest(Exception):\n    '''Raise this exception to mark a test as a known failing test.'''\n    pass\n\n\ndef knownfailureif(fail_condition, msg=None):\n    \"\"\"\n    Make function raise KnownFailureTest exception if given condition is true.\n\n    If the condition is a callable, it is used at runtime to dynamically\n    make the decision. This is useful for tests that may require costly\n    imports, to delay the cost until the test suite is actually executed.\n\n    Parameters\n    ----------\n    fail_condition : bool or callable\n        Flag to determine whether to mark the decorated test as a known\n        failure (if True) or not (if False).\n    msg : str, optional\n        Message to give on raising a KnownFailureTest exception.\n        Default is None.\n\n    Returns\n    -------\n    decorator : function\n        Decorator, which, when applied to a function, causes SkipTest\n        to be raised when `skip_condition` is True, and the function\n        to be called normally otherwise.\n\n    Notes\n    -----\n    The decorator itself is decorated with the ``nose.tools.make_decorator``\n    function in order to transmit function name, and various other metadata.\n\n    \"\"\"\n    if msg is None:\n        msg = 'Test skipped due to known failure'\n\n    # Allow for both boolean or callable known failure conditions.\n    if callable(fail_condition):\n        fail_val = fail_condition\n    else:\n        fail_val = lambda: fail_condition\n\n    def knownfail_decorator(f):\n        # Local import to avoid a hard nose dependency and only incur the\n        # import time overhead at actual test-time.\n        import nose\n\n        def knownfailer(*args, **kwargs):\n            if fail_val():\n                raise KnownFailureTest(msg)\n            else:\n                return f(*args, **kwargs)\n        return nose.tools.make_decorator(f)(knownfailer)\n\n    return knownfail_decorator\n\ndef make_signature(func) :\n    \"\"\"\n    Returns a string repr of the arg list of a func call, with any defaults\n\n    Examples\n    --------\n\n    >>> def f(a,b,c=2) :\n    >>>     return a*b*c\n    >>> print(_make_signature(f))\n    a,b,c=2\n    \"\"\"\n    from inspect import getargspec\n    spec = getargspec(func)\n    if spec.defaults == None :\n        n_wo_defaults = len(spec.args)\n        defaults = ('',) * n_wo_defaults\n    else :\n        n_wo_defaults = len(spec.args) - len(spec.defaults)\n        defaults = ('',) * n_wo_defaults + spec.defaults\n    args = []\n    for i, (var, default) in enumerate(zip(spec.args, defaults)) :\n        args.append(var if default=='' else var+'='+repr(default))\n    if spec.varargs:\n        args.append('*' + spec.varargs)\n    if spec.keywords:\n        args.append('**' + spec.keywords)\n    return args, spec.args\n\n", "path": "pandas/util/decorators.py"}]}