| \section{\module{atexit} --- |
| Exit handlers} |
| |
| \declaremodule{builtin}{atexit} |
| \moduleauthor{Skip Montanaro}{skip@mojam.com} |
| \sectionauthor{Skip Montanaro}{skip@mojam.com} |
| \modulesynopsis{Register and execute cleanup functions.} |
| |
| \versionadded{2.0} |
| |
| |
| The \module{atexit} module defines functions to register and |
| unregister cleanup functions. Functions thus registered are |
| automatically executed upon normal interpreter termination. |
| |
| Note: the functions registered via this module are not called when |
| the program is killed by a signal, when a Python fatal internal |
| error is detected, or when \function{os._exit()} is called. |
| |
| \begin{funcdesc}{register}{func\optional{, *args\optional{, **kargs}}} |
| Register \var{func} as a function to be executed at termination. Any |
| optional arguments that are to be passed to \var{func} must be passed |
| as arguments to \function{register()}. |
| |
| At normal program termination (for instance, if |
| \function{sys.exit()} is called or the main module's execution |
| completes), all functions registered are called in last in, first out |
| order. The assumption is that lower level modules will normally be |
| imported before higher level modules and thus must be cleaned up |
| later. |
| |
| If an exception is raised during execution of the exit handlers, a |
| traceback is printed (unless \exception{SystemExit} is raised) and the |
| exception information is saved. After all exit handlers have had a |
| chance to run the last exception to be raised is re-raised. |
| |
| \versionchanged[This function now returns \var{func} which makes it |
| possible to use it as a decorator without binding the |
| original name to \code{None}]{2.6} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{unregister}{func} |
| Remove a function \var{func} from the list of functions to be run at |
| interpreter-shutdown. After calling \function{unregister()}, |
| \var{func} is guaranteed not to be called when the interpreter |
| shuts down. |
| |
| \versionadded{3.0} |
| \end{funcdesc} |
| |
| |
| \begin{seealso} |
| \seemodule{readline}{Useful example of \module{atexit} to read and |
| write \refmodule{readline} history files.} |
| \end{seealso} |
| |
| |
| \subsection{\module{atexit} Example \label{atexit-example}} |
| |
| The following simple example demonstrates how a module can initialize |
| a counter from a file when it is imported and save the counter's |
| updated value automatically when the program terminates without |
| relying on the application making an explicit call into this module at |
| termination. |
| |
| \begin{verbatim} |
| try: |
| _count = int(open("/tmp/counter").read()) |
| except IOError: |
| _count = 0 |
| |
| def incrcounter(n): |
| global _count |
| _count = _count + n |
| |
| def savecounter(): |
| open("/tmp/counter", "w").write("%d" % _count) |
| |
| import atexit |
| atexit.register(savecounter) |
| \end{verbatim} |
| |
| Positional and keyword arguments may also be passed to |
| \function{register()} to be passed along to the registered function |
| when it is called: |
| |
| \begin{verbatim} |
| def goodbye(name, adjective): |
| print 'Goodbye, %s, it was %s to meet you.' % (name, adjective) |
| |
| import atexit |
| atexit.register(goodbye, 'Donny', 'nice') |
| |
| # or: |
| atexit.register(goodbye, adjective='nice', name='Donny') |
| \end{verbatim} |
| |
| Usage as a decorator: |
| |
| \begin{verbatim} |
| import atexit |
| |
| @atexit.register |
| def goodbye(): |
| print "You are now leaving the Python sector." |
| \end{verbatim} |
| |
| This obviously only works with functions that don't take arguments. |