ship.tuflow package

Submodules

ship.tuflow.controlfile module

Summary:

Container for the main tuflow control files (tcf/tgc/etc).

This class is used to store the order of items in the file and any data that is not understood by the tuflowloader e.g. commented sections and components of the file that are not specifically listed.

If does not store the data directly, just the hash codes for the file parts so that they can be cross referenced against the TuflowModel.file_parts dictionary.

The ModelFileEntry class is also kept in this module. This provides simple access to main variables held by the TuflowFilePart objects.

Author:
Duncan Runnacles
Created:
01 Apr 2016
Copyright:
Duncan Runnacles 2016

TODO:

Updates:

class ControlFile(model_type)[source]

Bases: object

addControlFile(model_file, control_file, **kwargs)[source]

Add the contents of a new ControlFile to this ControlFile.

**kwargs:
‘after’: ModelFile to place the new ModelFile (model_file) after
in terms of the ordering of the contents.
‘before’: ModelFile to place the new ModelFile (model_file) before
in terms of the ordering of the contents.

If bother ‘before’ and ‘after’ are given after will take preference. If neither are given a ValueError will be raised.

Parameters:
  • model_file (ModelFile) – the ModelFile that is being added.
  • control_file (ControlFile) – the Control to combine with this one.
Raises:

ValueError – if neither ‘after’ or ‘before’ are given.
addLogicPart(add_part, adjacent_part, **kwargs)[source]

Called when a TuflowPart is added to a TuflowLogic.

**kwargs:
‘after’: the part after the one being added. ‘before’: the part before the one being added.

If both ‘after’ and ‘before’ are given in kwargs, or neither are given, ‘after’ will take precedence.

This is mostly for use by a callback function in TuflowLogic parts. It makes sure that when a TuflowPart is added to a TuflowLogic it is also added to the PartHolder.

allParentHashes(parent_hash, iterator)[source]

Get all of the TuflowParts with a specific parent in their heirachy.

Calls the allParents() method in TuflowPart. To get all of the parent TuflowPart.hash values. allParents() is a recursive method that will walk all the way up the tree and return the hash of every parent item.

This method checks to see if a certain hash is in the returned list.

Parameters:
  • parent_hash (uuid4) – hash to check against.
  • iterator (list or Iterator) – containing TuflowPart’s to fetch the parents from.
Returns:

tuple - list(Tuflowpart’s), first index of found paren, last index

of found parent.
checkPartLogic(part, se_vals)[source]

Check that the part or it’s parents are inside the current logic terms.

See TuflowPart isInSeVals method for further information.

Parameters:
  • part (TuflowPart) – the part to check logic terms for.
  • se_vals (dict) – containing the current scenario and event values.
Returns:

bool - True if it’s in the logic terms, or False otherwise.
checkPathsExist(se_vals=None, **kwargs)[source]

Check that all of the TuflowFile type’s absolute paths exist.

Parameters:se_vals=None (dict) – to select only those TuflowFile’s that are within certain scenario and event clauses.
Returns:list - containing all TuflowFile’s that failed the check.
contains(se_vals=None, **kwargs)[source]

Find TuflowPart variables that contain a particular string or value.

All searches are case insensitive.

**kwargs:

command(str): text to search for in a TuflowPart.command. variable(str): characters to search for in a TuflowPart.variable. filename(str): text to search for in a TuflowPart.filename. parent_filename(str): text to search for in a

TuflowPart.associates.parent.filename.
active_only(bool): if True only parts currently set to ‘active’ will
be returned. Default is True.
exact(bool): Default is False. If set to True it will only return an
exact match, otherwise checks if the str is ‘in’.
Parameters:se_vals (dict) – containing scenario and event values to define the search criteria.
Returns:list - of TuflowParts that match the search term.
controlFileIndices(parent_file, **kwargs)[source]

Get the last index of TuflowParts with particular parent.

**kwargs:
‘start’(bool): only returns the start indices of the control file. ‘end’(bool): only returns the end indices of the control file. ‘both’(bool): return the start and end indices of the control file. ‘part’(bool): returns the parts in that control file as well.

If not kwargs are supplied ‘both’ and ‘part’ are assumed.

The dict returned will vary in structure depending on the kwargs provided. All keys are X_parts, X_logic, X_cfile where ‘X’ is either ‘start’, ‘end’, ‘part’ to match the args given. E.g:

outputs = {
    'start_part': PartHolder start index,
    'start_logic': LogicHolder start index,
    'start_cfile': control_files start index,
    'part_part': [TuflowPart, TuflowPart],
    ...etc
}
Parameters:parent_file (ModelFile) – to check for last occurence of in self.parts.
Returns:dict - with last index of ‘parts’, ‘logic’ and ‘control_files’
customPartSearch(callback_func, include_unknown=False)[source]

Return TuflowPart’s based on the return value of callback_func.

