[python] rename `print_evaluation()` into `log_evaluation()` (#4604)

* Update __init__.py

* Update Python-API.rst

* Update engine.py

* Update test_utilities.py

* Update sklearn.py

* Update callback.py

* Update callback.py

* Update callback.py

docs/Python-API.rst

@@ -53,7 +53,7 @@ Callbacks
     :toctree: pythonapi/
 
     early_stopping
-    print_evaluation
+    log_evaluation
     record_evaluation
     reset_parameter
 

python-package/lightgbm/__init__.py

@@ -6,7 +6,7 @@ Contributors: https://github.com/microsoft/LightGBM/graphs/contributors.
 from pathlib import Path
 
 from .basic import Booster, Dataset, Sequence, register_logger
-from .callback import early_stopping, print_evaluation, record_evaluation, reset_parameter
+from .callback import early_stopping, log_evaluation, print_evaluation, record_evaluation, reset_parameter
 from .engine import CVBooster, cv, train
 
 try:
@@ -32,5 +32,5 @@ __all__ = ['Dataset', 'Booster', 'CVBooster', 'Sequence',
            'train', 'cv',
            'LGBMModel', 'LGBMRegressor', 'LGBMClassifier', 'LGBMRanker',
            'DaskLGBMRegressor', 'DaskLGBMClassifier', 'DaskLGBMRanker',
-           'print_evaluation', 'record_evaluation', 'reset_parameter', 'early_stopping',
+           'log_evaluation', 'print_evaluation', 'record_evaluation', 'reset_parameter', 'early_stopping',
            'plot_importance', 'plot_split_value_histogram', 'plot_metric', 'plot_tree', 'create_tree_digraph']

python-package/lightgbm/callback.py

@@ -52,6 +52,16 @@ def _format_eval_result(value: list, show_stdv: bool = True) -> str:
 def print_evaluation(period: int = 1, show_stdv: bool = True) -> Callable:
     """Create a callback that logs the evaluation results.
 
+    Deprecated, use ``log_evaluation()`` instead.
+    """
+    _log_warning("'print_evaluation()' callback is deprecated and will be removed in a future release of LightGBM. "
+                 "Use 'log_evaluation()' callback instead.")
+    return log_evaluation(period=period, show_stdv=show_stdv)
+
+
+def log_evaluation(period: int = 1, show_stdv: bool = True) -> Callable:
+    """Create a callback that logs the evaluation results.
+
     By default, standard output resource is used.
     Use ``register_logger()`` function to register a custom logger.
 

python-package/lightgbm/engine.py

@@ -238,16 +238,16 @@ def train(
     # Most of legacy advanced options becomes callbacks
     if verbose_eval != "warn":
         _log_warning("'verbose_eval' argument is deprecated and will be removed in a future release of LightGBM. "
-                     "Pass 'print_evaluation()' callback via 'callbacks' argument instead.")
+                     "Pass 'log_evaluation()' callback via 'callbacks' argument instead.")
     else:
-        if callbacks:  # assume user has already specified print_evaluation callback
+        if callbacks:  # assume user has already specified log_evaluation callback
             verbose_eval = False
         else:
             verbose_eval = True
     if verbose_eval is True:
-        callbacks.add(callback.print_evaluation())
+        callbacks.add(callback.log_evaluation())
     elif isinstance(verbose_eval, int):
-        callbacks.add(callback.print_evaluation(verbose_eval))
+        callbacks.add(callback.log_evaluation(verbose_eval))
 
     if early_stopping_rounds is not None and early_stopping_rounds > 0:
         callbacks.add(callback.early_stopping(early_stopping_rounds, first_metric_only, verbose=bool(verbose_eval)))
@@ -619,11 +619,11 @@ def cv(params, train_set, num_boost_round=100,
         callbacks.add(callback.early_stopping(early_stopping_rounds, first_metric_only, verbose=False))
     if verbose_eval is not None:
         _log_warning("'verbose_eval' argument is deprecated and will be removed in a future release of LightGBM. "
-                     "Pass 'print_evaluation()' callback via 'callbacks' argument instead.")
+                     "Pass 'log_evaluation()' callback via 'callbacks' argument instead.")
     if verbose_eval is True:
-        callbacks.add(callback.print_evaluation(show_stdv=show_stdv))
+        callbacks.add(callback.log_evaluation(show_stdv=show_stdv))
     elif isinstance(verbose_eval, int):
-        callbacks.add(callback.print_evaluation(verbose_eval, show_stdv=show_stdv))
+        callbacks.add(callback.log_evaluation(verbose_eval, show_stdv=show_stdv))
 
     callbacks_before_iter = {cb for cb in callbacks if getattr(cb, 'before_iteration', False)}
     callbacks_after_iter = callbacks - callbacks_before_iter

python-package/lightgbm/sklearn.py

@@ -7,7 +7,7 @@ from typing import Callable, Dict, Optional, Union
 import numpy as np
 
 from .basic import Dataset, LightGBMError, _choose_param_value, _ConfigAliases, _log_warning
-from .callback import print_evaluation, record_evaluation
+from .callback import log_evaluation, record_evaluation
 from .compat import (SKLEARN_INSTALLED, LGBMNotFittedError, _LGBMAssertAllFinite, _LGBMCheckArray,
                      _LGBMCheckClassificationTargets, _LGBMCheckSampleWeight, _LGBMCheckXY, _LGBMClassifierBase,
                      _LGBMComputeSampleWeight, _LGBMLabelEncoder, _LGBMModelBase, _LGBMRegressorBase, dt_DataTable,
@@ -731,13 +731,13 @@ class LGBMModel(_LGBMModelBase):
 
         if verbose != 'warn':
             _log_warning("'verbose' argument is deprecated and will be removed in a future release of LightGBM. "
-                         "Pass 'print_evaluation()' callback via 'callbacks' argument instead.")
+                         "Pass 'log_evaluation()' callback via 'callbacks' argument instead.")
         else:
-            if callbacks:  # assume user has already specified print_evaluation callback
+            if callbacks:  # assume user has already specified log_evaluation callback
                 verbose = False
             else:
                 verbose = True
-        callbacks.append(print_evaluation(int(verbose)))
+        callbacks.append(log_evaluation(int(verbose)))
 
         evals_result = {}
         callbacks.append(record_evaluation(evals_result))

tests/python_package_test/test_utilities.py

@@ -33,7 +33,7 @@ def test_register_logger(tmp_path):
     eval_records = {}
     callbacks = [
         lgb.record_evaluation(eval_records),
-        lgb.print_evaluation(2),
+        lgb.log_evaluation(2),
         lgb.early_stopping(4)
     ]
     lgb.train({'objective': 'binary', 'metric': ['auc', 'binary_error']},