[tune] Deprecate tune.report, tune.checkpoint_dir, checkpoint_dir, and reporter

[justinvyu]

Why are these changes needed?

In 2.7, we’re unifying some key APIs and implementations to be in ray.train, and this has some impact on legacy Tune APIs that have either been deprecated or not recommended for a long time.

Before 2.0, but also supported through 2.6:

def train_fn(config, reporter, checkpoint_dir: str = None):
    if checkpoint_dir:  # [1]
        torch.load(...)
    reporter(loss=1, accuracy=0)  # [2]

    with tune.checkpoint_dir(step=0) as checkpoint_dir:  # [3]
         torch.save(...)

    tune.report(loss=1, accuracy=0)  # [4] -- same as [2]

results = tune.Tuner(train_fn).fit()

API for 2.7+:

def train_fn(config):
    checkpoint: train.Checkpoint = ray.train.get_checkpoint()  # [1]
    if checkpoint:
        with checkpoint.as_directory() as checkpoint_dir:
            torch.load(...)

    with tempfile.TemporaryDirectory() as temp_checkpoint_dir:
        torch.save(...)
        ray.train.report(
            {"loss": 1, "accuracy": 0},  # [2, 3]
            checkpoint=Checkpoint.from_directory(temp_checkpoint_dir)  # [4]
        )

results = tune.Tuner(train_fn).fit()

Related issue number

Closes #39035

Checks

• I've signed off every commit(by using the -s flag, i.e., git commit -s) in this PR.
• I've run scripts/format.sh to lint the changes in this PR.
• I've included any doc changes needed for https://docs.ray.io/en/master/.
  • I've added any new APIs to the API Reference. For example, if I added a
    method in Tune, I've added it in doc/source/tune/api/ under the
    corresponding .rst file.
• I've made sure the tests are passing. Note that there might be a few flaky tests, see the recent failures at https://flakey-tests.ray.io/
• Testing Strategy
  • Unit tests
  • Release tests
  • This PR is not tested :(

[krfricke]

Very nice.

Are we planning to land this for 2.7?

[justinvyu]

Yep, going to pick for 2.7

[matthewdeng]

This is really awesome, thank you for cleaning this up!