def doc_qc_method(
template,
params=None,
refer_to=None,
refer_to_module_name=None,
one_column_method=False,
**kwargs,
):
"""
Build decorator which adds docstring for query compiler method.
Parameters
----------
template : str
Method docstring in the NumPy docstyle format. Must contain {params}
placeholder.
params : str, optional
Method parameters in the NumPy docstyle format to substitute
in the `template`. `params` string should not include the "Parameters"
header.
refer_to : str, optional
Method name in `refer_to_module_name` module to refer to for more information
about parameters and output format.
refer_to_module_name : str, optional
one_column_method : bool, default: False
Whether to append note that this method is for one-column
query compilers only.
**kwargs : dict
Values to substitute in the `template`.
Returns
-------
callable
"""
params_template = """
Parameters
----------
{params}
"""
params = format_string(params_template, params=params) if params else ""
substituted = format_string(template, params=params, refer_to=refer_to, **kwargs)
if refer_to_module_name:
refer_to = f"{refer_to_module_name}.{refer_to}"
def decorator(func):
func.__doc__ = substituted
appendix = ""
if refer_to:
appendix += _refer_to_note.format(refer_to)
if one_column_method:
appendix += _one_column_warning
if appendix:
func = append_to_docstring(appendix)(func)
return func
return decorator
def doc_resample_reduce(result, refer_to, params=None, compatibility_params=True):
"""
Build decorator which adds docstring for the resample reduce method.
Parameters
----------
result : str
The result of the method.
refer_to : str
Method name in ``modin.pandas.resample.Resampler`` module to refer to for
more information about parameters and output format.
params : str, optional
Method parameters in the NumPy docstyle format to substitute
to the docstring template.
compatibility_params : bool, default: True
Whether method takes `*args` and `**kwargs` that do not affect
the result.
Returns
-------
callable
"""
action = f"compute {result} for each group"
params_substitution = (
(
"""
*args : iterable
Serves the compatibility purpose. Does not affect the result.
**kwargs : dict
Serves the compatibility purpose. Does not affect the result.
"""
)
if compatibility_params
else ""
)
if params:
params_substitution = format_string(
"{params}\n{params_substitution}",
params=params,
params_substitution=params_substitution,
)
build_rules = f"""
- Labels on the specified axis are the group names (time-stamps)
- Labels on the opposit of specified axis are preserved.
- Each element of QueryCompiler is the {result} for the
corresponding group and column/row."""
return doc_resample(
action=action,
extra_params=params_substitution,
build_rules=build_rules,
refer_to=refer_to,
)
def doc_resample_agg(action, output, refer_to, params=None):
"""
Build decorator which adds docstring for the resample aggregation method.
Parameters
----------
action : str
What method does with the resampled data.
output : str
What is the content of column names in the result.
refer_to : str
Method name in ``modin.pandas.resample.Resampler`` module to refer to for
more information about parameters and output format.
params : str, optional
Method parameters in the NumPy docstyle format to substitute
to the docstring template.
Returns
-------
callable
"""
action = f"{action} for each group over the specified axis"
params_substitution = """
*args : iterable
Positional arguments to pass to the aggregation function.
**kwargs : dict
Keyword arguments to pass to the aggregation function.
"""
if params:
params_substitution = format_string(
"{params}\n{params_substitution}",
params=params,
params_substitution=params_substitution,
)
build_rules = f"""
- Labels on the specified axis are the group names (time-stamps)
- Labels on the opposit of specified axis are a MultiIndex, where first level
contains preserved labels of this axis and the second level is the {output}.
- Each element of QueryCompiler is the result of corresponding function for the
corresponding group and column/row."""
return doc_resample(
action=action,
extra_params=params_substitution,
build_rules=build_rules,
refer_to=refer_to,
)
def doc_resample_fillna(method, refer_to, params=None, overwrite_template_params=False):
"""
Build decorator which adds docstring for the resample fillna query compiler method.
Parameters
----------
method : str
Fillna method name.
refer_to : str
Method name in ``modin.pandas.resample.Resampler`` module to refer to for
more information about parameters and output format.
params : str, optional
Method parameters in the NumPy docstyle format to substitute
to the docstring template.
overwrite_template_params : bool, default: False
If `params` is specified indicates whether to overwrite method parameters in
the docstring template or append then at the end.
Returns
-------
callable
"""
action = f"fill missing values in each group independently using {method} method"
params_substitution = "limit : int\n"
if params:
params_substitution = (
params
if overwrite_template_params
else format_string(
"{params}\n{params_substitution}",
params=params,
params_substitution=params_substitution,
)
)
build_rules = "- QueryCompiler contains unsampled data with missing values filled."
return doc_resample(
action=action,
extra_params=params_substitution,
build_rules=build_rules,
refer_to=refer_to,
)
