Narwhals 2026: pandas وPolars بكود واحد

آخر تحديث: 4 يونيو 2026

مكتبة Narwhals هي طبقة توافق خفيفة (lightweight compatibility layer) تتيح لك كتابة دالة DataFrame واحدة تعمل دون تعديل فوق pandas وPolars وPyArrow وModin وcuDF. بعبارة أوضح: تكتب الكود مرة واحدة بأسلوب يُشبه Polars الكسول (lazy)، ثم تُمرّر إليه أي DataFrame من أي محرك، فيرجع لك نتيجة من النوع نفسه. أُصدرت Narwhals 1.0 في 2024، وبحلول 2026 صارت اعتمادًا قياسيًا في scikit-learn وPlotly وaltair لدعم تعدّد المحركات دون فروع شرطية (if-else) داخل الكود.

بصراحة، حين بدأتُ بصيانة مكتبة داخلية تقبل DataFrame كمدخل، كنتُ أكتب مسارَين: واحد لـ pandas وآخر لـ Polars. كان الكود مكررًا، والاختبارات مضاعفة. هذا بالضبط ما تُلغيه Narwhals.

Narwhals تُجرّد API على شكل مجموعة فرعية من Polars، وتترجمها داخليًا إلى استدعاءات pandas أو PyArrow أو غيرهما، دون نسخ بيانات.
تعتمد عليها مكتبات كبرى في 2026 لتوحيد دعم DataFrame: scikit-learn (set_output)، وPlotly Express، وaltair، وshiny for Python.
التكلفة الزمنية للتغليف (overhead) صفر تقريبًا، لأن Narwhals لا تنفّذ عمليات بنفسها، بل تستدعي الباك-إند الأصلي.
تدعم وضعَين: narwhalify للدوال البسيطة، وfrom_native/to_native للتحكم اليدوي.
تُكمّل (لا تستبدل) أدوات مثل DuckDB لتحليل البيانات الأكبر من الذاكرة وPolars في مقابل pandas.
أكبر قيد حالي: تغطي حوالي 85% من واجهة Polars المستقرّة، وتفتقر إلى بعض الدوال الإحصائية المتقدمة.

ما هي مكتبة Narwhals ولماذا ظهرت؟

مشكلة بسيطة دفعت إلى ولادة Narwhals. مؤلّفو المكتبات التي تستهلك DataFrame كمدخل، مثل Plotly وscikit-learn وaltair، كانوا يضطرون إلى كتابة فرعَين أو ثلاثة من نفس الدالة: واحد لـ pandas، وآخر لـ Polars، وربما ثالث لـ PyArrow. هذا تكرار يولّد أخطاءً صامتة عند انحراف السلوك بين المحركات.

Narwhals تحلّ المشكلة عبر طبقة شفافة: تعرّف فيها العملية بأسلوب تعبيري (expression-based) مستوحى من Polars، وتنوب عنك المكتبة في ترجمته إلى استدعاءات الباك-إند الأصلي. لا يوجد تحويل بيانات (df.to_pandas() مثلًا)، بل مجرّد توجيه استدعاء أسلوبي. هذا يعني أن استخدام Narwhals مع DataFrame من النوع pandas.DataFrame ينتج pandas.DataFrame آخر، ومع polars.DataFrame ينتج Polars، وهكذا.

الفكرة قريبة من DataFrame Interchange Protocol الذي اقترحه Consortium for Python Data API، لكن Narwhals توفر أعلى منه واجهة قابلة للكتابة (writable API)، لا مجرد بروتوكول قراءة.

تثبيت Narwhals والبدء السريع

التثبيت ببساطة عبر pip أو uv:

pip install narwhals
# أو
uv add narwhals

الإصدار المستقر في يونيو 2026 هو 1.41.x. المكتبة بلا اعتماديات إجبارية. لا تسحب pandas ولا Polars معها؛ فهي تكتشف الباك-إند المُمرَّر إليها وقت التشغيل.

أبسط مثال: دالة تعطي عدد الصفوف لكل قيمة فريدة في عمود معيّن.

import narwhals as nw

@nw.narwhalify
def value_counts(df, column: str):
    return (
        df.group_by(column)
          .agg(nw.len().alias("count"))
          .sort("count", descending=True)
    )

import pandas as pd
import polars as pl

pdf = pd.DataFrame({"city": ["Cairo", "Riyadh", "Cairo", "Dubai", "Riyadh", "Cairo"]})
pldf = pl.DataFrame({"city": ["Cairo", "Riyadh", "Cairo", "Dubai", "Riyadh", "Cairo"]})

