vulture
2.14 (2024-12-08)
يعثر Vulture على تعليمات برمجية غير مستخدمة في برامج Python. يعد هذا مفيدًا لتنظيف الأخطاء والعثور عليها في قواعد التعليمات البرمجية الكبيرة. إذا قمت بتشغيل Vulture على كل من مكتبتك ومجموعة الاختبار الخاصة بك، فيمكنك العثور على تعليمات برمجية لم يتم اختبارها.
نظرًا لطبيعة بايثون الديناميكية، فمن المرجح أن يفتقد محللو التعليمات البرمجية الثابتة مثل Vulture بعض التعليمات البرمجية الميتة. بالإضافة إلى ذلك، قد يتم الإبلاغ عن التعليمات البرمجية التي يتم استدعاؤها ضمنيًا فقط على أنها غير مستخدمة. ومع ذلك، يمكن أن تكون Vulture أداة مفيدة للغاية للحصول على جودة أعلى للتعليمات البرمجية.
--sort-by-size $ pip install vulture
$ vulture myscript.py # or
$ python3 -m vulture myscript.py
$ vulture myscript.py mypackage/
$ vulture myscript.py --min-confidence 100 # Only report 100% dead code.
قد تكون الوسائط المقدمة عبارة عن ملفات أو أدلة Python. لكل دليل، يقوم Vulture بتحليل جميع ملفات *.py المضمنة.
بعد العثور على التعليمات البرمجية الميتة وحذفها، قم بتشغيل Vulture مرة أخرى، لأنه قد يكتشف المزيد من التعليمات البرمجية الميتة.
بالإضافة إلى العثور على الوظائف والفئات غير المستخدمة وما إلى ذلك، يمكن لـ Vulture اكتشاف التعليمات البرمجية التي لا يمكن الوصول إليها. يتم تعيين قيمة ثقة لكل جزء من التعليمات البرمجية الميتة تتراوح بين 60% و100%، حيث تشير القيمة 100% إلى أنه من المؤكد أنه لن يتم تنفيذ التعليمات البرمجية. تعتبر القيم الأقل من 100% تقديرات تقريبية للغاية (استنادًا إلى نوع مجموعة التعليمات البرمجية) لمدى احتمال عدم استخدام التعليمات البرمجية.
| نوع الكود | قيمة الثقة |
|---|---|
| وسيطة الوظيفة/الطريقة/الفئة، رمز لا يمكن الوصول إليه | 100% |
| يستورد | 90% |
| سمة، فئة، وظيفة، طريقة، خاصية، متغير | 60% |
يمكنك استخدام علامة --min-confidence لتعيين الحد الأدنى من الثقة للكود الذي سيتم الإبلاغ عنه على أنه غير مستخدم. استخدم --min-confidence 100 للإبلاغ فقط عن التعليمات البرمجية المضمونة عدم استخدامها داخل الملفات التي تم تحليلها.
عندما يقوم Vulture بالإبلاغ عن أجزاء من التعليمات البرمجية بشكل غير صحيح على أنها غير مستخدمة، يكون لديك العديد من الخيارات لقمع النتائج الإيجابية الخاطئة. إذا كان إصلاح النتائج الإيجابية الخاطئة قد يفيد المستخدمين الآخرين أيضًا، فيرجى تقديم تقرير بالمشكلة.
الخيار الموصى به هو إضافة التعليمات البرمجية المستخدمة التي تم الإبلاغ عنها على أنها غير مستخدمة إلى وحدة Python وإضافتها إلى قائمة المسارات التي تم فحصها. للحصول على هذه القائمة البيضاء تلقائيًا، قم بتمرير --make-whitelist إلى Vulture:
$ vulture mydir --make-whitelist > whitelist.py
$ vulture mydir whitelist.py
لاحظ أن ملف whitelist.py الناتج سيحتوي على بناء جملة Python صالح، ولكن لكي تتمكن Python من تشغيله ، سيتعين عليك عادةً إجراء بعض التعديلات.
نقوم بجمع القوائم البيضاء لوحدات وحزم Python الشائعة في vulture/whitelists/ (نرحب بطلبات السحب).
إذا كنت تريد تجاهل ملف أو دليل بأكمله، فاستخدم المعلمة --exclude (على سبيل المثال، --exclude "*settings.py,*/docs/*.py,*/test_*.py,*/.venv/*.py" ). تتم مطابقة أنماط الاستبعاد مع المسارات المطلقة.
للتوافق مع Flake8، يدعم Vulture رموز الخطأ F401 وF841 لتجاهل الواردات غير المستخدمة ( # noqa: F401 ) والمتغيرات المحلية غير المستخدمة ( # noqa: F841 ). ومع ذلك، نوصي باستخدام القوائم البيضاء بدلاً من تعليقات noqa ، نظرًا لأن تعليقات noqa تضيف تشويشًا مرئيًا إلى الكود وتجعل قراءته أكثر صعوبة.
يمكنك استخدام --ignore-names foo*,ba[rz] للسماح لـ Vulture بتجاهل جميع الأسماء التي تبدأ بـ foo bar الأسماء و baz . بالإضافة إلى ذلك، يمكن استخدام خيار --ignore-decorators لتجاهل أسماء الدوال المزينة بمصمم الديكور المحدد (ولكن ليس وسائطها أو نص الدالة). يعد هذا مفيدًا على سبيل المثال في مشاريع Flask، حيث يمكنك استخدام --ignore-decorators "@app.route" لتجاهل جميع أسماء الوظائف باستخدام مصمم الديكور @app.route . لاحظ أن Vulture يبسط أدوات الديكور ولا يمكنه تحليلها: @foo.bar(x, y) يصبح "@foo.bar" و @foo.bar(x, y).baz يصبح "@" داخليًا.
نوصي باستخدام القوائم البيضاء بدلاً من --ignore-names أو --ignore-decorators كلما أمكن ذلك، حيث يتم التحقق من القوائم البيضاء تلقائيًا للتأكد من صحتها النحوية عند تمريرها إلى Vulture، وغالبًا ما يمكنك تمريرها إلى مترجم Python الخاص بك والسماح له بالتحقق من أن جميع القوائم البيضاء مدرجة في القائمة البيضاء. لا يزال الكود موجودًا بالفعل في مشروعك.
هناك مواقف لا يمكنك فيها إزالة المتغيرات غير المستخدمة، على سبيل المثال، في توقيعات الوظائف. الحل الموصى به هو استخدام الكلمة الأساسية del كما هو موضح في دليل PyLint وفي StackOverflow:
def foo ( x , y ):
del y
return x + 3 سوف يتجاهل Vulture أيضًا جميع المتغيرات التي تبدأ بشرطة سفلية، لذا يمكنك استخدام _x, y = get_pos() لوضع علامة على تعيينات المجموعة غير المستخدمة أو وسيطات الوظائف، على سبيل المثال، def foo(x, _y) .
ارفع الحد الأدنى لقيمة الثقة باستخدام علامة --min-confidence .
إذا اشتكت Vulture من التعليمات البرمجية مثل if False: فيمكنك استخدام العلامة المنطقية debug = False وكتابة if debug: بدلاً من ذلك. وهذا يجعل الكود أكثر قابلية للقراءة ويسكت Vulture.
انظر رقم 216. على سبيل المثال، بدلاً من def foo(arg: "Sequence"): ... ، نوصي باستخدام
from __future__ import annotations
def foo ( arg : Sequence ):
... يمكنك أيضًا تخزين وسيطات سطر الأوامر في pyproject.toml ضمن قسم tool.vulture . ما عليك سوى إزالة الشرطات البادئة واستبدال جميع الشرطات المتبقية بشرطات سفلية.
الخيارات المقدمة في سطر الأوامر لها الأسبقية على الخيارات الموجودة في pyproject.toml .
مثال التكوين:
[ tool . vulture ]
exclude = [ " *file*.py " , " dir/ " ]
ignore_decorators = [ " @app.route " , " @require_* " ]
ignore_names = [ " visit_* " , " do_* " ]
make_whitelist = true
min_confidence = 80
paths = [ " myscript.py " , " mydir " , " whitelist.py " ]
sort_by_size = true
verbose = true سوف يبحث Vulture تلقائيًا عن pyproject.toml في دليل العمل الحالي.
لاستخدام pyproject.toml في دليل آخر، يمكنك استخدام علامة --config path/to/pyproject.toml .
يمكنك استخدام خطاف ما قبل الالتزام لتشغيل Vulture قبل كل التزام. لهذا، قم بتثبيت الالتزام المسبق وأضف ما يلي إلى ملف .pre-commit-config.yaml في مستودعك:
repos :
- repo : https://github.com/jendrikseipp/vulture
rev : ' v2.3 ' # or any later Vulture version
hooks :
- id : vulture ثم قم بتشغيل pre-commit install . أخيرًا، قم بإنشاء ملف pyproject.toml في مستودعك وحدد جميع الملفات التي يجب على Vulture التحقق منها ضمن [tool.vulture] --> paths (انظر أعلاه).
هناك أيضًا GitHub Action for Vulture ويمكنك استخدام Vulture برمجيًا. على سبيل المثال:
import vulture
v = vulture . Vulture ()
v . scavenge ([ '.' ])
unused_code = v . get_unused_code () # returns a list of `Item` objects يستخدم Vulture الوحدة ast لإنشاء أشجار بناء جملة مجردة لجميع الملفات المحددة. أثناء اجتياز جميع أشجار بناء الجملة فإنه يسجل أسماء الكائنات المحددة والمستخدمة. وبعد ذلك، يقوم بالإبلاغ عن الكائنات التي تم تعريفها، ولكن لم يتم استخدامها. يتجاهل هذا التحليل النطاقات ويأخذ في الاعتبار أسماء الكائنات فقط.
يكتشف Vulture أيضًا التعليمات البرمجية التي لا يمكن الوصول إليها من خلال البحث عن التعليمات البرمجية بعد عبارات return break continue raise ، ومن خلال البحث عن شروط if - و while - غير المرضية.
عند استخدام خيار --sort-by-size ، يقوم Vulture بفرز التعليمات البرمجية غير المستخدمة حسب عدد الأسطر. يساعد هذا المطورين على تحديد أولويات مكان البحث عن التعليمات البرمجية الميتة أولاً.
خذ بعين الاعتبار نص بايثون التالي ( dead_code.py ):
import os
class Greeter :
def greet ( self ):
print ( "Hi" )
def hello_world ():
message = "Hello, world!"
greeter = Greeter ()
func_name = "greet"
greet_func = getattr ( greeter , func_name )
greet_func ()
if __name__ == "__main__" :
hello_world ()الاتصال :
$ vulture dead_code.py
يؤدي إلى الإخراج التالي:
dead_code.py:1: unused import 'os' (90% confidence)
dead_code.py:4: unused function 'greet' (60% confidence)
dead_code.py:8: unused variable 'message' (60% confidence)
يُبلغ Vulture بشكل صحيح عن os message على أنهما غير مستخدمين ولكنه يفشل في اكتشاف أن greet مستخدم بالفعل. الطريقة الموصى بها للتعامل مع النتائج الإيجابية الخاطئة مثل هذه هي إنشاء ملف Python بالقائمة البيضاء.
إعداد القوائم البيضاء
في القائمة البيضاء، نقوم بمحاكاة استخدام المتغيرات والسمات وما إلى ذلك. بالنسبة للبرنامج أعلاه، يمكن أن تبدو القائمة البيضاء كما يلي:
# whitelist_dead_code.py
from dead_code import Greeter
Greeter . greet وبدلاً من ذلك، يمكنك تمرير --make-whitelist إلى Vulture والحصول على قائمة بيضاء يتم إنشاؤها تلقائيًا.
تمرير كل من البرنامج الأصلي والقائمة البيضاء إلى Vulture
$ vulture dead_code.py whitelist_dead_code.py
يجعل Vulture يتجاهل طريقة greet :
dead_code.py:1: unused import 'os' (90% confidence)
dead_code.py:8: unused variable 'message' (60% confidence)
| رمز الخروج | وصف |
|---|---|
| 0 | لم يتم العثور على رمز ميت |
| 1 | إدخال غير صالح (ملف مفقود، خطأ في بناء الجملة، ترميز خاطئ) |
| 2 | وسيطات سطر الأوامر غير صالحة |
| 3 | تم العثور على رمز ميت |
يرجى زيارة https://github.com/jendrikseipp/vulture للإبلاغ عن أي مشكلات أو لتقديم طلبات السحب.
