scrapbook

álbum de recortes

A biblioteca de scrapbook registra os valores dos dados de um caderno e gera conteúdo visual como "restos". Os recados gravados podem ser lidos posteriormente.

Consulte a documentação do scrapbook para obter mais informações sobre como usar o scrapbook.

Casos de uso

Os usuários de notebook podem desejar registrar dados produzidos durante a execução de um notebook. Esses dados registrados, scraps , podem ser usados ​​posteriormente ou passados ​​em um fluxo de trabalho para outro notebook como entrada.

Ou seja, o álbum de recortes permite:

• persistir dados e conteúdo visual exibidos em um notebook como recados

• recuperar qualquer fragmento de dados persistente

• resumir coleções de cadernos

Suporte à versão Python

O alvo de suporte de longo prazo desta biblioteca é Python 3.6+. Atualmente, ele também oferece suporte ao Python 2.7 até que o Python 2 chegue ao fim de sua vida útil em 2020. Após essa data, o suporte ao Python 2 será interrompido e apenas as versões 3.x serão mantidas.

Instalação

Instale usando pip :

pip install scrapbook

Para instalar dependências de E/S opcionais, você pode especificar pacotes de armazenamento individuais, como s3 ou azure :

pip install scrapbook[s3]

ou use all :

pip install scrapbook[all]

---

Modelos e Terminologia

O Scrapbook define os seguintes itens:

• scraps : valores de dados serializáveis ​​e visualizações, como strings, listas de objetos, dataframes do pandas, gráficos, imagens ou referências de dados.

• notebook : um objeto de notebook nbformat empacotado com métodos extras para interagir com recados.

• scrapbook : coleção de cadernos com interface para tirar dúvidas do acervo.

• codificadores : um tradutor registrado de dados de/para formatos de armazenamento de notebook.

modelo scrap

O modelo scrap abriga alguns atributos principais em uma tupla, incluindo:

• name : O nome do recado

• data : quaisquer dados capturados pela chamada da API do scrapbook

• encoder : O nome do codificador usado para codificar/decodificar dados de/para o notebook

• display : quaisquer dados de exibição usados ​​pelo IPython para exibir conteúdo visual

---

API

O Scrapbook adiciona alguns comandos básicos de API que permitem salvar e recuperar dados, incluindo:

• glue para persistir recados com ou sem saída de exibição

• read_notebook lê um notebook

• scraps fornece um dicionário pesquisável de todos os scraps por nome

• reglue que copia um recado de outro caderno para o caderno atual

• read_notebooks lê muitos notebooks de um determinado caminho

• scraps_report exibe um relatório sobre recados coletados

• papermill_dataframe e papermill_metrics para compatibilidade com versões anteriores de dois recursos obsoletos da fábrica de papel

As seções a seguir fornecem mais detalhes sobre esses comandos de API.

glue para persistir restos

Registra um scrap (dados ou valor de exibição) na célula do notebook fornecida.

A scrap (valor registrado) pode ser recuperada durante a inspeção posterior do caderno de saída.

 """exemplo de cola para registrar valores de dados"""importar scrapbook 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, 'seta')

A biblioteca de scrapbook pode ser usada posteriormente para recuperar scraps do bloco de notas de saída:

 # leia um caderno e obtenha recados gravados anteriormentesnb = sb.read_notebook('notebook.ipynb')nb.scraps

scrapbook implicará no formato de armazenamento pelo tipo de valor de qualquer codificador de dados registrado. Alternativamente, o formato de codificação implícito pode ser substituído definindo o argumento encoder para o nome registrado (por exemplo, "json" ) de um codificador específico.

Esses dados são persistidos gerando uma saída de exibição com um tipo de mídia especial que identifica o formato e os dados de codificação do conteúdo. Essas saídas nem sempre são visíveis na renderização do notebook, mas ainda existem no documento. O Scrapbook pode então reidratar os dados associados ao notebook no futuro, lendo essas saídas de células.

Com saída de exibição

Para exibir um recado nomeado com saídas de exibição visíveis, você precisa indicar que o recado pode ser renderizado diretamente.

Isso pode ser feito alternando o argumento display .

 # grava uma mensagem da UI junto com a entrada stringsb.glue("hello", "Hello World", display=True)

A chamada salvará os dados e os atributos de exibição do objeto Scrap, tornando-o visível e também codificando os dados originais. Isso se baseia na função IPython.core.formatters.format_display_data para traduzir o objeto de dados em um display e ditado de metadados para o kernel do notebook analisar.

