Tukar buku nota Jupyter kepada Markdown — percuma dan peribadi

Tukar Jupyter Notebook kepada Markdown: simpan naratifnya, buang bungkusannya

Sebuah notebook sebenarnya dua dokumen yang berkongsi satu nama fail. Ada bahagian yang anda tulis — tajuk, penerangan, kod, hasil cetakan yang membuktikan hujah anda — dan ada bungkusan JSON tempat format itu menyimpannya. Buka fail .ipynb dalam editor teks dan yang anda nampak ialah bungkusannya: setiap baris prosa dipecah menjadi rentetan tersendiri, "execution_count": 7 pada setiap sel, objek "metadata": {} kosong bertaburan di merata tempat, dan di suatu tempat di tengahnya suku megabait base64 yang akhirnya memaparkan satu carta serakan kecil.

Menukar kepada Markdown bermakna membuang bungkusan dan menyimpan dokumen. Sel markdown anda memang sudah Markdown, jadi ia lalu tanpa disentuh. Sel kod menjadi blok kod berpagar yang dilabel dengan bahasa kernel — bentuk yang sudah difahami oleh setiap model, setiap README dan setiap penjana laman statik. Lepaskan fail .ipynb di atas dan penukaran berlaku dalam tab pelayar ini; fail itu tidak pernah dimuat naik.

Di mana beratnya sebenarnya

Ramai menyangka notebook yang besar itu besar kerana kodnya. Hampir tidak pernah begitu. Beratnya terletak pada empat tempat, mengikut urutan menurun:

• Output imej base64. Setiap plt.show() menulis PNG yang terhasil ke dalam fail sebagai teks base64. Satu rajah lazimnya menelan 200 hingga 400 KB aksara. Notebook dengan sedozen plot pada dasarnya memang plot. Bagi pembaca versi teks, tiada satu pun daripadanya membawa makna.
• Perwakilan HTML bagi dataframe. Pandas mengeluarkan text/plain dan text/html sekali gus untuk hasil yang sama. Versi HTML membawa gaya sebaris dan satu <table> dengan satu tag bagi setiap sel, jadi saiznya boleh dua puluh kali ganda versi biasa sedangkan maksudnya sama sahaja.
• Bingkai bar kemajuan. Gelung tqdm menulis baris baharu setiap kali ia disegar semula, dipisahkan oleh aksara pemulangan kereta. Akhirnya fail itu menyimpan ratusan salinan bar yang hanya sekali sahaja dilihat orang.
• Metadata setiap sel. Secara berasingan remeh, secara kumulatif tidak: id sel, kiraan pelaksanaan, bendera runtuh dan objek metadata kosong merentas beberapa ratus sel akhirnya menjadi angka yang nyata.

Penukar di atas menangani setiap satunya. Muatan media dikira lalu digantikan dengan satu baris penanda tempat supaya anda masih tahu di mana rajah pernah berada. Apabila satu hasil menawarkan teks biasa dan HTML sekali gus, teks biasa yang menang. Jujukan pemulangan kereta diruntuhkan kepada keadaan akhir baris itu. Metadata dibuang sepenuhnya. Alat ini melaporkan apa yang dibuangnya, jadi penjimatan itu sesuatu yang kelihatan, bukan sekadar dakwaan.

Kenapa blok berpagar lebih penting daripada rupanya

Perkara paling berguna yang Markdown lakukan untuk sebuah notebook ialah menandakan sempadan antara prosa dan kod secara eksplisit. Dalam JSON mentah, sempadan itu hanya wujud sebagai medan "cell_type" beberapa baris di atas kandungannya. Diratakan secara cuai, penerangan dan kod yang diterangkannya bercantum, dan pembaca — manusia mahupun model — terpaksa meneka mana satu yang mana semata-mata daripada sintaks.

