Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame^] | 1 | |
| 2 | :mod:`atexit` --- Exit handlers |
| 3 | =============================== |
| 4 | |
| 5 | .. module:: atexit |
| 6 | :synopsis: Register and execute cleanup functions. |
| 7 | .. moduleauthor:: Skip Montanaro <skip@mojam.com> |
| 8 | .. sectionauthor:: Skip Montanaro <skip@mojam.com> |
| 9 | |
| 10 | |
| 11 | .. versionadded:: 2.0 |
| 12 | |
| 13 | The :mod:`atexit` module defines functions to register and unregister cleanup |
| 14 | functions. Functions thus registered are automatically executed upon normal |
| 15 | interpreter termination. |
| 16 | |
| 17 | Note: the functions registered via this module are not called when the program |
| 18 | is killed by a signal, when a Python fatal internal error is detected, or when |
| 19 | :func:`os._exit` is called. |
| 20 | |
| 21 | |
| 22 | .. function:: register(func[, *args[, **kargs]]) |
| 23 | |
| 24 | Register *func* as a function to be executed at termination. Any optional |
| 25 | arguments that are to be passed to *func* must be passed as arguments to |
| 26 | :func:`register`. |
| 27 | |
| 28 | At normal program termination (for instance, if :func:`sys.exit` is called or |
| 29 | the main module's execution completes), all functions registered are called in |
| 30 | last in, first out order. The assumption is that lower level modules will |
| 31 | normally be imported before higher level modules and thus must be cleaned up |
| 32 | later. |
| 33 | |
| 34 | If an exception is raised during execution of the exit handlers, a traceback is |
| 35 | printed (unless :exc:`SystemExit` is raised) and the exception information is |
| 36 | saved. After all exit handlers have had a chance to run the last exception to |
| 37 | be raised is re-raised. |
| 38 | |
| 39 | .. versionchanged:: 2.6 |
| 40 | This function now returns *func* which makes it possible to use it as a |
| 41 | decorator without binding the original name to ``None``. |
| 42 | |
| 43 | |
| 44 | .. function:: unregister(func) |
| 45 | |
| 46 | Remove a function *func* from the list of functions to be run at interpreter- |
| 47 | shutdown. After calling :func:`unregister`, *func* is guaranteed not to be |
| 48 | called when the interpreter shuts down. |
| 49 | |
| 50 | .. versionadded:: 3.0 |
| 51 | |
| 52 | |
| 53 | .. seealso:: |
| 54 | |
| 55 | Module :mod:`readline` |
| 56 | Useful example of :mod:`atexit` to read and write :mod:`readline` history files. |
| 57 | |
| 58 | |
| 59 | .. _atexit-example: |
| 60 | |
| 61 | :mod:`atexit` Example |
| 62 | --------------------- |
| 63 | |
| 64 | The following simple example demonstrates how a module can initialize a counter |
| 65 | from a file when it is imported and save the counter's updated value |
| 66 | automatically when the program terminates without relying on the application |
| 67 | making an explicit call into this module at termination. :: |
| 68 | |
| 69 | try: |
| 70 | _count = int(open("/tmp/counter").read()) |
| 71 | except IOError: |
| 72 | _count = 0 |
| 73 | |
| 74 | def incrcounter(n): |
| 75 | global _count |
| 76 | _count = _count + n |
| 77 | |
| 78 | def savecounter(): |
| 79 | open("/tmp/counter", "w").write("%d" % _count) |
| 80 | |
| 81 | import atexit |
| 82 | atexit.register(savecounter) |
| 83 | |
| 84 | Positional and keyword arguments may also be passed to :func:`register` to be |
| 85 | passed along to the registered function when it is called:: |
| 86 | |
| 87 | def goodbye(name, adjective): |
| 88 | print 'Goodbye, %s, it was %s to meet you.' % (name, adjective) |
| 89 | |
| 90 | import atexit |
| 91 | atexit.register(goodbye, 'Donny', 'nice') |
| 92 | |
| 93 | # or: |
| 94 | atexit.register(goodbye, adjective='nice', name='Donny') |
| 95 | |
| 96 | Usage as a decorator:: |
| 97 | |
| 98 | import atexit |
| 99 | |
| 100 | @atexit.register |
| 101 | def goodbye(): |
| 102 | print "You are now leaving the Python sector." |
| 103 | |
| 104 | This obviously only works with functions that don't take arguments. |
| 105 | |