Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: make docstring examples function names more descriptive in functions.py #1602

Merged
merged 4 commits into from
Dec 16, 2024
Merged

docs: make docstring examples function names more descriptive in functions.py #1602

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
881581e
docs: make docstring examples function names more descriptive - funct…
Machele-codez Dec 15, 2024
11f783e
tests pass: pytest narwhals --doctest-modules
Machele-codez Dec 16, 2024
95457ac
fixup
MarcoGorelli Dec 16, 2024
8fd10d0
unskip
MarcoGorelli Dec 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 38 additions & 24 deletions narwhals/functions.py
View file
Open in desktop
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
Open in desktop
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
Loading