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 |
Larry Hastings | 1191709 | 2012-07-14 18:20:37 -0700 | [diff] [blame] | 12 | interpreter termination. :mod:`atexit` runs these functions in the *reverse* |
| 13 | order in which they were registered; if you register ``A``, ``B``, and ``C``, |
| 14 | at interpreter termination time they will be run in the order ``C``, ``B``, |
| 15 | ``A``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 16 | |
Larry Hastings | 1191709 | 2012-07-14 18:20:37 -0700 | [diff] [blame] | 17 | **Note:** The functions registered via this module are not called when the |
| 18 | program is killed by a signal not handled by Python, when a Python fatal |
| 19 | internal error is detected, or when :func:`os._exit` is called. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 20 | |
| 21 | |
Georg Brandl | b868a66 | 2009-04-02 02:56:10 +0000 | [diff] [blame] | 22 | .. function:: register(func, *args, **kargs) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Éric Araujo | ccddc47 | 2012-02-15 17:07:49 +0100 | [diff] [blame] | 26 | :func:`register`. It is possible to register the same function and arguments |
| 27 | more than once. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 28 | |
| 29 | At normal program termination (for instance, if :func:`sys.exit` is called or |
| 30 | the main module's execution completes), all functions registered are called in |
| 31 | last in, first out order. The assumption is that lower level modules will |
| 32 | normally be imported before higher level modules and thus must be cleaned up |
| 33 | later. |
| 34 | |
| 35 | If an exception is raised during execution of the exit handlers, a traceback is |
| 36 | printed (unless :exc:`SystemExit` is raised) and the exception information is |
| 37 | saved. After all exit handlers have had a chance to run the last exception to |
| 38 | be raised is re-raised. |
| 39 | |
Éric Araujo | ccddc47 | 2012-02-15 17:07:49 +0100 | [diff] [blame] | 40 | This function returns *func*, which makes it possible to use it as a |
| 41 | decorator. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 42 | |
| 43 | |
| 44 | .. function:: unregister(func) |
| 45 | |
Éric Araujo | ccddc47 | 2012-02-15 17:07:49 +0100 | [diff] [blame] | 46 | Remove *func* from the list of functions to be run at interpreter |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 47 | shutdown. After calling :func:`unregister`, *func* is guaranteed not to be |
Éric Araujo | ccddc47 | 2012-02-15 17:07:49 +0100 | [diff] [blame] | 48 | called when the interpreter shuts down, even if it was registered more than |
| 49 | once. :func:`unregister` silently does nothing if *func* was not previously |
| 50 | registered. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 51 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 52 | |
| 53 | .. seealso:: |
| 54 | |
| 55 | Module :mod:`readline` |
Georg Brandl | b868a66 | 2009-04-02 02:56:10 +0000 | [diff] [blame] | 56 | Useful example of :mod:`atexit` to read and write :mod:`readline` history |
| 57 | files. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 58 | |
| 59 | |
| 60 | .. _atexit-example: |
| 61 | |
| 62 | :mod:`atexit` Example |
| 63 | --------------------- |
| 64 | |
| 65 | The following simple example demonstrates how a module can initialize a counter |
| 66 | from a file when it is imported and save the counter's updated value |
| 67 | automatically when the program terminates without relying on the application |
| 68 | making an explicit call into this module at termination. :: |
| 69 | |
| 70 | try: |
Petri Lehtinen | 3c75a48 | 2013-02-23 19:34:15 +0100 | [diff] [blame] | 71 | with open("counterfile") as infile: |
Éric Araujo | e4f6a80 | 2011-03-12 15:56:09 +0100 | [diff] [blame] | 72 | _count = int(infile.read()) |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 73 | except FileNotFoundError: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | _count = 0 |
| 75 | |
| 76 | def incrcounter(n): |
| 77 | global _count |
| 78 | _count = _count + n |
| 79 | |
| 80 | def savecounter(): |
Petri Lehtinen | 3c75a48 | 2013-02-23 19:34:15 +0100 | [diff] [blame] | 81 | with open("counterfile", "w") as outfile: |
Éric Araujo | a3dd56b | 2011-03-11 17:42:48 +0100 | [diff] [blame] | 82 | outfile.write("%d" % _count) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 83 | |
| 84 | import atexit |
| 85 | atexit.register(savecounter) |
| 86 | |
| 87 | Positional and keyword arguments may also be passed to :func:`register` to be |
| 88 | passed along to the registered function when it is called:: |
| 89 | |
| 90 | def goodbye(name, adjective): |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 91 | print('Goodbye, %s, it was %s to meet you.' % (name, adjective)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
| 93 | import atexit |
| 94 | atexit.register(goodbye, 'Donny', 'nice') |
| 95 | |
| 96 | # or: |
| 97 | atexit.register(goodbye, adjective='nice', name='Donny') |
| 98 | |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 99 | Usage as a :term:`decorator`:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 100 | |
| 101 | import atexit |
| 102 | |
| 103 | @atexit.register |
| 104 | def goodbye(): |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 105 | print("You are now leaving the Python sector.") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 106 | |
Éric Araujo | ccddc47 | 2012-02-15 17:07:49 +0100 | [diff] [blame] | 107 | This only works with functions that can be called without arguments. |