Usage

The basic API is available for working with conventional namelist files and performing simple operations, such as reading or modifying values.

Users who require more control over parsing and namelist output formatting should create objects which can be controlled using the properties described below.

Basic API

f90nml.read(nml_path)

Parse a Fortran namelist file and return its contents.

File object usage:

>>> with open(nml_path) as nml_file:
>>>     nml = f90nml.read(nml_file)

File path usage:

>>> nml = f90nml.read(nml_path)

This function is equivalent to the read function of the Parser object.

>>> parser = f90nml.Parser()
>>> nml = parser.read(nml_file)

f90nml.write(nml, nml_path, force=False, sort=False)

Save a namelist to disk using either a file object or its file path.

File object usage:

>>> with open(nml_path, 'w') as nml_file:
>>>     f90nml.write(nml, nml_file)

File path usage:

>>> f90nml.write(nml, 'data.nml')

This function is equivalent to the write function of the Namelist object nml.

>>> nml.write('data.nml')

By default, write will not overwrite an existing file. To override this, use the force flag.

>>> nml.write('data.nml', force=True)

To alphabetically sort the Namelist keys, use the sort flag.

>>> nml.write('data.nml', sort=True)

f90nml.patch(nml_path, nml_patch, out_path=None)

Create a new namelist based on an input namelist and reference dict.

>>> f90nml.patch('data.nml', nml_patch, 'patched_data.nml')

This function is equivalent to the read function of the Parser object with the patch output arguments.

>>> parser = f90nml.Parser()
>>> nml = parser.read('data.nml', nml_patch, 'patched_data.nml')

A patched namelist file will retain any formatting or comments from the original namelist file. Any modified values will be formatted based on the settings of the Namelist object.

Classes

class f90nml.parser.Parser

Fortran namelist parser.

read(nml_fname, nml_patch_in=None, patch_fname=None)

Parse a Fortran namelist file and store the contents.

>>> parser = f90nml.Parser()
>>> data_nml = parser.read('data.nml')

reads(nml_string)

Parse a namelist string and return an equivalent Namelist object.

>>> parser = f90nml.Parser()
>>> data_nml = parser.reads('&data_nml x=1 y=2 /')

property comment_tokens

Return a string of single-character comment tokens in the namelist.

Type:

str

Default:

'!'

