From 4c203f6ce219f09f6b090f0a913126ff53a8c881 Mon Sep 17 00:00:00 2001 From: Machele Alhassan <57562100+Machele-codez@users.noreply.github.com> Date: Mon, 16 Dec 2024 17:36:46 +0000 Subject: [PATCH] docs: make docstring examples function names more descriptive in functions.py (#1602) --------- Co-authored-by: Marco Gorelli <33491632+MarcoGorelli@users.noreply.github.com> --- narwhals/functions.py | 62 +++++++++++++++++++++------------- narwhals/stable/v1/__init__.py | 62 +++++++++++++++++++++------------- 2 files changed, 76 insertions(+), 48 deletions(-) diff --git a/narwhals/functions.py b/narwhals/functions.py index bf2cbed39..c9363e383 100644 --- a/narwhals/functions.py +++ b/narwhals/functions.py @@ -218,36 +218,49 @@ def new_series( Examples: >>> import pandas as pd >>> import polars as pl + >>> import pyarrow as pa >>> import narwhals as nw + >>> from narwhals.typing import IntoFrameT, IntoSeriesT >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} Let's define a dataframe-agnostic function: - >>> @nw.narwhalify - ... def func(df): - ... values = [4, 1, 2] - ... native_namespace = nw.get_native_namespace(df) + >>> def agnostic_new_series(df_native: IntoFrameT) -> IntoSeriesT: + ... values = [4, 1, 2, 3] + ... native_namespace = nw.get_native_namespace(df_native) ... return nw.new_series( - ... name="c", + ... name="a", ... values=values, ... dtype=nw.Int32, ... native_namespace=native_namespace, - ... ) + ... ).to_native() - Let's see what happens when passing pandas / Polars input: + We can then pass any supported eager library, such as pandas / Polars / PyArrow: - >>> func(pd.DataFrame(data)) + >>> agnostic_new_series(pd.DataFrame(data)) 0 4 1 1 2 2 - Name: c, dtype: int32 - >>> func(pl.DataFrame(data)) # doctest: +NORMALIZE_WHITESPACE - shape: (3,) - Series: 'c' [i32] + 3 3 + Name: a, dtype: int32 + >>> agnostic_new_series(pl.DataFrame(data)) # doctest: +NORMALIZE_WHITESPACE + shape: (4,) + Series: 'a' [i32] [ 4 1 2 + 3 + ] + >>> agnostic_new_series(pa.table(data)) + + [ + [ + 4, + 1, + 2, + 3 + ] ] """ return _new_series_impl( @@ -348,23 +361,23 @@ def from_dict( >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw + >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} Let's create a new dataframe of the same class as the dataframe we started with, from a dict of new data: - >>> @nw.narwhalify - ... def func(df): + >>> def agnostic_from_dict(df_native: IntoFrameT) -> IntoFrameT: ... new_data = {"c": [5, 2], "d": [1, 4]} - ... native_namespace = nw.get_native_namespace(df) - ... return nw.from_dict(new_data, native_namespace=native_namespace) + ... native_namespace = nw.get_native_namespace(df_native) + ... return nw.from_dict(new_data, native_namespace=native_namespace).to_native() Let's see what happens when passing pandas, Polars or PyArrow input: - >>> func(pd.DataFrame(data)) + >>> agnostic_from_dict(pd.DataFrame(data)) c d 0 5 1 1 2 4 - >>> func(pl.DataFrame(data)) + >>> agnostic_from_dict(pl.DataFrame(data)) shape: (2, 2) ┌─────┬─────┐ │ c ┆ d │ @@ -374,7 +387,7 @@ def from_dict( │ 5 ┆ 1 │ │ 2 ┆ 4 │ └─────┴─────┘ - >>> func(pa.table(data)) + >>> agnostic_from_dict(pa.table(data)) pyarrow.Table c: int64 d: int64 @@ -761,25 +774,26 @@ def from_arrow( >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw + >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} Let's define a dataframe-agnostic function which creates a PyArrow Table. - >>> @nw.narwhalify - ... def func(df): - ... return nw.from_arrow(df, native_namespace=pa) + >>> def agnostic_to_arrow(df_native: IntoFrameT) -> IntoFrameT: + ... df = nw.from_native(df_native) + ... return nw.from_arrow(df, native_namespace=pa).to_native() Let's see what happens when passing pandas / Polars input: - >>> func(pd.DataFrame(data)) # doctest: +SKIP + >>> agnostic_to_arrow(pd.DataFrame(data)) pyarrow.Table a: int64 b: int64 ---- a: [[1,2,3]] b: [[4,5,6]] - >>> func(pl.DataFrame(data)) # doctest: +SKIP + >>> agnostic_to_arrow(pl.DataFrame(data)) pyarrow.Table a: int64 b: int64 diff --git a/narwhals/stable/v1/__init__.py b/narwhals/stable/v1/__init__.py index 3d482d351..e5aa8f28e 100644 --- a/narwhals/stable/v1/__init__.py +++ b/narwhals/stable/v1/__init__.py @@ -3079,36 +3079,49 @@ def new_series( Examples: >>> import pandas as pd >>> import polars as pl + >>> import pyarrow as pa >>> import narwhals as nw + >>> from narwhals.typing import IntoFrameT, IntoSeriesT >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} Let's define a dataframe-agnostic function: - >>> @nw.narwhalify - ... def func(df): - ... values = [4, 1, 2] - ... native_namespace = nw.get_native_namespace(df) + >>> def agnostic_new_series(df_native: IntoFrameT) -> IntoSeriesT: + ... values = [4, 1, 2, 3] + ... native_namespace = nw.get_native_namespace(df_native) ... return nw.new_series( - ... name="c", + ... name="a", ... values=values, ... dtype=nw.Int32, ... native_namespace=native_namespace, - ... ) + ... ).to_native() - Let's see what happens when passing pandas / Polars input: + We can then pass any supported eager library, such as pandas / Polars / PyArrow: - >>> func(pd.DataFrame(data)) + >>> agnostic_new_series(pd.DataFrame(data)) 0 4 1 1 2 2 - Name: c, dtype: int32 - >>> func(pl.DataFrame(data)) # doctest: +NORMALIZE_WHITESPACE - shape: (3,) - Series: 'c' [i32] + 3 3 + Name: a, dtype: int32 + >>> agnostic_new_series(pl.DataFrame(data)) # doctest: +NORMALIZE_WHITESPACE + shape: (4,) + Series: 'a' [i32] [ 4 1 2 + 3 + ] + >>> agnostic_new_series(pa.table(data)) + + [ + [ + 4, + 1, + 2, + 3 + ] ] """ return _stableify( # type: ignore[no-any-return] @@ -3139,25 +3152,26 @@ def from_arrow( >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw + >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} Let's define a dataframe-agnostic function which creates a PyArrow Table. - >>> @nw.narwhalify - ... def func(df): - ... return nw.from_arrow(df, native_namespace=pa) + >>> def agnostic_to_arrow(df_native: IntoFrameT) -> IntoFrameT: + ... df = nw.from_native(df_native) + ... return nw.from_arrow(df, native_namespace=pa).to_native() Let's see what happens when passing pandas / Polars input: - >>> func(pd.DataFrame(data)) # doctest: +SKIP + >>> agnostic_to_arrow(pd.DataFrame(data)) pyarrow.Table a: int64 b: int64 ---- a: [[1,2,3]] b: [[4,5,6]] - >>> func(pl.DataFrame(data)) # doctest: +SKIP + >>> agnostic_to_arrow(pl.DataFrame(data)) pyarrow.Table a: int64 b: int64 @@ -3199,23 +3213,23 @@ def from_dict( >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw + >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} Let's create a new dataframe of the same class as the dataframe we started with, from a dict of new data: - >>> @nw.narwhalify - ... def func(df): + >>> def agnostic_from_dict(df_native: IntoFrameT) -> IntoFrameT: ... new_data = {"c": [5, 2], "d": [1, 4]} - ... native_namespace = nw.get_native_namespace(df) - ... return nw.from_dict(new_data, native_namespace=native_namespace) + ... native_namespace = nw.get_native_namespace(df_native) + ... return nw.from_dict(new_data, native_namespace=native_namespace).to_native() Let's see what happens when passing pandas, Polars or PyArrow input: - >>> func(pd.DataFrame(data)) + >>> agnostic_from_dict(pd.DataFrame(data)) c d 0 5 1 1 2 4 - >>> func(pl.DataFrame(data)) + >>> agnostic_from_dict(pl.DataFrame(data)) shape: (2, 2) ┌─────┬─────┐ │ c ┆ d │ @@ -3225,7 +3239,7 @@ def from_dict( │ 5 ┆ 1 │ │ 2 ┆ 4 │ └─────┴─────┘ - >>> func(pa.table(data)) + >>> agnostic_from_dict(pa.table(data)) pyarrow.Table c: int64 d: int64