webrepl --- خادم WebREPL

تكشف هذه الوحدة عن WebREPL الخاص بـ MicroPython: وهو REPL يستند إلى WebSocket يتيح للعملاء الاتصال بالموجّه التفاعلي للوحة (ونقل الملفات) عبر اتصال شبكي. وتعمل صفحة ثابتة صغيرة مستضافة على micropython.org/webrepl كعميل JavaScript.

يستمع WebREPL على منفذ TCP رقم 8266 افتراضيًا ويستخدم os.dupterm لتكرار REPL على دفق WebSocket. ولا يُدعم سوى عميل واحد متزامن؛ وتُرفض محاولات الاتصال الإضافية.

مثال:

import webrepl
webrepl.start(password="changeme")
# ... or load the password from webrepl_cfg.py:
# webrepl.start()

الدوال

webrepl.start(port: int = 8266, password: str | None = None, accept_handler=accept_conn) → None

بدء مستمع WebREPL.

إذا كان password هو None، فتُحمَّل كلمة المرور من webrepl_cfg.py (المُنشأ بواسطة webrepl_setup). وعندما يتعذر استيراد webrepl_cfg يُطبع تحذير ولا يُبدأ تشغيل الخادم.

يختار port منفذ TCP الذي يُستمع عليه.

accept_handler هو الكائن القابل للاستدعاء الذي يُستدعى عند اتصال عميل TCP جديد. والقيمة الافتراضية هي accept_conn، التي تنفّذ مصافحة WebSocket في دالة رد نداء على المقبس في الخلفية. مرّر None لتشغيل الخادم في وضع المقدمة (وهو ما يكافئ start_foreground).

webrepl.start_foreground(port: int = 8266, password: str | None = None) → None

غلاف ملائم حول start يشغّل حلقة القبول بشكل متزامن في المقدمة حتى يتصل عميل.

webrepl.stop() → None

إغلاق المقبس المستمع وأي اتصال عميل نشط، وفصل WebREPL عن الطرفية المكررة عبر os.dupterm(None).

webrepl.accept_conn(listen_sock) → bool

قبول اتصال TCP معلّق على listen_sock وإكمال مصافحة WebSocket. إذا كان عميل متصلًا بالفعل فيُرفض الاتصال الجديد ويُعاد False. وعند نجاح الترقية، يُغلَّف WebSocket الناتج بـ _webrepl._webrepl ويُربط كطرفية مكررة.

يُكشف عن هذا بشكل أساسي ليتمكن المُستدعون من تمريره كوسيط accept_handler إلى start.

webrepl.server_handshake(cl) → bool

قراءة طلب HTTP على المقبس cl المقبول حديثًا والرد بترويسات Sec-WebSocket-Accept المناسبة. يُعيد True إذا طلب العميل ترقية WebSocket صالحة، وFalse خلاف ذلك (وفي هذه الحالة يلجأ المُستدعي عادةً إلى تقديم عميل HTML عبر send_html).

webrepl.send_html(cl) → None

الرد على طلب HTTP على cl بمستند HTML بسيط يحمّل عميل WebREPL JavaScript من static_host ثم يغلق المقبس.

الثوابت

webrepl.DEBUG: int

اضبطه على قيمة غير صفرية لتمكين التتبع المفصّل لطلبات HTTP ومصافحات WebSocket على sys.stdout. القيمة الافتراضية هي 0.

webrepl.static_host: str

عنوان URL الأساسي لعميل WebREPL الثابت المستخدم بواسطة send_html. القيمة الافتراضية هي "https://micropython.org/webrepl/". ويمكن تجاوزها بضبط BASE في webrepl_cfg.py أو بإعادة تعيين سمة الوحدة مباشرةً.

webrepl.listen_s

المقبس المستمع النشط حاليًا، أو None إذا كان الخادم متوقفًا. يُضبط بواسطة start ويُمحى بواسطة stop.

webrepl.client_s

مقبس العميل المتصل حاليًا، أو None إذا لم يكن هناك عميل مربوط. يُضبط بواسطة accept_conn ويُمحى بواسطة stop.