chasten
v0.2.0: Merge pull request #81 from AstuteSource
Chasten adalah program Python yang menggunakan XPath Expressions untuk menemukan pola dalam pohon sintaks abstrak (AST) dari program Python. Anda dapat menggunakan Chasten untuk dengan cepat mengimplementasikan aturan sering yang dapat dikonfigurasi Anda sendiri, tanpa harus menggunakan kerangka analisis AST yang kompleks atau menggunakan ekspresi reguler yang tidak tepat.
Apakah Anda ingin memastikan bahwa program Python tidak memiliki tiga kali lipat for loop di dalam fungsi async ? Atau, apakah Anda ingin mengonfirmasi bahwa setiap fungsi di dalam program Python Anda memiliki jenis anotasi dan komentar docstring? Buruk dapat membantu ! Ini memungkinkan Anda untuk mengekspresikan cek ini - dan banyak jenis analisis lainnya juga - dalam file YAML sederhana yang berisi ekspresi xPath.
CHASTEN (Verb Transitif) "untuk membuat seseorang sadar akan kegagalan atau melakukan sesuatu yang salah", Kamus Cambridge.
chasten (kata benda tak terhitung atau tunggal) "Alat yang menganalisis pohon sintaks abstrak dari program Python untuk mendeteksi sumber -sumber potensial kesalahan programmer untuk mencegah kegagalan program", pengembang astutsource.
chasten mengingatkan saya untuk menambahkan Docstrings dan mengetik anotasi ke semua fungsi di main.py Sangat mudah untuk melihat apa yang harus diperbaiki!"chasten memudahkan saya untuk mengonfirmasi bahwa program siswa memiliki konstruksi pengkodean yang diperlukan. Jauh lebih baik daripada menggunakan ekspresi reguler!"chasten membuatnya menyenangkan dan mudah bagi saya untuk melakukan analisis otomatis basis kode Python yang saya pertahankan."chasten memungkinkan saya mengeksplorasi data yang saya kumpulkan secara efektif." Ikuti langkah -langkah ini untuk menginstal program chasten :
pipx install chasten untuk menginstal chastenpipx list dan konfirmasi bahwa chasten diinstalchasten --help mempelajari cara menggunakan alat ini Anda dapat mengkonfigurasi chasten dengan dua file YAML, biasanya disebut config.yml dan checks.yml . Meskipun chasten dapat menghasilkan konfigurasi awal, Anda dapat memeriksa? Repositori Astututesource/Chasten-Configuration misalnya dari file konfigurasi yang mengatur alat. Meskipun file config.yml dapat merujuk beberapa file konfigurasi periksa, contoh ini menunjukkan cara menentukan file checks.yml tunggal:
# chasten configuration
chasten :
# point to a single checks file
checks-file :
- checks.yml File checks.yml harus berisi satu atau lebih cek. Berikut ini adalah contoh file konfigurasi cek dengan dua cek yang masing-masing menemukan jalur pertama yang dapat dieksekusi dari fungsi non-tes dan kasus uji dalam proyek Python. Perhatikan bahwa atribut pattern menentukan ekspresi XPath versi 2.0 yang chasten digunakan untuk mendeteksi jenis fungsi python yang ditentukan. Anda dapat mengetikkan chasten configure validate --config <path to chasten-configuration/ directory | config url> Setelah mengisi <path to chasten-configuration/directory | config url> Dengan nama yang sepenuhnya memenuhi syarat dari direktori konfigurasi Anda dan alat akan mengonfirmasi bahwa konfigurasi Anda memenuhi spesifikasi alat. Anda juga dapat menggunakan perintah Command chasten configure create untuk secara otomatis menghasilkan konfigurasi awal! Mengetik chasten configure --help akan menjelaskan cara mengkonfigurasi alat.
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 Karena chasten membutuhkan proyek dengan kode sumber Python sebagai input ke sub-komando analysis , Anda dapat mengkloning? Astututsource/LazyTracker dan? Repositori Astututesource/Multicounter yang merupakan garpu dari proyek Python yang ada yang dibuat untuk analisis yang nyaman. Untuk menganalisis dua proyek ini secara bertahap dengan chasten , Anda dapat mengetik perintah berikut untuk menghasilkan file JSON hasil untuk setiap proyek:
subject-data/ yang berisi lazytracker/ Direktori, Anda dapat menjalankan perintah chasten analyze untuk program 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 Sekarang Anda dapat memindai output untuk mengonfirmasi bahwa, misalnya, chasten menemukan 6 fungsi tes dalam proyek lazytracker . Jika Anda melihat di direktori subject-data/lazytracker Anda akan menemukan file JSON dengan nama seperti chasten-results-lazytracker-20230823162341-4c23fc443a6b4c4aa09886f1ecb96e9f.json . Menjalankan chasten pada program ini lebih dari satu kali akan menghasilkan file hasil baru dengan cap waktu yang berbeda (yaitu, 20230823162341 ) dan pengidentifikasi unik (yaitu, 4c23fc443a6b4c4aa09886f1ecb96e9f ) dalam namanya, dengan demikian memastikan bahwa Anda tidak secara tidak sengaja menulis di atas Anda --save
Setelah membuat multicounter/ direktori di subject-data/ yang ada, Anda dapat menjalankan perintah chasten analyze untuk program 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 Sekarang Anda dapat memindai output untuk mengonfirmasi bahwa, sebagai contoh, chasten menemukan 10 fungsi uji dalam proyek multicounter . If you look in the subject-data/lazytracker directory you will find a JSON file with a name like chasten-results-multicounter-20230821171712-5c52f2f1b61b4cce97624cc34cb39d4f.json and name components that are similar to the JSON file created for the multicounter program.
Karena pemeriksaan all-test-function-definition menentukan bahwa program harus memiliki antara 1 dan 10 tes, Anda akan melihat bahwa cek ini disahkan untuk lazytracker dan multicounter . Ini berarti bahwa chasten mengembalikan kode kesalahan 0 untuk berkomunikasi dengan sistem operasi Anda yang dilewati cek.
Anda dapat mempelajari lebih lanjut tentang cara menggunakan sub-perintah analyze dengan mengetikkan chasten analyze --help . Misalnya, chasten mendukung opsi --check-include dan --check-exclude yang memungkinkan Anda untuk masing-masing memasukkan dan mengecualikan cek spesifik sesuai dengan aturan pencocokan fuzzy yang dapat Anda tentukan untuk salah satu atribut cek yang ditentukan dalam file checks.yml .
Setelah menjalankan chasten pada program lazytracker dan multicounter , Anda dapat mengintegrasikan file JSON masing -masing ke dalam satu file JSON, file CSV terkait, dan database SQLite. Setelah Anda membuat integrated-data/ , Anda dapat mengetik perintah ini untuk melakukan integrasi:
chasten integrate all-programs
< path to subject-data > / ** / * .json
--save-directory < path to the integrated-data/ directory > Perintah ini akan menghasilkan direktori seperti chasten chasten.db chasten-flattened-csvs-sqlite-db-all-programs-20230823171016-2061b524276b4299b04359ba30452923/ yang ada di dalam c csv/ croryve yang ada di dalam caChase yang ada di setiap cosen. database.
Anda dapat mempelajari lebih lanjut tentang integrate Sub-Command dengan mengetikkan chasten integrate --help .
Saat memanfaatkan perintah chasten , menambahkan bendera ini --verbose dapat secara signifikan meningkatkan pengalaman pemecahan masalah Anda dan memberikan pemahaman terperinci tentang fungsionalitas alat tersebut. Berikut adalah contoh dengan 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 Setelah menjalankan perintah ini, Anda dapat mengharapkan output berisi pesan informatif seperti Matching source code: menunjukkan bahwa alat secara aktif membandingkan kode sumber dengan pola yang ditentukan. Selain itu, Anda akan menerima hasil pertandingan terperinci, memberikan wawasan tentang cek yang diidentifikasi.
Jika Anda ingin membuat dasbor analisis interaktif yang digunakan? Simonw/dataSette Anda dapat menjalankan chasten datasette-serve <path containing integrated results>/chasten.db --port 8001 . Sekarang Anda dapat menggunakan dasbor di browser web Anda untuk menganalisis hasilnya saat Anda mempelajari kode sumber untuk proyek -proyek ini dengan editor Anda! Meneliti hasilnya akan mengungkapkan bahwa chasten , melalui penggunaannya? Spookylukey/Pyastgrep, dengan benar menggunakan ekspresi XPath untuk all-test-function-definition untuk menemukan baris pertama dari kode sumber yang dapat dieksekusi di dalam setiap tes, melewatkan docString fungsi dan komentar terkemuka.
Untuk program lazytracker , Anda akan melihat bahwa chasten laporan bahwa ada 6 kasus uji meskipun pytest hanya menemukan dan menjalankan 5 tes. Hal ini disebabkan oleh fakta bahwa tests/test_tracked.py test suite di lazytracker berisi fungsi yang dimulai dengan test_ di dalam fungsi lain yang dimulai dengan test_ . Contoh ini menggambarkan keterbatasan analisis statis dengan chasten ! Meskipun alat ini dengan benar mendeteksi semua "fungsi tes", sarang fungsi dalam suite tes berarti bahwa pytest akan menjalankan fungsi test_ luar dan menggunakan fungsi test_ dalam untuk tujuan pengujian.
Dengan itu, chasten dengan benar menemukan masing -masing tes untuk proyek multicounter . Anda dapat mengikuti masing -masing langkah sebelumnya dalam dokumen ini untuk menerapkan chasten ke program Python Anda sendiri!
Jika Anda ingin membuat chasten.db Anda tersedia secara publik untuk dipelajari semua orang, Anda dapat menggunakan sub-perintah chasten datasette-publish . Selama Anda mengikuti instruksi instalasi? simonw/datasette-publish-fly dan? Simonw/DataSette-Publish-Vercel, Anda dapat menggunakan plugin untuk menggunakan server datasette publik yang meng-host chasten.db Anda. Misalnya, menjalankan perintah chasten datasette-publish <path containing integrated results>/chasten.db --platform vercel akan menerbitkan hasil dari menjalankan chasten di lazytracker dan multicounter ke platform Vercel.
Yang penting, penggunaan perintah chasten datasette-publish dengan opsi --platform vercel mengharuskan Anda untuk sebelumnya mengikuti instruksi untuk plugin datasette-publish-vercel untuk menginstal alat baris perintah vercel . Ini diperlukan karena, meskipun datasette-publish-vercel adalah salah satu dependensi chasten , baik tidak chasten maupun datasette-publish-vercel menyediakan alat vercel meskipun mereka menggunakannya. Anda harus mengambil langkah serupa sebelum menerbitkan database Anda untuk terbang!
Meskipun chasten adalah aplikasi baris perintah, Anda membuat secara interaktif membuat argumen dan opsi baris perintah alat melalui Terminal User Interface (TUI). Untuk menggunakan cara berbasis TUI untuk membuat baris perintah lengkap untuk chasten , Anda dapat mengetikkan perintah chasten interact .
Chasten memiliki log sistem bawaan. Saat menggunakan chasten, Anda dapat menggunakan perintah chasten log di terminal Anda. Fitur log sistem memungkinkan pengguna untuk melihat acara dan pesan yang diproduksi oleh chasten . Selain itu, fitur chasten log akan membantu dalam menemukan bug dan acara yang menyebabkan bug terjadi. Agar program chasten dapat ditampilkan ke log sistem, Anda harus membuka terminal terpisah dan menggunakan chasten log perintah. Selain itu untuk setiap perintah yang dijalankan --debug-level <choice of level> dan --debug-dest SYSLOG perlu ditambahkan.
Misalnya, chasten datasette-serve --debug-level DEBUG --debug-dest SYSLOG < database path to file> akan menghasilkan output berikut dalam log sistem.
? 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
Di setiap perintah di chasten , ada opsi untuk menambahkan --debug-level . Level debug memiliki 5 opsi debug, info, peringatan, kesalahan, dan kritis. Setiap level akan menunjukkan masalah yang berbeda dalam log sistem di mana debug adalah tingkat masalah terendah dari input di mana kritis adalah tingkat kesalahan tertinggi. Untuk memanfaatkan info lebih lanjut tentang ini, Anda dapat merujuk file 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. │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯
Ikuti langkah -langkah ini untuk menginstal alat chasten untuk pengembangan di masa depan:
Setelah python dan puisi diinstal, silakan pergi ke repositori chasten di github dan instal alat menggunakan perintah git clone di terminal Anda. Kemudian arahkan ke direktori chasten dan jalankan poetry install perintah untuk menginstal semua dependensi.
Ada juga opsi untuk menggunakan Docker untuk menggunakan chasten
Ikuti langkah -langkah ini untuk memanfaatkan Docker:
cd ke direktori chasten di mana Dockerfile beradadocker build -t chasten . untuk membangun wadahdocker 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 tipe wadahdocker ps untuk melihat informasi wadah yang berjalandocker commit <your-container-id> <your-image-name> Untuk menyimpan instalasi tergantungchasten Anda! Black dan Ruff pada ruang untuk memastikan konsistensi kode, keterbacaan, dan kepatuhan terhadap standar pemformatan yang telah ditentukan di seluruh proyek, pada akhirnya meningkatkan pemeliharaan dan kolaborasi di antara pengembang.poetry run task fiximports dan/atau poetry run task fixformat sebelum mengirimkan fitur baru. Jika fitur dikirimkan dengan masalah serat, build akan pecah di GitHub karena kegagalan test suite.Pytest dan Hypothesis yang memungkinkan kita untuk memperkuat konsistensi kode, keterbacaan, dan penyelarasan dengan standar pemformatan yang ditetapkan di seluruh proyek. Saat menulis kasus tes untuk fitur, buat file baru di direktori tes dengan penamaan konvensi test_(name of file) .poetry run task test untuk sebagian besar kasus atau jika Anda ingin poetry run task test-api fitur-fitur berbasis API OpenAi. Jika fitur dikirim tanpa suite tes, cakupan akan diturunkan pada github karena penambahan kode yang belum diuji dan secara potensial dapat menyebabkan masalah yang lebih besar di masa depan. Chasten dan Symbex, yang dibuat oleh Simon Willison, keduanya merupakan alat yang dirancang untuk menganalisis kode sumber Python, terutama yang berfokus pada pencarian fungsi dan kelas dalam file. Sementara mereka berbagi tujuan bersama, ada perbedaan penting antara keduanya, terutama dalam hal antarmuka dan fungsionalitas baris perintah mereka.
Dalam hal antarmuka baris perintah, Symbex menggunakan CLI yang ringkas, memanfaatkan singkatan untuk berbagai opsi. Misalnya, perintah untuk mencari tanda tangan fungsi dalam file bernama test_debug.py adalah sebagai berikut:
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 ():Burung, di sisi lain, memanfaatkan paket Python seperti Typer dan Rich untuk menyediakan antarmuka baris perintah yang ramah pengguna dan kaya fitur. Perintah yang tersedia untuk Chasten meliputi:
Dalam hal fungsionalitas, Symbex dirancang untuk mencari kode Python untuk fungsi dan kelas berdasarkan nama atau wildcard. Ini memberikan kemampuan untuk memfilter hasil berdasarkan berbagai kriteria, termasuk tipe fungsi (async atau non-async), keberadaan dokumentasi, visibilitas, dan jenis anotasi.
Di sisi lain, perintah analyze Chasten melakukan analisis AST pada kode sumber Python. Ini memungkinkan pengguna untuk menentukan nama proyek, versi XPath, jalur pencarian, dan berbagai kriteria penyaringan. CHASTEN mendukung pemeriksaan untuk dimasukkan dan pengecualian berdasarkan atribut, nilai, dan tingkat kepercayaan. Alat ini juga menyediakan opsi konfigurasi yang luas dan kemampuan untuk menyimpan hasil dalam format yang berbeda, termasuk markdown.
Singkatnya, sementara keduanya Chasten dan Symbex melayani tujuan umum dari menganalisis kode sumber Python, Chasten menawarkan CLI yang lebih fleksibel dan ramah pengguna dengan fitur tambahan konfigurasi dan manajemen hasil. Symbex, di sisi lain, mengadopsi CLI ringkas dengan fokus pada pencarian dan penyaringan fungsionalitas. Pilihan antara kedua alat tergantung pada preferensi pengguna dan persyaratan spesifik untuk analisis kode Python.
Selain Chasten dan Symbex, beberapa alat lain menawarkan kemampuan unik untuk menganalisis dan mencari melalui kode sumber Python, masing -masing melayani kasus penggunaan tertentu.
