Merge remote-tracking branch 'upstream/main' into df-repr-html

Author: dangotbanned

.github/workflows/pytest-pyspark.yml

@@ -2,7 +2,12 @@ name: PyTest PySpark constructor
 
 on:
   pull_request:
-    types: [opened, labeled, synchronize]  # Triggers on PR creation, updates, and label changes
+    paths:
+      - narwhals/_expression_parsing.py
+      - narwhals/_spark_like/**
+      - narwhals/_sql/**
+  schedule:
+    - cron: 0 12 * * 0  # Sunday at mid-day
 
 env:
   PY_COLORS: 1
@@ -11,10 +16,9 @@ env:
 jobs:
 
   pytest-pyspark-constructor:
-    if: ${{ contains(github.event.pull_request.labels.*.name, 'pyspark') || contains(github.event.pull_request.labels.*.name, 'spark-like') || contains(github.event.pull_request.labels.*.name, 'release')}}
     strategy:
       matrix:
-        python-version: ["3.10", "3.11"]
+        python-version: ["3.11"]
         os: [ubuntu-latest]
     runs-on: ${{ matrix.os }}
     steps:
@@ -39,10 +43,9 @@ jobs:
 
 
   pytest-pyspark-connect-constructor:
-    if: ${{ contains(github.event.pull_request.labels.*.name, 'pyspark-connect') || contains(github.event.pull_request.labels.*.name, 'release') }}
     strategy:
       matrix:
-        python-version: ["3.10", "3.11"]
+        python-version: ["3.11"]
         os: [ubuntu-latest]
     env:
       SPARK_VERSION: 3.5.5

.pre-commit-config.yaml

@@ -26,18 +26,15 @@ repos:
     hooks:
     -   id: flake8
         additional_dependencies: [darglint==1.8.1, Flake8-pyproject]
-        entry: flake8 --select DAR --ignore DAR101,DAR402,DAR401
+        entry: flake8 --select DAR --ignore DAR101,DAR401,DAR402
         exclude: |
             (?x)^(
                 tests/.*|
                 # TODO: gradually enable
-                narwhals/series\.py|
-                # TODO: gradually enable
-                narwhals/dataframe\.py|
-                # TODO: gradually enable
                 narwhals/dependencies\.py|
-                # private, so less urgent to document too well
+                # Private, so less urgent to document too well
                 narwhals/_.*|
+                # Internal use only, less urgent
                 ^utils/.*|
                 # Soft-deprecated, so less crucial to document so carefully
                 narwhals/stable/v1/.*

docs/api-reference/series.md

@@ -29,6 +29,7 @@
         - exp
         - fill_null
         - filter
+        - from_numpy
         - gather_every
         - head
         - hist

narwhals/_compliant/series.py

@@ -285,15 +285,15 @@ def hist_from_bin_count(
         ...
 
     @property
-    def str(self) -> Any: ...
+    def str(self) -> StringNamespace[Self]: ...
     @property
-    def dt(self) -> Any: ...
+    def dt(self) -> DateTimeNamespace[Self]: ...
     @property
-    def cat(self) -> Any: ...
+    def cat(self) -> CatNamespace[Self]: ...
     @property
-    def list(self) -> Any: ...
+    def list(self) -> ListNamespace[Self]: ...
     @property
-    def struct(self) -> Any: ...
+    def struct(self) -> StructNamespace[Self]: ...
 
 
 class EagerSeries(CompliantSeries[NativeSeriesT], Protocol[NativeSeriesT]):

narwhals/_duckdb/expr.py

@@ -292,23 +292,6 @@ def window_f(df: DuckDBLazyFrame, inputs: DuckDBWindowInputs) -> list[Expression
             version=self._version,
         )
 
-    def log(self, base: float) -> Self:
-        def _log(expr: Expression) -> Expression:
-            log = F("log", expr)
-            return (
-                when(expr < lit(0), lit(float("nan")))
-                .when(expr == lit(0), lit(float("-inf")))
-                .otherwise(log / F("log", lit(base)))
-            )
-
-        return self._with_elementwise(_log)
-
-    def sqrt(self) -> Self:
-        def _sqrt(expr: Expression) -> Expression:
-            return when(expr < lit(0), lit(float("nan"))).otherwise(F("sqrt", expr))
-
-        return self._with_elementwise(_sqrt)
-
     @property
     def str(self) -> DuckDBExprStringNamespace:
         return DuckDBExprStringNamespace(self)

narwhals/_duckdb/namespace.py

@@ -63,8 +63,15 @@ def _function(self, name: str, *args: Expression) -> Expression:  # type: ignore
     def _lit(self, value: Any) -> Expression:
         return lit(value)
 
-    def _when(self, condition: Expression, value: Expression) -> Expression:
-        return when(condition, value)
+    def _when(
+        self,
+        condition: Expression,
+        value: Expression,
+        otherwise: Expression | None = None,
+    ) -> Expression:
+        if otherwise is None:
+            return when(condition, value)
+        return when(condition, value).otherwise(otherwise)
 
     def _coalesce(self, *exprs: Expression) -> Expression:
         return CoalesceOperator(*exprs)

narwhals/_exceptions.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from warnings import warn
+
+
+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
+    """
+    import inspect
+    from pathlib import Path
+
+    import narwhals as nw
+
+    pkg_dir = str(Path(nw.__file__).parent)
+
+    # https://stackoverflow.com/questions/17407119/python-inspect-stack-is-slow
+    frame = inspect.currentframe()
+    n = 0
+    try:
+        while frame:
+            fname = inspect.getfile(frame)
+            if fname.startswith(pkg_dir) or (
+                (qualname := getattr(frame.f_code, "co_qualname", None))
+                # ignore @singledispatch wrappers
+                and qualname.startswith("singledispatch.")
+            ):
+                frame = frame.f_back
+                n += 1
+            else:  # pragma: no cover
+                break
+        else:  # pragma: no cover
+            pass
+    finally:
+        # https://docs.python.org/3/library/inspect.html
+        # > Though the cycle detector will catch these, destruction of the frames
+        # > (and local variables) can be made deterministic by removing the cycle
+        # > in a finally clause.
+        del frame
+    return n
+
+
+def issue_deprecation_warning(message: str, _version: str) -> None:  # pragma: no cover
+    """Issue a deprecation warning.
+
+    Arguments:
+        message: The message associated with the warning.
+        _version: Narwhals version when the warning was introduced. Just used for internal
+            bookkeeping.
+    """
+    warn(message=message, category=DeprecationWarning, stacklevel=find_stacklevel())
+
+
+def issue_warning(message: str, category: type[Warning]) -> None:
+    warn(message=message, category=category, stacklevel=find_stacklevel())

narwhals/_expression_parsing.py

@@ -1,6 +1,7 @@
 # Utilities for expression parsing
 # Useful for backends which don't have any concept of expressions, such
 # and pandas or PyArrow.
+# ! Any change to this module will trigger the pyspark and pyspark-connect tests in CI
 from __future__ import annotations
 
 from enum import Enum, auto

narwhals/_ibis/expr.py

@@ -324,23 +324,6 @@ def _rank(expr: ir.Column) -> ir.Column:
 
         return self._with_callable(_rank)
 
-    def log(self, base: float) -> Self:
-        def _log(expr: ir.NumericColumn) -> ir.Value:
-            otherwise = expr.log(cast("ir.NumericValue", lit(base)))
-            return ibis.cases(
-                (expr < lit(0), lit(float("nan"))),
-                (expr == lit(0), lit(float("-inf"))),
-                else_=otherwise,
-            )
-
-        return self._with_callable(_log)
-
-    def sqrt(self) -> Self:
-        def _sqrt(expr: ir.NumericColumn) -> ir.Value:
-            return ibis.cases((expr < lit(0), lit(float("nan"))), else_=expr.sqrt())
-
-        return self._with_callable(_sqrt)
-
     @property
     def str(self) -> IbisExprStringNamespace:
         return IbisExprStringNamespace(self)

narwhals/_ibis/namespace.py

@@ -51,8 +51,12 @@ def _function(self, name: str, *args: ir.Value | PythonLiteral) -> ir.Value:
     def _lit(self, value: Any) -> ir.Value:
         return lit(value)
 
-    def _when(self, condition: ir.Value, value: ir.Value) -> ir.Value:
-        return ibis.cases((condition, value))
+    def _when(
+        self, condition: ir.Value, value: ir.Value, otherwise: ir.Expr | None = None
+    ) -> ir.Value:
+        if otherwise is None:
+            return ibis.cases((condition, value))
+        return ibis.cases((condition, value), else_=otherwise)  # pragma: no cover
 
     def _coalesce(self, *exprs: ir.Value) -> ir.Value:
         return ibis.coalesce(*exprs)