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