docstrings

narwhals-dev · Jan 2, 2025 · 54c4a81 · 54c4a81
2 parents 4bbc5a0 + 44d449d
commit 54c4a81
Show file tree

Hide file tree

Showing 75 changed files with 4,037 additions and 1,731 deletions.
diff --git a/.github/workflows/check_docs_build.yml b/.github/workflows/check_docs_build.yml
@@ -19,7 +19,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}

diff --git a/.github/workflows/check_tpch_queries.yml b/.github/workflows/check_tpch_queries.yml
@@ -19,13 +19,13 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}
           cache-dependency-glob: "pyproject.toml"
       - name: local-install
-        run: uv pip install -e ".[dev, dask]" --system
+        run: uv pip install -e ".[dev, core, dask]" --system
       - name: generate-data
         run: cd tpch && python generate_data.py
       - name: tpch-tests 

diff --git a/.github/workflows/downstream_tests.yml b/.github/workflows/downstream_tests.yml
@@ -19,7 +19,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}
@@ -66,7 +66,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}
@@ -127,7 +127,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}
@@ -164,7 +164,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}
@@ -243,7 +243,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}
@@ -283,7 +283,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}
@@ -323,7 +323,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}

diff --git a/.github/workflows/downstream_tests_slow.yml b/.github/workflows/downstream_tests_slow.yml
@@ -21,7 +21,7 @@ jobs:
           with:
             python-version: ${{ matrix.python-version }}
         - name: Install uv
-          uses: astral-sh/setup-uv@v4
+          uses: astral-sh/setup-uv@v5
           with:
             enable-cache: "true"
             cache-suffix: ${{ matrix.python-version }}

diff --git a/.github/workflows/extremes.yml b/.github/workflows/extremes.yml
@@ -19,7 +19,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}
@@ -41,7 +41,7 @@ jobs:
           echo "$DEPS" | grep 'scipy==1.5.0'
           echo "$DEPS" | grep 'scikit-learn==1.1.0'
       - name: Run pytest
-        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=50 --runslow
+        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=50 --runslow --constructors=pandas,pyarrow,polars[eager],polars[lazy]
 
   pretty_old_versions:
     strategy:
@@ -55,12 +55,12 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}
           cache-dependency-glob: "pyproject.toml"
-      - name: install-minimum-versions
+      - name: install-pretty-old-versions
         run: uv pip install pipdeptree tox virtualenv setuptools pandas==1.1.5 polars==0.20.3 numpy==1.17.5 pyarrow==11.0.0 "pyarrow-stubs<17" pyspark==3.3.0 scipy==1.5.0 scikit-learn==1.1.0 tzdata --system
       - name: install-reqs
         run: uv pip install -e ".[dev]" --system
@@ -79,7 +79,7 @@ jobs:
           echo "$DEPS" | grep 'scipy==1.5.0'
           echo "$DEPS" | grep 'scikit-learn==1.1.0'
       - name: Run pytest
-        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=50 --runslow
+        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=50 --runslow --constructors=pandas,pyarrow,polars[eager],polars[lazy]
 
   not_so_old_versions:
     strategy:
@@ -93,7 +93,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}
@@ -116,7 +116,7 @@ jobs:
           echo "$DEPS" | grep 'scikit-learn==1.3.0'
           echo "$DEPS" | grep 'dask==2024.7'
       - name: Run pytest
-        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=50 --runslow
+        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=50 --runslow --constructors=pandas,pyarrow,polars[eager],polars[lazy],dask
 
   nightlies:
     strategy:
@@ -131,7 +131,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}
@@ -179,4 +179,6 @@ jobs:
           echo "$DEPS" | grep 'numpy'
           echo "$DEPS" | grep 'dask'
       - name: Run pytest
-        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=50 --runslow
+        run: |
+          pytest tests --cov=narwhals --cov=tests --cov-fail-under=50 --runslow \
+          --constructors=pandas,pandas[nullable],pandas[pyarrow],pyarrow,polars[eager],polars[lazy],dask
diff --git a/.github/workflows/pytest.yml b/.github/workflows/pytest.yml
@@ -18,18 +18,18 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}
           cache-dependency-glob: "pyproject.toml"
       - name: install-reqs
         # Python3.8 is technically at end-of-life, so we don't test everything
-        run: uv pip install -e ".[dev]" --system
+        run: uv pip install -e ".[dev, core]" --system
       - name: show-deps
         run: uv pip freeze
       - name: Run pytest
-        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=85
+        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=85 --constructors=pandas,pyarrow,polars[eager],polars[lazy]
 
   pytest-windows:
     strategy:
@@ -43,17 +43,18 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}
           cache-dependency-glob: "pyproject.toml"
       - name: install-reqs
-        run: uv pip install -e ".[dev, extra]" --system
+        run: uv pip install -e ".[dev, core, extra, dask, modin]" --system
       - name: show-deps
         run: uv pip freeze
       - name: Run pytest
-        run: pytest tests --cov=narwhals --cov=tests --runslow --cov-fail-under=95
+        run: |
+          pytest tests --cov=narwhals --cov=tests --runslow --cov-fail-under=95 --all-cpu-constructors
 
   pytest-full-coverage:
     strategy:
@@ -67,22 +68,26 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}
           cache-dependency-glob: "pyproject.toml"
       - name: install-reqs