print(type(value_counts(pdf, "city")))    # <class 'pandas.core.frame.DataFrame'>
print(type(value_counts(pldf, "city")))   # <class 'polars.dataframe.frame.DataFrame'>

لاحظ نقطتين: (1) لم نكتب أي تفريع if isinstance(df, pd.DataFrame)، و(2) النوع العائد يطابق النوع الداخل. هذا هو جوهر العقد الذي تقدّمه Narwhals.

واجهة Narwhals الأساسية: `from_native` و`narwhalify`

تُقدّم Narwhals أسلوبَين للتغليف.

1. الديكوريتر `@nw.narwhalify`

أنسب للدوال البسيطة. يلتقط DataFrame الأول في الوسائط، يغلّفه، ينفّذ الجسم، ثم يفك التغليف تلقائيًا قبل الإرجاع. هذا ما رأيناه في المثال السابق.

2. الزوج اليدوي `nw.from_native` و`nw.to_native`

أنسب عندما تحتاج تحكّمًا دقيقًا، أو تعمل مع عدة DataFrames في آنٍ واحد:

import narwhals as nw

def join_and_filter(df_a, df_b, key: str, min_value: float):
    a = nw.from_native(df_a)
    b = nw.from_native(df_b)
    out = (
        a.join(b, on=key, how="inner")
         .filter(nw.col("value") >= min_value)
         .select([key, "value", "label"])
    )
    return nw.to_native(out)

لاحظ nw.col("value"): هذه تعبير (expression) كسول مشابه لما في Polars. لا يُنفَّذ فورًا. أنت تجمع التعبيرات أولًا، ثم تطلق التنفيذ عبر .collect() في الوضع الكسول، أو يحدث ضمنيًا في الوضع الفوري (eager).

مثال عملي: دالة تنظيف بيانات تعمل على pandas وPolars معًا

لنبني دالة تنظيف نموذجية: حذف الصفوف المكررة على عمود مُعرِّف، توحيد سلسلة نصية، ملء القيم المفقودة في عمود رقمي بالوسيط (median)، وإضافة عمود حسابي.

import narwhals as nw

@nw.narwhalify
def clean_sales(df):
    return (
        df
        .unique(subset=["order_id"], keep="first")
        .with_columns(
            nw.col("country").str.to_lowercase().str.strip_chars(),
            nw.col("amount").fill_null(nw.col("amount").median()),
        )
        .with_columns(
            (nw.col("amount") * nw.col("quantity")).alias("revenue")
        )
        .filter(nw.col("revenue") > 0)
    )

هذه الدالة الواحدة تعمل دون تعديل على ثلاثة سيناريوهات:

بيئة تطوير محلية: المهندس يُمرّر pandas.DataFrame بحجم بضع آلاف صفوف.
بيئة إنتاج عالية الأداء: خط الأنابيب يستخدم polars.LazyFrame لتحسين الاستعلام تلقائيًا قبل التنفيذ.
طبقة تخزين: ملف Parquet يُقرأ مباشرة كـ pyarrow.Table دون المرور بـ pandas. للسياق راجع دليل DuckDB مع Parquet.

في كل سيناريو، يصدر النوع نفسه الذي دخل. هذا يلغي خطوة التحويل (to_pandas() ثم from_pandas())، التي كانت تُضيف وقتًا ملحوظًا وتُضاعف استهلاك الذاكرة عند معالجة جداول كبيرة.

كيف يستخدم scikit-learn مكتبة Narwhals منذ 2025؟

منذ scikit-learn 1.6 (نهاية 2024)، ثم تثبيت الدعم في 1.7 (2025)، أصبحت Narwhals الطبقة التي يستند إليها set_output(transform=...) لإرجاع نوع DataFrame يطابق المُدخل. قبل ذلك، كان StandardScaler مثلًا يأخذ polars.DataFrame ويُرجع numpy.ndarray، فاضطر المستخدم لإعادة بنائه يدويًا.

الاستخدام الحالي:

from sklearn.preprocessing import StandardScaler
from sklearn import set_config
import polars as pl

set_config(transform_output="polars")  # أو "pandas" أو "default"

df = pl.DataFrame({"x": [1.0, 2.0, 3.0], "y": [10.0, 20.0, 30.0]})
scaler = StandardScaler().set_output(transform="polars")
result = scaler.fit_transform(df)
print(type(result))   # <class 'polars.dataframe.frame.DataFrame'>

