merge main

.github/workflows/extremes.yml

@@ -20,7 +20,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Install uv (Unix)
         run: curl -LsSf https://astral.sh/uv/install.sh | sh
-      - name: install-minimu-versions
+      - name: install-minimum-versions
         run: uv pip install tox virtualenv setuptools pandas==0.25.3 polars==0.20.3 numpy==1.17.5 pyarrow==11.0.0 scipy==1.5.0 scikit-learn==1.1.0 tzdata --system
       - name: install-reqs
         run: uv pip install -r requirements-dev.txt --system
@@ -43,7 +43,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Install uv (Unix)
         run: curl -LsSf https://astral.sh/uv/install.sh | sh
-      - name: install-minimu-versions
+      - name: install-minimum-versions
         run: uv pip install tox virtualenv setuptools pandas==1.1.5 polars==0.20.3 numpy==1.17.5 pyarrow==11.0.0 scipy==1.5.0 scikit-learn==1.1.0 tzdata --system
       - name: install-reqs
         run: uv pip install -r requirements-dev.txt --system
@@ -54,6 +54,31 @@ jobs:
       - name: Run doctests
         run: pytest narwhals --doctest-modules
 
+  not_so_old_versions:
+    strategy:
+      matrix:
+        python-version: ["3.9"]
+        os: [ubuntu-latest]
+
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install uv (Unix)
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+      - name: install-minimum-versions
+        run: uv pip install tox virtualenv setuptools pandas==2.0.3 polars==0.20.8 numpy==1.24.4 pyarrow==14.0.0 scipy==1.8.0 scikit-learn==1.3.0 dask[dataframe]==2024.7 tzdata --system
+      - name: install-reqs
+        run: uv pip install -r requirements-dev.txt --system
+      - name: show-deps
+        run: uv pip freeze
+      - name: Run pytest
+        run: pytest tests --cov=narwhals --cov=tests --cov-fail-under=50 --runslow
+      - name: Run doctests
+        run: pytest narwhals --doctest-modules
+
   pandas-nightly-and-dask:
     strategy:
       matrix:

.github/workflows/publish_to_pypi.yml

@@ -30,7 +30,7 @@ jobs:
   publish-to-pypi:
     name: >-
       Publish Python 🐍 distribution 📦 to PyPI
-    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    if: startsWith(github.ref, 'refs/tags/v')  # only publish to PyPI on tag pushes
     needs:
     - build
     runs-on: ubuntu-latest

.pre-commit-config.yaml

@@ -31,8 +31,8 @@ repos:
       additional_dependencies: [polars]
     - id: imports-are-banned
       name: import are banned (use `get_pandas` instead of `import pandas`)
-      entry: (?<!>>> )import (pandas|polars|modin|cudf|pyarrow|dask)
-      language: pygrep
+      entry: python utils/import_check.py
+      language: python
       files: ^narwhals/
       exclude: ^narwhals/dependencies\.py
 - repo: https://github.com/kynan/nbstripout

CONTRIBUTING.md

