Jupytext

هل كنت تتمنى دائمًا أن تكون دفاتر ملاحظات Jupyter عبارة عن مستندات نصية عادية؟ هل تمنيت أن تتمكن من تعديلها في IDE المفضل لديك؟ والحصول على فروق واضحة وذات مغزى عند التحكم في الإصدار؟ إذًا، ربما تكون Jupytext هي الأداة التي تبحث عنها!

دفاتر النصوص

يحتوي دفتر ملاحظات Python المشفر بتنسيق py:percent على امتداد .py ويبدو كما يلي:

 # %% [markdown]
# This is a markdown cell

# %%
def f(x):
  return 3*x+1

يتم تضمين مدخلات دفتر الملاحظات فقط (وبيانات التعريف بشكل اختياري). تعتبر دفاتر الملاحظات النصية مناسبة تمامًا للتحكم في الإصدار. يمكنك أيضًا تحريرها أو إعادة تشكيلها في IDE - دفتر الملاحظات .py أعلاه هو ملف Python عادي.

نوصي باستخدام تنسيق percent لدفاتر الملاحظات التي تحتوي في الغالب على تعليمات برمجية. تنسيق percent متاح لـ Julia وPython وR والعديد من اللغات الأخرى.

إذا كان دفتر ملاحظاتك موجهًا نحو التوثيق، فقد يكون التنسيق المستند إلى Markdown (دفاتر ملاحظات نصية بامتداد .md ) أكثر ملاءمة. اعتمادًا على ما تخطط للقيام به مع الكمبيوتر الدفتري الخاص بك، قد تفضل تنسيق Myst Markdown، الذي يتفاعل بشكل جيد جدًا مع Jupyter Book، أو Quarto Markdown، أو حتى Pandoc Markdown.

تثبيت

قم بتثبيت Jupytext في بيئة Python التي تستخدمها لـ Jupyter. استخدم إما

 pip install jupytext

أو

 conda install jupytext -c conda-forge

بعد ذلك، أعد تشغيل خادم Jupyter Lab، وتأكد من تنشيط Jupytext في Jupyter: تحتوي ملفات .py و .md على أيقونة Notebook، ويمكنك فتحها كدفاتر ملاحظات بالنقر بزر الماوس الأيمن في Jupyter Lab.

أجهزة الكمبيوتر المحمولة المقترنة

تعد دفاتر الملاحظات النصية ذات الامتداد .py أو .md مناسبة تمامًا للتحكم في الإصدار. يمكن تحريرها أو تأليفها بسهولة في IDE. يمكنك فتحها وتشغيلها كدفاتر ملاحظات في Jupyter Lab بالنقر بزر الماوس الأيمن. ومع ذلك، يتم فقدان مخرجات دفتر الملاحظات عند إغلاق دفتر الملاحظات، حيث يتم حفظ مدخلات دفتر الملاحظات فقط في دفاتر الملاحظات النصية.

البديل المناسب لدفاتر الملاحظات النصية هو دفاتر الملاحظات المقترنة. هذه عبارة عن مجموعة من ملفين، على سبيل المثال .ipynb و .py ، تحتويان على نفس دفتر الملاحظات، ولكن بتنسيقات مختلفة.

يمكنك تحرير إصدار .py من دفتر الملاحظات المقترن، واستعادة التعديلات مرة أخرى في Jupyter عن طريق تحديد إعادة تحميل دفتر الملاحظات من القرص . سيتم إعادة تحميل المخرجات من ملف .ipynb ، إذا كان موجودًا. سيتم تحديث إصدار .ipynb أو إعادة إنشائه في المرة التالية التي تقوم فيها بحفظ دفتر الملاحظات في Jupyter.

لإقران دفتر ملاحظات في Jupyter Lab، استخدم الأمر " Pair Notebook with percent Script من لوحة الأوامر:

لإقران كافة دفاتر الملاحظات في دليل معين، قم بإنشاء ملف تكوين يتضمن هذا المحتوى:

 # jupytext.toml at the root of your notebook directory
formats = "ipynb,py:percent"

سطر الأوامر

Jupytext متاح أيضًا في سطر الأوامر. أنت تستطيع

