Flatten It

Introduction

Flatten It uses iteration (no recursion) to flatten iterables into a dictionary where each key is a reference path and each value is the value at the respective path.

Features

• Produces valid Python or JS reference paths for supported string and numeric keys.
• Raises ValueError on circular references.
• Iterative algorithm; flatten deeply nested structures without causing a call stack overflow.

Table of contents

• Installation
• Usage
• API
• Test

Installation

pip install flatten_iterables

Usage

In this example, an object named data will be flattened into a dictionary of reference paths and their respective values. The resulting dictionary will be dumped to a JSON string.

import json
from flatten_iterables import fi

fi.key_style = "python"

data = {
    "dict": {"a": 42},
    "nested_dicts": {"a0": {"b0": 42, "b1": 23}},
    "empty_dict": {},
    "list": [42],
    "nested_lists": [
        [
            42,
        ],
    ],
    "empty_list": [],
    ...: 42,
}

print(json.dumps(fi.flatten(data), indent=2))

{
  "['dict']['a']": 42,
  "['nested_dicts']['a0']['b0']": 42,
  "['nested_dicts']['a0']['b1']": 23,
  "['empty_dict']": {},
  "['list'][0]": 42,
  "['nested_lists'][0][0]": 42,
  "['empty_list']": [],
  "[Ellipsis]": 42
}

By default Flatten It will flatten structures that contain instances of list and dict. Other iterable and mapping types are supported by adding their respective types to the iterables and mappables sets. Registered iterable types must support both iteration and len(). Iterables such as sets are traversed in their normal iteration order, which is not guaranteed to be stable.

In this example, a structure containing the types set and OrderedDict will be flattened. The type set is added to the iterables set and the type OrderedDict is added to the mappables set.

import json
from flatten_iterables import fi
from collections import OrderedDict

fi.iterables.add(set)
fi.mappables.add(OrderedDict)

data = {
    "set": {23, 42, 57},
    "ordered_dict": OrderedDict(a=23, b=42, c=57),
}

print(json.dumps(fi.flatten(data), indent=2))

{
  "['set'][0]": 57,
  "['set'][1]": 42,
  "['set'][2]": 23,
  "['ordered_dict']['a']": 23,
  "['ordered_dict']['b']": 42,
  "['ordered_dict']['c']": 57
}

API

fi.flatten(it)

• it Union[Iterable, Mapping] The configured iterable or mapping to be flattened. Raises TypeError for unsupported root values.

fi.key_style Literal["python", "js"] Specify a key style. Default: python

fi.iterables Set[Iterable] Add iterable candidates to this set. Default: {list}

fi.mappables Set[Mapping] Add mappable candidates to this set. Default: {dict}

Test

How to run the test

Clone the repository.

git clone https://github.com/adamjpatterson/flatten_iterables.git

Change directory into the root of the repository.

cd flatten_iterables

Install Hatch.

python -m pip install hatch

Run the tests.

hatch test