Outro padrão que pode ser utilizado é especificar que apenas os dados de exibição devem ser salvos, e não o objeto original. Isto é conseguido configurando o codificador para ser display .

 # grava uma imagem sem a entrada original objectb.glue("sharable_png", IPython.display.Image(filename="sharable.png"), encoder='display')

Finalmente, os tipos de mídia gerados podem ser controlados passando um objeto list, tuple ou dict como argumento de exibição.

 sb.glue("media_as_text_only", media_obj, encoder='display', display=('text/plain',) # Isso passa [text/plain] para o argumento de inclusão de format_display_data)sb.glue("media_without_text", media_obj, encoder ='display', display={'exclude': 'text/plain'} # encaminha para format_display_data's kwargs)

Assim como os recados de dados, eles podem ser recuperados posteriormente acessando o atributo display do recado. Embora normalmente se use apenas o método reglue do Notebook (descrito abaixo).

read_notebook lê um notebook

Lê um objeto Notebook carregado do local especificado em path . Você já viu como essa função é usada nos exemplos de chamada de API acima, mas essencialmente isso fornece um wrapper fino sobre um NotebookNode de nbformat com a capacidade de extrair fragmentos de scrapbook.

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

Este objeto Notebook adere ao esquema json do nbformat, permitindo acesso aos seus campos obrigatórios.

 nb.cells # As células do notebooknb.metadatanb.nbformatnb.nbformat_minor

Existem alguns métodos adicionais fornecidos, a maioria dos quais são descritos com mais detalhes abaixo:

 nb.scrapsnb.reglue

A abstração também disponibiliza o conteúdo salvo como um dataframe referenciando cada chave e fonte. Mais desses métodos serão disponibilizados em versões posteriores.

 # Produz um quadro de dados com ["nome", "dados", "codificador", "display", "nome do arquivo"] como colunasnb.scrap_dataframe # Aviso: Este pode ser um objeto grande se os dados ou a exibição forem grandes

O objeto Notebook também possui algumas funções legadas para compatibilidade retroativa com o modelo de objeto Notebook da fábrica de papel. Como resultado, ele pode ser usado para ler estatísticas de execução de fábricas de papel, bem como abstrações de álbuns de recortes:

 nb.cell_timing # Lista de tempos de execução de células na célula ordernb.execution_counts # Lista de contagens de execução de células na célula ordernb.papermill_metrics # Dataframe de contagens e tempos de execução de célulasnb.papermill_record_dataframe # Dataframe de registros de notebook (sucatas apenas com dados)nb.parameter_dataframe # Dataframe de parâmetros do notebooknb.papermill_dataframe # Dataframe de parâmetros do notebook e restos de células

O leitor de notebook depende do iorw registrado da papermill para permitir o acesso a uma variedade de fontes, como - mas não limitado a - S3, Azure e Google Cloud.

scraps fornece um nome -> pesquisa de scraps

O método scraps permite o acesso a todos os recados de um determinado caderno.

 nb = sb.read_notebook('notebook.ipynb')nb.scraps # Imprime um ditado de todos os recados por nome

Este objeto também possui alguns métodos adicionais para conversão e execução convenientes.

 nb.scraps.data_scraps # Filtra apenas recados com `data` associadonb.scraps.data_dict # Mapeia `data_scraps` para um `nome` -> `data` dictnb.scraps.display_scraps # Filtra apenas recados com `display` associadonb. scraps.display_dict # Mapeia `display_scraps` para um `name` -> `display` dictnb.scraps.dataframe # Gera um dataframe com ["name", "data", "encoder", "display"] como colunas

Esses métodos permitem que casos de uso simples não exijam investigação em abstrações de modelo.

reglue copia um recado para o bloco de notas atual

Usando reglue você pode pegar qualquer pedaço colado em um caderno e colá-lo no atual.

 nb = sb.read_notebook('notebook.ipynb')nb.reglute("table_scrap") # Isso copia os dados e exibe

Quaisquer dados ou informações de exibição serão copiados literalmente no notebook em execução no momento, como se o usuário chamasse glue novamente na fonte original.

Também é possível renomear o recado no processo.

 nb.recolar("sucata_tabela", "sucata_tabela_antiga")

E, finalmente, se alguém quiser tentar re-colar sem verificar a existência, o raise_on_missing pode ser configurado para exibir apenas uma mensagem em caso de falha.

 nb.reglute("maybe_missing", raise_on_missing=False)# => "Nenhum recado encontrado com o nome 'maybe_missing' neste notebook"

read_notebooks lê muitos notebooks

Lê todos os cadernos localizados em um determinado path em um objeto Scrapbook.

 # crie um álbum de recortes chamado `book`book = sb.read_notebooks('path/to/notebook/collection/')# obtenha os cadernos subjacentes como um listbook.notebooks # Ou `book.values`

O caminho reutiliza iorw registrado da fábrica de papel para listar e ler arquivos de várias fontes, de modo que URLs não locais possam carregar dados.

 # crie um álbum de recortes chamado `book`book = sb.read_notebooks('s3://bucket/key/prefix/to/notebook/collection/')

O álbum de recortes ( book neste exemplo) pode ser usado para recuperar todos os recados da coleção de cadernos:

 book.notebook_scraps # Ditado da forma `notebook` -> (`name` -> `scrap`)book.scraps # ditado mesclado da forma `name` -> `scrap`

scraps_report exibe um relatório sobre recados coletados

A coleção Scrapbook pode ser usada para gerar um scraps_report em todos os recados da coleção como uma saída estruturada de redução.

 livro.scraps_report()

Esta exibição pode filtrar nomes de recados e cadernos, bem como ativar ou desativar um cabeçalho geral para a exibição.

 book.scraps_report( scrap_names=["scrap1", "scrap2"], notebook_names=["result1"], # corresponde aos notebooks com caminho `/notebook/collections/result1.ipynb`
  cabeçalho=Falso)

Por padrão, o relatório será preenchido apenas com elementos visuais. Para também relatar sobre elementos de dados, defina include_data.

 livro.scraps_report(include_data=True)

suporte para fábrica de papel

Finalmente, o álbum de recortes fornece dois recursos compatíveis com versões anteriores para recursos obsoletos papermill :

 livro.papermill_dataframebook.papermill_metrics

Codificadores

Os codificadores são acessíveis por nomes de chaves para objetos Encoder registrados no objeto encoders.registry . Para registrar novos codificadores de dados basta ligar:

 do registro de importação do codificador como encoder_registry# adicione o codificador ao registroencoder_registry.register("custom_encoder_name", MyCustomEncoder())

A classe encode deve implementar dois métodos, encode e decode :

 class MyCustomEncoder(object):def encode(self, scrap):# scrap.data é qualquer tipo, geralmente específico para o codificador namepass # Retorna um `Scrap` com `data` tipo um de [None, list, dict, *six .integer_types, *six.string_types]def decode(self, scrap):# scrap.data é um de [None, list, dict, *six.integer_types, *six.string_types]pass # Retorna um `Scrap` com o tipo `data` como qualquer tipo, geralmente específico para o nome do codificador

Isso pode ler fragmentos de transformação em um objeto JSON representando seu conteúdo ou localização e carregar essas strings de volta nos objetos de dados originais.

text

Um formato básico de armazenamento de strings que salva dados como strings python.

 sb.glue("olá", "mundo", "texto")

json

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

pandas

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

recurso record obsoleto da papermill

scrapbook fornece um esquema de gravação robusto e flexível. Esta biblioteca substitui a funcionalidade record existente da Papermill.

A documentação para record da fábrica de papel existe em ReadTheDocs. Em resumo, a função record obsoleta:

pm.record(name, value) : permite que valores sejam salvos com o notebook [documentação da API]

 pm.record("olá", "mundo")pm.record("número", 123)pm.record("alguma_lista", [1, 3, 5])pm.record("algum_dict", {"a" : 1, "b": 2})

pm.read_notebook(notebook) : o pandas pode ser usado posteriormente para recuperar valores registrados lendo o notebook de saída em um dataframe. Por exemplo:

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

Justificativa para a descontinuação record da Papermill

A função record da Papermill foi descontinuada devido a estas limitações e desafios:

• A função record não seguia o padrão de execução linear de um caderno da fábrica de papel. Foi estranho descrever record como um recurso adicional da fábrica de papel e tive vontade de descrever uma segunda biblioteca menos desenvolvida.

• A gravação/leitura exigia tradução de dados para JSON para tudo. Este é um processo tedioso e doloroso para dataframes.

• A leitura de valores registrados em um dataframe resultaria em formatos de dataframe não intuitivos.

• Menos modularidade e flexibilidade do que outros componentes da fábrica de papel onde operadores personalizados podem ser registrados.

Para superar essas limitações na Papermill, foi tomada a decisão de criar o Scrapbook .