scrapbook

سجل القصاصات

تسجل مكتبة سجل القصاصات قيم بيانات دفتر الملاحظات وتولد المحتوى المرئي على شكل "قصاصات". يمكن قراءة القصاصات المسجلة في وقت لاحق.

راجع وثائق سجل القصاصات للحصول على مزيد من المعلومات حول كيفية استخدام سجل القصاصات.

حالات الاستخدام

قد يرغب مستخدمو الكمبيوتر المحمول في تسجيل البيانات التي تم إنتاجها أثناء تنفيذ الكمبيوتر المحمول. يمكن استخدام هذه البيانات المسجلة، القصاصات ، في وقت لاحق أو تمريرها في سير العمل إلى دفتر ملاحظات آخر كمدخل.

وهي أن سجل القصاصات يتيح لك:

• يتم عرض البيانات المستمرة والمحتوى المرئي في دفتر الملاحظات كقصاصات

• تذكر أي قصاصة مستمرة من البيانات

• تلخيص مجموعات من الدفاتر

دعم إصدار بايثون

هدف الدعم طويل المدى لهذه المكتبة هو Python 3.6+. وهو يدعم حاليًا أيضًا Python 2.7 حتى يصل Python 2 إلى نهاية عمره في عام 2020. وبعد هذا التاريخ، سيتوقف دعم Python 2، وسيتم الاحتفاظ بإصدارات 3.x فقط.

تثبيت

التثبيت باستخدام pip :

pip install scrapbook

لتثبيت تبعيات الإدخال والإخراج الاختيارية، يمكنك تحديد حزم المتجر الفردية، مثل s3 أو azure :

pip install scrapbook[s3]

أو استخدم all :

pip install scrapbook[all]

---

النماذج والمصطلحات

يحدد سجل القصاصات العناصر التالية:

• القصاصات : قيم البيانات والمرئيات القابلة للتسلسل مثل السلاسل أو قوائم الكائنات أو إطارات بيانات الباندا أو المخططات أو الصور أو مراجع البيانات.

• دفتر الملاحظات : كائن دفتر ملاحظات بتنسيق nbformat مع طرق إضافية للتفاعل مع القصاصات.

• سجل القصاصات : مجموعة من دفاتر الملاحظات مع واجهة لطرح الأسئلة الخاصة بالمجموعة.

• أجهزة التشفير : مترجم مسجل للبيانات من/إلى تنسيقات تخزين أجهزة الكمبيوتر المحمولة.

نموذج scrap

يحتوي نموذج scrap على بعض السمات الرئيسية في صف، بما في ذلك:

• الاسم : اسم الخردة

• البيانات : أي بيانات تم التقاطها بواسطة استدعاء واجهة برمجة تطبيقات سجل القصاصات

• أداة التشفير : اسم أداة التشفير المستخدمة لتشفير/فك تشفير البيانات من/إلى الكمبيوتر الدفتري

• العرض : أي بيانات عرض يستخدمها IPython لعرض المحتوى المرئي

---

واجهة برمجة التطبيقات

يضيف Scrapbook بعض أوامر واجهة برمجة التطبيقات الأساسية التي تتيح حفظ البيانات واسترجاعها بما في ذلك:

• 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، 'arrow')

يمكن استخدام مكتبة سجل القصاصات لاحقًا لاستعادة scraps من دفتر الملاحظات الناتج:

 # اقرأ دفتر ملاحظات واحصل على القصاصات المسجلة مسبقًا = sb.read_notebook('notebook.ipynb')nb.scraps

سيشير سجل القصاصات إلى تنسيق التخزين حسب نوع القيمة لأي برامج تشفير بيانات مسجلة. وبدلاً من ذلك، يمكن استبدال تنسيق التشفير الضمني عن طريق ضبط وسيطة encoder على الاسم المسجل (على سبيل المثال "json" ) لبرنامج تشفير معين.

يتم الحفاظ على هذه البيانات عن طريق إنشاء مخرجات عرض بنوع وسائط خاص يحدد تنسيق وبيانات ترميز المحتوى. لا تكون هذه المخرجات مرئية دائمًا في عرض دفتر الملاحظات ولكنها تظل موجودة في المستند. يمكن لسجل القصاصات بعد ذلك إعادة ترطيب البيانات المرتبطة بدفتر الملاحظات في المستقبل من خلال قراءة مخرجات الخلية هذه.

