Skip to content

Commit 0c933ee

Browse files
FBruzzesiFBruzzesi
authored
docs: improve DataFrame, LazyFrame and Series docstrings (#1622)
* docs: improve DataFrame, LazyFrame and Series docstrings * maybe fix broken link * matching docstrings
1 parent 75c3e7c commit 0c933ee

File tree

4 files changed

+107
-35
lines changed

4 files changed

+107
-35
lines changed

‎narwhals/dataframe.py

+32-12
Original file line numberDiff line numberDiff line change
@@ -337,12 +337,28 @@ def __eq__(self, other: object) -> NoReturn:
337337

338338

339339
class DataFrame(BaseFrame[DataFrameT]):
340-
"""Narwhals DataFrame, backed by a native dataframe.
341-
342-
The native dataframe might be pandas.DataFrame, polars.DataFrame, ...
343-
344-
This class is not meant to be instantiated directly - instead, use
345-
`narwhals.from_native`.
340+
"""Narwhals DataFrame, backed by a native eager dataframe.
341+
342+
!!! warning
343+
This class is not meant to be instantiated directly - instead:
344+
345+
- If the native object is a eager dataframe from one of the supported
346+
backend (e.g. pandas.DataFrame, polars.DataFrame, pyarrow.Table),
347+
you can use [`narwhals.from_native`](../narwhals/#narwhals.from_native):
348+
```py
349+
narwhals.from_native(native_dataframe)
350+
narwhals.from_native(native_dataframe, eager_only=True)
351+
```
352+
353+
- If the object is a dictionary of column names and generic sequences mapping
354+
(e.g. `dict[str, list]`), you can create a DataFrame via
355+
[`narwhals.from_dict`](../narwhals/#narwhals.from_dict):
356+
```py
357+
narwhals.from_dict(
358+
data={"a": [1, 2, 3]},
359+
native_namespace=narwhals.get_native_namespace(another_object),
360+
)
361+
```
346362
"""
347363

348364
@property
@@ -3004,12 +3020,16 @@ def unpivot(
30043020

30053021

30063022
class LazyFrame(BaseFrame[FrameT]):
3007-
"""Narwhals DataFrame, backed by a native dataframe.
3008-
3009-
The native dataframe might be pandas.DataFrame, polars.LazyFrame, ...
3010-
3011-
This class is not meant to be instantiated directly - instead, use
3012-
`narwhals.from_native`.
3023+
"""Narwhals LazyFrame, backed by a native lazyframe.
3024+
3025+
!!! warning
3026+
This class is not meant to be instantiated directly - instead use
3027+
[`narwhals.from_native`](../narwhals/#narwhals.from_native) with a native
3028+
object that is a lazy dataframe from one of the supported
3029+
backend (e.g. polars.LazyFrame, dask_expr._collection.DataFrame):
3030+
```py
3031+
narwhals.from_native(native_lazyframe)
3032+
```
30133033
"""
30143034

30153035
@property

‎narwhals/expr.py

+2-1
Original file line numberDiff line numberDiff line change
@@ -6087,7 +6087,8 @@ def nth(*indices: int | Sequence[int]) -> Expr:
60876087
"""Creates an expression that references one or more columns by their index(es).
60886088
60896089
Notes:
6090-
`nth` is not supported for Polars version<1.0.0. Please use [`col`](/api-reference/narwhals/#narwhals.col) instead.
6090+
`nth` is not supported for Polars version<1.0.0. Please use
6091+
[`col`](../narwhals/#narwhals.col) instead.
60916092
60926093
Arguments:
60936094
indices: One or more indices representing the columns to retrieve.

‎narwhals/series.py

+19-4
Original file line numberDiff line numberDiff line change
@@ -33,11 +33,26 @@
3333
class Series(Generic[IntoSeriesT]):
3434
"""Narwhals Series, backed by a native series.
3535
36-
The native series might be pandas.Series, polars.Series, ...
36+
!!! warning
37+
This class is not meant to be instantiated directly - instead:
38+
39+
- If the native object is a series from one of the supported backend (e.g.
40+
pandas.Series, polars.Series, pyarrow.ChunkedArray), you can use
41+
[`narwhals.from_native`](../narwhals/#narwhals.from_native):
42+
```py
43+
narwhals.from_native(native_series, allow_series=True)
44+
narwhals.from_native(native_series, series_only=True)
45+
```
3746
38-
This class is not meant to be instantiated directly - instead, use
39-
`narwhals.from_native`, making sure to pass `allow_series=True` or
40-
`series_only=True`.
47+
- If the object is a generic sequence (e.g. a list or a tuple of values), you can
48+
create a series via [`narwhals.new_series`](../narwhals/#narwhals.new_series):
49+
```py
50+
narwhals.new_series(
51+
name=name,
52+
values=values,
53+
native_namespace=narwhals.get_native_namespace(another_object),
54+
)
55+
```
4156
"""
4257

4358
@property

‎narwhals/stable/v1/__init__.py

+54-18
Original file line numberDiff line numberDiff line change
@@ -92,12 +92,28 @@
9292

9393

9494
class DataFrame(NwDataFrame[IntoDataFrameT]):
95-
"""Narwhals DataFrame, backed by a native dataframe.
96-
97-
The native dataframe might be pandas.DataFrame, polars.DataFrame, ...
98-
99-
This class is not meant to be instantiated directly - instead, use
100-
`narwhals.from_native`.
95+
"""Narwhals DataFrame, backed by a native eager dataframe.
96+
97+
!!! warning
98+
This class is not meant to be instantiated directly - instead:
99+
100+
- If the native object is a eager dataframe from one of the supported
101+
backend (e.g. pandas.DataFrame, polars.DataFrame, pyarrow.Table),
102+
you can use [`narwhals.from_native`](../narwhals/#narwhals.from_native):
103+
```py
104+
narwhals.from_native(native_dataframe)
105+
narwhals.from_native(native_dataframe, eager_only=True)
106+
```
107+
108+
- If the object is a dictionary of column names and generic sequences mapping
109+
(e.g. `dict[str, list]`), you can create a DataFrame via
110+
[`narwhals.from_dict`](../narwhals/#narwhals.from_dict):
111+
```py
112+
narwhals.from_dict(
113+
data={"a": [1, 2, 3]},
114+
native_namespace=narwhals.get_native_namespace(another_object),
115+
)
116+
```
101117
"""
102118

103119
# We need to override any method which don't return Self so that type
@@ -364,12 +380,16 @@ def _l1_norm(self: Self) -> Self:
364380

365381

366382
class LazyFrame(NwLazyFrame[IntoFrameT]):
367-
"""Narwhals DataFrame, backed by a native dataframe.
368-
369-
The native dataframe might be pandas.DataFrame, polars.LazyFrame, ...
370-
371-
This class is not meant to be instantiated directly - instead, use
372-
`narwhals.from_native`.
383+
"""Narwhals LazyFrame, backed by a native lazyframe.
384+
385+
!!! warning
386+
This class is not meant to be instantiated directly - instead use
387+
[`narwhals.from_native`](../narwhals/#narwhals.from_native) with a native
388+
object that is a lazy dataframe from one of the supported
389+
backend (e.g. polars.LazyFrame, dask_expr._collection.DataFrame):
390+
```py
391+
narwhals.from_native(native_lazyframe)
392+
```
373393
"""
374394

375395
@property
@@ -425,11 +445,26 @@ def _l1_norm(self: Self) -> Self:
425445
class Series(NwSeries[Any]):
426446
"""Narwhals Series, backed by a native series.
427447
428-
The native series might be pandas.Series, polars.Series, ...
429-
430-
This class is not meant to be instantiated directly - instead, use
431-
`narwhals.from_native`, making sure to pass `allow_series=True` or
432-
`series_only=True`.
448+
!!! warning
449+
This class is not meant to be instantiated directly - instead:
450+
451+
- If the native object is a series from one of the supported backend (e.g.
452+
pandas.Series, polars.Series, pyarrow.ChunkedArray), you can use
453+
[`narwhals.from_native`](../narwhals/#narwhals.from_native):
454+
```py
455+
narwhals.from_native(native_series, allow_series=True)
456+
narwhals.from_native(native_series, series_only=True)
457+
```
458+
459+
- If the object is a generic sequence (e.g. a list or a tuple of values), you can
460+
create a series via [`narwhals.new_series`](../narwhals/#narwhals.new_series):
461+
```py
462+
narwhals.new_series(
463+
name=name,
464+
values=values,
465+
native_namespace=narwhals.get_native_namespace(another_object),
466+
)
467+
```
433468
"""
434469

435470
# We need to override any method which don't return Self so that type
@@ -2334,7 +2369,8 @@ def nth(*indices: int | Sequence[int]) -> Expr:
23342369
"""Creates an expression that references one or more columns by their index(es).
23352370
23362371
Notes:
2337-
`nth` is not supported for Polars version<1.0.0. Please use [`col`](/api-reference/narwhals/#narwhals.col) instead.
2372+
`nth` is not supported for Polars version<1.0.0. Please use
2373+
[`col`](../narwhals/#narwhals.col) instead.
23382374
23392375
Arguments:
23402376
indices: One or more indices representing the columns to retrieve.

0 commit comments

Comments
 (0)