[python-package] mark EarlyStopException as part of public API

[jameslamb]

Doing some research for another contribution, I found that several large projects rely on importing lightgbm.callback.EarlyStopException, and using it to trigger early stopping in LightGBM.

• autogluon: https://github.com/autogluon/autogluon/blob/f77a7b4ea2f6140685e73ef41f3b533cea272391/tabular/src/autogluon/tabular/models/lgb/callbacks.py#L8
• FLAML: https://github.com/microsoft/FLAML/blob/4886cb56891af6ccf3e6d694bd97f571623fa6f8/flaml/automl/model.py#L1430

This PR proposes formally marking that class (and by extension, that mechanism of triggering early stopping) as a part of the public API, to prevent it from being removed or altered in a non-backward-compatible way in the future.

[jameslamb]

This allows for imports like

from lightgbm import EarlyStopException

or

import lightgbm as lgb

def _early_stop(env):
    raise lgb.EarlyStopException(
        best_iteration=6,
        best_score=[("some_validation_set", "some_metric", 0.708, True)]
     )

Every other part of the public API can be imported like this, and I think such imports should be encouraged over those that require knowing the internal sub-module structure like from lightgbm.callback import EarlyStopException

[jameslamb]

Thanks @jmoralez !

If you haven't seen it, take a look at those FLAML + autogluon links (and the wandb one in #6096). It was pretty interesting for me to see how other popular projects are using the callback system here to provide supported LightGBM integrations.

[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.