مع إخراج العرض

لعرض قصاصة مسماة مع مخرجات عرض مرئية، يجب الإشارة إلى أن القصاصة قابلة للعرض مباشرة.

يمكن القيام بذلك عن طريق تبديل وسيطة display .

 # تسجيل رسالة واجهة المستخدم مع الإدخال stringsb.glue("hello", "Hello World",display=True)

سيؤدي الاستدعاء إلى حفظ البيانات وسمات العرض الخاصة بكائن Scrap، مما يجعله مرئيًا بالإضافة إلى تشفير البيانات الأصلية. يعتمد هذا على وظيفة IPython.core.formatters.format_display_data لترجمة كائن البيانات إلى شاشة عرض وإملاء بيانات التعريف لنواة دفتر الملاحظات لتحليلها.

النمط الآخر الذي يمكن استخدامه هو تحديد أنه يجب حفظ بيانات العرض فقط ، وليس الكائن الأصلي. يتم تحقيق ذلك عن طريق ضبط جهاز التشفير الذي سيتم display .

 # تسجيل صورة بدون كائنات الإدخال الأصليةb.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',) # يؤدي هذا إلى تمرير [نص/عادي] إلى وسيطة تضمين format_display_data)sb.glue("media_without_text"، media_obj، encoder ='display', Display={'exclude': 'text/plain'} # إعادة التوجيه إلى format_display_data's كوارجس)

مثل قصاصات البيانات، يمكن استرجاعها في وقت لاحق من خلال الوصول إلى سمة display القصاصة. على الرغم من أنه عادةً ما يستخدم المرء طريقة reglue دفتر الملاحظات (الموصوفة أدناه).

read_notebook يقرأ دفتر ملاحظات واحد

يقرأ كائن دفتر الملاحظات الذي تم تحميله من الموقع المحدد في path . لقد رأيت بالفعل كيفية استخدام هذه الوظيفة في أمثلة استدعاء واجهة برمجة التطبيقات المذكورة أعلاه، ولكن هذا يوفر بشكل أساسي غلافًا رفيعًا فوق NotebookNode الخاص بـ nbformat مع القدرة على استخراج قصاصات سجل القصاصات.

 ملحوظة: sb.read_notebook('notebook.ipynb')

يلتزم كائن Notebook هذا بمخطط json الخاص بتنسيق nbformat، مما يسمح بالوصول إلى الحقول المطلوبة.

 nb.cells # الخلايا من دفتر الملاحظاتnb.metadatanb.nbformatnb.nbformat_minor

هناك بعض الطرق الإضافية المتوفرة، معظمها موضح بمزيد من التفصيل أدناه:

 nb.scrapsnb.reglue

يجعل التجريد أيضًا المحتوى المحفوظ متاحًا كإطار بيانات يشير إلى كل مفتاح ومصدر. سيتم توفير المزيد من هذه الأساليب في الإصدارات اللاحقة.

 # إنتاج إطار بيانات يحتوي على ["name"، "data"، "encoder"، "display"، "filename"] كـ columnsnb.scrap_dataframe # تحذير: قد يكون هذا كائنًا كبيرًا إذا كانت البيانات أو العرض كبيرًا

يحتوي كائن Notebook أيضًا على بعض الوظائف القديمة للتوافق مع الإصدارات السابقة مع نموذج كائن Notebook الخاص بمطحنة الورق. ونتيجة لذلك، يمكن استخدامه لقراءة إحصائيات تنفيذ مصنع الورق بالإضافة إلى تجريدات سجل القصاصات:

 nb.cell_timing # قائمة توقيت تنفيذ الخلية في ترتيب الخلية ordernb.execution_counts # قائمة عدد تنفيذ الخلية في ترتيب الخلية ordernb.papermill_metrics # إطار بيانات عدد تنفيذ الخلية وtimesnb.papermill_record_dataframe # إطار بيانات سجلات دفتر الملاحظات (قصاصات تحتوي على بيانات فقط)nb.parameter_dataframe # إطار بيانات معلمات دفتر الملاحظاتnb.papermill_dataframe # إطار بيانات معلمات دفتر الملاحظات وقصاصات الخلايا

