Repository: ploomber/jupysql (python)

Issue:
deprecating legacy plot API
once https://github.com/ploomber/jupysql/pull/508 is merged, we should start showing deprecation warnings:

https://github.com/ploomber/jupysql/blob/8ce3334182733145dbea6ece9e3d59e30237788c/src/sql/run.py#L232
https://github.com/ploomber/jupysql/blob/8ce3334182733145dbea6ece9e3d59e30237788c/src/sql/run.py#L302

and tell people they should use the `%sqlplot` API

Pull request description:
513 Deprecating Legacy Plot API 
## Describe your changes

- Added deprecation warnings for legacy plot functions: .pie(), .bar(), and .plot()
- Added tests for deprecation warning messages
- Merged from master instead of individual branch

## Issue number

Closes #513 

## Checklist before requesting a review

- [x] Performed a self-review of my code
- [x] Formatted my code with [`pkgmt format`](https://ploomber-contributing.readthedocs.io/en/latest/contributing/pr.html#linting-formatting)
- [x] Added [tests](https://ploomber-contributing.readthedocs.io/en/latest/contributing/pr.html#testing) (when necessary).
- [x] 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)



<!-- readthedocs-preview jupysql start -->
----
:books: Documentation preview :books:: https://jupysql--870.org.readthedocs.build/en/870/

<!-- readthedocs-preview jupysql end -->

Patch:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a693921..153e7cb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,7 @@
 * [Doc] Clarify the use of `pyproject.toml` and `connections.ini` in documentations (#850)
 * [Doc] Update documentation to use `{{variable}}` instead of `string.Template` and remove `--with` since it's optional (#838)
 * [Fix] Fix result not displayed when `SUMMARIZE` argument is used in duckdb with a sqlalchemy connection (#836)
+* [Fix] Show deprecation warnings for legacy plot API (#513)
 * [Fix] Fix error when trying to access previously non-existing file (#840)
 
 ## 0.10.1 (2023-08-30)
diff --git a/src/sql/run/resultset.py b/src/sql/run/resultset.py
index 5e79a00..d1f8fa8 100644
--- a/src/sql/run/resultset.py
+++ b/src/sql/run/resultset.py
@@ -5,8 +5,8 @@ from io import StringIO
 from html import unescape
 from collections.abc import Iterable
 
-
 import prettytable
+import warnings
 
 from sql.column_guesser import ColumnGuesserMixin
 from sql.run.csv import CSVWriter, CSVResultDescriptor
@@ -282,6 +282,15 @@ class ResultSet(ColumnGuesserMixin):
         Any additional keyword arguments will be passed
         through to ``matplotlib.pylab.pie``.
         """
+        warnings.warn(
+            (
+                ".pie() is deprecated and will be removed in a future version. "
+                "Use %sqlplot pie instead. "
+                "For more help, find us at https://ploomber.io/community "
+            ),
+            UserWarning,
+        )
+
         self.guess_pie_columns(xlabel_sep=key_word_sep)
         import matplotlib.pylab as plt
 
@@ -310,6 +319,14 @@ class ResultSet(ColumnGuesserMixin):
         Any additional keyword arguments will be passed
         through to ``matplotlib.pylab.plot``.
         """
+        warnings.warn(
+            (
+                ".plot() is deprecated and will be removed in a future version. "
+                "For more help, find us at https://ploomber.io/community "
+            ),
+            UserWarning,
+        )
+
         import matplotlib.pylab as plt
 
         self.guess_plot_columns()
@@ -351,6 +368,15 @@ class ResultSet(ColumnGuesserMixin):
         Any additional keyword arguments will be passed
         through to ``matplotlib.pylab.bar``.
         """
+        warnings.warn(
+            (
+                ".bar() is deprecated and will be removed in a future version. "
+                "Use %sqlplot bar instead. "
+                "For more help, find us at https://ploomber.io/community "
+            ),
+            UserWarning,
+        )
+
         import matplotlib.pylab as plt
 
         ax = plt.gca()


Test patch:
diff --git a/src/tests/test_resultset.py b/src/tests/test_resultset.py
index 953ddfb..c391597 100644
--- a/src/tests/test_resultset.py
+++ b/src/tests/test_resultset.py
@@ -15,6 +15,8 @@ from sql.connection import DBAPIConnection, SQLAlchemyConnection
 from sql.run.resultset import ResultSet
 from sql.connection.connection import IS_SQLALCHEMY_ONE
 
+import warnings
+
 
 @pytest.fixture
 def config():
@@ -635,3 +637,58 @@ def test_doesnt_refresh_sqlaproxy_if_different_connection():
     list(first_set)
 
     assert id(first_set._sqlaproxy) == original_id
+
+
+@pytest.mark.parametrize(
+    "function, expected_warning, dataset",
+    [
+        (
+            "pie",
+            (
+                ".pie() is deprecated and will be removed in a future version. "
+                "Use %sqlplot pie instead. "
+                "For more help, find us at https://ploomber.io/community "
+            ),
+            {
+                "x": [1, 2, 3],
+                "y": [4, 5, 6],
+            },
+        ),
+        (
+            "bar",
+            (
+                ".bar() is deprecated and will be removed in a future version. "
+                "Use %sqlplot bar instead. "
+                "For more help, find us at https://ploomber.io/community "
+            ),
+            {
+                "x": [1, 2, 3],
+            },
+        ),
+        (
+            "plot",
+            (
+                ".plot() is deprecated and will be removed in a future version. "
+                "For more help, find us at https://ploomber.io/community "
+            ),
+            {
+                "x": [1, 2, 3],
+            },
+        ),
+    ],
+)
+def test_calling_legacy_plotting_functions_displays_warning(
+    config, function, expected_warning, dataset
+):
+    df = pd.DataFrame(dataset)  # noqa
+    engine = sqlalchemy.create_engine("duckdb://")
+    conn = SQLAlchemyConnection(engine)
+    result = conn.raw_execute("select * from df")
+
+    rs = ResultSet(result, config, statement="select * from df", conn=conn)
+
+    with warnings.catch_warnings(record=True) as record:
+        getattr(rs, function)()
+
+    assert len(record) == 1
+    assert str(record[0].message) == expected_warning