scrapbook

álbum de recortes

La biblioteca de álbumes de recortes registra los valores de datos de un cuaderno y genera contenido visual como "recortes". Los fragmentos grabados se pueden leer en el futuro.

Consulte la documentación del álbum de recortes para obtener más información sobre cómo utilizar el álbum de recortes.

Casos de uso

Es posible que los usuarios de portátiles deseen registrar los datos producidos durante la ejecución de un portátil. Estos datos grabados, borradores , se pueden utilizar más adelante o pasar en un flujo de trabajo a otro cuaderno como entrada.

Es decir, el álbum de recortes te permite:

• conservar los datos y el contenido visual en un cuaderno como borradores

• recuperar cualquier fragmento de datos persistente

• resumir colecciones de cuadernos

Soporte de versión Python

El objetivo de soporte a largo plazo de esta biblioteca es Python 3.6+. Actualmente también es compatible con Python 2.7 hasta que Python 2 llegue al final de su vida útil en 2020. Después de esta fecha, el soporte de Python 2 se detendrá y solo se mantendrán las versiones 3.x.

Instalación

Instalar usando pip :

pip install scrapbook

Para instalar dependencias de IO opcionales, puede especificar paquetes de tiendas individuales, como s3 o azure :

pip install scrapbook[s3]

o usar all :

pip install scrapbook[all]

---

Modelos y terminología

Scrapbook define los siguientes elementos:

• scraps : valores de datos serializables y visualizaciones como cadenas, listas de objetos, marcos de datos de pandas, gráficos, imágenes o referencias de datos.

• cuaderno : un objeto de cuaderno envuelto en formato nb con métodos adicionales para interactuar con los borradores.

• álbum de recortes : una colección de cuadernos con una interfaz para hacer preguntas sobre la colección.

• codificadores : un traductor registrado de datos hacia/desde formatos de almacenamiento de portátiles.

modelo scrap

El modelo scrap alberga algunos atributos clave en una tupla, que incluyen:

• nombre : El nombre del chatarra

• datos : cualquier dato capturado por la llamada a la API del álbum de recortes.

• codificador : El nombre del codificador utilizado para codificar/decodificar datos hacia/desde el portátil

• display : Cualquier dato de visualización utilizado por IPython para mostrar contenido visual.

---

API

Scrapbook agrega algunos comandos básicos de API que permiten guardar y recuperar datos, incluidos:

• glue para conservar restos con o sin salida de pantalla

• read_notebook lee un cuaderno

• scraps proporciona un diccionario de búsqueda de todos los scraps por nombre

• reglue que copia un fragmento de otro cuaderno al cuaderno actual

• read_notebooks lee muchos cuadernos de una ruta determinada

• scraps_report muestra un informe sobre los desechos recopilados

• papermill_dataframe y papermill_metrics para compatibilidad con versiones anteriores de dos funciones obsoletas de la fábrica de papel

Las siguientes secciones proporcionan más detalles sobre estos comandos de API.

glue para persistir restos

Registra un scrap (datos o valor de visualización) en la celda del cuaderno dada.

El scrap (valor registrado) se puede recuperar durante una inspección posterior del cuaderno de salida.

 """Ejemplo de pegamento para registrar valores de datos"""importar álbum de recortes como 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, 'flecha')

La biblioteca de álbumes de recortes se puede utilizar más adelante para recuperar scraps del cuaderno de salida:

 # leer un cuaderno y obtener recortes grabados previamentenb = sb.read_notebook('notebook.ipynb')nb.scraps

álbum de recortes implicará el formato de almacenamiento por el tipo de valor de cualquier codificador de datos registrado. Alternativamente, el formato de codificación implícito se puede sobrescribir estableciendo el argumento encoder en el nombre registrado (por ejemplo, "json" ) de un codificador en particular.

Estos datos se conservan generando una salida de visualización con un tipo de medio especial que identifica el formato de codificación del contenido y los datos. Estos resultados no siempre son visibles en la representación del cuaderno, pero aún existen en el documento. Luego, Scrapbook puede rehidratar los datos asociados con el cuaderno en el futuro leyendo estos resultados de celda.

Con salida de pantalla

Para mostrar un fragmento con nombre con resultados de visualización visibles, debe indicar que el fragmento se puede renderizar directamente.

Esto se puede hacer alternando el argumento display .

 # grabar un mensaje de UI junto con la entrada stringsb.glue("hello", "Hello World", display=True)

La llamada guardará los datos y los atributos de visualización del objeto Scrap, haciéndolo visible y codificando los datos originales. Esto se apoya en la función IPython.core.formatters.format_display_data para traducir el objeto de datos en una pantalla y un dictado de metadatos para que el kernel del portátil lo analice.