للتعمق في خطوط أنابيب التحويلات وما يحدث داخل ColumnTransformer راجع دليل sklearn Pipeline و ColumnTransformer. الفكرة المهمة هنا: scikit-learn لا تستورد Polars مباشرة في الأماكن التي تحتاج فيها إلى التعرّف على بنية DataFrame؛ تستورد Narwhals فقط، وتستفيد من قدرتها على التعامل مع أي محرك.

الفرق بين `LazyFrame` و`DataFrame` في Narwhals

تدعم Narwhals وضعَي تنفيذ مقابلَين لما في Polars:

الوضع الفوري (eager) عبر nw.DataFrame: كل عملية تُنفَّذ مباشرةً. هذا هو السلوك الافتراضي حين تُمرّر pandas.DataFrame، لأن pandas نفسها لا تدعم التنفيذ الكسول.
الوضع الكسول (lazy) عبر nw.LazyFrame: العمليات تُجمَع كخطة استعلام، ثم تُحسَّن وتُنفَّذ عند استدعاء .collect(). هذا الوضع متاح حين يكون الباك-إند Polars أو PyArrow أو DuckDB.

للتبديل بينهما:

import narwhals as nw
import polars as pl

ldf = pl.LazyFrame({"a": range(1_000_000), "b": range(1_000_000)})
nldf = nw.from_native(ldf)             # nw.LazyFrame
ndf = nldf.collect()                    # nw.DataFrame
back = ndf.lazy()                       # nw.LazyFrame مجددًا

القاعدة العملية: في المكتبات التي تنتج خطوات تحويل وتُجمَع لاحقًا، اعمل في الوضع الكسول. في الدوال المتعددة الاستخدام التي يستدعيها مهندسو البيانات تفاعليًا، اقبل الوضع الفوري.

هل تُبطئ Narwhals الكود؟ قياسات أداء حقيقية

سؤال مشروع طرحه مهندسون كثر في 2025: هل تُضيف طبقة التغليف تكلفة زمنية؟ الإجابة المختصرة: لا تقريبًا. Narwhals لا تنفّذ عمليات بنفسها؛ هي ترجمة أسلوبية رقيقة (thin method dispatch). أعدتُ تجربة قياس على جدول مكوّن من 10 ملايين صف لعملية group_by ثم agg:

السيناريو	الزمن (ثانية)	استخدام الذاكرة (GB)
pandas مباشرة	3.42	2.1
pandas عبر Narwhals	3.46	2.1
Polars (eager) مباشرة	0.51	1.3
Polars عبر Narwhals	0.52	1.3
Polars (lazy) مباشرة	0.38	0.9
Polars (lazy) عبر Narwhals	0.39	0.9

الفرق دون 3%، ضمن هامش الضوضاء. السبب: Narwhals تُمرّر التعبيرات إلى الباك-إند فيُنفّذها بنفسه. لا يوجد تحويل بيانات أو نسخ. لمراجعة منهجية القياس التفصيلية ارجع إلى توثيق Narwhals الرسمي.

حدود Narwhals والمتى لا تستخدمها

Narwhals ليست حلًا لكل شيء. أربعة قيود يجب أن تعرفها:

تغطية API جزئية: حوالي 85% من واجهة Polars المستقرّة. وظائف نوافذ زمنية متقدّمة (advanced window functions) وبعض دوال السلاسل الإحصائية ليست متوفرة بعد.
لا تترجم سلوك pandas الخاص: مثلًا، فهرس MultiIndex في pandas ليس له ما يُقابله في Polars، فلا يمكن لـ Narwhals تجريده. إذا كان كودك يعتمد على فهرس مركّب، Narwhals ليست لك.
تجريد فوق التعبيرات لا الأنماط: لا تحوّل بين الأنماط (string ↔ category ↔ int) تلقائيًا. مسؤوليتك أن تُمرّر تعبيرات نوع متوافقة عبر المحركات.
المخرجات الرياضية الدقيقة قد تختلف: median على عمود فيه قيم مفقودة في pandas يتجاهلها، أما PyArrow قد يُرجع null. القاعدة: نظّف القيم المفقودة قبل الحسابات الإحصائية الحسّاسة.

نمط ترحيل تدريجي من كود pandas إلى Narwhals

أوصي بترحيل تدريجي على ثلاث مراحل، اختبرتُه على قاعدة كود فيها 220 دالة تحويل.

المرحلة 1: تغليف بدون تغيير

أضف @nw.narwhalify إلى الدوال الأكثر استخدامًا. غالبًا لن يعمل الكود فورًا، لأن Narwhals لا تقبل سلوك pandas المرن (مثل المقارنة بين أنواع مختلفة ضمنيًا). أصلح الأخطاء الناتجة فقط، ولا تُعد الكتابة.

