assorted docs and typing improvements

py-polars/polars/dataframe/frame.py

@@ -614,7 +614,7 @@ def plot(self) -> DataFramePlot:
         .. versionchanged:: 1.6.0
             In prior versions of Polars, HvPlot was the plotting backend. If you would
             like to restore the previous plotting functionality, all you need to do
-            add `import hvplot.polars` at the top of your script and replace
+            is add `import hvplot.polars` at the top of your script and replace
             `df.plot` with `df.hvplot`.
 
         Polars does not implement plotting logic itself, but instead defers to

py-polars/polars/dataframe/plotting.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Callable, Dict, Union
+from typing import TYPE_CHECKING, Callable, Dict, Union
 
 if TYPE_CHECKING:
     import sys
@@ -38,12 +38,10 @@
 class DataFramePlot:
     """DataFrame.plot namespace."""
 
-    chart: alt.Chart
-
     def __init__(self, df: DataFrame) -> None:
         import altair as alt
 
-        self.chart = alt.Chart(df)
+        self._chart = alt.Chart(df)
 
     def bar(
         self,
@@ -68,7 +66,7 @@ def bar(
         .. versionchanged:: 1.6.0
             In prior versions of Polars, HvPlot was the plotting backend. If you would
             like to restore the previous plotting functionality, all you need to do
-            add `import hvplot.polars` at the top of your script and replace
+            is add `import hvplot.polars` at the top of your script and replace
             `df.plot` with `df.hvplot`.
 
         Parameters
@@ -106,7 +104,7 @@ def bar(
             encodings["color"] = color
         if tooltip is not None:
             encodings["tooltip"] = tooltip
-        return self.chart.mark_bar().encode(**encodings, **kwargs).interactive()
+        return self._chart.mark_bar().encode(**encodings, **kwargs).interactive()
 
     def line(
         self,
@@ -131,7 +129,7 @@ def line(
         .. versionchanged:: 1.6.0
             In prior versions of Polars, HvPlot was the plotting backend. If you would
             like to restore the previous plotting functionality, all you need to do
-            add `import hvplot.polars` at the top of your script and replace
+            is add `import hvplot.polars` at the top of your script and replace
             `df.plot` with `df.hvplot`.
 
         Parameters
@@ -172,7 +170,7 @@ def line(
             encodings["order"] = order
         if tooltip is not None:
             encodings["tooltip"] = tooltip
-        return self.chart.mark_line().encode(**encodings, **kwargs).interactive()
+        return self._chart.mark_line().encode(**encodings, **kwargs).interactive()
 
     def point(
         self,
@@ -181,7 +179,8 @@ def point(
         color: ChannelColor | None = None,
         size: ChannelSize | None = None,
         tooltip: ChannelTooltip | None = None,
-        **kwargs: Any,
+        /,
+        **kwargs: Unpack[EncodeKwds],
     ) -> alt.Chart:
         """
         Draw scatter plot.
@@ -197,7 +196,7 @@ def point(
         .. versionchanged:: 1.6.0
             In prior versions of Polars, HvPlot was the plotting backend. If you would
             like to restore the previous plotting functionality, all you need to do
-            add `import hvplot.polars` at the top of your script and replace
+            is add `import hvplot.polars` at the top of your script and replace
             `df.plot` with `df.hvplot`.
 
         Parameters
@@ -238,9 +237,9 @@ def point(
         if tooltip is not None:
             encodings["tooltip"] = tooltip
         return (
-            self.chart.mark_point()
+            self._chart.mark_point()
             .encode(
-                **encodings,  # type: ignore[arg-type]
+                **encodings,
                 **kwargs,
             )
             .interactive()
@@ -250,7 +249,7 @@ def point(
     scatter = point
 
     def __getattr__(self, attr: str) -> Callable[..., alt.Chart]:
-        method = getattr(self.chart, f"mark_{attr}", None)
+        method = getattr(self._chart, f"mark_{attr}", None)
         if method is None:
             msg = "Altair has no method 'mark_{attr}'"
             raise AttributeError(msg)

py-polars/polars/series/plotting.py

@@ -1,48 +1,27 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Callable, Dict, Union
+from typing import TYPE_CHECKING, Callable
 
 from polars.dependencies import altair as alt
 
 if TYPE_CHECKING:
     import sys
 
-    from altair.typing import (
-        ChannelColor,
-        ChannelOrder,
-        ChannelSize,
-        ChannelTooltip,
-        ChannelX,
-        ChannelY,
-        EncodeKwds,
-    )
-
-    if sys.version_info >= (3, 10):
-        from typing import TypeAlias
-    else:
-        from typing_extensions import TypeAlias
+    from altair.typing import EncodeKwds
+
     if sys.version_info >= (3, 11):
         from typing import Unpack
     else:
         from typing_extensions import Unpack
 
     from polars import Series
 
-    Encodings: TypeAlias = Dict[
-        str,
-        Union[
-            ChannelX, ChannelY, ChannelColor, ChannelOrder, ChannelSize, ChannelTooltip
-        ],
-    ]
-
 
 class SeriesPlot:
     """Series.plot namespace."""
 
     _accessor = "plot"
 
-    chart: alt.Chart
-
     def __init__(self, s: Series) -> None:
         name = s.name or "value"
         self._df = s.to_frame(name)
@@ -67,7 +46,7 @@ def hist(
         .. versionchanged:: 1.6.0
             In prior versions of Polars, HvPlot was the plotting backend. If you would
             like to restore the previous plotting functionality, all you need to do
-            add `import hvplot.polars` at the top of your script and replace
+            is add `import hvplot.polars` at the top of your script and replace
             `df.plot` with `df.hvplot`.
 
         Parameters
@@ -109,7 +88,7 @@ def kde(
         .. versionchanged:: 1.6.0
             In prior versions of Polars, HvPlot was the plotting backend. If you would
             like to restore the previous plotting functionality, all you need to do
-            add `import hvplot.polars` at the top of your script and replace
+            is add `import hvplot.polars` at the top of your script and replace
             `df.plot` with `df.hvplot`.
 
         Parameters
@@ -152,7 +131,7 @@ def line(
         .. versionchanged:: 1.6.0
             In prior versions of Polars, HvPlot was the plotting backend. If you would
             like to restore the previous plotting functionality, all you need to do
-            add `import hvplot.polars` at the top of your script and replace
+            is add `import hvplot.polars` at the top of your script and replace
             `df.plot` with `df.hvplot`.
 
         Parameters

py-polars/polars/series/series.py

@@ -7370,7 +7370,7 @@ def plot(self) -> SeriesPlot:
         .. versionchanged:: 1.6.0
             In prior versions of Polars, HvPlot was the plotting backend. If you would
             like to restore the previous plotting functionality, all you need to do
-            add `import hvplot.polars` at the top of your script and replace
+            is add `import hvplot.polars` at the top of your script and replace
             `df.plot` with `df.hvplot`.
 
         Polars does not implement plotting logic itself, but instead defers to
@@ -7384,7 +7384,7 @@ def plot(self) -> SeriesPlot:
           `alt.Chart(s.to_frame()).transform_density(s.name, as_=[s.name, 'density']).mark_area().encode(x=s.name, y='density:Q', **kwargs).interactive()`
         - for any other attribute `attr`, `s.plot.attr(**kwargs)`
           is shorthand for
-          `alt.Chart(s.to_frame().with_row_index()).mark_attr().encode(x=s.name, y='index', **kwargs).interactive()`
+          `alt.Chart(s.to_frame().with_row_index()).mark_attr().encode(x='index', y=s.name, **kwargs).interactive()`
 
         Examples
         --------