7.3.15. Database

This module aims to provide the core components that are required to build a Parflow input deck.

class parflow.tools.database.core.PFDBObj(parent=None)

Bases: object

Core ParFlow Database Object node

__init__(parent=None)

Create container object while keeping a reference to your parent

details(location='.')

Return details based on a location.

doc(location='.')

Return docs based on a location.

full_name()

Helper method returning the full name of a given ParFlow key.

get_children_of_type(class_name)

Return a list of PFDBObj of a given type that are part of our children.

get_context_settings()

Return global settings for our current parflow run. This is useful when providing global information for domains or else.

keys(skip_default=False)

Gets the key names necessary for the run while skipping unset ones

pfset(key='', value=None, yaml_file=None, yaml_content=None, pfidb_file=None, hierarchical_map=None, flat_map=None, exit_if_undefined=False, silence_if_undefined=False)

Allow to define any parflow key so it can be exported. Many formats are supported:

• key/value: To set a single value relative to our current

  PFDBObj.

• yaml_file: YAML file path to load and import using the

  current PFDBObj as root.

• yaml_content: YAML string to load and import using the

  current PFDBObj as root.

• hierarchical_map: Nested dict containing several key/value

  pair using the current PFDBObj as root.

• flat_map: Flat dict with parflow key/value pair to set

  using the current PFDBObj as root.

select(location='.')

Return a PFDBObj object based on a location.

i.e.:

run.Process.Topology.select(‘.’) => run.Process.Topology run.Process.Topology.select(‘..’) => run.Process run.Process.Topology.select(‘../../Geom’) => run.Geom run.Process.Topology.select(‘/Geom’) => run.Geom

to_dict()

Method that will return a flat map of all the ParFlow keys.

Returns:

Return Python dict with all the key set listed without

any hierarchy.

Return type:

dict

to_pf_name(parent_namespace, key)

Helper method returning the key to use for Parflow on a given field key. This allows us to handle differences between what can be defined in Python vs Parflow key.

validate(indent=1, verbose=False, enable_print=True, working_directory=None)

Method to validate sub hierarchy

value(location='.', skip_default=False)

Return a value based on a location.

e.g.:

run.ComputationalGrid.value(‘DX’) => 8.88 run.value(‘ComputationalGrid/DX’) => 8.88 run.value(‘/ComputationalGrid/DX’) => 8.88 run.Perm.value(‘../ComputationalGrid/DX’) => 8.88 run.Solver.value() => ‘Richards’

class parflow.tools.database.core.PFDBObjListNumber(parent=None)

Bases: PFDBObj

Class for leaf list values

to_pf_name(parent_namespace, key)

Helper method returning the key to use for Parflow on a given field key. This allows handling of differences between what can be defined in Python vs Parflow key.

parflow.tools.database.core.detail_helper(container, name, value)

Helper function that extract elements of the field’s detail

parflow.tools.database.core.extract_keys_from_dict(dict_to_fill, dict_obj, parent_namespace='')

Helper function to extract a flat key/value dictionary for a given PFDBObj inside dict_to_fill.

parflow.tools.database.core.extract_keys_from_object(dict_to_fill, instance, parent_namespace='')

Method that walk PFDBObj object and record their key and value inside a Python dict.

parflow.tools.database.core.flatten_hierarchical_map(hierarchical_map)

Helper function that take a hierarchical map and return a flat version of it.

parflow.tools.database.core.is_not_private_key(name)

Test if the given key is a key or a private member

Return True if it is a key

parflow.tools.database.core.is_private_key(name)

Test if the given key is a key or a private member

Return True if it is a private member

parflow.tools.database.core.to_str_dict_format(value)

Ensure that the output value is a valid string

parflow.tools.database.core.validate_helper(container, name, value, indent)

Helper function for validating a value

This module aims to gather all kind of value validation you would like to enable inside Parflow run.

class parflow.tools.database.domains.AddedInVersion

Bases: object

AddedInVersion domain deals with keys that were added to the ParFlow code in recent versions. It will check your version of ParFlow with the added version and print an error if your ParFlow version does not have the given key.

