Обзор Narwhals: один код для разных датафреймов показывает библиотеку, которая даёт общий слой выражений над pandas, Polars и другими движками. Вы пишете логику через совместимый API, а на входе и выходе остаётесь в родной библиотеке пользователя. Ниже — понятия, полный учебный пример, проверка результата и границы метода.
Задача читателя и границы метода
Читатель приходит с типовой ситуацией: код обработки таблиц написан под pandas, а часть команды или заказчик работает на Polars. Переписывать логику под каждый движок дорого, поддерживать две ветки кода — источник расхождений. Narwhals решает узкую задачу: даёт единый набор выражений, который транслируется в вызовы нижележащей библиотеки. Документация проекта в разделе «How it works» описывает это прямо: обёртка датафрейма переадресует вызов в нижележащую библиотеку. То есть Narwhals работает как адаптер поверх движка, который у вас уже установлен.
Границы метода важны сразу, потому что от них зависит, где библиотека уместна. Документация Narwhals в том же разделе указывает, что оптимизация запросов в целом выходит за рамки проекта. Проект не обещает автоматического ускорения: оптимизация запросов в общем случае остаётся за его рамками. В том же документе допускаются отдельные простые переписывания выражений, поэтому отсутствие любых преобразований плана утверждать нельзя. Он даёт переносимость кода между движками. Если ваша цель — ускорить конкретный расчёт, вопрос решается выбором движка и его собственными средствами, а слой Narwhals остаётся нейтральным посредником.
Второй ориентир — поддерживаемое подмножество. Документация в разделе «DataFrame» формулирует подход так: логику выражают через подмножество API Polars, которое поддерживает Narwhals. Полного покрытия всех возможностей каждого движка здесь нет по построению. Практический вывод: перед переносом большого модуля проверьте, что нужные операции входят в поддерживаемый набор. Мелкие проверки на учебной таблице дешевле, чем переписывание половины пайплайна.
Третий ориентир — режимы выполнения. Документация различает eager и lazy. Для LazyFrame порядок строк не определён, о чём сказано в разделе «How it works». Для eager-объектов порядок строк определён и может учитываться в выражениях. Это влияет на то, как вы пишете проверки: сравнение «строка за строкой» корректно для eager-таблицы и требует явной сортировки для ленивого плана.
Что метод сознательно не делает:
- не заменяет pandas или Polars целиком — вы продолжаете работать с их объектами на границах;
- не ускоряет вычисления автоматически — оптимизация запросов вне области проекта;
- не гарантирует одинакового поведения всех операций на всех движках — поддержка зависит от backend и режима;
- не переносит индекс pandas в бизнес-логику — индекс остаётся деталью конкретной библиотеки.
Эти четыре пункта задают рамку для всего дальнейшего разбора. Дальше — понятия, на которых держится API.
Основные понятия и параметры
Три понятия покрывают почти весь повседневный код на Narwhals: обёртка, выражение и контекст.
Обёртка. Документация в разделе «DataFrame» описывает вход так: инициализируйте Narwhals DataFrame или LazyFrame, передав свой датафрейм в nw.from_native. В справочнике верхнеуровневых функций указано, что from_native преобразует нативный объект в Narwhals DataFrame, LazyFrame или Series. Обратная операция — nw.to_native: справочник определяет её как преобразование объекта Narwhals в нативный, а тип результата описывает как класс, с которого начал пользователь. Это ключевая гарантия для библиотечного кода: функция принимает чужой датафрейм и возвращает объект того же типа.
Выражение. Документация в разделе «How it works» определяет выражение как функцию из DataFrame в последовательность Series. Там же сказано, что само по себе выражение значения не производит: значение появляется, когда выражение передано в контекст датафрейма. Практический смысл — выражение описывает намерение, а вычисление запускает контекст. Ещё одно ограничение из того же раздела: колонки, участвующие в одном выражении, должны быть выведены из одного датафрейма. Это защищает от неявного смешивания данных из разных источников.
Контекст. Документация перечисляет основные контексты. DataFrame.select создаёт датафрейм только с результатом данного выражения. DataFrame.with_columns создаёт датафрейм, похожий на текущий, и добавляет результат данного выражения. filter оставляет строки по условию. Эти три контекста покрывают большинство преобразований: выбрать, добавить, отфильтровать.
Параметры, которые стоит держать в голове:
eager_onlyуfrom_native— справочник описывает его как «разрешать только eager-объекты». Документация в разделе «DataFrame» поясняет причину на примере: параметр нужен там, где у LazyFrame нет.shape.@nw.narwhalify— декоратор, который объединяет шаги обёртки и разворачивания. Документация в разделе «DataFrame» говорит, что первый и третий шаги настолько часты, что для них предусмотрен этот декоратор, и тогда явно пишется только второй шаг — сама логика.- Ленивость. Документация в разделе «DataFrame» утверждает: все вычисления остаются ленивыми, если стартовать с ленивого датафрейма, и Narwhals никогда не запускает вычисление сам, без вашего запроса.
Сведём понятия и их роли в таблицу.
| Понятие | Что делает | Где описано |
|---|---|---|
nw.from_native |
Преобразует нативный объект в Narwhals DataFrame, LazyFrame или Series | Справочник верхнеуровневых функций |
nw.to_native |
Преобразует объект Narwhals в нативный; тип — как у исходного класса | Справочник верхнеуровневых функций |
@nw.narwhalify |
Объединяет обёртку и разворачивание, оставляя явной только логику | Раздел «DataFrame» |
| Выражение | Функция из DataFrame в последовательность Series; значение даёт контекст | Раздел «How it works» |
select |
Датафрейм только с результатом выражения | Раздел «How it works» |
with_columns |
Датафрейм как текущий плюс результат выражения | Раздел «How it works» |
filter |
Строки по условию | Раздел «How it works» |
eager_only |
Ограничение только eager-объектами | Справочник; раздел «DataFrame» |
Этой таблицы достаточно, чтобы читать примеры в документации и писать свои. Переходим к полному учебному примеру.
Полный учебный пример
Пример ниже — учебный. Внешний сервис не запускался, модель не обучалась, скорость и улучшение качества не измерялись. Все входные данные и эталоны даны в тексте; реальные параметры библиотеки сверяются с названной документацией.
Вход — таблица из трёх строк:
city = ["A", "B", "A"]
amount = [10, 20, 30]
Преобразование: отфильтровать строки с amount > 10, затем выбрать city и удвоенный amount под именем doubled. Эталон результата в исходном порядке строк: (B, 40), (A, 60).
Функция принимает нативный датафрейм, оборачивает его через nw.from_native, выполняет выражения nw.col, возвращает результат через .to_native().
import narwhals as nw
def transform(frame):
df = nw.from_native(frame)
result = (
df.filter(nw.col("amount") > 10)
.select(
nw.col("city"),
(nw.col("amount") * 2).alias("doubled"),
)
)
return result.to_native()
Разберём шаги по порядку.
Шаг 1. Обёртка. nw.from_native(frame) принимает pandas DataFrame, Polars DataFrame или другой поддерживаемый объект и возвращает объект Narwhals. Документация в разделе «DataFrame» описывает именно такой вход: передать свой датафрейм в nw.from_native.
Шаг 2. Фильтр. df.filter(nw.col("amount") > 10) оставляет строки, где значение в колонке amount больше десяти. Из трёх строк условие проходят две: (B, 20) и (A, 30). Строка (A, 10) отсеивается.
Шаг 3. Выбор и вычисление. .select(nw.col("city"), (nw.col("amount") * 2).alias("doubled")) формирует датафрейм только с результатом выражения. Колонка city берётся как есть, колонка amount умножается на два и получает имя doubled. Для (B, 20) получается (B, 40), для (A, 30) — (A, 60).
Шаг 4. Возврат. .to_native() преобразует объект Narwhals обратно в нативный. Справочник описывает результат как объект класса, с которого начал пользователь. Если на входе был pandas DataFrame, на выходе тоже pandas DataFrame.
Тот же код через декоратор выглядит короче: обёртка и разворачивание уходят в декоратор, остаётся логика.
import narwhals as nw
@nw.narwhalify
def transform(df):
return (
df.filter(nw.col("amount") > 10)
.select(
nw.col("city"),
(nw.col("amount") * 2).alias("doubled"),
)
)
Документация в разделе «DataFrame» описывает декоратор так: первый и третий шаги настолько часты, что для них предусмотрен @nw.narwhalify, и тогда явно пишется только второй шаг. В этом варианте функция принимает нативный датафрейм и возвращает нативный датафрейм, а тело работает с объектом Narwhals.
Сравнение двух вариантов:
| Критерий | Явные from_native / to_native |
@nw.narwhalify |
|---|---|---|
| Читаемость тела | Обёртка и разворот видны | Видна только логика |
| Контроль над типом возврата | Явный вызов .to_native() |
Декоратор разворачивает сам |
| Когда удобно | Нужен промежуточный объект Narwhals | Функция целиком про преобразование |
| Где описано | Раздел «DataFrame», справочник | Раздел «DataFrame» |
Оба варианта дают один и тот же результат на одном входе. Выбор — вопрос читаемости конкретного модуля.
Проверка результата на заданном входе
Проверка строится на сравнении выхода с эталоном. Эталон для учебного входа: строки (B, 40) и (A, 60) в исходном порядке.
Первый уровень проверки — колонки и значения. После filter и select ожидаются две колонки: city и doubled. Значения: B с 40, A с 60. Проверять стоит и имена, и порядок колонок, потому что select формирует датафрейм из перечисленных выражений.
Второй уровень — порядок строк. Для eager-таблицы порядок строк сохраняется, и эталон читается как последовательность. Документация в разделе «How it works» указывает: при работе с LazyFrame порядок строк не определён. Значит, для ленивого плана сравнение по позициям требует явной сортировки перед проверкой. Без сортировки совпадение множества строк ожидаемо, совпадение порядка — нет.
Третий уровень — тип возврата. Функция должна вернуть объект того же класса, что пришёл на вход. Справочник описывает to_native как преобразование в нативный объект с типом исходного класса. Проверка: подать pandas DataFrame и убедиться, что результат — pandas DataFrame; подать Polars DataFrame и убедиться, что результат — Polars DataFrame.
Четвёртый уровень — пустой результат. Если фильтр не пропускает ни одной строки, select сохраняет ожидаемые столбцы с нулём строк. Это важно для кода, который дальше обращается к колонкам по имени: имена остаются на месте, меняется только число строк.
Пятый уровень — сравнение движков на одном входе. Подайте один и тот же учебный вход в pandas и в Polars, примените одну функцию, сравните колонки и значения. Скорость при этом не измеряется: сравнение проверяет только переносимость кода. Документация Narwhals в разделе «How it works» прямо относит оптимизацию запросов за рамки проекта, поэтому замеры скорости здесь не входят в задачу проверки.
Соберём проверку в один список шагов.
import pandas as pd
import polars as pl
import narwhals as nw
def transform(frame):
df = nw.from_native(frame)
result = df.filter(nw.col("amount") > 10).select(
nw.col("city"), (nw.col("amount") * 2).alias("doubled")
)
return result.to_native()
pdf = pd.DataFrame({"city": ["A", "B", "A"], "amount": [10, 20, 30]})
pldf = pl.DataFrame({"city": ["A", "B", "A"], "amount": [10, 20, 30]})
out_pd = transform(pdf)
out_pl = transform(pldf)
assert type(out_pd) is pd.DataFrame
assert type(out_pl) is pl.DataFrame
assert list(out_pd.columns) == ["city", "doubled"]
assert list(out_pl.columns) == ["city", "doubled"]
assert out_pd["city"].tolist() == ["B", "A"]
assert out_pd["doubled"].tolist() == [40, 60]
assert out_pl["city"].to_list() == ["B", "A"]
assert out_pl["doubled"].to_list() == [40, 60]
Этот блок — учебная проверка на заданном входе. Он не измеряет скорость и не подтверждает лимиты продукта. Его задача — убедиться, что одна функция даёт одинаковые колонки и значения на двух движках и возвращает исходный тип.
Отдельно проверьте пустой фильтр: замените условие на nw.col("amount") > 100 и убедитесь, что колонки city и doubled остались, а строк стало ноль. Это ловит ошибки в коде, который дальше ожидает конкретные имена столбцов.
Как найти причину несовпадения двух результатов
Если проверка типа не прошла, сначала проверьте границу возврата. После вычисления должен возвращаться результат to_native, без дополнительного создания pandas DataFrame вокруг него. Принудительное приведение обоих ответов к одному классу скрыло бы нарушение контракта. Исходный тип полезно проверить до чтения значений: одинаково напечатанная таблица ещё не означает одинаковый объект. При этом проверка класса относится к нашему учебному преобразованию датафрейма; она не обещает, что любая операция библиотеки всегда возвращает датафрейм.
Если отличаются значения, двигайтесь от первой операции к последней. В условии примера стоит строгое сравнение amount > 10. Поэтому строка A с amount=10 должна исчезнуть. Замена знака на >= сохранит лишнюю строку, хотя остальной код останется тем же. Это различающая проверка конкретной границы: она обнаруживает смену правила фильтра, которую можно пропустить, сравнивая только общую сумму doubled. После фильтра вручную сопоставьте каждую оставшуюся сумму с исходным amount. Сортировка не исправляет лишние строки и неверные значения.
Если расходится только порядок, выясните режим выполнения до изменения эталона. Наш скрипт принимает готовые eager DataFrame и проверяет последовательность B, затем A после filter и select. Для другого сценария порядок можно включить в явный контракт сортировки по выбранным колонкам. Сортировка должна быть одинаковой у обеих сторон сравнения. Для LazyFrame отдельно требуется выполнить план средствами выбранного движка: разворачивание через to_native само по себе не следует считать получением готовых строк. Проверку значений запускают после такого выполнения.
Пустой результат проверяйте отдельно от непустого. Ожидается отсутствие строк при сохранённых именах city и doubled. Если следующий шаг требует эти имена, сам факт пустоты не является основанием возвращать произвольный пустой список. В отчёте о проверке разделите результат фильтрации и нарушение схемы. Первый может быть правильным ответом на вход, второе ломает контракт потребителя. Не подставляйте выдуманные значения вместо отсутствующих строк, чтобы удовлетворить последующий расчёт.
Наконец, проверьте, нет ли скрытого бизнес-ключа в индексе pandas. В нашем входе город хранится отдельной колонкой, поэтому преобразование явно читает city. Если в вашем коде важная метка существует только в индексе, сначала определите её роль и представьте нужные данные явной колонкой на входной границе. При сравнении не заменяйте бизнес-идентификатор случайным номером строки. Так проверяется смысл результата, который один контроль количества строк обнаружить не способен.
Для воспроизведения расхождения сохраните исходную таблицу, правило преобразования, ожидаемые колонки и значения, тип входа и названия установленных пакетов. Зафиксируйте их версии из собственного окружения. Если не импортируется pandas или Polars, сначала устраните отсутствие соответствующей библиотеки; ошибка импорта ещё ничего не говорит о переносимости выражения. Только после одинаковых исходных условий локализуйте неподдерживаемую операцию. Сам приведённый пример является ручной спецификацией проверки, успешный запуск на двух backend здесь не заявляется.
Сравнение с ближайшим подходом
Ближайший подход — писать код отдельно под каждый движок. Сравним по явным критериям, без замеров скорости.
| Критерий | Код под каждый движок | Слой Narwhals |
|---|---|---|
| Число реализаций логики | По одной на движок | Одна |
| Риск расхождения поведения | Растёт с числом движков | Ниже: логика в одном месте |
| Тип на входе и выходе | Родной для движка | Родной для движка, через to_native |
| Оптимизация запросов | Средствами движка | Вне области проекта |
| Поддержка операций | Полная для движка | Подмножество API Polars |
| Порядок строк в lazy | Зависит от движка | Не определён для LazyFrame |
| Индекс pandas | Доступен в логике | Остаётся деталью библиотеки |
Первый критерий — число реализаций. Две ветки кода означают две точки правки на каждое изменение правила. Одна функция на Narwhals означает одну точку правки. Это главный аргумент слоя.
Второй критерий — расхождение поведения. Когда логика продублирована, ветки расходятся со временем: в одной поправили округление, в другой забыли. Единая функция сокращает дублирование правила; совместимость и одинаковый смысл результата всё равно требуют проверки на выбранных движках.
Третий критерий — типы на границах. Здесь подходы совпадают по результату: пользователь получает объект своей библиотеки. Разница в том, что Narwhals делает это через явный to_native, а прямая реализация — по построению.
Четвёртый критерий — оптимизация. Прямой код на Polars может использовать ленивый план и оптимизации движка напрямую. Narwhals сохраняет ленивость, если стартовать с ленивого датафрейма, и не запускает вычисление сам. Оптимизацию запросов проект относит за свои рамки, поэтому выигрыш по скорости здесь не заявляется ни для одного из подходов.
Пятый критерий — покрытие операций. Прямой код на конкретном движке имеет доступ ко всем его возможностям. Narwhals ограничен поддерживаемым подмножеством API Polars. Для типовых преобразований — фильтр, выбор, добавление колонок, группировка — подмножества хватает. Для редких операций конкретного движка проверьте поддержку заранее.
Шестой критерий — порядок строк. В eager-режиме порядок строк определён. Для Narwhals LazyFrame документация не задаёт физический порядок строк. Это контракт интерфейса Narwhals; свойства нативного ленивого плана проверяйте отдельно. Правило одно: если порядок важен, сортируйте явно.
Седьмой критерий — индекс pandas. Индекс — деталь pandas. В логику, которая должна работать на нескольких движках, его переносить не стоит: у других движков такого понятия нет, и код станет непереносимым.
Практический вывод из сравнения: слой Narwhals выигрывает там, где одна и та же логика нужна на нескольких движках и укладывается в поддерживаемое подмножество. Прямой код выигрывает там, где нужны редкие возможности одного движка или тонкая настройка его плана выполнения.
Ограничения и следующий шаг
Ограничения собраны из документации проекта и из устройства самого слоя.
Первое. Оптимизация запросов выходит за рамки проекта. Narwhals передаёт вызовы нижележащей библиотеке и может применять отдельные преобразования выражений; общего обещания оптимизировать запрос нет. Ускорение достигается средствами движка.
Второе. Поддерживается подмножество API Polars. Перед переносом модуля сверьте список операций с документацией.
Третье. Порядок строк в LazyFrame не определён. Проверки на ленивых планах требуют явной сортировки.
Четвёртое. Поддержка зависит от backend и режима. Одна и та же операция может вести себя по-разному на разных движках; проверяйте на тех, что есть у вас.
Пятое. Индекс pandas остаётся деталью библиотеки. Логика, рассчитанная на переносимость, на него не опирается.
Шестое. eager_only=True ограничивает вход eager-объектами. Это нужно там, где операция требует свойств, которых у LazyFrame нет, — например, .shape.
Следующий шаг для читателя — небольшой пилот на своём коде.
- Выберите одну функцию обработки таблицы, которая сейчас написана под pandas.
- Перепишите её тело через
nw.from_native, выраженияnw.colиto_native. - Прогоните на учебном входе из этой статьи и сверьте колонки и значения с эталоном.
- Подайте тот же вход в Polars и сравните колонки и значения.
- Проверьте пустой фильтр: колонки сохраняются, строк ноль.
- Если функция стартует с ленивого датафрейма, добавьте явную сортировку перед проверкой порядка.
- Сверьте использованные операции со списком поддерживаемых в документации.
Если все семь шагов проходят, функцию можно переносить в общий модуль. Если на каком-то шаге операция не поддерживается, оставьте её в ветке конкретного движка, а переносимую часть вынесите в слой Narwhals.
Частые вопросы
Что такое Narwhals в Python?
Narwhals — библиотека совместимости для работы с таблицами. Она даёт общий набор выражений над pandas, Polars и другими движками. Документация проекта описывает вход через nw.from_native, выход через nw.to_native и логику через подмножество API Polars. Оптимизация запросов отнесена за рамки проекта.
Как установить библиотеку Narwhals?
Установка выполняется обычным способом для Python-пакетов, после чего модуль импортируется как import narwhals as nw. Точную команду и актуальную версию сверяйте на странице проекта. В коде используются nw.from_native, nw.to_native, nw.col и декоратор @nw.narwhalify.
Чем Narwhals отличается от прямого кода на pandas или Polars?
Прямой код работает с возможностями одного движка. Narwhals даёт одну реализацию логики для нескольких движков и возвращает объект исходного типа. Поддержка ограничена подмножеством операций; оптимизация запросов в общем случае выходит за рамки проекта, при этом документация допускает отдельные простые переписывания выражений.
Почему порядок строк не определён в LazyFrame?
Документация Narwhals указывает, что при работе с LazyFrame порядок строк не определён. Ленивый план выполняется движком, и порядок зависит от его решения. Если порядок важен для результата, добавляйте явную сортировку перед проверкой или выводом.
Заменяет ли Narwhals pandas и Polars?
Нет. Narwhals работает поверх установленного движка и переадресует вызовы ему. На границах функции вы по-прежнему принимаете и возвращаете нативные объекты. pandas и Polars остаются движками, которые выполняют вычисления.
