scrapbook

สมุดเรื่องที่สนใจ

ไลบรารี สมุดเรื่องที่สนใจ จะบันทึกค่าข้อมูลของสมุดบันทึกและสร้างเนื้อหาภาพเป็น "เรื่องที่สนใจ" เรื่องที่สนใจที่บันทึกไว้สามารถอ่านได้ในอนาคต

ดูเอกสารสมุดเรื่องที่สนใจสำหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีการใช้สมุดเรื่องที่สนใจ

ใช้กรณี

ผู้ใช้โน้ตบุ๊กอาจต้องการบันทึกข้อมูลที่เกิดขึ้นระหว่างการทำงานของโน้ตบุ๊ก ข้อมูลที่บันทึกไว้ เรื่องที่สนใจ นี้สามารถนำมาใช้ในภายหลังหรือส่งต่อในเวิร์กโฟลว์ไปยังสมุดบันทึกอื่นเป็นอินพุตได้

กล่าวคือ สมุดเรื่องที่สนใจช่วยให้คุณ:

• ข้อมูลและเนื้อหาภาพ คงอยู่ ในสมุดบันทึกเป็นเศษซาก

• เรียกคืน เศษข้อมูลที่มีอยู่

• สรุปการรวบรวม สมุดบันทึก

รองรับเวอร์ชันหลาม

เป้าหมายการสนับสนุนระยะยาวของไลบรารีนี้คือ Python 3.6+ ขณะนี้ยังรองรับ Python 2.7 จนกว่า Python 2 จะหมดอายุการใช้งานในปี 2020 หลังจากวันดังกล่าว การรองรับ Python 2 จะหยุดลง และจะมีเพียงเวอร์ชัน 3.x เท่านั้นที่ยังคงอยู่

การติดตั้ง

ติดตั้งโดยใช้ pip :

pip install scrapbook

สำหรับการติดตั้งการพึ่งพา IO เสริม คุณสามารถระบุบันเดิลร้านค้าแต่ละชุดได้ เช่น s3 หรือ azure :

pip install scrapbook[s3]

หรือใช้ all :

pip install scrapbook[all]

---

แบบจำลองและคำศัพท์เฉพาะทาง

สมุดเรื่องที่สนใจกำหนดรายการต่อไปนี้:

• เรื่องที่สนใจ : ค่าข้อมูลที่ต่อเนื่องกันและการแสดงภาพ เช่น สตริง รายการของวัตถุ กรอบข้อมูลแพนด้า แผนภูมิ รูปภาพ หรือการอ้างอิงข้อมูล

• สมุดบันทึก : ออบเจ็กต์สมุดบันทึก nbformat ที่ห่อพร้อมวิธีพิเศษสำหรับการโต้ตอบกับเรื่องที่สนใจ

• สมุดเรื่องที่สนใจ : ชุดสมุดบันทึกพร้อมอินเทอร์เฟซสำหรับถามคำถามในคอลเลกชัน

• ตัวเข้ารหัส : โปรแกรมแปลข้อมูลที่ลงทะเบียนแล้วไปยัง/จากรูปแบบการจัดเก็บข้อมูลโน้ตบุ๊ก

โมเดล scrap

โมเดล scrap ประกอบด้วยคุณลักษณะที่สำคัญบางประการในทูเพิล ได้แก่:

• name : ชื่อของเรื่องที่สนใจ

• data : ข้อมูลใด ๆ ที่บันทึกโดยการเรียก API สมุดเรื่องที่สนใจ

• encoder : ชื่อของตัวเข้ารหัสที่ใช้ในการเข้ารหัส/ถอดรหัสข้อมูลไปยัง/จากโน้ตบุ๊ก

• display : ข้อมูลการแสดงผลใด ๆ ที่ใช้โดย IPython เพื่อแสดงเนื้อหาภาพ

---

เอพีไอ

