cmlm.utils.input_file

A module for interacting with TOML format input files based on tomlkit.

Functions

beautify_document(doc[, max_inline_length, ...])

Move inline comments top line above item in TOML string.

recursively_update_dict(base, new)

Update items and subitems in one nested dict-like object based on another.

scalar_to_list(val)

Leave lists as is, convert scalars to 1 element lists.

Classes

TomlParmParse(datadict[, accessed_data, ...])

Wrapper for tomlkit document class.
class cmlm.utils.input_file.TomlParmParse(datadict, accessed_data=None, name='<base>', base=None, **kwargs)

Bases: object

Wrapper for tomlkit document class.

Enables a few new features: - Easier access to nested parameters - Autodocumentation of inputs - Combining inputs from the command line and an input file - Saving the config that was actually used - Optionally raise errors for unused inputs

Inspired by the ParmParse class from AMReX, but quite different.

Parameters:

  • datadict (tomlkit.TOMLDocument) – input TOMLDocument that has been read in

  • accessed_data (tomlkit.TOMLDocument, optional) – shows which entries from data_dict have already been accessed Default None.

  • base (TomlParmParse, optional) – Parent TomlParmParse object. If None, this is a base TomlParmParse object and output will occur during garbage collecting if requested. Default None.

  • output (string, optional kwarg) – Directory in which to save output. Default None (no output saved).

  • output_type (str, optional kwarg) – Type of output to save: “clean” will save only inputs used with no comments. “doc” will save only inputs used with comments generated based on doc info provided when accessing variables. “original” keeps all variables, comments, and formatting from the provided input file. Default “clean”.

  • no_overwrite (bool, optional kwarg) – Raise an error if multiple different values are set/accessed for a variable. Default False.

  • error_unused (bool, optional kwarg) – Raise an error for unused variables in input file. Default False.

  • live_update (bool, optional kwarg) – Continuously update output file as code runs. Default False.

check_unused_inputs()

Return any keys in table that have not been used.

doc(doc)

Add a high level comment to the TOML document.

Parameters:

doc (optional) – string to add as a comment in the TOML file

Returns:

self – The updated TomlParmParse object

Return type:

TomlParmParse

dump(outfile=None)

Output TomlParmParse data to file.

Parameters:

outfile (str, optional) – file name to save to

get(item_name, default=None, doc=None, choices=None)

Retrieve a leaf or subtable form the TomlParmParse table.

Can optionally specify a default, otherwise an error will be raised if not found. Can also optionally specify a doc string to add to the TOML file for the input being retrieved.

Parameters:

  • item_name (str) – key to lookup in table. May parse through multiple levels in hierarchy by separating different levels with periods, e.g. lev1name.level2name.lev3name

  • default (optional) – value to use if item_name is not found in table

  • doc (optional) – string to add as a comment in the TOML file

  • choices (optional) – list or tuple of allowable options for input parameter. If specified, an error will be raised if the specified value is not in the list.

Returns:

retval – If item_name is not a leaf, a subtable of the TomlParmParse object, otherwise the leaf (which may be a string, int, list, etc.)

Return type:

TomlParmParse or any

classmethod parse_args(description=None, infile=None, require_output=False)

Parse command line arguments specifying file and arguments to create a TPP.

Parameters:

  • description (str, optional) – Short description of program for which config is being loaded

  • infile (str, optional) – Default TOML input file to use

  • require_output (bool, optional) – if true, the -o command line argument is required. Default False.

Returns:

tpp – A TOML ParmParser

Return type:

TomlParmParse

classmethod parse_file(file_name=None, additional_args=None, **kwargs)

Parse a file and/or string into a TomlParmParse object.

Parameters:

  • file_name (str (path-like), optional) – File to load as a tomlkit Document

  • additional_args (str (toml), optional) – TOML format string of parameters to add to the file

  • kwargs (optional) – Passed to TomlParmParse constructor

Returns:

tpp – A TOML ParmParser

Return type:

TomlParmParse

set(item_name, value, doc=None)

Set value for a leaf in the table.

Parameters:

  • item_name (str) – key for the item being added

  • value (int, str, list, etc.) – value for the item being added (must be TOML format compatible type)

  • doc (str) – comment to add for item in TOML file

cmlm.utils.input_file.beautify_document(doc, max_inline_length=20, max_line_length=88)

Move inline comments top line above item in TOML string.

Parameters:

  • doc (str (TOML format)) – string representation of document being updated

  • max_inline_length (int, default 20) – Maximum length of comment to leave as inline, but total line length must still be less than max_line_length or comment will be moved

  • max_line_length (int, default 88) – Maximum line length for wrapping comment text

cmlm.utils.input_file.recursively_update_dict(base, new)

Update items and subitems in one nested dict-like object based on another.

For each key in new.keys(), replace base[key] with new[key], unless new[key] also has a .keys() attribute, in which case this function is recursively called to update the sub-dict-like.

Parameters:

  • base (dict-like) – Input (nested) dictionary to update

  • new (dict-like) – (Nested) dictionary entries to update in base

cmlm.utils.input_file.scalar_to_list(val)

Leave lists as is, convert scalars to 1 element lists.