Decorators for deprecation and named arguments validation
Author: qubvel
Pull request: yes

# What does this PR do?

Introduces 2 decorators for a better approach to deprecate and validate named arguments.

## Deprecation decorator

Function or method decorator to notify users about deprecated keyword arguments, replacing them with a new name if specified.

This decorator allows you to:
 - Notify users when a keyword argument is deprecated.
 - Automatically replace deprecated keyword arguments with new ones.
 - Raise an error if deprecated arguments are used, depending on the specified conditions.

By default, the decorator notifies the user about the deprecated argument while the `transformers.__version__`  < specified `version` in the decorator. To keep notifications with any version `warn_if_greater_or_equal_version=True` can be set.

#### Example usage **with** renaming argument:

```python
from transformers.utils.deprecation import deprecate_kwarg

@deprecate_kwarg("reduce_labels", new_name="do_reduce_labels", version="6.0.0")
def my_function(do_reduce_labels):
    print(do_reduce_labels)

my_function(reduce_labels=True)  # Will show a deprecation warning and use do_reduce_labels=True
```
```output
FutureWarning: `reduce_labels` is deprecated and will be removed in version 6.0.0 for `my_function`. Use `do_reduce_labels` instead.
```

#### Example when both deprecated and new arguments were specified for function call:

```python
from transformers.utils.deprecation import deprecate_kwarg

@deprecate_kwarg("reduce_labels", new_name="do_reduce_labels", version="6.0.0")
def my_function(do_reduce_labels):
    print(do_reduce_labels)

my_function(do_reduce_labels=False, reduce_labels=True)  # not deprecated kwarg has higher priority
# False
```
```output
FutureWarning: Both `reduce_labels` and `do_reduce_labels` are set for `my_function`. Using `do_reduce_labels=False` and ignoring deprecated `reduce_labels=True`.
  my_function(do_reduce_labels=False, reduce_labels=True)  # not deprecated kwarg has higher priority
```

#### Example usage **without** renaming argument:

```python
from transformers.utils.deprecation import deprecate_kwarg

@deprecate_kwarg("max_size", version="6.0.0")
def my_function(max_size):
    print(max_size)

my_function(max_size=1333)  # Will show a deprecation warning
```
```output
FutureWarning: `max_size` is deprecated and will be removed in version 6.0.0 for `my_function`.
  my_function(max_size=1333)  # Will show a deprecation warning
  ```
  
## Validation decorator

Decorator to filter out named arguments that are not in the function signature.
This decorator ensures that only the keyword arguments that match the function's signature, or are specified in the
`extra` list, are passed to the function. Any additional keyword arguments are filtered out and a **warning is issued**.

Example usage:

```python
from transformers.utils.generic import filter_out_non_signature_kwargs

@filter_out_non_signature_kwargs(extra=["allowed_extra_arg"])
def my_function(arg1, arg2, **kwargs):
    print("Function args:", arg1, arg2, kwargs)

my_function(arg1=1, arg2=2, allowed_extra_arg=3, invalid_arg=4)
```
```output
UserWarning: The following named arguments are not valid for `my_function` and were ignored: 'invalid_arg'
  my_function(arg1=1, arg2=2, allowed_extra_arg=3, invalid_arg=4)
Function args: 1 2 {'allowed_extra_arg': 3}
```

## Additional testing

Introducing such decorators might be tricky and lead to some unexpected issues since historically all **kwargs arguments were captured and saved as image_processor's attributes. Despite testing the decorators themselves and tests that passed for image processors, additional testing was conducted for configurations on the hub.

For each image processor in ["maskformer", "mask2former", "segformer", "beit", "oneformer"], configs from the hub with more than 10 downloads were pulled, and the result of the preprocess method was compared with the main branch to ensure they are identical.

Code just for reference:
https://gist.github.com/qubvel/85cf17f516063d63219ef773a365e83d

## Before submitting
- [x] This PR fixes a typo or improves the docs (you can dismiss the other checks if that's the case).
- [x] Did you read the [contributor guideline](https://github.com/huggingface/transformers/blob/main/CONTRIBUTING.md#create-a-pull-request),
      Pull Request section?
- [x] Did you make sure to update the documentation with your changes? Here are the
      [documentation guidelines](https://github.com/huggingface/transformers/tree/main/docs), and
      [here are tips on formatting docstrings](https://github.com/huggingface/transformers/tree/main/docs#writing-source-documentation).
- [x] Did you write any new necessary tests?


## Who can review?

Anyone in the community is free to review the PR once the tests have passed. Feel free to tag
members/contributors who may be interested in your PR.


Comments:
The docs for this PR live [here](https://moon-ci-docs.huggingface.co/docs/transformers/pr_30799). All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

@molbap @amyeroberts I made a new iteration here. Added two decorators
1) `@deprecate_kwarg("reduce_labels", new_name="do_reduce_labels", version="4.41.0")`
 - rename argument if `new_name` is provided
 - raise warning if current version < `version` specified,  then just do it silently
 2) `filter_out_non_signature_kwargs(extra=["max_size"])`
  - filter out all named args that are not in the function signature and not specified in `extra`. As mentioned by @molbap it is not always possible to get rid of all `**kwargs` (for example, it might include complex logic of parameters interaction).
  
 Please, have a look, feedback is appreciated 🤗 

I modified PR's name and description to make it clear.
@amyeroberts @molbap could you please have a look once again, it should be done now.

Rebase + revert to class specific from_dict (discussed here https://github.com/huggingface/transformers/pull/30799#discussion_r1631283521)