pynblint

Muitos cientistas profissionais de dados usam o Jupyter Notebook para realizar suas tarefas diárias, desde a exploração preliminar de dados até modelar prototipagem. A interatividade dos notebooks é particularmente conveniente para a programação centrada em dados e sua natureza de auto-documentação fornece um excelente suporte para a comunicação de resultados analíticos.

No entanto, o notebook Jupyter tem sido frequentemente criticado por induzir maus hábitos de programação e mal apoiar as melhores práticas de engenharia de software. Para realmente se beneficiar dos notebooks, os usuários devem estar cientes de suas armadilhas comuns e aprender a evitá -las.

Em trabalhos anteriores (consulte "Excunhando as melhores práticas para colaboração com notebooks computacionais" [1]), introduzimos um catálogo de 17 diretrizes empiricamente validadas para o uso colaborativo de notebooks em um contexto profissional.

Para promover a adoção dessas melhores práticas, criamos o Pynblint, uma ferramenta de análise estática para os notebooks Jupyter escritos em Python. A Pynblint revela possíveis defeitos no caderno e recomenda ações corretivas. Ele pode ser operado como um aplicativo CLI independente ou como parte de um pipeline CI/CD.

As principais regras de linha de Pynblint foram derivadas como operacionalizações das melhores práticas do nosso catálogo. No entanto, a arquitetura plug-in da Pynblint permite que seus usuários estendam facilmente o conjunto principal de cheques com suas próprias regras de linha.

Requisitos

Python 3.7+.

Instalação

O Pynblint pode ser instalado com pip ou outro gerenciador de pacotes do Pypi:

pip install pynblint

Após a instalação, recomendamos explorar a interface da linha de comando da ferramenta:

pynblint --help

Uso

Pynblint pode ser usado para analisar:

• Um caderno independente:

  pynblint path/to/the/notebook.ipynb

• Um repositório de código contendo cadernos:

  pynblint path/to/the/project/dir/

  • (possivelmente também compactado como um arquivo .zip ):

    pynblint path/to/the/compressed/archive.zip

• Um repositório público do GitHub contendo cadernos (o suporte a repositórios privados está em nosso roteiro?):

  pynblint --from-github https://github.com/collab-uniba/pynblint

Para obter mais informações sobre as opções disponíveis, consulte a documentação do projeto.

Catálogo de melhores práticas

Atualmente, Pynblint implementa 22 regras de linha:

• 17 regras aplicáveis ​​a cadernos independentes;
• 5 Regras aplicáveis ​​a repositórios de ciência de dados inteiros.

Essas regras são derivadas do nosso catálogo abrangente de melhores práticas para o desenvolvimento colaborativo de notebooks [1]. Abaixo está o atual estado de implementação das regras de linha associadas a cada prática recomendada:

• ✅ Complete: totalmente implementado
• ? Parcial: parcialmente implementado com melhorias planejadas
• ⏳ em andamento: implementação planejada para futuras versões
• Não planejado: nenhuma implementação planejada

Melhor prática de [1]	Status	Detalhes
1. Use o controle da versão	✅ Complete	Totalmente implementado
2. Gerencie as dependências do projeto	✅ Complete	Totalmente implementado
3. Use ambientes independentes	⏳ em andamento:	Planejado : detecção de - Ambientes virtuais de Python (por exemplo, criados com venv , pyenv ou conda ) - Ambientes de contêiner (por exemplo, Docker).
4. Coloque as importações no começo	✅ Complete	Totalmente implementado
5. Garanta a reexecutabilidade (re-executões de notebooks de cima para baixo)	✅ Complete	Totalmente implementado
6. Modularize seu código	? Parcial	Corrente : Detecção de construções de modularização em notebooks. Planejado : Recomendações de refatoração focadas na modularização com base em padrões detectados
7. Teste seu código	? Parcial	Corrente : Detecção no nível do repositório dos dados de cobertura. Planejado : Detecção de módulos de teste/funções independentes das ferramentas de cobertura
8. Nomeie seus notebooks de forma consistente	✅ Complete	Totalmente implementado
9. Atenha -se aos padrões de codificação	? Parcial	Corrente : Detecção de células com sintaxe de Python inválido. Planejado : integração de linters python, como Pylint, Flake8 e Ruff
10. Use caminhos relativos	⏳ em andamento:	Planejado : Identificação de instâncias de caminhos absolutos nos notebooks e recomendação de caminhos relativos correspondentes
11. Documente sua análise	✅ Complete	Totalmente implementado
12. Aproveite os títulos de marcação para estruturar seu notebook	✅ Complete	Totalmente implementado
13. Mantenha seu caderno limpo	✅ Complete	Totalmente implementado
14. Mantenha seu caderno conciso	✅ Complete	Totalmente implementado
15. Distinguir artefatos de produção e desenvolvimento	Não planejado	Implementação considerada inviável (veja a nota abaixo)
16. Disponibilize seus cadernos	⏳ em andamento:	Planejado : Pynblint garantirá que os notebooks marcados como publicados em sua configuração estejam disponíveis online
17. Visite seus dados disponíveis	✅ Complete	Totalmente implementado

NOTA : A prática recomendada #15 (distinguir artefatos de produção/desenvolvimento) não será implementada, pois não há critérios objetivos para determinar essa distinção através da análise estática de notebooks ou repositórios.

Licença

Este projeto está licenciado nos termos da licença do MIT.

Referências

[1] Luigi Quaranta, Fabio Calefato e Filippo Lanubile. 2022. Excunhando as melhores práticas para colaboração com notebooks computacionais. Proc. ACM Hum.-comput. Interagir. 6 , CSCW1, artigo 87 (abril de 2022), 41 páginas. https://doi.org/10.1145/3512934