feat: add typeof() and isinstance(), closes #4

Author: jg-rp

CHANGELOG.md

@@ -4,7 +4,9 @@
 
 **Features**
 
-- Added the keys/properties selector (`~`).
+- Added a non-standard keys/properties selector (`~`).
+- Added a non-standard `typeof()` filter function. `type()` is an alias for `typeof()`.
+- Added a non-standard `isinstance()` filter function. `is()` is an alias for `isinstance()`.
 
 **IETF JSONPath Draft compliance**
 

docs/functions.md

@@ -1,6 +1,6 @@
 # Filter Functions
 
-A filter function is a named function that can be called as part of a [filter selector](syntax.md#filters-expression) expression. Here we describe the standard, built-in filters. You can [define your own function extensions](advanced.md#function-extensions) too.
+A filter function is a named function that can be called as part of a [filter selector](syntax.md#filters-expression) expression. Here we describe built-in filters. You can [define your own function extensions](advanced.md#function-extensions) too.
 
 ## `count()`
 
@@ -14,6 +14,39 @@ Return the number of items in _obj_. If the object does not respond to Python's
 $.categories[?count(@.products.*) >= 2]
 ```
 
+## `isinstance()`
+
+**_New in version 0.6.0_**
+
+```text
+isinstance(obj: object, t: str) -> bool
+```
+
+Return `True` if the type of _obj_ matches _t_. This function allows _t_ to be one of several aliases for the real Python "type". Some of these aliases follow JavaScript/JSON semantics.
+
+| type                  | aliases                       |
+| --------------------- | ----------------------------- |
+| UNDEFINED             | "undefined"                   |
+| None                  | "null", "nil", "None", "none" |
+| str                   | "str", "string"               |
+| Sequence (array-like) | "array", "list", "sequence"   |
+| Mapping (dict-like)   | "object", "dict", "mapping"   |
+| bool                  | "bool", "boolean"             |
+| int                   | "number", "int"               |
+| float                 | "number", "float"             |
+
+For example :
+
+```
+$.categories[?isinstance(@.length, 'number')]
+```
+
+And `is()` is an alias for `isinstance()`:
+
+```
+$.categories[?is(@.length, 'number')]
+```
+
 ## `length()`
 
 ```text
@@ -58,6 +91,22 @@ If _pattern_ is a string literal, it will be compiled at compile time, and raise
 
 If _pattern_ is a query and the result is not a valid regex, `False` is returned.
 
+## `typeof()`
+
+**_New in version 0.6.0_**
+
+```text
+typeof(obj: object) -> str
+```
+
+Return the type of _obj_ as a string. The strings returned from this function use JavaScript/JSON terminology like "string", "array" and "object", much like the result of JavaScript's `typeof` operator.
+
+```
+$.categories[?typeof(@.length) == 'number']
+```
+
+`type()` is and alias for `typeof()`.
+
 ## `value()`
 
 ```

jsonpath/env.py

@@ -252,6 +252,10 @@ def setup_function_extensions(self) -> None:
         self.function_extensions["match"] = function_extensions.Match()
         self.function_extensions["search"] = function_extensions.Search()
         self.function_extensions["value"] = function_extensions.value
+        self.function_extensions["isinstance"] = function_extensions.IsInstance()
+        self.function_extensions["is"] = self.function_extensions["isinstance"]
+        self.function_extensions["typeof"] = function_extensions.TypeOf()
+        self.function_extensions["type"] = self.function_extensions["typeof"]
 
     def validate_function_extension_signature(
         self, token: Token, args: List[Any]

jsonpath/function_extensions/__init__.py

@@ -1,18 +1,22 @@
 # noqa: D104
 from .arguments import validate
 from .count import Count
+from .is_instance import IsInstance
 from .keys import keys
 from .length import length
 from .match import Match
 from .search import Search
+from .typeof import TypeOf
 from .value import value
 
 __all__ = (
     "Count",
-    "Match",
-    "Search",
-    "value",
+    "IsInstance",
     "keys",
     "length",
+    "Match",
+    "Search",
+    "TypeOf",
     "validate",
+    "value",
 )

jsonpath/function_extensions/is_instance.py

@@ -0,0 +1,35 @@
+"""A non-standard "isinstance" filter function."""
+
+from typing import Mapping
+from typing import Sequence
+
+from ..filter import UNDEFINED
+from ..filter import UNDEFINED_LITERAL
+
+
+class IsInstance:
+    """A non-standard "isinstance" filter function."""
+
+    def __call__(self, obj: object, t: str) -> bool:  # noqa: PLR0911
+        """Return `True` if the type of _obj_ matches _t_.
+
+        This function allows _t_ to be one of several aliases for the real
+        Python "type". Some of these aliases follow JavaScript/JSON semantics.
+        """
+        if obj is UNDEFINED or obj is UNDEFINED_LITERAL:
+            return t == "undefined"
+        if obj is None:
+            return t in ("null", "nil", "None", "none")
+        if isinstance(obj, str):
+            return t in ("str", "string")
+        if isinstance(obj, Sequence):
+            return t in ("array", "list", "sequence")
+        if isinstance(obj, Mapping):
+            return t in ("object", "dict", "mapping")
+        if isinstance(obj, bool):
+            return t in ("bool", "boolean")
+        if isinstance(obj, int):
+            return t in ("number", "int")
+        if isinstance(obj, float):
+            return t in ("number", "float")
+        return t == "object"

jsonpath/function_extensions/typeof.py

@@ -0,0 +1,43 @@
+"""A non-standard "typeof" filter function."""
+
+from typing import Mapping
+from typing import Sequence
+
+from ..filter import UNDEFINED
+from ..filter import UNDEFINED_LITERAL
+
+
+class TypeOf:
+    """A non-standard "typeof" filter function.
+
+    Arguments:
+        single_number_type: If True, will return "number" for ints and floats,
+            otherwise we'll use "int" and "float" respectively. Defaults to `True`.
+    """
+
+    def __init__(self, *, single_number_type: bool = True) -> None:
+        self.single_number_type = single_number_type
+
+    def __call__(self, obj: object) -> str:  # noqa: PLR0911
+        """Return the type of _obj_ as a string.
+
+        The strings returned from this function use JSON terminology, much
+        like the result of JavaScript's `typeof` operator.
+        """
+        if obj is UNDEFINED or obj is UNDEFINED_LITERAL:
+            return "undefined"
+        if obj is None:
+            return "null"
+        if isinstance(obj, str):
+            return "string"
+        if isinstance(obj, Sequence):
+            return "array"
+        if isinstance(obj, Mapping):
+            return "object"
+        if isinstance(obj, bool):
+            return "boolean"
+        if isinstance(obj, int):
+            return "number" if self.single_number_type else "int"
+        if isinstance(obj, float):
+            return "number" if self.single_number_type else "float"
+        return "object"

tests/test_isinstance_function.py

@@ -0,0 +1,107 @@
+import asyncio
+import dataclasses
+import operator
+from typing import Any
+from typing import List
+from typing import Mapping
+from typing import Sequence
+from typing import Union
+
+import pytest
+
+from jsonpath import JSONPathEnvironment
+
+
+@dataclasses.dataclass
+class Case:
+    description: str
+    path: str
+    data: Union[Sequence[Any], Mapping[str, Any]]
+    want: Union[Sequence[Any], Mapping[str, Any]]
+
+
+SOME_OBJECT = object()
+
+TEST_CASES = [
+    Case(
+        description="type of a string",
+        path="$.some[?is(@.thing, 'string')]",
+        data={"some": [{"thing": "foo"}]},
+        want=[{"thing": "foo"}],
+    ),
+    Case(
+        description="not a string",
+        path="$.some[?is(@.thing, 'string')]",
+        data={"some": [{"thing": 1}]},
+        want=[],
+    ),
+    Case(
+        description="type of undefined",
+        path="$.some[?is(@.other, 'undefined')]",  # things without `other`
+        data={"some": [{"thing": "foo"}]},
+        want=[{"thing": "foo"}],
+    ),
+    Case(
+        description="type of None",
+        path="$.some[?is(@.thing, 'null')]",
+        data={"some": [{"thing": None}]},
+        want=[{"thing": None}],
+    ),
+    Case(
+        description="type of array-like",
+        path="$.some[?is(@.thing, 'array')]",
+        data={"some": [{"thing": [1, 2, 3]}]},
+        want=[{"thing": [1, 2, 3]}],
+    ),
+    Case(
+        description="type of mapping",
+        path="$.some[?is(@.thing, 'object')]",
+        data={"some": [{"thing": {"other": 1}}]},
+        want=[{"thing": {"other": 1}}],
+    ),
+    Case(
+        description="type of bool",
+        path="$.some[?is(@.thing, 'boolean')]",
+        data={"some": [{"thing": True}]},
+        want=[{"thing": True}],
+    ),
+    Case(
+        description="type of int",
+        path="$.some[?is(@.thing, 'number')]",
+        data={"some": [{"thing": 1}]},
+        want=[{"thing": 1}],
+    ),
+    Case(
+        description="type of float",
+        path="$.some[?is(@.thing, 'number')]",
+        data={"some": [{"thing": 1.1}]},
+        want=[{"thing": 1.1}],
+    ),
+    Case(
+        description="none of the above",
+        path="$.some[?is(@.thing, 'object')]",
+        data={"some": [{"thing": SOME_OBJECT}]},
+        want=[{"thing": SOME_OBJECT}],
+    ),
+]
+
+
+@pytest.fixture()
+def env() -> JSONPathEnvironment:
+    return JSONPathEnvironment()
+
+
+@pytest.mark.parametrize("case", TEST_CASES, ids=operator.attrgetter("description"))
+def test_isinstance_function(env: JSONPathEnvironment, case: Case) -> None:
+    path = env.compile(case.path)
+    assert path.findall(case.data) == case.want
+
+
+@pytest.mark.parametrize("case", TEST_CASES, ids=operator.attrgetter("description"))
+def test_isinstance_function_async(env: JSONPathEnvironment, case: Case) -> None:
+    path = env.compile(case.path)
+
+    async def coro() -> List[object]:
+        return await path.findall_async(case.data)
+
+    assert asyncio.run(coro()) == case.want