iterobj#

iterobj(obj, func=None, inplace=False, copy=False, leaf=False, recursion=0, depthfirst=True, atomic='default', skip=None, rootkey='root', verbose=False, flatten=False, to_df=False, *args, **kwargs)[source]#

Iterate over an object and apply a function to each node (item with or without children).

Can modify an object in-place, or return a value. See also sc.search() for a function to search through complex objects.

By default, lists, dictionaries, and objects are iterated over. For custom iteration options, see sc.IterObj().

Note: there are three different output possibilities, depending on the keywords:

  • inplace=False, copy=False (default): collate the output of the function into a flat dictionary, with keys corresponding to each node of the project

  • inplace=True, copy=False: modify the actual object in-place, such that the original object is modified

  • inplace=True, copy=True: make a deep copy of the object, modify that object, and return it (the original is unchanged)

Parameters:

  • obj (any) – the object to iterate over

  • func (function) – the function to apply; if None, return a flat dictionary of all nodes in the object

  • inplace (bool) – whether to modify the object in place (else, collate the output of the functions)

  • copy (bool) – if modifying an object in place, whether to make a copy first

  • leaf (bool) – whether to apply the function only to leaf nodes of the object

  • recursion (int) – number of recursive steps to allow, i.e. parsing the same objects multiple times (default 0)

  • depthfirst (bool) – whether to parse the object depth-first (default) or breadth-first

  • atomic (list) – a list of known classes to treat as atomic (do not descend into); if ‘default’, use defaults (e.g. np.array, pd.DataFrame)

  • skip (list) – a list of classes or object IDs to skip over entirely

  • rootkey (str) – the key to list as the root of the object (default 'root')

  • verbose (bool) – whether to print progress

  • flatten (bool) – whether to use flattened traces (single strings) rather than tuples

  • to_df (bool) – whether to return a dataframe of the output instead of a dictionary (not valid with inplace=True)

  • *args (list) – passed to func()

  • **kwargs (dict) – passed to func()

Examples:

data = dict(a=dict(x=[1,2,3], y=[4,5,6]), b=dict(foo='string', bar='other_string'))

# Search through an object
def check_int(obj):
    return isinstance(obj, int)

out = sc.iterobj(data, check_int)
print(out)


# Modify in place -- collapse mutliple short lines into one
def collapse(obj, maxlen):
    string = str(obj)
    if len(string) < maxlen:
        return string
    else:
        return obj

sc.printjson(data)
sc.iterobj(data, collapse, inplace=True, maxlen=10) # Note passing of keyword argument to function
sc.printjson(data)
New in version 3.0.0.
New in version 3.1.0: default func, renamed “twigs_only” to “leaf”, “atomic” argument
New in version 3.1.2: copy defaults to False; refactored into class
New in version 3.1.3: “rootkey” argument
New in version 3.1.5: “recursion” argument; better handling of atomic classes
New in version 3.1.6: “skip”, “depthfirst”, “to_df”, and “flatten” arguments
On this page