ansible-later/testenv/lib/python2.7/site-packages/nested_lookup-0.2.12.dist-info/METADATA
2019-04-23 13:04:27 +02:00

235 lines
5.8 KiB
Plaintext

Metadata-Version: 2.1
Name: nested-lookup
Version: 0.2.12
Summary: Python functions for working with deeply nested documents (lists and dicts)
Home-page: https://github.com/russellballestrini/nested-lookup
Author: Russell Ballestrini
Author-email: russell@ballestrini.net
License: Public Domain
Keywords: nested document dictionary dict list lookup schema json xml yaml
Platform: All
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Dist: six
nested_lookup
#############
.. image:: https://img.shields.io/badge/pypi-0.2.12-green.svg
:target: https://pypi.python.org/pypi/nested-lookup
Make working with JSON, YAML, and XML document responses fun again!
The `nested_lookup` package provides many Python functions for working with deeply nested documents.
A document in this case is a a mixture of Python dictionary and list objects typically derived from YAML or JSON.
*nested_lookup:*
Perform a key lookup on a deeply nested document.
Returns a `list` of matching values.
*nested_update:*
Given a document, find all occurences of the given key and update the value.
By default, returns a copy of the document.
To mutate the original specify the `in_place=True` argument.
*nested_delete:*
Given a document, find all occurrences of the given key and delete it.
By default, returns a copy of the document.
To mutate the original specify the `in_place=True` argument.
*get_all_keys:*
Fetch all keys from a deeply nested dictionary.
Returns a `list` of keys.
*get_occurrence_of_key/get_occurrence_of_value:*
Returns the number of occurrences of a key/value from a nested dictionary.
For example function invocations, plesae see the tutorial.
.. 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 .
quick tutorial
==============
.. code-block:: python
>>> from nested_lookup import nested_lookup
>>> document = [ { 'taco' : 42 } , { 'salsa' : [ { 'burrito' : { 'taco' : 69 } } ] } ]
>>> print(nested_lookup('taco', document))
[42, 69]
>>> from nested_lookup import nested_update, nested_delete
>>> nested_update(document, key='burrito', value='Test')
[{'taco': 42}, {'salsa': [{'burrito': 'Test'}]}]
>>> nested_delete(document, 'taco')
[{}, {'salsa': [{'burrito': {}}]}]
>>> 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:
.. 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',
'email_address' : 'test4@example.com',
},
},
Next, we could act `wild` and find all the email addresses like this:
.. code-block:: python
results = nested_lookup(
key = 'mail',
document = my_document,
wild = True
)
print(results)
.. code-block:: python
['test1@example.com', 'test4@example.com', 'test2@example.com', 'test3@example.com']
Additionally, if you also needed the matched key names, you could do this:
.. code-block:: python
results = nested_lookup(
key = 'mail',
document = my_document,
wild = True,
with_keys = True,
)
print(results)
.. code-block:: python
{
'email_address': ['test1@example.com', 'test4@example.com'],
'secondary_email': ['test2@example.com'],
'EMAIL_RECOVERY': ['test3@example.com']
}
To Get / Delete / Update a key->value pair in nested document
.. code-block:: python
from nested_lookup import nested_update, nested_delete
result = nested_delete(my_document, 'EMAIL_RECOVERY')
print(result) # result => {'other': {'secondary_email': 'test2@example.com', 'email_address': 'test4@example.com'}, 'email_address': 'test1@example.com', 'name': 'Russell Ballestrini'}
result = nested_update(my_document, key='other', value='Test')
print(result) # result => {'other': 'Test', 'email_address': 'test1@example.com', 'name': 'Russell Ballestrini'}
To get a list of every nested key in a document, run this:
.. code-block:: python
from nested_lookup import get_all_keys
keys = get_all_keys(my_document)
print(keys)
.. code-block:: python
['name', 'email_address', 'other', 'secondary_email', 'EMAIL_RECOVERY', 'email_address']
To get the number of occurrence of the given key/value
.. code-block:: python
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='test2@example.com')
print(no_of_value_occurrence) # result => 1
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