Dotli

Yet another library for flattening structures

Installation

pip install dotli

Usage

flatten

from dotli import Dotli

data = {
    'a': {
        'c': 'val1',
        'd': 'val2',
    },
    'b': {
        'c': 2,
        'd': {'key3': 'val3', 'key4': 'val4'},
    }
}

d = Dotli()                 # create an obj with a default configuration
flat = d.flatten(data)      # flatten
orig = d.unflatten(flat)    # unflatten
assert data == orig
print(flat)

{
  'a.c': 'val1',
  'a.d': 'val2',
  'b.c': 2,
  'b.d.key3': 'val3',
  'b.d.key4': 'val4',
}

The separator can be configured

data = {
    'a': {'c': 'd'},
    'b': {'e': 'f'}
}

d = Dotli(separator='-')
print(d.flatten(data))

{
  'a-c': 'd',
  'b-e': 'f',
}

It is also possible to flatten lists and a mixture of lists and dicts

data = {
    'a': {
        'c': [1, 2, 3],
        'd': ['e1', 'e2', 'e3'],
    },
    'b': 'h'
}

d = Dotli()
print(d.flatten(data))

{
  'a.c.0': 1,
  'a.c.1': 2,
  'a.c.2': 3,
  'a.d.0': 'e1',
  'a.d.1': 'e2',
  'a.d.2': 'e3',
  'b': 'h',
}

List indices can be wrapped in square brackets to allow numerical strings in dicts as keys

data = {
    'a': {
        '1': [1, 2, 3],
        '2': ['e1', 'e2', 'e3'],
    },
    'b': 'h'
}

d = Dotli(list_brackets=True)
flat = d.flatten(data)
orig = d.unflatten(flat)
assert data == orig
print(flat)

{
  'a.1.[0]': 1,
  'a.1.[1]': 2,
  'a.1.[2]': 3,
  'a.2.[0]': 'e1',
  'a.2.[1]': 'e2',
  'a.2.[2]': 'e3',
  'b': 'h',
}

There will be a nice error message if the dict can not be flattened including the path to the invalid element.

from dotli.errors import SeparatorInKeyError

data = {
    'a': {
        'b.b': 1,
    },
    'b': 'h'
}
try:
    Dotli().flatten(data)
except SeparatorInKeyError as e:
    print(e)

Separator "." is in key "b.b"! @ root.a

unflatten

When elements are missing in a list Dotli will throw an error

from dotli.errors import IncompleteListError

data = {
    'a.0': 0,
    'a.2': 2,
}
try:
    d = Dotli()
    d.unflatten(data)
except IncompleteListError as e:
    print(e)

No entry for index "1" in list! @ a

However it is possible to specify a fill value which will automatically be inserted into the list for missing entries

data = {
    'a.0': 0,
    'a.2': 2,
}

d = Dotli(fill_value_list=None)
print(d.unflatten(data))

{
  'a': [0, None, 2],
}