Scrapbook เพิ่มคำสั่ง API พื้นฐานบางประการซึ่งช่วยให้สามารถบันทึกและเรียกข้อมูลได้ รวมถึง:

• glue เพื่อคงเศษที่สนใจโดยมีหรือไม่มี เอาต์พุตแสดงผล

• read_notebook อ่านสมุดบันทึกหนึ่งเล่ม

• scraps ให้พจนานุกรมที่ค้นหาได้ของเรื่องที่สนใจทั้งหมดตามชื่อ

• reglue ซึ่งคัดลอกเรื่องที่สนใจจากสมุดบันทึกอื่นไปยังสมุดบันทึกปัจจุบัน

• read_notebooks อ่านสมุดบันทึกจำนวนมากจากเส้นทางที่กำหนด

• scraps_report แสดงรายงานเกี่ยวกับเรื่องที่สนใจที่รวบรวมไว้

• papermill_dataframe และ papermill_metrics สำหรับความเข้ากันได้แบบย้อนหลังสำหรับฟีเจอร์โรงกระดาษสองรายการที่เลิกใช้แล้ว

ส่วนต่อไปนี้จะให้รายละเอียดเพิ่มเติมเกี่ยวกับคำสั่ง api เหล่านี้

glue เพื่อคงเศษ

บันทึก scrap (ข้อมูลหรือค่าการแสดงผล) ในเซลล์สมุดบันทึกที่กำหนด

สามารถเรียกคืน scrap (มูลค่าที่บันทึกไว้) ได้ในระหว่างการตรวจสอบสมุดบันทึกเอาท์พุตในภายหลัง

 """ตัวอย่างกาวสำหรับการบันทึกค่าข้อมูล"""นำเข้าสมุดภาพเป็น sbsb.glue("hello", "world")sb.glue("number", 123)sb.glue("some_list", [1, 3, 5])sb.glue("some_dict", {"a": 1, "b": 2})sb.glue("non_json", df, 'ลูกศร')

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

 # อ่านสมุดบันทึกและรับเรื่องที่สนใจที่บันทึกไว้ก่อนหน้านี้nb = sb.read_notebook('notebook.ipynb')nb.scraps

สมุดเรื่องที่สนใจ จะบ่งบอกถึงรูปแบบการจัดเก็บข้อมูลตามประเภทค่าของตัวเข้ารหัสข้อมูลที่ลงทะเบียนไว้ อีกทางหนึ่ง รูปแบบการเข้ารหัสโดยนัยสามารถเขียนทับได้โดยการตั้งค่าอาร์กิวเมนต์ encoder เป็นชื่อที่ลงทะเบียน (เช่น "json" ) ของตัวเข้ารหัสเฉพาะ

ข้อมูลนี้ยังคงอยู่โดยการสร้างเอาต์พุตการแสดงผลด้วยสื่อชนิดพิเศษที่ระบุรูปแบบและข้อมูลการเข้ารหัสเนื้อหา ผลลัพธ์เหล่านี้ไม่สามารถมองเห็นได้เสมอไปในการเรนเดอร์โน้ตบุ๊ก แต่ยังคงมีอยู่ในเอกสาร สมุดเรื่องที่สนใจสามารถคืนข้อมูลที่เกี่ยวข้องกับสมุดบันทึกได้ในอนาคตโดยการอ่านเอาต์พุตของเซลล์เหล่านี้

พร้อม เอาท์พุตการแสดงผล

หากต้องการแสดงเรื่องที่สนใจพร้อมเอาท์พุตการแสดงผลที่มองเห็นได้ คุณต้องระบุว่าเรื่องที่สนใจนั้นสามารถแสดงผลได้โดยตรง

ซึ่งสามารถทำได้โดยการสลับอาร์กิวเมนต์ display

 # บันทึกข้อความ UI พร้อมกับอินพุต stringsb.glue("hello", "Hello World", display=True)

