docs: describe the API and add function descriptions in the code

Author: josdejong

README.md

@@ -2,7 +2,7 @@
 
 ![JSON Query Logo](https://jsonquerylang.org/frog-756900-100.png)
 
-This is the Python implementation of **JSON Query**, a small, flexible, and expandable JSON query language.
+This is a Python implementation of **JSON Query**, a small, flexible, and expandable JSON query language.
 
 Try it out on the online playground: <https://jsonquerylang.org>
 
@@ -35,6 +35,150 @@ pprint(execute([32, 19, 23])) # [19, 23, 32]
 pprint(execute([5, 2, 7, 4])) # [2, 4, 5, 7]
 ```
 
+## API
+
+### jsonquery
+
+Compile and evaluate a JSON query.
+
+Syntax:
+
+```
+jsonquery(data, query [, options])
+```
+
+Where:
+
+- `data` is a JSON object or array
+- `query` is a JSON query or string containing a text query
+- `options` is an optional object which can have the following options:
+  - `functions` an object with custom functions
+
+Example:
+
+```python
+from pprint import pprint
+from "jsonquery" import jsonquery
+
+input = [
+    {"name": "Chris", "age": 23, "scores": [7.2, 5, 8.0]},
+    {"name": "Joe", "age": 32, "scores": [6.1, 8.1]},
+    {"name": "Emily", "age": 19},
+]
+query = ["sort", ["get", "age"], "desc"]
+output = jsonquery(query)
+pprint(output)
+# [{'age': 32, 'name': 'Joe', 'scores': [6.1, 8.1]},
+#  {'age': 23, 'name': 'Chris', 'scores': [7.2, 5, 8.0]},
+#  {'age': 19, 'name': 'Emily'}]
+```
+
+### compile
+
+Compile a JSON Query. Returns a function which can execute the query.
+
+Syntax:
+
+```
+compile(query [, options])
+```
+
+Where:
+
+- `query` is a JSON query or string containing a text query
+- `options` is an optional object which can have the following options:
+  - `functions` an object with custom functions
+
+The function returns a lambda function which can be executed by passing JSON data as first argument.
+
+Example:
+
+```python
+from pprint import pprint
+from "jsonquery" import compile
+
+input = [
+    {"name": "Chris", "age": 23, "scores": [7.2, 5, 8.0]},
+    {"name": "Joe", "age": 32, "scores": [6.1, 8.1]},
+    {"name": "Emily", "age": 19},
+]
+query = ["sort", ["get", "age"], "desc"]
+queryMe = compile(query)
+output = queryMe(input)
+pprint(output)
+# [{'age': 32, 'name': 'Joe', 'scores': [6.1, 8.1]},
+#  {'age': 23, 'name': 'Chris', 'scores': [7.2, 5, 8.0]},
+#  {'age': 19, 'name': 'Emily'}]
+```
+
+### parse
+
+Parse a string containing a JSON Query into JSON.
+
+Syntax:
+
+```
+parse(textQuery, [, options]) 
+```
+
+Where: 
+
+- `textQuery`: A query in text format
+- `options`: An optional object which can have the following properties:
+  - `functions` an object with custom functions
+  - `operators` an object with the names of custom operators both as key and value
+
+Example:
+
+```python
+from pprint import pprint
+from "jsonquery" import parse
+
+text_query = '.friends | filter(.city == "new York") | sort(.age) | pick(.name, .age)'
+json_query = parse(text_query)
+pprint(json_query)
+# ['pipe',
+#  ['get', 'friends'],
+#  ['filter', ['eq', ['get', 'city'], 'New York']],
+#  ['sort', ['get', 'age']],
+#  ['pick', ['get', 'name'], ['get', 'age']]]
+```
+
+### stringify
+
+Stringify a JSON Query into a readable, human friendly text format.
+
+Syntax:
+
+```
+stringify(query [, options])
+```
+
+Where:
+
+- `query` is a JSON Query
+- `options` is an optional object that can have the following properties:
+  - `operators` an object with the names of custom operators both as key and value
+  - `indentation` a string containing the desired indentation, defaults to two spaces: `"  "`
+  - `max_line_length` a number with the maximum line length, used for wrapping contents. Default value: `40`.
+
+Example:
+
+```python
+from "jsonquery" import stringify
+
+jsonQuery = [
+    "pipe",
+    ["get", "friends"],
+    ["filter", ["eq", ["get", "city"], "New York"]],
+    ["sort", ["get", "age"]],
+    ["pick", ["get", "name"], ["get", "age"]],
+]
+textQuery = stringify(jsonQuery)
+print(textQuery)
+# '.friends | filter(.city == "new York") | sort(.age) | pick(.name, .age)'
+```
+
 ## License
 
 Released under the [ISC license](LICENSE.md).

jsonquery/compile.py

@@ -8,7 +8,25 @@ def compile(
     query: JsonQueryType, options: Optional[JsonQueryOptions] = None
 ) -> Callable[[JsonType], JsonType]:
     """
-    Compile a JSON Query
+    Compile a JSON Query.
+
+    Example:
+
+        from pprint import pprint
+        from "jsonquery" import compile
+
+        input = [
+            {"name": "Chris", "age": 23, "scores": [7.2, 5, 8.0]},
+            {"name": "Joe", "age": 32, "scores": [6.1, 8.1]},
+            {"name": "Emily", "age": 19},
+        ]
+        query = ["sort", ["get", "age"], "desc"]
+        queryMe = compile(query)
+        output = queryMe(input)
+        pprint(output)
+        # [{'age': 32, 'name': 'Joe', 'scores': [6.1, 8.1]},
+        #  {'age': 23, 'name': 'Chris', 'scores': [7.2, 5, 8.0]},
+        #  {'age': 19, 'name': 'Emily'}]
 
     :param query: A JSON Query
     :param options: Can an object with custom functions

jsonquery/jsonquery.py

@@ -1,19 +1,39 @@
-from jsonquery.types import JsonType, JsonQueryType, JsonQueryOptions
 from jsonquery.compile import compile
+from jsonquery.parse import parse
+from jsonquery.types import JsonType, JsonQueryType, JsonQueryOptions
 
 
 def jsonquery(
-    data: JsonType, query: JsonQueryType, options: JsonQueryOptions | None = None
+    data: JsonType, query: JsonQueryType | str, options: JsonQueryOptions | None = None
 ) -> JsonType:
     """
-    Compile and evaluate a query
+    Compile and evaluate a JSON query.
+
+    Example:
+
+        from pprint import pprint
+        from "jsonquery" import jsonquery
+
+        input = [
+            {"name": "Chris", "age": 23, "scores": [7.2, 5, 8.0]},
+            {"name": "Joe", "age": 32, "scores": [6.1, 8.1]},
+            {"name": "Emily", "age": 19},
+        ]
+        query = ["sort", ["get", "age"], "desc"]
+        output = jsonquery(query)
+        pprint(output)
+        # [{'age': 32, 'name': 'Joe', 'scores': [6.1, 8.1]},
+        #  {'age': 23, 'name': 'Chris', 'scores': [7.2, 5, 8.0]},
+        #  {'age': 19, 'name': 'Emily'}]
 
     :param data: The JSON document to be queried
     :param query: A JSON Query
     :param options: Can an object with custom functions
     :return: Returns the result of the query applied to the data
     """
 
-    evaluate = compile(query, options)
+    _query = parse(query, options) if isinstance(query, str) else query
+
+    evaluate = compile(_query, options)
 
     return evaluate(data)

jsonquery/parse.py

@@ -15,8 +15,34 @@
 
 
 def parse(query: str, options: Optional[JsonQueryParseOptions] = None) -> JsonQueryType:
-    # FIXME: document the function
-
+    """
+    Parse a string containing a JSON Query into JSON.
+
+    Example:
+
+        from pprint import pprint
+        from "jsonquery" import parse
+
+        text_query = '.friends | filter(.city == "new York") | sort(.age) | pick(.name, .age)'
+        json_query = parse(text_query)
+        pprint(json_query)
+        # ['pipe',
+        #  ['get', 'friends'],
+        #  ['filter', ['eq', ['get', 'city'], 'New York']],
+        #  ['sort', ['get', 'age']],
+        #  ['pick', ['get', 'name'], ['get', 'age']]]
+
+    :param query: A query in text format
+    :param options: Can an object with custom operators and functions
+    :return: Returns the query in JSON format
+    """
+    jsonQuery = [
+        "pipe",
+        ["get", "friends"],
+        ["filter", ["eq", ["get", "city"], "New York"]],
+        ["sort", ["get", "age"]],
+        ["pick", ["get", "name"], ["get", "age"]],
+    ]
     custom_operators: Final = (options.get("operators") if options else None) or {}
     custom_functions: Final = (options.get("functions") if options else None) or {}
     all_functions: Final = {**functions, **custom_functions}

jsonquery/stringify.py

@@ -17,7 +17,28 @@
 def stringify(
     query: JsonQueryType, options: Optional[JsonQueryStringifyOptions] = None
 ) -> str:
-    # FIXME: document the function
+    """
+    Stringify a JSON Query into a readable, human friendly text syntax.
+
+    Example:
+
+        from "jsonquery" import stringify
+
+        jsonQuery = [
+            "pipe",
+            ["get", "friends"],
+            ["filter", ["eq", ["get", "city"], "New York"]],
+            ["sort", ["get", "age"]],
+            ["pick", ["get", "name"], ["get", "age"]],
+        ]
+        textQuery = stringify(jsonQuery)
+        print(textQuery)
+        # '.friends | filter(.city == "new York") | sort(.age) | pick(.name, .age)'
+
+    :param query: A JSON Query
+    :param options: A dict with custom operators, max_line_length, and indentation
+    :return: Returns a human friendly string representation of the query
+    """
 
     space: Final = (
         options.get("indentation") if options else None

jsonquery/types.py

@@ -1,6 +1,8 @@
 from typing import TypeAlias, List, Mapping, TypedDict, Callable, NotRequired
 
-JsonType: TypeAlias = List["JsonValueType"] | Mapping[str, "JsonValueType"]
+JsonType: TypeAlias = (
+    List["JsonValueType"] | Mapping[str, "JsonValueType"] | "JsonValueType"
+)
 JsonValueType: TypeAlias = str | int | float | None | JsonType
 
 JsonPath = List[str | int]

tests/test_jsonquery.py

@@ -20,6 +20,22 @@ def test_jsonquery(self):
             ],
         )
 
+    def test_jsonquery_str1(self):
+        """Test jsonquery parsing a query text"""
+        self.assertEqual(
+            jsonquery(data, "sort(.name)"),
+            [
+                {"name": "Chris", "age": 23, "scores": [7.2, 5, 8.0]},
+                {"name": "Emily", "age": 19},
+                {"name": "Joe", "age": 32, "scores": [6.1, 8.1]},
+            ],
+        )
+
+    def test_jsonquery_str2(self):
+        """Test jsonquery parsing a query text with options"""
+        options = {"functions": {"times": lambda factor: lambda x: x * factor}}
+        self.assertEqual(jsonquery(4, "times(3)", options), 12)
+
     def test_options1(self):
         """Test defining a custom function"""