[air] Add stacklevel option to deprecation_warning (#58357)

Currently are deprecation warnings sometimes not informative enough. The
the warning is triggered it does not tell us *where* the deprecated
feature is used. For example, ray internally raises a deprecation
warning when an `RLModuleConfig` is initialized.

```python
>>> from ray.rllib.core.rl_module.rl_module import RLModuleConfig
>>> RLModuleConfig()
2025-11-02 18:21:27,318 WARNING deprecation.py:50 -- DeprecationWarning: `RLModule(config=[RLModuleConfig object])` has been deprecated. Use `RLModule(observation_space=.., action_space=.., inference_only=.., model_config=.., catalog_class=..)` instead. This will raise an error in the future!
```

This is confusing, where did *I* use a config, what am I doing wrong?
This raises issues like:
https://discuss.ray.io/t/warning-deprecation-py-50-deprecationwarning-rlmodule-config-rlmoduleconfig-object-has-been-deprecated-use-rlmodule-observation-space-action-space-inference-only-model-config-catalog-class-instead/23064

Tracing where the error actually happens is tedious - is it my code or
internal? The output just shows `deprecation.:50`. Not helpful.

This PR adds a stacklevel option with stacklevel=2 as the default to all
`deprecation_warning`s. So devs and users can better see where is the
deprecated option actually used.

---

EDIT:

**Before**

```python
WARNING deprecation.py:50 -- DeprecationWarning: `RLModule(config=[RLModuleConfig object])` 
```

**After** module.py:line where the deprecated artifact is used is shown
in the log output:

When building an Algorithm:
```python
WARNING rl_module.py:445 -- DeprecationWarning: `RLModule(config=[RLModuleConfig object])` has been deprecated. Use `RLModule(observation_space=.., action_space=.., inference_only=.., model_config=.., catalog_class=..)` instead. This will raise an error in the future!
```

```python
.../ray/tune/logger/unified.py:53: RayDeprecationWarning: This API is deprecated and may be removed in future Ray releases. You could suppress this warning by setting env variable PYTHONWARNINGS="ignore::DeprecationWarning"
```

Signed-off-by: Daraan <[email protected]>

Author: Daraan

python/ray/_common/deprecation.py

@@ -19,6 +19,7 @@ def deprecation_warning(
     *,
     help: Optional[str] = None,
     error: Optional[Union[bool, Exception]] = None,
+    stacklevel: int = 2,
 ) -> None:
     """Warns (via the `logger` object) or throws a deprecation warning/error.
 
@@ -30,6 +31,9 @@ def deprecation_warning(
         error: Whether or which exception to raise. If True, raise ValueError.
             If False, just warn. If `error` is-a subclass of Exception,
             raise that Exception.
+        stacklevel: The stacklevel to use for the warning message.
+            Use 2 to point to where this function is called, 3+ to point
+            further up the stack.
 
     Raises:
         ValueError: If `error=True`.
@@ -48,7 +52,8 @@ def deprecation_warning(
             raise ValueError(msg)
     else:
         logger.warning(
-            "DeprecationWarning: " + msg + " This will raise an error in the future!"
+            "DeprecationWarning: " + msg + " This will raise an error in the future!",
+            stacklevel=stacklevel,
         )
 
 
@@ -105,6 +110,7 @@ def patched_init(*args, **kwargs):
                         new=new,
                         help=help,
                         error=error,
+                        stacklevel=3,
                     )
                 return obj_init(*args, **kwargs)
 
@@ -123,6 +129,7 @@ def _ctor(*args, **kwargs):
                     new=new,
                     help=help,
                     error=error,
+                    stacklevel=3,
                 )
             # Call the deprecated method/function.
             return obj(*args, **kwargs)