add Series.plot

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

@@ -20,6 +20,7 @@ This page gives an overview of all public Series methods.
    list
    modify_select
    miscellaneous
+   plot
    string
    struct
    temporal

py-polars/polars/dataframe/frame.py

@@ -618,15 +618,20 @@ def plot(self) -> Plot:
             `df.plot` with `df.hvplot`.
 
         Polars does not implement plotting logic itself, but instead defers to
-        Altair:
+        `Altair <https://altair-viz.github.io/>`_:
 
-        - `df.plot.line(*args, **kwargs)`
+        - `df.plot.line(**kwargs)`
           is shorthand for
-          `alt.Chart(df).mark_line().encode(*args, **kwargs).interactive()`
-        - `df.plot.point(*args, **kwargs)`
+          `alt.Chart(df).mark_line().encode(**kwargs).interactive()`
+        - `df.plot.point(**kwargs)`
           is shorthand for
-          `alt.Chart(df).mark_point().encode(*args, **kwargs).interactive()`
-        - ... (likewise, for any other attribute, e.g. `df.plot.bar`)
+          `alt.Chart(df).mark_point().encode(**kwargs).interactive()`
+        - `df.plot.bar(**kwargs)`
+          is shorthand for
+          `alt.Chart(df).mark_bar().encode(**kwargs).interactive()`
+        - for any other attribute `attr`, `df.plot.attr(**kwargs)`
+          is shorthand for
+          `alt.Chart(df).mark_attr().encode(**kwargs).interactive()`
 
         Examples
         --------
@@ -652,6 +657,19 @@ def plot(self) -> Plot:
         ...     }
         ... )
         >>> df.plot.line(x="date", y="price", color="stock")  # doctest: +SKIP
+
+        Bar plot:
+
+        >>> df = pl.DataFrame(
+        ...     {
+        ...         "day": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] * 2,
+        ...         "group": ["a"] * 7 + ["b"] * 7,
+        ...         "value": [1, 3, 2, 4, 5, 6, 1, 1, 3, 2, 4, 5, 1, 2],
+        ...     }
+        ... )
+        >>> df.plot.bar(
+        ...     x="day", y="value", color="day", column="group"
+        ... )  # doctest: +SKIP
         """
         if not _ALTAIR_AVAILABLE or parse_version(altair.__version__) < (5, 4, 0):
             msg = "altair>=5.4.0 is required for `.plot`"

py-polars/polars/dataframe/plotting.py

@@ -57,9 +57,11 @@ def bar(
         """
         Draw bar plot.
 
-        Polars does not implement plotting logic itself but instead defers to Altair.
-        `df.plot.bar(*args, **kwargs)` is shorthand for
-        `alt.Chart(df).mark_bar().encode(*args, **kwargs).interactive()`,
+        Polars does not implement plotting logic itself but instead defers to
+        `Altair <https://altair-viz.github.io/>`_.
+
+        `df.plot.bar(**kwargs)` is shorthand for
+        `alt.Chart(df).mark_bar().encode(**kwargs).interactive()`,
         as is intended for convenience - for full customisatibility, use a plotting
         library directly.
 
@@ -79,8 +81,8 @@ def bar(
             Column to color bars by.
         tooltip
             Columns to show values of when hovering over bars with pointer.
-        *args, **kwargs
-            Additional arguments and keyword arguments passed to Altair.
+        **kwargs
+            Additional keyword arguments passed to Altair.
 
         Examples
         --------
@@ -120,9 +122,10 @@ def line(
         """
         Draw line plot.
 
-        Polars does not implement plotting logic itself but instead defers to Altair.
-        `df.plot.line(*args, **kwargs)` is shorthand for
-        `alt.Chart(df).mark_line().encode(*args, **kwargs).interactive()`,
+        Polars does not implement plotting logic itself but instead defers to
+        `Altair <https://altair-viz.github.io/>`_.
+
+        `alt.Chart(df).mark_line().encode(**kwargs).interactive()`,
         as is intended for convenience - for full customisatibility, use a plotting
         library directly.
 
@@ -144,8 +147,8 @@ def line(
             Column to use for order of data points in lines.
         tooltip
             Columns to show values of when hovering over lines with pointer.
-        *args, **kwargs
-            Additional arguments and keyword arguments passed to Altair.
+        **kwargs
+            Additional keyword arguments passed to Altair.
 
         Examples
         --------
@@ -183,15 +186,16 @@ def point(
         color: ChannelColor | None = None,
         size: ChannelSize | None = None,
         tooltip: ChannelTooltip | None = None,
-        *args: Any,
         **kwargs: Any,
     ) -> alt.Chart:
         """
         Draw scatter plot.
 
-        Polars does not implement plotting logic itself but instead defers to Altair.
-        `df.plot.point(*args, **kwargs)` is shorthand for
-        `alt.Chart(df).mark_point().encode(*args, **kwargs).interactive()`,
+        Polars does not implement plotting logic itself but instead defers to
+        `Altair <https://altair-viz.github.io/>`_.
+
+        `df.plot.point(**kwargs)` is shorthand for
+        `alt.Chart(df).mark_point().encode(**kwargs).interactive()`,
         as is intended for convenience - for full customisatibility, use a plotting
         library directly.
 
@@ -213,8 +217,8 @@ def point(
             Column which determines points' sizes.
         tooltip
             Columns to show values of when hovering over points with pointer.
-        *args, **kwargs
-            Additional arguments and keyword arguments passed to Altair.
+        **kwargs
+            Additional keyword arguments passed to Altair.
 
         Examples
         --------
@@ -240,15 +244,16 @@ def point(
             encodings["tooltip"] = tooltip
         return (
             self.chart.mark_point()
-            .encode(*args, **{**encodings, **kwargs})
+            .encode(
+                **encodings,  # type: ignore[arg-type]
+                **kwargs,
+            )
             .interactive()
         )
 
-    def __getattr__(
-        self, attr: str, *args: EncodeKwds, **kwargs: EncodeKwds
-    ) -> Callable[..., alt.Chart]:
-        method = self.chart.__getattr__(f"mark_{attr}", None)
+    def __getattr__(self, attr: str) -> Callable[..., alt.Chart]:
+        method = getattr(self.chart, f"mark_{attr}", None)
         if method is None:
             msg = "Altair has no method 'mark_{attr}'"
             raise AttributeError(msg)
-        return method().encode(*args, **kwargs).interactive()
+        return lambda **kwargs: method().encode(**kwargs).interactive()