Betik (Scripting) Referansı

Bu sayfa, studio Python paketinin sunduğu kamuya açık başsız (headless) betik API'sini belgelendirir.

Burada şu herkese açık sembollere odaklanır:

• StudioScenario

• install_logging_event

• enable_logging_stdout

• disable_logging_stdout

Daha önce bir senaryoyu başsız (UI olmadan) çalıştırmadıysanız önce Headless bölümünü okuyun, ardından API ayrıntarları için buraya geri dönün.

---

İçe Aktarımlar

Buradaki tüm API'ler üst seviye studio paketinden dışa aktarılır:

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

---

Tip İpuçları (Type Stubs)

Kamuya açık başsız yüzeyi şöyle görünür:

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, bir .pmod dosyasını masaüstü UI'sı olmadan yüklemek ve çalıştırmak için ana giriş noktasıdır.

Yapıcı (Constructor)

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

verification_code

Bu değer, başsız çalıştırma için lisanslamayı yapılandırmakta kullanılır.

Yaygın kullanım örnekleri:

• Yerel makine / sunucu: doğrulama kodu dizesini verin.

• Docker / CI: lisans dosyasını konteynere bağlayıp verification_code olarak dosya yolunu verin.

Uyarı: Etkileşimsiz ortamlarda (Docker/CI/servisler) verification_code değerini her zaman açıkça verin.

---

Tipik yaşam döngüsü

Çoğu betikte şu adımları izlersiniz:

1. Senaryoyu oluşturun (StudioScenario(...))

2. Bir .pmod yükleyin (load_scenario(...))

3. Çalıştırın (run(...))

4. Temizlik yapın (cleanup())

import os

from studio import StudioScenario, enable_logging_stdout


def main() -> None:
	# İsteğe bağlı: hata ayıklarken çalışma zamanı günlüklerini stdout'a yazdırır.
	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")

		# Eğer senaryonuzun N adet giriş portu varsa, tam olarak N argüman geçmelisiniz.
		result = scenario.run(args=())
		print("Scenario result:", result)
	finally:
		scenario.cleanup()


if __name__ == "__main__":
	main()

Bilgi: cleanup() uzun süre çalışan süreçlerde (servisler, batch işleri) belleği serbest bırakmak ve çalışma zamanı durumunu sıfırlamak için önemlidir.

---

Bir .pmod yükleme

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

• Başarılıysa StudioScenario döner.

• Yol mevcut değilse None döner.

Senaryonuz harici kaynaklara referans veriyorsa, masaüstünde kullandığınız aynı dizin yapısını koruyun (bkz. “Transferring .pmod files” bölümü).

---

Bir senaryoyu çalıştırma

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

Çalışma zamanı, argüman sayısının senaryodaki giriş sayısıyla eşleştiğini doğrular.

.pmod dosyanızda:

• 0 giriş varsa: scenario.run() veya scenario.run(()) çağırın

• 1 giriş varsa: scenario.run((value,)) çağırın

• 2 giriş varsa: scenario.run((value1, value2)) çağırın

Uyarı: args bir tuple olmalıdır. Tek giriş için sonuna virgül eklemeyi unutmayın: (value,).

---

Diğer StudioScenario Metodları

Bu bölüm, otomasyon ve hata ayıklama için kullanabileceğiniz ek herkese açık metodları kapsar.

Eksik kaynaklarda yüklemenin başarısız olmasını engelleme

Eğer senaryoları makineler/konteynerler arasında taşıyorsanız ve bazı kaynaklar eksik olabiliyorsa daha toleranslı yükleme seçeneğini kullanabilirsiniz:

from studio import StudioScenario

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

Yükleme / kaydetme

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

Özel düğümler (custom nodes)

Bir klasörden özel düğüm Python modüllerini yükleyin:

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

Uyarı: Bu, Python dosyalarını dinamik olarak içe aktarır. Yalnızca güvendiğiniz kodları yükleyin.

Senaryo adı

name = scenario.get_name()

Portlar (senaryo girişleri/çıkışları)

Giriş/çıkış port isimlerini sorgulayabilirsiniz:

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

Bir web sunucusu çalıştırma (isteğe bağlı)

Senaryo çalıştırıcısını HTTP üzerinden açmak isterseniz:

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

Olaylar (Events)

Senaryo yürütme yaşam döngüsüne ilişkin geri çağırmaları (callback) kurun:

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


scenario.installStartEvent(on_start)

---

Günlükleme (Logging) Yardımcıları

AugeLab Studio, bloklar ve senaryolar tarafından kullanılan bir çalışma zamanı kaydedicisine (logger) sahiptir. Başsız modda tipik olarak şu seçeneklerden birine ihtiyaç duyarsınız:

• geliştirme sırasında günlükleri stdout'a yazdırmak

• günlükleri kendi kayıt sisteminize iletmek

Bu yardımcılar globaldir (başsız senaryonuz tarafından kullanılan çalışma zamanı kaydedicisini etkiler).

---

enable_logging_stdout()

Çalışma zamanı günlüklerini stdout'a yazdırmayı etkinleştirir.

Konsolda blok/senaryo günlüklerini görmek istediğinizde kullanın:

from studio import enable_logging_stdout

enable_logging_stdout()

---

disable_logging_stdout()

Çalışma zamanı günlüklerinin stdout'a yazdırılmasını devre dışı bırakır.

Aşağıdaki durumlarda kullanışlıdır:

• install_logging_event(...) kullanıyor ve günlüklerin çift görünmesini istemiyorsanız

• yalnızca kendi print(...)/kendi logger çıktınızı görmek istiyorsanız

from studio import disable_logging_stdout

disable_logging_stdout()

---

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

Çalışma zamanı günlük mesajlarını alan bir geri çağırma (callback) kurar.

AugeLab çalışma zamanı günlüklerini kendi Python logging çerçevenize entegre etmenin en kolay yoludur.

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)

Eğer her bir senaryo için seviye filtrelemesiyle birlikte hook kurmayı tercih ediyorsanız, şu şekilde kullanın:

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


scenario.install_logging_hook(hook, level=20)

Uyarı: Geri çağırmanızı hızlı tutun. Ağır iş (I/O, ağ) gerekiyorsa mesajları tamponlayıp başka bir thread/process içinde işlemek daha iyidir.

---

Önerilen Kalıplar (Recommended Patterns)

1) Lisanslama için ortam değişkeni (Environment variable)

Yerel/CI/Docker gibi farklı ortamlarda çalışan betikler için verification_code değerini ortam değişkeni ile geçirmek kodun taşınabilirliğini artırır:

import os
from studio import StudioScenario

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

2) Her zaman try/finally ile cleanup

from studio import StudioScenario

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