Criar uma extensão do Jupyter Notebook

Artigo
10/16/2024

Este tutorial demonstra como criar uma nova extensão do Jupyter Notebook Azure Data Studio. A extensão fornece um exemplo de Jupyter Notebook que pode ser aberto e executado no Azure Data Studio.

Neste artigo, vai aprender a:

Crie um projeto de extensão.
Instale o gerador de extensão.
Crie sua extensão de bloco de anotações.
Execute sua extensão.
Empacote sua extensão.
Publique sua extensão no mercado.

APIs usadas

azdata.nb.showNotebookDocument

Casos de uso de extensão

Há algumas razões diferentes pelas quais você criaria uma extensão de bloco de anotações:

Partilhar documentação interativa
Guarde e tenha acesso constante a esse bloco de notas
Fornecer problemas de codificação para os usuários acompanharem
Versão e acompanhamento das atualizações do bloco de notas

Pré-requisitos

O Azure Data Studio é criado na mesma estrutura do Visual Studio Code, portanto, as extensões para o Azure Data Studio são criadas usando o Visual Studio Code. Para começar, você precisa dos seguintes componentes:

Node.js instalado e disponível no seu $PATH. Node.js inclui o npm, o Node.js Package Manager, que é usado para instalar o gerador de extensão.
Visual Studio Code para depurar a extensão.
Certifique-se de azuredatastudio que está no seu caminho. Para Windows, certifique-se de escolher a opção Adicionar ao caminho no setup.exe. Para Mac ou Linux, execute o comando Instalar 'azuredatastudio' no PATH a partir da Paleta de Comandos no Azure Data Studio.

Instale o gerador de extensões

Para simplificar o processo de criação de extensões, construímos um gerador de extensões usando o Yeoman. Para instalá-lo, execute o seguinte comando no prompt de comando:

npm install -g yo generator-azuredatastudio

Crie a sua extensão

Para criar uma extensão:

Inicie o gerador de extensões com o seguinte comando:

yo azuredatastudio
Escolha Novos Blocos de Anotações (Individual) na lista de tipos de extensão.
Siga as etapas para preencher o nome da extensão. Para este tutorial, use o Bloco de Anotações de Teste. Em seguida, preencha um nome de editor. Para este tutorial, use a Microsoft. Finalmente, adicione uma descrição.

Ora, é aqui que existe alguma ramificação. Você pode adicionar blocos de anotações Jupyter que você já criou ou você pode usar blocos de anotações de amostra fornecidos a você através do gerador.

Para este tutorial, usaremos um bloco de anotações Python de exemplo:

Selecionar exemplo python

Se você tiver blocos de anotações que você está interessado em enviar, responda que você tem blocos de anotações existentes que você deseja enviar. Forneça o caminho de arquivo absoluto onde todos os seus blocos de anotações ou arquivos de marcação vivem.

A conclusão das etapas anteriores cria uma nova pasta com o bloco de anotações de exemplo. Abra a pasta no Visual Studio Code e você estará pronto para enviar sua nova extensão de bloco de anotações.

Entenda sua extensão

Este é o aspeto que o seu projeto deve ter atualmente:

estrutura do arquivo de extensão

O vsc-extension-quickstart.md arquivo fornece uma referência dos arquivos importantes. O README.md arquivo é onde você pode fornecer documentação para sua nova extensão. Observe o package.json, notebook.tse pySample.ipynb arquivos.

Se houver algum arquivo ou pasta que você não deseja publicar, você pode incluir seus nomes no .vscodeignore arquivo.

Vamos dar uma olhada para notebook.ts entender o que nossa extensão recém-formada está fazendo.

// This function is called when you run the command `Launch Notebooks: Test Notebook` from the
// command palette in Azure Data Studio. If you want any additional functionality
// to occur when you launch the book, add it to the activate function.
export function activate(context: vscode.ExtensionContext) {
    context.subscriptions.push(vscode.commands.registerCommand('launchNotebooks.test-notebook', () => {
        let notebooksToDisplay: Array<string> = processNotebooks();
        notebooksToDisplay.forEach(name => {
            azdata.nb.showNotebookDocument(vscode.Uri.file(name));
        });
    }));

    // Add other code here if you want to register another command.
}

