مرجع السكربتات

تُوثّق هذه الصفحة واجهة برمجة التطبيقات العامة (public headless scripting API) المعروضة عبر حزمة Python المسماة studio.

تركز الوثائق على الرموز العامة التالية:

• StudioScenario

• install_logging_event

• enable_logging_stdout

• disable_logging_stdout

إذا لم تقُم بتشغيل سيناريو في الوضع headless مسبقًا، فاقرأ قسم Headless أولاً ثم عد إلى هنا للحصول على تفاصيل الـ API.

---

الاستيراد

كل واجهات الـ API الموثقة هنا يتم تصديرها من الحزمة العلوية studio:

from studio import (
	StudioScenario,
	install_logging_event,
	enable_logging_stdout,
	disable_logging_stdout,
)

---

تعريفات الأنواع (Type Stubs)

السطح العام للعمل في الوضع headless يمكن إيجاده كالتالي:

from __future__ import annotations

from typing import Any, Callable, Optional


def enable_logging_stdout() -> None: ...
def disable_logging_stdout() -> None: ...
def install_logging_event(event: Callable[[str], None]) -> None: ...


class StudioScenario:
	def __init__(self, *, verification_code: str = "") -> None: ...

	def load_scenario(self, path: str) -> Optional[StudioScenario]: ...
	def load_scenario_raw(self, content: str) -> bool: ...
	def save_scenario(self, path: str) -> bool: ...
	def clear_scenario(self) -> bool: ...
	def disable_load_errors(self) -> StudioScenario: ...
	def load_custom_nodes(self, path: str) -> bool: ...

	def get_ports(
		self,
		input_op_title: str = "Subsystem In",
		output_op_title: str = "Subsystem Out",
	) -> dict[str, list[str]]: ...
	def get_name(self) -> str: ...

	def run(self, args: tuple[Any, ...] = ()) -> tuple[list[Any], ...]: ...
	def run_server(
		self,
		inputs: tuple[Any, ...] = (),
		host: str = "127.0.0.1",
		port: int = 8080,
		display_controls: bool = False,
		header: str = "Scenario Server",
	) -> None: ...
	def cleanup(self) -> bool: ...

	def enable_logging_stdout(self) -> StudioScenario: ...
	def disable_logging_stdout(self) -> StudioScenario: ...
	def install_logging_hook(self, hook: Callable[[str, int], None], level: int = 0) -> StudioScenario: ...

	def installStartEvent(self, event: Callable[..., None]) -> StudioScenario: ...
	def installEndEvent(self, event: Callable[..., None]) -> StudioScenario: ...
	def installStepStartEvent(self, event: Callable[..., None]) -> StudioScenario: ...
	def installStepEndEvent(self, event: Callable[..., None]) -> StudioScenario: ...

---

StudioScenario

StudioScenario هو نقطة الدخول الرئيسية لعمليات تحميل وتشغيل ملف .pmod بدون واجهة سطح المكتب (desktop UI).

المُنشئ

scenario = StudioScenario(verification_code="...")

verification_code

تُستخدم هذه القيمة لتكوين الترخيص (licensing) للتنفيذ في الوضع headless.

الأنماط الشائعة:

• جهاز محلي / خادم: مرّر سلسلة رمز التحقق (verification code).

• Docker / CI: قم بتركيب ملف الترخيص داخل الحاوية ومرّر مسار الملف (path) كـ verification_code.

بالنسبة للبيئات غير التفاعلية (مثل Docker/CI/الخدمات)، مرّر دائمًا verification_code بشكل صريح.

---

دورة الحياة النموذجية

في معظم السكربتات ستقوم بالخطوات التالية:

1. إنشاء السيناريو (StudioScenario(...))

2. تحميل ملف .pmod (load_scenario(...))

3. تشغيله (run(...))

4. التنظيف (cleanup())

import os

from studio import StudioScenario, enable_logging_stdout


def main() -> None:
	# اختياري: يعرض سجلات التشغيل إلى stdout (مفيد عند التصحيح).
	enable_logging_stdout()

	verification_code = os.environ.get("AUGELAB_VERIFICATION_CODE", "")
	scenario = StudioScenario(verification_code=verification_code)

	try:
		loaded = scenario.load_scenario("your_scenario.pmod")
		if loaded is None:
			raise FileNotFoundError("Could not load .pmod file")

		# If your scenario has N input ports, you must pass exactly N args.
		result = scenario.run(args=())
		print("Scenario result:", result)
	finally:
		scenario.cleanup()


if __name__ == "__main__":
	main()

cleanup() مهم في العمليات طويلة التشغيل (خدمات، مهام دفعية) لتحرير الذاكرة وإعادة ضبط حالة وقت التشغيل.

---

تحميل ملف .pmod

scenario.load_scenario("path/to/scenario.pmod")

• تُرجع StudioScenario عند النجاح.

• تُرجع None إذا كان المسار غير موجود.

إذا كان السيناريو يشير إلى موارد خارجية، فاحفظ نفس هيكل المجلدات المستخدم على سطح المكتب (راجع قسم “Transferring .pmod files”).

---

تشغيل سيناريو

