add depreacated decorator

[zpcore]

Introduce the mark_deprecated decorator to map deprecated function to the new function. The reason is that existing deprecated function only maps to function with the same name. It's impossible to map function like xrt_world_size to world_size.

Instead of passing old function to the deprecation wrapper, I think use the decorator above the old function is the most straightward.

Example to use:

import torch_xla
from torch_xla.experimental.deprecation import mark_deprecated

@mark_deprecated(torch_xla.runtime.world_size)
def xrt_world_size(defval=1):
  """Retrieves the number of devices which is taking part of the replication.

  Args:
    defval (int, optional): The default value to be returned in case there is no
      replication information available.
      Default: 1

  Returns:
    The number of devices which is taking part of the replication.
  """
  global _WORLD_SIZE
  if _WORLD_SIZE is not None:
    return _WORLD_SIZE

  return runtime.world_size()

Output:

>>> import torch_xla
>>> torch_xla.core.xla_model.xrt_world_size()
WARNING:root:torch_xla.core.xla_model.xrt_world_size is deprecated. Use torch_xla.runtime.world_size instead.
1

[will-cromar]

The decorator makes sense here, but not because It's impossible to map function like xrt_world_size to world_size.. For example, see how these three functions in experimental.pjrt were renamed after being deprecated:

xla/torch_xla/experimental/pjrt.py

Lines 28 to 31 in b1f2167

	rendezvous = deprecated(this_module, xm.xla_rendezvous)
	device_attributes = deprecated(this_module, runtime.runtime_device_attributes)
	global_device_attributes = deprecated(this_module,
	runtime.global_runtime_device_attributes)

You would need the decorator if the implementation of the old function is actually different than the new one. In this case, the signatures of xrt_world_size ((int) -> int) and world_size (() -> int) differ.

Having said that, you can make mark_deprecated DRY. Remember that a decorator is a function that takes one function as an argument and returns a function. If you use functools.partial to fill the first argument of deprecated ((module, fn) -> fn), the partial callable is (fn) -> fn (ie a decorator. For any module, you can create a decorator like this:

mark_deprecated = functools.partial(deprecated, this_module)

Or, you can put this idea to work in experimental.deprecation to reduce the duplicated logic in your implementation:

def mark_deprecated(module):
  def f(func):
    return deprecated(module, func)
  return f

[zpcore]

The decorator makes sense here, but not because It's impossible to map function like xrt_world_size to world_size.. For example, see how these three functions in experimental.pjrt were renamed after being deprecated:

xla/torch_xla/experimental/pjrt.py

Lines 28 to 31 in b1f2167

	rendezvous = deprecated(this_module, xm.xla_rendezvous)
	device_attributes = deprecated(this_module, runtime.runtime_device_attributes)
	global_device_attributes = deprecated(this_module,
	runtime.global_runtime_device_attributes)

You would need the decorator if the implementation of the old function is actually different than the new one. In this case, the signatures of xrt_world_size ((int) -> int) and world_size (() -> int) differ.

Having said that, you can make mark_deprecated DRY. Remember that a decorator is a function that takes one function as an argument and returns a function. If you use functools.partial to fill the first argument of deprecated ((module, fn) -> fn), the partial callable is (fn) -> fn (ie a decorator. For any module, you can create a decorator like this:

mark_deprecated = functools.partial(deprecated, this_module)

Or, you can put this idea to work in experimental.deprecation to reduce the duplicated logic in your implementation:

def mark_deprecated(module):
  def f(func):
    return deprecated(module, func)
  return f

Thanks for the point. It's mostly about the warning message. If we did something like:

 rendezvous = deprecated(this_module, xm.xla_rendezvous) 

It will warn like this_module.xla_rendezvous is deprecated with xm.xla_rendezvous, while there is no function named xla_rendezvous originally in this module.

[will-cromar]

It will warn like this_module.xla_rendezvous is deprecated with xm.xla_rendezvous, while there is no function named xla_rendezvous originally in this module.

I see, good catch. It looks like deprecated is missing a parameter to print the correct warning then. You can add something like this:

def deprecated(module, new_fn, old_name=None):
  old_name = old_name or newfn.__name__
  ...
     logging.warning(f'{module.__name__}.{old_name} is deprecated. Use {new.__module__}.{new.__name__} instead.)
  ...

[will-cromar]

Thanks!