papermill

papermill é uma ferramenta para parametrizar, executar e analisar Jupyter Notebooks.

Papermill permite que você:

• parametrizar notebooks
• executar cadernos

Isso abre novas oportunidades de como os notebooks podem ser usados. Por exemplo:

• Talvez você tenha um relatório financeiro que deseja gerar com valores diferentes no primeiro ou último dia de um mês ou no início ou final do ano, o uso de parâmetros facilita essa tarefa.
• Você deseja executar um notebook e dependendo dos resultados, escolher um notebook específico para executar em seguida? Agora você pode executar programaticamente um fluxo de trabalho sem precisar copiar e colar manualmente de um bloco de anotações para outro.

A Papermill adota uma abordagem opinativa para parametrização e execução de notebooks com base em nossas experiências no uso de notebooks em escala em pipelines de dados.

Instalação

Na linha de comando:

 pip install papermill

Para todas as dependências io opcionais, você pode especificar pacotes individuais como s3 ou azure – ou usar all . Para usar Preto para formatar parâmetros que você pode adicionar como extra, requer ['preto'].

 pip install papermill[all]

Suporte à versão Python

Esta biblioteca atualmente suporta versões Python 3.8+. Como as versões secundárias do Python foram oficialmente descontinuadas pela Python org, a papermill também abandonará o suporte no futuro.

Uso

Parametrizando um Notebook

Para parametrizar seu notebook designe uma célula com a tag parameters .

Papermill procura a célula parameters e trata esta célula como padrão para os parâmetros passados ​​em tempo de execução. A Papermill adicionará uma nova célula marcada com injected-parameters com parâmetros de entrada para substituir os valores em parameters . Se nenhuma célula estiver marcada com parameters a célula injetada será inserida na parte superior do notebook.

Além disso, se você executar novamente os notebooks por meio do papermill, ele reutilizará a célula de injected-parameters da execução anterior. Neste caso, a Papermill substituirá a antiga célula injected-parameters pelas entradas da nova execução.

Executando um Notebook

As duas maneiras de executar o notebook com parâmetros são: (1) por meio da API Python e (2) por meio da interface de linha de comando.

Execute por meio da API Python

 import papermill as pm

pm.execute_notebook(
   'path/to/input.ipynb',
   'path/to/output.ipynb',
   parameters = dict(alpha=0.6, ratio=0.1)
)

Executar via CLI

Aqui está um exemplo de um notebook local sendo executado e enviado para uma conta do Amazon S3:

 $ papermill local/input.ipynb s3://bkt/output.ipynb -p alpha 0.6 -p l1_ratio 0.1

NOTA: Se você usar várias contas da AWS e tiver configurado corretamente suas credenciais da AWS, poderá especificar qual conta usar definindo a variável de ambiente AWS_PROFILE na linha de comando. Por exemplo:

 $ AWS_PROFILE=dev_account papermill local/input.ipynb s3://bkt/output.ipynb -p alpha 0.6 -p l1_ratio 0.1

No exemplo acima, dois parâmetros são definidos: alpha e l1_ratio usando -p ( --parameters também funciona). Valores de parâmetros que parecem booleanos ou números serão interpretados como tal. Aqui estão as diferentes maneiras pelas quais os usuários podem definir parâmetros:

 $ papermill local/input.ipynb s3://bkt/output.ipynb -r version 1.0

Usando -r ou --parameters_raw , os usuários podem definir os parâmetros um por um. No entanto, ao contrário de -p , o parâmetro permanecerá uma string, mesmo que possa ser interpretado como um número ou booleano.

 $ papermill local/input.ipynb s3://bkt/output.ipynb -f parameters.yaml

Usando -f ou --parameters_file , os usuários podem fornecer um arquivo YAML do qual os valores dos parâmetros devem ser lidos.

 $ papermill local/input.ipynb s3://bkt/output.ipynb -y "
alpha: 0.6
l1_ratio: 0.1"

Usando -y ou --parameters_yaml , os usuários podem fornecer diretamente uma string YAML contendo valores de parâmetro.

 $ papermill local/input.ipynb s3://bkt/output.ipynb -b YWxwaGE6IDAuNgpsMV9yYXRpbzogMC4xCg==

Usando -b ou --parameters_base64 , os usuários podem fornecer uma string YAML, codificada em base64, contendo valores de parâmetro.

Ao usar YAML para passar argumentos, por meio de -y , -b ou -f , os valores dos parâmetros podem ser arrays ou dicionários:

 $ papermill local/input.ipynb s3://bkt/output.ipynb -y "
x:
    - 0.0
    - 1.0
    - 2.0
    - 3.0
linear_function:
    slope: 3.0
    intercept: 1.0"

Manipuladores de nomes suportados

Papermill suporta os seguintes manipuladores de nomes para caminhos de entrada e saída durante a execução:

• Sistema de arquivos local: local

• Protocolo HTTP, HTTPS: http://, https://

• Amazon Web Services: AWS S3 s3://

• Azure: Azure DataLake Store, Azure Blob Store adl://, abs://

• Google Cloud: Google Cloud Storage gs://

Guia de desenvolvimento

Leia CONTRIBUTING.md para obter orientações sobre como configurar um ambiente de desenvolvimento local e fazer alterações de código no Papermill.

Para diretrizes de desenvolvimento, consulte o arquivo DEVELOPMENT_GUIDE.md. Isso deve informá-lo sobre como fazer acréscimos específicos à base de código.

Documentação

Hospedamos a documentação da Papermill no ReadTheDocs.