[python-package] add type hints on Booster eval methods

[jameslamb]

Contributes to #3756 and #3867.

Adds type hints on the following closely-related methods.

• Booster.eval()
• Booster.eval_train()
• Booster.eval_valid()
• Booster.__inner_eval()

Modifies docstrings for those methods to be a bit more informative about the structure of the returned tuples.

Modifies type hints for other methods using the results of these methods so that they share the same definitions imported across different files.

How I tested this

Used the following small sample code to test these return types.

test code (click me)

import lightgbm as lgb
from sklearn.datasets import make_blobs

def _single_tuple_metric(preds, ds):
    return ("single_tuple", 1.0, True)

def _list_of_tuples_metric(preds, ds):
    return [("list_id_0", 2.0, True), ("list_id_1", 2.0, True)]

X, y = make_blobs(n_samples=1234, centers=[[-4, -4], [-4, 4]])
dtrain = lgb.Dataset(X, y)

Notes for Reviewers

This PR introduces 6 new mypy errors.

python-package/lightgbm/engine.py:250: error: Argument 1 to "eval_train" of "Booster" has incompatible type "Union[Callable[[ndarray[Any, Any], Dataset], Tuple[str, float, bool]], List[Callable[[ndarray[Any, Any], Dataset], Tuple[str, float, bool]]], None]"; expected "Union[Callable[[ndarray[Any, Any], Dataset], Any], Callable[[ndarray[Any, Any], Dataset], List[Any]], List[Union[Callable[[ndarray[Any, Any], Dataset], Any], Callable[[ndarray[Any, Any], Dataset], List[Any]]]], None]"
python-package/lightgbm/engine.py:251: error: Argument 1 to "eval_valid" of "Booster" has incompatible type "Union[Callable[[ndarray[Any, Any], Dataset], Tuple[str, float, bool]], List[Callable[[ndarray[Any, Any], Dataset], Tuple[str, float, bool]]], None]"; expected "Union[Callable[[ndarray[Any, Any], Dataset], Any], Callable[[ndarray[Any, Any], Dataset], List[Any]], List[Union[Callable[[ndarray[Any, Any], Dataset], Any], Callable[[ndarray[Any, Any], Dataset], List[Any]]]], None]"
python-package/lightgbm/engine.py:262: error: Incompatible types in assignment (expression has type "Union[List[Tuple[str, str, float, bool]], List[Tuple[str, str, float, bool, float]]]", variable has type "List[Tuple[str, str, float, bool]]")
python-package/lightgbm/sklearn.py:190: error: Incompatible return value type (got "Union[Tuple[str, float, bool], List[Tuple[str, float, bool]]]", expected "Tuple[str, float, bool]")
python-package/lightgbm/sklearn.py:192: error: Incompatible return value type (got "Union[Tuple[str, float, bool], List[Tuple[str, float, bool]]]", expected "Tuple[str, float, bool]")
python-package/lightgbm/sklearn.py:194: error: Incompatible return value type (got "Union[Tuple[str, float, bool], List[Tuple[str, float, bool]]]", expected "Tuple[str, float, bool]")

I think this is a result of how mypy deals with overwriting a local variable with a different type than the first type it was instantiated with.

I believe investigating and fixing these will be non-trivial, and I'm proposing that we defer fixing them to separate PRs targeting #3867.

[github-actions]

This pull request has been automatically locked since there has not been any recent activity since it was closed. To start a new related discussion, open a new issue at https://github.com/microsoft/LightGBM/issues including a reference to this.