validate(value, arg, pf_version=None, **kwargs)

class parflow.tools.database.domains.AnyString

Bases: object

AnyString domain constrains the value to be a string or list of strings.

validate(value, **kwargs)

class parflow.tools.database.domains.BoolDomain

Bases: object

BoolDomain domain constrains the value to be a boolean.

validate(value, **kwargs)

class parflow.tools.database.domains.DeprecatedInVersion

Bases: object

DeprecatedInVersion domain deals with keys that have been or will be deprecated. It will check your version of ParFlow with the deprecated version and print an error or warning depending on whether the key has been deprecated.

validate(value, arg, pf_version=None, **kwargs)

class parflow.tools.database.domains.DoubleValue

Bases: object

DoubleValue domain constrains value to be a double (or int) while also ensure optionally if its value needs to be above or below another one.

The expected set of keyword arguments are:

• min_value: If available the value must be strictly above it

• max_value: If available the value must be strictly below it

validate(value, min_value=None, max_value=None, **kwargs)

class parflow.tools.database.domains.EnumDomain

Bases: object

EnumDomain domain constrains value to be a particular string that is part of a list defined in the enum_list.

The expected keyword argument is a list of the accepted values.

validate(value, enum_list=[], location='', locations=[], container=None, pf_version=None, **kwargs)

class parflow.tools.database.domains.IntValue

Bases: object

IntRange domain constrains value to be an integer while also ensure optionally if its value needs to be above or below another one.

The expected set of keyword arguments are:

• min_value: If available the value must be strictly above it

• max_value: If available the value must be strictly below it

validate(value, min_value=None, max_value=None, **kwargs)

class parflow.tools.database.domains.MandatoryValue

Bases: object

MandatoryValue makes sure that the key is set

If the value is not defined in the script and has a default value, the default value will be written out in the validation message and database file.

validate(value, **kwargs)

class parflow.tools.database.domains.RemovedInVersion

Bases: object

RemovedInVersion domain deals with keys that have been or will be removed from the ParFlow code. It will check your version of ParFlow with the removed version and print an error or warning depending on whether the key has been or will be removed.

validate(value, arg, pf_version=None, **kwargs)

class parflow.tools.database.domains.RequiresModule

Bases: object

RequiresModule domain deals with keys that require specific modules associated with ParFlow (e.g. CLM, SILO, NetCDF, etc.). It will check to see whether the required modules are installed with ParFlow and will print an error message if the required module is missing.

validate(value, arg, **kwargs)

class parflow.tools.database.domains.ValidFile

Bases: object

ValidFile domain checks the working directory to find the specified file.

validate(value, working_directory=None, path_prefix_source=None, container=None, **kwargs)

exception parflow.tools.database.domains.ValidationException

Bases: Exception

Basic parflow exception used for domains to report error

parflow.tools.database.domains.error(message)

Message decorator that add ERROR as type

parflow.tools.database.domains.filter_errors_by_type(msg_type, errors)

Extract decorated message for a given type

parflow.tools.database.domains.get_comparable_version(version)

Return an integer that can be used for comparison

Parameters:

version (str) – A version like ‘3.6.0’ or ‘v3.6.0’

Returns:

An integer that you can easily compare (i.e: 3006000)

Return type:

int

parflow.tools.database.domains.get_domain(class_name)

Return a domain instance based on its class_name or None if not found.

A message will be printed to notify the user that a domain was not found.

parflow.tools.database.domains.get_installed_parflow_module(module)

Helper function to test if a given module is available inside ParFlow This method rely on PARFLOW_DIR environment variable.

Parameters:

module (str) – Name of the module to test. (CLM, SILO, NetCDF, etc.)

Returns:

Return True if the provided module was found.

Return type:

bool

parflow.tools.database.domains.validate_value_to_string(container, value, has_default=False, domain_definition=None, domain_add_on_kwargs=None, history=None, indent=1)

This method validates the value set to a key using the domains provided in the key definition files. But it will return a string that could be used for printing information.

Parameters:

• container (PFDBObj) – Object that own the field

• name (str) – Name of the key that hold the value

• value – Value to check

