nested_lookup
#############

.. image:: https://img.shields.io/badge/pypi-0.1.3-green.svg
  :target: https://pypi.python.org/pypi/nested-lookup

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!

.. contents::


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 .

tutorial
========

.. code-block:: python

 >>> from nested_lookup import nested_lookup

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

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


 wild
 ========

 We also have a `wild` mode that treats the given `key` as a case insensitive
 substring of all the keys in the document and returns any values which match.

 For example:

 .. code-block:: python

  from nested_lookup import nested_lookup

  my_document = {
      'name' : 'Russell Ballestrini',
      'email_address' : 'test1@example.com',
      'other' : {
          'secondary_email' : 'test2@example.com',
          'EMAIL_RECOVERY' : 'test3@example.com',
      },
  },

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

  print(results)
  ['test1@example.com', 'test2@example.com', 'test3@example.com']


  output
  ========

  There are two `output` modes:
    - `list`: the function returns a list of values corresponding to the
    matched keys.
    - `dict`: the function returns a `dict` with the matched keys as keys and
    their corresponding values as values.

  For example:

  .. code-block:: python

   from nested_lookup import nested_lookup

   my_document = {
       'name' : 'Russell Ballestrini',
       'email_address' : 'test1@example.com',
       'other' : {
           'secondary_email' : 'test2@example.com',
           'EMAIL_RECOVERY' : 'test3@example.com',
       },
   },

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

   print(results)
   {'email_address': 'test1@example.com',
   'secondary_email': 'test2@example.com',
   'EMAIL_RECOVERY': 'test3@example.com'}


misc
========

:license:
  * Public Domain

:authors:
  * Russell Ballestrini
  * Douglas Miranda

:web:
  * http://russell.ballestrini.net
  * http://douglasmiranda.com
  * https://gist.github.com/douglasmiranda/5127251