scrapbook

альбом для вырезок

Библиотека вырезок записывает значения данных записной книжки и созданный визуальный контент как «записки». Записанные записки можно будет прочитать в будущем.

Дополнительную информацию о том, как использовать альбом, смотрите в документации альбома.

Варианты использования

Пользователи ноутбуков могут захотеть записывать данные, полученные во время выполнения блокнота. Эти записанные данные, записки , можно использовать позже или передать в рабочем процессе в другой блокнот в качестве входных данных.

А именно, альбом позволяет:

• сохранять данные и визуальный контент в записной книжке в виде записок

• вспомнить любой сохранившийся обрывок данных

• обобщить коллекции тетрадей

Поддержка версий Python

Целью долгосрочной поддержки этой библиотеки является 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]

---

Модели и терминология

Scrapbook определяет следующие элементы:

• записки : сериализуемые значения данных и визуализации, такие как строки, списки объектов, фреймы данных pandas, диаграммы, изображения или ссылки на данные.

• блокнот : обернутый объект блокнота nbformat с дополнительными методами для взаимодействия с записками.

• Scrapbook : коллекция блокнотов с интерфейсом для задания вопросов по коллекции.

• кодировщики : зарегистрированный переводчик данных в/из форматов хранения ноутбуков.

модель scrap

Модель scrap содержит несколько ключевых атрибутов в кортеже, в том числе:

• name : Название записки

• data : любые данные, полученные вызовом API Scrapbook.

• кодировщик : имя кодировщика, используемого для кодирования/декодирования данных в/из записной книжки.

• display : любые данные отображения, используемые IPython для отображения визуального контента.

---

API

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

Scrapbook будет подразумевать формат хранения по типу значения любых зарегистрированных кодировщиков данных. Альтернативно, подразумеваемый формат кодирования можно перезаписать, установив в качестве аргумента encoder зарегистрированное имя (например, "json" ) конкретного кодировщика.

Эти данные сохраняются путем создания вывода на дисплей со специальным типом носителя, определяющим формат кодирования контента и данные. Эти выходные данные не всегда видны при рендеринге блокнота, но все же существуют в документе. Scrapbook может затем регидратировать данные, связанные с блокнотом, в будущем, считывая выходные данные ячеек.

С выходом на дисплей

Чтобы отобразить именованный фрагмент с видимыми выходными данными, вам необходимо указать, что этот фрагмент можно напрямую визуализировать.

Это можно сделать, переключив аргумент 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',) # Это передает [text/plain] в аргумент включения format_display_data)sb.glue("media_without_text", media_obj, encoder ='display', display={'exclude': 'text/plain'} # пересылаем в format_display_data кварги)

Как и фрагменты данных, их можно получить позже, обратившись к атрибуту display фрагмента. Хотя обычно можно просто использовать метод reglue Notebook (описанный ниже).

read_notebook читает одну записную книжку

Считывает объект Notebook, загруженный из местоположения, указанного в path . Вы уже видели, как эта функция используется в приведенных выше примерах вызовов API, но по сути это обеспечивает тонкую оболочку над NotebookNode nbformat с возможностью извлечения записок.

 nb = 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 # Кадр данных с количеством и временем выполнения ячеек nb.papermill_record_dataframe # Кадр данных записей блокнота (обрывки только с данными)nb.parameter_dataframe # Кадр данных параметров блокнота nb.papermill_dataframe # Кадр данных параметров блокнота и остатков ячеек

Устройство чтения записных книжек использует зарегистрированный iorw бумажной фабрики для обеспечения доступа к различным источникам, таким как, помимо прочего, S3, Azure и Google Cloud.

scraps предоставляют имя -> поиск записок

Метод scraps позволяет получить доступ ко всем запискам в конкретной записной книжке.

 nb = sb.read_notebook('notebook.ipynb')nb.scraps # Печатает список всех записок по имени

Этот объект также имеет несколько дополнительных методов для удобного преобразования и выполнения.

 nb.scraps.data_scraps # Фильтрует только записки с `data` Associatenb.scraps.data_dict # Сопоставляет `data_scraps` с `name` -> `data` dictnb.scraps.display_scraps # Фильтрует только записки с `display` Associatednb. Scraps.display_dict # Сопоставляет `display_scraps` с `name` -> `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", raise_on_missing=False)# => "В этом блокноте не найдено записок с именем 'maybe_missing'"

read_notebooks читает много блокнотов

Считывает все блокноты, расположенные по заданному path в объект Scrapbook.

 # создаем альбом с именем `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

Кодеры

Кодировщики доступны по именам ключей для объектов Encoder, зарегистрированных для объекта encoders.registry . Чтобы зарегистрировать новые кодировщики данных, просто вызовите:

 из реестра импорта кодировщика как encoder_registry# добавить кодировщик в реестрencoder_registry.register("custom_encoder_name", MyCustomEncoder())

Класс encode должен реализовывать два метода: encode и decode :

 class MyCustomEncoder(object):def encode(self, Scrap):# Scrap.data имеет любой тип, обычно специфичный для namepass кодировщика # Возвращает `Scrap` с типом `data` одного из [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

Базовый формат хранения строк, который сохраняет данные в виде строк Python.

 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 бумажной фабрики

Scrapbook обеспечивает надежную и гибкую схему записи. Эта библиотека заменяет существующие функции record бумажной фабрики.

Документация по record бумажной фабрики доступна на ReadTheDocs. Вкратце, устаревшая функция record :

pm.record(name, value) : позволяет сохранять значения в записной книжке [документация API]

 pm.record("привет", "мир")pm.record("number", 123)pm.record("some_list", [1, 3, 5])pm.record("some_dict", {"a" : 1, "б": 2})

pm.read_notebook(notebook) : pandas можно использовать позже для восстановления записанных значений путем чтения выходного блокнота в фрейм данных. Например:

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

Обоснование устаревания record Papermill

Функция record Papermill устарела из-за следующих ограничений и проблем:

• Функция record не следовала шаблону линейного исполнения блокнота, принятому на бумажной фабрике. Было неловко описывать record как дополнительную функцию бумажной фабрики, и мне действительно хотелось описать вторую, менее развитую библиотеку.

• Для записи/чтения для всего требовался перевод данных в JSON. Это утомительный и болезненный процесс для фреймов данных.

• Чтение записанных значений в фрейм данных приведет к неинтуитивным формам фрейма данных.

• Меньшая модульность и гибкость, чем у других компонентов бумажной фабрики, где можно зарегистрировать индивидуальных операторов.

Чтобы преодолеть эти ограничения в Papermill, было принято решение создать Scrapbook .