Add deprecate module

[Louis-Dupont]

Breaking change fail will be fixed in #1420
Please review the PR above first, to fix breacking change test 🙏

Motivation

Have a nicer decorator to deprecate functions. The idea is to easily deprecate any function, with nice logs

Answers to Ofri

I. Usage of warning vs logger.warning

With warnings, we get

1. a nice DeprecationWarning built-in, which is standard in python, and which is also easy to catch (see tests)
2. Option to show the line that raised the warning fully_configured_deprecated_func() in the example below. This is thanks to stacklevel in warnings.warn(message, DeprecationWarning, stacklevel=2)

/Users/Louis.Dupont/PycharmProjects/super-gradients/tests/unit_tests/deprecate.py:19: DeprecationWarning: Function `__main__.fully_configured_deprecated_func` is deprecated since version `3.2.0` and will be removed in version `4.0.0`.
Reason: Replaced for optimization.
Please update your code:
  [-] from `module` import `fully_configured_deprecated_func`
  [+] from `module` import `new_func`
  fully_configured_deprecated_func()

I think using this is cleaner than logger.warning, what do you think ?

II. Making sure that removed_in_v is enforced

After discussion with @shaydeci and @ofrimasad, we decided to enforce removed_in_v. Basically, using a function that is not supported (version > removed_in_v) will lead to an ImportError with a clear error message explaining how to fix it.

Should be something like

ImportError('Function `some_module.get_local_rank` was deprecated and has been removed. Deprecated since version `3.2.0`
        and will be removed in version `4.0.0`. Reason: `Replaced for optimization`.
        Please update your code:
          [-] from `some_module` import `get_local_rank`
          [+] from `new.module.path` import `new_get_local_rank`.')

I think it is eventually a nice way to remove a function and force people to move to the new one, while giving them a clear tip on how to do

[ofrimasad]

about the warning - ok
about the assert on version, that is incorrect.
before version release, we bump the __version__, at wich point the tests will fail.

[Louis-Dupont]

Added

• Test to make sure it works well with classes
• Check the version + test
• rename to deprecated

---

Question

The function was renamed to deprecated. Should the module also be renamed deprecated or still deprecate ?

about the assert on version, that is incorrect.
before version release, we bump the version, at wich point the tests will fail.

I changed the code accordingly, and I tested it - see added tests here a210e0a
But I am a bit uneasy with it. If, for some reason, we don't remove the deprecated function when we should, then it would crash all the code and make SG unusable.
This would be a major issue. Yes we should catch it because we bump the version before testing, but I'm still a bit afraid it would somehow happen.

I think this type of exception should be directly implemented/checked in the test, and not to the user code (similarly to what we did with breaking changes)

[BloodAxe]

LGTM
Left a minor comment on argument names. Not a big deal tho
Up to you whether to address or ignore if you disagree ;)

[ofrimasad]

LGTM
consider @BloodAxe comments about param names

[BloodAxe]

LGTM