nestedfetch 0.1.1

Syntactic sugar to perform GET, SET and FLATTEN values from nested dictionaries and nested lists.

ℕ𝕖𝕤𝕥𝕖𝕕𝔽𝕖𝕥𝕔𝕙

Outline

1. Overview
2. Installation
3. Usage
4. Examples
   1. Fetch Value
   2. Set Value
   3. Flatten Nested Lists
5. How to Contribute

Overview

NestedFetch provides syntactic sugar 🍬 to deal with a nested python dictionary or a nested list 🐍.
You can get, set, update and flatten values from a deeply nested dictionary or a list with a more concise, easier and a more KeyError, IndexError free way 😌.
You can further flatten lists of lists having the same depth.

data = {
        "league": "Champions League",
        "matches": [
            {
                "match_id": "match_1",
                "goals": [
                {
                    "time": 13,
                    "scorrer": "Lionel Messi",
                    "assist": "Luis Suarez"
                },
                {
                    "time": 78,
                    "scorrer": "Luis Suarez",
                    "assist": "Ivan Rakitic"
                }]
            },
            {
                "match_id": "match_2",
                "goals": [
                {
                    "time": 36,
                    "scorrer": "C. Ronaldo",
                    "assist": "Luka Modric"
                }]
            }]
        }

Installation

NestedFetch works with Python3.
You can directly install it via pip

$ pip3 install nestedfetch

Usage

Import the methods from the package.

from nestedfetch import nested_get, nested_set

No need to instantiate any object, just use the methods specifying valid parameters.

Examples

Fetch Data

nested_get(data, keys, default=None, flatten=False)

@Arguments
data : dict / list
keys => List of sequential keys leading to the desired value to fetch
default => Specifies the default value to be returned if any specified key is not present. If not specified, it will be None
flatten => Specifies whether to flatten the returned value

@Return
Returns the fetched value if it exists, or returns specified default value

1. Fetch simple nested data :

data = {
            'name': 'Jesse Pinkman',
            'details': {
                'address':{
                    'city': 'Albuquerque'
                }
            }
        }
res = nested_get(data,['details','address','city'])
# res = Albuquerque

2. Fetch simple nested data with default value:

data = {
            'name': 'Jesse Pinkman',
            'details': {
                'address':{
                    'city': 'Albuquerque'
                }
            }
        }
res = nested_get(data,['details','address','state'], default=-1)
# res = -1

3. Fetch nested data:

data = {
            'name': 'Jesse Pinkman',
            'details': {
                'address':[{
                    'city': 'Albuquerque'
                },{
                    'city': 'El Paso'
                }]
            }
        }
res = nested_get(data,['details','address','city'])
# res = ['Albuquerque','El Paso']

4. Fetch nested data with default value:

data = {
            'name': 'Jesse Pinkman',
            'details': {
                'address':[{
                    'city': 'Albuquerque'
                },{
                    'city': 'El Paso'
                },{
                    'state': 'New Mexico'
                }]
            }
        }
res = nested_get(data,['details','address','city'], default= None)
# res = ['Albuquerque','El Paso', None]

5. Fetch nested data by specifing index:

data = {
            'name': 'Walter White',
            'details': {
                'address':[{
                    'city': 'Albuquerque'
                },{
                    'city': 'El Paso'
                }]
            }
        }
res = nested_get(data,['details','address','city', 0])
# res = Albuquerque

6. Fetch nested data without flatten:

data = {
        "league": "Champions League",
        "matches": [
            {
                "match_id": "match_1",
                "goals": [
                {
                    "time": 13,
                    "scorrer": "Lionel Messi",
                    "assist": "Luis Suarez"
                },
                {
                    "time": 78,
                    "scorrer": "Luis Suarez",
                    "assist": "Ivan Rakitic"
                }]
            },
            {
                "match_id": "match_2",
                "goals": [
                {
                    "time": 36,
                    "scorrer": "C. Ronaldo",
                    "assist": "Luka Modric"
                }]
            }]
        }
res = nested_get(data,['matches','goals','scorrer'])
# res = [['Lionel Messi', 'Luis Suarez'], ['C. Ronaldo']]

8. Fetch nested data with flatten:

data = {
        "league": "Champions League",
        "matches": [
            {
                "match_id": "match_1",
                "goals": [
                {
                    "time": 13,
                    "scorrer": "Lionel Messi",
                    "assist": "Luis Suarez"
                },
                {
                    "time": 78,
                    "scorrer": "Luis Suarez",
                    "assist": "Ivan Rakitic"
                }]
            },
            {
                "match_id": "match_2",
                "goals": [
                {
                    "time": 36,
                    "scorrer": "C. Ronaldo",
                    "assist": "Luka Modric"
                }]
            }]
        }
res = nested_get(data,['matches','goals','scorrer'], flatten=True)
# res = ['Lionel Messi', 'Luis Suarez', 'C. Ronaldo']

Set / Update Data

nested_set(data, keys, value, create_missing=False):

@Arguments
data => dict / list
keys => List of sequential keys leading to the desired value to set / update
value => Specifies the value to set / update
create_missing => Specifies whether to create new key while building up if the specified key does not exists

@Return
Returns the number of values updated

1. Update value of simple nested data :

data = {
            'name': 'Jesse Pinkman',
            'details': {
                'address':{
                    'city': 'Albuquerque'
                }
            }
        }
res = nested_set(data,['details','address','city'], "Denver")
# res = 1

# data = {
#             'name': 'Jesse Pinkman',
#             'details': {
#                 'address':{
#                     'city': 'Denver'
#                 }
#             }
#         }

2. Update nested data:

data = {
            'name': 'Jesse Pinkman',
            'details': {
                'address':[{
                    'city': 'Albuquerque'
                },{
                    'city': 'El Paso'
                }]
            }
        }
res = nested_set(data,['details','address','city'], "Denver")
# res = 2

# data = {
#     'name': 'Jesse Pinkman',
#     'details': {
#         'address':[{
#             'city': 'Denver'
#         },{
#             'city': 'Denver'
#         }]
#     }
# }

3. Update nested data with index:

data = {
            'name': 'Jesse Pinkman',
            'details': {
                'address':[{
                    'city': 'Albuquerque'
                },{
                    'city': 'El Paso'
                }]
            }
        }
res = nested_set(data,['details','address',0,'city'], "Denver")
# res = 1

# data = {
#     'name': 'Jesse Pinkman',
#     'details': {
#         'address':[{
#             'city': 'Denver'
#         },{
#             'city': 'El Paso'
#         }]
#     }
# }

4. Set nested data with create_missing :

data = {
            'name': 'Jesse Pinkman',
            'details': {
                'address':{
                    'city': 'Albuquerque'
                }
            }
        }
res = nested_set(data,['details','address','state'], "New Mexico", create_missing=True)
# res = 1

# data = {
#             'name': 'Jesse Pinkman',
#             'details': {
#                 'address':{
#                     'city': 'Denver',
#                     'state': 'New Mexico'
#                 }
#             }
#         }

Flatten Nested Lists

flatten_data(data):

@Arguments
data => list of list

@Return
Returns the flattened list

1. Flatten List of Lists

data = [[
    ['This','is'],
    ['flattened', 'data']
]]

res = flatten_data(data)
# res = ['This','is','flattened','data']

How to contribute

Contributions are welcome 😇.
Feel free to submit a patch, report a bug 🐛 or ask for a feature 🐣.
Please open an issue first to encourage and keep track of potential discussions 📝.