feat(python): add plot namespace (which defers to hvplot)

README.md

@@ -192,10 +192,13 @@ Install Polars with all optional dependencies.
 
 ```sh
 pip install 'polars[all]'
-pip install 'polars[numpy,pandas,pyarrow]'  # install a subset of all optional dependencies
 ```
 
-You can also install the dependencies directly.
+You can also install a subset of all optional dependencies.
+
+```sh
+pip install 'polars[numpy,pandas,pyarrow]'
+```
 
 | Tag        | Description                                                                  |
 | ---------- | ---------------------------------------------------------------------------- |
@@ -209,6 +212,7 @@ You can also install the dependencies directly.
 | openpyxl   | Support for reading from Excel files with native types                       |
 | deltalake  | Support for reading from Delta Lake Tables                                   |
 | pyiceberg  | Support for reading from Apache Iceberg tables                               |
+| plot       | Support for plot functions on Dataframes                                     |
 | timezone   | Timezone support, only needed if are on Python<3.9 or you are on Windows     |
 
 Releases happen quite often (weekly / every few days) at the moment, so updating polars regularly to get the latest bugfixes / features might not be a bad idea.

docs/user-guide/installation.md

@@ -55,6 +55,7 @@ pip install 'polars[numpy,fsspec]'
 | connectorx | Support for reading from SQL databases                                                                                                |
 | xlsx2csv   | Support for reading from Excel files                                                                                                  |
 | deltalake  | Support for reading from Delta Lake Tables                                                                                            |
+| plot       | Support for plotting Dataframes                                                                                                       |
 | timezone   | Timezone support, only needed if 1. you are on Python < 3.9 and/or 2. you are on Windows, otherwise no dependencies will be installed |
 
 ### Rust

py-polars/docs/source/reference/dataframe/attributes.rst

@@ -10,6 +10,7 @@ Attributes
     DataFrame.dtypes
     DataFrame.flags
     DataFrame.height
+    DataFrame.plot
     DataFrame.schema
     DataFrame.shape
     DataFrame.width

py-polars/docs/source/reference/dataframe/index.rst

@@ -16,6 +16,7 @@ This page gives an overview of all public DataFrame methods.
    group_by
    modify_select
    miscellaneous
+   plotting
 
 .. currentmodule:: polars
 

py-polars/docs/source/reference/dataframe/plotting.rst

@@ -0,0 +1,44 @@
+========
+Plotting
+========
+
+Polars does not implement plotting logic itself, but instead defers to
+hvplot. Please see the `hvplot reference gallery <https://hvplot.holoviz.org/reference/index.html>`_
+for more information and documentation.
+
+Examples
+--------
+Scatter plot:
+
+.. code-block:: python
+
+    df = pl.DataFrame(
+        {
+            "length": [1, 4, 6],
+            "width": [4, 5, 6],
+            "species": ["setosa", "setosa", "versicolor"],
+        }
+    )
+    df.plot.scatter(x="length", y="width", by="species")
+
+Line plot:
+
+.. code-block:: python
+
+    from datetime import date
+    df = pl.DataFrame(
+        {
+            "date": [date(2020, 1, 2), date(2020, 1, 3), date(2020, 1, 3)],
+            "stock_1": [1, 4, 6],
+            "stock_2": [1, 5, 2],
+        }
+    )
+    df.plot.line(x="date", y=["stock_1", "stock_2"])
+
+For more info on what you can pass, you can use ``hvplot.help``:
+
+.. code-block:: python
+
+    import hvplot
+    hvplot.help('scatter')
+

py-polars/polars/dataframe/frame.py

