بررسی nbdev v2: نوت بوک های Jupyter سازگار با Git

افزودنی به نوت‌بوک‌های Jupyter یک سبک توسعه باسواد پایتون را فعال می‌کند که اسناد، آزمایش‌ها، ادغام مداوم و بسته‌بندی را به صورت رایگان در اختیار شما قرار می‌دهد.

راه های زیادی برای برنامه نویسی وجود دارد. یکی از پربازده‌ترین پارادایم‌ها تعاملی است: شما از یک REPL (حلقه خواندن-ایوال-چاپ) برای نوشتن و آزمایش کد خود در حین کدنویسی استفاده می‌کنید و سپس کد آزمایش شده را در یک فایل کپی می‌کنید.

روش REPL که در محیط‌های توسعه LISP ایجاد شد، برای برنامه‌نویسی پایتون مناسب است، زیرا پایتون همیشه ابزارهای توسعه تعاملی خوبی داشته است. اشکال این سبک برنامه نویسی این است که وقتی کد را نوشتید، باید تست ها را جداگانه بیرون بکشید و مستندات را بنویسید، همه آن ها را در یک مخزن ذخیره کنید، بسته بندی خود را انجام دهید و بسته و مستندات خود را منتشر کنید.

پارادایم برنامه نویسی باسواد دونالد کنوت، نوشتن مستندات و کد را تجویز می کند. در همان سند، با اسنادی که هدفشان انسان است، با کد در نظر گرفته شده برای رایانه در هم آمیخته شده است. برنامه نویسی با سواد به طور گسترده برای برنامه نویسی علمی و علم داده استفاده شده است، اغلب از محیط های نوت بوک مانند Notebooks Jupyter، Jupyter Lab، Visual Studio Code استفاده می شود. و PyCharm. یکی از مشکلات نوت‌بوک‌ها این است که گاهی اوقات با مخازن خوب بازی نمی‌کنند، زیرا اطلاعات زیادی را ذخیره می‌کنند، از جمله ابرداده‌هایی که برای کسی مهم نیست. هنگامی که تداخل ادغام وجود داشته باشد، مشکل ایجاد می کند، زیرا نوت بوک ها سلول گرا هستند و مخازن کد منبع مانند Git خط گرا هستند.

جرمی هاوارد و همل حسین از fast.ai، به همراه حدود دوجین مشارکت‌کننده کوچک، وارد شده‌اند. با مجموعه ای از ابزارهای خط فرمان که نه تنها به نوت بوک های Jupyter اجازه می دهد تا به خوبی با Git بازی کنند، بلکه یک سبک برنامه نویسی با سواد تعاملی بسیار کارآمد را نیز فعال می کنند. علاوه بر تولید سریع کد پایتون صحیح، می‌توانید اسناد و آزمایش‌ها را همزمان تولید کنید، همه آن‌ها را بدون ترس از خراب شدن درگیری‌های ادغام در Git ذخیره کنید و با چند دستور در PyPI و Conda منتشر کنید. در حالی که یک منحنی یادگیری برای این ابزارهای برقی وجود دارد، اما این سرمایه گذاری سودی را به همراه دارد، زیرا می توانید پروژه توسعه خود را در مدت زمانی که معمولاً صرف نوشتن کد می کند، انجام دهید.

همانطور که در نمودار زیر می بینید، nbdev با Jupyter Notebooks، GitHub کار می کند. a>، Quarto، Anaconda و PyPI. برای خلاصه کردن آنچه که هر قطعه از این سیستم انجام می دهد:

• می‌توانید با استفاده از Quarto اسناد تولید کنید و آن‌ها را در صفحات GitHub. اسناد از LaTeX پشتیبانی می‌کنند، قابل جستجو هستند و به‌طور خودکار پیوند داده می‌شوند.
• می توانید بسته ها را در PyPI و Conda و همچنین ابزارهایی برای ساده سازی انتشار بسته منتشر کنید. بهترین روش‌های پایتون به‌طور خودکار دنبال می‌شوند، برای مثال، فقط اشیاء صادر شده در __all__ گنجانده می‌شوند.
• همگام سازی دو طرفه بین نوت بوک ها و کد منبع متن ساده وجود دارد که به شما امکان می دهد از IDE خود برای پیمایش کد یا ویرایش های سریع استفاده کنید.
• تست‌هایی که به‌عنوان سلول‌های نوت‌بوک معمولی نوشته می‌شوند به‌طور موازی با یک فرمان اجرا می‌شوند.
• یکپارچه‌سازی مداوم با اقدامات GitHub وجود دارد که آزمایش‌های شما را اجرا می‌کند و اسناد شما را بازسازی می‌کند.
• نوت‌بوک‌های سازگار با Git با قلاب‌های Jupyter/Git که ابرداده‌های ناخواسته را تمیز می‌کنند و ادغام را ارائه می‌کنند. درگیری در قالبی قابل خواندن برای انسان.

