1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
# Filter Functions
A filter function is a named function that can be called as part of a [filter selector](syntax.md#filter-selector). Here we describe built in filters. You can [define your own function extensions](advanced.md#function-extensions) too.
!!! note
If you pass `strict=True` when calling [`findall()`](convenience.md#jsonpath.findall), [`finditer()`](convenience.md#jsonpath.finditer), etc., Only standard functions - those defined by RFC 9535 - will be enabled. The standard functions are `count`, `length`, `match`, `search` and `value`.
## `count()`
```text
count(obj: object) -> Optional[int]
```
Return the number of items in _obj_. If the object does not respond to Python's `len()` function, `None` is returned.
```
$.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", "missing" |
| None | "null", "nil", "None", "none" |
| str | "str", "string" |
| Sequence (array-like) | "array", "list", "sequence", "tuple" |
| 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')]
```
## `keys()`
**_New in version 2.0.0_**
```
keys(value: object) -> Tuple[str, ...] | Nothing
```
Return a list of keys from an object/mapping. If `value` does not have a `keys()` method, the special _Nothing_ value is returned.
!!! note
`keys()` is not registered with the default JSONPath environment. The [keys selector](syntax.md#keys-selector) and [keys filter selector](syntax.md#keys-filter-selector) are usually the better choice when strict compliance with the specification is not needed.
You can register `keys()` with your JSONPath environment like this:
```python
from jsonpath import JSONPathEnvironment
from jsonpath import function_extensions
env = JSONPathEnvironment()
env.function_extensions["keys"] = function_extensions.Keys()
```
```
$.some[?'thing' in keys(@)]
```
## `length()`
```text
length(obj: object) -> Optional[int]
```
Return the number of items in the input object. If the object does not respond to Python's `len()` function, `None` is returned.
```
$.categories[?length(@) > 1]
```
## `match()`
```text
match(obj: object, pattern: str) -> bool
```
Return `True` if _obj_ is a string and is a full match to the regex _pattern_.
```text
$..products[?match(@.title, ".+ainers.+")]
```
If _pattern_ is a string literal, it will be compiled at compile time, and raise a `JSONPathTypeError` at compile time if it's invalid.
If _pattern_ is a query and the result is not a valid regex, `False` is returned.
## `search()`
```text
search(obj: object, pattern: str) -> bool
```
Return `True` if _obj_ is a string and it contains the regexp _pattern_.
```text
$..products[?search(@.title, "ainers")]
```
If _pattern_ is a string literal, it will be compiled at compile time, and raise a `JSONPathTypeError` at compile time if it's invalid.
If _pattern_ is a query and the result is not a valid regex, `False` is returned.
## `startswith()`
**_New in version 2.0.0_**
```
startswith(value: str, prefix: str) -> bool
```
Return `True` if `value` starts with `prefix`. If `value` or `prefix` are not strings, `False` is returned.
```
$[?startswith(@, 'ab')]
```
## `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()`.
`jsonpath.function_extensions.TypeOf` takes a `single_number_type` argument, which controls the behavior of `typeof()` when given and int or float. By default, `single_number_type` is `True` and `"number"` is returned. Register a new instance of `TypeOf` with a `JSONPathEnvironment` with `single_number_type` set to `False` and `"int"` and `"float"` will be returned when given integers and floats, respectively.
| instance | type string |
| --------------------- | ------------------------------------------------------ |
| UNDEFINED | "undefined" |
| None | "null" |
| str | "string" |
| Sequence (array-like) | "array" |
| Mapping (dict-like) | "object" |
| bool | "boolean" |
| int | "number" or "int" if `single_number_type` is `False` |
| float | "number" or "float" if `single_number_type` is `False` |
## `value()`
```
value(nodes: object) -> object | undefined
```
Return the first value from _nodes_ resulting from a JSONPath query, if there is only one node, or `undefined` otherwise.
```text
$..products[?value(@.price) == 9]
```
|