@@ -67,6 +67,26 @@ Please adhere to the following guidelines:
 If Narwhals looks like underwater unicorn magic to you, then please read
 [how it works](https://narwhals-dev.github.io/narwhals/how-it-works/).
 
+## Imports
+
+In Narwhals, we are very particular about imports. When it comes to importing
+heavy third-party libraries (pandas, NumPy, Polars, etc...) please follow these rules:
+
+- Never import anything to do `isinstance` checks. Instead, just use the functions
+  in `narwhals.dependencies` (such as `is_pandas_dataframe`);
+- If you need to import anything, do it in a place where you know that the import
+  is definitely available. For example, NumPy is a required dependency of PyArrow,
+  so it's OK to import NumPy to implement a PyArrow function - however, NumPy
+  should never be imported to implement a Polars function. The only exception is
+  for when there's simply no way around it by definition - for example, `Series.to_numpy`
+  always requires NumPy to be installed.
+- Don't place a third-party import at the top of a file. Instead, place it in the
+  function where it's used, so that we minimise the chances of it being imported
+  unnecessarily.
+
+We're trying to be really lightweight and minimal-overhead, and
+unnecessary imports can slow things down.
+
 ## Happy contributing!
 
 Please remember to abide by the code of conduct, else you'll be conducted away from this project.

README.md

@@ -8,6 +8,7 @@
 </h1>
 
 [![PyPI version](https://badge.fury.io/py/narwhals.svg)](https://badge.fury.io/py/narwhals)
+[![Downloads](https://static.pepy.tech/badge/narwhals/month)](https://pepy.tech/project/narwhals)
 
 Extremely lightweight and extensible compatibility layer between dataframe libraries!
 
@@ -39,6 +40,7 @@ Get started!
 
 Join the party!
 
+- [Altair](https://github.com/vega/altair/)
 - [Hamilton](https://github.com/DAGWorks-Inc/hamilton/tree/main/examples/narwhals)
 - [scikit-lego](https://github.com/koaning/scikit-lego)
 - [scikit-playtime](https://github.com/koaning/scikit-playtime)

docs/api-reference/dataframe.md

@@ -4,6 +4,7 @@
     handler: python
     options:
       members:
+        - __arrow_c_stream__
         - __getitem__
         - clone
         - collect_schema
@@ -31,6 +32,7 @@
         - shape
         - sort
         - tail
+        - to_arrow
         - to_dict
         - to_numpy
         - to_pandas

docs/api-reference/expr_str.md

@@ -8,6 +8,8 @@
         - ends_with
         - head
         - slice
+        - replace
+        - replace_all
         - starts_with
         - strip_chars
         - tail

docs/api-reference/narwhals.md

@@ -17,14 +17,15 @@ Here are the top-level functions available in Narwhals.
         - get_native_namespace
         - is_ordered_categorical
         - len
-        - maybe_align_index
-        - maybe_set_index
-        - maybe_convert_dtypes
         - lit
         - max
+        - maybe_align_index
+        - maybe_convert_dtypes
+        - maybe_set_index
         - mean
         - min
         - narwhalify
+        - new_series
         - sum
         - sum_horizontal
         - show_versions

docs/api-reference/series.md

@@ -4,6 +4,8 @@
     handler: python
     options:
       members:
+        - __arrow_c_stream__
+        - __getitem__
         - abs
         - alias
         - all
@@ -47,6 +49,7 @@
         - std
         - sum
         - tail
+        - to_arrow
         - to_dummies
         - to_frame
         - to_list

docs/api-reference/series_str.md

@@ -7,6 +7,8 @@
         - contains
         - ends_with
         - head
+        - replace
+        - replace_all
         - slice
         - starts_with
         - strip_chars

docs/extending.md

@@ -26,14 +26,16 @@ Make sure that, in addition to the public Narwhals API, you also define:
     from `Narwhals.DataFrame`
   - `DataFrame.__narwhals_namespace__`: return an object which implements public top-level
     functions from `narwhals` (e.g. `narwhals.col`, `narwhals.concat`, ...)
+  - `DataFrame.__native_namespace__`: return a native namespace object which must have a
+    `from_dict` method
   - `LazyFrame.__narwhals_lazyframe__`: return an object which implements public methods
     from `Narwhals.LazyFrame`
   - `LazyFrame.__narwhals_namespace__`: return an object which implements public top-level
     functions from `narwhals` (e.g. `narwhals.col`, `narwhals.concat`, ...)
+  - `LazyFrame.__native_namespace__`: return a native namespace object which must have a
+    `from_dict` method
   - `Series.__narwhals_series__`: return an object which implements public methods
     from `Narwhals.Series`
-  - `Series.__narwhals_namespace__`: return an object which implements public top-level
-    functions from `narwhals` (e.g. `narwhals.col`, `narwhals.concat`, ...)
 
   If your library doesn't distinguish between lazy and eager, then it's OK for your dataframe
   object to implement both `__narwhals_dataframe__` and `__narwhals_lazyframe__`. In fact,

docs/how_it_works.md

@@ -88,7 +88,7 @@ The `_call` method gives us that function! Let's see it in action.
 
 Note: the following examples use `PandasLikeDataFrame` and `PandasLikeSeries`. These are backed
 by actual `pandas.DataFrame`s and `pandas.Series` respectively and are Narwhals-compliant. We can access the 
-underlying pandas objects via `PandasLikeDataFrame._native_dataframe` and `PandasLikeSeries._native_series`.
+underlying pandas objects via `PandasLikeDataFrame._native_frame` and `PandasLikeSeries._native_series`.
 
 ```python exec="1" result="python" session="pandas_impl" source="above"
 import narwhals as nw
@@ -222,10 +222,10 @@ df_compliant = df._compliant_frame
 result = df_compliant.select(expr)
 ```
 
-We can then view the underlying pandas Dataframe which was produced by calling `._native_dataframe`:
+We can then view the underlying pandas Dataframe which was produced by calling `._native_frame`:
 
 ```python exec="1" result="python" session="pandas_api_mapping" source="above"
-print(result._native_dataframe)
+print(result._native_frame)
 ```
 which is the same as we'd have obtained by just using the Narwhals API directly:
 

docs/installation.md

@@ -11,6 +11,6 @@ Then, if you start the Python REPL and see the following:
 ```python
 >>> import narwhals
 >>> narwhals.__version__
-'1.3.0'
+'1.4.0'
 ```
 then installation worked correctly!

narwhals/__init__.py

@@ -36,6 +36,7 @@
 from narwhals.functions import concat
 from narwhals.functions import from_dict
 from narwhals.functions import get_level
+from narwhals.functions import new_series
 from narwhals.functions import show_versions
 from narwhals.schema import Schema
 from narwhals.series import Series
@@ -48,13 +49,14 @@
 from narwhals.utils import maybe_convert_dtypes
 from narwhals.utils import maybe_set_index
 
-__version__ = "1.3.0"
+__version__ = "1.4.0"
 
 __all__ = [
     "selectors",
     "concat",
     "from_dict",
     "get_level",
+    "new_series",
     "to_native",
     "from_native",
     "is_ordered_categorical",