{
    "info": {
        "author": "Luca Buccioni",
        "author_email": "kerkops7@gmail.com",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "# ker_dict_tools\n\nSmart tools to operate on Python's dicts.\n\n  - **_dict_diff()_**: Function to compare two dicts reporting their differences.\n  - **_get_value_by_path()_**: Get single or multiple values from a dict passing the path leading to them.\n  - **_set_value_by_path()_**: Set a value in a nested dict passing the path leading to it.\n  \n### The 'path' concept:\nI needed a smart way to access dict whose structure could change unpredictably (for example nested list of dicts) putting them in relationship with other objects.\nSo i developed the functions 'get_value_by_path()' and 'set_value_by_path()' that allows me to access to those values in a safe and rapid way.\nThe _path_ is a list of values, each one pointing to a subsequential sub-level of the dict.\nFor example, given the dict:\n```\ndct = {\n    \"foo\": [\n        {\"bar\":1},\n        {\"baz\":2}\n    ]\n}\n```\nthe path to access to the value _2_ is:\n```\n[\n    \"foo\",      # Key for outer level of the dict\n    1,          # Index for list contained in the \"foo\" value\n    \"baz\"       # Key for dict at index 1 of the list\n]\n```\nSince is designed to be used in a context where the actual dict could be partially unknown, the entry point to define a path to be used is the **_get_value_by_path()_** function, wich accepts a much more \"elastic\" list (allowing simple queries on the dict).\n## get_value_by_path(_dct_, _path_, _fail=False_, _debug=False_)\nAllows to retrieve the value (or values) stored somewhere in the _dct_ dict if the given _path_ is correct (corresponds to the structure of the dict).\nThe _dct_ argument can be either a _dict_ or a _list of dicts_.\nIf the _fail_ argument is passed (_True_), when an element in the _path_ doesn't correspond to the the layer of the _dct_ dict where is applied, a _TypeError_ exception will be raised. Otherwise the function will return an empty namedtuple with _0_ as value for _.found_ attribute.\nIf the _debug_ argument is passed (_True_), the function will log (using the _logging_ module) every operation with a _debug_ level.\n\n#### Accepted values in the _path_ list when passed to _get_values_by_path()_\n\n| Dict layer type | Accepted Values |\n|-----------------|-----------------|\n| List of dicts | **int** (Index of list) |\n| | **dict** (_key:value_ pair to be matched in one or more dicts inside the list) |\n| | **list (of dicts)** (list of dicts containing a single _key:value_pair, all to be matched in one or more dict inside the list)|\n| | **str** (key to be found among keys of dicts contained in the list)|\n| | **string \"\\*\"** (wildcard to return all the elements in the list)|\n| Dict | **str** (key for the dict) |\n| | **string \"\\*\"** (wildcard to return all items in the dict) |\n\nFor example:\n```\ndct = [\n{ \"foo\": [{\"bar\":1, \"baz\":2},{\"bar\":3, \"baz\":4}] },\n{ \"foo\": [{\"bar\":5, \"baz\":6},{\"bar\":7, \"baz\":8}] },\n]\npath1 = [0, \"foo\", {\"bar\":1}, \"baz\"] \npath2 = [0, \"foo\", 0, \"baz\"]\n```\n_path1_ and _path2_ will lead to the value 2.\nWith:\n```\npath3 = [0, \"foo\", \"*\", \"baz\"]\n```\n_path3_ will lead to the values _2_ and _4_\n\n#### Object returned by _get_value_by_path()_\nThe function will return a _dict_search_ object.\n```\nres = get_value_by_path(myDict, myPath)\n\nres => 'dict_search'(\n    found=n, # -> number of matches\n    results=[\n        dict_branch(\n            path={list1} # Path leading to the value #1\n            value={value1} # Value #1\n            ),\n        dict_branch(\n            path={list2} # Path leading to the value #2\n            value={any} # Value #2\n            ),\n        ...\n            \n    ]\n    )\n```\nThe function will return a '_dict_search_' namedtuple, containing two attributes:\n - **.found** {int}: Number of elements in the dict matching the given _path_\n - **.results** {list}: List of _dict_branch_ namedtuples, each one specifing the _path_ and _value_ of for the elements matching the given path.\n##### _dict_branch_ namedtuple structure:\n- **.path** {list}: \"normalized\" path leading to the value (contains only dict keys or list indexes)\n- **.value** {any}: value found at specified _path_\n### Using _get_value_by_path()_ to query the dict\nIs also possible to verify if a given value is present at a certain layer of the dict passing as path the path leading to it and specifing the value to find as last item in the path's list.\nThe function returns a namedtuple that specifies at index 0 (_.found_) the number of matches for the given path.\n\n## set_value_by_path(_dct_, _path_, _value_, _debug=False_)\nAllows to set a given _value_ at a certain position of the _dct_ dict specified with the given _path_.\nThe _path_ argument must be a list of _ints_ or _strings_ according to the structure of the dict (such those returned in the _dict_search_ object from _get_value_by_path()_).\n\n## diff_dict(_dct1_, _dct2_, _fail=False_, _startPath=None_)\nPerforms a comparison from _dct1_ and _dct2_ dicts. \nThose two arguments must be of the same type (bot lists of dicts or simple dicts).\nReturns a '_diff_results_' object, containing four attributes:\n- **.compared** {bool}: True if the comparison has been performed without problems.\n- **.updated** {list}: List of '_updated_item_' namedtuple (see below) containing info about elements present in both dicts but with different values.\n- **.added** {list}: List of paths pointing elements found in the _dct2_ but not in the _dct1_.\n- **.removed** {list}: List of paths pointing elements found in the _dct1_ but not in the _dct2_.\n\nThe _updated_item_ namedtuple, that populates the _.updated_ list, has the follwing structure:\n- **.path** {list}: Path leading to updated element.\n- **.old_value** {any}: Old value for the element.\n- **.old_type** {type}: Old type for element's value.\n- **.new_value** {any}: New value for the element.\n- **.new_type** {type}: New type for element's value.",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://bitbucket.org/kerkops/dict_tools",
        "keywords": "dicts,dict,path,paths,paths for dicts,dict diff,dict differences,diff,operations on dictionaries,dict values by path,dict queries,dict query,differences between nested dicts,Intended Audience :: Developers,Topic :: Software Development :: Build Tools,License :: OSI Approved :: MIT License,Programming Language :: Python :: 3,Programming Language :: Python :: 3.6,Programming Language :: Python :: 2,Programming Language :: Python :: 2.7",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "ker-dict-tools",
        "package_url": "https://pypi.org/project/ker-dict-tools/",
        "platform": "",
        "project_url": "https://pypi.org/project/ker-dict-tools/",
        "project_urls": {
            "Homepage": "https://bitbucket.org/kerkops/dict_tools"
        },
        "release_url": "https://pypi.org/project/ker-dict-tools/0.1.1/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Tools for smart operations with python dicts",
        "version": "0.1.1"
    },
    "last_serial": 4387533,
    "releases": {
        "0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "ce185295a7a9a56907b596ab91c99b45",
                    "sha256": "79510df50766663f7039ee85ebff6f114c1987764939f47f5b041cd21e1ec195"
                },
                "downloads": -1,
                "filename": "ker_dict_tools-0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "ce185295a7a9a56907b596ab91c99b45",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 8418,
                "upload_time": "2018-10-17T16:55:13",
                "url": "https://files.pythonhosted.org/packages/69/ab/2a8ec4068083ed8aca02174d5fb736c2ebd9a62f7bb82041cdaf23b86066/ker_dict_tools-0.1.tar.gz"
            }
        ],
        "0.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "2087b0e173075608c3ded283681592b1",
                    "sha256": "651288c025f667026b31d31b9139af7fec69556fa41d90955bbc70e8e82d109e"
                },
                "downloads": -1,
                "filename": "ker_dict_tools-0.1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "2087b0e173075608c3ded283681592b1",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 13036,
                "upload_time": "2018-10-17T20:01:11",
                "url": "https://files.pythonhosted.org/packages/13/1a/d2fd5f7de4b28e6e962d490c1bb21679086510e780c65dba535d173de197/ker_dict_tools-0.1.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "2087b0e173075608c3ded283681592b1",
                "sha256": "651288c025f667026b31d31b9139af7fec69556fa41d90955bbc70e8e82d109e"
            },
            "downloads": -1,
            "filename": "ker_dict_tools-0.1.1.tar.gz",
            "has_sig": false,
            "md5_digest": "2087b0e173075608c3ded283681592b1",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 13036,
            "upload_time": "2018-10-17T20:01:11",
            "url": "https://files.pythonhosted.org/packages/13/1a/d2fd5f7de4b28e6e962d490c1bb21679086510e780c65dba535d173de197/ker_dict_tools-0.1.1.tar.gz"
        }
    ]
}