Logging future warning

.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## Describe your changes
+
+## Issue number
+
+Closes #X
+
+## Checklist before requesting a review
+
+- [ ] Performed a self-review of my code
+- [ ] Formatted my code with [`pkgmt format`](https://ploomber-contributing.readthedocs.io/en/latest/contributing/pr.html#linting-formatting)
+- [ ] Added [tests](https://ploomber-contributing.readthedocs.io/en/latest/contributing/pr.html#testing) (when necessary).
+- [ ] Added [docstring](https://ploomber-contributing.readthedocs.io/en/latest/contributing/pr.html#documenting-changes-and-new-features) documentation and update the [changelog](https://ploomber-contributing.readthedocs.io/en/latest/contributing/pr.html#changelog) (when needed)
+

doc/deprecation.md

@@ -498,6 +498,31 @@ def example_function(n_clusters=10, another=42, k="deprecated"):
 example_function(k=10)
 ```
 
+## Deprecation warning with logger
+
+`deprecation_warning(telemetry, message)` is designed to facilitate the logging of deprecated features in your codebase. It throws warning messages and log
+the information about the message, the current package name and version.
+
+We need to provide telemetry instance and the message string:
+
+- telemetry, [Telemetry class](telemetry.md)
+- message, str, the message to display
+
+### Example
+
+In the [jupysql](https://github.com/ploomber/jupysql) project, we may import the existing telemetry instance and pass to `deprecation_warning`
+
+```
+from sql.telemetry import telemetry
+
+def some_random_func():
+    deprecation_warning(telemetry, "you are using old feature")
+
+some_random_func()
+```
+
+The message `you are using old feature` and jupysql package info will be logged
+
 ## Reference
 
 This is based on [sklearn's guidelines.](https://scikit-learn.org/stable/developers/contributing.html#maintaining-backwards-compatibility)

src/ploomber_core/warnings.py

@@ -1,3 +1,7 @@
+from warnings import warn
+from ploomber_core.telemetry import telemetry as core_telemetry
+
+
 class PloomberDeprecationWarning(FutureWarning):
     """
     Notes
@@ -7,3 +11,22 @@ class PloomberDeprecationWarning(FutureWarning):
     """
 
     pass
+
+
+def deprecation_warning(telemetry, message):
+    """Raise deprecation warning message, also log to posthog with telemetry instance
+    is provided
+
+    Parameters
+    ----------
+    message : str
+        The warning message displayed to the user
+    module_telemetry : Telemetry
+        The telemetry instance defined in ploomber_core.telemetry.Telemetry,
+        by default None
+    """
+    warn(message, FutureWarning)
+    if telemetry and isinstance(telemetry, core_telemetry.Telemetry):
+        telemetry.log_api(
+            action="deprecation-warning-shown", metadata={"message": message}
+        )

tests/test_warning.py

@@ -0,0 +1,25 @@
+# import posthog
+
+from unittest.mock import Mock
+from ploomber_core.warnings import deprecation_warning
+from ploomber_core.telemetry import telemetry as telemetry_module
+
+import pytest
+
+
+def test_deprecation_warning_w_posthog(monkeypatch):
+    # Initiate telemetry instance with mock_log_api
+    somepackage_telemetry = telemetry_module.Telemetry(
+        api_key="KEY", package_name="somepackage", version="0.1"
+    )
+    mock_log_api = Mock()
+    monkeypatch.setattr(somepackage_telemetry, "log_api", mock_log_api)
+
+    # To test if warning is shown
+    with pytest.warns(FutureWarning):
+        deprecation_warning(somepackage_telemetry, "Test")
+
+    # To test if log_api is called
+    mock_log_api.assert_called_once_with(
+        action="deprecation-warning-shown", metadata={"message": "Test"}
+    )