API Toolbox#

Summary#

The API toolbox serves as a place to store and maintain tools that integrate with the Flood Modeller Python API, and by using a common class to define tools (FMTool), allows for a single tool to be used in multiple ways e.g. from command line, imported into python code, as a simple gui or any other method you can implement.

Run a tool#

API Tools can be executed from the command line or from within python code.

From code To run a tool from a python script, simply import the tool and then run using the .run() method (including) any input parameters. For example, you can run the Structure Log tool as follows:

from floodmodeller_api.toolbox import StructureLog

StructureLog.run(
    input_path="path/to/dat.dat",
    output_path="path/to/csv.csv",
)

From the command line

You can also run API tools from the command line. Tools already included in the API toolbox can be called from the command line simply using the tool name and prefixed with ‘fmapi-’. For example to run the Structure Log tool from the command line you would call:

fmapi-structure_log --input_path "<dat file path>" --output_path "<give a file path to a csv>"

As well as passing the arguments in this way, you can also invoke a very simple GUI by simply passing the argument ‘gui’:

fmapi-structure_log gui

From code

from floodmodeller_api.toolbox import TuflowToFloodModeller

TuflowToFloodModeller.run(
    tcf_path="path/to/tcf.tcf",
    folder="path/to/model",
    name="model_name",
)

Developing Custom Tools#

You can develop your own tools to integrate with the Flood Modeller Python API!

There are a few conventions you need to follow to do this. - Add a python file or folder to one of the directories in the toolbox - Write the tool functionality however you prefer (i.e. a single function, a class, or even a module with multiple files) so long as there is a single entry-point for the tool - Create a ‘tool_definition’ python file and define the tool using the FMTool class, passing in the tool name and description, function to be run and the function parameters. - Finally, ensure to expose your tool to the floodmodeller_api.toolbox module by including it in the toolboc module __init__.py files

See the example_tool.py script for an example of how to do this.

When developing your own custom tools, they will not automatically be included in the package scripts and so will not be exposed to run as above, but a simple way to do this for custom tools is to just include an if __name__ == "__main__" block in your definition file (or any python file that imports the tool) and call the tool’s run_from_command_line() method. This will allow you to run that python file directly from the command line with python and pass in any required arguments. For example, including something like:

# some_file.py
if __name__ == "__main__":
    SomeCustomTool().run_from_command_line()

and then running it with:

python some_file.py --some_argument "something"

Reference#

class floodmodeller_api.tool.FMTool#

Compare two parameters by their name attribute.

Use the class by wrapping it in a child class which defines the parameters and function to call:

This class provides a consistent method to structure flood modeller tools that use the API to automate processes, extract data and visualise results. The class also provides methods to extend any tool with a command line interface or tkinter GUI.

We plan to add more extensions in the future.

Parameters:

name (str) – The name of the tool to display in the GUI or cmd line
description (str) – A description of the tool and what it does.
parameters (list[Parameter]) – the Tool parameters, one per input function
tool_function (function) – The function to be called by the tool

# concatenates strings
def concat(str1, str2):
    return str1 + str2
class MyTool(FMTool):
    name = "Name"
    description = "Tool description"
    parameters = [
        Parameter("str1", str),
        Parameter("str2", str)
    ]
    tool_function = concat

classmethod run(**kwargs)#

Method to run the entry point function.

This approach allows the function to be run either from the command line interface, the GUI or any other extensions that we add in the future. :param **kwargs: keyword arguments for the tool_function function.

run_from_command_line()#

Method to run the tool from the command line.

This method parses command line arguments (as defined in self.parameters) and passes them to run to execute the tool

run_gui()#: Method to run the GUI

class floodmodeller_api.tool.Parameter(name: str, dtype: type, description: str | None = None, help_text: str | None = None, required: bool = True)#

Class to represent an FM Tool parameter. There should be one parameter for each argument of the tool_function function

Parameters:

name (str) – The name of the parameter.
dtype (type) – The expected data type of the parameter.
description (str) – A description of the parameter.
help_text (str) – The help text to be displayed for the parameter.
required (bool) – A flag indicating whether the parameter is required or optional. Default is True.

__eq__()#: Compare two parameters by their name attribute.

__hash__()#: Return the hash value of the parameter name.

__repr__()#: Return a string representation of the parameter.