`sys` --- دوال خاصة بالنظام¶

توفر هذه الوحدة الوصول إلى المتغيرات والدوال الخاصة بالمفسّر، بما في ذلك وسائط سطر الأوامر، ومسار البحث عن الوحدات، والتدفقات القياسية، والمعلومات حول التنفيذ الجاري.

الدوال¶

sys.exit(retval: object = 0, /) → NoReturn¶

ينهي البرنامج الحالي برمز خروج معطى. ضمنياً، تثير هذه الدالة استثناء SystemExit. إذا أُعطي وسيط، فإن قيمته تُمرَّر كوسيط إلى SystemExit.

على OpenMV Cam، يؤدي استثناء SystemExit غير المعالَج حالياً إلى إعادة التعيين الناعمة لـ MicroPython.

sys.atexit(func: Callable[[], None] | None) → Callable[[], None] | None¶: يسجّل func ليتم استدعاؤه عند الإنهاء. يجب أن يكون func قابلاً للاستدعاء ولا يأخذ أي وسائط، أو None لتعطيل الاستدعاء. ستعيد دالة atexit القيمة السابقة التي ضبطتها هذه الدالة، والتي تكون مبدئياً None.

الفرق عن CPython

هذه الدالة هي امتداد من MicroPython يهدف إلى توفير وظيفة مشابهة لوحدة atexit في CPython.

sys.print_exception(exc: BaseException, file: Any = sys.stdout, /) → None¶: يطبع الاستثناء مع تتبّع للمكدس إلى كائن شبيه بالملف file (أو sys.stdout افتراضياً).

الفرق عن CPython

هذه نسخة مبسّطة من دالة تظهر في وحدة traceback في CPython. على عكس traceback.print_exception()، تأخذ هذه الدالة قيمة الاستثناء فقط بدلاً من نوع الاستثناء وقيمة الاستثناء وكائن التتبّع؛ يجب أن يكون الوسيط file موضعياً؛ والوسائط الإضافية غير مدعومة. يمكن العثور على وحدة traceback المتوافقة مع CPython في micropython-lib.

sys.settrace(tracefunc: Callable | None) → None¶

يُمكّن تتبّع تنفيذ البايت كود. للحصول على التفاصيل راجع وثائق CPython.

هذه الدالة غير متوفرة على OpenMV Cam. وهي معطّلة افتراضياً لأنها تبطئ تنفيذ الكود؛ ويتطلب تمكينها بناء برنامج ثابت مخصص.

الثوابت¶

sys.argv: list[str]¶: قائمة قابلة للتعديل بالوسائط التي بدأ بها البرنامج الحالي.

sys.byteorder: str¶: ترتيب البايتات في النظام ("little" أو "big").

sys.implementation: object¶

كائن يحتوي على معلومات حول تنفيذ Python الحالي. بالنسبة إلى MicroPython، يحتوي على السمات التالية:

name - السلسلة "micropython"
version - صف tuple (major, minor, micro, releaselevel)، على سبيل المثال (1, 22, 0, '')
_machine - سلسلة تصف الجهاز الأساسي
_mpy - إصدار صيغة ملف mpy المدعوم (سمة اختيارية)
_build - سلسلة يمكن أن تساعد في تحديد التهيئة التي بُني بها MicroPython
_thread - سمة سلسلة اختيارية، توجد إذا كان الهدف يدعم خيوط المعالجة وتكون إما "GIL" أو "unsafe"

هذا الكائن هو الطريقة الموصى بها لتمييز MicroPython عن تنفيذات Python الأخرى (لاحظ أنه قد لا يوجد في المنافذ الأدنى جداً).

ابتداءً من الإصدار 1.22.0-preview، العقدة الرابعة releaselevel في implementation.version هي إما سلسلة فارغة أو "preview".

أُضيف الإدخال _build في الإصدار 1.25.0 وهو مجموعة من العناصر مفصولة بشرطات. قد تُضاف عناصر جديدة في المستقبل، لذا من الأفضل الوصول إلى هذا الحقل باستخدام sys.implementation._build.split("-"). العناصر المستخدمة حالياً هي:

على OpenMV Cam، يكون العنصر الأول هو اسم اللوحة والعنصر الثاني (إن وُجد) هو متغيّر اللوحة.

