Skip to content

cli.md

Latest commit

 

History

History
321 lines (223 loc) · 10.3 KB

cli.md

File metadata and controls

321 lines (223 loc) · 10.3 KB

Command Line Interface

New in version 0.9.0

Python JSONPath includes a script called json, exposing JSONPath, JSON Pointer and JSON Patch features on the command line. Use the --version argument to check the current version of Python JSONPath, and the --help argument to display command information.

$ json --version
python-jsonpath, version 0.9.0
$ json --help
usage: json [-h] [--debug] [--pretty] [-v] [--no-unicode-escape] COMMAND ...

JSONPath, JSON Pointer and JSON Patch utilities.

positional arguments:
  COMMAND
    path               Find objects in a JSON document given a JSONPath.
    pointer            Resolve a JSON Pointer against a JSON document.
    patch              Apply a JSON Patch to a JSON document.

optional arguments:
  -h, --help           show this help message and exit
  --debug              Show stack traces. (default: False)
  --pretty             Add indents and newlines to output JSON. (default: False)
  -v, --version        Show the version and exit.
  --no-unicode-escape  Disable decoding of UTF-16 escape sequence within paths and pointers. (default:
                       False)

Use [json COMMAND --help] for command specific help.

Usage Examples:
  Find objects in source.json matching a JSONPath, write them to result.json.
  $ json path -q "$.foo['bar'][[email protected] > 1]" -f source.json -o result.json

  Resolve a JSON Pointer against source.json, pretty print the result to stdout.
  $ json --pretty pointer -p "/foo/bar/0" -f source.json

  Apply JSON Patch patch.json to JSON from stdin, output to result.json.
  $ cat source.json | json patch /path/to/patch.json -o result.json

Use json COMMAND --help for command specific help.

$ json path --help
usage: json path [-h] (-q QUERY | -r PATH_FILE) [-f FILE] [-o OUTPUT]

Find objects in a JSON document given a JSONPath.

optional arguments:
  -h, --help            show this help message and exit
  -q QUERY, --query QUERY
                        JSONPath query string.
  -r PATH_FILE, --path-file PATH_FILE
                        Text file containing a JSONPath query.
  -f FILE, --file FILE  File to read the target JSON document from. Defaults to reading from the
                        standard input stream.
  -o OUTPUT, --output OUTPUT
                        File to write resulting objects to, as a JSON array. Defaults to the standard
                        output stream.
  --no-type-checks      Disables filter expression well-typedness checks.
  --strict              Compile and evaluate JSONPath expressions with strict compliance with RFC 9535.

Global Options

These arguments apply to any subcommand and must be listed before the command.

--debug

Enable debugging. Display full stack traces, if available, when errors occur. Without the --debug option, the following example shows a short "json path syntax error" message.

$ json path -q "$.1" -f /tmp/source.json
json path syntax error: unexpected token '1', line 1, column 2

With the --debug option, we get the stack trace triggered by JSONPathSyntaxError.

