開(kāi)發(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é)作。本文以倉(cāng)庫(kù)測(cè)試集中一個(gè)最簡(jiǎn) SageMath 筆記本sage_print_hello.ipynb為例完整演示并剖析 Sage 筆記本 → Markdown 的轉(zhuǎn)換流程從 YAML 元數(shù)據(jù)頭的生成、代碼單元到圍欄代碼塊的映射到命令行與 Python API 兩種實(shí)操方式再到反向轉(zhuǎn)換與源碼級(jí)原理驗(yàn)證幫助讀者在任意語(yǔ)言內(nèi)核尤其是 SageMath上快速上手 Jupytext 的文本化工作流。轉(zhuǎn)換產(chǎn)物一瞥輸入與輸出對(duì)照關(guān)聯(lián)文檔tests/data/notebooks/outputs/ipynb_to_md/sage_print_hello.md是轉(zhuǎn)換的最終產(chǎn)物內(nèi)容極簡(jiǎn)但完整--- 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、無(wú)輸出 - 頂層 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é)。 對(duì)照兩張表可以發(fā)現(xiàn)**轉(zhuǎn)換并非機(jī)械復(fù)制單元內(nèi)容**而是做了三件事剝離執(zhí)行計(jì)數(shù)與輸出輕量 Markdown 格式只承載代碼與元數(shù)據(jù)、把 kernelspec 元數(shù)據(jù)重新組織成 Jupytext 的 YAML 元數(shù)據(jù)頭、把代碼單元渲染成帶語(yǔ)言標(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見(jiàn) [README.md](https://link.gitcode.com/i/4c8680e0fcd27acf9e879b616b6b7020)對(duì)應(yīng)方向反過(guò)來(lái)即可 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對(duì)應(yīng) Jupytext 的markdown格式format_namemarkdown、extension.md見(jiàn)下文 formats 源碼。需要注意在轉(zhuǎn)換命令沒(méi)有顯式加-o時(shí)輸出文件路徑由目標(biāo)擴(kuò)展名推導(dǎo)運(yùn)行時(shí)請(qǐng)依據(jù)實(shí)際工作目錄合理組織輸入輸出避免覆蓋同名文件。方式二Python API 調(diào)用在 Python 會(huì)話中調(diào)用同樣簡(jiǎn)單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對(duì)象write再根據(jù)目標(biāo)擴(kuò)展名.md選擇 Markdown 輸出器完成序列化。這種雙向讀寫機(jī)制與倉(cāng)庫(kù)中 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中的代碼則還原為代碼單元。這正是文本筆記本 ? 原生筆記本無(wú)損往返的核心閉環(huán)也是 Jupytext 在 Git 協(xié)作場(chǎng)景中讓.md文件成為.ipynb的文本替身的基礎(chǔ)。源碼級(jí)原理Markdown 格式是如何定義與映射的Markdown 格式的注冊(cè)在 src/jupytext/formats.py 中markdown格式通過(guò)NotebookFormatDescription注冊(cè)format_namemarkdown同時(shí)支持.md與.markdown兩種擴(kuò)展名分別綁定MarkdownCellReader讀取與MarkdownCellExporter寫出兩個(gè)類對(duì)應(yīng) cell 層級(jí)的反序列化與序列化.md格式當(dāng)前版本號(hào)1.3最低可讀版本1.0為格式演進(jìn)如 2021 年起代碼單元允許超過(guò)三個(gè)反引號(hào)開(kāi)頭的圍欄見(jiàn)注釋預(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é)對(duì) Markdown 單元源碼進(jìn)行轉(zhuǎn)義處理而代碼單元?jiǎng)t由對(duì)應(yīng)的 cell exporter 序列化為sage print(Hello world)其中圍欄的語(yǔ)言標(biāo)簽 sage 取自單元語(yǔ)言。對(duì)本文示例而言這個(gè)語(yǔ)言既來(lái)自 kernelspec.language sage也由輸出擴(kuò)展名 .sage 的映射兜底——見(jiàn)下文擴(kuò)展名映射。 ### 語(yǔ)言與擴(kuò)展名的映射表 [src/jupytext/languages.py](https://link.gitcode.com/i/6426d335af38a4927e89373251dabd97) 維護(hù)了 _SCRIPT_EXTENSIONS 表其中明確登記 python .sage: {language: sage, comment: #},這意味著 Jupytext 原生識(shí)別.sage擴(kuò)展名及其語(yǔ)言sage注釋符為#Sage 腳本的 Markdown/percent/light 格式均以此為前綴參見(jiàn)ipynb_to_percent、ipynb_to_hydrogen等輸出目錄中sage_print_hello.sage的# ---/# %%寫法。該表正是jupytext --to md判斷目標(biāo)格式、以及jupytext --to ipynb判斷腳本語(yǔ)言類型的數(shù)據(jù)基礎(chǔ)。Sage 內(nèi)核的特殊處理重要細(xì)節(jié)從源碼可以確認(rèn)一個(gè)針對(duì) 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 在檢測(cè)到kernelspec.language sage時(shí)強(qiáng)制把自動(dòng)擴(kuò)展名改寫為.sage。這解釋了為什么倉(cāng)庫(kù)ipynb_to_percent與ipynb_to_hydrogen目錄下同源輸出均為sage_print_hello.sage而非.py。多格式家族中的同一輸入從測(cè)試集看輸出差異同一輸入筆記本在倉(cāng)庫(kù)測(cè)試輸出目錄中衍生出多個(gè)文本形態(tài)方便對(duì)比不同格式的差異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 的多格式回歸測(cè)試集同一筆記本在不同格式間往返轉(zhuǎn)換后應(yīng)保持語(yǔ)義等價(jià)這正是 tests/round_trip 與test_sample_notebooks_are_normalized等測(cè)試要守護(hù)的核心不變量。用戶在選型時(shí)可據(jù)此判斷追求可讀性選 Markdown/MyST追求腳本化執(zhí)行選 percent/light。實(shí)戰(zhàn)建議與適用前提元數(shù)據(jù)頭是內(nèi)核還原的關(guān)鍵請(qǐng)保留 Markdown 文本開(kāi)頭的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ù)的版本控制場(chǎng)景需要保留輸出時(shí)請(qǐng)改用--to ipynb的原生格式或按需配置。版本兼容.md的 Markdown 格式版本為 1.3最低可讀 1.0老版本生成的 Markdown 文本仍可被當(dāng)前版本讀取跨大版本升級(jí)時(shí)建議先做一次往返轉(zhuǎn)換驗(yàn)證。SageMath 的.sage自動(dòng)擴(kuò)展名依賴本文所述的auto_ext_from_metadata特殊分支使用auto擴(kuò)展名配對(duì)如formats ipynb,sage:auto一類配置時(shí)Sage 筆記本會(huì)正確落到.sage無(wú)需手動(dòng)指定擴(kuò)展名。至此從最簡(jiǎn)print(Hello world)筆記本出發(fā)你已經(jīng)走通了 SageMath 筆記本 → Markdown → 反向還原的完整鏈路并掌握了 Jupytext 在格式注冊(cè)、語(yǔ)言映射與 Sage 內(nèi)核適配上的底層設(shè)計(jì)。將同樣的方法套用到你自己的 SageMath或其他語(yǔ)言內(nèi)核筆記本上即可立即獲得 Git 友好的文本化協(xié)作體驗(yàn)。贊分享開(kāi)發(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 提供開(kāi)發(fā)工具Lighthouse硬編碼UI字符串翻譯langinfo.yml的strings字段詳解Lighthouse硬編碼UI字符串翻譯langinfo.yml的strings字段詳解 Lighthouse 是 HarbourMasters 出品的《班卓開(kāi)發(fā)工具pandas v0.16.1 版本解析CategoricalIndex、sample 抽樣與字符串訪問(wèn)器的里程碑式增強(qiáng)pandas v0.16.1 版本解析CategoricalIndex、sample 抽樣與字符串訪問(wèn)器的里程碑式增強(qiáng) pandas v0.16.12015開(kāi)發(fā)工具上一篇Labwc集成方案如何與waybar、swaybg等工具完美協(xié)作下一篇探索未來(lái)的代碼管理工具M(jìn)Git創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考