Flatsplode

Flatten/Explode JSON objects.

Installation

pip install flatsplode

Usage

Use the flatsplode() function to recursively flatten and explode complex JSON objects.

Import the flatsplode function:

from flatsplode import flatsplode

Create a sample object to flatsplode:

item = {
    'id': '78e5b18c',
    'keywords': [
        'fizz',
        'buzz'
    ],
    'attrs': [
        {'name': 'color', 'value': 'green'},
        {'name': 'size', 'value': 42},
    ],
    'deep': {
        'nested': {
            'keys': {
                'fizz': 'buzz',
                'jazz': 'fuzz',
            }
        }
    }
}

Calling flatsplode(item) will return a generator. Use list() to expand:

list(flatsplode(item))

[
    {
        'id': '78e5b18c',
        'keywords': 'fizz',
        'attrs.name': 'color',
        'attrs.value': 'green',
        'deep.nested.keys.fizz': 'buzz',
        'deep.nested.keys.jazz': 'fuzz'
    },
    {
        'id': '78e5b18c',
        'keywords': 'fizz',
        'attrs.name': 'size',
        'attrs.value': 42,
        'deep.nested.keys.fizz': 'buzz',
        'deep.nested.keys.jazz': 'fuzz'
    },
    {
        'id': '78e5b18c',
        'keywords': 'buzz',
        'attrs.name': 'color',
        'attrs.value': 'green',
        'deep.nested.keys.fizz': 'buzz',
        'deep.nested.keys.jazz': 'fuzz'
    },
    {
        'id': '78e5b18c',
        'keywords': 'buzz',
        'attrs.name': 'size',
        'attrs.value': 42,
        'deep.nested.keys.fizz': 'buzz',
        'deep.nested.keys.jazz': 'fuzz'
    }
]

You can also provide your own join-character:

list(flatsplode(item, '/'))

[
    {
        'id': '78e5b18c',
        'keywords': 'fizz',
        'attrs/name': 'color',
        'attrs/value': 'green',
        'deep/nested/keys/fizz': 'buzz',
        'deep/nested/keys/jazz': 'fuzz'
    },
    …
]

Flatsploding is useful when converting objects to pandas DataFrame matrices:

import pandas
from flatsplode import flatsplode

pandas.DataFrame(flatsplode(item))

Pandas also has a built in normalizer that will flatten (but not explode) your data:

from flatsplode import explode

pandas.json_normalize(explode(item))

Result:

         id attrs.name attrs.value deep.nested.keys.fizz deep.nested.keys.jazz keywords
0  78e5b18c      color       green                  buzz                  fuzz     fizz
1  78e5b18c       size          42                  buzz                  fuzz     fizz
2  78e5b18c      color       green                  buzz                  fuzz     buzz
3  78e5b18c       size          42                  buzz                  fuzz     buzz