نرم‌افزار nbdev با Jupyter Notebooks، GitHub، Quarto، Anaconda و PyPi کار می‌کند تا محیطی سازنده و تعاملی برای توسعه Python ایجاد کند.

نصب nbdev

nbdev روی macOS، Linux و اکثر سیستم عامل‌های سبک یونیکس کار می‌کند. به نسخه اخیر پایتون ۳ نیاز دارد. من از Python 3.9.6 در macOS Ventura استفاده کردم که روی M1 MacBook Pro اجرا می‌شود. nbdev روی ویندوز تحت WSL (زیر سیستم ویندوز برای لینوکس) کار می کند، اما نه تحت cmd یا PowerShell. می توانید nbdev را با pip یا Conda نصب کنید. من از pip استفاده کردم:

pip install nbdev

که ۲۹ ابزار خط فرمان را نصب کرد که می‌توانید با استفاده از nbdev_help فهرست کنید:

% nbdev_help
nbdev_bump_version              Increment version in settings.ini by one
nbdev_changelog                 Create a CHANGELOG.md file from closed and labeled GitHub issues
nbdev_clean                     Clean all notebooks in `fname` to avoid merge conflicts
nbdev_conda                     Create a `meta.yaml` file ready to be built into a package, and optionally build and upload it
nbdev_create_config             Create a config file.
nbdev_docs                      Create Quarto docs and README.md
nbdev_export                    Export notebooks in `path` to Python modules
nbdev_filter                    A notebook filter for Quarto
nbdev_fix                       Create working notebook from conflicted notebook `nbname`
nbdev_help                      Show help for all console scripts
nbdev_install                   Install Quarto and the current library
nbdev_install_hooks             Install Jupyter and git hooks to automatically clean, trust, and fix merge conflicts in notebooks
nbdev_install_quarto            Install latest Quarto on macOS or Linux, prints instructions for Windows
nbdev_merge                     Git merge driver for notebooks
nbdev_migrate                   Convert all markdown and notebook files in `path` from v1 to v2
nbdev_new                       Create an nbdev project.
nbdev_prepare                   Export, test, and clean notebooks, and render README if needed
nbdev_preview                   Preview docs locally
nbdev_proc_nbs                  Process notebooks in `path` for docs rendering
nbdev_pypi                      Create and upload Python package to PyPI
nbdev_readme                    None
nbdev_release_both              Release both conda and PyPI packages
nbdev_release_gh                Calls `nbdev_changelog`, lets you edit the result, then pushes to git and calls `nbdev_release_git`
nbdev_release_git               Tag and create a release in GitHub for the current version
nbdev_sidebar                   Create sidebar.yml
nbdev_test                      Test in parallel notebooks matching `path`, passing along `flags`
nbdev_trust                     Trust notebooks matching `fname`
nbdev_update                    Propagate change in modules matching `fname` to notebooks that created them

توسعه‌دهندگان nbdev پیشنهاد می‌کنند یا این ویدیوی ۹۰ دقیقه‌ای را تماشا کنید یا این تقریباً یک ساعته را تماشا کنید توضیحات نوشتاری. من هر دو را انجام دادم و همچنین اطلاعات بیشتری از اسناد و برخی از کد منبع را مطالعه کردم. من مطالب متفاوتی را از هر کدام یاد گرفتم، بنابراین پیشنهاد می‌کنم ابتدا ویدیو را تماشا کنید و سپس مراحل را انجام دهید. برای من، این ویدیو به من ایده کافی واضحی از کاربرد بسته به من داد تا من را تشویق کند تا آموزش را طی کنم.

راهنمایی nbdev را شروع کنید

آموزش با نصب Jupyter Notebook شروع می‌شود:

pip install notebook

و سپس Jupyter را راه اندازی کنید:

jupyter notebook

نصب در نوت بوک، ابتدا با ایجاد یک ترمینال جدید و سپس استفاده از ترمینال برای نصب nbdev ادامه می یابد. اگر قبلاً آن را در پوسته انجام داده‌اید، مانند من، می‌توانید از نصب صرفنظر کنید.