outputs = scenario.run(args=(... ,))

يتحقق وقت التشغيل من أن عدد الوسائط (arguments) يطابق عدد مداخل السيناريو.

إذا كان ملف .pmod يحتوي على:

• 0 مدخلات: استدعِ scenario.run() أو scenario.run(())

• مدخل واحد: استدعِ scenario.run((value,))

• مدخلان: استدعِ scenario.run((value1, value2))

يجب أن يكون args عبارة عن tuple. للمُدخل الواحد، تذكّر الفاصلة في النهاية: (value,).

---

مزيد من أساليب StudioScenario

يغطي هذا القسم طرقًا عامة إضافية يمكن استخدامها للأتمتة والتصحيح.

التحميل بدون الفشل عند عدم وجود موارد

إذا كنت تنقل سيناريوهات بين آلات/حاويات وبعض الموارد قد تكون غير متاحة، يمكنك التحميل بتسامح أكبر:

from studio import StudioScenario

scenario = StudioScenario(verification_code="YOUR_CODE")
scenario.disable_load_errors()
scenario.load_scenario("scenario.pmod")

التحميل / الحفظ

scenario.load_scenario_raw(content="...")
scenario.save_scenario("out.pmod")
scenario.clear_scenario()

العقد المخصصة (Custom nodes)

تحميل وحدات Python للعقد المخصصة من مجلد:

scenario.load_custom_nodes("path/to/custom_nodes")

هذا يستورد ملفات Python ديناميكيًا. قم بتحميل كود موثوق فقط.

اسم السيناريو

name = scenario.get_name()

المنافذ (مدخلات/مخرجات السيناريو)

يمكنك استعلام أسماء منافذ الإدخال/الإخراج:

ports = scenario.get_ports()
print("inputs:", ports["inputs"])
print("outputs:", ports["outputs"])

تشغيل خادم ويب (اختياري)

إذا رغبت في كشف مشغل السيناريو عبر HTTP:

scenario.run_server(host="0.0.0.0", port=8080)

الأحداث (Events)

تثبيت ردود نداء (callbacks) حول دورة حياة تنفيذ السيناريو:

def on_start() -> None:
	print("Scenario started")


scenario.installStartEvent(on_start)

---

مساعدات السجل (Logging Helpers)

يمتلك AugeLab Studio نظام سجل وقت تشغيل يُستخدم بواسطة البلوكات والسيناريوهات. في الوضع headless عادةً تريد أحد الخيارات التالية:

• طباعة السجلات إلى stdout أثناء التطوير

• إعادة توجيه السجلات إلى نظام التسجيل الخاص بك

تلك المساعدات عامة (global) وتؤثر على مسجل وقت التشغيل المستخدم بواسطة سيناريوهاتك في الوضع headless.

---

enable_logging_stdout()

يفعّل طباعة سجلات وقت التشغيل بشكل "موجَّه" إلى stdout.

استخدم هذا عندما تريد رؤية سجلات البلوكات/السيناريو في الكونسول:

from studio import enable_logging_stdout

enable_logging_stdout()

---

disable_logging_stdout()

يعطّل طباعة سجلات وقت التشغيل إلى stdout.

مفيد عندما:

• تستخدم install_logging_event(...) وتريد تجنب تكرار السجلات

• تريد إخراجًا نظيفًا (فقط مخرجات print(...) أو سجلك الخاص)

from studio import disable_logging_stdout

disable_logging_stdout()

---

install_logging_event(event: Callable[[str], None])

يثبت رد نداء يستقبل رسائل السجل في وقت التشغيل.

هذا أسهل طريقة لدمج سجلات AugeLab في إطار تسجيل الخاص بك.

import logging

from studio import install_logging_event, disable_logging_stdout

logger = logging.getLogger("augelab")


def forward_to_python_logging(msg: str) -> None:
	logger.info(msg)


disable_logging_stdout()
install_logging_event(forward_to_python_logging)

StudioScenario.install_logging_hook(hook, level=0)

إذا فضّلت تثبيت hook على مستوى السيناريو مع تصفية بمستوى محدد، استخدم:

def hook(msg: str, level: int) -> None:
	print(level, msg)


scenario.install_logging_hook(hook, level=20)

اجعل رد النداء سريعًا. إذا كنت بحاجة لإجراء عمل ثقيل (I/O، شبكة)، فكّر في تخزين الرسائل مؤقتًا ومعالجتها في خيط/عملية أخرى.

---

أنماط موصى بها

1) متغير بيئي لترخيص التشغيل

بالنسبة للسكربتات التي تعمل في بيئات مختلفة (محلي مقابل CI مقابل Docker)، تمرير verification_code عبر متغير بيئي يجعل الشيفرة قابلة للنقل:

import os
from studio import StudioScenario

scenario = StudioScenario(verification_code=os.environ["AUGELAB_VERIFICATION_CODE"])

2) التنظيف دائمًا باستخدام try/finally

from studio import StudioScenario

scenario = StudioScenario(verification_code="YOUR_CODE")
try:
	scenario.load_scenario("scenario.pmod")
	scenario.run(())
finally:
	scenario.cleanup()