[docs][python] Refer to functions as callable in docstrings (#4575)

python-package/lightgbm/basic.py

@@ -1130,7 +1130,7 @@ class Dataset:
 
         Parameters
         ----------
-        data : str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, Sequence, list of Sequences or list of numpy arrays
+        data : str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, Sequence, list of Sequence or list of numpy array
             Data source of Dataset.
             If str or pathlib.Path, it represents the path to a text file (CSV, TSV, or LibSVM) or a LightGBM Dataset binary file.
         label : list, numpy 1-D array, pandas Series / one-column DataFrame or None, optional (default=None)
@@ -1260,9 +1260,9 @@ class Dataset:
 
         Parameters
         ----------
-        sample_data : list of numpy arrays
+        sample_data : list of numpy array
             Sample data for each column.
-        sample_indices : list of numpy arrays
+        sample_indices : list of numpy array
             Sample data row index for each column.
         sample_cnt : int
             Number of samples.
@@ -1774,7 +1774,7 @@ class Dataset:
 
         Parameters
         ----------
-        data : str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, Sequence, list of Sequences or list of numpy arrays
+        data : str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, Sequence, list of Sequence or list of numpy array
             Data source of Dataset.
             If str or pathlib.Path, it represents the path to a text file (CSV, TSV, or LibSVM) or a LightGBM Dataset binary file.
         label : list, numpy 1-D array, pandas Series / one-column DataFrame or None, optional (default=None)
@@ -2241,7 +2241,7 @@ class Dataset:
 
         Returns
         -------
-        data : str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, Sequence, list of Sequences or list of numpy arrays or None
+        data : str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, Sequence, list of Sequence or list of numpy array or None
             Raw data used in the Dataset construction.
         """
         if self.handle is None:

python-package/lightgbm/callback.py

@@ -61,7 +61,7 @@ def print_evaluation(period: int = 1, show_stdv: bool = True) -> Callable:
 
     Returns
     -------
-    callback : function
+    callback : callable
         The callback that prints the evaluation results every ``period`` iteration(s).
     """
     def _callback(env: CallbackEnv) -> None:
@@ -84,7 +84,7 @@ def record_evaluation(eval_result: Dict[str, Dict[str, List[Any]]]) -> Callable:
 
     Returns
     -------
-    callback : function
+    callback : callable
         The callback that records the evaluation history into the passed dictionary.
     """
     if not isinstance(eval_result, dict):
@@ -114,16 +114,16 @@ def reset_parameter(**kwargs: Union[list, Callable]) -> Callable:
 
     Parameters
     ----------
-    **kwargs : value should be list or function
+    **kwargs : value should be list or callable
         List of parameters for each boosting round
-        or a customized function that calculates the parameter in terms of
+        or a callable that calculates the parameter in terms of
         current number of round (e.g. yields learning rate decay).
         If list lst, parameter = lst[current_round].
-        If function func, parameter = func(current_round).
+        If callable func, parameter = func(current_round).
 
     Returns
     -------
-    callback : function
+    callback : callable
         The callback that resets the parameter after the first iteration.
     """
     def _callback(env: CallbackEnv) -> None:
@@ -167,7 +167,7 @@ def early_stopping(stopping_rounds: int, first_metric_only: bool = False, verbos
 
     Returns
     -------
-    callback : function
+    callback : callable
         The callback that activates early stopping.
     """
     best_score = []

python-package/lightgbm/dask.py

@@ -435,13 +435,13 @@ def _train(
         of evals_result_ and best_score_ will be 'not_evaluated'.
     eval_names : list of str, or None, optional (default=None)
         Names of eval_set.
-    eval_sample_weight : list of Dask Arrays or Dask Series, or None, optional (default=None)
+    eval_sample_weight : list of Dask Array or Dask Series, or None, optional (default=None)
         Weights for each validation set in eval_set.
     eval_class_weight : list of dict or str, or None, optional (default=None)
         Class weights, one dict or str for each validation set in eval_set.
-    eval_init_score : list of Dask Arrays or Dask Series, or None, optional (default=None)
+    eval_init_score : list of Dask Array or Dask Series, or None, optional (default=None)
         Initial model score for each validation set in eval_set.
-    eval_group : list of Dask Arrays or Dask Series, or None, optional (default=None)
+    eval_group : list of Dask Array or Dask Series, or None, optional (default=None)
         Group/query for each validation set in eval_set.
     eval_metric : str, callable, list or None, optional (default=None)
         If str, it should be a built-in evaluation metric to use.
@@ -1194,9 +1194,9 @@ class DaskLGBMClassifier(LGBMClassifier, _DaskLGBMModel):
         sample_weight_shape="Dask Array or Dask Series of shape = [n_samples] or None, optional (default=None)",
         init_score_shape="Dask Array or Dask Series of shape = [n_samples] or None, optional (default=None)",
         group_shape="Dask Array or Dask Series or None, optional (default=None)",
-        eval_sample_weight_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)",
-        eval_init_score_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)",
-        eval_group_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)"
+        eval_sample_weight_shape="list of Dask Array or Dask Series, or None, optional (default=None)",
+        eval_init_score_shape="list of Dask Array or Dask Series, or None, optional (default=None)",
+        eval_group_shape="list of Dask Array or Dask Series, or None, optional (default=None)"
     )
 
     # DaskLGBMClassifier does not support group, eval_group, early_stopping_rounds.
@@ -1371,9 +1371,9 @@ class DaskLGBMRegressor(LGBMRegressor, _DaskLGBMModel):
         sample_weight_shape="Dask Array or Dask Series of shape = [n_samples] or None, optional (default=None)",
         init_score_shape="Dask Array or Dask Series of shape = [n_samples] or None, optional (default=None)",
         group_shape="Dask Array or Dask Series or None, optional (default=None)",
-        eval_sample_weight_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)",
-        eval_init_score_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)",
-        eval_group_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)"
+        eval_sample_weight_shape="list of Dask Array or Dask Series, or None, optional (default=None)",
+        eval_init_score_shape="list of Dask Array or Dask Series, or None, optional (default=None)",
+        eval_group_shape="list of Dask Array or Dask Series, or None, optional (default=None)"
     )
 
     # DaskLGBMRegressor does not support group, eval_class_weight, eval_group, early_stopping_rounds.
@@ -1538,9 +1538,9 @@ class DaskLGBMRanker(LGBMRanker, _DaskLGBMModel):
         sample_weight_shape="Dask Array or Dask Series of shape = [n_samples] or None, optional (default=None)",
         init_score_shape="Dask Array or Dask Series of shape = [n_samples] or None, optional (default=None)",
         group_shape="Dask Array or Dask Series or None, optional (default=None)",
-        eval_sample_weight_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)",
-        eval_init_score_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)",
-        eval_group_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)"
+        eval_sample_weight_shape="list of Dask Array or Dask Series, or None, optional (default=None)",
+        eval_init_score_shape="list of Dask Array or Dask Series, or None, optional (default=None)",
+        eval_group_shape="list of Dask Array or Dask Series, or None, optional (default=None)"
     )
 
     # DaskLGBMRanker does not support eval_class_weight or early stopping

python-package/lightgbm/engine.py

@@ -50,7 +50,7 @@ def train(
         Data to be trained on.
     num_boost_round : int, optional (default=100)
         Number of boosting iterations.
-    valid_sets : list of Datasets, or None, optional (default=None)
+    valid_sets : list of Dataset, or None, optional (default=None)
         List of data to be evaluated on during training.
     valid_names : list of str, or None, optional (default=None)
         Names of ``valid_sets``.
@@ -76,7 +76,7 @@ def train(
         If you want to get i-th row preds in j-th class, the access way is score[j * num_data + i]
         and you should group grad and hess in this way as well.
 
-    feval : callable, list of callable functions, or None, optional (default=None)
+    feval : callable, list of callable, or None, optional (default=None)
         Customized evaluation function.
         Each evaluation function should accept two parameters: preds, train_data,
         and return (eval_name, eval_result, is_higher_better) or list of such tuples.
@@ -147,7 +147,7 @@ def train(
 
     learning_rates : list, callable or None, optional (default=None)
         List of learning rates for each boosting round
-        or a customized function that calculates ``learning_rate``
+        or a callable that calculates ``learning_rate``
         in terms of current number of round (e.g. yields learning rate decay).
     keep_training_booster : bool, optional (default=False)
         Whether the returned Booster will be used to keep training.
@@ -156,7 +156,7 @@ def train(
         When your model is very large and cause the memory error,
         you can try to set this param to ``True`` to avoid the model conversion performed during the internal call of ``model_to_string``.
         You can still use _InnerPredictor as ``init_model`` for future continue training.
-    callbacks : list of callables, or None, optional (default=None)
+    callbacks : list of callable, or None, optional (default=None)
         List of callback functions that are applied at each iteration.
         See Callbacks in Python API for more information.
 
@@ -472,7 +472,7 @@ def cv(params, train_set, num_boost_round=100,
         If you want to get i-th row preds in j-th class, the access way is score[j * num_data + i]
         and you should group grad and hess in this way as well.
 
-    feval : callable, list of callable functions, or None, optional (default=None)
+    feval : callable, list of callable, or None, optional (default=None)
         Customized evaluation function.
         Each evaluation function should accept two parameters: preds, train_data,
         and return (eval_name, eval_result, is_higher_better) or list of such tuples.
@@ -528,7 +528,7 @@ def cv(params, train_set, num_boost_round=100,
         Results are not affected by this parameter, and always contain std.
     seed : int, optional (default=0)
         Seed used to generate the folds (passed to numpy.random.seed).
-    callbacks : list of callables, or None, optional (default=None)
+    callbacks : list of callable, or None, optional (default=None)
         List of callback functions that are applied at each iteration.
         See Callbacks in Python API for more information.
     eval_train_metric : bool, optional (default=False)

python-package/lightgbm/sklearn.py

@@ -253,7 +253,7 @@ _lgbmmodel_doc_fit = (
         Large values could be memory consuming. Consider using consecutive integers starting from zero.
         All negative values in categorical features will be treated as missing values.
         The output cannot be monotonically constrained with respect to a categorical feature.
-    callbacks : list of callback functions, or None, optional (default=None)
+    callbacks : list of callable, or None, optional (default=None)
         List of callback functions that are applied at each iteration.
         See Callbacks in Python API for more information.
     init_model : str, pathlib.Path, Booster, LGBMModel or None, optional (default=None)
@@ -737,9 +737,9 @@ class LGBMModel(_LGBMModelBase):
         sample_weight_shape="array-like of shape = [n_samples] or None, optional (default=None)",
         init_score_shape="array-like of shape = [n_samples] or None, optional (default=None)",
         group_shape="array-like or None, optional (default=None)",
-        eval_sample_weight_shape="list of arrays, or None, optional (default=None)",
-        eval_init_score_shape="list of arrays, or None, optional (default=None)",
-        eval_group_shape="list of arrays, or None, optional (default=None)"
+        eval_sample_weight_shape="list of array, or None, optional (default=None)",
+        eval_init_score_shape="list of array, or None, optional (default=None)",
+        eval_group_shape="list of array, or None, optional (default=None)"
     ) + "\n\n" + _lgbmmodel_doc_custom_eval_note
 
     def predict(self, X, raw_score=False, start_iteration=0, num_iteration=None,