سپس می توانید از nbdev برای نصب Quarto استفاده کنید:

nbdev_install_quarto

این به دسترسی روت نیاز دارد، بنابراین باید رمز عبور خود را وارد کنید. می‌توانید کد منبع Quarto یا docs تا مطمئن شوید که ایمن است.

در این مرحله باید به GitHub بروید و یک مخزن خالی ایجاد کنید (repo). من آموزش را دنبال کردم و با nbdev_hello_world تماس گرفتم و یک توضیح نسبتاً عمومی اضافه کردم. مخزن را ایجاد کنید. در صورت نیاز به دستورالعمل‌ها مراجعه کنید. سپس مخزن را در دستگاه محلی خود کلون کنید. دستورالعمل ها پیشنهاد می کنند از خط فرمان Git در دستگاه خود استفاده کنید، اما اتفاقاً من دوست دارم از GitHub Desktop استفاده کنم، که همچنین خوب کار می کرد.

در هر صورت، cd را به مخزن خود در ترمینال خود وارد کنید. فرقی نمی کند که از ترمینال روی دسکتاپ یا نوت بوک خود استفاده می کنید. اکنون nbdev_new را اجرا کنید، که مجموعه ای از فایل ها را در مخزن شما ایجاد می کند. سپس موارد اضافه شده خود را به GitHub متعهد و فشار دهید:

git add .
git commit -m'Initial commit'
git push

به مخزن خود در GitHub برگردید و تب Actions را باز کنید. چیزی شبیه به این خواهید دید:

عملکردهای GitHub پس از انجام اولیه. دو وجود دارد: یک گردش کار یکپارچه سازی پیوسته (CI) برای پاک کردن کد شما، و یک گردش کاری Deploy to GitHub Pages برای ارسال اسناد شما.

اکنون صفحات GitHub را با دنبال کردن دستورالعمل‌های اختیاری فعال کنید. باید به این شکل باشد:

فعال کردن صفحات GitHub.

برگه Actions را دوباره باز کنید و سومین گردش کار را مشاهده خواهید کرد:

اکنون سه گردش کار در مخزن شما وجود دارد. مورد جدید اسناد وب را تولید می کند.

اکنون وب سایت ایجاد شده خود را در https://{user}.github.io/{repo} باز کنید. مال من در https://meheller.github.io/nbdev-hello-world/ می توانید آن را کپی کنید و meheller را به دسته GitHub خود تغییر دهید و چیزی شبیه به موارد زیر ببینید:

صفحه اسناد وب اولیه برای بسته.

بررسی nbdev را ادامه دهید

اکنون بالاخره به چیزهای خوب می رسیم. الف>. وقتی نوت‌بوک‌ها را چک می‌کنید، قلاب‌های وب را نصب می‌کنید تا به‌طور خودکار آنها را تمیز کنید،

nbdev_install_hooks

کتابخانه خود را صادر کنید،

nbdev_export

بسته خود را نصب کنید،

pip install -e '.[dev]'

پیش‌نمایش اسناد خود،

nbdev_preview

(و روی پیوند کلیک کنید) و در نهایت شروع به ویرایش نوت بوک پایتون خود کنید:

jupyter notebook

(و روی nbs کلیک کنید و روی ۰۰_core.ipynb کلیک کنید).

نوت بوک را همانطور که توضیح داده شد ویرایش کنید، سپس تغییرات خود را آماده کنید :

nbdev_prepare

index.ipynb همانطور که توضیح داده شد ویرایش کنید، سپس فشار دهید تغییرات در GitHub:

git add .
git commit -m'Add `say_hello`; update index'
git push

در صورت تمایل، می‌توانید ادامه دهید و عملکردهای پیشرفته را اضافه کنید .

مخزن nbdev-hello-world پس از اتمام آموزش.

همانطور که مشاهده کردید، به خصوص اگر خودتان از طریق آموزش کار کرده باشید، nbdev می‌تواند یک گردش کار توسعه پایتون بسیار سازنده را در نوت‌بوک‌ها فعال کند، و با یک مخزن GitHub و اسناد Quarto که در صفحات GitHub نمایش داده می‌شود، به راحتی کار کند. اگر هنوز از طریق آموزش کار نکرده اید، منتظر چه چیزی هستید؟

—

تماس: fast.ai، https://nbdev.fast.ai/