Some Fortran programs will introduce alternative comment tokens (e.g. #) for internal preprocessing.

If you need to support these tokens, create a Parser object and set the comment token as follows:

>>> parser = f90nml.Parser()
>>> parser.comment_tokens += '#'
>>> nml = parser.read('sample.nml')

Be aware that this is non-standard Fortran and could mangle any strings using the # characters. Characters inside string delimiters should be protected, however.

property default_start_index

Assumed starting index for a vector.

Type:

int

Default:

1

Since Fortran allows users to set an arbitrary start index, it is not always possible to assign an index to values when no index range has been provided.

For example, in the namelist idx.nml shown below, the index of the values in the second assignment are ambiguous and depend on the implicit starting index.

&idx_nml
    v(3:5) = 3, 4, 5
    v = 1, 2
/

The indices of the second entry in v are ambiguous. The result for different values of default_start_index are shown below.

>>> parser = f90nml.Parser()
>>> parser.default_start_index = 1
>>> nml = parser.read('idx.nml')
>>> nml['idx_nml']['v']
[1, 2, 3, 4, 5]

>>> parser.default_start_index = 0
>>> nml = parser.read('idx.nml')
>>> nml['idx_nml']['v']
[1, 2, None, 3, 4, 5]

property global_start_index

Define an explicit start index for all vectors.

Type:

int, None

Default:

None

When set to None, vectors are assumed to start at the lowest specified index. If no index appears in the namelist, then default_start_index is used.

When global_start_index is set, then all vectors will be created using this starting index.

For the namelist file idx.nml shown below,

&idx_nml
   v(3:5) = 3, 4, 5
/

the following Python code behaves as shown below.

>>> parser = f90nml.Parser()
>>> nml = parser.read('idx.nml')
>>> nml['idx_nml']['v']
[3, 4, 5]

>>> parser.global_start_index = 1
>>> nml = parser.read('idx.nml')
>>> nml['idx_nml']['v']
[None, None, 3, 4, 5]

Currently, this property expects a scalar, and applies this value to all dimensions.

property row_major

Read multidimensional arrays in row-major format.

Type:

bool

Default:

False

Multidimensional array data contiguity is preserved by default, so that column-major Fortran data is represented as row-major Python list of lists.

The row_major flag will reorder the data to preserve the index rules between Fortran to Python, but the data will be converted to row-major form (with respect to Fortran).

property sparse_arrays

Store unset rows of multidimensional arrays as empty lists.

Type:

bool

Default:

False

Enabling this flag will replace rows of unset values with empty lists, and will also not pad any existing rows when other rows are expanded.

This is not a true sparse representation, but rather is slightly more sparse than the default dense array representation.

property strict_logical

Use strict rules for parsing logical data value parsing.

Type:

bool

Default:

True

The strict_logical flag will limit the parsing of non-delimited logical strings as logical values. The default value is True.

When strict_logical is enabled, only .true., .t., true, and t are interpreted as True, and only .false., .f., false, and f are interpreted as false.

When strict_logical is disabled, any value starting with .t or t is interpreted as True, while any string starting with .f or f is interpreted as False, as described in the language standard. However, it can interfere with namelists which contain non-delimited strings.

class f90nml.namelist.Namelist(default_start_index=None[, items])

Representation of Fortran namelist in a Python environment.

Namelists can be initialised as empty or with a pre-defined dict of items. If an explicit default start index is required for items, then it can be initialised with the default_start_index input argument.

In addition to the standard methods supported by dict, several additional methods and properties are provided for working with Fortran namelists.

class RepeatValue(n, value)

Container class for output using repeat counters.

add_cogroup(key, val)

Append a duplicate group to the Namelist as a new group.

create_cogroup(group_name)

Convert an existing namelist group to a cogroup.

get(key, default=None)

Return the value for key if key is in the Namelist, else default.

groups()

Return an iterator that spans values with group and variable names.

Elements of the iterator consist of a tuple containing two values. The first is internal tuple containing the current namelist group and its variable name. The second element of the returned tuple is the value associated with the current group and variable.

items()

Return the namelist keys as an ItemsView.

keys()

Return the namelist keys as a KeysView.

patch(nml_patch)

Update the namelist from another partial or full namelist.

This is different from the intrinsic update() method, which replaces a namelist section. Rather, it updates the values within a section.

todict(complex_tuple=False)

Return a dict equivalent to the namelist.

Since Fortran variables and names cannot start with the _ character, any keys starting with this token denote metadata, such as starting index.

The complex_tuple flag is used to convert complex data into an equivalent 2-tuple, with metadata stored to flag the variable as complex. This is primarily used to facilitate the storage of the namelist into an equivalent format which does not support complex numbers, such as JSON or YAML.

write(nml_path, force=False, sort=False)

Write Namelist to a Fortran 90 namelist file.

>>> nml = f90nml.read('input.nml')
>>> nml.write('out.nml')

property column_width

Set the maximum number of characters per line of the namelist file.

Type:

int

Default:

72

Tokens longer than column_width are allowed to extend past this limit.

property default_start_index

Set the default start index for vectors with no explicit index.

Type:

int, None

Default:

None

When the default_start_index is set, all vectors without an explicit start index are assumed to begin with default_start_index. This index is shown when printing the namelist output.

If set to None, then no start index is assumed and is left as implicit for any vectors undefined in start_index.

property end_comma

Append commas to the end of namelist variable entries.

Type:

bool

Default:

False

Fortran will generally disregard any commas separating variable assignments, and the default behaviour is to omit these commas from the output. Enabling this flag will append commas at the end of the line for each variable assignment.

property false_repr

Set the string representation of logical false values.

Type:

str

Default:

'.false.'

This is equivalent to the first element of logical_repr.

property float_format

Set the namelist floating point format.

Type:

str

Default:

''

The property sets the format string for floating point numbers, following the format expected by the Python format() function.

property indent

Set the whitespace indentation of namelist entries.

Type:

int, str

Default:

'    ' (four spaces)

This can be set to an integer, denoting the number of spaces, or to an explicit whitespace character, such as a tab (\t).

property index_spacing

Apply a space between indexes of multidimensional vectors.

Type:

bool

Default:

False

property logical_repr

Set the string representation of logical values.

Type:

dict

Default:

{False: '.false.', True: '.true.'}

There are multiple valid representations of True and False values in Fortran. This property sets the preferred representation in the namelist output.

The properties true_repr and false_repr are also provided as interfaces to the elements of logical_repr.

property repeat_counter

Return whether the namelist uses repeat counters for arrays.

If True, then arrays with repeated values will use repeat tokens. For example, the array [1, 2, 2, 2] will be written as 1, 3*2.

Type:

bool

Default:

False

property split_strings

Split strings at the column_width over multiple lines.

Type:

bool

Default:

False

property start_index

Set the starting index for each vector in the namelist.

Type:

dict

Default:

{}

start_index is stored as a dict which contains the starting index for each vector saved in the namelist. For the namelist vec.nml shown below,

&vec_nml
    a = 1, 2, 3
    b(0:2) = 0, 1, 2
    c(3:5) = 3, 4, 5
    d(:,:) = 1, 2, 3, 4
/

the start_index contents are

>>> import f90nml
>>> nml = f90nml.read('vec.nml')
>>> nml['vec_nml'].start_index
{'b': [0], 'c': [3], 'd': [None, None]}

The starting index of a is absent from start_index, since its starting index is unknown and its values cannot be assigned without referring to the corresponding Fortran source.

property true_repr

Set the string representation of logical true values.

Type:

str

Default:

.true.

This is equivalent to the second element of logical_repr.

property uppercase

Print group and variable names in uppercase.

Type:

bool

Default:

False

This is equivalent to the second element of logical_repr.