การโทรจะบันทึกข้อมูลและคุณลักษณะการแสดงผลของวัตถุเศษ ทำให้มองเห็นได้เช่นเดียวกับการเข้ารหัสข้อมูลต้นฉบับ สิ่งนี้อาศัยฟังก์ชัน IPython.core.formatters.format_display_data เพื่อแปลออบเจ็กต์ข้อมูลเป็นจอแสดงผลและ dict ข้อมูลเมตาสำหรับเคอร์เนลโน้ตบุ๊กเพื่อแยกวิเคราะห์

รูปแบบอื่นที่สามารถใช้ได้คือการระบุว่าควรบันทึก เฉพาะข้อมูลที่แสดงเท่านั้น ไม่ใช่ออบเจ็กต์ต้นฉบับ สามารถทำได้โดยการตั้งค่าตัวเข้ารหัสให้ display

 # บันทึกภาพโดยไม่มีอินพุตดั้งเดิม objectb.glue("sharable_png", IPython.display.Image(filename="sharable.png"), encoder='display')

ในที่สุดประเภทสื่อที่สร้างขึ้นสามารถควบคุมได้โดยการส่งรายการ ทูเพิล หรืออ็อบเจ็กต์ dict เป็นอาร์กิวเมนต์การแสดงผล

 sb.glue("media_as_text_only", media_obj, encoder='display', display=('text/plain',) # สิ่งนี้ส่งผ่าน [text/plain] ไปยัง format_display_data รวมอาร์กิวเมนต์) sb.glue ("media_without_text", media_obj, encoder ='display', display={'exclude': 'text/plain'} # ส่งต่อไปยัง kwargs ของ format_display_data)

เช่นเดียวกับเศษข้อมูล สิ่งเหล่านี้สามารถเรียกคืนได้ในภายหลังโดยเข้าถึงแอตทริบิวต์ display ของเศษข้อมูล แม้ว่าโดยปกติแล้วเราจะใช้วิธี reglue ของ Notebook (อธิบายไว้ด้านล่าง)

read_notebook อ่านสมุดบันทึกหนึ่งเล่ม

อ่านวัตถุ Notebook ที่โหลดจากตำแหน่งที่ระบุที่ path คุณคงได้เห็นแล้วว่าฟังก์ชั่นนี้ใช้งานอย่างไรในตัวอย่างการเรียก api ข้างต้น แต่โดยพื้นฐานแล้ว สิ่งนี้จะทำให้มีกระดาษห่อบางๆ บน NotebookNode ของ nbformat พร้อมความสามารถในการแยกเศษสมุดเรื่องที่สนใจ

 nb = sb.read_notebook('notebook.ipynb')

ออบเจ็กต์ Notebook นี้ยึดตามสคีมา json ของ nbformat ทำให้สามารถเข้าถึงฟิลด์ที่จำเป็นได้

 nb.cells # เซลล์จาก notebooknb.metadatanb.nbformatnb.nbformat_minor

มีวิธีเพิ่มเติมสองสามวิธีที่ให้ไว้ ซึ่งส่วนใหญ่มีรายละเอียดเพิ่มเติมด้านล่าง:

 nb.เรื่องที่สนใจnb.reglue

นามธรรมยังทำให้เนื้อหาที่บันทึกไว้พร้อมใช้งานเป็นดาต้าเฟรมที่อ้างอิงแต่ละคีย์และแหล่งที่มา วิธีการเหล่านี้เพิ่มเติมจะมีให้ใช้งานในเวอร์ชันต่อๆ ไป

 # สร้าง data frame ด้วย ["name", "data", "encoder", "display", "filename"] เป็น columnsnb.scrap_dataframe # คำเตือน: นี่อาจเป็นวัตถุขนาดใหญ่หากข้อมูลหรือจอแสดงผลมีขนาดใหญ่

ออบเจ็กต์ Notebook ยังมีฟังก์ชันดั้งเดิมบางประการสำหรับความเข้ากันได้แบบย้อนหลังกับโมเดลออบเจ็กต์ Notebook ของโรงงานกระดาษ ด้วยเหตุนี้ จึงสามารถใช้เพื่ออ่านสถิติการดำเนินการของโรงงานกระดาษตลอดจนบทคัดย่อของสมุดเรื่องที่สนใจได้:

 nb.cell_timing # รายการการกำหนดเวลาการดำเนินการของเซลล์ในเซลล์ ordernb.execution_counts # รายการจำนวนการดำเนินการของเซลล์ในลำดับเซลล์nb.papermill_metrics # Dataframe ของการนับการดำเนินการเซลล์และ timesnb.papermill_record_dataframe # Dataframe ของบันทึกสมุดบันทึก (เรื่องที่สนใจที่มีเฉพาะข้อมูล) nb.parameter_dataframe # Dataframe ของพารามิเตอร์โน้ตบุ๊ก nb.papermill_dataframe # Dataframe ของพารามิเตอร์โน้ตบุ๊กและเศษเซลล์

เครื่องอ่านโน้ตบุ๊กอาศัย IORW ที่ลงทะเบียนของโรงงานกระดาษเพื่อให้สามารถเข้าถึงแหล่งข้อมูลที่หลากหลาย เช่น -- แต่ไม่จำกัดเพียง -- S3, Azure และ Google Cloud

scraps ให้ชื่อ -> การค้นหาเรื่องที่สนใจ

วิธี scraps ช่วยให้สามารถเข้าถึงเรื่องที่สนใจทั้งหมดในสมุดบันทึกเฉพาะได้

 nb = sb.read_notebook('notebook.ipynb')nb.scraps # พิมพ์คำสั่งของเรื่องที่สนใจทั้งหมดตามชื่อ

ออบเจ็กต์นี้มีวิธีการเพิ่มเติมสองสามวิธีเช่นกัน เพื่อการแปลงและดำเนินการที่สะดวก

 nb.scraps.data_scraps # กรองเฉพาะเรื่องที่สนใจด้วย `data` Associatednb.scraps.data_dict # แมป `data_scraps` เป็น `name` -> `data` dictnb.scraps.display_scraps # กรองเฉพาะเรื่องที่สนใจที่มี `display` เชื่อมโยงnb scraps.display_dict # แมป `display_scraps` เป็น `name` -> `display` dictnb.scraps.dataframe # สร้าง dataframe ด้วย ["name", "data", "encoder", "display"] เป็นคอลัมน์

วิธีการเหล่านี้ช่วยให้กรณีการใช้งานธรรมดาไม่ต้องขุดผ่านนามธรรมของโมเดล

reglue คัดลอกเรื่องที่สนใจลงในสมุดบันทึกปัจจุบัน

การใช้ reglue สามารถนำเศษกาวมาใส่ในสมุดจดเล่มเดียวและติดกาวเข้ากับอันปัจจุบันได้

 nb = sb.read_notebook('notebook.ipynb')nb.reglue("table_scrap") # นี่เป็นการคัดลอกทั้งข้อมูลและการแสดงผล

ข้อมูลหรือข้อมูลการแสดงผลใดๆ จะถูกคัดลอกแบบคำต่อคำไปยังสมุดบันทึกที่กำลังดำเนินการอยู่ราวกับว่าผู้ใช้เรียก glue อีกครั้งจากแหล่งต้นฉบับ

นอกจากนี้ยังสามารถเปลี่ยนชื่อเรื่องที่สนใจในกระบวนการได้อีกด้วย

 nb.reglue("table_scrap", "old_table_scrap")

และสุดท้ายนี้ ถ้าใครอยากจะลอง reglue โดยไม่ตรวจสอบการมีอยู่ของ raise_on_missing ก็สามารถตั้งค่าให้แสดงข้อความเมื่อเกิดความล้มเหลวได้

 nb.reglue("maybe_missing", Raise_on_missing=False)# => "ไม่พบเรื่องที่สนใจที่มีชื่อ 'maybe_missing' ในสมุดบันทึกนี้"

read_notebooks อ่านสมุดบันทึกได้หลายเล่ม

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

 # สร้างสมุดเรื่องที่สนใจชื่อ `book`book = sb.read_notebooks('path/to/notebook/collection/')# รับสมุดบันทึกพื้นฐานเป็น listbook.notebooks # หรือ `book.values`

เส้นทางนี้จะนำ iorw ที่ลงทะเบียนไว้ของโรงกระดาษกลับมาใช้ใหม่เพื่อแสดงรายการและอ่านไฟล์จากแหล่งต่างๆ เพื่อให้ URL ที่ไม่ใช่ในเครื่องสามารถโหลดข้อมูลได้

 # สร้างสมุดเรื่องที่สนใจชื่อ `book`book = sb.read_notebooks('s3://bucket/key/prefix/to/notebook/collection/')

สมุดเรื่องที่สนใจ ( book ในตัวอย่างนี้) สามารถใช้เพื่อเรียกคืนเรื่องที่สนใจทั้งหมดในคอลเลกชันสมุดบันทึกได้:

 book.notebook_scraps # การเขียนตามรูปร่าง `notebook` -> (`ชื่อ` -> `scrap`)book.scraps # การเขียนตามรูปร่างที่ผสาน `ชื่อ` -> `scrap`

scraps_report แสดงรายงานเกี่ยวกับเรื่องที่สนใจที่รวบรวมไว้

คอลเลกชันสมุดเรื่องที่สนใจสามารถใช้เพื่อสร้าง scraps_report เกี่ยวกับเรื่องที่สนใจทั้งหมดจากคอลเลกชันเป็นเอาต์พุตที่มีโครงสร้างมาร์กดาวน์

 หนังสือเรื่องที่สนใจ_รายงาน()

จอแสดงผลนี้สามารถกรองชื่อเรื่องที่สนใจและสมุดบันทึก รวมทั้งเปิดหรือปิดใช้งานส่วนหัวโดยรวมของจอแสดงผลได้

 book.scraps_report( scrap_names=["scrap1", "scrap2"], notebook_names=["result1"], # ตรงกับสมุดบันทึกที่มีเส้นทาง `/notebook/collections/result1.ipynb`
  ส่วนหัว=เท็จ)

ตามค่าเริ่มต้น รายงานจะเติมข้อมูลด้วยองค์ประกอบภาพเท่านั้น หากต้องการรายงานเกี่ยวกับองค์ประกอบข้อมูลให้ตั้งค่า include_data

 book.scraps_report(include_data=True)

การสนับสนุนโรงกระดาษ

สุดท้ายนี้ สมุดเรื่องที่สนใจมีคุณลักษณะที่เข้ากันได้แบบย้อนหลังสองประการสำหรับความสามารถของ papermill ที่เลิกใช้แล้ว:

 book.papermill_dataframebook.papermill_metrics

ตัวเข้ารหัส

ตัวเข้ารหัสสามารถเข้าถึงได้ด้วยชื่อคีย์ของออบเจ็กต์ Encoder ที่ลงทะเบียนกับออบเจ็กต์ encoders.registry หากต้องการลงทะเบียนตัวเข้ารหัสข้อมูลใหม่ เพียงโทร:

 จากรีจิสทรีการนำเข้าตัวเข้ารหัสเป็น encoder_registry# เพิ่มตัวเข้ารหัสไปที่ registerencoder_registry.register("custom_encoder_name", MyCustomEncoder())

คลาส encode ต้องใช้สองวิธี encode และ decode :

 class MyCustomEncoder(object):def encode(self, scrap):# scrap.data เป็นประเภทใดก็ได้ ซึ่งปกติจะเฉพาะกับเนมพาสตัวเข้ารหัส # ส่งคืน `Scrap` ด้วย `data` ประเภทหนึ่งของ [None, list, dict, *six .integer_types, *six.string_types]def decode(self, scrap):# scrap.data เป็นหนึ่งใน [ไม่มี, รายการ, dict, *six.integer_types, *six.string_types]pass # ส่งคืน `เศษ` ที่มีประเภท `data` เป็นประเภทใดก็ได้ ซึ่งโดยปกติจะเฉพาะกับชื่อตัวเข้ารหัส

ซึ่งสามารถอ่านการแปลงเรื่องที่สนใจให้เป็นออบเจ็กต์ json ที่แสดงเนื้อหาหรือตำแหน่ง และโหลดสตริงเหล่านั้นกลับเข้าไปในออบเจ็กต์ข้อมูลต้นฉบับ

text

รูปแบบการจัดเก็บสตริงพื้นฐานที่จะบันทึกข้อมูลเป็นสตริงหลาม

 sb.glue("สวัสดี", "โลก", "ข้อความ")

json

 sb.glue("foo_json", {"foo": "bar", "baz": 1}, "json")

pandas

 sb.glue("pandas_df",pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]}), "pandas")

