acme.runtime.ScriptManager.ScriptManager

class documentation

class ScriptManager:

Constructor: ScriptManager()

This manager entity handles script execution in the CSE.

Method	`__init__`	Constructor for the ScriptManager class.
Method	`checkScriptUpdates`	This is the callback for the monitor to look for new, updated or outdated scripts.
Method	`configUpdate`	Callback for the configUpdate event.
Method	`cronMonitor`	This is the callback for the cron scheduler.
Method	`cseStarted`	Callback for the cseStartup event.
Method	`findScripts`	Find scripts by a filter.
Method	`getContext`	Returns the context for the given script name or None if not found.
Method	`initialize`	Initializer for the ScriptManager class.
Method	`loadScript`	Load and initialize a script. If no name is set in the script itself, then the filename's stem is set as the name.
Method	`loadScriptFromFile`	Load and store a script from a file.
Method	`loadScriptsFromDirectory`	Load all scripts from a (monitored) directory.
Method	`onKeyboard`	Callback for the keyboard event.
Method	`onNotification`	Callback for the notification event.
Method	`removeScripts`	Remove all scripts.
Method	`restart`	Callback for the cseReset event.
Method	`restartFinished`	Callback for the cseRestarted event.
Method	`run`	Run a script by its name (only in the foreground).
Method	`runComparisonQuery`	Run a comparison query against a JSON strcture or a resource.
Method	`runEventScripts`	Get and run all the scripts for specific events.
Method	`runScript`	Run a script.
Method	`shutdown`	Shutdown the ScriptManager.
Method	`storageGet`	Retrieve a key/value pair from the persistent storage storage.
Method	`storageHas`	Test whether a key exists in the persistent storage storageID.
Method	`storagePut`	Store a key/value pair in the persistent storage identified by storage. Existing values will be overwritten.
Method	`storageRemove`	Remove a key/value pair from the persistent storage.
Method	`storageRemoveStorage`	Remove all key/value pairs from the persistent storage.
Class Variable	`__slots__`	Slots of class attributes.
Class Variable	`importer`	Importer instance
Class Variable	`textUI`	TextUI plugin, if available.
Class Variable	`validator`	Validator instance.
Instance Variable	`categoryDescriptions`	Dictionary of category descriptions.
Instance Variable	`scriptCronWorker`	`BackgroundWorker` worker to run cron-enabled scripts.
Instance Variable	`scripts`	Dictionary of scripts and script `ACMEPContext`. The key is the script name.
Instance Variable	`scriptUpdatesMonitor`	`BackgroundWorker` worker to monitor script directories.
Instance Variable	`storage`	Dictionary for internal global variable storage.
Class Variable	`_allowedQuerySymbols`	Allowed symbols for comparison queries.

def __init__(self): ¶

Constructor for the ScriptManager class.

def checkScriptUpdates(self) -> bool: ¶

This is the callback for the monitor to look for new, updated or outdated scripts.

Returns
`bool`	Boolean. Usually True to continue with monitoring.

@onEvent(eventManager.configUpdate)

def configUpdate(self, eventData: EventData): ¶

Callback for the configUpdate event.

Parameters
eventData:`EventData`	The event data, containing the updated configuration key.

def cronMonitor(self) -> bool: ¶

This is the callback for the cron scheduler.

It looks for scripts with an @at meta tag and takes the argument as a cron pattern. Scripts that are scheduled to run now will be run, one after the other.

Returns
`bool`	Boolean. Usually True to continue with monitoring.

@onEvent(eventManager.cseStartup)

def cseStarted(self, eventData: EventData): ¶

Callback for the cseStartup event.

Start a background worker to monitor directories for scripts.

def findScripts(self, name: str | None = None, meta: str | list[str] | None = None, ignoreCase: bool = False) -> list[PContext]: ¶

Find scripts by a filter.

Filters are and-combined.

Parameters
name:`str \| None`	Filter by script name. The name can be a simple match.
meta:`str \| list[str] \| None`	Filter by script meta data. This can be a single string or a list of strings.
ignoreCase:`bool`	Undocumented

Returns
`list[PContext]`	List of `PContext` objects with the script(s), sorted by name, or None in case of an error.

def getContext(self, name: str) -> PContext | None: ¶

Returns the context for the given script name or None if not found.

Parameters
name:`str`	The name of the script.

Returns
`PContext \| None`	The context for the given script name or None if not found.

def initialize(self): ¶

Initializer for the ScriptManager class.

def loadScript(self, script: str, filename: str) -> ACMEPContext | None: ¶

Load and initialize a script. If no name is set in the script itself, then the filename's stem is set as the name.

The script is stored in the scripts dictionary.

Parameters
script:`str`	The script as a single string.
filename:`str`	The filename of the file.

Returns
`ACMEPContext \| None`	`ACMEPContext` object with the script, or None.

def loadScriptFromFile(self, filename: str) -> ACMEPContext | None: ¶

Load and store a script from a file.

Parameters
filename:`str`	The filename of the file.

Returns
`ACMEPContext \| None`	`ACMEPContext` object with the script, or None.

def loadScriptsFromDirectory(self, directory: str | list[str]) -> int: ¶

Load all scripts from a (monitored) directory.

Parameters
directory:`str \| list[str]`	The directory from which to load the scripts.

Returns
`int`	Number scripts loaded, or -1 in case of an error.

@onEvent(eventManager.keyboard)

def onKeyboard(self, eventData: EventData): ¶

