chasten
v0.2.0: Merge pull request #81 from AstuteSource
Chasten هو برنامج Python يستخدم تعبيرات XPath للعثور على أنماط في شجرة بناء الجملة المجردة (AST) لبرنامج Python. يمكنك استخدام Chasten لتنفيذ قواعد linting القابلة للتكوين الخاصة بك بسرعة ، دون الحاجة إلى استخدام إطار تحليل AST المعقد أو اللجوء إلى تعبيرات غير دقيقة.
هل ترغب في التأكد من أن برنامج Python ليس لديه أي تدوير ثلاثي for داخل وظائف async ؟ أو هل تريد أن تؤكد أن كل وظيفة داخل برنامج Python الخاص بك لديها التعليقات التوضيحية من النوع وتعليق Docstring؟ يمكن أن تساعد Chasten ! يتيح لك التعبير عن هذه الشيكات - والعديد من أنواع التحليلات الأخرى أيضًا - في ملفات YAML البسيطة التي تحتوي على تعبيرات XPath.
chasten (الفعل المتعدل) "لإدراك شخص ما الفشل أو فعل خطأ ما" ، قاموس كامبريدج.
chasten (الاسم الذي لا يمكن اعتباره أو المفرد) "أداة تحلل شجرة بناء الجملة المجردة لبرنامج Python للكشف عن مصادر محتملة لأخطاء المبرمجين لمنع فشل البرنامج" ، مطوري Astutesource.
chasten ذكّرني بإضافة Docstrings واكتب التعليقات التوضيحية لجميع الوظائف في main.py كان من السهل معرفة ما يجب إصلاحه!"chasten من السهل على تأكيد أن برامج الطلاب لديها بنيات الترميز المطلوبة. إنه أفضل بكثير من استخدام التعبيرات العادية!"chasten من السهل بالنسبة لي إجراء تحليل أتمتة لقاعدة كود بيثون التي أحافظ عليها."chasten 's Analysis Mashoving Succite Scode Source Screen Beachde ، لاستكشاف البيانات التي أجمعها بشكل فعال." اتبع هذه الخطوات لتثبيت برنامج chasten :
pipx install chasten لتثبيت Chastenpipx list وتأكد من تثبيت Chastenchasten --help لمعرفة كيفية استخدام الأداة يمكنك تكوين chasten مع ملفين yaml ، يسمى عادة config.yml و checks.yml . على الرغم من أن chasten يمكنه إنشاء تكوين البداية ، يمكنك التحقق من؟ مستودع AstuteSource/Chasten-Configuration على سبيل المثال (S) لملفات التكوين التي تقوم بإعداد الأداة. على الرغم من أن ملف config.yml يمكنه الرجوع إلى ملفات التكوين المتعددة ، فإن هذا المثال يوضح كيفية تحديد ملف checks.yml واحد:
# chasten configuration
chasten :
# point to a single checks file
checks-file :
- checks.yml يجب أن يحتوي ملف checks.yml على واحد أو أكثر من الشيكات. ما يلي هو مثال على ملف تكوين الشيك مع اثنين من الشيكات التي تجد على التوالي أول خط قابلة للتنفيذ من وظائف عدم الاختبار والاختبار في مشروع Python. لاحظ أن سمة pattern تحدد تعبير XPath الإصدار 2.0 الذي سيستخدمه chasten للكشف عن النوع المحدد من وظيفة Python. يمكنك كتابة chasten configure validate --config <path to chasten-configuration/ directory | config url> بعد ملء <path to chasten-configuration/directory | config url> مع الاسم المؤهل بالكامل لدليل التكوين الخاص بك وستؤكد الأداة أن التكوين الخاص بك يفي بمواصفات الأداة. يمكنك أيضًا استخدام الأمر chasten configure create لإنشاء تكوين بدء تلقائيًا! تكوين chasten configure --help يشرح help كيفية تكوين الأداة.
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 نظرًا لأن chasten يحتاج إلى مشروع مع رمز المصدر Python كمدخلات إلى MOMMAND analysis ، يمكنك استنساخ؟ Astutesource/lazytracker و؟ مستودعات Astutesource/Multicounter التي هي شوكات من مشاريع Python الحالية التي تم إنشاؤها لتحليل مريح. لتحليل هذين المشروعين بشكل متزايد مع chasten ، يمكنك كتابة الأوامر التالية لإنتاج ملفات JSON لكل مشروع:
subject-data/ دليل يحتوي على lazytracker/ Directory ، يمكنك تشغيل الأمر chasten analyze لبرنامج 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 يمكنك الآن مسح الإخراج لتأكيد أنه ، على سبيل المثال ، يجد chasten 6 وظائف اختبار في مشروع lazytracker . إذا نظرت إلى دليل subject-data/lazytracker ، فستجد ملف JSON يحمل اسمًا مثل chasten-results-lazytracker-20230823162341-4c23fc443a6b4c4aa09886f1ecb96e9f.json . سيؤدي تشغيل chasten على هذا البرنامج إلى أكثر من مرة ينتج عن ملف نتائج جديد مع طابع زمني مختلف (أي 20230823162341 ) ومعرف فريد (أي 4c23fc443a6b4c4aa09886f1ecb96e9f ) في اسمه ، مما يضمن أنك لا تكتب عن طريق الخطأ عن النتائج السابقة --save
بعد إنشاء دليل multicounter/ في subject-data/ الدليل الحالي ، يمكنك تشغيل أمر chasten analyze لبرنامج 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 يمكنك الآن مسح الإخراج لتأكيد أنه ، على سبيل المثال ، يجد chasten 10 وظائف اختبار في مشروع multicounter . إذا نظرت إلى دليل subject-data/lazytracker ، فستجد ملف JSON يحمل اسمًا مثل chasten-results-multicounter-20230821171712-5c52f2f1b61b4cce97624cc34cb39d4f.json و COMPONATES التي تشبه ملف JSONTER من أجل multicounter .
نظرًا لأن التحقق all-test-function-definition يحدد أن البرنامج يجب أن يكون لديه ما بين 1 و 10 اختبارات ستلاحظ أن هذا الفحص يمر لكل من lazytracker و multicounter . هذا يعني أن chasten إرجاع رمز خطأ 0 للتواصل مع نظام التشغيل الخاص بك الذي تم تمرير الشيك.
يمكنك معرفة المزيد حول كيفية استخدام analyze SUBLING COMMAND من خلال كتابة chasten analyze --help . على سبيل المثال ، تدعم chasten خيارات --check-include و --check-exclude والتي تسمح لك بتضمين واستبعاد شيكات محددة على التوالي وفقًا لقواعد المطابقة الغامضة التي يمكنك تحديدها لأي من سمات الشيكات المحددة في ملف checks.yml .
بعد تشغيل chasten على برامج lazytracker و multicounter ، يمكنك دمج ملفات JSON الفردية في ملف JSON واحد ، وملفات CSV ذات الصلة ، وقاعدة بيانات SQLite. بمجرد قيامك بإنشاء integrated-data/ ، يمكنك كتابة هذا الأمر لأداء التكامل:
chasten integrate all-programs
< path to subject-data > / ** / * .json
--save-directory < path to the integrated-data/ directory > csv/ ينتج هذا الأمر دليلًا مثل chasten chasten.db chasten-flattened-csvs-sqlite-db-all-programs-20230823171016-2061b524276b4299b04359ba30452923/ التي تحتوي قاعدة البيانات.
يمكنك معرفة المزيد حول integrate العمل الفرعي عن طريق كتابة chasten integrate --help .
عند استخدام الأمر chasten ، يمكن لإلحاق هذا -أن علامة --verbose يمكن أن يعزز بشكل كبير تجربة استكشاف الأخطاء وإصلاحها وتقديم فهم مفصل لوظيفة الأداة. فيما يلي مثال على 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 عند تنفيذ هذا الأمر ، يمكنك توقع أن يحتوي الإخراج على رسائل مفيدة مثل Matching source code: تشير إلى أن الأداة تقارن بشكل نشط رمز المصدر مع الأنماط المحددة. بالإضافة إلى ذلك ، ستتلقى نتائج مطابقة مفصلة ، مما يوفر رؤى حول الشيكات المحددة.
إذا كنت ترغب في إنشاء لوحة معلومات تحليل تفاعلية تستخدم؟ Simonw/DataSette يمكنك تشغيل chasten datasette-serve <path containing integrated results>/chasten.db --port 8001 . يمكنك الآن استخدام لوحة القيادة في متصفح الويب الخاص بك لتحليل النتائج أثناء دراسة الكود المصدري لهذه المشاريع مع المحرر الخاص بك! سوف يكشف دراسة النتائج عن chasten ، من خلال استخدامه؟ يستخدم Spookylukey/Pyastgrep بشكل صحيح تعبير XPath من أجل all-test-function-definition للعثور على السطر الأول من التعليمات البرمجية المصدر القابلة للتنفيذ داخل كل اختبار ، والتخطي على مستدلية الدالة والتعليقات الرائدة.
بالنسبة لبرنامج lazytracker ، ستلاحظ أن chasten تقارير أن هناك 6 حالات اختبار على الرغم من أن pytest يجد فقط ويدير 5 اختبارات. ويرجع ذلك إلى حقيقة أن tests/test_tracked.py Test Suite في lazytracker يحتوي على وظيفة تبدأ من test_ داخل وظيفة أخرى تبدأ بـ test_ . يوضح هذا المثال القيود المفروضة على التحليل الثابت مع chasten ! على الرغم من أن الأداة اكتشفت بشكل صحيح جميع "وظائف الاختبار" ، فإن تعشيش الوظائف في جناح الاختبار يعني أن pytest سيقوم بتشغيل وظيفة test_ الخارجية واستخدام وظيفة test_ الداخلية لأغراض الاختبار.
مع ذلك ، يجد chasten بشكل صحيح كل اختبار لمشروع multicounter . يمكنك متابعة كل خطوة من الخطوات السابقة في هذا المستند لتطبيق chasten على برنامج Python الخاص بك!
إذا كنت ترغب في إتاحة chasten.db بشكل عام للجميع للدراسة ، فيمكنك استخدام chasten datasette-publish SUBLIST. طالما أنك اتبعت تعليمات التثبيت؟ Simonw/DataSette-publish-fly و؟ Simonw/DataSette-Publish-Vercel ، يمكنك استخدام المكونات الإضافية لنشر خادم datasette العام الذي يستضيف chasten.db . على سبيل المثال ، يقوم تشغيل Command chasten datasette-publish <path containing integrated results>/chasten.db --platform vercel ستنشر نتائج من تشغيل chasten على lazytracker و multicounter إلى منصة Vercel.
الأهم من ذلك ، أن استخدام أمر chasten datasette-publish مع خيار- --platform vercel يتطلب منك أن تتبع الإرشادات السابقة لمكوّن الإضافات datasette-publish-vercel لتثبيت أداة سطر الأوامر vercel . يعد هذا ضروريًا لأنه على الرغم من أن datasette-publish-vercel هي واحدة من تبعيات chasten ، فلا توفر chasten أو datasette-publish-vercel أداة vercel على الرغم من أنها تستخدمها. يجب أن تتخذ خطوات مماثلة قبل نشر قاعدة البيانات الخاصة بك للطيران!
على الرغم من أن chasten هو تطبيق سطر الأوامر ، إلا أنك تقوم بإنشاء وسيطات وخيارات خط الأوامر بشكل تفاعلي من خلال واجهة مستخدم طرفية (TUI). لاستخدام الطريقة المستندة إلى TUI لإنشاء سطر أوامر كامل لـ chasten ، يمكنك كتابة Command chasten interact .
Chasten لديه سجل نظام مدمج. أثناء استخدام Chasten ، يمكنك استخدام Command chasten log إلى المحطة الخاصة بك. تتيح ميزة سجل النظام للمستخدم رؤية الأحداث والرسائل التي تنتجها chasten . بالإضافة إلى ذلك ، ستساعد ميزة chasten log في العثور على الأخطاء والأحداث التي أدت إلى حدوث خطأ. لكي يتم عرض برنامج chasten إلى سجل النظام ، سيتعين عليك فتح محطة منفصلة واستخدام chasten log . بالإضافة إلى كل أمر يتم تشغيله --debug-level <choice of level> و- --debug-dest SYSLOG يجب إضافته.
على سبيل المثال ، chasten datasette-serve --debug-level DEBUG --debug-dest SYSLOG < database path to file> إلى إنتاج الإخراج التالي في سجل النظام.
? 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
في كل أمر في chasten ، هناك خيار لإضافة --debug-level . يحتوي مستوى التصحيح على 5 خيارات تصحيح ، معلومات ، تحذير ، خطأ ، وحرج. سيظهر كل مستوى مشكلات مختلفة في سجل النظام حيث يكون التصحيح هو أدنى مستوى من المشكلات من الإدخال حيث يكون الحرج هو أعلى مستوى من الخطأ. للاستفادة من مزيد من المعلومات حول هذا ، يمكنك الرجوع إلى ملف 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. │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯
اتبع هذه الخطوات لتثبيت أداة chasten للتطوير المستقبلي:
بمجرد تثبيت Python والشعر ، يرجى الانتقال إلى مستودع Chasten على Github وتثبيت الأداة باستخدام أمر git clone في المحطة الخاصة بك. ثم انتقل إلى دليل Chasten وقم بتشغيل poetry install الأوامر لتثبيت جميع التبعيات.
هناك أيضًا خيار لاستخدام Docker لاستخدام chasten
اتبع هذه الخطوات للاستفادة من Docker:
cd في دليل Chasten حيث يوجد Dockerfiledocker build -t chasten . لبناء الحاويةdocker 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 نوع الحاويةdocker ps لعرض معلومات الحاويةdocker commit <your-container-id> <your-image-name> لحفظ تثبيت DependCychasten ! Black و Ruff على Chasten لضمان اتساق الكود ، وقابلية القراءة ، والالتزام بمعايير التنسيق المحددة مسبقًا عبر المشروع بأكمله ، مما يعزز في النهاية الصيانة والتعاون بين المطورين.poetry run task fiximports و/أو poetry run task fixformat قبل شحن ميزات جديدة. إذا تم شحن الميزات بمشكلات ضيقة ، فسوف ينهار البناء على Github بسبب فشل جناح الاختبار.Pytest Hypothesis التي تمكننا من تعزيز اتساق الكود ، وقابلية القراءة ، والمواءمة مع معايير التنسيق المعمول بها في جميع أنحاء المشروع. عند كتابة حالات الاختبار للميزات ، قم بإنشاء ملف جديد في دليل الاختبارات باستخدام test_(name of file) .poetry run task test لمعظم الحالات أو إذا كنت ترغب في اختبار ميزات API التي تعتمد على API Openai poetry run task test-api قبل الشحن. إذا تم شحن الميزات بدون مجموعة اختبار ، فسيتم تخفيض التغطية على Github بسبب إضافة الكود غير المختبرة وقد تؤدي إلى مشكلات أكبر في المستقبل. يعد كل من Chasten و Symbex ، الذي تم إنشاؤه بواسطة Simon Willison ، كلا من الأدوات المصممة لتحليل شفرة مصدر Python ، مع التركيز بشكل خاص على البحث عن الوظائف والفئات داخل الملفات. على الرغم من أنها تشترك في هدف مشترك ، إلا أن هناك اختلافات ملحوظة بين الاثنين ، وخاصة من حيث واجهات خط الأوامر والوظائف.
من حيث واجهة سطر الأوامر ، توظف Symbex CLI موجز ، باستخدام اختصارات لخيارات مختلفة. على سبيل المثال ، فإن الأمر للبحث عن توقيعات الوظائف في ملف يسمى test_debug.py كما يلي:
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 بالتعزيز على حزم Python مثل Typer و Rich لتوفير واجهة سطر أوامر سهلة الاستخدام وخصوصية. تتضمن الأوامر المتاحة لـ Chasten:
من حيث الوظيفة ، تم تصميم Symbex للبحث في رمز Python للوظائف والفئات حسب الاسم أو Wildcard. يوفر القدرة على تصفية النتائج استنادًا إلى معايير مختلفة ، بما في ذلك نوع الوظيفة (Async أو غير ASYNC) ، ووجود الوثائق ، والرؤية ، ونوع التعليقات التوضيحية.
من ناحية أخرى ، يقوم Command analyze الخاص بـ Chasten بإجراء تحليل AST على رمز مصدر Python. يسمح للمستخدمين بتحديد اسم المشروع ، وإصدار XPath ، ومسار البحث ، ومعايير التصفية المختلفة. يدعم Chasten عمليات التحقق من التضمين والاستبعاد بناءً على السمات والقيم ومستويات الثقة المطابقة. توفر الأداة أيضًا خيارات تكوين واسعة والقدرة على توفير النتائج بتنسيقات مختلفة ، بما في ذلك Markdown.
باختصار ، في حين أن كل من Chasten و Symbex يخدمان الغرض المشترك المتمثل في تحليل رمز مصدر Python ، فإن Chasten يوفر CLI أكثر تنوعًا وسهلة الاستخدام مع ميزات إضافية من التكوين وإدارة النتائج. Symbex ، من ناحية أخرى ، يتبنى CLI موجز مع التركيز على البحث وتصفية وظائف. يعتمد الاختيار بين الأداة على تفضيلات المستخدم والمتطلبات المحددة لتحليل رمز Python.
بالإضافة إلى Chasten و Symbex ، تقدم العديد من الأدوات الأخرى إمكانات فريدة لتحليل وبحث رمز مصدر Python ، كل تقديم الطعام لحالات الاستخدام المحددة.
