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.
*nested_alter:*
Given a document, find all occurrences of the given key and alter it with a callback function.
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 examples on how to invoke these functions, please check out the tutorial sections.
.. contents::
install
========
install from pypi using pip::
pip install nested-lookup
or install from source using::
git clone ssh://git@git.unturf.com:2222/python/nested-lookup.git
cd nested-lookup
pip install .
quick tutorial
==============
This tutorial uses the Python Interactive shell, please follow along : )
Before we start, let's define an example document to work on.
.. code-block:: python
>>> document = [ { 'taco' : 42 } , { 'salsa' : [ { 'burrito' : { 'taco' : 69 } } ] } ]
First, we lookup a key from all layers of a document using ``nested_lookup``:
.. code-block:: python
>>> from nested_lookup import nested_lookup
>>> print(nested_lookup('taco', document))
[42, 69]
As you can see the function returned a list of two integers, these integers are the values from the matched key lookups.
Next, we update a key and value from all layers of a document using ``nested_update``:
.. code-block:: python
>>> from nested_lookup import nested_update
>>> nested_update(document, key='burrito', value='test')
[{'taco': 42}, {'salsa': [{'burrito': 'test'}]}]
Here you see that the key ``burrito`` had it's value changed to the string ``'test'``, like we asked.
Finally, we try out a delete operation using ``nested_delete``:
.. code-block:: python
>>> from nested_lookup import nested_delete
>>> nested_delete(document, 'taco')
[{}, {'salsa': [{'burrito': {}}]}]
Perfect, the returned document looks just like we expected!
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" : "Rocko 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"]
}
We do not mutate input, if we do you found a defect. Please open an issue.
Let's delete and update our deeply nested key / values and see the results:
.. code-block:: python
from nested_lookup import nested_update, nested_delete
# result => {'other': {'secondary_email': 'test2@example.com', 'email_address': 'test4@example.com'}, 'email_address': 'test1@example.com', 'name': 'Rocko Ballestrini'}
result = nested_delete(my_document, 'EMAIL_RECOVERY')
print(result)
# result => {'other': 'Test', 'email_address': 'test1@example.com', 'name': 'Rocko Ballestrini'}
result = nested_update(my_document, key='other', value='Test')
print(result)
Now let's say we wanted to get a list of every nested key in a document, we could 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']
Also, to get the number of times a key or value occurs in the document, try:
.. code-block:: python
from nested_lookup import (
get_occurrence_of_key,
get_occurrence_of_value,
)
# result => 2
key_occurrence_count = get_occurrence_of_key(my_document, key='email_address')
print(no_of_key_occurrence)
# result => 1
value_occurrence_count = get_occurrence_of_value(my_document, value='test2@example.com')
print(no_of_value_occurrence)
To get the number of occurrence and their respective values
.. code-block:: python
from nested_lookup import get_occurrences_and_values
my_documents = [
{
"processor_name": "4",
"processor_speed": "2.7 GHz",
"core_details": {
"total_numberof_cores": "4",
"l2_cache(per_core)": "256 KB",
}
}
]
result = get_occurrences_and_values(my_documents, value='4')
print(result)
{
"4": {
"occurrences": 2,
"values": [
{
"processor_name": "4",
"processor_speed": "2.7 GHz",
"core_details": {
"total_numberof_cores": "4",
"l2_cache(per_core)": "256 KB"
}
},
{
"total_numberof_cores": "4",
"l2_cache(per_core)": "256 KB"
}
]
}
}
nested_alter tutorial
=====================
*Nested Alter*:
write a callback function which processes a scalar value.
Be aware about the possible types which can be passed to the callback functions.
In this example we can be sure that only int will be passed, in production you should check the type because it could be anything.
Before we start, let's define an example document to work on.
.. code-block:: python
>>> document = [ { 'taco' : 42 } , { 'salsa' : [ { 'burrito' : { 'taco' : 69 } } ] } ]
.. code-block:: python
>>> def callback(data):
>>> return data + 10 # add 10 to every taco prize
The alter-version only works for scalar input (one dict), if you need to adress a list of dicts, you have to
manually iterate over those and pass them to nested_update one by one
.. code-block:: python
>>> out =[]
>>> for elem in document:
>>> altered_document = nested_alter(elem,"taco", callback)
>>> out.append(altered_document)
>>> print(out)
[ { 'taco' : 52 } , { 'salsa' : [ { 'burrito' : { 'taco' : 79 } } ] } ]
>>> 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
misc
========
:license:
* Public Domain
:authors:
* Russell Ballestrini
* Douglas Miranda
* Ramesh RV
* Salfiii (Florian S.)
* Matheus Lins
:web:
* https://russell.ballestrini.net
* http://douglasmiranda.com (https://gist.github.com/douglasmiranda/5127251)
* https://github.com/Salfiii
* https://github.com/matheuslins
Raw data
{
"_id": null,
"home_page": "https://git.unturf.com/python/nested-lookup",
"name": "nested-lookup",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "nested document dictionary dict list lookup schema json xml yaml",
"author": "Russell Ballestrini",
"author_email": "russell.ballestrini@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fd/42/7d6a06916aba63124eb30d2ff638cf76054f6aeea529d47f1859c3b5ccae/nested-lookup-0.2.25.tar.gz",
"platform": "All",
"description": "nested_lookup\n#############\n\nMake working with JSON, YAML, and XML document responses fun again!\n\nThe `nested_lookup` package provides many Python functions for working with deeply nested documents.\nA document in this case is a a mixture of Python dictionary and list objects typically derived from YAML or JSON.\n\n*nested_lookup:*\n Perform a key lookup on a deeply nested document.\n Returns a ``list`` of matching values.\n\n*nested_update:*\n Given a document, find all occurences of the given key and update the value.\n By default, returns a copy of the document.\n To mutate the original specify the ``in_place=True`` argument.\n\n*nested_delete:*\n Given a document, find all occurrences of the given key and delete it.\n By default, returns a copy of the document.\n To mutate the original specify the ``in_place=True`` argument.\n \n*nested_alter:*\n Given a document, find all occurrences of the given key and alter it with a callback function.\n By default, returns a copy of the document.\n To mutate the original specify the ``in_place=True`` argument.\n\n*get_all_keys:*\n Fetch all keys from a deeply nested dictionary.\n Returns a ``list`` of keys.\n\n*get_occurrence_of_key/get_occurrence_of_value:*\n Returns the number of occurrences of a key/value from a nested dictionary.\n\nFor examples on how to invoke these functions, please check out the tutorial sections.\n\n\n.. contents::\n\n\ninstall\n========\n\ninstall from pypi using pip::\n\n pip install nested-lookup\n\nor install from source using::\n\n git clone ssh://git@git.unturf.com:2222/python/nested-lookup.git\n cd nested-lookup\n pip install .\n\n\nquick tutorial\n==============\n\nThis tutorial uses the Python Interactive shell, please follow along : )\n\nBefore we start, let's define an example document to work on.\n\n.. code-block:: python\n\n >>> document = [ { 'taco' : 42 } , { 'salsa' : [ { 'burrito' : { 'taco' : 69 } } ] } ]\n\n\nFirst, we lookup a key from all layers of a document using ``nested_lookup``:\n\n.. code-block:: python\n\n >>> from nested_lookup import nested_lookup\n >>> print(nested_lookup('taco', document))\n [42, 69]\n \nAs you can see the function returned a list of two integers, these integers are the values from the matched key lookups.\n\nNext, we update a key and value from all layers of a document using ``nested_update``:\n\n.. code-block:: python\n\n >>> from nested_lookup import nested_update\n >>> nested_update(document, key='burrito', value='test')\n [{'taco': 42}, {'salsa': [{'burrito': 'test'}]}]\n \nHere you see that the key ``burrito`` had it's value changed to the string ``'test'``, like we asked.\n\nFinally, we try out a delete operation using ``nested_delete``:\n\n.. code-block:: python\n\n >>> from nested_lookup import nested_delete\n >>> nested_delete(document, 'taco')\n [{}, {'salsa': [{'burrito': {}}]}]\n\nPerfect, the returned document looks just like we expected!\n\n\nlonger tutorial\n======================\n\nYou may control the function's behavior by passing some optional arguments.\n\nwild (defaults to `False`):\n if `wild` is `True`, treat the given `key` as a case insensitive\n substring when performing lookups.\n\nwith_keys (defaults to `False`):\n if `with_keys` is `True`, return a dictionary of all matched keys\n and a list of values.\n\nFor example, given the following document:\n\n.. code-block:: python\n\n from nested_lookup import nested_lookup\n\n my_document = {\n \"name\" : \"Rocko Ballestrini\",\n \"email_address\" : \"test1@example.com\",\n \"other\" : {\n \"secondary_email\" : \"test2@example.com\",\n \"EMAIL_RECOVERY\" : \"test3@example.com\",\n \"email_address\" : \"test4@example.com\",\n },\n }\n\nNext, we could act ``wild`` and find all the email addresses like this:\n\n.. code-block:: python\n\n results = nested_lookup(\n key = \"mail\",\n document = my_document,\n wild = True\n )\n\n print(results)\n\n.. code-block:: python\n\n [\"test1@example.com\", \"test4@example.com\", \"test2@example.com\", \"test3@example.com\"]\n\nAdditionally, if you also needed the matched key names, you could do this:\n\n.. code-block:: python\n\n results = nested_lookup(\n key = \"mail\",\n document = my_document,\n wild = True,\n with_keys = True,\n )\n\n print(results)\n\n.. code-block:: python\n\n {\n \"email_address\": [\"test1@example.com\", \"test4@example.com\"],\n \"secondary_email\": [\"test2@example.com\"],\n \"EMAIL_RECOVERY\": [\"test3@example.com\"]\n }\n\nWe do not mutate input, if we do you found a defect. Please open an issue.\n\nLet's delete and update our deeply nested key / values and see the results:\n\n.. code-block:: python\n\n from nested_lookup import nested_update, nested_delete\n\n # result => {'other': {'secondary_email': 'test2@example.com', 'email_address': 'test4@example.com'}, 'email_address': 'test1@example.com', 'name': 'Rocko Ballestrini'}\n result = nested_delete(my_document, 'EMAIL_RECOVERY')\n print(result)\n\n # result => {'other': 'Test', 'email_address': 'test1@example.com', 'name': 'Rocko Ballestrini'}\n result = nested_update(my_document, key='other', value='Test')\n print(result)\n\n\nNow let's say we wanted to get a list of every nested key in a document, we could run this:\n\n.. code-block:: python\n\n from nested_lookup import get_all_keys\n\n keys = get_all_keys(my_document)\n print(keys)\n\n.. code-block:: python\n\n ['name', 'email_address', 'other', 'secondary_email', 'EMAIL_RECOVERY', 'email_address']\n\nAlso, to get the number of times a key or value occurs in the document, try:\n\n.. code-block:: python\n\n from nested_lookup import (\n get_occurrence_of_key,\n get_occurrence_of_value,\n )\n\n # result => 2\n key_occurrence_count = get_occurrence_of_key(my_document, key='email_address')\n print(no_of_key_occurrence) \n\n # result => 1\n value_occurrence_count = get_occurrence_of_value(my_document, value='test2@example.com')\n print(no_of_value_occurrence)\n\nTo get the number of occurrence and their respective values\n\n.. code-block:: python\n\n from nested_lookup import get_occurrences_and_values\n \n my_documents = [\n {\n \"processor_name\": \"4\",\n \"processor_speed\": \"2.7 GHz\",\n \"core_details\": {\n \"total_numberof_cores\": \"4\",\n \"l2_cache(per_core)\": \"256 KB\",\n }\n }\n ]\n\n result = get_occurrences_and_values(my_documents, value='4')\n\n print(result)\n \n {\n\t \"4\": {\n\t\t \"occurrences\": 2,\n\t\t \"values\": [\n\t\t\t {\n\t\t\t\t \"processor_name\": \"4\",\n\t\t\t\t \"processor_speed\": \"2.7 GHz\",\n\t\t\t\t \"core_details\": {\n\t\t\t\t\t \"total_numberof_cores\": \"4\",\n\t\t\t\t\t \"l2_cache(per_core)\": \"256 KB\"\n\t\t\t\t }\n\t\t\t },\n\t\t\t {\n\t\t\t\t \"total_numberof_cores\": \"4\",\n\t\t\t\t \"l2_cache(per_core)\": \"256 KB\"\n\t\t\t }\n\t\t ]\n\t }\n }\n\n\n\n\n\nnested_alter tutorial\n=====================\n\n*Nested Alter*:\nwrite a callback function which processes a scalar value.\nBe aware about the possible types which can be passed to the callback functions.\nIn this example we can be sure that only int will be passed, in production you should check the type because it could be anything.\n\nBefore we start, let's define an example document to work on.\n\n.. code-block:: python\n\n >>> document = [ { 'taco' : 42 } , { 'salsa' : [ { 'burrito' : { 'taco' : 69 } } ] } ]\n\n.. code-block:: python\n\n >>> def callback(data):\n >>> return data + 10 # add 10 to every taco prize\n\nThe alter-version only works for scalar input (one dict), if you need to adress a list of dicts, you have to \nmanually iterate over those and pass them to nested_update one by one\n\n.. code-block:: python\n\n >>> out =[]\n >>> for elem in document:\n >>> altered_document = nested_alter(elem,\"taco\", callback)\n >>> out.append(altered_document)\n\n >>> print(out)\n [ { 'taco' : 52 } , { 'salsa' : [ { 'burrito' : { 'taco' : 79 } } ] } ]\n\n >>> from nested_lookup import get_all_keys\n\n >>> get_all_keys(document)\n ['taco', 'salsa', 'burrito', 'taco']\n\n >>> from nested_lookup import get_occurrence_of_key, get_occurrence_of_value\n\n >>> get_occurrence_of_key(document, key='taco')\n 2\n\n >>> get_occurrence_of_value(document, value='42')\n 1\n\n\nmisc\n========\n\n:license:\n * Public Domain\n\n:authors:\n * Russell Ballestrini\n * Douglas Miranda\n * Ramesh RV\n * Salfiii (Florian S.)\n * Matheus Lins\n\n:web:\n * https://russell.ballestrini.net\n * http://douglasmiranda.com (https://gist.github.com/douglasmiranda/5127251)\n * https://github.com/Salfiii\n * https://github.com/matheuslins\n\n\n",
"bugtrack_url": null,
"license": "Public Domain",
"summary": "Python functions for working with deeply nested documents (lists and dicts)",
"version": "0.2.25",
"project_urls": {
"Homepage": "https://git.unturf.com/python/nested-lookup"
},
"split_keywords": [
"nested",
"document",
"dictionary",
"dict",
"list",
"lookup",
"schema",
"json",
"xml",
"yaml"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fd427d6a06916aba63124eb30d2ff638cf76054f6aeea529d47f1859c3b5ccae",
"md5": "cc34addfe1997aa25fce42c89b3eb416",
"sha256": "6fa832748c90381f2291d850809e32492519ee5f253d6a5acbc29d937eca02e8"
},
"downloads": -1,
"filename": "nested-lookup-0.2.25.tar.gz",
"has_sig": false,
"md5_digest": "cc34addfe1997aa25fce42c89b3eb416",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14189,
"upload_time": "2022-07-06T18:55:03",
"upload_time_iso_8601": "2022-07-06T18:55:03.226503Z",
"url": "https://files.pythonhosted.org/packages/fd/42/7d6a06916aba63124eb30d2ff638cf76054f6aeea529d47f1859c3b5ccae/nested-lookup-0.2.25.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-07-06 18:55:03",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "nested-lookup"
}
JSON