Pagar yang dilabel bahasa menghapuskan tekaan itu. Ia turut membawa bahasa kernel ke hadapan: penukar membaca language_info daripada metadata notebook, dan berundur kepada kernelspec jika tiada, jadi notebook R atau Julia dipagar sebagai R atau Julia dan bukan dilabel Python secara senyap. Output mendapat pagarnya sendiri tanpa label di bawah sel yang menghasilkannya, didahului satu baris Output: yang ringkas — cukup untuk mengekalkan hubungan sebab-akibat tanpa mencipta sintaks yang Markdown memang tidak ada.

Traceback berbaloi disimpan

Ada godaan untuk membuang output ralat sekali dengan yang lain. Biasanya itu keputusan yang salah. Jika anda menyerahkan notebook kepada model dan bertanya kenapa satu sel gagal, traceback itulah keseluruhan soalannya. Yang menjengkelkan tentang traceback dalam bentuk mentah bukan kandungannya tetapi kod warna ANSI yang IPython bungkus di sekelilingnya — jujukan pelarian yang terpapar sebagai warna kemas dalam terminal dan sebagai sampah ESC[0;31m di tempat lain.

Jujukan itu ditanggalkan dan teks traceback dikekalkan. Yang terlalu panjang dipendekkan dari tengah, bukan dari hujung, kerana dalam timbunan yang dalam bingkai yang berguna ialah beberapa yang pertama dan beberapa yang terakhir, manakala dua ratus baris dalaman pustaka di antaranya memang bahagian yang anda akan langkau.

Notebook dalam himpunan repositori

Penukaran yang sama berjalan di dalam alat GitHub, GitLab dan folder tempatan di laman ini. Pilih fail .ipynb dalam sesebuah repositori dan ia muncul dalam output sebagai sel yang boleh dibaca, bukan sebagai dinding JSON. Ini lebih penting daripada bunyinya: dalam repositori sains data, notebook selalunya tempat penaakulan sebenar berada, sedangkan sebelum ini ia justru fail yang terpaksa anda nyahpilih supaya output kekal berguna.

Dalam konteks itu had output lebih ketat berbanding halaman ini, kerana himpunan repositori ialah konteks untuk model dan, bagi setiap token, output sel adalah bahagian yang paling kurang bernilai. Satu nota dalam teks yang ditukar merekodkan berapa banyak yang dibuang, jadi tiada apa yang hilang secara senyap.

Notebook lama masih boleh ditukar kepada Markdown

Format versi 4 meletakkan sel dalam tatasusunan cells di peringkat atas. Versi 3, yang masih bertaburan dalam repositori awam sejak awal 2010-an, menyarangkannya satu lapis lebih dalam di bawah worksheets dan menamakan medan sumbernya input dan bukan source. Kedua-dua bentuk dibaca. Begitu juga jenis output pyout yang digunakan versi 3 di tempat versi 4 menulis execute_result.

Dua perkara sengaja tidak dicuba. Widget notebook — penggelongsor dan plot interaktif yang disokong ipywidgets — menyimpan keadaannya dalam blok metadata berasingan dan tidak menghasilkan apa-apa yang berguna sebagai teks; penanda tempat memberitahu anda satu pernah ada di situ. Dan susunan pelaksanaan sel dikekalkan seperti mana ia muncul dalam fail, bukan diisih mengikut kiraan pelaksanaan, kerana susunan anda membaca notebook ialah susunan ia ditulis.

Tiada apa yang dimuat naik

Notebook membawa perkara yang orang lupa: kunci API yang ditampal ke dalam sel semasa menyahpepijat, rentetan sambungan pangkalan data, sekeping data produksi yang dicetak untuk menyemak satu join. Penukaran berjalan dalam JavaScript di tab ini. Tiada langkah muat naik, tiada salinan pelayan, dan tiada permintaan pemadaman yang perlu dihantar selepasnya. Tutup tab dan ia hilang.

Jika anda mahukan teks biasa dan bukan Markdown — tiada pagar, tiada struktur, hanya prosa dan kod — penukar notebook kepada teks melakukannya, dan fail yang anda pilih akan dibawa bersama.