os --- خدمات "نظام التشغيل" الأساسية

تحتوي الوحدة os على دوال للوصول إلى نظام الملفات وتركيبه، وإعادة توجيه الطرفية ومضاعفتها، والدالتين uname و urandom.

الدوال العامة

os.uname() → Tuple[str, str, str, str, str]

تُعيد صفًا (tuple) (وقد يكون صفًا مسمّى) يحتوي على معلومات حول الجهاز الأساسي و/أو نظام تشغيله. يحتوي الصف على خمسة حقول بالترتيب التالي، كل منها سلسلة نصية:

  • sysname -- اسم النظام الأساسي

  • nodename -- الاسم الشبكي (قد يكون مماثلًا لـ sysname)

  • release -- إصدار النظام الأساسي

  • version -- إصدار MicroPython وتاريخ البناء

  • machine -- معرّف للعتاد الأساسي (مثل اللوحة أو وحدة المعالجة المركزية)

os.urandom(n: int) → bytes

تُعيد كائن بايتات يحتوي على n من البايتات العشوائية. المصدر مناسب تشفيريًا على كل كاميرا مدعومة، رغم أن التطبيق يختلف باختلاف المنفذ (port):

  • كاميرات STM32 (M4, M7, H7, H7+, PT, N6) تستخدم طرفية مولّد الأرقام العشوائية (RNG) العتادية في STM32.

  • كاميرات i.MX RT1062 (RT1060) تستخدم مولّد الأرقام العشوائية الحقيقي (TRNG) العتادي في الشريحة.

  • كاميرات Alif Ensemble (AE3) تستخدم خدمة الأرقام العشوائية العتادية في الحاوية الآمنة (Secure Enclave).

  • Arduino Nano 33 BLE Sense يستخدم طرفية مولّد الأرقام العشوائية (RNG) العتادية في nRF52.

  • Arduino Nano RP2040 Connect لا يحتوي على TRNG عتادي؛ يُزوَّد مولّد الأرقام شبه العشوائي (PRNG) في pico-sdk ببذرة ويُعاد مزجه باستمرار مع مصادر العشوائية الموجودة على شريحة RP2040.

الوصول إلى نظام الملفات

os.chdir(path: str) → None

تغيير الدليل الحالي.

os.getcwd() → str

الحصول على الدليل الحالي.

os.ilistdir(dir: str | None = None) → Iterator[Tuple]

تُعيد هذه الدالة مكرِّرًا (iterator) يُنتج بعد ذلك صفوفًا (tuples) تقابل العناصر في الدليل الذي تسرده. من دون وسيط تسرد الدليل الحالي، وإلا فتسرد الدليل المعطى بواسطة dir.

للصفوف الشكل (name, type, inode[, size]):

  • name هو سلسلة نصية (أو بايتات إذا كان dir كائن بايتات) وهو اسم العنصر؛

  • type هو عدد صحيح يحدد نوع العنصر، حيث 0x4000 للأدلة و 0x8000 للملفات العادية؛

  • inode هو عدد صحيح يقابل العقدة الفهرسية (inode) للملف، وقد يكون 0 لأنظمة الملفات التي لا تملك مثل هذا المفهوم.

  • size هو عدد صحيح قد يُضمَّن اعتمادًا على نوع نظام الملفات. بالنسبة لعناصر الملفات، تمثّل size حجم الملف أو -1 إذا كان غير معروف. أما معناها بالنسبة لعناصر الأدلة فهو غير محدد حاليًا.

os.listdir(dir: str | None = None) → List[str]

من دون وسيط، تسرد الدليل الحالي. وإلا فتسرد الدليل المعطى.

os.mkdir(path: str) → None

إنشاء دليل جديد.

os.remove(path: str) → None

إزالة ملف.

إزالة ملف. هذا اسم بديل لـ remove().

os.rmdir(path: str) → None

إزالة دليل.

os.rename(old_path: str, new_path: str) → None

إعادة تسمية ملف.

os.stat(path: str) → Tuple

الحصول على حالة ملف أو دليل.

os.statvfs(path: str) → Tuple

الحصول على حالة نظام ملفات.

تُعيد صفًا يحتوي على معلومات نظام الملفات بالترتيب التالي:

  • f_bsize -- حجم كتلة نظام الملفات

  • f_frsize -- حجم الجزء (Fragment)

  • f_blocks -- حجم نظام الملفات بوحدات f_frsize

  • f_bfree -- عدد الكتل الحرة

  • f_bavail -- عدد الكتل الحرة للمستخدمين غير المتميزين

  • f_files -- عدد العقد الفهرسية (inodes)

  • f_ffree -- عدد العقد الفهرسية الحرة

  • f_favail -- عدد العقد الفهرسية الحرة للمستخدمين غير المتميزين

  • f_flag -- رايات التركيب (Mount)

  • f_namemax -- الحد الأقصى لطول اسم الملف

المعاملات المتعلقة بالعقد الفهرسية: f_files و f_ffree و f_favail والمعامل f_flag قد تُعيد 0 إذ قد تكون غير متوفرة في تطبيق خاص بالمنفذ.

os.sync() → None

مزامنة جميع أنظمة الملفات.

os.sep: str

الفاصل بين مكوّنات المسار المستخدَم في نظام الملفات، وهو السلسلة النصية '/'.

إعادة توجيه الطرفية ومضاعفتها

os.dupterm(stream_object: Any, index: int = 0, /) → Any

