pyiron.base.generic.inputlist module

Lists structure for versatile input handling.

class pyiron.base.generic.inputlist.InputList(*args, **kwargs)

Bases: collections.abc.MutableMapping

Mutable sequence with optional keys.

If no argument is given, the constructor creates a new empty InputList. If specified init maybe a Sequence, Set or Mapping and all recursive occurrences of these are also wrapped by InputList. >>> pl = InputList([3, 2, 1, 0]) >>> pm = InputList({“foo”: 24, “bar”: 42})

Access can be like a normal list with integers or optionally with strings as keys. >>> pl[0] 3 >>> pl[2] 1 >>> pm[“foo”] 24

Keys do not have to be present for all elements. >>> pl2 = InputList([1,2]) >>> pl2[“end”] = 3 >>> pl2 InputList({0: 1, 1: 2, “end”: 3})

It is also allowed to set an item one past the length of the InputList, this is then equivalent to appending that element. This allows to use the update method also with other InputLists >>> pl[len(pl)] = -1 >>> pl InputList([3, 2, 1, 0, -1]) >>> pl.pop(-1) -1

Where strings are used they may also be used as attributes. Getting keys which clash with methods of InputList must be done with item access, but setting them works without overwriting the instance methods, but is not recommended for readability. >>> pm.foo 24 >>> pm.append = 23 >>> pm InputList({“foo”: 24, “bar”: 42, “append”: 23})

Keys and indices can be tuples to traverse nested InputLists. >>> pn = InputList({“foo”: {“bar”: [4, 2]}}) >>> pn[“foo”, “bar”] InputList([4, 2]) >>> pn[“foo”, “bar”, 0] 4

Using keys with “/” in them is equivalent to the above after splitting the key. >>> pn[“foo/bar”] == pn[“foo”, “bar”] True >>> pn[“foo/bar/0”] == pn[“foo”, “bar”, 0] True

To make that work strings that are only decimal digits are automatically converted to integers before accessing the list and keys are restricted to not only contain digits on initialization. >>> pl[“0”] == pl[0] True >>> InputList({1: 42}) Traceback (most recent call last):

File “<stdin>”, line 1, in <module> File “proplist.py”, line 126, in __init__

raise ValueError(

ValueError: keys in initializer must not be int or str of decimal digits or in correct order, is 1

When initializing from a dict, it may not have integers or decimal strings as keys unless they match their position in the insertion order. This is to avoid ambiguities in the final order of the InputList. >>> InputList({0: “foo”, 1: “bar”, 2: 42}) InputList([“foo”, “bar”, 42]) >>> InputList({0: “foo”, 2: 42, 1: “bar”}) Traceback (most recent call last):

File “<stdin>”, line 1, in <module> File “proplist.py”, line 132, in __init__

raise ValueError(

ValueError: keys in initializer must not be int or str of decimal digits or in correct order, is 2

Using keys is completely optional, InputList can always be treated as a list, with the exception that iter() iterates of the keys and indices. This is to correctly implement the MutableMapping protocol, to convert to a normal list and discard the keys use values(). >>> pm[0] 24 >>> pn[“0/0/1”] 2 >>> list(pl) [0, 1, 2, 3] >>> list(pl.values()) [3, 2, 1, 0] >>> list(pl.keys()) [0, 1, 2, 3]

append(val)

Add new value to the list without a key.

Parameters

val – new element

clear()

Remove all items from InputList.

copy()

Returns deep copy of it self. A shallow copy can be obtained via the copy module.

Returns

deep copy of itself

Return type

InputList

>>> pl = InputList([[1,2,3]])
>>> pl.copy() == pl
True
>>> pl.copy() is pl
False
>>> all(a is not b for a, b in zip(pl.copy().values(), pl.values()))
True

create_group(name)

Add a new empty sublist under the given key.

Parameters

name (str) – key under which to store the new sublist in this list

Returns

the newly created sublist

Return type

InputList

>>> pl = InputList({})
>>> pl.create_group("group_name")
InputList([])
>>> list(pl.group_name)
[]

extend(vals)

Append vals to the end of this InputList.

Parameters

vals (Sequence) – any python sequence to draw new elements from

from_hdf(hdf, group_name=None)

Restore the InputList from an HDF5 file. If group_name or self.table_name are not None, open a sub group in hdf prior to reading if not read directly from hdf. group_name overrides self.table_name if both are not None.

Parameters

• hdf (ProjectHDFio) – HDF5 group object

• group_name (str, optional) – HDF5 subgroup name, overrides self.table_name

get(key, default=None, create=False)

If key exists, behave as generic, if not call create_group.

Parameters

• key (str) – key to search

• default (optional) – return this instead if nothing found

• create (bool, optional) – create empty list at key if nothing found

Raises

• IndexError – if key is not in the list and neither default not

• create are given –

Returns

element at key or new empty sublist

Return type

object

has_keys()

Check if the list has keys set or not.

Returns

True if there is at least one key set

Return type

bool

insert(index, val, key=None)

Add a new element to the list at the specified position, with an optional key. If the key is already in the list it will be updated to point to the new element at the new index. If index is larger than list, append instead.

Parameters

• index (int) – place val after this element

• val – new element to add

• key (str, optional) – optional key to mark the new element

mark(index, key)

Add a key to an existing item at index. If key already exists, it is overwritten.

Parameters

• index (int) – index of the existing element to mark

• key (str) – key for the existing element

Raises

IndexError – if index > len(self)

>>> pl = InputList([42])
>>> pl.mark(0, "head")
>>> pl.head == 42
True

to_builtin(stringify=False)

Convert the list back to builtin dict”s and list”s recursively.

Parameters

• stringify (bool, optinal) – convert all non-recursive elements to

• str –

to_hdf(hdf, group_name=None)

Store the InputList in an HDF5 file. If group_name or self.table_name are not None, create a sub group in hdf prior to writing if not save directly to hdf. group_name overrides self.table_name if both are not None.

Parameters

• hdf (ProjectHDFio) – HDF5 group object

• group_name (str, optional) – HDF5 subgroup name, overrides self.table_name

update(init, wrap=False, **kwargs)

Add all elements or key-value pairs from init to this list. If wrap is not given, behaves as the generic method.

Parameters

• init (Sequence, Set, Mapping) – container to draw new elements from

• wrap (bool) – if True wrap all encountered Sequences and Mappings in InputLists recursively

• **kwargs – update from this mapping as well