Otro patrón que se puede utilizar es especificar que solo se deben guardar los datos de visualización y no el objeto original. Esto se logra configurando el codificador para que se display .

 # grabar una imagen sin los objetos de entrada originalesb.glue("sharable_png", IPython.display.Image(filename="sharable.png"), encoder='display')

Finalmente, los tipos de medios que se generan se pueden controlar pasando un objeto de lista, tupla o dict como argumento de visualización.

 sb.glue("media_as_text_only", media_obj, encoder='display', display=('text/plain',) # Esto pasa [text/plain] al argumento de inclusión de format_display_data)sb.glue("media_ without_text", media_obj, encoder ='display', display={'exclude': 'text/plain'} # reenviar a format_display_data kwargs)

Al igual que los fragmentos de datos, estos se pueden recuperar más adelante accediendo al atributo display del fragmento. Aunque normalmente uno simplemente usará el método de reglue de Notebook (descrito a continuación).

read_notebook lee un cuaderno

Lee un objeto Notebook cargado desde la ubicación especificada en path . Ya ha visto cómo se usa esta función en los ejemplos de llamadas a la API anteriores, pero esencialmente esto proporciona un contenedor delgado sobre un NotebookNode de nbformat con la capacidad de extraer fragmentos de álbumes de recortes.

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

Este objeto Notebook se adhiere al esquema json del formato nb, lo que permite el acceso a sus campos obligatorios.

 nb.cells # Las celdas del cuadernonb.metadatanb.nbformatnb.nbformat_minor

Se proporcionan algunos métodos adicionales, la mayoría de los cuales se describen con más detalle a continuación:

 nb.scrapsnb.reglue

La abstracción también hace que el contenido guardado esté disponible como un marco de datos que hace referencia a cada clave y fuente. Más de estos métodos estarán disponibles en versiones posteriores.

 # Produce un marco de datos con ["name", "data", "encoder", "display", "filename"] como columnsnb.scrap_dataframe # Advertencia: Este podría ser un objeto grande si los datos o la visualización son grandes

El objeto Notebook también tiene algunas funciones heredadas para compatibilidad con versiones anteriores del modelo de objetos Notebook de Papermill. Como resultado, se puede utilizar para leer estadísticas de ejecución de la fábrica de papel, así como abstracciones de álbumes de recortes:

 nb.cell_timing # Lista de tiempos de ejecución de celdas en orden de celdas nb.execution_counts # Lista de recuentos de ejecución de celdas en orden de celdas nb.papermill_metrics # Marco de datos de recuentos y tiempos de ejecución de celdas nb.papermill_record_dataframe # Marco de datos de registros del cuaderno (restos con solo datos) nb.parameter_dataframe # Marco de datos de los parámetros del cuadernonb.papermill_dataframe # Marco de datos de los parámetros del cuaderno y restos de celdas

El lector de portátiles se basa en el iow registrado de Papermill para permitir el acceso a una variedad de fuentes como, entre otras, S3, Azure y Google Cloud.

scraps proporciona un nombre -> búsqueda de scrap

El método scraps permite el acceso a todos los recortes de un cuaderno en particular.

 nb = sb.read_notebook('notebook.ipynb')nb.scraps # Imprime un dictado de todos los borradores por nombre

Este objeto también tiene algunos métodos adicionales para una conversión y ejecución convenientes.

 nb.scraps.data_scraps # Filtra solo para borradores con `datos` asociadosnb.scraps.data_dict # Asigna `data_scraps` a un `nombre` -> `data` dictnb.scraps.display_scraps # Filtra solo para borradores con `display` asociadonb. scraps.display_dict # Asigna `display_scraps` a un `nombre` -> `display` dictnb.scraps.dataframe # Genera un marco de datos con ["nombre", "datos", "codificador", "display"] como columnas

Estos métodos permiten casos de uso simples que no requieren profundizar en las abstracciones del modelo.

reglue copia un borrador en el cuaderno actual

Usando reglue uno puede tomar cualquier resto de pegamento en un cuaderno y pegarlo en el actual.

 nb = sb.read_notebook('notebook.ipynb')nb.reglue("table_scrap") # Esto copia los datos y muestra

Cualquier dato o información mostrada se copiará palabra por palabra en el cuaderno que se está ejecutando actualmente como si el usuario volviera a llamar glue en la fuente original.

También es posible cambiar el nombre del fragmento en el proceso.

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

Y finalmente, si uno desea intentar volver a pegar sin verificar su existencia, se puede configurar raise_on_missing para que solo muestre un mensaje en caso de falla.

 nb.reglue("maybe_missing", rise_on_missing=False)# => "No se encontró ningún fragmento con el nombre 'maybe_missing' en este cuaderno"

read_notebooks lee muchos cuadernos

Lee todos los cuadernos ubicados en una path determinada en un objeto Scrapbook.

 # crear un álbum de recortes llamado `book`book = sb.read_notebooks('path/to/notebook/collection/')# obtener los cuadernos subyacentes como listbook.notebooks # O `book.values`

La ruta reutiliza iorw registrado de la fábrica de papel para enumerar y leer archivos de varias fuentes, de modo que las URL no locales puedan cargar datos.

 # crear un álbum de recortes llamado `book`book = sb.read_notebooks('s3://bucket/key/prefix/to/notebook/collection/')

El Álbum de recortes ( book en este ejemplo) se puede utilizar para recuperar todos los recortes de la colección de cuadernos:

 book.notebook_scraps # dictado de forma `notebook` -> (`nombre` -> `scrap`)book.scraps # dictado fusionado de forma `nombre` -> `scrap`

scraps_report muestra un informe sobre los desechos recopilados

La colección Scrapbook se puede utilizar para generar un scraps_report en todos los desechos de la colección como una salida estructurada de rebajas.

 libro.scraps_report()

Esta visualización puede filtrar por nombres de borradores y cuadernos, así como habilitar o deshabilitar un encabezado general para la visualización.

 book.scraps_report( scrap_names=["scrap1", "scrap2"], notebook_names=["result1"], # coincide con `/notebook/collections/result1.ipynb` cuadernos con ruta
  encabezado = Falso)

De forma predeterminada, el informe solo se completará con elementos visuales. Para informar también sobre elementos de datos, establezca include_data.

 libro.scraps_report(include_data=True)

soporte de fábrica de papel

Finalmente, el álbum de recortes proporciona dos funciones compatibles con versiones anteriores de capacidades obsoletas papermill :

 libro.papermill_dataframebook.papermill_metrics

Codificadores

Se puede acceder a los codificadores mediante nombres de clave para los objetos Encoder registrados en el objeto encoders.registry . Para registrar nuevos codificadores de datos simplemente llame:

 desde el registro de importación del codificador como encoder_registry# agregue el codificador al registroencoder_registry.register("custom_encoder_name", MyCustomEncoder())

La clase de codificación debe implementar dos métodos, encode y decode :

 clase MyCustomEncoder(object):def encode(self, scrap):# scrap.data es de cualquier tipo, generalmente específico del nombre del codificador # Devuelve un `Scrap` con `data` tipo uno de [Ninguno, list, dict, *six .integer_types, *six.string_types]def decode(self, scrap):# scrap.data es uno de [Ninguno, lista, dict, *six.integer_types, *six.string_types]pass # Devuelve un `Scrap` con el tipo `data` como cualquier tipo, generalmente específico del nombre del codificador

Esto puede leer, transformar fragmentos en un objeto json que represente su contenido o ubicación y cargar esas cadenas nuevamente en los objetos de datos originales.

text

Un formato de almacenamiento de cadenas básico que guarda datos como cadenas de Python.

 sb.glue("hola", "mundo", "texto")

json

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

pandas

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

característica record obsoleta de la fábrica de papel

Scrapbook proporciona un esquema de grabación sólido y flexible. Esta biblioteca reemplaza la funcionalidad record existente de la fábrica de papel.

La documentación para record de la fábrica de papel existe en ReadTheDocs. En resumen, la función record obsoleta:

pm.record(name, value) : permite guardar valores con el cuaderno [documentación API]

 pm.record("hola", "mundo")pm.record("número", 123)pm.record("alguna_lista", [1, 3, 5])pm.record("algún_dict", {"a" : 1, "b": 2})

pm.read_notebook(notebook) : los pandas podrían usarse más adelante para recuperar los valores registrados leyendo el cuaderno de salida en un marco de datos. Por ejemplo:

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

Justificación de la desaprobación record de Papermill

La función record de Papermill quedó obsoleta debido a estas limitaciones y desafíos:

• La función record no siguió el patrón de ejecución lineal de un cuaderno de la fábrica de papel. Fue incómodo describir record como una característica adicional de la fábrica de papel, y realmente sentí como si describiera una segunda biblioteca menos desarrollada.

• La grabación/lectura requirió traducción de datos a JSON para todo. Este es un proceso tedioso y doloroso para los marcos de datos.

• Leer los valores registrados en un marco de datos daría como resultado formas de marco de datos poco intuitivas.

• Menos modularidad y flexibilidad que otros componentes de la fábrica de papel donde se pueden registrar operadores personalizados.

Para superar estas limitaciones en Papermill, se tomó la decisión de crear Scrapbook .