مضاعفة أو تبديل طرفية MicroPython (الـ REPL) على الكائن الشبيه بـ stream المعطى. يجب أن يكون الوسيط stream_object كائن دفق (stream) أصليًا، أو مشتقًا من io.IOBase ومطبّقًا للطريقتين readinto() و write(). ينبغي أن يكون الدفق في النمط غير الحاجب وأن تُعيد readinto() القيمة None إذا لم تكن هناك بيانات متاحة للقراءة.

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

ينبغي أن يكون المعامل index عددًا صحيحًا غير سالب ويحدد أي فتحة مضاعفة (duplication slot) يتم تعيينها. قد يطبّق منفذ معين أكثر من فتحة (ستكون الفتحة 0 متاحة دائمًا) وفي هذه الحالة يُضاعَف إدخال وخرج الطرفية على جميع الفتحات المعيَّنة.

إذا مُرِّرت القيمة None كوسيط stream_object، فتُلغى المضاعفة على الفتحة المعطاة بواسطة index.

تُعيد الدالة الكائن الشبيه بالدفق السابق في الفتحة المعطاة.

os.dupterm_notify(obj_in: Any, /) → None

إخطار REPL الخاص بـ MicroPython بأن الإدخال متاح على كائن شبيه بالدفق سُجّل مسبقًا عبر os.dupterm().

ينبغي استدعاء هذه الدالة بواسطة تطبيقات الدفق المخصصة (مثل UART أو Bluetooth أو دفقات REPL أخرى غير USB) لإعلام REPL بأن الإدخال جاهز للقراءة. يضمن الاستخدام السليم أن تُعالَج الأحرف الخاصة مثل Ctrl+C (المستخدَم لإطلاق KeyboardInterrupt) بسرعة من قِبل REPL، بما يتيح سلوك المقاطعة المتوقع لشيفرة المستخدم.

يُتجاهَل المعامل obj_in من قِبل os.dupterm_notify()، لكنه مطلوب للسماح باستدعاء dupterm_notify من معالج مقاطعة مثل UART.irq().

مثال:

from machine import UART
import os
uart = UART(0)
os.dupterm(uart, 0)
uart.irq(os.dupterm_notify, machine.UART.IRQ_RX)

ملاحظة

إذا لم تُستدعَ الدالة dupterm_notify()، فقد لا يُكتشَف الإدخال من الدفق المخصص أو يُعالَج حتى استطلاع REPL التالي، مما قد يؤخر إطلاق KeyboardInterrupts أو إشارات تحكم أخرى. وهذا مهم بصفة خاصة لاتصالات UART و Bluetooth واتصالات REPL غير القياسية الأخرى، حيث لا يكون الإخطار التلقائي مضمونًا.

تركيب نظام الملفات

نُقلت الدوال والأصناف التالية إلى الوحدة vfs. وهي متوفرة في هذه الوحدة فقط من أجل التوافق مع الإصدارات السابقة وستُزال في الإصدار 2 من MicroPython.

os.mount(fsobj: Any, mount_point: str, *, readonly: bool = False) → None

تركيب كائن نظام الملفات fsobj عند الموقع في نظام الملفات الافتراضي (VFS) المعطى بواسطة السلسلة النصية mount_point. يمكن أن يكون fsobj كائن VFS لديه طريقة mount()، أو جهاز كتلة (block device). إذا كان جهاز كتلة فيُكتشَف نوع نظام الملفات تلقائيًا (يُطلَق استثناء إذا لم يُتعرَّف على أي نظام ملفات). قد تكون mount_point هي '/' لتركيب fsobj عند الجذر، أو '/<name>' لتركيبه عند دليل فرعي تحت الجذر.

إذا كانت readonly تساوي True فيُركَّب نظام الملفات للقراءة فقط.

خلال عملية التركيب تُستدعى الطريقة mount() على كائن نظام الملفات.

سيُطلق OSError(EPERM) إذا كانت mount_point مركّبة بالفعل.

os.mount() → List[Tuple[Any, str]]

من دون وسائط لـ mount()، تُعيد قائمة من الصفوف تمثّل جميع نقاط التركيب النشطة.

للقائمة المُعادة الشكل [(fsobj, mount_point), ...].

os.umount(mount_point: str | Any) → None

إلغاء تركيب نظام ملفات. يمكن أن تكون mount_point سلسلة نصية تسمّي موقع التركيب، أو كائن نظام ملفات سبق تركيبه. خلال عملية إلغاء التركيب تُستدعى الطريقة umount() على كائن نظام الملفات.

سيُطلق OSError(EINVAL) إذا لم تُوجد mount_point.

class os.VfsFat(block_dev: AbstractBlockDev)

إنشاء كائن نظام ملفات يستخدم تنسيق نظام ملفات FAT. تخزين نظام ملفات FAT يوفّره block_dev. يمكن تركيب الكائنات التي يُنشئها هذا المُنشئ باستخدام mount().

static mkfs(block_dev: AbstractBlockDev) → None

بناء نظام ملفات FAT على block_dev.

class os.VfsPosix(root: str | None = None)

إنشاء كائن نظام ملفات يصل إلى نظام ملفات POSIX المضيف. إذا حُدِّد root فينبغي أن يكون مسارًا في نظام ملفات المضيف لاستخدامه كجذر لكائن VfsPosix. وإلا فيُستخدَم الدليل الحالي لنظام ملفات المضيف.

ملاحظة

يتوفر VfsPosix على منفذ Unix فقط؛ وهو غير موجود على OpenMV Cam.