README.rst

nested_lookup

A small Python library which enables:

1. key lookups on deeply nested documents.
2. fetching all keys from a nested dictionary.
3. get the number of occurrences of a key/value from a nested dictionary

Documents may be built out of dictionaries (dicts) and/or lists.

Make working with JSON, YAML, and XML document responses fun again!

Contents

• install
• quick tutorial
• longer tutorial
• misc

install

install from pypi using pip:

pip install nested-lookup

or easy_install:

easy_install nested-lookup

or install from source using:

git clone https://github.com/russellballestrini/nested-lookup.git
cd nested-lookup
pip install .

quick tutorial

>>> from nested_lookup import nested_lookup

>>> document = [ { 'taco' : 42 } , { 'salsa' : [ { 'burrito' : { 'taco' : 69 } } ] } ]

>>> print(nested_lookup('taco', document))
[42, 69]

>>> from nested_lookup import get_all_keys

>>> get_all_keys(document)
['taco', 'salsa', 'burrito', 'taco']

>>> from nested_lookup import get_occurrence_of_key, get_occurrence_of_value

>>> get_occurrence_of_key(document, key='taco')
2

>>> get_occurrence_of_value(document, value='42')
1

longer tutorial

You may control the function's behavior by passing some optional arguments.

wild (defaults to False):

if wild is True, treat the given key as a case insensitive substring when performing lookups.

with_keys (defaults to False):

if with_keys is True, return a dictionary of all matched keys and a list of values.

For example, given the following document:

from nested_lookup import nested_lookup

my_document = {
   'name' : 'Russell Ballestrini',
   'email_address' : '[email protected]',
   'other' : {
       'secondary_email' : '[email protected]',
       'EMAIL_RECOVERY' : '[email protected]',
       'email_address' : '[email protected]',
    },
},

To get a list of every nested key in a document, run this:

from nested_lookup import get_all_keys

keys = get_all_keys(my_document)

print(keys)

['name', 'email_address', 'other', 'secondary_email', 'EMAIL_RECOVERY', 'email_address']

To get the number of occurrence of the given key/value

from nested_lookup import get_occurrence_of_key, get_occurrence_of_value

no_of_key_occurrence = get_occurrence_of_key(my_document, key='email_address')

print(no_of_key_occurrence)  # result => 2

no_of_value_occurrence = get_occurrence_of_value(my_document, value='[email protected]')

print(no_of_value_occurrence)  # result => 1

Next, we could act wild and find all the email addresses like this:

results = nested_lookup(
    key = 'mail',
    document = my_document,
    wild = True
)

print(results)

['[email protected]', '[email protected]', '[email protected]', '[email protected]']

Additionally, if you also needed the matched key names, you could do this:

results = nested_lookup(
    key = 'mail',
    document = my_document,
    wild = True,
    with_keys = True,
)

print(results)

{
 'email_address': ['[email protected]', '[email protected]'],
 'secondary_email': ['[email protected]'],
 'EMAIL_RECOVERY': ['[email protected]']
}

misc

license:	Public Domain
authors:	Russell Ballestrini Douglas Miranda Ramesh RV
web:	http://russell.ballestrini.net http://douglasmiranda.com https://gist.github.com/douglasmiranda/5127251