Skip to content

Commit

Permalink
docs: make docstring examples function names more descriptive in func…
Browse files Browse the repository at this point in the history 
…tions.py (#1602)



---------

Co-authored-by: Marco Gorelli <[email protected]>
  • Loading branch information
@Machele-codez @MarcoGorelli
Machele-codez and MarcoGorelli authored Dec 16, 2024
1 parent 7c89fb8 commit 4c203f6
Show file tree
Hide file tree
Showing 2 changed files with 76 additions and 48 deletions.
62 changes: 38 additions & 24 deletions narwhals/functions.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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))
<pyarrow.lib.ChunkedArray object at ...>
[
[
4,
1,
2,
3
]
]
"""
return _new_series_impl(
Expand Down Expand Up @@ -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 │
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
62 changes: 38 additions & 24 deletions narwhals/stable/v1/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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))
<pyarrow.lib.ChunkedArray object at ...>
[
[
4,
1,
2,
3
]
]
"""
return _stableify( # type: ignore[no-any-return]
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 │
Expand All @@ -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
Expand Down

0 comments on commit 4c203f6

Please sign in to comment.