أُضيف الإدخال _thread في الإصدار 1.26.0 وإذا كان موجوداً فإن الهدف يمتلك وحدة _thread. إذا مكّن الهدف الـ GIL (القفل العام للمفسّر) فإن هذه السمة تكون "GIL". وإلا فإن السمة تكون "unsafe" ويمتلك الهدف خيوط المعالجة لكنه لا يمكّن الـ GIL، ويجب حماية كائنات Python القابلة للتعديل (مثل bytearray و list و dict) المشتركة بين الخيوط بشكل صريح بواسطة أقفال مثل _thread.allocate_lock.

الفرق عن CPython

يفرض CPython سمات أكثر لهذا الكائن، لكن الحد الأدنى المفيد فعلياً منفّذ في MicroPython.

sys.maxsize: int¶

أقصى قيمة يمكن أن يحملها نوع عدد صحيح أصلي على المنصة الحالية، أو أقصى قيمة قابلة للتمثيل بنوع العدد الصحيح في MicroPython، إذا كانت أصغر من القيمة القصوى للمنصة (وهذا هو الحال في منافذ MicroPython بدون دعم الأعداد الصحيحة الطويلة).

هذه السمة مفيدة لاكتشاف "عدد البتات" للمنصة (32 بت مقابل 64 بت، إلخ). يُوصى بعدم مقارنة هذه السمة بقيمة ما مباشرة، وإنما بدلاً من ذلك حساب عدد البتات فيها:

bits = 0
v = sys.maxsize
while v:
    bits += 1
    v >>= 1
if bits > 32:
    # 64-bit (or more) platform
    ...
else:
    # 32-bit (or less) platform
    # Note that on 32-bit platform, value of bits may be less than 32
    # (e.g. 31) due to peculiarities described above, so use "> 16",
    # "> 32", "> 64" style of comparisons.

sys.modules: dict¶: قاموس بالوحدات المحمّلة. على OpenMV Cam لا يشمل هذا الوحدات المدمجة.

sys.path: list[str]¶: قائمة قابلة للتعديل بالأدلة التي يُبحث فيها عن الوحدات المستوردة.

الفرق عن CPython

في MicroPython، يشير إدخال بالقيمة ".frozen" إلى أن عملية الاستيراد يجب أن تبحث عن الوحدات المجمّدة عند تلك النقطة في البحث. إذا لم يُعثر على وحدة مجمّدة فإن البحث لن يبحث عن دليل باسم .frozen، بل سيتابع مع الإدخال التالي في sys.path.

sys.platform: str¶: المنصة التي يعمل عليها MicroPython. هذه سلسلة محددة من المنفذ/اللوحة -- على سبيل المثال "mimxrt" على OpenMV RT1060 و "alif" على OpenMV AE3 (تبلّغ بعض كاميرات OpenMV Cam الأقدم عن سلسلة خاصة بالطراز مثل "OpenMV4-H7"). للتحقق مما إذا كان برنامجك يعمل على MicroPython (مقابل تنفيذ Python آخر)، استخدم sys.implementation بدلاً من ذلك.

sys.ps1: str¶: سمة قابلة للتعديل تحمل السلسلة المستخدمة لموجّه REPL الأساسي. يعطي الافتراضي موجّه Python القياسي >>>. راجع أيضاً sys.ps2 لموجّه المتابعة.

sys.ps2: str¶: سمة قابلة للتعديل تحمل السلسلة المستخدمة لموجّه متابعة REPL. يعطي الافتراضي موجّه Python القياسي .... راجع أيضاً sys.ps1 للموجّه الأساسي.

sys.stderr: object¶: تدفق stream الخطأ القياسي.

sys.stdin: object¶: تدفق stream الإدخال القياسي.

sys.stdout: object¶: تدفق stream الإخراج القياسي.

sys.tracebacklimit: int¶

سمة قابلة للتعديل تحمل قيمة عدد صحيح هي الحد الأقصى لعدد إدخالات تتبّع المكدس المخزّنة في استثناء. اضبطها على 0 لتعطيل إضافة تتبّعات المكدس. القيمة الافتراضية 1000.

ملاحظة: هذه السمة غير متوفرة على OpenMV Cam.

sys.version: str¶: إصدار لغة Python الذي يتوافق معه هذا التنفيذ، كسلسلة نصية.

sys.version_info: tuple¶: إصدار لغة Python الذي يتوافق معه هذا التنفيذ، كصف tuple من الأعداد الصحيحة.

الفرق عن CPython

تُدعم أرقام الإصدار الثلاثة الأولى فقط (major, minor, micro) ويمكن الإشارة إليها بالفهرس فقط، وليس بالاسم.

sys --- دوال خاصة بالنظام¶

الدوال¶

الثوابت¶

`sys` --- دوال خاصة بالنظام¶