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 และคุณสามารถเปิดเป็น Notebooks ได้ด้วยการคลิกขวาใน Jupyter Lab

สมุดบันทึกที่จับคู่

สมุดบันทึกข้อความที่มีนามสกุล .py หรือ .md เหมาะอย่างยิ่งสำหรับการควบคุมเวอร์ชัน สามารถแก้ไขหรือเขียนได้อย่างสะดวกใน IDE คุณสามารถเปิดและเรียกใช้เป็นสมุดบันทึกใน Jupyter Lab ได้ด้วยการคลิกขวา อย่างไรก็ตาม ผลลัพธ์ของโน้ตบุ๊กจะหายไปเมื่อปิดโน้ตบุ๊ก เนื่องจากมีเพียงอินพุตโน้ตบุ๊กเท่านั้นที่ถูกบันทึกในโน้ตบุ๊กข้อความ

ทางเลือกที่สะดวกสำหรับสมุดบันทึกข้อความคือสมุดบันทึกที่จับคู่ นี่คือชุดของไฟล์สองไฟล์ เช่น .ipynb และ .py ซึ่งมีสมุดบันทึกเดียวกัน แต่อยู่ในรูปแบบที่แตกต่างกัน

คุณสามารถแก้ไขสมุดบันทึกที่จับคู่เวอร์ชัน .py และรับการแก้ไขกลับใน Jupyter โดยเลือก โหลดสมุดบันทึกซ้ำจากดิสก์ เอาต์พุตจะถูกโหลดซ้ำจากไฟล์ .ipynb หากมีอยู่ เวอร์ชัน .ipynb จะได้รับการอัปเดตหรือสร้างขึ้นใหม่ในครั้งถัดไปที่คุณบันทึกสมุดบันทึกใน Jupyter

หากต้องการจับคู่สมุดบันทึกใน Jupyter Lab ให้ใช้คำสั่งจับ Pair Notebook with percent Script จาก Command Palette:

หากต้องการจับคู่สมุดบันทึกทั้งหมดในไดเรกทอรีใดไดเรกทอรีหนึ่ง ให้สร้างไฟล์การกำหนดค่าด้วยเนื้อหานี้:

 # 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 โดยใช้คำสั่ง pair ใน Jupyter Lab หรือไฟล์การกำหนดค่าส่วนกลาง
บันทึกสมุดบันทึก - สิ่งนี้จะสร้างสมุดบันทึก .py
เพิ่มสมุดบันทึก .py นี้ลงในการควบคุมเวอร์ชัน

คุณอาจแยกไฟล์ .ipynb ออกจากการควบคุมเวอร์ชัน (เว้นแต่คุณต้องการดูเอาต์พุตที่มีเวอร์ชัน!) Jupytext จะสร้างไฟล์ .ipynb ขึ้นมาใหม่เมื่อผู้ใช้เปิดและบันทึกสมุด .py

การทำงานร่วมกันบนโน้ตบุ๊กด้วย Git

การทำงานร่วมกันบนสมุดบันทึก Jupyter ผ่าน Git กลายเป็นเรื่องง่ายเหมือนกับการทำงานร่วมกันในไฟล์ข้อความ

สมมติว่าคุณมีสมุดบันทึก .py ของคุณอยู่ภายใต้การควบคุมเวอร์ชัน (ดูด้านบน) แล้ว,

ผู้ทำงานร่วมกันของคุณดึงสมุดบันทึก .py
พวกเขาเปิด เป็นสมุดบันทึก ใน Jupyter (คลิกขวาใน Jupyter Lab)
ในขั้นตอนนั้นโน้ตบุ๊กไม่มีเอาต์พุต พวกเขาเรียกใช้สมุดบันทึกและบันทึก เอาต์พุตจะถูกสร้างขึ้นใหม่ และสร้างไฟล์ .ipynb ในเครื่อง
พวกเขาแก้ไขสมุดบันทึกและพุชไฟล์ notebook.py ที่อัปเดต ความแตกต่างนั้นไม่มีอะไรมากไปกว่าความแตกต่างมาตรฐานในสคริปต์ Python
คุณดึงสคริปต์ notebook.py ที่อัปเดตแล้ว และรีเฟรชเบราว์เซอร์ของคุณ เซลล์อินพุตได้รับการอัปเดตตามเนื้อหาใหม่ของ notebook.py ผลลัพธ์จะถูกโหลดซ้ำจากไฟล์ .ipynb ในเครื่องของคุณ ในที่สุด ตัวแปรเคอร์เนลจะไม่ถูกแตะต้อง ดังนั้นคุณจึงมีตัวเลือกให้รันเฉพาะเซลล์ที่แก้ไขเพื่อรับเอาต์พุตใหม่

การแก้ไขหรือปรับโครงสร้างสมุดบันทึกใน IDE

เมื่อสมุดบันทึกของคุณจับคู่กับไฟล์ .py คุณสามารถแก้ไขหรือปรับโครงสร้างการแสดง .py ของสมุดบันทึกใน IDE ได้อย่างง่ายดาย

เมื่อคุณแก้ไขสมุดบันทึก .py เสร็จแล้ว คุณจะต้องโหลดสมุดบันทึก ซ้ำ ใน Jupyter เพื่อแก้ไขล่าสุดที่นั่น

หมายเหตุ: การปิดสมุดบันทึก .ipynb ใน Jupyter จะง่ายกว่าเมื่อคุณแก้ไขไฟล์ .py ที่จับคู่ไว้ ไม่มีข้อผูกมัดที่จะต้องทำเช่นนั้น อย่างไรก็ตาม ถ้าคุณไม่ทำ คุณควรเตรียมพร้อมที่จะอ่านข้อความป๊อปอัปอย่างละเอียด หาก Jupyter พยายามบันทึกโน้ตบุ๊กในขณะที่ไฟล์ .py ที่จับคู่ไว้ได้รับการแก้ไขบนดิสก์ตั้งแต่การรีโหลดครั้งล่าสุด ระบบจะตรวจพบข้อขัดแย้ง และระบบจะขอให้คุณตัดสินใจว่าโน้ตบุ๊กเวอร์ชันใด (ในหน่วยความจำหรือบนดิสก์) อันที่เหมาะสม