[stefankoegl]

A patch that could not be applied, an invalid patch, invalid JSON, and errors reading or writing files all ended the command line programs with a Python traceback. They now print one line to stderr and exit with status 2:

$ jsonpatch doc.json patch.json
jsonpatch: error: can't remove a non-existent object 'zz'

$ jsondiff a.json broken.json
jsondiff: error: broken.json: Expecting property name enclosed in double quotes: line 2 column 1 (char 2)

This is the format and status argparse already uses for wrong arguments and files that cannot be opened.

Behaviour changes

• Exit status 2 instead of 1 for these errors. This keeps them apart from status 1, with which jsondiff reports that the files differ (as diff does). Scripts that test for "non-zero" are unaffected; scripts that test jsonpatch for exactly 1 would need changing.
• Messages for invalid JSON and invalid UTF-8 name the file, or <stdin>.
• Handled: JsonPatchException, JsonPointerException, ValueError (JSON and encoding errors) and OSError. Anything else would be a bug and still shows a traceback. Ctrl-C still exits silently with status 1.

Internally, diff_files() and patch_files() now raise a ValueError that wraps the JSONDecodeError (as __cause__) in order to carry the file name.

Docs and tests

• doc/commandline.rst describes the exit statuses.
• New tests for each kind of error for both programs. Three existing tests looked for exception names in the traceback and now check the message instead.

python tests.py passes with coverage at 100%; flake8 and sphinx-build -W are clean (Python 3.13).

Touches jsonpatch_cli.py and tests.py in different places than #270, so the two should merge in either order.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PewzpjVeke4LTQ7Q88nyu6

[coveralls]

coverage: 100.0%. remained the same — claude/cli-error-messages into master

[Copilot]

🟡 Changes recommended

Buffered stdout failures can escape error handling and produce the wrong exit status, while unescaped newlines in exception messages or filenames can violate the promised one-line diagnostic.

2 open issues

• Flush stdout safely to preserve the promised exit status on broken pipes · New
• Escape newlines in error messages to keep diagnostics on one line · New

What changed in this PR

This PR centralizes error handling for the jsondiff and jsonpatch command-line tools, replacing tracebacks for expected input and file errors with concise diagnostics and exit status 2.

Changes:

• Adds shared error handling and filenames to JSON and encoding errors.
• Adds error-reporting tests and updates existing assertions.
• Documents error statuses while preserving jsondiff’s status 1 for differing files.

File	Description
tests.py	Tests diagnostics, exit statuses, input errors, and interruption handling.
jsonpatch_cli.py	Adds shared error handling and filename-aware JSON loading.
doc/​commandline.rst	Documents error reporting and exit statuses.

_{Review effort: Balanced}