docs(python) remove now unnecessary returns statements (#3170)

* feat

* fixup#

* typing, docs

Author: MarcoGorelli

docstring_template.mustache

@@ -10,17 +10,3 @@ Arguments:
     {{var}}: {{descriptionPlaceholder}}
 {{/kwargs}}
 {{/parametersExist}}
-{{#returnsExist}}
-
-Returns:
-{{#returns}}
-    {{descriptionPlaceholder}}
-{{/returns}}
-{{/returnsExist}}
-{{#yieldsExist}}
-
-Yields:
-{{#yields}}
-    {{descriptionPlaceholder}}
-{{/yields}}
-{{/yieldsExist}}

narwhals/_duckdb/utils.py

@@ -59,8 +59,6 @@ def concat_str(*exprs: Expression, separator: str = "") -> Expression:
         exprs: Native columns.
         separator: String that will be used to separate the values of each column.
 
-    Returns:
-        A new native expression.
 
     [concat]: https://duckdb.org/docs/stable/sql/functions/char.html#concatstring-
     [concat_ws]: https://duckdb.org/docs/stable/sql/functions/char.html#concat_wsseparator-string-

narwhals/_exceptions.py

@@ -6,9 +6,6 @@
 def find_stacklevel() -> int:
     """Find the first place in the stack that is not inside narwhals.
 
-    Returns:
-        Stacklevel.
-
     Taken from:
     https://github.com/pandas-dev/pandas/blob/ab89c53f48df67709a533b6a95ce3d911871a0a8/pandas/util/_exceptions.py#L30-L51
     """

narwhals/_polars/series.py

@@ -652,12 +652,12 @@ def to_polars(self) -> pl.Series:
     def first(self) -> PythonLiteral:
         if self._backend_version < (1, 10):  # pragma: no cover
             return self.native.item(0) if len(self) else None
-        return self.native.first()
+        return self.native.first()  # type: ignore[return-value]
 
     def last(self) -> PythonLiteral:
         if self._backend_version < (1, 10):  # pragma: no cover
             return self.native.item(-1) if len(self) else None
-        return self.native.last()
+        return self.native.last()  # type: ignore[return-value]
 
     @property
     def dt(self) -> PolarsSeriesDateTimeNamespace:

narwhals/_utils.py

@@ -695,9 +695,6 @@ def parse_version(version: str | ModuleType | _SupportsVersion) -> tuple[int, ..
 
     Arguments:
         version: Version string, or object with one, to parse.
-
-    Returns:
-        Parsed version number.
     """
     # lifted from Polars
     # [marco]: Take care of DuckDB pre-releases which end with e.g. `-dev4108`
@@ -779,9 +776,6 @@ def maybe_align_index(
         lhs: Dataframe or Series.
         rhs: Dataframe or Series to align with.
 
-    Returns:
-        Same type as input.
-
     Notes:
         This is only really intended for backwards-compatibility purposes,
         for example if your library already aligns indices for users.
@@ -871,9 +865,6 @@ def maybe_get_index(obj: DataFrame[Any] | LazyFrame[Any] | Series[Any]) -> Any |
     Arguments:
         obj: Dataframe or Series.
 
-    Returns:
-        Same type as input.
-
     Notes:
         This is only really intended for backwards-compatibility purposes,
         for example if your library already aligns indices for users.
@@ -918,9 +909,6 @@ def maybe_set_index(
             `ValueError` is raised.
         index: series or list of series to set as index.
 
-    Returns:
-        Same type as input.
-
     Raises:
         ValueError: If one of the following conditions happens
 
@@ -996,9 +984,6 @@ def maybe_reset_index(obj: FrameOrSeriesT) -> FrameOrSeriesT:
     Arguments:
         obj: Dataframe or Series.
 
-    Returns:
-        Same type as input.
-
     Notes:
         This is only really intended for backwards-compatibility purposes,
         for example if your library already resets the index for users.
@@ -1106,9 +1091,6 @@ def maybe_convert_dtypes(
         *args: Additional arguments which gets passed through.
         **kwargs: Additional arguments which gets passed through.
 
-    Returns:
-        Same type as input.
-
     Notes:
         For non-pandas-like inputs, this is a no-op.
         Also, `args` and `kwargs` just get passed down to the underlying library as-is.
@@ -1146,9 +1128,6 @@ def scale_bytes(sz: int, unit: SizeUnit) -> int | float:
     Arguments:
         sz: original size in bytes
         unit: size unit to convert into
-
-    Returns:
-        Integer or float.
     """
     if unit in {"b", "bytes"}:
         return sz
@@ -1182,9 +1161,6 @@ def is_ordered_categorical(series: Series[Any]) -> bool:
     Arguments:
         series: Input Series.
 
-    Returns:
-        Whether the Series is an ordered categorical.
-
     Examples:
         >>> import narwhals as nw
         >>> import pandas as pd
@@ -1677,9 +1653,6 @@ def _into_arrow_table(data: IntoArrowTable, context: _LimitedContext, /) -> pa.T
     Arguments:
         data: Object which implements `__arrow_c_stream__`.
         context: Initialized compliant object.
-
-    Returns:
-        A PyArrow Table.
     """
     if find_spec("pyarrow"):
         ns = context._version.namespace.from_backend("pyarrow").compliant

narwhals/dataframe.py

@@ -1842,9 +1842,6 @@ def top_k(
             reverse: Consider the k smallest elements of the by column(s) (instead of the k largest).
                 This can be specified per column by passing a sequence of booleans.
 
-        Returns:
-            The dataframe with the `k` largest rows.
-
         Examples:
             >>> import pandas as pd
             >>> import narwhals as nw
@@ -3088,9 +3085,6 @@ def top_k(
             reverse: Consider the k smallest elements of the by column(s) (instead of the k largest).
                 This can be specified per column by passing a sequence of booleans.
 
-        Returns:
-            The LazyFrame with the `k` largest rows.
-
         Examples:
             >>> import duckdb
             >>> import narwhals as nw

narwhals/dependencies.py

@@ -480,9 +480,6 @@ def is_into_series(native_series: Any | IntoSeriesT) -> TypeIs[IntoSeriesT]:
     Arguments:
         native_series: The object to check.
 
-    Returns:
-        `True` if `native_series` can be converted to a Narwhals Series, `False` otherwise.
-
     Examples:
         >>> import pandas as pd
         >>> import polars as pl
@@ -517,9 +514,6 @@ def is_into_dataframe(native_dataframe: Any | IntoDataFrameT) -> TypeIs[IntoData
     Arguments:
         native_dataframe: The object to check.
 
-    Returns:
-        `True` if `native_dataframe` can be converted to a Narwhals DataFrame, `False` otherwise.
-
     Examples:
         >>> import pandas as pd
         >>> import polars as pl

narwhals/expr_list.py

@@ -111,9 +111,6 @@ def get(self, index: int) -> ExprT:
 
         Negative indices are not accepted.
 
-        Returns:
-            A new expression.
-
         Examples:
             >>> import polars as pl
             >>> import narwhals as nw