chasten
v0.2.0: Merge pull request #81 from AstuteSource
Chasten é um programa Python que usa expressões XPath para encontrar padrões na árvore de sintaxe abstrata (AST) de um programa Python. Você pode usar o Chasten para implementar rapidamente suas próprias regras de linha configurável, sem precisar usar uma estrutura de análise AST complexa ou recorrer a expressões regulares imprecisas.
Deseja garantir que um programa Python tenha não ter nenhum triplo aninhado for loops dentro das funções async ? Ou você deseja confirmar que todas as funções dentro do seu programa Python têm anotações de tipo e um comentário de Docstring? Chasten pode ajudar ! Ele permite expressar essas verificações - e muitos outros tipos de análises também - em arquivos YAML simples que contêm expressões XPath.
Cheten (verbo transitivo) "Para conscientizar alguém do fracasso ou de ter feito algo errado", Dictionary Cambridge.
CHASTEN (INCONTENCIAL OU Singular substantivo) "Uma ferramenta que analisa a árvore de sintaxe abstrata de um programa Python para detectar fontes em potencial de erros de programador, a fim de impedir a falha do programa", desenvolvedores de Astutesource.
chasten me lembrou de adicionar documentos e anotações a todas as funções do main.py Foi fácil ver o que consertar!"chasten facilita para mim confirmar com segurança que os programas de estudantes têm os construtos de codificação necessários. É muito melhor do que usar expressões regulares!"chasten tornou divertido e fácil para mim fazer uma análise automatizada de uma base de código Python que mantenho".chasten me permite explorar efetivamente os dados que coleciono". Siga estas etapas para instalar o programa chasten :
pipx install chasten para instalar o castelopipx list e confirme que o Chasten está instaladochasten --help para aprender a usar a ferramenta Você pode configurar chasten com dois arquivos YAML, normalmente chamados de config.yml e checks.yml . Embora chasten possa gerar uma configuração inicial, você pode conferir o? ASTUTESURCE/CHASTEN-Configuration Repository, por exemplo (s) de arquivos de configuração que configuram a ferramenta. Embora o arquivo config.yml possa fazer referência a vários arquivos de configuração de verificação, este exemplo mostra como especificar um único arquivo checks.yml :
# chasten configuration
chasten :
# point to a single checks file
checks-file :
- checks.yml O arquivo checks.yml deve conter uma ou mais verificações. O que se segue é um exemplo de um arquivo de configuração de verificação com duas verificações que encontram respectivamente a primeira linha executável de funções não testadas e casos de teste em um projeto Python. Observe que o atributo pattern especifica a expressão do XPath versão 2.0 que chasten usará para detectar o tipo especificado da função Python. Você pode digitar chasten configure validate --config <path to chasten-configuration/ directory | config url> Após o preenchimento de <path to chasten-configuration/directory | config url> Com o nome totalmente qualificado do seu diretório de configuração e a ferramenta confirmará que sua configuração atende à especificação da ferramenta. Você também pode usar o comando chasten configure create comando para gerar automaticamente uma configuração inicial! Digitar chasten configure --help explicará como configurar a ferramenta.
checks :
- name : " all-non-test-function-definition "
code : " FUNC "
id : " FUNC001 "
description : " First executable line of a non-test function, skipping over docstrings and/or comments "
pattern : ' //FunctionDef[not(contains(@name, "test_"))]/body/Expr[value/Constant]/following-sibling::*[1] | //FunctionDef[not(contains(@name, "test_"))]/body[not(Expr/value/Constant)]/*[1] '
- name : " all-test-function-definition "
code : " FUNC "
id : " FUNC002 "
description : " First executable line of a test function, skipping over docstrings and/or comments "
pattern : ' //FunctionDef[starts-with(@name, "test_")]/body/Expr[value/Constant]/following-sibling::*[1] | //AsyncFunctionDef[starts-with(@name, "test_")]/body/Expr[value/Constant]/following-sibling::*[1] | //FunctionDef[starts-with(@name, "test_")]/body[not(Expr/value/Constant)]/*[1] | //AsyncFunctionDef[starts-with(@name, "test_")]/body[not(Expr/value/Constant)]/*[1] '
count :
min : 1
max : 10 Como chasten precisa de um projeto com o código-fonte do Python como entrada para seu subcomando analysis , você pode clonar o? Astutesource/lazytracker e? Repositórios Astutesource/multicounter que são garfos de projetos Python existentes criados para análise conveniente. Para analisar incrementalmente esses dois projetos com chasten , você pode digitar os seguintes comandos para produzir um arquivo JSON de resultados para cada projeto:
subject-data/ que contém um diretório lazytracker/ , você pode executar o comando chasten analyze para o programa lazytracker : chasten analyze lazytracker
--config < path to the chasten-configuration/ directory | config url >
--search-path < path to the lazytracker/ directory >
--save-directory < path to the subject-data/lazytracker/ directory >
--save Agora você pode digitalizar a saída para confirmar que, por exemplo, chasten encontra 6 funções de teste no projeto lazytracker . Se você procurar no diretório de subject-data/lazytracker encontrará um arquivo JSON com um nome como chasten-results-lazytracker-20230823162341-4c23fc443a6b4c4aa09886f1ecb96e9f.json . A execução chasten neste programa mais de uma vez produzirá um novo arquivo de resultados com um registro de data e hora diferente (isto é, 20230823162341 ) e identificador exclusivo (ou seja, 4c23fc443a6b4c4aa09886f1ecb96e9f ) em seu nome, como você não é acidental --save
Depois de criar um diretório multicounter/ no subject-data/ existentes, você pode executar o comando chasten analyze para o programa multicounter :
chasten analyze multicounter
--config < path to the chasten-configuration/ directory | config url >
--search-path < path to the multicounter/ directory >
--save-directory < path to the subject-data/lazytracker/ directory >
--save Agora você pode digitalizar a saída para confirmar que, como exemplo, chasten encontra 10 funções de teste no projeto multicounter . Se você procurar no diretório subject-data/lazytracker encontrará um arquivo JSON com um nome como chasten-results-multicounter-20230821171712-5c52f2f1b61b4cce97624cc34cb39d4f.json , os componentes do multicounter .
Como a verificação all-test-function-definition especifica que o programa deve ter entre 1 e 10 testes, você notará que esse cheque passa para lazytracker e multicounter . Isso significa que chasten retorna um código de erro 0 para se comunicar ao seu sistema operacional que a verificação passou.
Você pode aprender mais sobre como usar o subcomando analyze digitando chasten analyze --help . Por exemplo, chasten suporta as opções --check-include e --check-exclude que permitem que você inclua e exclua respectivamente verificações específicas de acordo com as regras de correspondência difusa que você pode especificar para qualquer um dos atributos de um cheque especificados no arquivo checks.yml .
Depois de executar chasten nos programas lazytracker e multicounter , você pode integrar seus arquivos JSON individuais em um único arquivo JSON, arquivos CSV relacionados e um banco de dados SQLite. Depois de fazer um integrated-data/ , você pode digitar este comando para executar a integração:
chasten integrate all-programs
< path to subject-data > / ** / * .json
--save-directory < path to the integrated-data/ directory > Este comando produzirá um diretório como chasten-flattened-csvs-sqlite-db-all-programs-20230823171016-2061b524276b4299b04359ba30452923/ que contém o sqlite de tais de chasten.db e a todos os sqlite de csv/ . banco de dados.
Você pode aprender mais sobre o subcomando integrate digitando chasten integrate --help .
Ao utilizar o comando chasten , anexar esse sinalizador --verbose pode aprimorar significativamente sua experiência em solução de problemas e fornecer um entendimento detalhado da funcionalidade da ferramenta. Aqui está um exemplo com chasten analyze lazytracker :
chasten analyze lazytracker
--config < path to the chasten-configuration/ directory >
--search-path < path to the lazytracker/ directory >
--save-directory < path to the subject-data/lazytracker/ directory >
--save
--verbose Ao executar este comando, você pode esperar que a saída contenha mensagens informativas, como Matching source code: indicando que a ferramenta está comparando ativamente o código -fonte com os padrões especificados. Além disso, você receberá resultados detalhados de correspondência, fornecendo informações sobre os cheques identificados.
Se você deseja criar um painel de análise interativa que use? Simonw/DataSette Você pode executar chasten datasette-serve <path containing integrated results>/chasten.db --port 8001 . Agora você pode usar o painel no seu navegador para analisar os resultados enquanto estuda o código -fonte desses projetos com seu editor! Examinar os resultados revelará que chasten , através de seu uso? SpookyLukey/pyastgrep, usa corretamente a expressão XPath para all-test-function-definition para encontrar a primeira linha de código-fonte executável dentro de cada teste, pulando os comentários de Docstring e líder de uma função.
Para o programa lazytracker , você notará que chasten relata que existem 6 casos de teste, embora pytest apenas encontre e execute 5 testes. Isso se deve ao fato de que o conjunto de tests/test_tracked.py no lazytracker contém uma função começando com test_ dentro de outra função começando com test_ . Este exemplo ilustra as limitações da análise estática com chasten ! Embora a ferramenta tenha detectado corretamente todas as "funções de teste", o ninho das funções no conjunto de testes significa que pytest executará a função test_ Exterior e usará a função test_ INER para fins de teste.
Com isso dito, chasten encontra corretamente cada um dos testes para o projeto multicounter . Você pode seguir cada uma das etapas anteriores deste documento para aplicar chasten ao seu próprio programa Python!
Se você deseja disponibilizar seu chasten.db publicamente para todos estudarem, você pode usar o Sub-Companhia chasten datasette-publish . Contanto que você tenha seguido as instruções de instalação para? Simonw/DataSette-Publish-Fly e? Simonw/DataSette-Publish-Vercel, você pode usar os plug-ins para implantar um servidor público datasette público que hospeda o seu chasten.db . Por exemplo, a execução do comando chasten datasette-publish <path containing integrated results>/chasten.db --platform vercel publicará os resultados da execução chasten no lazytracker e no multicounter na plataforma Vercel.
É importante ressaltar que o uso do Comando chasten datasette-publish com a opção --platform vercel exige que você tenha seguido anteriormente as instruções para o plugin datasette-publish-vercel para instalar a ferramenta de linha de comando vercel . Isso é necessário porque, embora datasette-publish-vercel seja uma das dependências de chasten , nem chasten nem datasette-publish-vercel fornecem a ferramenta vercel , mesmo que a use. Você deve tomar medidas semelhantes antes de publicar seu banco de dados para voar!
Embora chasten seja um aplicativo de linha de comando, você cria interativamente os argumentos e opções da linha de comando da ferramenta por meio de uma interface do usuário do Terminal (TUI). Para usar a maneira baseada em TUI de criar uma linha de comando completa para chasten , você pode digitar o comando chasten interact .
Chasten possui um log do sistema interno. Ao usar o Chasten, você pode usar o comando chasten log no seu terminal. O recurso de log do sistema permite que o usuário veja eventos e mensagens que são produzidas por chasten . Além disso, o recurso chasten log ajudará a encontrar bugs e os eventos que levaram o bug acontecendo. Para que o programa chasten seja exibido no log do sistema, você precisará abrir um terminal separado e usar o chasten log de comando. Além disso, para cada comando que é executado, o --debug-level <choice of level> e- --debug-dest SYSLOG precisará ser adicionado.
Por exemplo, chasten datasette-serve --debug-level DEBUG --debug-dest SYSLOG < database path to file> produzirá a seguinte saída no log do sistema.
? chasten: Analyze the AST of Python Source Code
? GitHub: https://github.com/gkapfham/chasten
Syslog server for receiving debugging information
Display verbose output? False
Debug level? DEBUG
Debug destination? SYSLOG
Em cada comando em chasten , há uma opção para adicionar um --debug-level . O nível de depuração tem 5 opções depuração, informações, aviso, erro e crítico. Cada nível mostrará problemas diferentes no log do sistema, onde a depuração é o nível mais baixo de emissão a partir da entrada onde crítico é o nível mais alto de erro. Para aproveitar mais informações sobre isso, você pode fazer referência ao arquivo debug.py :
class DebugLevel ( str , Enum ):
"""The predefined levels for debugging."""
DEBUG = "DEBUG"
INFO = "INFO"
WARNING = "WARNING"
ERROR = "ERROR"
CRITICAL = "CRITICAL" Usage: chasten [OPTIONS] COMMAND [ARGS]...
╭─ Options ───────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy it or │
│ customize the installation. │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────╮
│ analyze ? Analyze the AST of Python source code. │
│ configure ? Manage chasten ' s configuration. │
│ datasette-publish ? Publish a datasette to Fly or Vercel. │
│ datasette-serve ? Start a local datasette server. │
│ integrate ? Integrate files and make a database. │
│ interact Interactively configure and run. │
│ log ? Start the logging server. │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯
Siga estas etapas para instalar a ferramenta chasten para desenvolvimento futuro:
Depois que o Python e a poesia forem instalados, vá para o repositório Chasten no Github e instale a ferramenta usando o comando git clone no seu terminal. Em seguida, navegue até o diretório Chasten e execute a poetry install de comando para instalar todas as dependências.
Há também a opção de usar o Docker para usar chasten
Siga estas etapas para utilizar o Docker:
cd no diretório Chasten, onde o Dockerfile está localizadodocker build -t chasten . Para construir o contêinerdocker run --rm -v "%cd%":/root/src -it chastendocker run --rm -v ${pwd}:/root/src -it chastendocker run --rm -v $(pwd):/root/src -it chastenpoetry install do tipo recipientedocker ps para visualizar informações de contêiner em execuçãodocker commit <your-container-id> <your-image-name> para salvar a instalação dependentechasten ! Black and Ruff em castigar para garantir a consistência do código, a legibilidade e a adesão aos padrões de formatação predefinidos em todo o projeto, aumentando a manutenção e a colaboração entre os desenvolvedores.poetry run task fiximports e/ou poetry run task fixformat antes de enviar novos recursos. Se os recursos forem enviados com problemas de linha, a compilação será divulgada no Github devido à falha do conjunto de testes.Pytest e Hypothesis das ferramentas de teste, o que nos permite fortalecer a consistência do código, a legibilidade e o alinhamento com os padrões de formatação estabelecidos ao longo do projeto. Ao escrever casos de teste para recursos, crie um novo arquivo no diretório de testes com o test_(name of file) .poetry run task test para a maioria dos casos ou se você deseja testar os recursos baseados em API do OpenAI poetry run task test-api antes do envio. Se os recursos forem enviados sem uma suíte de teste, a cobertura será reduzida no Github devido à adição de código não testado e poderá levar em potencial a questões maiores no futuro. CHASTEN e SYMBEX, criados por Simon Willison, são ferramentas projetadas para analisar o código -fonte do Python, focando particularmente na busca de funções e classes nos arquivos. Embora eles compartilhem um objetivo comum, há diferenças notáveis entre os dois, especialmente em termos de interfaces e funcionalidade da linha de comando.
Em termos de interface da linha de comando, o SyMbex emprega uma CLI concisa, utilizando abreviações para várias opções. Por exemplo, o comando para pesquisar assinaturas de função em um arquivo chamado test_debug.py é o seguinte:
command : symbex - s - f symbex / test_debug . py
def test_debug_level_values ():
def test_debug_level_isinstance ():
def test_debug_level_iteration ():
def test_debug_destination_values ():
def test_debug_destination_isinstance ():
def test_debug_destination_iteration ():
def test_level_destination_invalid ():
def test_debug_destination_invalid ():Chasten, por outro lado, aproveita os pacotes Python, como Typer e Rich, para fornecer uma interface de linha de comando rica em usuário e rica em recursos. Os comandos disponíveis para Chasten incluem:
Em termos de funcionalidade, o SyMbex foi projetado para pesquisar o código Python por funções e classes por nome ou curinga. Ele fornece a capacidade de filtrar os resultados com base em vários critérios, incluindo o tipo de função (assíncrono ou não asincroso), presença de documentação, visibilidade e anotações de tipo.
Por outro lado, o comando analyze de Chasten executa a análise AST no código -fonte do Python. Ele permite que os usuários especifiquem um nome de projeto, versão XPath, caminho de pesquisa e vários critérios de filtragem. O Chasten suporta verificações de inclusão e exclusão com base em atributos, valores e níveis de confiança. A ferramenta também fornece opções de configuração extensas e a capacidade de economizar resultados em diferentes formatos, incluindo o Markdown.
Em resumo, enquanto Chasten e SyMbex servem ao objetivo comum de analisar o código-fonte do Python, a Chasten oferece uma CLI mais versátil e fácil de usar, com recursos adicionais de configuração e gerenciamento de resultados. O SyMbex, por outro lado, adota uma CLI concisa, com foco na pesquisa e filtragem de funcionalidades. A escolha entre as duas ferramentas depende das preferências do usuário e dos requisitos específicos para análise de código Python.
Além da CHASTEN e SYMBEX, várias outras ferramentas oferecem recursos exclusivos para analisar e pesquisar através do código -fonte do Python, cada um atendendo a casos de uso específicos.
