5. script — Basic pyFormex script functions

The script module provides the basic functions available in all pyFormex scripts. These functions are available in GUI and NONGUI applications, without the need to explicitely importing the script module.

5.1. Functions defined in module script

script.Globals()

Return the globals that are passed to the scripts on execution.

When running pyformex with the –nogui option, this contains all the globals defined in the module formex (which include those from coords, arraytools and numpy.

When running with the GUI, this also includes the globals from gui.draw (including those from gui.color).

Furthermore, the global variable __name__ will be set to either ‘draw’ or ‘script’ depending on whether the script was executed with the GUI or not.

script.export(dic)

Export the variables in the given dictionary.

script.export2(names, values)

Export a list of names and values.

script.forget(names)

Remove the global variables specified in list.

script.forgetAll()

Delete all the global variables.

script.rename(oldnames, newnames)

Rename the global variables in oldnames to newnames.

script.listAll(clas=None, like=None, filtr=None, dic=None, sort=False)

Return a list of all objects in dictionary that match criteria.

• clas: a class or list of classes: if specified, only instances of this/these class(es) will be returned
• like: a string: if given, only object names starting with this string will be returned
• filtr: a function taking an object name as parameter and returning True or False. If specified, only objects passing the test will be returned.
• dic: a dictionary object with strings as keys, defaults to pyformex.PF.
• sort: bool: if True, the returned list will be sorted.

The return value is a list of keys from dic.

script.named(name)

Returns the global object named name.

script.getcfg(name, default=None)

Return a value from the configuration or None if nonexistent.

script.ask(question, choices=None, default='')

Ask a question and present possible answers.

If no choices are presented, anything will be accepted. Else, the question is repeated until one of the choices is selected. If a default is given and the value entered is empty, the default is substituted. Case is not significant, but choices are presented unchanged. If no choices are presented, the string typed by the user is returned. Else the return value is the lowest matching index of the users answer in the choices list. Thus, ask(‘Do you agree’,[‘Y’,’n’]) will return 0 on either ‘y’ or ‘Y’ and 1 on either ‘n’ or ‘N’.

script.ack(question)

Show a Yes/No question and return True/False depending on answer.

script.error(message)

Show an error message and wait for user acknowlegement.

script.autoExport(g)

Autoexport globals from script/app globals.

g: dict holding the globals dict from a script/app run enviroment.

This exports some objects from the script/app runtime globals to the pf.PF session globals directory. The default is to export all instances of class Geometry.

This can be customized in the script/app by setting the global variable autoglobals. If set to a value that evaluates to False, no autoexport will be done. If set to True, the default autoexport will be done: all instances of geometry. If set to a list of names, only the specified names will be exported. Furthermore, a global variable autoclasses may be set to a list of class names. All global instances of the specified classes will be exported.

Remember that the variables need to be globals in your script/app in order to be autoexported, and that autoglobals feature needs to be enabled in your configuration.

script.playScript(scr, name=None, filename=None, argv=[], encoding=None)

Play a pyformex script scr. scr should be a valid Python text.

There is a lock to prevent multiple scripts from being executed at the same time. This implies that pyFormex scripts can currently not be recurrent. If name is specified, set the global variable pyformex.scriptName to it when the script is started. If filename is specified, set the global variable __file__ to it.

script.breakpt(msg=None)

Set a breakpoint where the script can be halted on a signal.

If an argument is specified, it will be written to the message board.

The exitrequested signal is usually emitted by pressing a button in the GUI.

script.stopatbreakpt()

Set the exitrequested flag.

script.runScript(fn, argv=[])

Play a formex script from file fn.

fn is the name of a file holding a pyFormex script. A list of arguments can be passed. They will be available under the name argv. This variable can be changed by the script and the resulting argv is returned to the caller.

script.runApp(appname, argv=[], refresh=False, lock=True, check=True)

Run a pyFormex application.

A pyFormex application is a Python module that can be loaded in pyFormex and that contains a function ‘run()’. Running the application is equivalent to executing this function.

Parameters:

• appname: name of the module in Python dot notation. The module should live in a path included the the a file holding a pyFormex script.
• argv: list of arguments. This variable can be changed by the app and the resulting argv will be returned to the caller.

Returns the exit value of the run function. A zero value is supposed to mean a normal exit.

script.runAny(appname=None, argv=[], step=False, refresh=False, remember=True)

Run the current pyFormex application or script file.

Parameters:

• appname: either the name of a pyFormex application (app) or a file containing a pyFormex script. An app name is specified in Python module syntax (package.subpackage.module) and the path to the package should be in the configured app paths.

This function does nothing if no appname/filename is passed or no current script/app was set. If arguments are given, they are passed to the script. If step is True, the script is executed in step mode. The ‘refresh’ parameter will reload the app.

script.exit(all=False)

Exit from the current script or from pyformex if no script running.

script.quit()

Quit the pyFormex program

This is a hard exit from pyFormex. It is normally not called directly, but results from an exit(True) call.

script.processArgs(args)

Run the application without gui.

Arguments are interpreted as names of script files, possibly interspersed with arguments for the scripts. Each running script should pop the required arguments from the list.

script.setPrefs(res, save=False)

Update the current settings (store) with the values in res.

res is a dictionary with configuration values. The current settings will be update with the values in res.

If save is True, the changes will be stored to the user’s configuration file.

script.chdir(path, create=False)

Change the current working directory.

If path exists and it is a directory name, make it the current directory. If path exists and it is a file name, make the containing directory the current directory. If path does not exist and create is True, create the path and make it the current directory. If create is False, raise an Error.

Parameters:

• path: pathname of the directory or file. If it is a file, the name of the directory holding the file is used. The path can be an absolute or a relative pathname. A ‘~’ character at the start of the pathname will be expanded to the user’s home directory.
• create: bool. If True and the specified path does not exist, it will be created. The default is to do nothing if the specified path does not exist.

The changed to current directory is stored in the user’s preferences for persistence between pyFormex invocations.

script.pwdir()

Print the current working directory.

script.mkdir(path, clear=False, new=False)

Create a directory.

Create a directory, including any needed parent directories. Any part of the path may already exist.

• path: pathname of the directory to create, either an absolute or relative path. A ‘~’ character at the start of the pathname will be expanded to the user’s home directory.
• clear: bool. If True, and the directory already exists, its contents will be deleted.
• new: bool. If True, requires the directory to be a new one. An error will be raised if the path already exists.

The following table gives an overview of the actions for different combinations of the parameters:

clear	new	path does not exist	path exists
F	F	kept as is	newly created
T	F	emptied	newly created
T/F	T	raise	newly created

If successful, returns the tilde-expanded path of the directory. Raises an exception in the following cases:

• the directory could not be created,
• clear is True, and the existing directory could not be cleared,
• new is False, clear is False, and the existing path is not a directory,
• new is True, and the path exists.

script.runtime()

Return the time elapsed since start of execution of the script.

script.startGui(args=[])

Start the gui

script.writeGeomFile(filename, objects, sep=' ', mode='w', shortlines=False, **kargs)

Save geometric objects to a pyFormex Geometry File.

A pyFormex Geometry File can store multiple geometrical objects in a native format that can be efficiently read back into pyFormex. The format is portable over different pyFormex versions and even to other software.

• filename: the name of the file to be written. If it ends with ‘.gz’ or ‘.bz2’, the file will be compressed with gzip or bzip2, respectively.
• objects: a list or a dictionary. If it is a dictionary, the objects will be saved with the key values as there names. Objects that can not be exported to a Geometry File will be silently ignored.
• mode: can be set to ‘a’ to append to an existing file.
• sep: the string used to separate data. If set to an empty string, the data will be written in binary format and the resulting file will be smaller but less portable.
• kargs: more arguments are passed to geomfile.GeometryFile.write().

Returns the number of objects written to the file.

script.readGeomFile(filename, count=-1)

Read a pyFormex Geometry File.

A pyFormex Geometry File can store multiple geometrical objects in a native format that can be efficiently read back into pyformex. The format is portable over different pyFormex versions and even to other software.

• filename: the name of an existing pyFormex Geometry File. If the filename ends on ‘.gz’, it is considered to be a gzipped file and will be uncompressed transparently during the reading.

Returns a dictionary with the geometric objects read from the file. If object names were stored in the file, they will be used as the keys. Else, default names will be provided.