يعتمد قارئ أجهزة الكمبيوتر المحمولة على iorw المسجل لدى شركة Papermill لتمكين الوصول إلى مجموعة متنوعة من المصادر مثل - على سبيل المثال لا الحصر - S3 وAzure وGoogle Cloud.

توفر scraps اسمًا -> البحث عن الخردة

تسمح طريقة scraps بالوصول إلى كافة القصاصات الموجودة في دفتر ملاحظات معين.

 nb = sb.read_notebook('notebook.ipynb')nb.scraps # يطبع إملاءًا لجميع القصاصات بالاسم

يحتوي هذا الكائن على بعض الطرق الإضافية أيضًا للتحويل والتنفيذ المريح.

 nb.scraps.data_scraps # يقوم بالتصفية إلى القصاصات ذات `البيانات` المرتبطة فقط بـnb.scraps.data_dict # يعين `data_scraps` إلى `اسم` -> `بيانات` dictnb.scraps.display_scraps # يقوم بالتصفية إلى القصاصات ذات `العرض` المرتبطة بـnb فقط. سكرابز.ديسبلاي_ديكت # يُعيِّن `display_scraps` إلى `اسم` -> `display` dictnb.scraps.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")

وأخيرًا، إذا رغب أحد في محاولة إعادة اللصق دون التحقق من وجوده، فيمكن ضبط raise_on_missing لعرض رسالة عند الفشل فقط.

 nb.reglue("maybe_missing", rise_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` -> (`name` -> `scrap`)book.scraps # إملاء الشكل المدمج `name` -> `scrap`

يعرض scraps_report تقريرًا حول القصاصات المجمعة

يمكن استخدام مجموعة Scrapbook لإنشاء scraps_report على جميع القصاصات من المجموعة كمخرج منظم لتخفيض السعر.

 book.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

التشفير

يمكن الوصول إلى أدوات التشفير عن طريق أسماء المفاتيح لكائنات التشفير المسجلة مقابل كائن encoders.registry . لتسجيل أجهزة تشفير البيانات الجديدة، ما عليك سوى الاتصال بـ:

 من سجل استيراد برنامج التشفير باسم encoder_registry# أضف برنامج التشفير إلى السجلencoder_registry.register("custom_encoder_name", MyCustomEncoder())

يجب أن تنفذ فئة التشفير طريقتين، encode decode :

 class MyCustomEncoder(object):def encode(self, سكراب):# سكراب. البيانات هي أي نوع، عادةً ما تكون خاصة بكلمة مرور برنامج التشفير # قم بإرجاع "Scrap" مع "بيانات" النوع الأول من [None, list, dict, *six .integer_types, *six.string_types]def decode(self,scrap):#scrap.data هي واحدة من [None, list, dict, *six.integer_types, *six.string_types]pass # قم بإرجاع `Scrap` بنوع `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 المهملة في مصنع الورق

يوفر سجل القصاصات مخطط تسجيل قوي ومرن. تحل هذه المكتبة محل وظيفة record الموجودة في مصنع الورق.

توجد وثائق record مصنع الورق على ReadTheDocs. باختصار، وظيفة record المهملة:

pm.record(name, value) : يتيح حفظ القيم في دفتر الملاحظات [وثائق API]

 مساءً.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) : يمكن استخدام الباندا لاحقًا لاستعادة القيم المسجلة عن طريق قراءة دفتر الملاحظات الناتج في إطار البيانات. على سبيل المثال:

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

الأساس المنطقي لإهمال record Papermill

تم إهمال وظيفة record في Papermill بسبب هذه القيود والتحديات:

• لم تتبع وظيفة record نمط مصنع الورق للتنفيذ الخطي لجهاز الكمبيوتر المحمول. كان من المحرج وصف record كميزة إضافية لمصنع الورق، وشعرت حقًا بوصف مكتبة ثانية أقل تطورًا.

• يتطلب التسجيل/القراءة ترجمة البيانات إلى JSON لكل شيء. هذه عملية شاقة ومؤلمة لإطارات البيانات.

• قد تؤدي قراءة القيم المسجلة في إطار بيانات إلى أشكال غير بديهية لإطار البيانات.

• نمطية ومرونة أقل من مكونات مصنع الورق الأخرى حيث يمكن تسجيل المشغلين المخصصين.

للتغلب على هذه القيود في Papermill، تم اتخاذ قرار بإنشاء Scrapbook .