Implement exit codes in Jupytext CLI for the most common errors

[mwouts]

As suggested by @caenrigen at caenrigen/vscode-jupytext-sync#12 (comment), we could return more informative exit codes - especially when Jupytext has a single file as argument.

[caenrigen]

Hi Mark, I have been working on making use of jupytext --paired-paths in Jupytext Sync VS Code extension and the topic of the exit codes came up again and I think I have a stronger opinion now about the meaning of exit codes.

I find it counter intuitive and unconventional (in terms of unix/POSIX) to have a CLI tool that returns a non-zero exit code when the command executed perfectly fine without any error.

In particular, have a look at this example (previous exit code shows inside ╰[1] on my zsh shell prompt). This might be a particular bug in the --paired-paths. I always get exit code 1 it seems independently of the number of files. I think you mentioned somewhere that for one of the jupytext commands the return code was tied to the number of files, but I guess it is not the case here:

╰[✔] g n23 ~/Documents/ProjectsDev/vscode/vscode-jupytext-sync-testing/config ‹master●› 
[25-11-23 12:21:15] $ jupytext --version
1.18.1
╰[✔] g n23 ~/Documents/ProjectsDev/vscode/vscode-jupytext-sync-testing/config ‹master●› 
[25-11-23 11:48:07] $ jupytext --paired-paths notebook.py
notebook.md
╰[1] g n23 ~/Documents/ProjectsDev/vscode/vscode-jupytext-sync-testing/config ‹master●› 
[25-11-23 11:49:34] $ jupytext --paired-paths jupytext.toml
Traceback (most recent call last):
  File "/opt/homebrew/anaconda3/envs/g/bin/jupytext", line 8, in <module>
    sys.exit(jupytext())
             ~~~~~~~~^^
... REDACTED ...
jupytext.formats.JupytextFormatError: Extension '.toml' is not a notebook extension. Please use one of '.ipynb', '.md', '.markdown', '.Rmd', '.py', '.coco', '.R', '.r', '.jl', '.cpp', '.ss', '.clj', '.scm', '.sh', '.ps1', '.q', '.m', '.wolfram', '.pro', '.js', '.ts', '.scala', '.rs', '.robot', '.resource', '.cs', '.fsx', '.fs', '.sos', '.java', '.groovy', '.sage', '.ml', '.hs', '.tcl', '.mac', '.gp', '.do', '.sas', '.xsh', '.lgt', '.logtalk', '.lua', '.go', '.qmd', '.myst', '.mystnb', '.mnb', '.auto'.
╰[1] g n23 ~/Documents/ProjectsDev/vscode/vscode-jupytext-sync-testing/config ‹master●› 
[25-11-23 11:49:35] $ 

Is this is a bug? If not, how do I distinguish between: all is good vs actual fatal error as shown above? If it is a bug let me know if you want me to move this to a new dedicated issue.

---

In any case, as a continuation of the topic of what should be the meaning of the exit codes, consider the following as well:

If you enable the "exit on error" feature in a bash script (that calls jupytext commands) via set -e, at the top of the script, for debugging purposes usually, you would not want the jupytext --paired-paths to interrupt the script when there are no fatal errors.

---

In the meantime, I will try o dig into the jupytext source to see if I can access the equivalent of --paired-paths via some python functions which can give me more freedom of how my code interacts with it.

[caenrigen]

Quick update, I used the internal python functions for the VS Code extension. It is actually better because I can output JSON from Python and load it again in JS for a more "clean" programmatic flow.

Regarding the bug above, from look at the jupytext code the --paired-paths (print_paired_paths) simply returns 1 which ends up being the command's exit code.