قم بإقران دفتر ملاحظات باستخدام jupytext --set-formats ipynb,py:percent notebook.ipynb
مزامنة الملفات المقترنة مع jupytext --sync notebook.py (يتم تحميل المدخلات من أحدث ملف مقترن)
تحويل دفتر ملاحظات بتنسيق إلى آخر باستخدام jupytext --to ipynb notebook.py (استخدم -o إذا كنت تريد ملف إخراج محدد)
قم بتوصيل دفتر ملاحظات إلى linter باستخدام jupytext --pipe black notebook.ipynb

حالات الاستخدام العينة

أجهزة الكمبيوتر المحمولة تحت التحكم في الإصدار

هذه طريقة سريعة:

افتح دفتر ملاحظاتك .ipynb في Jupyter وقم بإقرانه بدفتر ملاحظات .py ، باستخدام إما أمر الاقتران في Jupyter Lab، أو ملف التكوين العام
احفظ دفتر الملاحظات - يؤدي هذا إلى إنشاء دفتر .py
قم بإضافة دفتر الملاحظات .py هذا إلى التحكم في الإصدار

يمكنك استبعاد ملفات .ipynb من التحكم في الإصدار (إلا إذا كنت تريد رؤية المخرجات التي تم إصدار إصدارها!). سيقوم Jupytext بإعادة إنشاء ملفات .ipynb محليًا عندما يقوم المستخدمون بفتح دفاتر الملاحظات .py وحفظها.

التعاون في دفاتر الملاحظات مع Git

أصبح التعاون في دفاتر ملاحظات Jupyter من خلال Git سهلاً مثل التعاون في الملفات النصية.

افترض أن لديك دفاتر ملاحظات .py الخاصة بك تحت التحكم في الإصدار (انظر أعلاه). ثم،

يقوم المتعاون بسحب دفتر الملاحظات .py
يقومون بفتحه كدفتر ملاحظات في Jupyter (انقر بزر الماوس الأيمن في Jupyter Lab)
في تلك المرحلة، لا يحتوي دفتر الملاحظات على أي مخرجات. يقومون بتشغيل دفتر الملاحظات وحفظه. يتم إعادة إنشاء المخرجات، ويتم إنشاء ملف .ipynb محلي
يقومون بتحرير دفتر الملاحظات، ويدفعون ملف notebook.py المحدث. الفرق ليس سوى فرق قياسي في برنامج بايثون النصي.
يمكنك سحب البرنامج النصي notebook.py المحدث، وتحديث المتصفح الخاص بك. يتم تحديث خلايا الإدخال بناءً على المحتوى الجديد لـ notebook.py . يتم إعادة تحميل المخرجات من ملف .ipynb المحلي الخاص بك. وأخيرًا، لم يتم تغيير متغيرات النواة، لذا لديك خيار تشغيل الخلايا المعدلة فقط للحصول على المخرجات الجديدة.

تحرير أو إعادة بناء دفتر ملاحظات في IDE

بمجرد إقران دفتر الملاحظات الخاص بك بملف .py ، يمكنك بسهولة تحرير أو إعادة تشكيل تمثيل .py لدفتر الملاحظات في IDE.

بمجرد الانتهاء من تحرير دفتر الملاحظات .py ، سيتعين عليك فقط إعادة تحميل دفتر الملاحظات في Jupyter للحصول على أحدث التعديلات هناك.

ملاحظة: من الأسهل إغلاق دفتر الملاحظات .ipynb في Jupyter عندما تقوم بتحرير ملف .py المقترن. ليس هناك أي التزام للقيام بذلك؛ ومع ذلك، إذا لم تقم بذلك، يجب أن تكون مستعدًا لقراءة الرسائل المنبثقة بعناية. إذا حاول Jupyter حفظ دفتر الملاحظات بينما تم أيضًا تحرير ملف .py المقترن على القرص منذ آخر عملية إعادة تحميل، فسيتم اكتشاف تعارض وسيُطلب منك تحديد إصدار دفتر الملاحظات (في الذاكرة أو على القرص) الذي يناسبك واحد مناسب.