[doc] Clarify that states in callbacks are mutated. (#7685)

* Fix copy for cv.  This prevents inserting default callbacks into the input list.
* Clarify the behavior of callbacks in training/cv.
* Fix typos in doc.

python-package/xgboost/callback.py

@@ -256,7 +256,7 @@ class LearningRateScheduler(TrainingCallback):
     Parameters
     ----------
 
-    learning_rates : callable/collections.Sequence
+    learning_rates :
         If it's a callable object, then it should accept an integer parameter
         `epoch` and returns the corresponding learning rate.  Otherwise it
         should be a sequence like list or tuple with the same size of boosting

python-package/xgboost/sklearn.py

@@ -286,13 +286,21 @@ __model_doc = f'''
 
     callbacks : Optional[List[TrainingCallback]]
         List of callback functions that are applied at end of each iteration.
-        It is possible to use predefined callbacks by using :ref:`callback_api`.
+        It is possible to use predefined callbacks by using
-        Example:
+        :ref:`Callback API <callback_api>`.
+
+        .. note::
+
+           States in callback are not preserved during training, which means callback
+           objects can not be reused for multiple training sessions without
+           reinitialization or deepcopy.
 
         .. code-block:: python
 
-            callbacks = [xgb.callback.EarlyStopping(rounds=early_stopping_rounds,
+            for params in parameters_grid:
-                                                    save_best=True)]
+                # be sure to (re)initialize the callbacks before each run
+                callbacks = [xgb.callback.LearningRateScheduler(custom_rates)]
+                xgboost.train(params, Xy, callbacks=callbacks)
 
     kwargs : dict, optional
         Keyword arguments for XGBoost Booster object.  Full documentation of parameters
@@ -916,8 +924,8 @@ class XGBModel(XGBModelBase):
             otherwise a `ValueError` is thrown.
 
         callbacks :
-            .. deprecated: 1.6.0
+            .. deprecated:: 1.6.0
-                Use `callbacks` in :py:meth:`__init__` or :py:methd:`set_params` instead.
+                Use `callbacks` in :py:meth:`__init__` or :py:meth:`set_params` instead.
         """
         evals_result: TrainingCallback.EvalsLog = {}
         train_dmatrix, evals = _wrap_evaluation_matrices(
@@ -1791,8 +1799,8 @@ class XGBRanker(XGBModel, XGBRankerMixIn):
             otherwise a `ValueError` is thrown.
 
         callbacks :
-            .. deprecated: 1.6.0
+            .. deprecated:: 1.6.0
-                Use `callbacks` in :py:meth:`__init__` or :py:methd:`set_params` instead.
+                Use `callbacks` in :py:meth:`__init__` or :py:meth:`set_params` instead.
         """
         # check if group information is provided
         if group is None and qid is None:

python-package/xgboost/training.py

@@ -123,11 +123,19 @@ def train(
         List of callback functions that are applied at end of each iteration.
         It is possible to use predefined callbacks by using
         :ref:`Callback API <callback_api>`.
-        Example:
+
+        .. note::
+
+           States in callback are not preserved during training, which means callback
+           objects can not be reused for multiple training sessions without
+           reinitialization or deepcopy.
 
         .. code-block:: python
 
-            [xgb.callback.LearningRateScheduler(custom_rates)]
+            for params in parameters_grid:
+                # be sure to (re)initialize the callbacks before each run
+                callbacks = [xgb.callback.LearningRateScheduler(custom_rates)]
+                xgboost.train(params, Xy, callbacks=callbacks)
 
     custom_metric:
 
@@ -416,15 +424,24 @@ def cv(params, dtrain, num_boost_round=10, nfold=3, stratified=False, folds=None
         Results are not affected, and always contains std.
     seed : int
         Seed used to generate the folds (passed to numpy.random.seed).
-    callbacks : list of callback functions
+    callbacks :
         List of callback functions that are applied at end of each iteration.
         It is possible to use predefined callbacks by using
         :ref:`Callback API <callback_api>`.
-        Example:
+
+        .. note::
+
+           States in callback are not preserved during training, which means callback
+           objects can not be reused for multiple training sessions without
+           reinitialization or deepcopy.
 
         .. code-block:: python
 
-            [xgb.callback.LearningRateScheduler(custom_rates)]
+            for params in parameters_grid:
+                # be sure to (re)initialize the callbacks before each run
+                callbacks = [xgb.callback.LearningRateScheduler(custom_rates)]
+                xgboost.train(params, Xy, callbacks=callbacks)
+
     shuffle : bool
         Shuffle data before creating folds.
     custom_metric :
@@ -467,7 +484,7 @@ def cv(params, dtrain, num_boost_round=10, nfold=3, stratified=False, folds=None
     metric_fn = _configure_custom_metric(feval, custom_metric)
 
     # setup callbacks
-    callbacks = [] if callbacks is None else callbacks
+    callbacks = [] if callbacks is None else copy.copy(list(callbacks))
     _assert_new_callback(callbacks)
 
     if verbose_eval: