spinetoolbox.project_items.tool.tool_specifications

Contains Tool specification classes.

authors:
  1. Savolainen (VTT), E. Rinne (VTT), M. Marin (KTH)
date:

24.1.2018

Module Contents

Classes

ToolSpecification Super class for all tool specifications.
GAMSTool Class for GAMS tool specifications.
JuliaTool Class for Julia tool specifications.
PythonTool Class for Python tool specifications.
ExecutableTool Class for Executable tool specifications.
spinetoolbox.project_items.tool.tool_specifications.TOOL_TYPES = ['Julia', 'Python', 'GAMS', 'Executable'][source]
spinetoolbox.project_items.tool.tool_specifications.REQUIRED_KEYS = ['name', 'tooltype', 'includes'][source]
spinetoolbox.project_items.tool.tool_specifications.OPTIONAL_KEYS = ['description', 'short_name', 'inputfiles', 'inputfiles_opt', 'outputfiles', 'cmdline_args', 'execute_in_work'][source]
spinetoolbox.project_items.tool.tool_specifications.LIST_REQUIRED_KEYS = ['includes', 'inputfiles', 'inputfiles_opt', 'outputfiles'][source]
class spinetoolbox.project_items.tool.tool_specifications.ToolSpecification(name, tooltype, path, includes, settings, logger, description=None, inputfiles=None, inputfiles_opt=None, outputfiles=None, cmdline_args=None, execute_in_work=True)[source]

Bases: spinetoolbox.project_item_specification.ProjectItemSpecification

Super class for all tool specifications.

Parameters:
  • name (str) – Tool specification name
  • tooltype (str) – Type of Tool (e.g. Python, Julia, ..)
  • path (str) – Path to Tool specification
  • includes (list) – List of files belonging to the tool specification (relative to ‘path’)
  • settings (QSettings) – Toolbox settings
  • logger (LoggerInterface) – a logger instance
  • description (str) – Description of the Tool specification
  • inputfiles (list) – List of required data files
  • inputfiles_opt (list, optional) – List of optional data files (wildcards may be used)
  • outputfiles (list, optional) – List of output files (wildcards may be used)
  • cmdline_args (str, optional) – Tool command line arguments (read from tool definition file)
  • execute_in_work (bool) – Execute in work folder
save(self)[source]

Saves this specification to a .json file in the definition path.

Returns:How it went
Return type:bool
is_equivalent(self, definition)[source]

Checks if this spec is equivalent to the given definition dictionary. Used by the tool spec widget when updating specs.

Parameters:definition (dict) –
Returns:True if equivalent
Return type:bool
set_return_code(self, code, description)[source]

Sets a return code and an associated text description for the tool specification.

Parameters:
  • code (int) – Return code
  • description (str) – Description
static check_definition(data, logger)[source]

Checks that a tool specification contains the required keys and that it is in correct format.

Parameters:
  • data (dict) – Tool specification
  • logger (LoggerInterface) – A logger instance
Returns:

Dictionary or None if there was a problem in the tool definition.
get_cmdline_args(self, optional_input_files, input_urls, output_urls)[source]

Returns tool specification’s command line args as list.

Replaces special tags in arguments:

  • @@optional_inputs@@ expands to a space-separated list of Tool’s optional input files
  • @@url:<Data Store name>@@ expands to the URL provided by a named data store
  • @@url_inputs@@ expands to a space-separated list of Tool’s input database URLs
  • @@url_outputs@@ expands to a space-separated list of Tool’s output database URLs
Parameters:
  • optional_input_files (list) – a list of Tool’s optional input file names
  • input_urls (dict) – a mapping from URL provider (input Data Store name) to URL string
  • output_urls (dict) – a mapping from URL provider (output Data Store name) to URL string
Returns:

a list of expanded command line arguments
Return type:

list
create_tool_instance(self, basedir)[source]

Returns an instance of the tool specification configured to run in the given directory. Needs to be implemented in subclasses.

Parameters:basedir (str) – Path to directory where the instance will run
static toolbox_load(definition, definition_path, app_settings, logger, embedded_julia_console, embedded_python_console)[source]

Deserializes and constructs a tool specification from definition.

Parameters:
  • definition (dict) – a dictionary containing the serialized specification.
  • definition_path (str) – path to the definition file
  • app_settings (QSettings) – Toolbox settings
  • logger (LoggerInterface) – a logger
  • embedded_julia_console (JuliaREPLWidget, optional) – Julia console widget, required if a Julia tool is to be run in the console
  • embedded_python_console (PythonReplWidget, optional) – Python console widget, required if a Python tool is to be run in the console
Returns:

a tool specification constructed from the given definition,

or None if there was an error
Return type:

ToolSpecification
open_main_program_file(self)[source]

Open this specification’s main program file in the default editor.

class spinetoolbox.project_items.tool.tool_specifications.GAMSTool(name, tooltype, path, includes, settings, logger, description=None, inputfiles=None, inputfiles_opt=None, outputfiles=None, cmdline_args=None, execute_in_work=True)[source]

Bases: spinetoolbox.project_items.tool.tool_specifications.ToolSpecification

Class for GAMS tool specifications.

Parameters:
  • name (str) – GAMS Tool name
  • tooltype (str) – Tool specification type
  • path (str) – Path to model main file
  • includes (list) – List of files belonging to the tool (relative to ‘path’). # TODO: Change to src_files
  • settings (QSettings) – Toolbox settings
  • logger (LoggerInterface) – a logger instance
  • file in the list is the main GAMS program. (First) –
  • description (str) – GAMS Tool description
  • inputfiles (list) – List of required data files
  • inputfiles_opt (list, optional) – List of optional data files (wildcards may be used)
  • outputfiles (list, optional) – List of output files (wildcards may be used)
  • cmdline_args (str, optional) – GAMS tool command line arguments (read from tool definition file)
update_gams_options(self, key, value)[source]

[OBSOLETE?] Updates GAMS command line options. Only ‘cerr’ and ‘logoption’ keywords supported.

Parameters:
  • key (str) – Option name
  • value (int, float) – Option value
static load(path, data, settings, logger)[source]

Creates a GAMSTool according to a tool specification file.

Parameters:
  • path (str) – Base path to tool files
  • data (dict) – Dictionary of tool definitions
  • settings (QSettings) – Toolbox settings
  • logger (LoggerInterface) – A logger instance
Returns:

GAMSTool instance or None if there was a problem in the tool specification file.
create_tool_instance(self, basedir)[source]

Returns an instance of this tool specification that is configured to run in the given directory.

Parameters:basedir (str) – the path to the directory where the instance will run
class spinetoolbox.project_items.tool.tool_specifications.JuliaTool(name, tooltype, path, includes, settings, embedded_julia_console, logger, description=None, inputfiles=None, inputfiles_opt=None, outputfiles=None, cmdline_args=None, execute_in_work=True)[source]

Bases: spinetoolbox.project_items.tool.tool_specifications.ToolSpecification

Class for Julia tool specifications.

Parameters:
  • name (str) – Julia Tool name
  • tooltype (str) – Tool specification type
  • path (str) – Path to model main file
  • includes (list) – List of files belonging to the tool (relative to ‘path’). # TODO: Change to src_files
  • file in the list is the main Julia program. (First) –
  • settings (QSettings) – Toolbox settings
  • embedded_julia_console (JuliaREPLWidget) – a Julia console widget for execution in the embedded console
  • logger (LoggerInterface) – A logger instance
  • description (str) – Julia Tool description
  • inputfiles (list) – List of required data files
  • inputfiles_opt (list, optional) – List of optional data files (wildcards may be used)
  • outputfiles (list, optional) – List of output files (wildcards may be used)
  • cmdline_args (str, optional) – Julia tool command line arguments (read from tool definition file)
update_julia_options(self, key, value)[source]

[OBSOLETE?] Updates Julia command line options.

Parameters:
  • key (str) – Option name
  • value (int, float) – Option value
static load(path, data, settings, embedded_julia_console, logger)[source]

Creates a JuliaTool according to a tool specification file.

Parameters:
  • path (str) – Base path to tool files
  • data (dict) – Dictionary of tool definitions
  • settings (QSetting) – Toolbox settings
  • embedded_julia_console (JuliaREPLWidget) – a Julia console for execution in the embedded console
  • logger (LoggerInterface) – A logger instance
Returns:

JuliaTool instance or None if there was a problem in the tool definition file.
create_tool_instance(self, basedir)[source]

Returns an instance of this tool specification that is configured to run in the given directory.

Parameters:basedir (str) – the path to the directory where the instance will run
class spinetoolbox.project_items.tool.tool_specifications.PythonTool(name, tooltype, path, includes, settings, embedded_python_console, logger, description=None, inputfiles=None, inputfiles_opt=None, outputfiles=None, cmdline_args=None, execute_in_work=True)[source]

Bases: spinetoolbox.project_items.tool.tool_specifications.ToolSpecification

Class for Python tool specifications.

Parameters:
  • name (str) – Python Tool name
  • tooltype (str) – Tool specification type
  • path (str) – Path to model main file
  • includes (list) – List of files belonging to the tool (relative to ‘path’). # TODO: Change to src_files
  • settings (QSettings) – Toolbox settings
  • embedded_python_console (PythonReplWidget) – a Python console widget for embedded console execution
  • logger (LoggerInterface) – A logger instance
  • file in the list is the main Python program. (First) –
  • description (str) – Python Tool description
  • inputfiles (list) – List of required data files
  • inputfiles_opt (list, optional) – List of optional data files (wildcards may be used)
  • outputfiles (list, optional) – List of output files (wildcards may be used)
  • cmdline_args (str, optional) – Python tool command line arguments (read from tool definition file)
update_python_options(self, key, value)[source]

[OBSOLETE?] Updates Python command line options.

Parameters:
  • key (str) – Option name
  • value (int, float) – Option value
static load(path, data, settings, embedded_python_console, logger)[source]

Creates a PythonTool according to a tool specification file.

Parameters:
  • path (str) – Base path to tool files
  • data (dict) – Dictionary of tool definitions
  • settings (QSettings) – Toolbox settings
  • embedded_python_console (PythonReplWidget) – Python console widget for execution in the embedded console
  • logger (LoggerInterface) – A logger instance
Returns:

PythonTool instance or None if there was a problem in the tool definition file.
create_tool_instance(self, basedir)[source]

Returns an instance of this tool specification that is configured to run in the given directory.

Parameters:basedir (str) – the path to the directory where the instance will run
class spinetoolbox.project_items.tool.tool_specifications.ExecutableTool(name, tooltype, path, includes, settings, logger, description=None, inputfiles=None, inputfiles_opt=None, outputfiles=None, cmdline_args=None, execute_in_work=True)[source]

Bases: spinetoolbox.project_items.tool.tool_specifications.ToolSpecification

Class for Executable tool specifications.

Parameters:
  • name (str) – Tool name
  • tooltype (str) – Tool specification type
  • path (str) – Path to main script file
  • includes (list) – List of files belonging to the tool (relative to ‘path’). # TODO: Change to src_files
  • file in the list is the main script file. (First) –
  • settings (QSettings) – Toolbox settings
  • logger (LoggerInterface) – A logger instance
  • description (str) – Tool description
  • inputfiles (list) – List of required data files
  • inputfiles_opt (list, optional) – List of optional data files (wildcards may be used)
  • outputfiles (list, optional) – List of output files (wildcards may be used)
  • cmdline_args (str, optional) – Tool command line arguments (read from tool definition file)
static load(path, data, settings, logger)[source]

Creates an ExecutableTool according to a tool specification file.

Parameters:
  • path (str) – Base path to tool files
  • data (dict) – Tool specification
  • settings (QSettings) – Toolbox settings
  • logger (LoggerInterface) – A logger instance
Returns:

ExecutableTool instance or None if there was a problem in the tool specification.
create_tool_instance(self, basedir)[source]

Returns an instance of this tool specification that is configured to run in the given directory.

Parameters:basedir (str) – the path to the directory where the instance will run