Содержание
  1. Задача читателя и границы метода
  2. Основные понятия и параметры
  3. Полный учебный пример
  4. Проверка результата на заданном входе
  5. Как найти причину несовпадения двух результатов
  6. Сравнение с ближайшим подходом
  7. Ограничения и следующий шаг
  8. Частые вопросы
Обзоры

Обзор Narwhals: один код для разных датафреймов

17 ноября 2026 · 17 минут чтения

Обзор 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»

Этой таблицы достаточно, чтобы читать примеры в документации и писать свои. Переходим к полному учебному примеру.

Полный учебный пример

Пример ниже — учебный. Внешний сервис не запускался, модель не обучалась, скорость и улучшение качества не измерялись. Все входные данные и эталоны даны в тексте; реальные параметры библиотеки сверяются с названной документацией.

Вход — таблица из трёх строк:

КОД2 строки
city   = ["A", "B", "A"]
amount = [10, 20, 30]

Преобразование: отфильтровать строки с amount > 10, затем выбрать city и удвоенный amount под именем doubled. Эталон результата в исходном порядке строк: (B, 40), (A, 60).

Функция принимает нативный датафрейм, оборачивает его через nw.from_native, выполняет выражения nw.col, возвращает результат через .to_native().

PYTHON13 строк
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.

Тот же код через декоратор выглядит короче: обёртка и разворачивание уходят в декоратор, остаётся логика.

PYTHON12 строк
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» прямо относит оптимизацию запросов за рамки проекта, поэтому замеры скорости здесь не входят в задачу проверки.

Соберём проверку в один список шагов.

PYTHON29 строк
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.

Следующий шаг для читателя — небольшой пилот на своём коде.

  1. Выберите одну функцию обработки таблицы, которая сейчас написана под pandas.
  2. Перепишите её тело через nw.from_native, выражения nw.col и to_native.
  3. Прогоните на учебном входе из этой статьи и сверьте колонки и значения с эталоном.
  4. Подайте тот же вход в Polars и сравните колонки и значения.
  5. Проверьте пустой фильтр: колонки сохраняются, строк ноль.
  6. Если функция стартует с ленивого датафрейма, добавьте явную сортировку перед проверкой порядка.
  7. Сверьте использованные операции со списком поддерживаемых в документации.

Если все семь шагов проходят, функцию можно переносить в общий модуль. Если на каком-то шаге операция не поддерживается, оставьте её в ветке конкретного движка, а переносимую часть вынесите в слой 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 остаются движками, которые выполняют вычисления.

Читайте также

3 материала