Get a generator containing all of the TuflowPart’s in PartHolder that meet the condition of callback_func.

callback_func must accept a TuflowPart and return a tuple of: keep-status and the return value. For example:

# This is the callback_func that we test the TuflowPart. It is
# defined in your script
def callback_func(part):

    # In this case we check for GIS parts and return a tuple of:
    # - bool(keep-status): True if it is a GIS filepart_type
    # - tuple: filename and parent.model_type. This can be
    #       whatever you want though
    if part.filepart_type == fpt.GIS:
        return True, (part.filename, part.associates.parent.model_type)

    # Any TuflowPart's that you don't want included must return
    # a tuple of (False, None)
    else:
        return False, None

tgc = tuflow.control_files['TGC']
tgc.customPartSearch(callback_func)
Parameters:
  • callback_func (func) – a function to run for each TuflowPart in this ControlFile’s PartHolder.
  • include_unknown=False (bool) – If False any UnknownPart’s will be ignored. If set to True it is the resonsibility of the callback_func to check for this and deal with it.
Returns:

generator - containing the results of the search.
fetchPartType(instance_type, filepart_type=None, no_duplicates=True, se_vals=None, **kwargs)[source]

Get all the TuflowPart’s that match the criteria.

TuflowPart’s will be returned in order.

The callback_func kwarg can be used to do any other checks on a file part that you need and are not included in the given arguments. It is the last check that’s run and will therefore only be performed on parts that have already passed all other checks.

**kwargs:
active_only(bool): if True will only return TuflowPart’s that have the
‘active’ flag set to True.
‘callback_func’(func): if given the function will be called with
the part after all other logic has run. It must take a list of all the parts found so far and the current part (list, TuflowPart). It must return a bool, stating whether to add the part to list.
‘by_parent’(bool): if True it will return a dict containing lists of
the parts under their parent filename and extension as a key. Default is False.
exclude(list): filepart_type’s that should not be included
in the return list.
Parameters:
  • instance_type (TuflowPart) – class derived from TuflowPart to restrict the search to.
  • filepart_type=None – the FILEPART_TYPES value to check. If None all TuflowFile types will be checked. You can also supply a list of multiple filepart_type’s.
  • se_vals (dict) – containing scenario and event values to define the search criteria.
Returns:

list - of filepaths that matched.
filepaths(filepart_type=None, absolute=False, no_duplicates=True, no_blanks=True, se_vals=None, **kwargs)[source]

Get all the TuflowFile filepaths that match the criteria.

Filepaths will be returned in order.