-        run: uv pip install -e ".[dev, extra]" --system
+        run: uv pip install -e ".[dev, core, extra, modin, dask]" --system
+      - name: install pyspark
+        run: uv pip install -e ".[pyspark]" --system
+        # PySpark is not yet available on Python3.12+
+        if: matrix.python-version == '3.9' || matrix.python-version == '3.11'
       - name: install ibis
-        run: uv pip install ibis-framework>=6.0.0 rich packaging pyarrow_hotfix --system
+        run: uv pip install -e ".[ibis]" --system
         # Ibis puts upper bounds on dependencies, and requires Python3.10+,
         # which messes with other dependencies on lower Python versions
         if: matrix.python-version == '3.11'
       - name: show-deps
         run: uv pip freeze
       - name: Run pytest
-        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=100 --runslow
+        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=100 --runslow --all-cpu-constructors
       - name: Run doctests
         # reprs differ between versions, so we only run doctests on the latest Python
         if: matrix.python-version == '3.13'

diff --git a/.github/workflows/random_ci_pytest.yml b/.github/workflows/random_ci_pytest.yml
@@ -17,22 +17,20 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: "true"
           cache-suffix: ${{ matrix.python-version }}
           cache-dependency-glob: "pyproject.toml"
-      - name: install package
-        run: uv pip install -e . --system
       - name: generate-random-versions
         run: python utils/generate_random_versions.py
-      - name: install-reqs
-        run: uv pip install -e ".[dev]" --system
-      - name: uninstall scipy/sklearn
-        run: uv pip uninstall scipy scikit-learn --system
       - name: install-random-verions
         run: uv pip install -r random-requirements.txt --system
+      - name: install-narwhals
+        run: uv pip install -e ".[dev]" --system
       - name: show versions
         run: uv pip freeze
       - name: Run pytest
-        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=80
+        run: |
+            pytest tests --cov=narwhals --cov=tests --cov-fail-under=80 \
+            --constructors=pandas,pyarrow,polars[eager],polars[lazy]
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -96,8 +96,9 @@ Here's how you can set up your local development environment to contribute.
       uv venv -p 3.12 --seed
       ```
    4. Activate it. On Linux, this is `. .venv/bin/activate`, on Windows `.\.venv\Scripts\activate`.
-2. Install Narwhals: `uv pip install -e ".[dev, docs]"`. If you also want to test Dask , PySpark, and
-   Modin, you can install them too with `uv pip install -e ".[dev, docs, extra]"`.
+2. Install Narwhals: `uv pip install -e ".[dev, core, docs]"`. This will include fast-ish core libraries.
+   If you also want to test other libraries like Dask , PySpark, and Modin, you can install them too with
+   `uv pip install -e ".[dev, core, docs, dask, pyspark, modin]"`.
 3. Install a fork of griffe:
    ```
    uv pip install git+https://github.com/MarcoGorelli/griffe.git@no-overloads
@@ -131,6 +132,12 @@ If you add code that should be tested, please add tests.
 - To run tests on the doctests, use `pytest narwhals --doctest-modules`
 - To run unit tests and doctests at the same time, run `pytest tests narwhals --cov=narwhals --doctest-modules`
 - To run tests multiprocessed, you may also want to use [pytest-xdist](https://github.com/pytest-dev/pytest-xdist) (optional)
+- To choose which backends to run tests with you, you can use the `--constructors` flag:
+  - To only run tests for pandas, Polars, and PyArrow, use `pytest --constructors=pandas,pyarrow,polars`
+  - To run tests for all CPU constructors, use `pytest --all-cpu-constructors`
+  - By default, tests run for pandas, pandas (PyArrow dtypes), PyArrow, and Polars.
+  - To run tests using `cudf.pandas`, run `NARWHALS_DEFAULT_CONSTRUCTORS=pandas python -m cudf.pandas -m pytest`
+  - To run tests using `polars[gpu]`, run `NARWHALS_POLARS_GPU=1 pytest --constructors=polars[lazy]`
 
 If you want to have less surprises when opening a PR, you can take advantage of [nox](https://nox.thea.codes/en/stable/index.html) to run the entire CI/CD test suite locally in your operating system.
 

diff --git a/docs/installation.md b/docs/installation.md
@@ -91,5 +91,5 @@ Let's learn about what you just did, and what Narwhals can do for you!
 
 !!! info
 
-    These examples are using pandas, Polars and PyArrow, however Narwhals supports
-    other dataframe libraries (See [supported libraries](extending.md)).
+    These examples are using pandas, Polars, and PyArrow, however Narwhals
+    supports other dataframe libraries (See [supported libraries](extending.md)).
diff --git a/narwhals/_arrow/dataframe.py b/narwhals/_arrow/dataframe.py
@@ -655,7 +655,7 @@ def unique(
         subset: list[str] | None,
         *,
         keep: Literal["any", "first", "last", "none"],
-        maintain_order: bool,
+        maintain_order: bool = False,
     ) -> Self:
         # The param `maintain_order` is only here for compatibility with the Polars API
         # and has no effect on the output.

diff --git a/narwhals/_dask/dataframe.py b/narwhals/_dask/dataframe.py
@@ -200,11 +200,8 @@ def unique(
         self: Self,
         subset: list[str] | None,
         *,
-        keep: Literal["any", "first", "last", "none"] = "any",
-        maintain_order: bool = False,
+        keep: Literal["any", "none"] = "any",
     ) -> Self:
-        # The param `maintain_order` is only here for compatibility with the Polars API
-        # and has no effect on the output.
         native_frame = self._native_frame
         if keep == "none":
             subset = subset or self.columns