Esta é a principal função que notebook.ts é chamada sempre que executamos a nossa extensão através do comando Launch Notebooks: Test Notebook. Criamos nosso novo comando usando a vscode.commands.registerCommand API. A seguinte definição dentro das chaves é o código que é executado cada vez que chamamos nosso comando. Para cada bloco de anotações encontrado em nossa processNotebooks função, nós o abrimos no Azure Data Studio usando azdata.nb.showNotebookDocument.

O package.json arquivo também desempenha um papel importante no registro de nosso comando Launch Notebooks: Test Notebook.

"activationEvents": [
		"onCommand:launchNotebooks.test-notebook"
	],
	"main": "./out/notebook.js",
	"contributes": {
		"commands": [
			{
				"command": "launchNotebooks.test-notebook",
				"title": "Launch Notebooks: Test Notebook"
			}
		]
	}

Temos um evento de ativação para o comando e também adicionamos pontos de contribuição específicos. Esses pontos de contribuição aparecem no mercado de extensão, onde as extensões são publicadas, quando os usuários estão olhando para sua extensão. Se quiser adicionar mais comandos, certifique-se de adicioná-los ao activationEvents campo. Para obter mais opções, consulte Eventos de ativação.

Empacote sua extensão

Para compartilhar com outras pessoas, você precisa empacotar a extensão em um único arquivo. Sua extensão pode ser publicada no mercado de extensões do Azure Data Studio ou compartilhada com sua equipe ou comunidade. Para fazer essa etapa, você precisa instalar outro pacote npm a partir da linha de comando.

npm install -g vsce

Edite o README.md ficheiro ao seu gosto. Em seguida, vá para o diretório base da extensão e execute vsce package. Opcionalmente, você pode vincular um repositório à sua extensão ou continuar sem um. Para adicionar uma, adicione uma linha semelhante ao seu package.json ficheiro.

"repository": {
    "type": "git",
    "url": "https://github.com/laurajjiang/testnotebook.git"
}

Depois que essas linhas são adicionadas, um my test-notebook-0.0.1.vsix arquivo é criado e pronto para instalar e compartilhar com o mundo.

Execute sua extensão

Para executar e testar sua extensão, abra o Azure Data Studio e abra a paleta de comandos selecionando Ctrl+Shift+P. Encontre o comando Extensões: Instalar a partir do VSIX e vá para a pasta que contém a nova extensão.

Instalar o VSIX

Sua extensão agora deve aparecer no painel de extensão no Azure Data Studio. Abra a paleta de comandos novamente e você encontrará o novo comando que criamos com nossa extensão Launch Book: Test Book. Ao correr, ele deve abrir o Jupyter Book que empacotamos com nossa extensão.

Comando Bloco de Anotações

Parabéns! Você construiu e agora pode enviar sua primeira extensão Jupyter Notebook.

Publique sua extensão no mercado

O mercado de extensão do Azure Data Studio está em construção. Para publicar, hospede a extensão VSIX em algum lugar, por exemplo, em uma página de versão do GitHub. Em seguida, envie uma solicitação pull que atualize esse arquivo JSON com suas informações de extensão.

Próximos passos

Neste tutorial, ficou a saber como:

Crie um projeto de extensão.
Instale o gerador de extensão.
Crie sua extensão de bloco de anotações.
Crie a sua extensão.
Empacote sua extensão.
Publique sua extensão no mercado.

Esperamos que, depois de ler este artigo, você se inspire para criar sua própria extensão para o Azure Data Studio.

Se você tiver uma ideia, mas não tiver certeza de como começar, abra um problema ou tweete a equipe do azuredatastudio.

Para obter mais informações, o guia de extensão de código do Visual Studio abrange todas as APIs e padrões existentes.

Partilhar via