Callback for the keyboard event.

Run script(s) with configured meta tags, if any.

Parameters
eventData:`EventData`	The event data, containing the pressed key.

@onEvent(eventManager.acmeNotification)

def onNotification(self, eventData: EventData): ¶

Callback for the notification event.

Run script(s) with configured meta tags, if any.

Parameters
eventData:`EventData`	The event data, containing the notification information. The first element is the notification URI, the second element is the request that caused the notification.

def removeScripts(self): ¶

Remove all scripts.

@onEvent(eventManager.cseReset)

def restart(self, eventData: EventData): ¶

Callback for the cseReset event.

Restart the script manager service, ie. clear the scripts and storage. They are reloaded during import.

@onEvent(eventManager.cseRestarted)

def restartFinished(self, eventData: EventData): ¶

Callback for the cseRestarted event.

Run the restart script(s), if any.

def run(self, scriptName: str, arguments: list[str] | str | None = '', metaFilter: list[str] | None = [], ignoreCase: bool | None = False) -> tuple[bool, SSymbol]: ¶

Run a script by its name (only in the foreground).

Parameters
scriptName:`str`	The name of the script to run..
arguments:`list[str] \| str \| None`	Optional arguments to the script. These are available to the script via the argv macro.
metaFilter:`list[str] \| None`	Extra filter to select a script.
ignoreCase:`bool \| None`	Undocumented

Returns
`tuple[bool, SSymbol]`	The result of the script run in a tuple. Boolean indicating success, and an optional result.

def runComparisonQuery(self, query: str, resource: JSON | Resource) -> bool: ¶

Run a comparison query against a JSON strcture or a resource.

The query consists of logical or comparison operations, and only those are allowed. It can contain attributes, which values are taken from the JSON structure or resource.

Parameters
query:`str`	String with a valid s-expression.
resource:`JSON \| Resource`	JSON dictionary or resource for the attributes.

Returns
`bool`	Boolean value indicating the success of the query.

def runEventScripts(self, event: str, eventData: str | None = None, background: bool | None = True, environment: dict[str, SSymbol] | None = {}): ¶

Get and run all the scripts for specific events.

If the argument is given then the event's parameter must match the argument.

This method is still called in the same thread as the console (the event is raised not in the background!), because otherwise the prompt input and the getch() function from the console are mixing up.

Parameters
event:`str`	The event for which the script(s) are run.
eventData:`str \| None`	The optional event data that needs to match the event's pararmeter of the script.
background:`bool \| None`	Run the script in the background
environment:`dict[str, SSymbol] \| None`	Extra variables to set in the script's environment

def runScript(self, pcontext: PContext, arguments: list[str] | str | None = '', background: bool | None = False, finished: Callable | None = None, environment: dict[str, SSymbol] | None = {}) -> bool: ¶

Run a script.

Parameters
pcontext:`PContext`	The script context to run.
arguments:`list[str] \| str \| None`	Optional arguments to the script. These are available to the script via the argv macro.
background:`bool \| None`	Boolean to indicate whether to run the script in the backhround (as an Actor).
finished:`Callable \| None`	An optional function that will be called after the script finished.
environment:`dict[str, SSymbol] \| None`	An optional set of variables that are passed to the script.

Returns
`bool`	Boolean that indicates the successful running of the script. A background script always returns True.

def shutdown(self) -> bool: ¶

Shutdown the ScriptManager.

Run the shutdown script(s) if present.

Returns
`bool`	Boolean, always True.

def storageGet(self, storage: str, key: str) -> SSymbol | None: ¶

Retrieve a key/value pair from the persistent storage storage.

Parameters
storage:`str`	Name or ID of the storage.
key:`str`	Key for the value to retrieve.

Returns
`SSymbol \| None`	Previously stored value for the key, or None.

def storageHas(self, storage: str, key: str) -> bool: ¶

Test whether a key exists in the persistent storage storageID.

Parameters
storage:`str`	Name or ID of the storage.
key:`str`	Key to check.

Returns
`bool`	Boolean result.

def storagePut(self, storage: str, key: str, value: SSymbol): ¶

Store a key/value pair in the persistent storage identified by storage. Existing values will be overwritten.

Args:

storage: Name or ID of the storage. key: Key where to store the value. value: Value to store.

def storageRemove(self, storage: str, key: str): ¶

Remove a key/value pair from the persistent storage.

Parameters
storage:`str`	Name or ID of the storage.
key:`str`	Key where to store the value.

def storageRemoveStorage(self, storage: str): ¶

Remove all key/value pairs from the persistent storage.

Parameters
storage:`str`	Name or ID of the storage.

__slots__: tuple[str, ...] = ¶

Slots of class attributes.

importer: Importer = ¶

Importer instance

textUI: TextUI | None = ¶

TextUI plugin, if available.

validator: Validator = ¶

Validator instance.

categoryDescriptions: dict[str, str] = ¶

Dictionary of category descriptions.

scriptCronWorker: BackgroundWorker = ¶

BackgroundWorker worker to run cron-enabled scripts.

scripts: dict[str, ACMEPContext] = ¶

Dictionary of scripts and script ACMEPContext. The key is the script name.

scriptUpdatesMonitor: BackgroundWorker = ¶

BackgroundWorker worker to monitor script directories.

storage: dict[str, dict[str, SSymbol]] = ¶

Dictionary for internal global variable storage.

_allowedQuerySymbols: tuple[str, ...] = ¶

Allowed symbols for comparison queries.