Skip to content

Commit

Permalink
docs: improve DataFrame, LazyFrame and Series docstrings (#1622)
Browse files Browse the repository at this point in the history
* docs: improve DataFrame, LazyFrame and Series docstrings

* maybe fix broken link

* matching docstrings
  • Loading branch information
FBruzzesi authored Dec 19, 2024
1 parent 75c3e7c commit 0c933ee
Show file tree
Hide file tree
Showing 4 changed files with 107 additions and 35 deletions.
44 changes: 32 additions & 12 deletions narwhals/dataframe.py
Original file line number Diff line number Diff line change
Expand Up @@ -337,12 +337,28 @@ def __eq__(self, other: object) -> NoReturn:


class DataFrame(BaseFrame[DataFrameT]):
"""Narwhals DataFrame, backed by a native dataframe.
The native dataframe might be pandas.DataFrame, polars.DataFrame, ...
This class is not meant to be instantiated directly - instead, use
`narwhals.from_native`.
"""Narwhals DataFrame, backed by a native eager dataframe.
!!! warning
This class is not meant to be instantiated directly - instead:
- If the native object is a eager dataframe from one of the supported
backend (e.g. pandas.DataFrame, polars.DataFrame, pyarrow.Table),
you can use [`narwhals.from_native`](../narwhals/#narwhals.from_native):
```py
narwhals.from_native(native_dataframe)
narwhals.from_native(native_dataframe, eager_only=True)
```
- If the object is a dictionary of column names and generic sequences mapping
(e.g. `dict[str, list]`), you can create a DataFrame via
[`narwhals.from_dict`](../narwhals/#narwhals.from_dict):
```py
narwhals.from_dict(
data={"a": [1, 2, 3]},
native_namespace=narwhals.get_native_namespace(another_object),
)
```
"""

@property
Expand Down Expand Up @@ -3004,12 +3020,16 @@ def unpivot(


class LazyFrame(BaseFrame[FrameT]):
"""Narwhals DataFrame, backed by a native dataframe.
The native dataframe might be pandas.DataFrame, polars.LazyFrame, ...
This class is not meant to be instantiated directly - instead, use
`narwhals.from_native`.
"""Narwhals LazyFrame, backed by a native lazyframe.
!!! warning
This class is not meant to be instantiated directly - instead use
[`narwhals.from_native`](../narwhals/#narwhals.from_native) with a native
object that is a lazy dataframe from one of the supported
backend (e.g. polars.LazyFrame, dask_expr._collection.DataFrame):
```py
narwhals.from_native(native_lazyframe)
```
"""

@property
Expand Down
3 changes: 2 additions & 1 deletion narwhals/expr.py
Original file line number Diff line number Diff line change
Expand Up @@ -6087,7 +6087,8 @@ def nth(*indices: int | Sequence[int]) -> Expr:
"""Creates an expression that references one or more columns by their index(es).
Notes:
`nth` is not supported for Polars version<1.0.0. Please use [`col`](/api-reference/narwhals/#narwhals.col) instead.
`nth` is not supported for Polars version<1.0.0. Please use
[`col`](../narwhals/#narwhals.col) instead.
Arguments:
indices: One or more indices representing the columns to retrieve.
Expand Down
23 changes: 19 additions & 4 deletions narwhals/series.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,11 +33,26 @@
class Series(Generic[IntoSeriesT]):
"""Narwhals Series, backed by a native series.
The native series might be pandas.Series, polars.Series, ...
!!! warning
This class is not meant to be instantiated directly - instead:
- If the native object is a series from one of the supported backend (e.g.
pandas.Series, polars.Series, pyarrow.ChunkedArray), you can use
[`narwhals.from_native`](../narwhals/#narwhals.from_native):
```py
narwhals.from_native(native_series, allow_series=True)
narwhals.from_native(native_series, series_only=True)
```
This class is not meant to be instantiated directly - instead, use
`narwhals.from_native`, making sure to pass `allow_series=True` or
`series_only=True`.
- If the object is a generic sequence (e.g. a list or a tuple of values), you can
create a series via [`narwhals.new_series`](../narwhals/#narwhals.new_series):
```py
narwhals.new_series(
name=name,
values=values,
native_namespace=narwhals.get_native_namespace(another_object),
)
```
"""

@property
Expand Down
72 changes: 54 additions & 18 deletions narwhals/stable/v1/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -92,12 +92,28 @@


class DataFrame(NwDataFrame[IntoDataFrameT]):
"""Narwhals DataFrame, backed by a native dataframe.
The native dataframe might be pandas.DataFrame, polars.DataFrame, ...
This class is not meant to be instantiated directly - instead, use
`narwhals.from_native`.
"""Narwhals DataFrame, backed by a native eager dataframe.
!!! warning
This class is not meant to be instantiated directly - instead:
- If the native object is a eager dataframe from one of the supported
backend (e.g. pandas.DataFrame, polars.DataFrame, pyarrow.Table),
you can use [`narwhals.from_native`](../narwhals/#narwhals.from_native):
```py
narwhals.from_native(native_dataframe)
narwhals.from_native(native_dataframe, eager_only=True)
```
- If the object is a dictionary of column names and generic sequences mapping
(e.g. `dict[str, list]`), you can create a DataFrame via
[`narwhals.from_dict`](../narwhals/#narwhals.from_dict):
```py
narwhals.from_dict(
data={"a": [1, 2, 3]},
native_namespace=narwhals.get_native_namespace(another_object),
)
```
"""

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


class LazyFrame(NwLazyFrame[IntoFrameT]):
"""Narwhals DataFrame, backed by a native dataframe.
The native dataframe might be pandas.DataFrame, polars.LazyFrame, ...
This class is not meant to be instantiated directly - instead, use
`narwhals.from_native`.
"""Narwhals LazyFrame, backed by a native lazyframe.
!!! warning
This class is not meant to be instantiated directly - instead use
[`narwhals.from_native`](../narwhals/#narwhals.from_native) with a native
object that is a lazy dataframe from one of the supported
backend (e.g. polars.LazyFrame, dask_expr._collection.DataFrame):
```py
narwhals.from_native(native_lazyframe)
```
"""

@property
Expand Down Expand Up @@ -425,11 +445,26 @@ def _l1_norm(self: Self) -> Self:
class Series(NwSeries[Any]):
"""Narwhals Series, backed by a native series.
The native series might be pandas.Series, polars.Series, ...
This class is not meant to be instantiated directly - instead, use
`narwhals.from_native`, making sure to pass `allow_series=True` or
`series_only=True`.
!!! warning
This class is not meant to be instantiated directly - instead:
- If the native object is a series from one of the supported backend (e.g.
pandas.Series, polars.Series, pyarrow.ChunkedArray), you can use
[`narwhals.from_native`](../narwhals/#narwhals.from_native):
```py
narwhals.from_native(native_series, allow_series=True)
narwhals.from_native(native_series, series_only=True)
```
- If the object is a generic sequence (e.g. a list or a tuple of values), you can
create a series via [`narwhals.new_series`](../narwhals/#narwhals.new_series):
```py
narwhals.new_series(
name=name,
values=values,
native_namespace=narwhals.get_native_namespace(another_object),
)
```
"""

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

0 comments on commit 0c933ee

Please sign in to comment.