@@ -348,7 +348,7 @@ class DataFrame:
 
     """
 
-    _accessors: ClassVar[set[str]] = set()
+    _accessors: ClassVar[set[str]] = {"plot"}
 
     def __init__(
         self,
@@ -1116,6 +1116,55 @@ def _replace(self, column: str, new_column: Series) -> Self:
         self._df.replace(column, new_column._s)
         return self
 
+    @property
+    def plot(self) -> Any:
+        """
+        Create a plot namespace.
+
+        Polars does not implement plotting logic itself, but instead defers to
+        hvplot. Please see the `hvplot reference gallery <https://hvplot.holoviz.org/reference/index.html>`_
+        for more information and documentation.
+
+        Examples
+        --------
+        Scatter plot:
+
+        >>> df = pl.DataFrame(
+        ...     {
+        ...         "length": [1, 4, 6],
+        ...         "width": [4, 5, 6],
+        ...         "species": ["setosa", "setosa", "versicolor"],
+        ...     }
+        ... )
+        >>> df.plot.scatter(x="length", y="width", by="species")  # doctest: +SKIP
+
+        Line plot:
+
+        >>> from datetime import date
+        >>> df = pl.DataFrame(
+        ...     {
+        ...         "date": [date(2020, 1, 2), date(2020, 1, 3), date(2020, 1, 3)],
+        ...         "stock_1": [1, 4, 6],
+        ...         "stock_2": [1, 5, 2],
+        ...     }
+        ... )
+        >>> df.plot.line(x="date", y=["stock_1", "stock_2"])  # doctest: +SKIP
+
+        For more info on what you can pass, you can use ``hvplot.help``:
+
+        >>> import hvplot  # doctest: +SKIP
+        >>> hvplot.help("scatter")  # doctest: +SKIP
+        """
+        try:
+            import hvplot.polars  # noqa: F401
+        except ModuleNotFoundError:
+            raise ModuleNotFoundError(
+                "hvplot is not installed, or is older than version 0.9.0.\n\n"
+                "Please see https://hvplot.holoviz.org/getting_started/installation.html "
+                "for installation instructions."
+            ) from None
+        return self.hvplot  # type: ignore[attr-defined]
+
     @property
     def shape(self) -> tuple[int, int]:
         """

py-polars/polars/utils/show_versions.py

@@ -24,6 +24,7 @@ def show_versions() -> None:
     connectorx:           0.3.2
     deltalake:            0.13.0
     fsspec:               2023.10.0
+    hvplot:               0.9.0
     gevent:               23.9.1
     matplotlib:           3.8.2
     numpy:                1.26.2
@@ -66,6 +67,7 @@ def _get_dependency_info() -> dict[str, str]:
         "deltalake",
         "fsspec",
         "gevent",
+        "hvplot",
         "matplotlib",
         "numpy",
         "openpyxl",

py-polars/pyproject.toml

@@ -45,6 +45,7 @@ connectorx = ["connectorx >= 0.3.2"]
 deltalake = ["deltalake >= 0.14.0"]
 fsspec = ["fsspec"]
 gevent = ["gevent"]
+plot = ["hvplot >= 0.9.0"]
 matplotlib = ["matplotlib"]
 numpy = ["numpy >= 1.16.0"]
 openpyxl = ["openpyxl >= 3.0.0"]
@@ -58,7 +59,7 @@ timezone = ["backports.zoneinfo; python_version < '3.9'", "tzdata; platform_syst
 xlsx2csv = ["xlsx2csv >= 0.8.0"]
 xlsxwriter = ["xlsxwriter"]
 all = [
-  "polars[pyarrow,pandas,numpy,fsspec,connectorx,xlsx2csv,deltalake,timezone,matplotlib,pydantic,pyiceberg,sqlalchemy,xlsxwriter,adbc,cloudpickle,gevent]",
+  "polars[pyarrow,pandas,numpy,fsspec,plot,connectorx,xlsx2csv,deltalake,timezone,pydantic,pyiceberg,sqlalchemy,xlsxwriter,adbc,cloudpickle,gevent]",
 ]
 
 [tool.maturin]
@@ -88,6 +89,7 @@ module = [
   "ezodf.*",
   "fsspec.*",
   "gevent",
+  "hvplot.*",
   "matplotlib.*",
   "moto.server",
   "openpyxl",

py-polars/requirements-dev.txt

@@ -47,8 +47,10 @@ dataframe-api-compat >= 0.1.6
 pyiceberg >= 0.5.0
 # Csv
 zstandard
-# Other
+# Plotting
+hvplot>=0.9.0
 matplotlib
+# Other
 gevent
 
 # -------

py-polars/tests/unit/namespaces/test_plot.py

@@ -0,0 +1,23 @@
+from datetime import date
+
+import polars as pl
+
+
+def test_plot_namespace() -> None:
+    df = pl.DataFrame(
+        {
+            "length": [1, 4, 6],
+            "width": [4, 5, 6],
+            "species": ["setosa", "setosa", "versicolor"],
+        }
+    )
+    df.plot.scatter(x="length", y="width", by="species")
+
+    df = pl.DataFrame(
+        {
+            "date": [date(2020, 1, 2), date(2020, 1, 3), date(2020, 1, 3)],
+            "stock_1": [1, 4, 6],
+            "stock_2": [1, 5, 2],
+        }
+    )
+    df.plot.line(x="date", y=["stock_1", "stock_2"])