scrapbook
1.0.0
Perpustakaan lembar memo mencatat nilai data buku catatan dan menghasilkan konten visual sebagai "memo". Memo yang direkam dapat dibaca di lain waktu.
Lihat dokumentasi scrapbook untuk informasi lebih lanjut tentang cara menggunakan scrapbook.
Pengguna notebook mungkin ingin merekam data yang dihasilkan selama eksekusi notebook. Data yang direkam ini, scraps , dapat digunakan di lain waktu atau diteruskan dalam alur kerja ke buku catatan lain sebagai masukan.
Yaitu, lembar memo memungkinkan Anda:
data bertahan dan konten visual ditampilkan di buku catatan sebagai memo
mengingat kembali sisa data yang tersisa
merangkum koleksi buku catatan
Target dukungan jangka panjang perpustakaan ini adalah Python 3.6+. Saat ini juga mendukung Python 2.7 hingga Python 2 mencapai akhir masa pakainya pada tahun 2020. Setelah tanggal ini, dukungan Python 2 akan dihentikan, dan hanya versi 3.x yang akan dipertahankan.
Instal menggunakan pip :
pip install scrapbook Untuk menginstal dependensi IO opsional, Anda dapat menentukan paket toko individual, seperti s3 atau azure :
pip install scrapbook[s3] atau gunakan all :
pip install scrapbook[all]Scrapbook mendefinisikan item berikut:
scraps : nilai dan visualisasi data yang dapat diserialkan seperti string, daftar objek, kerangka data panda, bagan, gambar, atau referensi data.
notebook : objek notebook nbformat yang dibungkus dengan metode tambahan untuk berinteraksi dengan memo.
scrapbook : kumpulan buku catatan dengan antarmuka untuk mengajukan pertanyaan tentang koleksi tersebut.
encoders : penerjemah data terdaftar ke/dari format penyimpanan notebook.
scrap Model scrap menampung beberapa atribut utama dalam sebuah tuple, termasuk:
name : Nama memo
data : Data apa pun yang diambil oleh panggilan api scrapbook
encoder : Nama encoder yang digunakan untuk menyandikan/mendekode data ke/dari notebook
display : Data tampilan apa pun yang digunakan oleh IPython untuk menampilkan konten visual
Scrapbook menambahkan beberapa perintah api dasar yang memungkinkan penyimpanan dan pengambilan data termasuk:
glue untuk menahan sisa dengan atau tanpa keluaran tampilan
read_notebook membaca satu buku catatan
scraps menyediakan kamus yang dapat dicari untuk semua memo berdasarkan nama
reglue yang menyalin potongan dari buku catatan lain ke buku catatan saat ini
read_notebooks membaca banyak buku catatan dari jalur tertentu
scraps_report menampilkan laporan tentang memo yang dikumpulkan
papermill_dataframe dan papermill_metrics untuk kompatibilitas mundur untuk dua fitur papermill yang tidak digunakan lagi
Bagian berikut memberikan detail lebih lanjut tentang perintah api ini.
glue untuk menahan sisa Merekam scrap (data atau nilai tampilan) di sel buku catatan tertentu.
scrap (nilai yang direkam) dapat diambil pada pemeriksaan selanjutnya pada buku catatan keluaran.
"""contoh lem untuk mencatat nilai data"""impor scrapbook sebagai 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, 'panah') Pustaka lembar memo nantinya dapat digunakan untuk memulihkan scraps dari buku catatan keluaran:
# membaca buku catatan dan mengambil catatan sebelumnyasnb = sb.read_notebook('notebook.ipynb')nb.scraps scrapbook akan menyiratkan format penyimpanan berdasarkan tipe nilai dari setiap pembuat enkode data yang terdaftar. Alternatifnya, format pengkodean tersirat dapat ditimpa dengan mengatur argumen encoder ke nama terdaftar (misalnya "json" ) dari encoder tertentu.
Data ini disimpan dengan menghasilkan output tampilan dengan tipe media khusus yang mengidentifikasi format dan data pengkodean konten. Output ini tidak selalu terlihat dalam rendering buku catatan namun masih ada dalam dokumen. Scrapbook kemudian dapat merehidrasi data yang terkait dengan buku catatan di masa mendatang dengan membaca keluaran sel ini.
Untuk menampilkan memo bernama dengan keluaran tampilan yang terlihat, Anda perlu menunjukkan bahwa memo tersebut dapat dirender secara langsung.
Hal ini dapat dilakukan dengan mengaktifkan argumen display .
# merekam pesan UI bersama dengan input stringsb.glue("hello", "Hello World", display=True) Panggilan tersebut akan menyimpan data dan atribut tampilan objek Scrap, membuatnya terlihat serta menyandikan data asli. Ini bersandar pada fungsi IPython.core.formatters.format_display_data untuk menerjemahkan objek data ke dalam dict tampilan dan metadata untuk diurai oleh kernel notebook.
Pola lain yang dapat digunakan adalah dengan menentukan bahwa hanya data tampilan yang harus disimpan, dan bukan objek aslinya. Hal ini dicapai dengan mengatur encoder menjadi display .
# merekam gambar tanpa objek masukan aslib.glue("sharable_png", IPython.display.Image(filename="sharable.png"), encoder='display')Terakhir, tipe media yang dihasilkan dapat dikontrol dengan meneruskan objek list, tuple, atau dict sebagai argumen tampilan.
sb.glue("media_as_text_only", media_obj, encoder='display', display=('text/plain',) # Ini meneruskan [teks/polos] ke argumen penyertaan format_display_data)sb.glue("media_without_text", media_obj, encoder ='display', display={'exclude': 'text/plain'} # meneruskan ke kwarg format_display_data) Seperti potongan data, potongan ini dapat diambil nanti dengan mengakses atribut display potongan tersebut. Meskipun biasanya seseorang hanya akan menggunakan metode reglue Notebook (dijelaskan di bawah).
read_notebook membaca satu buku catatan Membaca objek Notebook yang dimuat dari lokasi yang ditentukan di path . Anda telah melihat bagaimana fungsi ini digunakan dalam contoh panggilan api di atas, namun pada dasarnya fungsi ini memberikan pembungkus tipis pada NotebookNode nbformat dengan kemampuan untuk mengekstrak sisa lembar memo.
nb = sb.read_notebook('notebook.ipynb')Objek Notebook ini mematuhi skema json nbformat, memungkinkan akses ke bidang yang diperlukan.
nb.cells # Sel dari notebooknb.metadatanb.nbformatnb.nbformat_minor
Ada beberapa metode tambahan yang disediakan, sebagian besar diuraikan secara lebih rinci di bawah ini:
nb.scrapsnb.reglue
Abstraksi juga membuat konten tersimpan tersedia sebagai kerangka data yang merujuk pada setiap kunci dan sumber. Lebih banyak metode ini akan tersedia di versi selanjutnya.
# Menghasilkan bingkai data dengan ["name", "data", "encoder", "display", "filename"] sebagai kolomnb.scrap_dataframe # Peringatan: Ini mungkin objek besar jika data atau tampilannya besar
Objek Notebook juga memiliki beberapa fungsi warisan untuk kompatibilitas dengan model objek Notebook papermill. Hasilnya, ini dapat digunakan untuk membaca statistik eksekusi papermill serta abstraksi lembar memo:
nb.cell_timing # Daftar waktu eksekusi sel dalam urutan selnb.execution_counts # Daftar jumlah eksekusi sel dalam sel ordernb.papermill_metrics # Kerangka data jumlah dan waktu eksekusi selnb.papermill_record_dataframe # Kerangka data catatan buku catatan (memo yang hanya berisi data)nb.parameter_dataframe # Kerangka data parameter buku catatannb.papermill_dataframe # Kerangka data parameter buku catatan dan sisa sel
Pembaca buku catatan mengandalkan iorw terdaftar Papermill untuk mengaktifkan akses ke berbagai sumber seperti -- namun tidak terbatas pada -- S3, Azure, dan Google Cloud.
scraps memberikan nama -> pencarian memo Metode scraps memungkinkan akses ke semua memo di buku catatan tertentu.
nb = sb.read_notebook('notebook.ipynb')nb.scraps # Mencetak dict semua memo berdasarkan namaObjek ini juga memiliki beberapa metode tambahan untuk memudahkan konversi dan eksekusi.
nb.scraps.data_scraps # Memfilter hanya untuk memo dengan `data` terkaitnb.scraps.data_dict # Memetakan `data_scraps` ke `nama` -> `data` dictnb.scraps.display_scraps # Memfilter hanya untuk memo dengan `display` terkaitnb. scraps.display_dict # Memetakan `display_scraps` ke `nama` -> `display` dictnb.scraps.dataframe # Menghasilkan kerangka data dengan ["name", "data", "encoder", "display"] sebagai kolom
Metode ini memungkinkan kasus penggunaan sederhana tidak memerlukan penggalian abstraksi model.
reglue menyalin potongan ke dalam buku catatan saat ini Dengan menggunakan reglue seseorang dapat mengambil sisa lem apa pun ke dalam satu buku catatan dan merekatkannya ke buku yang sekarang.
nb = sb.read_notebook('notebook.ipynb')nb.reglue("table_scrap") # Ini menyalin data dan tampilan Setiap data atau informasi tampilan akan disalin kata demi kata ke dalam buku catatan yang sedang dijalankan seolah-olah pengguna memanggil glue lagi pada sumber aslinya.
Dimungkinkan juga untuk mengganti nama memo dalam prosesnya.
nb.reglue("meja_bekas", "meja_bekas_lama") Dan terakhir jika seseorang ingin mencoba merekatkan ulang tanpa memeriksa keberadaannya, raise_on_missing dapat diatur untuk hanya menampilkan pesan kegagalan.
nb.reglue("maybe_missing", raise_on_missing=False)# => "Tidak ditemukan memo dengan nama 'maybe_missing' di buku catatan ini"read_notebooks membaca banyak buku catatan Membaca semua buku catatan yang terletak di path tertentu ke dalam objek Scrapbook.
# buat scrapbook bernama `book`book = sb.read_notebooks('path/to/notebook/collection/')# dapatkan buku catatan yang mendasarinya sebagai listbook.notebooks # Atau `book.values` Jalur ini menggunakan kembali iorw terdaftar Papermill untuk membuat daftar dan membaca file dari berbagai sumber, sehingga url non-lokal dapat memuat data.
# buat scrapbook bernama `book`book = sb.read_notebooks('s3://bucket/key/prefix/to/notebook/collection/') Scrapbook ( book dalam contoh ini) dapat digunakan untuk mengingat semua memo di seluruh koleksi buku catatan:
book.notebook_scraps # Dikt bentuk `notebook` -> (`nama` -> `scrap`)book.scraps # dikt bentuk `nama` yang digabungkan -> `scrap`
scraps_report menampilkan laporan tentang memo yang dikumpulkan Koleksi Scrapbook dapat digunakan untuk menghasilkan scraps_report pada semua memo dari koleksi sebagai keluaran terstruktur penurunan harga.
buku.scraps_report()
Tampilan ini dapat memfilter nama memo dan buku catatan, serta mengaktifkan atau menonaktifkan header keseluruhan untuk tampilan.
book.scraps_report( scrap_names=["scrap1", "scrap2"], notebook_names=["result1"], # cocok dengan `/notebook/collections/result1.ipynb` pathed notebooks tajuk=Salah)
Secara default, laporan hanya akan diisi dengan elemen visual. Untuk juga melaporkan kumpulan elemen data include_data.
buku.scraps_report(include_data=Benar)
Yang terakhir, scrapbook menyediakan dua fitur yang kompatibel untuk kemampuan papermill yang sudah tidak digunakan lagi:
buku.papermill_dataframebook.papermill_metrics
Encoder dapat diakses dengan nama kunci ke objek Encoder yang didaftarkan pada objek encoders.registry . Untuk mendaftarkan pembuat enkode data baru, cukup hubungi:
dari encoder impor registri sebagai encoder_registry# tambahkan encoder ke registryencoder_registry.register("custom_encoder_name", MyCustomEncoder()) Kelas encode harus mengimplementasikan dua metode, encode dan decode :
class MyCustomEncoder(object):def encode(self, scrap):# scrap.data adalah tipe apa pun, biasanya khusus untuk namepass encoder # Mengembalikan `Scrap` dengan `data` ketik salah satu dari [None, list, dict, *six .integer_types, *six.string_types]def decode(self, scrap):# scrap.data adalah salah satu dari [None, list, dict, *six.integer_types, *six.string_types]pass # Mengembalikan `Scrap` dengan tipe `data` sebagai tipe apa pun, biasanya khusus untuk nama pembuat enkode
Ini dapat membaca potongan transformasi menjadi objek json yang mewakili konten atau lokasinya dan memuat string tersebut kembali ke objek data asli.
textFormat penyimpanan string dasar yang menyimpan data sebagai string python.
sb.lem("halo", "dunia", "teks")json sb.lem("foo_json", {"foo": "bar", "baz": 1}, "json")pandas sb.glue("pandas_df",pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]}), "panda")record yang tidak digunakan lagi di Papermill scrapbook menyediakan skema perekaman yang kuat dan fleksibel. Perpustakaan ini menggantikan fungsi record Papermill yang sudah ada.
Dokumentasi untuk record pabrik kertas ada di ReadTheDocs. Singkatnya, fungsi record yang tidak digunakan lagi:
pm.record(name, value) : memungkinkan nilai disimpan dengan notebook [dokumentasi API]
pm.record("halo", "dunia")pm.record("angka", 123)pm.record("some_list", [1, 3, 5])pm.record("some_dict", {"a" : 1, "b": 2}) pm.read_notebook(notebook) : panda nantinya dapat digunakan untuk memulihkan nilai yang direkam dengan membaca buku catatan keluaran ke dalam kerangka data. Misalnya:
nb = pm.read_notebook('notebook.ipynb')nb.dataframerecord Papermill Fungsi record Papermill tidak digunakan lagi karena keterbatasan dan tantangan berikut:
Fungsi record tidak mengikuti pola eksekusi linier sebuah buku catatan seperti pabrik kertas. Rasanya canggung untuk menggambarkan record sebagai fitur tambahan dari pabrik kertas, dan benar-benar terasa seperti menggambarkan perpustakaan kedua yang kurang berkembang.
Merekam/Membaca diperlukan terjemahan data ke JSON untuk semuanya. Ini adalah proses yang membosankan dan menyakitkan untuk kerangka data.
Membaca nilai yang direkam ke dalam kerangka data akan menghasilkan bentuk kerangka data yang tidak intuitif.
Modularitas dan fleksibilitasnya lebih rendah dibandingkan komponen pabrik kertas lainnya di mana operator khusus dapat didaftarkan.
Untuk mengatasi keterbatasan tersebut di Papermill, diambil keputusan untuk membuat Scrapbook .