$ json --debug path -q "$.1" -f /tmp/source.json
Traceback (most recent call last):
  File "/home/james/.local/share/virtualenvs/jsonpath_cli-8Tb3e-ir/bin/json", line 8, in <module>
    sys.exit(main())
  File "/home/james/.local/share/virtualenvs/jsonpath_cli-8Tb3e-ir/lib/python3.9/site-packages/jsonpath/cli.py", line 338, in main
    args.func(args)
  File "/home/james/.local/share/virtualenvs/jsonpath_cli-8Tb3e-ir/lib/python3.9/site-packages/jsonpath/cli.py", line 234, in handle_path_command
    path = jsonpath.compile(args.query or args.path_file.read())
  File "/home/james/.local/share/virtualenvs/jsonpath_cli-8Tb3e-ir/lib/python3.9/site-packages/jsonpath/env.py", line 148, in compile
    _path: Union[JSONPath, CompoundJSONPath] = JSONPath(
  File "/home/james/.local/share/virtualenvs/jsonpath_cli-8Tb3e-ir/lib/python3.9/site-packages/jsonpath/path.py", line 49, in __init__
    self.selectors = tuple(selectors)
  File "/home/james/.local/share/virtualenvs/jsonpath_cli-8Tb3e-ir/lib/python3.9/site-packages/jsonpath/parse.py", line 256, in parse
    raise JSONPathSyntaxError(
jsonpath.exceptions.JSONPathSyntaxError: unexpected token '1', line 1, column 2

--pretty

Enable pretty formatting when outputting JSON. Adds newlines and indentation to output specified with the -o or --output option. Without the --pretty option, the following example output is on one line.

$ json pointer -p "/categories/1/products/0" -f /tmp/source.json
{"title": "Cap", "description": "Baseball cap", "price": 15.0}

With the --pretty option, we get nicely formatted JSON output.

$ json --pretty pointer -p "/categories/1/products/0" -f /tmp/source.json
{
  "title": "Cap",
  "description": "Baseball cap",
  "price": 15.0
}

--no-unicode-escape

Disable decoding of UTF-16 escape sequences, including surrogate paris. This can improve performance if you know your paths and pointers don't contain UTF-16 escape sequences.

$ json --no-unicode-escape path -q "$.price_cap" -f /tmp/source.json

Commands

One of the subcommands path, pointer or patch must be specified, depending on whether you want to search a JSON document with a JSONPath, resolve a JSON Pointer against a JSON document or apply a JSON Patch to a JSON Document.

path

Find objects in a JSON document given a JSONPath. One of -q/--query or -r/--path-file must be given. -q being a JSONPath given on the command line as a string, -r being the path to a file containing a JSONPath.

json path [-h] (-q QUERY | -r PATH_FILE) [-f FILE] [-o OUTPUT]

-q / --query

The JSONPath as a string.

$ json path -q "$.price_cap" -f /tmp/source.json
$ json path --query "$.price_cap" -f /tmp/source.json

-r / --path-file

The path to a file containing a JSONPath.

$ json path -r /tmp/path.txt -f /tmp/source.json
$ json path --path-file /tmp/path.txt -f /tmp/source.json

-f / --file

The path to a file containing the target JSON document. If omitted or a hyphen (-), the target JSON document will be read from the standard input stream.

$ json path -q "$.price_cap" -f /tmp/source.json
$ json path -q "$.price_cap" --file /tmp/source.json

-o / --output

The path to a file to write resulting objects to, as a JSON array. If omitted or a hyphen (-) is given, results will be written to the standard output stream.

$ json path -q "$.price_cap" -f /tmp/source.json -o result.json
$ json path -q "$.price_cap" -f /tmp/source.json --output result.json

--no-type-checks

New in version 0.10.0

Disables JSONPath filter expression well-typedness checks. The well-typedness of a filter expression is defined by RFC 9535.

--strict

New in version 2.0.0

Compile and evaluate JSONPath expressions with strict compliance with RFC 9535.

pointer

Resolve a JSON Pointer against a JSON document. One of -p/--pointer or -r/--pointer-file must be given. -p being a JSON Pointer given on the command line as a string, -r being the path to a file containing a JSON Pointer.

json pointer [-h] (-p POINTER | -r POINTER_FILE) [-f FILE] [-o OUTPUT] [-u]

-p / --pointer

An RFC 6901 formatted JSON Pointer string.

$ json pointer -p "/categories/0/name" -f /tmp/source.json
$ json pointer --pointer "/categories/0/name" -f /tmp/source.json

-r / --pointer-file

The path to a file containing a JSON Pointer.

$ json pointer -r /tmp/pointer.txt -f /tmp/source.json
$ json pointer --pointer-file /tmp/pointer.txt -f /tmp/source.json

-f / --file

The path to a file containing the target JSON document. If omitted or a hyphen (-), the target JSON document will be read from the standard input stream.

$ json pointer -p "/categories/0/name" -f /tmp/source.json
$ json pointer -p "/categories/0/name" --file /tmp/source.json

-o / --output

The path to a file to write the resulting object to. If omitted or a hyphen (-) is given, results will be written to the standard output stream.

$ json pointer -p "/categories/0/name" -f /tmp/source.json -o result.json
$ json pointer -p "/categories/0/name" -f /tmp/source.json --output result.json

-u / --uri-decode

Enable URI decoding of the JSON Pointer. In this example, we would look for a property called "hello world" in the root of the target document.

$ json pointer -p "/hello%20world" -f /tmp/source.json -u
$ json pointer -p "/hello%20world" -f /tmp/source.json --uri-decode

patch

Apply a JSON Patch to a JSON document. Unlike path and pointer commands, a patch can't be given as a string argument. PATCH is a positional argument that should be a file path to a JSON Patch document or a hyphen (-), which means the patch document will be read from the standard input stream.

json patch [-h] [-f FILE] [-o OUTPUT] [-u] PATCH

These examples read the patch from patch.json and the document to modify from target.json

$ json patch /tmp/patch.json -f /tmp/target.json
$ cat /tmp/patch.json | json patch - -f /tmp/target.json

-f / --file

The path to a file containing the target JSON document. If omitted or a hyphen (-), the target JSON document will be read from the standard input stream.

$ json patch /tmp/patch.json -f /tmp/target.json
$ json patch /tmp/patch.json --file /tmp/target.json

-o / --output

The path to a file to write the resulting object to. If omitted or a hyphen (-) is given, results will be written to the standard output stream.

$ json patch /tmp/patch.json -f /tmp/target.json -o result.json
$ json patch /tmp/patch.json -f /tmp/target.json --output result.json

-u / --uri-decode

Enable URI decoding of JSON Pointers in the patch document.

$ json patch /tmp/patch.json -f /tmp/target.json -u
$ json patch /tmp/patch.json -f /tmp/target.json --uri-decode