{ "info": { "author": "Marcelo Silva", "author_email": "msilva@arkhotech.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 2 - Pre-Alpha", "Intended Audience :: Developers", "License :: OSI Approved :: GNU General Public License (GPL)", "Natural Language :: Spanish", "Operating System :: OS Independent", "Programming Language :: Python :: 3.7", "Topic :: Software Development :: Libraries :: Python Modules" ], "description": "\n\n# JSON Query\n\n## State: PROTOTYPE\n#### AUTHOR: Marcelo Silva\n#### Language: Python\n\n\n### Setup\n\nInstall application from GitHub using git client:\n\n```bash\ngit clone https://gitlab.com/arkhotech/json_query.git\n```\n\nInstall aplication from Pypi.org:\n\n```bash\npip install arkho-jsonquery\n```\n\n\nOnce the repository is cloned we can use the library adding the following import:\n\n```python\nfrom jsonquery import JsonQuery\n```\nThe library have two ways to use it, one way is usgin the class **JsonQuery**. This class takes 1 parameters: file path that contains the json \ndata.\n\n```python\nquery = JsonQuery(filepath)\n```\n\nOnce you has initialized the object, you can make the query over the JSON data loaded from the file (that is made when you init the object) using the **execute** method:\n\nExample:\n\n```python\n\nquery = JsonQuery('path/to/file.json')\n\nquery.execute('/')\n\n#the result it's an dict or list with the result\n\n```\n\n* **query**: Query applied over the data (see syntax).\n\nYou can use a dict objet to if you don't want to use a file.\n\nExample:\n\n```python\nfrom json_query import JsonQuery\n\nimport json\ndata = None\nwith open('test.json','r') as input:\n data = json.load(input)\n\njsonquery = JsonQuery(dataset=data)\nretval = jsonquery.execute('/items')\n\nprint(retval)\n```\n\nThe second way to use it is like a function. The module have got a function called jsonquery and you must declare the correct import. Ex.\n\n```python\n\nfrom jsonquery import jsonquery\n\njsonquery('archivo.json','/item[0]/items[@id=='1001']\n```\n\n\n## Syntax\n\nThe sytanx used for the query have got 3 parts:\n\n* path\n* select\n* query\n\n### PATH\n\nThe path represents every level in the Json on a single line, separated trough the slash ('/') symbol. Ex:\n\n```json\n{\n\t\"nivel1\": {\n\t\t\"nivel2\": {\n\t\t\t\"nivel3\": \"hola\"\n\t\t}\n\t}\n}\n```\n\nOne query like this over the json example above: **/nivel1/nivel2/nivel3**, must return the following **\"hola\"**.\n\n## Arrays\n\nIf the json contains some array dadta inside, you can specify the index of the item that you want, using a index number between bracket ( **[ ]** ).\n\n> **NOTA:** The array have got 0 base index.\n> \n> **NOTA2:** The query execution returns a list with result if the query return mora that one item or if the result is a json array otherwise return a json value.\n\nUsing the following JSON:\n\n```json\n{\n \"lista\":\n { \"items\": [\n \t{ \"item\": 1},\n \t{ \"item\": 3},\n \t{ \"item\": 4},\n \t.....\n \t{ \"item\": N},\n ]\n}\n```\n\n| query | descrici\u00f3n | resultado |\n|-------|------------|-----------|\n| /items/items[15] | Recover the item on 16th position | **[{ \"item\": 16}]** |\n| /items/items[0]/item | Return the item value: 1 | **1** |\n| /items/items[n+1] | throws a error index out of range |**Error**|\n\n### Root Node\n\nOn a query, the root node is representated with the slash symbol on the begining. If you don't especified the slash on the begin of the path query, the seek could select any node on the three wich match with the node name specified in the path query. \n\nUsing the json above if we execute just the following query: \n\n'item'\n\nWe will get the following result:\n\n```json\n[\n\t{ \"item\": 1},\n\t{ \"item\": 3},\n\t....\n\t{ \"item\": N}\n]\n```\n\n## select\n\nYou can use field selector if you don't want only especific fields from the requested json file. By use selector you must add a list of fields between curly bracket ( **{ }** ) separated with comes: \n\n```\n { 'FIELD-1', 'FIELD-2', ... 'FIELD-N' }\n```\n\nThe field names must be inside \"\" or ''.\n\nExample, if we execte the following query: Si ejecutamos: **/items[0]{ 'id','name'}**\n\nOver the following json:\n\n```json\n{ \n\"items\":{\n\t[ \n\t\t{\n\t\t\t\"id\": \"7002\",\n\t\t\t\"name\": \"Custard\",\n\t\t\t\"addcost\": 0\n\t\t},\n\t\t{\n\t\t\t\"id\": \"7003\",\n\t\t\t\"name\": \"Whipped Cream\",\n\t\t\t\"addcost\": 0\n\t\t},\n\t\t{\n\t\t\t\"id\": \"7004\",\n\t\t\t\"name\": \"Strawberry Jelly\",\n\t\t\t\"addcost\": 0\n\t\t},\n\t\t{\n\t\t\t\"id\": \"7005\",\n\t\t\t\"name\": \"Rasberry Jelly\",\n\t\t\t\"addcost\": 0\n\t\t}\n\t]}\n}\n```\n\nThe returned of the query will be:\n\n```python\n>>> from jsonquery import *\n>>> jsonquery('archivo.json','items[0]{ 'id','name'}')\n\n{\n\t\"id\": \"7003\",\n\t\"name\": \"Whipped Cream\"\n}\n```\n\n### Query Filter\n\nThe must important part of the jsonquery sentence is the selector or filters. We can filter what items will be selected according the criteria applied over the node. \nThe selector are between square bracket ( **[ ]** ) and it must put over the end of the node name. Ex:\n\n```\n/nodename[ query ]\n``` \n\nthe query filter must be applied over the node child. You can mix the query filter with item index if the child of the current node where the query will be applied. Ex:\n\n```\n/nodename[15][ query ]\n```\n\nOn the example above the query fileter must be applied over the item number 16 (remember that the first item index is 0). \n\nYou could apply new query path over the result in the same query path. Ex.\n\n```\n/nodename[15][ query]/another-item\n```\nOn the example above the query will be applied over the item 16 of the nodename and over the result, will be requested the node \"another-item\" and so on.\n\n> **NOTE**: You must consider if the requested json node is an array or not for make a path quert over the result. You cannot get an unique particular node name over an array. The array return a list.\n\n\n### Query filter Syntax\n\n\n**[** *OPERATION* *[LOGIC_OPERATOR OPERATION]*+ **]**\n\nWhere:\n\n* ***OPERATION***: 2 operands plus a mathematical comparator.\n* ***LOGIC_OPERADOR***: Logic operation. You could use: **and, or**\n\n\nExample:\n\n```python\n>>> from jsonquery import *\n>>> path = '/item/items[@valor >= 1000 and @valor <= 10000]'\n>>> \n>>> jsonquery('archivo.json',path)\n\n```\n\n#### Operands\n\nThe operands are values that you can use for filter values that accomplish with the condition. The operands must be a *field* and some value for perform the comparation. An field represents some name inside of the json file and you can map with a '**@**' before the name.\n\nAn operation must take an field, an comparator and a value. The value must be a string, integer, float or boolean. Ex:\n\n```\n@id == 1000\n```\n\nThe field must be in the first place or to the left of the operation.\n\n#### Field\n\nrepresenta el nombre de un campo dentro de un Json. El nombre debe comenzar con un simbolo '@'. Por ejemplo: \n\n```\n# @id\n# Este valor hace referencia al campo id del siguiente JSON:\n\n{\n\t\"id\": 1000,\n\t\"comantario\": \"Test\"\n}\n\n```\n\n#### Comparators\n\nThe permited comparators over an operation are:\n\n\n| Comparator| Description|\n|-----------|------------|\n| == | Equals to. If you comparate agains an array value, equlas act as a 'IN' operation.|\n| != | Not equal. Over an array acts as a 'NOT IN'|\n| > , <, <= , >= | \ninequality . Only applied over integer and float values.|\n\n#### Compare against array\n\nWhen the value it's comparated against and array the simbols '==' and '!=' acts a IN and NOT IN operation respectively. Ex:\n\nBy the following JSON:\n\n```json\n{\n\t\"valor\" : [2,3,4,5,6],\n\t\"valor\" : [5,6,7]\n}\n```\n\nAnd the following operation:\n\n```python\n>>> from jsonquery import *\n>>> \n>>> jsonquery('archivo.json','/[@valor==5]')\n>>> \n{ \"valor\": [2,3,4,5,6] }\n\n```\n\nOn the example above it has slected the first array because it array comtains the number five. \nThe opossite case, we can change the equal for not equal:\n\n```python \n>>> from jsonquery import *\n>>> \n>>> jsonquery('archivo.json','/[@valor!=5]')\n>>> \n{ }\n\n```\n\nOn the example above the returned value is a empty json because on both cases exists the number five in the array's\n\n### Operations AND & OR\n\nThe operations **AND** performs a union of dataset with that accomplish with the conditions.\n\nThe **OR** logic conditions, performs a union of datasets that accomplish with our respective conditions. Both resulting dataset will be merged.\n\n###\u00a0Excution order\n\nAll of the operations are executed from left to rigth. Consider the following example:\n\n```\n[ @id=='1001' and @type=='t\u00e9' or @type=='cafe']\n```\n\n* First will be executed the operation: ***(@id=='1001' and @type=='t\u00e9' )*** \n* The previus result will be all values that have id equals to '1001' and type equals to 'te. The operation will be a intersection of both results.\n* Then, will be executed the operation: **@type=='cafe'**\n* The result of the previus operation will be merged with the first operation\n\n## Syntax\n\n\n\n\n---\n\n|expresion| |\n|---------|----|\n| ***QUERY_PATH*** | **[/*NODE_NAME*]+** |\n| **NODE_NAME** | *NAME* **[** *INDEX* **]**\\* **[** *QUERY* **]**\\* |\n| **NAME** | Sequence \"a-z A-Z_0-9\" |\n| **INDEX** | *DIGIT*+:*DIGIT*\\* |\n| **DIGIT** | [0-9]+ |\n| **QUERY** | *OPERATION* [*LOGIC_OPERATOR* *OPERATION*]\\* ( **the spaces are required ** ) |\n| **OPERATION** | *OPERAND* *COMPARATOR* *OPERAND* |\n| **OPERANDO** | *FIELD* | *VALUE* |\n| **FIELD** | @*NAME* (**el @ es literal**) |\n| **VALUE** | 'STRING' | INTEGER |\n| **COMPARADOR** | ==, !=, >, <, <=, >= |\n| **OPERACION** | and \\| or |\n\n----\n\n## Examples:\n\nWith the following Json\n\n```json\n{\n \"a\" : {\n \"b\" : {\n\t\"valor\" : 1000\t\n }\t\t\n\n }\n\n}\n\n```\nYou can execute the following querys:\n\n\n```\nQuery: /a/b\n\nReturn: [{ \"valor\": 1000 }]\n\nQuery: /a \n\nReturn: [{ \"b\": { \"valor\": 1000 }}]\n\nQuery: /a/b/valor\n\nReturn: 1000\n\n```\n\nSelect directly an item inside an array:\n\n```json\n\n{ \"a\" : \n { \"b\" : [ \n { \"name\" : \"a\", \"valor\" : 1000 },\n {\"name\" : \"b\",\"valor\" :2000},\n {\"name\" : \"c\",\"valor\": 3000}\n ]\n }\n}\n```\n\nQuerys over json:\n\n```\nQuery: /a/b[0]\n\nReturn: [{ \"name\" : \"a\", \"valor\" : 1000 }]\n\nQuery: /a/b[2]\n\nReturn: [{\"name\" : \"c\",\"valor\": 3000}]\n\n```\n\n\n", "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/arkhotech/json_query.git", "keywords": "", "license": "", "maintainer": "", "maintainer_email": "", "name": "arkho-jsonquery", "package_url": "https://pypi.org/project/arkho-jsonquery/", "platform": "", "project_url": "https://pypi.org/project/arkho-jsonquery/", "project_urls": { "Homepage": "https://github.com/arkhotech/json_query.git" }, "release_url": "https://pypi.org/project/arkho-jsonquery/0.0.5/", "requires_dist": null, "requires_python": ">=3.6", "summary": "Prototype of query path over JSON files", "version": "0.0.5" }, "last_serial": 5874203, "releases": { "0.0.4": [ { "comment_text": "", "digests": { "md5": "f9036d1ece02311ce0c52e26ebd364b7", "sha256": "5ffb26ab9459906a9296a8c17157db2edf050b0bc2c0eecfdb06dbdb50f7aafd" }, "downloads": -1, "filename": "arkho_jsonquery-0.0.4-py3-none-any.whl", "has_sig": false, "md5_digest": "f9036d1ece02311ce0c52e26ebd364b7", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.6", "size": 21841, "upload_time": "2019-09-23T15:01:42", "url": "https://files.pythonhosted.org/packages/48/8a/f5c94483660848dedf51d2ac190bc41646f35212b10bd7c5b0102b43dfe0/arkho_jsonquery-0.0.4-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "9e70507f46aa0babb8298cfc86fa7a14", "sha256": "4ec5034a7d51332a57671c8545b142c0a4bec65de004259e457c31c1ec27e509" }, "downloads": -1, "filename": "arkho-jsonquery-0.0.4.tar.gz", "has_sig": false, "md5_digest": "9e70507f46aa0babb8298cfc86fa7a14", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.6", "size": 9914, "upload_time": "2019-09-20T16:53:54", "url": "https://files.pythonhosted.org/packages/e4/b3/e7a4d2e33192b60ea5dcd2f754413df736a60c3e6c1e1c8cac1cbb293e9c/arkho-jsonquery-0.0.4.tar.gz" } ], "0.0.5": [ { "comment_text": "", "digests": { "md5": "61b99204631e2435c086947c1a3b0bf1", "sha256": "abfb86ee1a344926e4659734a23633836b2f71b8cab03f1de0641884015032de" }, "downloads": -1, "filename": "arkho_jsonquery-0.0.5-py3-none-any.whl", "has_sig": false, "md5_digest": "61b99204631e2435c086947c1a3b0bf1", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.6", "size": 21829, "upload_time": "2019-09-23T15:06:33", "url": "https://files.pythonhosted.org/packages/cb/a0/c298a6fcc087dac7bd9cb87eb57b2b2b42c8286f1ffb31f843627a97b065/arkho_jsonquery-0.0.5-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "c6d44eecb53096219f45d059a4789ef8", "sha256": "80f5985c60388165a9ab643a8cbe3398d8a3721c5a9f05a0686d70b395eddf7b" }, "downloads": -1, "filename": "arkho-jsonquery-0.0.5.tar.gz", "has_sig": false, "md5_digest": "c6d44eecb53096219f45d059a4789ef8", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.6", "size": 10115, "upload_time": "2019-09-23T15:06:35", "url": "https://files.pythonhosted.org/packages/80/42/aff4d244acf70671b4ad432f8178965ba232c5371ea867a799c5502c902e/arkho-jsonquery-0.0.5.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "61b99204631e2435c086947c1a3b0bf1", "sha256": "abfb86ee1a344926e4659734a23633836b2f71b8cab03f1de0641884015032de" }, "downloads": -1, "filename": "arkho_jsonquery-0.0.5-py3-none-any.whl", "has_sig": false, "md5_digest": "61b99204631e2435c086947c1a3b0bf1", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.6", "size": 21829, "upload_time": "2019-09-23T15:06:33", "url": "https://files.pythonhosted.org/packages/cb/a0/c298a6fcc087dac7bd9cb87eb57b2b2b42c8286f1ffb31f843627a97b065/arkho_jsonquery-0.0.5-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "c6d44eecb53096219f45d059a4789ef8", "sha256": "80f5985c60388165a9ab643a8cbe3398d8a3721c5a9f05a0686d70b395eddf7b" }, "downloads": -1, "filename": "arkho-jsonquery-0.0.5.tar.gz", "has_sig": false, "md5_digest": "c6d44eecb53096219f45d059a4789ef8", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.6", "size": 10115, "upload_time": "2019-09-23T15:06:35", "url": "https://files.pythonhosted.org/packages/80/42/aff4d244acf70671b4ad432f8178965ba232c5371ea867a799c5502c902e/arkho-jsonquery-0.0.5.tar.gz" } ] }