Skip to main content

lookup a key in a deeply nested document of dicts and lists

Project description

A small Python library which enables key lookups on deeply nested documents.

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

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


install from pypi using pip:

pip install nested-lookup

or easy_install:

easy_install nested-lookup

or install from source using:

git clone
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]

longer tutorial

You may control the libraries 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' : '',
   'other' : {
       'secondary_email' : '',
       'EMAIL_RECOVERY' : '',
       'email_address' : '',

We could act wild and find all the email addresses like this:

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

['', '', '', '']

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,

 'email_address': ['', ''],
 'secondary_email': [''],


  • Public Domain
  • Russell Ballestrini
  • Douglas Miranda

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
nested_lookup-0.1.5-py2.7.egg (3.9 kB) Copy SHA256 hash SHA256 Egg 2.7 Apr 24, 2018
nested-lookup-0.1.5.tar.gz (3.1 kB) Copy SHA256 hash SHA256 Source None Apr 24, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page