[Train/Tune] Warn pending deprecation for ray.train.Trainer and ray.tune DistributedTrainableCreators

[amogkam]

ray.train.Trainer and ray.tune.integration.*.DistributedTrainableCreator will be deprecated in Ray 2.0 in favor of Ray AIR. In Ray 1.13, we should warn about this pending deprecation.

First step towards #23014

Why are these changes needed?

Related issue number

Checks

• 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 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 :(

[Yard1]

Add @Deprecated decorators as well?

[amogkam]

Ah @Yard1 we will officially denote as deprecated for Ray 2.0. But for Ray 1.13, we just want to print a warning message saying that this will happen in the future.

[Yard1]

The decorator only adds a message to the docstring that this API will be removed in a future ray release. I think that fits what we want to convey exactly

[amogkam]

The decorator officially denotes the APIs as deprecated (even though may actually be removed in a later release). We don't want to deprecate these APIs in Ray 1.x, and will wait for the major release to do so.

[amogkam]

Basically we don't want this part yet: DEPRECATED: This API is deprecated

[Yard1]

I see, ok! Seems odd to have this warning on init but not in the docstring somewhere, though. We want to dissuade people from using those in the first place, right? Having a mention in the docstring about the pending depreciation would steer users who land on the docs page towards Train.

[amogkam]

Yeah that's a good point. I can definitely manually add it, but I'm not sure if we have standardized on any particular policy across all of Ray.

For reference, this is what Python does:

Python library uses warnings.warn() to emit a deprecation warning in the body of functions.
3 categories are used: DeprecationWarning, PendingDeprecationWarning and FutureWarning.
The docstring doesn’t show anything about deprecation.
The documentation warns about some, but not all, deprecated usages.

From https://deprecated.readthedocs.io/en/latest/white_paper.html.

[xwjiang2010]

How about others under ray/tune/integration?

[amogkam]

@xwjiang2010 these are the only ones we want to deprecate right? (These are the only ones with DistributedTrainableCreators).

[xwjiang2010]

@amogkam Ah I see. That makes sense.
One more question, how about the docs? Like should we update examples here? Or maybe we will wait for 2.0.0 when it's truly deprecated?

[amogkam]

@xwjiang2010 yep let's remove the docs once they are fully deprecated!

[bveeramani]

Had a question about the documentation linked. Otherwise LGTM

[bveeramani]

LGTM