You're looking for calls to sys.exit(...) (exit(...) calls sys.exit(...)) in the script. The argument to that method is returned to the environment as the exit code.

It's fairly likely that the script is never calling the exit(...) method, and that 0 is the default exit code.

Wait until the end of your loop to return the 1 exit code. I'd do it like:

def process_pdf_dir() -> int:
    ret = 0
    for file in os.listdir('pdf_files/'):
        if file.endswith('.pdf'):

            if not anonymiser(file):
                # remember to return a warning
                ret = 1

            if criticalError:
                # immediately return a failure
                return 2
    return ret

if __name__ == '__main__':
    sys.exit(process_pdf_dir())

If "critical error" includes uncaught exceptions, maybe put that outside of process_pdf_dir, e.g.:

if __name__ == '__main__':
    try:
        sys.exit(process_pdf_dir())
    except:
        sys.exit(2)

Take a look at the traceback module. You could do the following:

import sys, traceback

try:
  raise Exception()
except:
  traceback.print_exc()
  sys.exit(3)

This will write traceback to standard error and exit with code 3.

sys.exit documents a default exit status of 0, and os._exit's docs specify a UNIX-like OS constant for "normal" exit status, os.EX_OK, but there is no documented guarantee I can find for the exit status in general.

Aside from that, the best I can give you is that in CPython, the python executable (including python.exe/pythonw.exe on Windows) is implemented in python.c by calling Py_Main and returning whatever it returns; per the documented guarantees on Py_Main, the exit status is:

0 if the interpreter exits normally (i.e., without an exception), 1 if the interpreter exits due to an exception, or 2 if the parameter list does not represent a valid Python command line.

Note that if an otherwise unhandled SystemExit is raised, this function will not return 1, but exit the process, as long as Py_InspectFlag is not set.

so this implies that simply running off the end of the __main__ module without an active exception should always return 0 for CPython, though alternate interpreters are not technically required to do the same.

This tracks with the implied exit status rules expected of most applications; while nothing explicitly says Python has to follow those rules, it would be extremely unusual for a tool that grew up in the command line UNIX-like world to violate those conventions.

As JBernardo pointed out, sys.exit() raises an exception. This exception is SystemExit. When it is not handled by the user code, the interpreter exits cleanly (a debugger debugging the program can catch it and keep control of the program, thanks to this mechanism, for instance)—as opposed to os._exit(), which is an unconditional abortion of the program.

This exception is not caught by except Exception:, because SystemExit does not inherit from Exception. However, it is caught by a naked except: clause.

So, if your program sees an exception, you may want to catch fewer exceptions by using except Exception: instead of except:. That said, catching all exceptions is discouraged, because this might hide real problems, so avoid it if you can, by making the except clause (if any) more specific.

My understanding of why this SystemExit exception mechanism is useful is that the user code goes through any finally clause after a sys.exit() found in an except clause: files can be closed cleanly, etc.; then the interpreter catches any SystemExit that was not caught by the user and exits for good (a debugger would instead catch it so as to keep the interpreter running and obtain information about the program that exited).