คุณลักษณะ record ที่เลิกใช้แล้วของ Papermill

สมุดภาพมี สคีมาการบันทึกที่แข็งแกร่งและยืดหยุ่น ไลบรารีนี้จะมาแทนที่ฟังก์ชัน record ที่มีอยู่ของโรงกระดาษ

เอกสารสำหรับ record โรงงานกระดาษมีอยู่ใน ReadTheDocs โดยสรุป ฟังก์ชัน record ที่เลิกใช้แล้ว:

pm.record(name, value) : เปิดใช้งานค่าที่จะบันทึกลงในสมุดบันทึก [เอกสารประกอบ API]

 pm.record("hello", "world")pm.record("number", 123)pm.record("some_list", [1, 3, 5])pm.record("some_dict", {"a" : 1, "ข": 2})

pm.read_notebook(notebook) : pandas สามารถใช้ในภายหลังเพื่อกู้คืนค่าที่บันทึกไว้โดยการอ่านสมุดบันทึกเอาท์พุตลงใน dataframe ตัวอย่างเช่น:

 nb = pm.read_notebook('notebook.ipynb')nb.dataframe

เหตุผลสำหรับการเลิก record Papermill

ฟังก์ชัน record ของ Papermill เลิกใช้แล้วเนื่องจากข้อจำกัดและความท้าทายเหล่านี้:

