Vídeo + notas sobre a atualização de um plug-in Datasette para a versão alfa 1.0 mais recente, com ajuda de uv e OpenAI Codex CLI

Vídeo + notas sobre a atualização de um plug-in Datasette para a versão alfa 1.0 mais recente, com ajuda de uv e OpenAI Codex CLI

6 de novembro de 2025

Estou atualizando vários plugins para compatibilidade com a nova versão alfa do Datasette 1.0a20 e decidi gravar um vídeo do processo. Esta postagem acompanha esse vídeo com notas adicionais detalhadas.

O plugin datasette-checkbox

Escolhi um plugin muito simples para ilustrar o processo de atualização (possivelmente simples demais). caixa de seleção do conjunto de dados adiciona apenas um recurso ao Datasette: se você estiver visualizando uma tabela com colunas booleanas (detectadas como colunas inteiras com nomes como is_active ou has_attachments ou should_notify) e seu usuário atual tem permissão para atualizar linhas nessa tabela e adiciona uma interface de caixa de seleção embutida semelhante a esta:

Construí a primeira versão com a ajuda de Claude em agosto de 2024 – detalhes neste comentário da edição.

A maior parte da implementação é JavaScript que faz chamadas para a API de gravação JSON do Datasette 1.0. O código Python apenas verifica se o usuário possui as permissões necessárias antes de incluir o JavaScript extra.

Executando os testes do plugin

A primeira etapa na atualização de qualquer plugin é executar seus testes na versão mais recente do Datasette.

Felizmente uv facilita a execução de código em ambientes virtuais de rascunho que incluem as diferentes versões de código que você deseja testar.

Eu tenho um utilitário de teste chamado tadd (para “teste contra conjunto de dados de desenvolvimento”) que utilizo para esse fim. Posso executá-lo em qualquer diretório de plugins como este:

E ele executará os testes de plug-in existentes em qualquer versão do Datasette que eu verifiquei em meu ~/dev/datasette diretório.

Você pode ver a implementação completa de tadd (e seu amigo radd descrito abaixo) neste TIL — a versão básica se parece com isto:

#!/bin/sh
uv run --no-project --isolated 
  --with-editable '.(test)' --with-editable ~/dev/datasette 
  python -m pytest "$@"

Comecei correndo tadd no datasette-checkbox diretório, e tive minha primeira falha… mas não foi por causa de permissões, foi porque o pyproject.toml para o plugin foi fixado para uma versão específica incompatível do Datasette:

dependencies = (
    "datasette==1.0a19"
)

Resolvi esse problema trocando == para >= e fiz os testes novamente… e eles passaram! O que foi um problema porque eu esperava falhas relacionadas à permissão.

Acontece que quando escrevi o plugin pela primeira vez eu estava preguiçoso com os testes– eles não estavam realmente confirmando se a página da tabela foi carregada sem erros.

Eu precisava executar o código sozinho para ver o bug esperado.

Primeiro eu criei um banco de dados de demonstração usando sqlite-utils criar tabela:

sqlite-utils create-table demo.db 
  demo id integer is_checked integer --pk id

Então eu executei com o Datasette no código do plugin assim:

Com certeza, visitando /demo/demo produziu um erro 500 sobre o desaparecimento Datasette.permission_allowed() método.

A próxima etapa foi atualizar o teste para também acionar este erro:

@pytest.mark.asyncio
async def test_plugin_adds_javascript():
    datasette = Datasette()
    db = datasette.add_memory_database("demo")
    await db.execute_write(
        "CREATE TABLE IF NOT EXISTS test (id INTEGER PRIMARY KEY, is_active INTEGER)"
    )
    await datasette.invoke_startup()
    response = await datasette.client.get("/demo/test")
    assert response.status_code == 200

E agora tadd falha conforme o esperado.

Atualizando o plugin com Codex

Neste ponto, eu poderia ter corrigido manualmente o próprio plug-in – o que provavelmente teria sido mais rápido devido ao pequeno tamanho da correção – mas, em vez disso, demonstrei uma linha única do bash que estou usando para aplicar esses tipos de alterações automaticamente:

codex exec --dangerously-bypass-approvals-and-sandbox 
"Run the command tadd and look at the errors and then
read ~/dev/datasette/docs/upgrade-1.0a20.md and apply
fixes and run the tests again and get them to pass"

codex exec executa o OpenAI Codex em modo não interativo – ele fará um loop até concluir o prompt fornecido.

Eu digo para consultar o subconjunto do Documentação de atualização do conjunto de dados que fala sobre permissões do Datasette e, em seguida, obter o tadd comando para passar em seus testes.

Este é um exemplo do que chamo de design de loops de agente – dei ao Codex as ferramentas necessárias (tadd) e um objetivo claro e deixá-lo trabalhar em meu nome.

O restante do vídeo aborda a conclusão do trabalho – testando a correção manualmente, confirmando meu trabalho usando:

git commit -a -m "$(basename "$PWD") for datasette>=1.0a20" 
  -m "Refs https://github.com/simonw/datasette/issues/2577"

Em seguida, enviar um Versão 0.1a4 para PyPI usando o padrão descrito neste TIL. Finalmente, demonstrei que o plugin fornecido funcionava em um ambiente novo usando uvx assim:

uvx --prerelease=allow --with datasette-checkbox 
  datasette --root ~/dev/ecosystem/datasette-checkbox/demo.db

A execução deste comando instala e executa uma nova instância do Datasette com uma nova cópia do novo plugin alfa (--prerelease=allow). É uma maneira bacana de confirmar se o software recém-lançado funciona conforme o esperado.

Um colofão para o vídeo

Este vídeo foi filmado em uma única tomada usando Descriçãosem ensaio e com pouca preparação prévia. Gravei através dos meus AirPods e apliquei o filtro “Studio Sound” para limpar o áudio. colei em um simonwillison.net fechei o slide do meu vídeo anterior e exportei-o localmente em 1080p e depois carreguei-o no YouTube.

Algo que aprendi no curso de treinamento para instrutores de Carpintaria de Software é que cometer erros na frente de um público é ativamente útil – ajuda-os a ver uma versão realista de como funciona o desenvolvimento de software e podem aprender observando sua recuperação. Vejo isso como uma ótima desculpa para não editar todos os meus erros!

Estou tentando criar novos hábitos em torno do conteúdo de vídeo que me permitam produzir vídeos úteis e, ao mesmo tempo, minimizar o tempo gasto na produção.

Pretendo iterar mais no formato à medida que me sinto mais confortável com o processo. Espero encontrar o equilíbrio certo entre o tempo de produção e o valor para os espectadores.