blob: 3d5c0147622011985c97483d000c2ce4f20dd75d [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`atexit` --- Exit handlers
2===============================
3
4.. module:: atexit
5 :synopsis: Register and execute cleanup functions.
Christian Heimes895627f2007-12-08 17:28:33 +00006.. moduleauthor:: Skip Montanaro <skip@pobox.com>
7.. sectionauthor:: Skip Montanaro <skip@pobox.com>
Georg Brandl116aa622007-08-15 14:28:22 +00008
9
Georg Brandl116aa622007-08-15 14:28:22 +000010The :mod:`atexit` module defines functions to register and unregister cleanup
11functions. Functions thus registered are automatically executed upon normal
Éric Araujofe1e2982011-07-29 18:04:24 +020012interpreter termination. The order in which the functions are called is not
13defined; if you have cleanup operations that depend on each other, you should
14wrap them in a function and register that one. This keeps :mod:`atexit` simple.
Georg Brandl116aa622007-08-15 14:28:22 +000015
16Note: the functions registered via this module are not called when the program
Georg Brandl7c4cad52010-10-14 06:43:22 +000017is killed by a signal not handled by Python, when a Python fatal internal error
18is detected, or when :func:`os._exit` is called.
Georg Brandl116aa622007-08-15 14:28:22 +000019
20
Georg Brandlb868a662009-04-02 02:56:10 +000021.. function:: register(func, *args, **kargs)
Georg Brandl116aa622007-08-15 14:28:22 +000022
23 Register *func* as a function to be executed at termination. Any optional
24 arguments that are to be passed to *func* must be passed as arguments to
Éric Araujoccddc472012-02-15 17:07:49 +010025 :func:`register`. It is possible to register the same function and arguments
26 more than once.
Georg Brandl116aa622007-08-15 14:28:22 +000027
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
Éric Araujoccddc472012-02-15 17:07:49 +010039 This function returns *func*, which makes it possible to use it as a
40 decorator.
Georg Brandl116aa622007-08-15 14:28:22 +000041
42
43.. function:: unregister(func)
44
Éric Araujoccddc472012-02-15 17:07:49 +010045 Remove *func* from the list of functions to be run at interpreter
Georg Brandl116aa622007-08-15 14:28:22 +000046 shutdown. After calling :func:`unregister`, *func* is guaranteed not to be
Éric Araujoccddc472012-02-15 17:07:49 +010047 called when the interpreter shuts down, even if it was registered more than
48 once. :func:`unregister` silently does nothing if *func* was not previously
49 registered.
Georg Brandl116aa622007-08-15 14:28:22 +000050
Georg Brandl116aa622007-08-15 14:28:22 +000051
52.. seealso::
53
54 Module :mod:`readline`
Georg Brandlb868a662009-04-02 02:56:10 +000055 Useful example of :mod:`atexit` to read and write :mod:`readline` history
56 files.
Georg Brandl116aa622007-08-15 14:28:22 +000057
58
59.. _atexit-example:
60
61:mod:`atexit` Example
62---------------------
63
64The following simple example demonstrates how a module can initialize a counter
65from a file when it is imported and save the counter's updated value
66automatically when the program terminates without relying on the application
67making an explicit call into this module at termination. ::
68
69 try:
Éric Araujoe4f6a802011-03-12 15:56:09 +010070 with open("/tmp/counter") as infile:
71 _count = int(infile.read())
Antoine Pitrou62ab10a02011-10-12 20:10:51 +020072 except FileNotFoundError:
Georg Brandl116aa622007-08-15 14:28:22 +000073 _count = 0
74
75 def incrcounter(n):
76 global _count
77 _count = _count + n
78
79 def savecounter():
Éric Araujoa3dd56b2011-03-11 17:42:48 +010080 with open("/tmp/counter", "w") as outfile:
81 outfile.write("%d" % _count)
Georg Brandl116aa622007-08-15 14:28:22 +000082
83 import atexit
84 atexit.register(savecounter)
85
86Positional and keyword arguments may also be passed to :func:`register` to be
87passed along to the registered function when it is called::
88
89 def goodbye(name, adjective):
Georg Brandl6911e3c2007-09-04 07:15:32 +000090 print('Goodbye, %s, it was %s to meet you.' % (name, adjective))
Georg Brandl116aa622007-08-15 14:28:22 +000091
92 import atexit
93 atexit.register(goodbye, 'Donny', 'nice')
94
95 # or:
96 atexit.register(goodbye, adjective='nice', name='Donny')
97
Christian Heimesd8654cf2007-12-02 15:22:16 +000098Usage as a :term:`decorator`::
Georg Brandl116aa622007-08-15 14:28:22 +000099
100 import atexit
101
102 @atexit.register
103 def goodbye():
Georg Brandl6911e3c2007-09-04 07:15:32 +0000104 print("You are now leaving the Python sector.")
Georg Brandl116aa622007-08-15 14:28:22 +0000105
Éric Araujoccddc472012-02-15 17:07:49 +0100106This only works with functions that can be called without arguments.