**kwargs:
active_only: if True only the TuflowPart’s with the ‘active’ flag
set to True will be returned.
by_parent: if True a dict where keys are parent filename and
extension will be returned. Each dict value is a list of paths.
exclude(list): filepart_type’s that should not be included
in the return list.
user_vars(dict): containing placeholder variables as keys and the
required values as values. (see TuflowPart.resolvePlaceholder() for more information.
Parameters:
  • filepart_type=None – the FILEPART_TYPES value to check. If None all TuflowFile types will be checked. You can also supply a list of multiple filepart_type’s.
  • absolute=False (bool) – If True absolute paths will be returned. If False only filenames will be returned.
  • no_duplicates=True (bool) – If True any duplicate paths will be ignored.
  • no_blanks=True (bool) – if True any blank filenames will be ignored.
  • se_vals (dict) – containing scenario and event values to define the search criteria.
Returns:

list - of filepaths that matched.
files(filepart_type=None, no_duplicates=True, se_vals=None, **kwargs)[source]

Get all the TuflowFile types that match the criteria.

TuflowPart’s will be returned in order.

All kwargs are passed onto fetchPartType. See there for more details.

Parameters:
  • filepart_type=None – the FILEPART_TYPES value to check. If None all TuflowFile types will be checked. You can also supply a list of multiple filepart_type’s.
  • no_duplicates=True (bool) – If True any duplicate commands will be ignored.
  • se_vals (dict) – containing scenario and event values to define the search criteria.
Returns:

list - of TuflowFile’s that matched.
getPrintableContents(se_vals=None, **kwargs)[source]

Return the control files with contents formatted for writing to file.

**kwargs:
active_only=True(bool): if True only the parts with ‘active’ status
set to True will be included.
parents(list): a list of parents (tuflow control files) to return.
if not given all the parents in self.control_files will be returned.
Parameters:se_vals (dict) – containing scenario and event values to define the search criteria.
Returns:
dict - control files paths as keys and a ordered list of Tuflow
commands as the values.
logics(filepart_type=None, se_vals=None, **kwargs)[source]
removeControlFile(model_file)[source]

Remove the contents of an existing ControlFile.

Will return a dict with the starting indices of removed sections:

indices = {
    'parts': int, 'logic': int, 'control_files': int
}
Parameters:model_file (ModelFile) – the ModelFile that will be used to find the sections of this ControlFile to delete.
removeLogicPart(remove_part, last_part)[source]

Called when a TuflowPart is removed from a TuflowLogic.

This is mostly for use by a callback function in TuflowLogic parts. It makes sure that when a TuflowPart is removed from a TuflowLogic it is moved outside of the scope of the TuflowLogic in the PartHolder.

replaceControlFile(model_file, control_file, replace_modelfile)[source]

Replace contents of an existing ModelFile with a new one.

Parameters:
  • model_file (ModelFile) – the ModelFile that will be replacing an existing ModelFile.
  • control_file (ControlFile) – containing the contents to update this ControlFile with.
  • replace_modelfile (ModelFile) – the ModelFile in this ControlFile to replace with the new ControlFile.
updateRoot(root, must_exist=True)[source]

Update the root variable of all TuflowPart’s.

Parameters:
  • root (str) – the new directory path.
  • must_exist=True (bool) – if True and the given root directory doesn’t exist it will raise a ValueError.
variables(filepart_type=None, no_duplicates=True, se_vals=None, **kwargs)[source]

Get all the ATuflowVariable types that match the criteria.

TuflowPart’s will be returned in order.

All kwargs are passed onto fetchPartType. See there for more details.

Parameters:
  • filepart_type=None – the FILEPART_TYPES value to check. If None all TuflowFile types will be checked. You can also supply a list of multiple filepart_type’s.
  • no_duplicates=True (bool) – If True any duplicate commands will be ignored.
  • se_vals (dict) – containing scenario and event values to define the search criteria.
Returns:

list - of ATuflowVariable types that matched.
write(overwrite=False, **kwargs)[source]

Write the control files to disk.

Calls the getPrintableContents function and then writes the returned contents to file.

**kwargs:
active_only=True(bool): if True only the parts with ‘active’ status
set to True will be included.
parents(list): a list of parents (tuflow control files) to return.
if not given all the parents in self.control_files will be returned.
Parameters:overwrite=False (bool) – if set to True it will overwrite an existing file without warning. If False it will raise an error if the file already exists.
class LogicHolder(remove_callback=None, add_callback=None)[source]

Bases: object

add(logic)[source]
getAllParts(hash_only)[source]
partFromHash(hash)[source]
class PartHolder[source]

Bases: object

add(filepart, **kwargs)[source]

If both after and before are supplied, after will take precedence.

append(filepart)[source]

Adds part to the end of the parts list.

Most of the time you probably want to use the add() method with no ‘before’ or ‘after’ kwarg, which will append the TuflowPart to the end of it’s parent contents. Otherwise you will probably mess up the ordering of the parts.

index(part)[source]
lastIndexOfParent(parent)[source]
move(part, **kwargs)[source]
remove(filepart)[source]
replace(part, replace_part)[source]
class TcfControlFile(mainfile, remove_callback=None, replace_callback=None, add_callback=None)[source]

Bases: ship.tuflow.controlfile.ControlFile

addControlFile(model_file, control_file, **kwargs)[source]

Add the contents of a new ControlFile to this ControlFile.

**kwargs:
‘after’: ModelFile to place the new ModelFile (model_file) after
in terms of the ordering of the contents.
‘before’: ModelFile to place the new ModelFile (model_file) before
in terms of the ordering of the contents.

If both ‘before’ and ‘after’ are given after will take preference. If neither are given a ValueError will be raised.

Parameters:
  • model_file (ModelFile) – the ModelFile that is being added.
  • control_file (ControlFile) – the Control to combine with this one.
Raises:

ValueError – if neither ‘after’ or ‘before’ are given.
mainfile
removeControlFile(model_file)[source]

Remove the contents of an existing ControlFile.

Will return a dict with the starting indices of removed sections:

indices = {
    'parts': int, 'logic': int, 'control_files': int
}
Parameters:model_file (ModelFile) – the ModelFile that will be used to find the sections of this ControlFile to delete.
Returns:
dict - containging the starting indices of ‘parts’, ‘logic’,
and ‘control_files’ that were deleted.
replaceControlFile(model_file, control_file, replace_modelfile)[source]

Replace contents of an existing ModelFile with a new one.

Parameters:
  • model_file (ModelFile) – the ModelFile that will be replacing an existing ModelFile.
  • control_file (ControlFile) – containing the contents to update this ControlFile with.
  • replace_modelfile (ModelFile) – the ModelFile in this ControlFile to replace with the new ControlFile.
updateRoot(root, must_exist=True)[source]

Update the root variable of all TuflowPart’s.

Parameters:
  • root (str) – the new directory path.
  • must_exist=True (bool) – if True and the given root directory doesn’t exist it will raise a ValueError.
logger = <logging.Logger object at 0x06EDDB90>

logging references with a __name__ set to this module.

ship.tuflow.tuflowfactory module

class TuflowFactory[source]

Bases: object

static createBcEventVariable(line, parent, **kwargs)[source]
static createBlockLogic(parent, commands, terms, comments)[source]

Create a new IfLogic object.

Parameters:
  • parent (ModelFile) – the parent TuflowPart.
  • commands (str) – the command part e.g. ‘Define Event’.
  • terms – (list): terms to add for the clause [‘scen1’, ‘scen2’].
  • comments (str) – the comment that should be attached to the end of the clause line. e.g. ‘If Scenario == scen1 | scen2 ! comment’
Returns:

BlockLogic - created with given args.
static createDataType(line, parent, **kwargs)[source]
static createGisType(line, parent, **kwargs)[source]
static createIfLogic(parent, commands, terms, comments)[source]

Create a new IfLogic object.

Parameters:
  • parent (ModelFile) – the parent TuflowPart.
  • commands (list) – a list of the command part to add for each clause. e.g. ‘If Scenario’, ‘Else’, ‘Else If Event’, etc.
  • terms – (list(list)): terms to add for each clause. e.g. [[‘scen1’, ‘scen2’], [‘scen3’]]
  • comments (list) – the comment that should be attached to the end of each clause line. e.g. ‘If Scenario == scen1 | scen2 ! comment’
Returns:

IfLogic - created with given args.
Raises:

ValueError - if commands, terms and comments are not the same length.
static createKeyValueType(line, parent, **kwargs)[source]
static createModelType(line, parent, **kwargs)[source]
static createModelVariableType(line, parent, **kwargs)[source]
static createResultType(line, parent, **kwargs)[source]
static createUserVariableType(line, parent, **kwargs)[source]
static createVariableType(line, parent, **kwargs)[source]
classmethod getTuflowPart(line, parent, part_type=None, logic=None)[source]
assignSiblings(parts)[source]

Assign’s next and previours sibling’s in an ordered list.

Parameters:parts (list) – a list of TuflowFilepart’s in associate order.
Returns:
parts(list) - with sibling_next and sibling_prev objects set to
adjacent parts in the provided list.
breakLine(line)[source]

Breaks a file line into it’s command/instruction components.

Most lines in tuflow files are in the form:: Read Command == ..somepath.ext ! comment

This separates the command from the rest.

Parameters:line (str) – the line as read from the file.
Returns:Tuple - (command, instruction).
checkEstryAuto(line, parent)[source]
checkIsComment(line)[source]
checkMultiTypes(line, part_type)[source]

Returns the corrent filepart _type for multi-type commands.

For example projection can be either a string variable or a gis file.

Parameters:
  • line (str) – the control file line to check.
  • part_type (FILEPART_TYPE) – the default value to return if everything was already correct.
Returns:

FILEPART_TYPE
getExtension(path, upper=True)[source]
logger = <logging.Logger object>

logging references with a __name__ set to this module.

partsFromPipedFiles(part_type, parent, **kwargs)[source]

Separates piped file paths and creates a TuflowFilepart for each.

The ‘path’ entry in the kwargs will be replaced with the specific section of the piped file that is being created for each part.

Note

This function also call assignSiblings().

Parameters:
  • part_type (TuflowFilePart) – class to crate the resultant parts with.
  • parent (TuflowFilePart) – the control file part containing this command.
  • kwargs (dict) – the arguments to use when building the TuflowFilePart. These are dependent on the type of TuflowFilePart that you create.
Returns:

list - containing TuflowFilePart instance of part_type type.
resolveResult(result_part)[source]

Fixes the self.type.RESULT paths after load.

Result and Check file paths are a bit tricky because they can be set up in a range of ways as either relative or absolute e.g.:

..\some\path\end
..\some\path\end\
..\some\path\end_as_prefix_

If output is a checkfile no ‘’ on the end indicates that the final string should be prepended to all files, but if it’s a result output it is the same as having a ‘’ on the end.

This function attempts to work out what’s going on with it all and setup the root, relative_root and filename accordingly.

Todo

Need to account for the case where a string follows the directory is given that will be prepended to all output files.

Parameters:entry (ResultFile) –
Returns:ResultFile - ammended.
separateComment(instruction)[source]

Separates any comment from the line.

Parameters:instructions (str) – the line to seperate comment from.
Returns:
tuple(Bool, tuple) - (0)==True if comment found, (1) contains a
tuple with (instruction, comment).
takeParentType(path)[source]

ship.tuflow.tuflowfilepart module

Summary:
Contains all of the TuflowPart type classes used to store the data within Tuflow control files.
Author:
Duncan Runnacles
Created:
20 Nov 2016
Copyright:
Duncan Runnacles 2016

TODO:

Updates:

class ATuflowVariable(parent, obj_type='variable', **kwargs)[source]

Bases: ship.tuflow.tuflowfilepart.TuflowPart

resolvedVariable(user_vars)[source]

Return the variable with any placeholder vars resolved to a value.

For more information on user_vars see TuflowPart.resolvePlaceholder.

variable
class AssociatedParts(parent, **kwargs)[source]

Bases: object

Stores associate TuflowPart references.

Every TuflowPart will hold a copy of this class. It is used to store references to any other TuflowPart’s that it has an association with.

logic
observedActiveChange(status)[source]

called by the parent when registered as an observer.

parent
class BlockLogic(parent, **kwargs)[source]

Bases: ship.tuflow.tuflowfilepart.TuflowLogic

For any logic that uses a ‘Define something’.

I can only think of ‘Define Event == term1 | term2 | termN’, but maybe there are others?

addClause()[source]

Only one clause allowed in this type.

class DataFile(parent, **kwargs)[source]

Bases: ship.tuflow.tuflowfilepart.TuflowFile

DATA_TYPES = {'CSV': ('csv',), 'TMF': ('tmf',)}
class GisFile(parent, **kwargs)[source]

Bases: ship.tuflow.tuflowfilepart.TuflowFile

GIS_TYPES = {'shp': ('shp', 'shx', 'dbf'), 'mi': ('mif', 'mid')}
class IfLogic(parent, **kwargs)[source]

Bases: ship.tuflow.tuflowfilepart.TuflowLogic

addClause(command, terms, comment='')[source]

Add a new clause to this TuflowLogic.

Parameters:
  • command (str) – the command part of the clause (e.g. ‘Else if Event ==’)
  • terms (list) – str’s of terms for clause (e.g. [‘evt1’, ‘evt2’, ‘evtN’].
  • comment='' (str) – any comment for the clause line.
getMiddleClause(part, out)[source]

Check to see if there’s any middle clause.

Used for writing out the clauses when printing to file.

getPrintableContents(part, out, **kwargs)[source]

Get the printable contents for this TuflowLogic.

class ModelFile(parent, **kwargs)[source]

Bases: ship.tuflow.tuflowfilepart.TuflowFile

getPrintableContents(**kwargs)[source]
class ResultFile(parent, **kwargs)[source]

Bases: ship.tuflow.tuflowfilepart.TuflowFile

RESULT_TYPE = {'output': 'OUTPUT FOLDER', 'log': 'LOG', 'check': 'WRITE CHECK FILE'}
filenameAndExtension(user_vars=None)[source]
class SectionLogic(parent, **kwargs)[source]

Bases: ship.tuflow.tuflowfilepart.BlockLogic

Used for all other types of scoping logic.

This includes things like ‘Define Output Zone ==’ etc. The only real difference between this and BlockLogic is that BlockLogic sets check_sevals = True. It kind of makes sense to treat them slightly differently though as the BlockLogic and IfLogic are used with scenario and event logic.

class TuflowFile(parent, obj_type='file', **kwargs)[source]

Bases: ship.tuflow.tuflowfilepart.TuflowPart, ship.utils.filetools.PathHolder

absolutePath(user_vars=None)[source]

Get the absolute path of this object.

Parameters:user_vars (dict) – a dict containing variable placeholder values as keys and the actual values as values. See TuflowPart.resolvePlaceholder() method for more information.
absolutePathAllTypes(user_vars=None)[source]

Get the absolute paths for all_types.

If the file has other file types in all_types (e.g. .shp, shx, .dbf) this will return the absolute paths for all of them.

Parameters:user_vars (dict) – a dict containing variable placeholder values as keys and the actual values as values. See TuflowPart.resolvePlaceholder() method for more information.
checkPipedStatus(path)[source]
filenameAllTypes(user_vars=None)[source]
filenameAndExtension(user_vars=None)[source]
getPrintableContents(**kwargs)[source]
getRelativeRoots(roots)[source]

Get the relative paths of this and all parent objects.

Recursively calls all of it’s parents to obtain the relative paths before calling absolutePath of the PathHolder superclass.

class TuflowKeyValue(parent, **kwargs)[source]

Bases: ship.tuflow.tuflowfilepart.ATuflowVariable

getPrintableContents(**kwargs)[source]
class TuflowLogic(parent, obj_type='logic', **kwargs)[source]

Bases: ship.tuflow.tuflowfilepart.TuflowPart

END_CLAUSE = None

Override with with whatever the end statement is (e.g. ‘End If’)

addPart(part, group=-1, **kwargs)[source]

Add a new TuflowPart.

**kwargs:
skip_callback=False(bool): if true it won’t call the callback
function in the ControlFile. Basically don’t use this.
Parameters:
  • part (TuflowPart) – the part to add.
  • group (int) – the clause group to add the part to.
  • skip_callback=False (bool) – if true it won’t call the callback function in the ControlFile. Basically don’t change this.
add_callback = None

Function called when a TuflowPart is added.

allTerms()[source]

Returns all of the terms in every clause.

check_sevals = None

Whether to check the scenarion event values.

getAllParts(hash_only)[source]

Return all of the TuflowParts in this TuflowLogic.

Parameters:hash_only – if True the TuflowPart.hash codes otherwise the actual TuflowPart will be.
Returns:list - of TuflowPart’s or TuflowPart.hash
getEndClause(part)[source]

Get the end clause formatted for printing.

getGroup(part)[source]

Return the group index of the given part.

Parameters:part (TuflowPart) –
Returns:
int - the index of the group that this part is in, or -1 if it
could not be found.
getLogic(hash_only)[source]

TODO: Check what this does and if it’s used.

getPrintableContents(part, out, group=0, **kwargs)[source]

Return contents formatted for printing.

Parameters:
  • part (TuflowPart) – current TuflowPart in PartHolder parts list.
  • out (list) – list to update.
getTopClause(part, out, force, **kwargs)[source]

Get the top clause command and terms formatted for printing.

insertPart(new_part, adjacent_part)[source]

Insert a TuflowPart adjacent to an existing part.

This allows you to have control over where in a group a part is placed. If you don’t care where it goes in the group, or you want it to go at the end of the group use addPart() instead.

Parameters:
  • new_part (TuflowPart) – the part to add.
  • adjacent_part (TuflowPart) – the part to put the new part next to. It will be placed above the existing part.
isInClause(part, term)[source]

Test whether the given part is within a particular clause.

Parameters:
  • part (TuflowPart) – check if it’s in this TuflowLogic.
  • term (str) – term to check the part against.
Returns:

bool - True if the term is part of one of the clauses in this

TuflowLogic and the part is within that clause; Else False.
isInTerms(part, se_vals)[source]

Checks to see if the clause terms associated with part match se_vals.

If the part is in an ‘Else’ clause it checks that the se_vals DON’T match any of the terms in any of the clauses.

Parameters:
  • part (TuflowPart) – to find the terms for. If now reference of the part can be found False will be returned.
  • se_Vals (dict) – in format {‘scenario’: [list, of]. ‘event’: [terms]}.
Returns:

bool - True if the part is within the given se_vals, otherwise False.
isTuflowPart(part)[source]

Internal function.

removePart(part)[source]

Remove a TuflowPart.

Will also call a callback function to the ControlFile object that contains this TuflowLogic and ensure that the PartHolder order is updated. It just ensures that the TuflowPart is moved out of the scope of the parts still within the TuflowLogic.

Parameters:part (TuflowPart) –
remove_callback = None

Function called when a TuflowPart is removed.

class TuflowModelVariable(parent, **kwargs)[source]

Bases: ship.tuflow.tuflowfilepart.ATuflowVariable

getPrintableContents(**kwargs)[source]
classmethod noParent(key, variable)[source]
variable_name
class TuflowPart(parent, obj_type, **kwargs)[source]

Bases: object

Interface for all TuflowPart’s.

All components containing data stored by ControlFile subclass this one.

active
allParents(parent_list)[source]

Get all the hash codes of all parents to this object.

Recursive method to search up through all of the parents - in the associates object - and retrieve their hash codes.

The parent hash codes will be returned in ascending order. I.e. the immediate parent will be at index 0, then it’s parent, and so on.

Note

parent_list arg is used to pass the found parents through the recursion. When calling this method you should probably always provide an empty list.

Returns:list - containing the hash codes for every parent of the called TuflowPart in assending order.
buildPrintline(command, instruction, comment='')[source]
classmethod copy(**kwargs)[source]
getPrintableContents(**kwargs)[source]
isInSeVals(se_vals)[source]

Check that this TuflowPart or it’s parents are inside given logic terms.

The parents must be checked when a part doesn’t have a reference to any logic because the part may exists inside a control file that does have a logic clause. In this situation the part would not have any logic directly assigned to it, but would be within the logical clause by virtue of it’s parent being inside it...

Example:: :

a_tcf_file.tcf...

If Scenario == somescenario
tgc1.tgc
Else
tgc2.tgc

End If

tgc1.tgc...

! This file’s logic == None, but if scenario == ‘somescenario’ it ! should not be returned. Read GIS Z Line == afile.shp

Parameters:
  • part (TuflowPart) – the part to check logic terms for.
  • user_vars (UserVariables) – containing the current scenario and event values.
Returns:

bool - True if it’s in the logic terms, or False otherwise.
observers = None

This is a poor man’s observer interface.

If an object wants to be notified of key internal changes, such as the Logic being activated/deactivated, then can add themselves to this list.

If an object is added to this list it should implement the following .. method:: - observedActiveChange(bool)

static resolvePlaceholder(value, user_vars)[source]

Replaces the contents of a placeholder value with an actual value.

Tuflow allows scenario, event and user defined variables to be used as placeholders. This method will check for a given value against a dict of current variables and update the value if found.

Example:

# Original tcf command
Cell Size == <<myvar>>
Read Materials File == '..\Materials_<<s1>>.tmf
Timestep == <<unknownvar>>

# user_vars  note that this includes all variable in UserVars in
# a single dict
user_vars = {
    's1': 'scen1', 's2': 'scen2', 'e1': 'event1', 'e2': 'event2',
    'myvar': '12'
}

# The above commands would return the following values when the
# above user_vars are given.
Cell Size == 12
Read Materials File == '..\Materials_scen1.tmf
Timestep == <<unknownvar>>
Parameters:
  • value – the value to check for a placeholder and replace.
  • user_vars (dict) – see UserVariables.variablesTodict().
Returns:

the value, updated if found or the same if not.
class TuflowUserVariable(parent, **kwargs)[source]

Bases: ship.tuflow.tuflowfilepart.ATuflowVariable

getPrintableContents(**kwargs)[source]
classmethod noParent(key, variable)[source]
variable_name
class TuflowVariable(parent, **kwargs)[source]

Bases: ship.tuflow.tuflowfilepart.ATuflowVariable

getPrintableContents(**kwargs)[source]
split_variable
variable
class UnknownPart(parent, **kwargs)[source]

Bases: ship.tuflow.tuflowfilepart.TuflowPart

getPrintableContents(**kwargs)[source]
logger = <logging.Logger object at 0x06EE39D0>

logging references with a __name__ set to this module.

ship.tuflow.tuflowmodel module

Summary:

Container and main interface for accessing the Tuflow model and a class for containing the main tuflow model files (Tcf, Tgc, etc).

There are several other classes in here that are used to determine the order of the files in the model and key words for reading in the files.

Author:
Duncan Runnacles
Created:
01 Apr 2016
Copyright:
Duncan Runnacles 2016

TODO:

Updates:

class TuflowFilepartTypes[source]

Bases: object

Contains key words from Tuflow files for lookup.

This acts as a lookup table for the TuflowLoader class more than anything else. It is kept here as that seems to be most sensible.

Contains methods for identifying whether a command given to it is known to the library and what type it is. i.e. what UNIT_CATEGORY it falls into.

find(find_val, file_type='*')[source]

Checks if the given value is known or not.

The word to look for doesn’t have to be an exact match to the given value, it only has to start with it. This means that we don’t need to know whether it is a ‘command == something’ or just ‘command something’ (like: ‘Estry Control File Auto’) at this point.

This helps to avoid unnecessary repitition. i.e. many files are like: ‘READ GIS’ + another word. All of them are GIS type files so they all get dealt with in the same way.

In some edge cases there are command that start the same. These are dealt with by secondary check to see if the next character is ‘=’ or not.

Parameters:
  • find_val (str) – the value attempt to find in the lookup table.
  • file_type (int) – Optional - reduce the lookup time by providing the type (catgory) to look for the value in. These are the constants (MODEL, GIS, etc).
Returns:

Tuple (Bool, int) True if found. Int is the class constant

indicating what type the value was found under.
class TuflowModel(root)[source]

Bases: object

Container for the entire loaded tuflow model.

addTcfModelFile(model_file, control_file, **kwargs)[source]

Add a new ModelFile instance to a TCF type ControlFile.

Note

You can call this function directly if you want to, but it is also hooked into a callback in the TCF ControlFile. This means that when you use the standard ControlFile add/remove/replaceControlFile() methods these will be called automatically.

**kwargs:
after(TuflowPart): the part to add the new ModelFile after. before(TuflowPart): the part to add the new ModelFile before.

Either after or before kwargs must be given. If both are provided after will take precedence.

Args:

model_file(ModelFile): the replacement ModelFile TuflowPart. control_file(ControlFile): containing the contents to replace the

existing ControlFile.
bc_event = None

Contains the currently acitve BC Event variables.

checkPathsExist()[source]

Test that all of the filepaths in the TuflowModel exist.

control_files = None

Tuflow Control File objects.

All types of Tuflow Control file are stored here under the type header. Types are: TCF, TGC, TBC, ECF, TEF. TCF is slightly different to the others as it contains an additional member variable ‘main_file_hash’ to identify the main tcf file that was called to load the model.

customPartSearch(control_callback, tuflow_callback=None, include_unknown=False)[source]

Return TuflowPart’s based on the return value of the callbacks.

control_callback will be used as an argument in each of self.control_files’ customPartSearch() methods. The tuflow_callback will be called on the combined generators returned from that method.

See also

ControlFile.customPartSearch

Continuing the example in the ControlFile.customPartSearch method. This time the additinal tuflow_callback function is defined as well.

callback_func must accept a TuflowPart and return a tuple of: keep-status and the return value. For example:

# This is the callback_func that we test the TuflowPart. It is
# defined in your script
def callback_func(part):

    # In this case we check for GIS parts and return a tuple of:
    # - bool(keep-status): True if it is a GIS filepart_type
    # - tuple: filename and parent.model_type. This can be
    #       whatever you want though
    if part.filepart_type == fpt.GIS:
        return True, (part.filename, part.associates.parent.model_type)

    # Any TuflowPart's that you don't want included must return
    # a tuple of (False, None)
    else:
        return False, None

# Here we define a function to run after the generators are returned
# from callback_func. In the funcion above the return type is a
# tuple, so we accept that as the arg in this function, but it will
# be whatever you return from callback_func above.
# This function checks to see if there are any duplicate filename's.
# Note that it must return the same tuple as the other callback.
# i.e. keep-status, result
def tuflow_callback(part_tuple):
    found = []
    if part_tuple[0] in found:
        return False, None
    else:
        return True, part_tuple[0]

# Both callback's given this time
results = tuflow.customPartSearch(callback,
                                  tuflow_callback=tuflowCallback)
# You can now iteratre the results
for r in results:
    print (str(r))
Parameters:
  • callback_func (func) – a function to run for each TuflowPart in this ControlFile’s PartHolder.
  • include_unknown=False (bool) – If False any UnknownPart’s will be ignored. If set to True it is the resonsibility of the callback_func to check for this and deal with it.
Returns:

generator - containing the results of the search.
missing_model_files = None

Contains any tcf, tgs, etc files that could not be loaded.

removeTcfModelFile(model_file)[source]

Remove an existing ModelFile from ‘TCF’ and update ControlFile.

Note

You can call this function directly if you want to, but it is also hooked into a callback in the TCF ControlFile. This means that when you use the standard ControlFile add/remove/replaceControlFile() methods these will be called automatically.

Parameters:model_files (ModelFile) – the ModelFile being removed.
replaceTcfModelFile(model_file, control_file, replace_file)[source]

Replace an existing ModelFile in ‘TCF’ and update ControlFile.

Note

You can call this function directly if you want to, but it is also hooked into a callback in the TCF ControlFile. This means that when you use the standard ControlFile add/remove/replaceControlFile() methods these will be called automatically.

Parameters:
  • model_file (ModelFile) – the replacement TuflowPart.
  • control_file (ControlFile) – containing the contents to replace the existing ControlFile.
  • replace_file (ModelFile) – the TuflowPart to be replaced.
root
updateRoot(root)[source]

Update the root variable in all TuflowFile’s in the model.

The root variable (TuflowModel.root) is the directory that the main .tcf file is in. This is used to define the location of all other files which are usually referenced relative to each other.

Note

This method will be called automatically when setting the
TuflowModel.root variable.
Parameters:root (str) – the new root to set.
user_variables = None

Class containing the scenario/event/variable keys and values.

class UserVariables[source]

Bases: object

Container for all user defined variables.

Includes variable set in the control files with ‘Set somevar ==’ and the scenario and event variables.

Note

Only the currently active scenario and event variables will be stored in this class.

add(filepart, vtype=None)[source]

Add a new variables to the class.

Parameters:

filepart (TuflowModelVariables or TuflowUserVariable) –

Raises:
  • TypeError - if filepart is not a TuflowModelVariable or TuflowUserVariable.
  • ValueError - if filepart already exists.
get(key, vtype=None)[source]

Return the TuflowPart at the given key.

Parameters:
  • key (str) – the key associated with the required TuflowPart.
  • vtype=None (str) – the type of part to return. If None it will return a ‘variable’ type. Other options are ‘scenario’ and ‘event’.
Returns:

TuflowPart - TuflowModelVariable or TuflowUserVariable type.
remove(key)[source]

Remove the variable stored at the given key.

Parameters:key (str) – key for either the scenario, event, or variables dict.
replace(filepart)[source]

Replace an existing variable.

Parameters:

filepart (TuflowModelVariables or TuflowUserVariable) –

Raises:
  • TypeError - if filepart is not a TuflowModelVariable or TuflowUserVariable.
  • ValueError - if filepart doesn’t already exist.
seValsToDict()[source]

Get the values of the scenario and event variables.

Returns the currently active scenario and event values only - not the placeholder keys - in a dictionary in the format:

{'scenario': [val1, val2, valN], 'event': [val1, val2, valN]}
Returns:dict - of scenario and event values.
variablesToDict()[source]

Get the values of the variables.

Note that, like tuflow, scenario and event values will be includes in the variables dict returned.

{‘name1’: var1, ‘name2’: var2, ‘nameN’: name2}
Returns:dict - with variables names as key and values as values.
logger = <logging.Logger object at 0x05461D30>

logging references with a __name__ set to this module.

Module contents