• domain_definitions (dict) –

  Set of domains to test against. The structure will look like the one below: domain_definitions = {

  IntRangeDomain: {

  min_value: 1

  },

  NoNoneValueDomain:

  }

• domain_add_on_kwargs (dict) – This dictionary will contains global settings such as parflow version, working directory. This allow domains to validate things to a broader scale.

• history (array) – List of set values

• indent (int) – Depth level of the given value

Returns:

Number of detected issue message (str): String to print

Return type:

number_of_errors (int)

parflow.tools.database.domains.validate_value_with_errors(value, domain_definitions=None, domain_add_on_kwargs=None)

This method validates the value set to a key using the domains provided in the key definition files.

Parameters:

• value – Value to check

• domain_definitions (dict) –

  Set of domains to test against. The structure will look like the one below: domain_definitions = {

  IntRangeDomain: {

  min_value: 1

  },

  NoNoneValueDomain:

  }

• domain_add_on_kwargs (dict) – This dictionary will contains global settings such as parflow version, working directory. This allow domains to validate things to a broader scale.

Returns:

A list of tagged message

Return type:

List of errors/warnings

parflow.tools.database.domains.validate_value_with_exception(value, domain_definition=None, domain_add_on_kwargs=None, exit_on_error=False)

This method validates the value set to a key using the domains provided in the key definition files. But it will print information on where the error was detected (line number).

Parameters:

• value – Value to check

• domain_definitions (dict) –

  Set of domains to test against. The structure will look like the one below: domain_definitions = {

  IntRangeDomain: {

  min_value: 1

  },

  NoNoneValueDomain:

  }

• domain_add_on_kwargs (dict) – This dictionary will contains global settings such as parflow version, working directory. This allow domains to validate things to a broader scale.

• exit_on_error (bool) – If True the program will stop at the first error.

parflow.tools.database.domains.warning(message)

Message decorator that add WARNING as type

This module aims to gather all kind of value handler you would like to enable inside Parflow run.

A value handler is responsible to process the user input and returned a possibly modified version of it while maybe affecting that container object along the way.

class parflow.tools.database.handlers.ChildHandler

Bases: object

This class creates new keys from user-defined name input (e.g. GeomName)

decorate(value, container, class_name=None, location='.', eager=None, **kwargs)

class parflow.tools.database.handlers.ChildrenHandler

Bases: object

This class creates new keys from user-defined name inputs (e.g. GeomNames)

__init__()

decorate(value, container, class_name=None, location='.', eager=None, **kwargs)

class parflow.tools.database.handlers.ListHandler

Bases: object

This class ensures the output is not a single string but a list of trimmed string.

__init__()

decorate(value, container, **kwargs)

class parflow.tools.database.handlers.SplitHandler

Bases: object

This class will split the provided key using the separator convert each token using a type converter and set the field list.

decorate(value, container, separator='/', convert='int', fields=None, **kwargs)

exception parflow.tools.database.handlers.ValueHandlerException

Bases: Exception

Basic parflow exception used for ValueHandlers to report error

parflow.tools.database.handlers.decorate_value(value, container=None, handlers=None)

Return a decorated version of the value while possibly affecting other keys by creating children.

Parameters:

• value – Value to handle and maybe decorate

• container – The parent object that own the field where the value will be set.

• handlers –

  Set of handlers definitions. Example of content: {

  GeomInputUpdater: {

  type: ‘ChildrenHandler’, class_name: ‘GeomInputItemValue’, location: ‘../..’

  }, GeomUpdater: {

  type: ‘ChildrenHandler’, class_name: ‘GeomItem’, location: ‘../../Geom’

  }, ChildrenHandler: {

  class_name: ‘GeomInputLocal’

  }

  }

Returns:

Decorated version of the values. Typically for Names we ensure the output is not a single string but a list of trimmed string.

parflow.tools.database.handlers.get_handler(class_name, print_error=True)

Return a handler instance from a handler class name

Parameters:

• class_name (str) – Class name to instantiate.

• print_error (bool) – By default will print error if class not found

Returns:

Instance of that given class or None

Return type:

handler