• ฟังก์ชัน record ไม่เป็นไปตามรูปแบบของการดำเนินการเชิงเส้นของโน้ตบุ๊กของโรงงานกระดาษ มันเป็นเรื่องที่น่าอึดอัดใจที่จะอธิบายว่า record เป็นคุณลักษณะเพิ่มเติมของโรงงานกระดาษ และรู้สึกเหมือนเป็นการอธิบายห้องสมุดแห่งที่สองที่ด้อยพัฒนากว่าจริงๆ

• การบันทึก / การอ่าน การแปลข้อมูลที่จำเป็นเป็น JSON สำหรับทุกสิ่ง นี่เป็นกระบวนการที่น่าเบื่อและเจ็บปวดสำหรับดาต้าเฟรม

• การอ่านค่าที่บันทึกไว้ในดาต้าเฟรมจะส่งผลให้รูปร่างของดาต้าเฟรมไม่เป็นธรรมชาติ

• มีความเป็นโมดูลและความยืดหยุ่นน้อยกว่าส่วนประกอบของโรงงานกระดาษอื่นๆ ที่สามารถลงทะเบียนผู้ปฏิบัติงานแบบกำหนดเองได้

เพื่อเอาชนะข้อจำกัดเหล่านี้ใน Papermill จึงมีการตัดสินใจสร้าง Scrapbook