utility function to warn changes in default arguments

[wyli]

Is your feature request related to a problem? Please describe.

MONAI/monai/utils/deprecate_utils.py

Lines 119 to 127 in e8c6247

	def deprecated_arg(
	name,
	since: Optional[str] = None,
	removed: Optional[str] = None,
	msg_suffix: str = "",
	version_val: str = __version__,
	new_name: Optional[str] = None,
	warning_category=FutureWarning,
	):

the deprecated_arg can trigger warnings when a deprecating argument is provided by the user,
it however doesn't warn when a default value of an argument has been/will be changed.

for example it's currently not possible to warn about these changes:

• random_size defaulting to False in RandSpatialCropd #5652
• set image_only=True in LoadImaged #5007

[f-schnabel]

I would like to work on this. I'm not quite sure if we want to add this functionality into deprecated_arg or have a separate decorator like deprecated_default since otherwise it's a bit ambiguos if there argument is deprecated or it's default simply changed. What do you think @wyli?

[wyli]

agreed, please feel free to create a separate decorator for this feature request.

[f-schnabel]

My current idea how one could implement this decorator is as follows:

@deprecated_arg_default("name", old_default="test", new_default="new_name", since="1.1.0", changed="1.2.0")
def test(name: str = "test"):
    print(name)

name, old_default and new_default are all required.
The decorators only purpose is to validate if the deprecation is valid and to print a warning if version >= since and the parameter isn't directly specified,
it doesn't change the default argument by itself (would be too much "magic" in the background IMO and would be confusing if in the function signature the old default is still present, but it's changed by the decorator).

It will print different messages if since <= version < changed, version >= changed and if since and changed are not present (adopted from deprecated_default).

Two open questions I still have:

1. Should I include an "end of warning version"? Otherwise, all future versions will print the deprecation warning if no explicit argument is used.
2. What if a parameters default is changed multiple times? Should I also consider this scenario in my PR?

[wyli]

it looks good to me, there's no need to add end of warning or consider multiple changes.

we may consider another simple case of changing the default behaviour but using the same signature:

def test(name=None):
   _name = "test"
   if name is None:
-      _name = "old_default"
+      _name = "new_default"
   return _name