開發(fā)工具【免費(fèi)下載鏈接】jupytextJupyter Notebooks as Markdown Documents, Julia, Python or R scripts項(xiàng)目地址https://gitcode.com/gh_mirrors/ju/jupytext點(diǎn)擊查看免費(fèi)下載Jupytext 的核心能力是把 Jupyter 筆記本.ipynb與純文本格式Markdown、腳本等相互轉(zhuǎn)換讓筆記本可以被 Git 友好地版本管理和協(xié)作。本文以倉庫測試集中一個(gè)最簡 SageMath 筆記本sage_print_hello.ipynb為例完整演示并剖析 Sage 筆記本 → Markdown 的轉(zhuǎn)換流程從 YAML 元數(shù)據(jù)頭的生成、代碼單元到圍欄代碼塊的映射到命令行與 Python API 兩種實(shí)操方式再到反向轉(zhuǎn)換與源碼級原理驗(yàn)證幫助讀者在任意語言內(nèi)核尤其是 SageMath上快速上手 Jupytext 的文本化工作流。轉(zhuǎn)換產(chǎn)物一瞥輸入與輸出對照關(guān)聯(lián)文檔tests/data/notebooks/outputs/ipynb_to_md/sage_print_hello.md是轉(zhuǎn)換的最終產(chǎn)物內(nèi)容極簡但完整--- jupyter: kernelspec: display_name: SageMath 9.2 language: sage name: sagemath --- sage print(Hello world)其上游輸入是 [tests/data/notebooks/inputs/ipynb_sage/sage_print_hello.ipynb](https://link.gitcode.com/i/13380073bd58bf9aea2372d0cca7656e) - 筆記本只有一個(gè) code 類型單元源代碼為 print(Hello world)execution_count 為 null、無輸出 - 頂層 metadata.kernelspec 聲明內(nèi)核為 SageMath 9.2display_name: SageMath 9.2、language: sage、name: sagemath - language_info 記錄 name: python、file_extension: .py、codemirror_mode 為 ipython 3 等——這是 Sage 內(nèi)核繼承自 IPython 環(huán)境的典型特征也是下方源碼分析中一個(gè)關(guān)鍵細(xì)節(jié)。 對照兩張表可以發(fā)現(xiàn)**轉(zhuǎn)換并非機(jī)械復(fù)制單元內(nèi)容**而是做了三件事剝離執(zhí)行計(jì)數(shù)與輸出輕量 Markdown 格式只承載代碼與元數(shù)據(jù)、把 kernelspec 元數(shù)據(jù)重新組織成 Jupytext 的 YAML 元數(shù)據(jù)頭、把代碼單元渲染成帶語言標(biāo)簽 sage 的 Markdown 圍欄代碼塊。 ## 把 Sage 筆記本變成 Markdown 的兩種實(shí)操方式 ### 方式一命令行轉(zhuǎn)換CLI 與 README 中 convert a notebook in one format to another with jupytext --to ipynb notebook.py見 [README.md](https://link.gitcode.com/i/4c8680e0fcd27acf9e879b616b6b7020)對應(yīng)方向反過來即可 bash # 將 Sage 筆記本轉(zhuǎn)換為 Markdown 文本筆記本 jupytext --to md tests/data/notebooks/inputs/ipynb_sage/sage_print_hello.ipynb # 若希望生成獨(dú)立的指定輸出文件使用 -o 指定輸出路徑 jupytext --to md tests/data/notebooks/inputs/ipynb_sage/sage_print_hello.ipynb -o sage_print_hello.md生成的sage_print_hello.md即與ipynb_to_md目錄下的輸出一致。--to md中的md對應(yīng) Jupytext 的markdown格式format_namemarkdown、extension.md見下文 formats 源碼。需要注意在轉(zhuǎn)換命令沒有顯式加-o時(shí)輸出文件路徑由目標(biāo)擴(kuò)展名推導(dǎo)運(yùn)行時(shí)請依據(jù)實(shí)際工作目錄合理組織輸入輸出避免覆蓋同名文件。方式二Python API 調(diào)用在 Python 會(huì)話中調(diào)用同樣簡單import jupytext nb jupytext.read(tests/data/notebooks/inputs/ipynb_sage/sage_print_hello.ipynb) jupytext.write(nb, sage_print_hello.md)read負(fù)責(zé)把任意格式的筆記本載入統(tǒng)一的nbformat對象write再根據(jù)目標(biāo)擴(kuò)展名.md選擇 Markdown 輸出器完成序列化。這種雙向讀寫機(jī)制與倉庫中 tests/functional/simple_notebooks/test_read_simple_ipynb.py 體現(xiàn)的讀寫一致性思路一致Jupytext 保證write產(chǎn)出的文本能再次被read還原為等價(jià)筆記本。反向轉(zhuǎn)換從 Markdown 回到 Sage 筆記本Jupytext 的轉(zhuǎn)換是雙向的把上面的 Markdown 文本還原成.ipynbjupytext --to ipynb sage_print_hello.md -o sage_print_hello.ipynb或import jupytext nb jupytext.read(sage_print_hello.md) jupytext.write(nb, sage_print_hello.ipynb)此時(shí) YAML 元數(shù)據(jù)頭中的kernelspecdisplay_name: SageMath 9.2、language: sage、name: sagemath會(huì)被重新注入筆記本元數(shù)據(jù)保證還原后的筆記本仍使用正確的 SageMath 內(nèi)核圍欄代碼塊sage中的代碼則還原為代碼單元。這正是文本筆記本 ? 原生筆記本無損往返的核心閉環(huán)也是 Jupytext 在 Git 協(xié)作場景中讓.md文件成為.ipynb的文本替身的基礎(chǔ)。源碼級原理Markdown 格式是如何定義與映射的Markdown 格式的注冊在 src/jupytext/formats.py 中markdown格式通過NotebookFormatDescription注冊format_namemarkdown同時(shí)支持.md與.markdown兩種擴(kuò)展名分別綁定MarkdownCellReader讀取與MarkdownCellExporter寫出兩個(gè)類對應(yīng) cell 層級的反序列化與序列化.md格式當(dāng)前版本號1.3最低可讀版本1.0為格式演進(jìn)如 2021 年起代碼單元允許超過三個(gè)反引號開頭的圍欄見注釋預(yù)留兼容空間。當(dāng)write拿到擴(kuò)展名為.md的目標(biāo)路徑時(shí)Jupytext 會(huì)據(jù)此選擇MarkdownCellExporterread讀取.md文件時(shí)則按格式名與擴(kuò)展名反查MarkdownCellReaderread_format_from_metadata、擴(kuò)展名到格式的映射邏輯同樣位于 src/jupytext/formats.py 一帶。代碼單元到圍欄代碼塊的渲染在 src/jupytext/cell_to_text.py 中markdown_to_text負(fù)責(zé)對 Markdown 單元源碼進(jìn)行轉(zhuǎn)義處理而代碼單元?jiǎng)t由對應(yīng)的 cell exporter 序列化為sage print(Hello world)其中圍欄的語言標(biāo)簽 sage 取自單元語言。對本文示例而言這個(gè)語言既來自 kernelspec.language sage也由輸出擴(kuò)展名 .sage 的映射兜底——見下文擴(kuò)展名映射。 ### 語言與擴(kuò)展名的映射表 [src/jupytext/languages.py](https://link.gitcode.com/i/6426d335af38a4927e89373251dabd97) 維護(hù)了 _SCRIPT_EXTENSIONS 表其中明確登記 python .sage: {language: sage, comment: #},這意味著 Jupytext 原生識別.sage擴(kuò)展名及其語言sage注釋符為#Sage 腳本的 Markdown/percent/light 格式均以此為前綴參見ipynb_to_percent、ipynb_to_hydrogen等輸出目錄中sage_print_hello.sage的# ---/# %%寫法。該表正是jupytext --to md判斷目標(biāo)格式、以及jupytext --to ipynb判斷腳本語言類型的數(shù)據(jù)基礎(chǔ)。Sage 內(nèi)核的特殊處理重要細(xì)節(jié)從源碼可以確認(rèn)一個(gè)針對 Sage 筆記本的專門處理在 src/jupytext/formats.py 的auto_ext_from_metadata中# Sage notebooks have .py as the associated extension in language_info, # so we change it to .sage in that case, see #727 if auto_ext .py and metadata.get(kernelspec, {}).get(language) sage: auto_ext .sage正如本文示例筆記本的language_info.file_extension為.py所體現(xiàn)的SageMath 內(nèi)核繼承自 IPython其language_info常被標(biāo)成 Python。若不特殊處理auto擴(kuò)展名推斷會(huì)把 Sage 筆記本錯(cuò)誤地當(dāng)成 Python 腳本輸出為.py。因此 Jupytext 在檢測到kernelspec.language sage時(shí)強(qiáng)制把自動(dòng)擴(kuò)展名改寫為.sage。這解釋了為什么倉庫ipynb_to_percent與ipynb_to_hydrogen目錄下同源輸出均為sage_print_hello.sage而非.py。多格式家族中的同一輸入從測試集看輸出差異同一輸入筆記本在倉庫測試輸出目錄中衍生出多個(gè)文本形態(tài)方便對比不同格式的差異tests/data/notebooks/outputs/ipynb_to_md/sage_print_hello.mdYAML 元數(shù)據(jù)頭 sage圍欄代碼塊本文主題tests/data/notebooks/outputs/ipynb_to_percent/sage_print_hello.sage# ---注釋形式元數(shù)據(jù)頭 # %%分隔的 percent 腳本tests/data/notebooks/outputs/ipynb_to_hydrogen/sage_print_hello.sage氫格式同樣以# %%分隔tests/data/notebooks/outputs/ipynb_to_myst/sage_print_hello.mdMyST Markdown 變體tests/data/notebooks/outputs/ipynb_to_Rmd/sage_print_hello.RmdR Markdown 變體tests/data/notebooks/outputs/ipynb_to_script/sage_print_hello.sage純腳本light變體。這些文件共同構(gòu)成 Jupytext 的多格式回歸測試集同一筆記本在不同格式間往返轉(zhuǎn)換后應(yīng)保持語義等價(jià)這正是 tests/round_trip 與test_sample_notebooks_are_normalized等測試要守護(hù)的核心不變量。用戶在選型時(shí)可據(jù)此判斷追求可讀性選 Markdown/MyST追求腳本化執(zhí)行選 percent/light。實(shí)戰(zhàn)建議與適用前提元數(shù)據(jù)頭是內(nèi)核還原的關(guān)鍵請保留 Markdown 文本開頭的jupyter.kernelspec段。反向轉(zhuǎn)換時(shí) Jupytext 會(huì)據(jù)此恢復(fù)內(nèi)核配置若手工刪除還原出的筆記本將丟失內(nèi)核信息需在 Jupyter 中重新選擇 SageMath 內(nèi)核。execution_count與輸出不會(huì)進(jìn)入 Markdown輕量 Markdown 格式不記錄執(zhí)行計(jì)數(shù)與單元格輸出因此轉(zhuǎn)換常用于代碼 元數(shù)據(jù)的版本控制場景需要保留輸出時(shí)請改用--to ipynb的原生格式或按需配置。版本兼容.md的 Markdown 格式版本為 1.3最低可讀 1.0老版本生成的 Markdown 文本仍可被當(dāng)前版本讀取跨大版本升級時(shí)建議先做一次往返轉(zhuǎn)換驗(yàn)證。SageMath 的.sage自動(dòng)擴(kuò)展名依賴本文所述的auto_ext_from_metadata特殊分支使用auto擴(kuò)展名配對如formats ipynb,sage:auto一類配置時(shí)Sage 筆記本會(huì)正確落到.sage無需手動(dòng)指定擴(kuò)展名。至此從最簡print(Hello world)筆記本出發(fā)你已經(jīng)走通了 SageMath 筆記本 → Markdown → 反向還原的完整鏈路并掌握了 Jupytext 在格式注冊、語言映射與 Sage 內(nèi)核適配上的底層設(shè)計(jì)。將同樣的方法套用到你自己的 SageMath或其他語言內(nèi)核筆記本上即可立即獲得 Git 友好的文本化協(xié)作體驗(yàn)。贊分享開發(fā)工具【免費(fèi)下載鏈接】jupytextJupyter Notebooks as Markdown Documents, Julia, Python or R scripts項(xiàng)目地址https://gitcode.com/gh_mirrors/ju/jupytext點(diǎn)擊查看免費(fèi)下載相關(guān)推薦Apache Flink SQL Gateway 完全指南架構(gòu)原理、啟動(dòng)配置與 REST 查詢實(shí)戰(zhàn)Apache Flink SQL Gateway 完全指南架構(gòu)原理、啟動(dòng)配置與 REST 查詢實(shí)戰(zhàn) SQL Gateway 是 Apache Flink 提供開發(fā)工具Lighthouse硬編碼UI字符串翻譯langinfo.yml的strings字段詳解Lighthouse硬編碼UI字符串翻譯langinfo.yml的strings字段詳解 Lighthouse 是 HarbourMasters 出品的《班卓開發(fā)工具pandas v0.16.1 版本解析CategoricalIndex、sample 抽樣與字符串訪問器的里程碑式增強(qiáng)pandas v0.16.1 版本解析CategoricalIndex、sample 抽樣與字符串訪問器的里程碑式增強(qiáng) pandas v0.16.12015開發(fā)工具上一篇Labwc集成方案如何與waybar、swaybg等工具完美協(xié)作下一篇探索未來的代碼管理工具M(jìn)Git創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考