Warn with `stacklevel=2` to show caller of deprecation

[hugovk]

trafficstars

Summary

With httpx==0.27.0, I'm getting deprecation warnings like:

  /Users/hugo/my-project/.tox/py312/.venv/lib/python3.12/site-packages/httpx/_client.py:680: DeprecationWarning: The 'app' shortcut is now deprecated. Use the explicit style 'transport=WSGITransport(app=...)' instead.
    warnings.warn(message, DeprecationWarning)

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html

This points to where the deprecated code is in HTTPX and isn't actionable for me.

Instead, if would be more helpful to point to where the deprecated code is being called from, so I can fix my code (or report to the library).

Adding stacklevel=2 gives:

  /Users/hugo/my-project/.tox/py312/.venv/lib/python3.12/site-packages/litestar/testing/client/sync_client.py:77: DeprecationWarning: The 'app' shortcut is now deprecated. Use the explicit style 'transport=WSGITransport(app=...)' instead.
    Client.__init__(

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html

(Aha, so Litestar needs fixing! And they've already fixed and released: https://github.com/litestar-org/litestar/pull/3140, I just need to update 👍)

---

Digging a big deeper, I see there used to be a helper function in httpx/_utils.py:

def warn_deprecated(message: str) -> None:  # pragma: nocover	
    warnings.warn(message, DeprecationWarning, stacklevel=2)	

It was introduced in https://github.com/encode/httpx/pull/963, and removed in https://github.com/encode/httpx/pull/1597.

Should we add it back?

Checklist

• [x] I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
• [n/a?] I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• [n/a?] I've updated the documentation accordingly.