pytuflow.TGC.find_input

Contents

pytuflow.TGC.find_input#

TGC.find_input(filter_by=None, lhs=None, rhs=None, recursive=True, regex=False, regex_flags=0, attrs=(), callback=None, comments=False)#

Find a particular input(s) using a search filter. The filter can be for the entire command, or specifically to the left-hand side lhs or right-hand side rhs of the command.

The filter can be a basic search string, or it can be switched to be a regular expression depending on the regex parameter with regex flags passed in using the regex_flags parameter. If regex is set to False, the filter strings will be case-insensitive. If regex is set to True, the filter strings will be treated as regular expressions and the regex_flags will be used to control the matching behaviour.

More complex rules / filtering can be done by using the attrs or callback parameters. Comments can also be searched through by setting the comments parameter to True.

If no filtering parameters are provided, all inputs will be returned.

Parameters:

  • filter_by (str, optional) – A string or regular expression to filter the input by. This will search through the entire input string (not comments).

  • lhs (str, optional) – A string or regular expression to filter the input by. This will search through the left-hand side of the input.

  • rhs (str, optional) – A string or regular expression to filter the input by. This will search through the right-hand side of the input.

  • recursive (bool, optional) – If set to True, will also search through any child control files.

  • regex (bool, optional) – If set to True, the filter, lhs, and rhs parameters will be treated as regular expressions.

  • regex_flags (int, optional) – The regular expression flags to use when using regular expressions.

  • attrs (SearchTagLike, optional) – A list of tags to filter the input by. The tags represent properties of the input, such as dirty or has_missing_files. The tag can be a tuple of (tag_name, tag_value) or just a tag name where the tag value is assumed to be evaluated as True. A single tag (tag_name, tag_value) or a list of tags can be provided.

  • callback (Callable, optional) – A function that will be called with the input as an argument. The callback should take an T_Input argument and return a boolean indicating whether the input matches the filter.

  • comments (bool, optional) – If set to True, will also search through the comments of the input, including lines that only contain comments. Note that commented out inputs are not separated into left-hand side and right-hand side, and the lhs and rhs parameters will not work on commented out inputs.

Returns:

A list of inputs that match the filter.

Return type:

list[T_Input]

Examples

An example of a simple search to find all GIS material inputs in the model:

>>> control_file = ... # Assume the control file has been loaded
>>> control_file.find_input(lhs='read gis mat')
[<GisInput> Read GIS Mat == gisd_mat_Roads_001_R.shp, <GisInput> Read GIS Mat == gisd_mat_Grass_001_R.shp]

Extending the example above to find all material inputs using a regular expression. A regular expression needs to be used in the case since using the filter "mat" will return false positives. For example, it will return instances if the word “format” appears in the command (e.g. “GIS Format == …” or “Map Output Format == …”). It will also return the material file if searching from the TCF.

>>> import re
>>> control_file.find_input(lhs=r'(set|read gis|read grid) mat', regex=True, regex_flags=re.IGNORECASE)
[<SettingInput> Set Mat == 1,
 <GisInput> Read GIS Mat == gisd_mat_Roads_001_R.shp, <GisInput> Read GIS Mat == gisd_mat_Grass_001_R.shp]

An example using the tags parameter is to find all inputs that have missing files. This can be useful when performing any integrity or pre-modelling checks on the model inputs:

>>> control_file.find_input(attrs=('has_missing_files', True))
[<GisInput> Read GIS Code == gisd_code_EG00_001.shp]

An example of using the callback parameter to find all inputs that use GIS polygon geometry:

>>> from osgeo import ogr # this example requires GDAL/OGR to be installed
>>> from pytuflow import const
>>> control_file.find_input(callback=lambda x: x.TUFLOW_TYPE == const.INPUT.GIS and ogr.wkbPolygon in x.geoms)
Contents