neurocarto.util.edit.script

class neurocarto.util.edit.script.BlueprintScript

A protocol class to represent a blueprint script function.

__call__(bp, *args, **kwargs)

Command structure

def example_script(bp: BlueprintFunctions):
    """Document"""
    bp.check_probe() # checking used probe
    ...

Available decorators

Generator script

Blueprint script function could be a generator by using yield keyword. Yielding a number to indicate the caller to wait for a given seconds. During running, the “Run” button will become “Stop”, in order to interrupt the running.

When interrupted, a KeyboardInterrupt will be raised. Blueprint script function can capture it for cleanup purpose, and then reraise it to the caller to let it handle the interrupting message. Otherwise, the caller will considered this script has a normal exit.

def generator_example_script(bp: BlueprintFunctions):
    yield 10 # wait 10 seconds
    yield # wait until next update tick

    try:
        yield 100
    except KeyboardInterrupt:
        ... # do something cleanup
        raise

Document script

We use reStructuredText format by default, so we format the document into html based on that rules.

def example_script(bp: BlueprintFunctions, a0: str, a1:int=0):
    """
    Document here.

    :param bp:
    :param a0: (type=default) parameter description
    :param a1: (int=0) as example.

    """

  • The line :param bp: will be removed.

  • The line :param PARA: will be replaced as a bold font (<b>).

  • The word **WORD** will be replaced as a bold font (<b>).

  • The word *WORD* will be replaced as an italic font (<em>).

And it will look like:

example_script(a0, a1)

Document here.


a0: (type=default) parameter description

a1: (int=0) as example.

Note that we do not fetch the typing information and default value via reflection. (only parameters’ name. Others would happen in the future, probability) The creator has to manually type those information in the document.

Parameters:
Return type:

None

__init__(*args, **kwargs)
class neurocarto.util.edit.script.BlueprintScriptInfo

A BlueprintScript holder

name: str

script name.

module: str | None

script module path expression in ‘MODUlE:NAME’

filepath: Path | None

actual module file path

time_stamp: float | None

module file last modified time.

script: BlueprintScript

script instance.

classmethod load(name, module_path)

Load a blueprint script.

Parameters:

  • name (str) – script name.

  • module_path (str) – script module path.

Returns:

Return type:

Self

check_changed()

Was source module file of the script modified from latest loading?

Returns:

True when it has modified at this moment.

Return type:

bool

reload()

Reload the script from source module file.

Returns:

Return type:

Self

script_use_probe()

Get the probe requirement.

Returns:

See:

use_probe()

Return type:

RequestChannelmapType | None

static __new__(_cls, name, module, filepath, time_stamp, script)

Create new instance of BlueprintScriptInfo(name, module, filepath, time_stamp, script)

Parameters:

  • name (str)

  • module (str | None)

  • filepath (Path | None)

  • time_stamp (float | None)

  • script (BlueprintScript)

script_use_view()

Get the view requirement

Returns:

See:

use_view()

Return type:

RequestView | None

eval(bp, script_input)

Eval script_input and invoke actual script function.

Although script_input should be a valid Python code, we cheat on the name resolution that take the undefined variable as a str by its name. For example, the following script_input will be considered:

(input) a,1,"b,3",d=4
(output) ("a", 1, "b,3", d=4)
(evaluation) __script_func__(bp, "a", 1, "b,3", d=4)

where __script_func__ and bp are preset in the evaluation context. (do not use them).

There are some limitations:

  • This function does not do the argument type validation.

  • If it contains operator, such as ‘.’ in filename, it fails.

  • for above case, use “” to quote them.

Parameters:
Returns:

blueprint script function’s return

Return type:

Any

__call__(bp, *args, **kwargs)

Invoke the script function.

Parameters:

  • bp (BlueprintFunctions)

  • args – script function’s positional arguments.

  • kwargs – script function’s keyword arguments.

Returns:

script function’s return.

Return type:

Any

neurocarto.util.edit.script.format_html_doc(doc)
Parameters:

doc (str)

Return type:

str

neurocarto.util.edit.script.script_html_doc(script)
Parameters:

script (BlueprintScriptInfo)

Return type:

str