{ "info": { "author": "mike.reider", "author_email": "mike.reider@gmail.com", "bugtrack_url": null, "classifiers": [], "description": "# Dictor - the dictionary doctor\n\n## An elegant dictionary and JSON handler\n\nVersion 0.1.9\n\nDictor is a Python 2 and 3 compatible JSON/Dictionary handler.\n\nDictor takes a dictionary or JSON data and returns value for a specific key.\n\nIf Dictor doesnt find a value for a key, or if JSON or Dictionary data is missing the key, the return value is either None or whatever fallback value you provide.\n\nDictor is polite with Exception errors commonly encountered when parsing large Dictionaries/JSONs.\n\nUsing Dictor eliminates the repeated use of try/except blocks in your code when dealing with lookups of large JSON structures, as well as providing flexibility for inserting fallback values on missing keys/values.\n\n## Why not use dict.get(\"value\") ?\n\nusing the built-in dict.get() does not parse the full body of a dict.\n\nThis method works if parsing a simple key=value structure, for example:\n\n data = {\"name\": \"Joe\"}\n\n >>> print(data.get(\"name\"))\n Joe\n >>> print(data.get(\"age\"))\n None\n >>> print(data.get(\"age\", \"this key doesnt exist\"))\n this key doesnt exist\n\nBut this wont work if the dict is a list,\n\n >>> data = [{\"name\": \"Joe\"}]\n >>> print(data.get(\"age\"))\n Traceback (most recent call last):\n File \"\", line 1, in \n AttributeError: 'list' object has no attribute 'get'\n\nor if the dict has a complex and nested structure, for example if I want to get Joe's age, I need to create a for-loop to parse the hierarchial levels of the dict structure until I reach the \"age\" key:\n\n data = {\n \"employees\": {\n \"Joe\": {\n \"age\": 20,\n \"id\": 123\n }\n }\n }\n\n >>> print(data.get(\"employees.Joe\"))\n None\n\nDictor greatly simplifies all this code by abstracting the logic.\n\n---\n\n## Installation\n\n pip install dictor\n\n## Usage\n\nsample.json\n\n```json\n{\n \"characters\": {\n \"Lonestar\": {\n \"id\": 55923,\n \"role\": \"renegade\",\n \"items\": [\"space winnebago\", \"leather jacket\"]\n },\n \"Barfolomew\": {\n \"id\": 55924,\n \"role\": \"mawg\",\n \"items\": [\"peanut butter jar\", \"waggy tail\"]\n },\n \"Dark Helmet\": {\n \"id\": 99999,\n \"role\": \"Good is dumb\",\n \"items\": [\"Shwartz\", \"helmet\"]\n },\n \"Skroob\": {\n \"id\": 12345,\n \"role\": \"Spaceballs CEO\",\n \"items\": [\"luggage\"]\n }\n }\n}\n```\n\nnow lets get info on all Characters\n\n```python\nfrom dictor import dictor\n\nwith open('sample.json') as data:\n data = json.load(data)\n\nprint(dictor(data, 'characters'))\n\n{u'Lonestar': {u'items': [u'space winnebago', u'leather jacket'], u'role': u'renegade', u'id': 55923}, u'Dark Helmet': {u'items': [u'Shwartz', u'helmet'], u'role': u'Good is dumb', u'id': 99999}, u'Barfolomew': {u'items': [u'peanut butter jar', u'waggy tail'], u'role': u'mawg', u'id': 55924}, u'Skroob': {u'items': [u'luggage'], u'role': u'Spaceballs CEO', u'id': 12345}}\n```\n\n---\n\nget details for Dark Helmet\n\n```python\nprint(dictor(data, 'characters.Dark Helmet.items'))\n\n>> [u'Shwartz', u'helmet']\n```\n\nyou can also pass a flag to ignore letter Upper/Lower casing,\n\n```python\nprint(dictor(data, 'characters.dark helmet.items', ignorecase=True))\n```\n\n---\n\nget only the 1st Item of a character\n\n```python\nprint(dictor(data, 'characters.Dark Helmet.items.0'))\n\n>> Shwartz\n```\n\n---\n\n## Fallback Value & Error Handling\n\nby default, dictor will return a None if a dictionary does not contain your search path,\n\n```python\nprint(dictor(data, 'characters.Princess Leia'))\n\n>> None\n```\n\nyou can provide a default fallback value either by passing\n`default=\"fallback value\"` or just placing a fallback string,\n\n```python\nprint(dictor(data, 'characters.Princess Leia', default='Not in Spaceballs'))\n\n>> Not in spaceballs\n```\n\nor just add a fallback string,\n\n```python\nprint(dictor(data, 'characters.Princess Leia', 'fallback to this'))\n\n>> fallback to this\n```\n\nif you want to error out on a None value, simply provide a CheckNone flag, a ValueError will be raised.\n\n```python\nprint(dictor(data, 'characters.Princess Leia', checknone=True))\n\nTraceback (most recent call last):\nFile \"test.py\", line 14, in \n print(dictor(data, 'characters.Princess Leia', checknone=True))\nFile \"/github.com/dictor/dictor/__init__.py\", line 77, in dictor\n raise ValueError('missing value for %s' % path)\nValueError: value not found for search path: \"characters.Princess Leia\"\n```\n\n---\n\n## Passing a variable into search path\n\nif you need to pass a variable into search path\n\n```python\nwho = \"Barfolomew\"\nprint(dictor(data, \"characters.{}.id\".format(who)))\n\n>> 55924\n```\n\nif using Python 3, you can also use F-strings\n\n```python\nwho = \"Barfolomew\"\nprint(dictor(data, f\"characters.{who}.id\"))\n```\n\n---\n\n## List of Dicts\n\nif the entire JSON structure is a list\n\n```json\n[\n {\n \"color\": \"red\",\n \"value\": \"#f00\"\n },\n {\n \"color\": \"green\",\n \"value\": \"#0f0\"\n },\n {\n \"color\": \"blue\",\n \"value\": \"#00f\"\n }\n]\n```\n\njust provide the list index into search path\n\n```python\nprint(dictor(data, '2.color'))\n\n>> blue\n```\n\n---\n\n## Nested List of lists\n\nto parse a complex nested list of lists and dicts, just provide the list index in the search path\n\n```json\n[\n {\n \"type\": \"json\",\n \"message\": [\n [\n {\n \"english\": \"apple\",\n \"spanish\": \"manzana\"\n },\n {\n \"english\": \"banana\",\n \"spanish\": \"platano\"\n }\n ],\n [\n {\n \"english\": \"cherry\",\n \"spanish\": \"cereza\"\n },\n {\n \"english\": \"durian\",\n \"spanish\": \"durian\",\n \"color\": [\"black\", \"brown\", \"orange\"]\n }\n ]\n ]\n }\n]\n```\n\ndictor will parse each lookup element hierarchicly, starting with top and will work down to the last element, reading in each dot-separated list index.\n\n```python\nprint(dictor(data, '0.message.1.1.color.2'))\n\n>> orange\n```\n\n---\n\n## Handling Key lookups with dots or other characters\n\nif you need to look up a key value that has a dot or some other character in the key name, for example\n\n```json\n{\n \"dirty.harry\": {\n \"year\": 1977,\n \"genre\": \"romance\"\n }\n}\n```\n\nsearching for dictor(data, 'dirty.harry') will return a None since Dictor sees the dot-separated entry as 2 separate keys.\n\nTo search for a key with a dot in the name, simply use a Path Separator flag, this allows you to control the separator of keys by using a custom character. (by default, pathsep is set to '.')\n\n```python\nprint(dictor(data, 'dirty.harry/genre', pathsep='/'))\n\n>> {'romance'}\n```\n\nyou can also use an escape character \"\\\\\" to escape a dot,\n\n```python\n\nprint(dictor(data, \"dirty\\.harry.genre\"))\n\n>>> {'romance'}\n```\n\n---\n\n## Searching specific keys\n\nDictor has the ability to search for specific keys and output a list of values. For example, to search for all values that match \"name\" key\n\n```python\ndata = {\n \"planets\": [\n {\n \"name\": \"Mars\",\n \"type\": \"rock\",\n \"attributes\": {\n \"name\": \"named after Roman god of war\",\n \"color\": \"red\",\n \"size\" : \"28,230 km\"\n }\n },\n {\n \"name\": \"Neptune\",\n \"type\": \"gas\",\n \"attributes\": {\n \"name\": \"named after Roman god of ocean\",\n \"color\": \"blue\",\n \"size\" : \"338,382 km\"\n }\n },\n ]\n}\n```\n\nsimply pass the `search=\"key_name\"` flag\n\n```python\nprint(dictor(data, 'planets', search='name'))\n>> ['Mars', 'Neptune']\n```\n\nIf search key is non existent, dictor will pass a None. In this case you can pass a default fallback value,\n\n```python\nprint(dictor(data, 'planets', search='fake_key', default='couldnt find value'))\n>> couldnt find value\n```\n\nif the entire dict structure is a list, ie:\n\n```json\n[\n {\n \"name\": \"spaceballs\",\n \"genre\": \"romance\"\n },\n {\n \"name\": \"gone with the wind\",\n \"genre\": \"chick flick\"\n },\n {\n \"name\": \"titanic\",\n \"genre\": \"comedy\"\n }\n]\n```\n\nyou can search for all keys directly, ie\n\n print(dictor(data, search='genre'))\n\n >> ['romance', 'chick flick', 'comedy']\n\n---\n\n## Pretty Print\n\nyou can pretty print (human readable JSON output) your result,\n\n```python\nprint(dictor(data, pretty=True))\n```\n\n```json\n[\n {\n \"genre\": \"comedy\",\n \"name\": \"spaceballs\"\n },\n {\n \"genre\": \"tragedy\",\n \"name\": \"gone with the wind\"\n },\n {\n \"genre\": \"comedy\",\n \"name\": \"titanic\"\n }\n]\n```\n\n---\n\n## Return specific type\n\nif you want to return lookup value in a specific character type (int or str), use the return type (rtype) flag\n\nConvert an integer return value into a string\n\n```\ndata = { \"age\": 25 }\n\nprint(dictor(data, \"age\", rtype=\"str\"))\n>>> \"25\"\n\n```\n\nConvert a string return value into an integer\n\n```\ndata = { \"some string value\": \"1234\" }\n\nprint(dictor(data, \"some string value\", rtype=\"int\"))\n>>> 1234\n\n```\n\nThis will only return the desired output type if return value is string or int. If the return value is a dictionary, list or tuple, the original return value will be returned.\n\n---\n\n## Testing\n\ntesting is done using Python Nose. Tests are located in 'tests' directory.\n\n pip install nose\n\n shell> nosetests test.py -v\n\n---\n\n## Release Notes\n\n### 0.1.9\n\n- added escape option for pathsep (can either use pathsep flag or use \"\\\" escape in path)\n\n### 0.1.8\n\n- broke down main dictor function into several sub-functions\n- added 'rtype' flag to return type-specific output (int or str)\n\n### 0.1.7\n\n- README win10 compatibility fix\n- docstring fixes\n\n### 0.1.6\n\n- added ability to search keys, will return a list of key names via Search flag\n- added Pretty flag to pretty print JSON output\n\n### 0.1.5\n\n- checknone updated to only error out on None values, 0 values are accepted\n\n### 0.1.4\n\n- lookup engine update\n- ability to provide new type of path separator\n\n### 0.1.3\n\n- bugfix\n\n### 0.1.2\n\n- fixed lookup bug\n\n### 0.1.1\n\n- removed `eval()` function for added security\n- entire lookup engine was rewritten for increased speed and simplicy\n- added `ignorecase` parameter\n- added ability to escape dot character for keys with dots in them\n- looking up lists indexes was modified,\n\n in previous version, looking up an element looked like this,\n\n ```python\n dictor(data, 'characters.Dark Helmet.items[0]')\n ```\n\n new syntax is to place everything as a dot-separated path, this creates a single lookup standard, ie,\n\n ```python\n dictor(data, 'characters.Dark Helmet.items.0')\n ```\n\n### 0.0.1\n\n- initial project released\n\n---\n\n## packaging\n\n python setup.py sdist\n sudo pip install twine\n sudo twine upload dist/*", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/perfecto25/dictor", "keywords": "", "license": "MIT", "maintainer": "", "maintainer_email": "", "name": "dictor", "package_url": "https://pypi.org/project/dictor/", "platform": "", "project_url": "https://pypi.org/project/dictor/", "project_urls": { "Homepage": "https://github.com/perfecto25/dictor" }, "release_url": "https://pypi.org/project/dictor/0.1.9/", "requires_dist": null, "requires_python": "", "summary": "an elegant dictionary and JSON handler", "version": "0.1.9", "yanked": false, "yanked_reason": null }, "last_serial": 12684471, "releases": { "0.0.1": [ { "comment_text": "", "digests": { "md5": "3a337b58930ca7e4a4f6fd472f33d184", "sha256": "c5a2b2821b3973845567be2c78f95e52ba22d7ea552490451e2ba9a9233ebf8d" }, "downloads": -1, "filename": "dictor-0.0.1.tar.gz", "has_sig": false, "md5_digest": "3a337b58930ca7e4a4f6fd472f33d184", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 3217, "upload_time": "2018-11-30T23:33:40", "upload_time_iso_8601": "2018-11-30T23:33:40.522956Z", "url": "https://files.pythonhosted.org/packages/06/ad/bf388cee2ddce24ad83452c6d9d87e87df5404ceab8417c130c0773454d1/dictor-0.0.1.tar.gz", "yanked": false, "yanked_reason": null } ], "0.1.1": [ { "comment_text": "", "digests": { "md5": "23c8cc624d93a41fdbc966327a36211c", "sha256": "42d75aedc4c622a644dcb6c454ab14fba2ec8660e6a19abbd3d9b70258cb9ccb" }, "downloads": -1, "filename": "dictor-0.1.1-py3-none-any.whl", "has_sig": false, "md5_digest": "23c8cc624d93a41fdbc966327a36211c", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": null, "size": 5158, "upload_time": "2019-07-14T02:22:47", "upload_time_iso_8601": "2019-07-14T02:22:47.736708Z", "url": "https://files.pythonhosted.org/packages/c1/d9/540d8e5cff415c0cdbd1135de1ba7e1eac2e1582a573e5f47522f60729b1/dictor-0.1.1-py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "digests": { "md5": "c51823916d229d0f49b4e794c949e146", "sha256": "85e4aa2b7d14b46644bd48129eb0330bce593282414417b4c7023b1447358540" }, "downloads": -1, "filename": "dictor-0.1.1.tar.gz", "has_sig": false, "md5_digest": "c51823916d229d0f49b4e794c949e146", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 4712, "upload_time": "2019-07-14T02:22:49", "upload_time_iso_8601": "2019-07-14T02:22:49.115795Z", "url": "https://files.pythonhosted.org/packages/12/d4/e0ac58e8a29c98178d14ed0cb16a2c992fb3dfa96e62bb3881df91586491/dictor-0.1.1.tar.gz", "yanked": false, "yanked_reason": null } ], "0.1.2": [ { "comment_text": "", "digests": { "md5": "ae3fd344b3ec91b91cac0771db5a1710", "sha256": "16a019817108675dc176b201c35b045478456244078b29949d57636792f864ca" }, "downloads": -1, "filename": "dictor-0.1.2-py3-none-any.whl", "has_sig": false, "md5_digest": "ae3fd344b3ec91b91cac0771db5a1710", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": null, "size": 5401, "upload_time": "2019-08-21T12:06:25", "upload_time_iso_8601": "2019-08-21T12:06:25.815915Z", "url": "https://files.pythonhosted.org/packages/ab/2b/a88d7ea83d89fca79c4d307c5fb9a1bdd5e2459b0cf2d5601ef499edaa69/dictor-0.1.2-py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "digests": { "md5": "ed64d52414174df6a5e7a5d97c72acc2", "sha256": "ef379466c4dadd47350bed4affeb84344c935768c22237fa1b9714f8747fcbf4" }, "downloads": -1, "filename": "dictor-0.1.2.tar.gz", "has_sig": false, "md5_digest": "ed64d52414174df6a5e7a5d97c72acc2", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 4770, "upload_time": "2019-08-21T12:06:28", "upload_time_iso_8601": "2019-08-21T12:06:28.174778Z", "url": "https://files.pythonhosted.org/packages/94/0b/19e50f8808c443c3c6737f5a562d48b300a6778d3a3cc83272ea835dacc8/dictor-0.1.2.tar.gz", "yanked": false, "yanked_reason": null } ], "0.1.3": [ { "comment_text": "", "digests": { "md5": "9f4010c194de7011de8a805ac5de9a41", "sha256": "d1bd584697db89f32370d13bdcc3ae235d190e11f0175196b4237a980e4ad278" }, "downloads": -1, "filename": "dictor-0.1.3.tar.gz", "has_sig": false, "md5_digest": "9f4010c194de7011de8a805ac5de9a41", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 4813, "upload_time": "2019-10-21T19:05:42", "upload_time_iso_8601": "2019-10-21T19:05:42.529027Z", "url": "https://files.pythonhosted.org/packages/7e/e1/03c4d8fc666f133e3187f60829a065f60e8b37e4aa65d397470c95f8e04d/dictor-0.1.3.tar.gz", "yanked": false, "yanked_reason": null } ], "0.1.4": [ { "comment_text": "", "digests": { "md5": "11538c82c834f06c43f47f9f76dc7812", "sha256": "6737c08463364c48c3ebcf2f5bcc14498b4c895e1c78154d62cfd24ca1fe3159" }, "downloads": -1, "filename": "dictor-0.1.4.tar.gz", "has_sig": false, "md5_digest": "11538c82c834f06c43f47f9f76dc7812", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 4755, "upload_time": "2019-12-02T04:41:52", "upload_time_iso_8601": "2019-12-02T04:41:52.429788Z", "url": "https://files.pythonhosted.org/packages/63/f7/1d97dd52626613c87a1e4bfea5af450485e730817bfb013e8f7dad9d6d9e/dictor-0.1.4.tar.gz", "yanked": false, "yanked_reason": null } ], "0.1.5": [ { "comment_text": "", "digests": { "md5": "e0fd7537254cc48689e4af968bcd89b7", "sha256": "149d073ef174e19e6713e505ff9fcb90177b264f621810550e34c74a1bc1179f" }, "downloads": -1, "filename": "dictor-0.1.5.tar.gz", "has_sig": false, "md5_digest": "e0fd7537254cc48689e4af968bcd89b7", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 4808, "upload_time": "2020-02-05T04:28:15", "upload_time_iso_8601": "2020-02-05T04:28:15.683504Z", "url": "https://files.pythonhosted.org/packages/d4/3a/dc2273856497b3fcfc23365532dad417049002d804ec46fe10f305e0fe21/dictor-0.1.5.tar.gz", "yanked": false, "yanked_reason": null } ], "0.1.6": [ { "comment_text": "", "digests": { "md5": "14df7e8cd6488ae9dd889b5552898d02", "sha256": "69c6277020ad207f2eb686902e4967c243b0419bd742374c0f1aa4ce64cc81b5" }, "downloads": -1, "filename": "dictor-0.1.6.tar.gz", "has_sig": false, "md5_digest": "14df7e8cd6488ae9dd889b5552898d02", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 5887, "upload_time": "2020-05-20T04:49:40", "upload_time_iso_8601": "2020-05-20T04:49:40.660922Z", "url": "https://files.pythonhosted.org/packages/cf/b0/4ce44ff9c6b70fbbff136a6e013178dc5442f5179d3b9b92440fc8f176d3/dictor-0.1.6.tar.gz", "yanked": false, "yanked_reason": null } ], "0.1.7": [ { "comment_text": "", "digests": { "md5": "de7c68f784400df3426c737c85bb1efe", "sha256": "3b1a99e999781c801d91d8463bea03dbbfcf9bc714ac84a3a32b859dd7df6e7d" }, "downloads": -1, "filename": "dictor-0.1.7.tar.gz", "has_sig": false, "md5_digest": "de7c68f784400df3426c737c85bb1efe", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 6239, "upload_time": "2020-06-09T15:56:55", "upload_time_iso_8601": "2020-06-09T15:56:55.368811Z", "url": "https://files.pythonhosted.org/packages/e1/2c/d89ed9ba974919ae12a64d0bf15fbbb004ce15e4d103dcbf4e1e9ec4503a/dictor-0.1.7.tar.gz", "yanked": false, "yanked_reason": null } ], "0.1.8": [ { "comment_text": "", "digests": { "md5": "a26590d83a64aaaa8ab67545f6801fdb", "sha256": "513fafccbebc440de3065bcea46d7356caa09858854bd7f8aea3326c0a0dee4c" }, "downloads": -1, "filename": "dictor-0.1.8.tar.gz", "has_sig": false, "md5_digest": "a26590d83a64aaaa8ab67545f6801fdb", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 8495, "upload_time": "2022-01-21T14:36:40", "upload_time_iso_8601": "2022-01-21T14:36:40.263987Z", "url": "https://files.pythonhosted.org/packages/f4/c2/f9b22dbb6e4a14c6e065180afbb40a8b249e0af4ea029805c27a3b6d5199/dictor-0.1.8.tar.gz", "yanked": false, "yanked_reason": null } ], "0.1.9": [ { "comment_text": "", "digests": { "md5": "86bbd78d8bbd8b9c93eba176c0120b3a", "sha256": "84f6e0edce6a80a2178f97754af4c62a11ca48d12e7cc33eee8f309305605213" }, "downloads": -1, "filename": "dictor-0.1.9.tar.gz", "has_sig": false, "md5_digest": "86bbd78d8bbd8b9c93eba176c0120b3a", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 8707, "upload_time": "2022-01-25T06:58:10", "upload_time_iso_8601": "2022-01-25T06:58:10.561855Z", "url": "https://files.pythonhosted.org/packages/2d/45/7b4dbebbcca64ece8da17c094a3b147a6e8c49d3557eec5aee70c077f3ee/dictor-0.1.9.tar.gz", "yanked": false, "yanked_reason": null } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "86bbd78d8bbd8b9c93eba176c0120b3a", "sha256": "84f6e0edce6a80a2178f97754af4c62a11ca48d12e7cc33eee8f309305605213" }, "downloads": -1, "filename": "dictor-0.1.9.tar.gz", "has_sig": false, "md5_digest": "86bbd78d8bbd8b9c93eba176c0120b3a", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 8707, "upload_time": "2022-01-25T06:58:10", "upload_time_iso_8601": "2022-01-25T06:58:10.561855Z", "url": "https://files.pythonhosted.org/packages/2d/45/7b4dbebbcca64ece8da17c094a3b147a6e8c49d3557eec5aee70c077f3ee/dictor-0.1.9.tar.gz", "yanked": false, "yanked_reason": null } ], "vulnerabilities": [] }