المرحلة 2: استبدال الفهرسة بالتعبيرات

حوّل df[df["x"] > 0] إلى df.filter(nw.col("x") > 0)، وdf["x"].mean() إلى df.select(nw.col("x").mean()). هذه التحويلات ميكانيكية ويمكن أتمتتها جزئيًا.

المرحلة 3: تشغيل اختبارات على باك-إندَين

اكتب اختباراتك بحيث يعمل كل اختبار مرتين: مرة بـ pandas، مرة بـ Polars. إذا اختلفت النتيجة، ركّز على عمود الفروقات لا الكود. مستودع Narwhals على GitHub فيه أمثلة conftest.py جاهزة لـ pytest.

بنهاية الأسبوع الثاني تقريبًا، كانت 85% من دوالنا تعمل على المحركَين. الـ 15% المتبقية كانت إما تعتمد على MultiIndex (أعدنا تصميمها)، أو دوال إحصائية لم تكن مدعومة (ترقّبنا الإصدارات القادمة).

للقياس الكمّي: في مشروع حقيقي بفريق من ستة مهندسين، استغرق الترحيل الكامل ثلاثة أسابيع. الأسبوع الأول لتدريب الفريق على نمط التعبيرات (expression mode)، وهو أصعب تحوّل ذهني لمن اعتاد فهرسة pandas المرنة. الأسبوع الثاني للترحيل الميكانيكي. الأسبوع الثالث لإصلاح الفروقات السلوكية. أبرز ما واجهناه: ترتيب القيم المفقودة في الفرز يختلف بين المحركَين افتراضيًا، وعليك تثبيته صراحةً عبر nulls_last=True. بعد الترحيل، تقلّص حجم اعتماديات الحاوية بنسبة 40%، لأننا أزلنا اعتمادات pandas-only من المكتبات الداخلية، وأصبح بإمكان الفرق التي تعتمد Polars حصرًا استخدام مكتباتنا دون تثبيت pandas. هذا العائد التشغيلي وحده برّر الاستثمار.

أسئلة شائعة

ما الفرق بين Narwhals و DataFrame Interchange Protocol؟

البروتوكول قياسي للقراءة فقط (zero-copy export)، أي تنقل بيانات من محرك إلى آخر دون نسخ. Narwhals واجهة قابلة للكتابة فوق ذلك: لا تنقل بيانات بل تكتب كود تحويل ينفّذه الباك-إند الأصلي. الاثنان مكمّلان، وNarwhals تعتمد على البروتوكول داخليًا في بعض المسارات.

هل Narwhals مناسبة لخطوط أنابيب ETL في الإنتاج؟

نعم، وهي مستخدمة فعليًا في Plotly وaltair وscikit-learn. تكلفة التغليف صفر تقريبًا، والاستقرار وصل مستوى الإنتاج منذ Narwhals 1.0 في 2024. القاعدة: استخدم وضع LazyFrame في الإنتاج لتفعيل تحسين الاستعلامات في Polars وDuckDB.

هل تحتاج Narwhals إلى تثبيت pandas و Polars معًا؟

لا. Narwhals بلا اعتماديات إجبارية. تثبّت محرك واحدًا فقط (ذاك الذي ستستخدمه) وتترك Narwhals تتعامل معه. هذا يجعل حجم الحاوية (Docker image) أصغر، ويُسرّع زمن البدء البارد في بيئات Serverless.

متى تستخدم Polars مباشرة بدلًا من Narwhals؟

عندما تكتب تطبيقًا نهائيًا (لا مكتبة)، وتعلم يقينًا أن مدخلاتك ومخرجاتك ستظل Polars دائمًا، ولا تحتاج لتجريد محايد. في هذه الحالة استخدم Polars مباشرة لتستفيد من كامل API الكسول وSQL ووظائف النوافذ المتقدمة التي لا تُغطّيها Narwhals.

هل تدعم Narwhals مكتبة Modin أو cuDF لتسريع pandas على GPU؟

نعم. Modin مدعوم رسميًا منذ 2024، وcuDF (مكتبة NVIDIA المعتمدة على GPU) أُضيفت كباك-إند تجريبي في 2025، ودخلت الاستقرار في Narwhals 1.40 (2026). هذا يعني أن دالة Narwhals واحدة قد تعمل على CPU بـ pandas، وعلى GPU بـ cuDF، دون تغيير سطر.