Skip to content

Commit 42a5c1c

Browse files
authored
DOC: Make doc decorator a class and replace Appender by doc (#33160)
1 parent f26d3d5 commit 42a5c1c

File tree

3 files changed

+29
-33
lines changed

3 files changed

+29
-33
lines changed

pandas/core/arrays/datetimelike.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -757,7 +757,7 @@ def _validate_shift_value(self, fill_value):
757757
"will raise in a future version, pass "
758758
f"{self._scalar_type.__name__} instead.",
759759
FutureWarning,
760-
stacklevel=10,
760+
stacklevel=8,
761761
)
762762
fill_value = new_fill
763763

pandas/tseries/offsets.py

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@
3535
to_dt64D,
3636
)
3737
from pandas.errors import AbstractMethodError
38-
from pandas.util._decorators import Appender, Substitution, cache_readonly
38+
from pandas.util._decorators import cache_readonly, doc
3939

4040
__all__ = [
4141
"Day",
@@ -877,11 +877,12 @@ class BusinessMonthBegin(MonthOffset):
877877
_day_opt = "business_start"
878878

879879

880+
@doc(bound="bound")
880881
class _CustomBusinessMonth(CustomMixin, BusinessMixin, MonthOffset):
881882
"""
882883
DateOffset subclass representing custom business month(s).
883884
884-
Increments between %(bound)s of month dates.
885+
Increments between {bound} of month dates.
885886
886887
Parameters
887888
----------
@@ -971,14 +972,12 @@ def apply(self, other):
971972
return result
972973

973974

974-
@Substitution(bound="end")
975-
@Appender(_CustomBusinessMonth.__doc__)
975+
@doc(_CustomBusinessMonth, bound="end")
976976
class CustomBusinessMonthEnd(_CustomBusinessMonth):
977977
_prefix = "CBM"
978978

979979

980-
@Substitution(bound="beginning")
981-
@Appender(_CustomBusinessMonth.__doc__)
980+
@doc(_CustomBusinessMonth, bound="beginning")
982981
class CustomBusinessMonthBegin(_CustomBusinessMonth):
983982
_prefix = "CBMS"
984983

pandas/util/_decorators.py

Lines changed: 23 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -329,55 +329,52 @@ def wrapper(*args, **kwargs) -> Callable[..., Any]:
329329
return decorate
330330

331331

332-
def doc(*args: Union[str, Callable], **kwargs) -> Callable[[F], F]:
332+
def doc(*docstrings: Union[str, Callable], **params) -> Callable[[F], F]:
333333
"""
334334
A decorator take docstring templates, concatenate them and perform string
335335
substitution on it.
336336
337337
This decorator will add a variable "_docstring_components" to the wrapped
338-
function to keep track the original docstring template for potential usage.
338+
callable to keep track the original docstring template for potential usage.
339339
If it should be consider as a template, it will be saved as a string.
340340
Otherwise, it will be saved as callable, and later user __doc__ and dedent
341341
to get docstring.
342342
343343
Parameters
344344
----------
345-
*args : str or callable
345+
*docstrings : str or callable
346346
The string / docstring / docstring template to be appended in order
347-
after default docstring under function.
348-
**kwargs
349-
The objects which would be used to format docstring template.
347+
after default docstring under callable.
348+
**params
349+
The string which would be used to format docstring template.
350350
"""
351351

352-
def decorator(func: F) -> F:
353-
@wraps(func)
354-
def wrapper(*args, **kwargs) -> Callable:
355-
return func(*args, **kwargs)
356-
352+
def decorator(decorated: F) -> F:
357353
# collecting docstring and docstring templates
358354
docstring_components: List[Union[str, Callable]] = []
359-
if func.__doc__:
360-
docstring_components.append(dedent(func.__doc__))
355+
if decorated.__doc__:
356+
docstring_components.append(dedent(decorated.__doc__))
361357

362-
for arg in args:
363-
if hasattr(arg, "_docstring_components"):
364-
docstring_components.extend(arg._docstring_components) # type: ignore
365-
elif isinstance(arg, str) or arg.__doc__:
366-
docstring_components.append(arg)
358+
for docstring in docstrings:
359+
if hasattr(docstring, "_docstring_components"):
360+
docstring_components.extend(
361+
docstring._docstring_components # type: ignore
362+
)
363+
elif isinstance(docstring, str) or docstring.__doc__:
364+
docstring_components.append(docstring)
367365

368366
# formatting templates and concatenating docstring
369-
wrapper.__doc__ = "".join(
367+
decorated.__doc__ = "".join(
370368
[
371-
arg.format(**kwargs)
372-
if isinstance(arg, str)
373-
else dedent(arg.__doc__ or "")
374-
for arg in docstring_components
369+
component.format(**params)
370+
if isinstance(component, str)
371+
else dedent(component.__doc__ or "")
372+
for component in docstring_components
375373
]
376374
)
377375

378-
wrapper._docstring_components = docstring_components # type: ignore
379-
380-
return cast(F, wrapper)
376+
decorated._docstring_components = docstring_components # type: ignore
377+
return decorated
381378

382379
return decorator
383380

0 commit comments

Comments
 (0)