blob: c9775d1b6ddf673b503271fd22808507d2188c19 [file] [log] [blame]
Fred Drakec19425d2000-06-28 15:07:31 +00001\section{\module{atexit} ---
Fred Drake3c62d9e2000-07-06 04:51:04 +00002 Exit handlers}
Fred Drakec19425d2000-06-28 15:07:31 +00003
4\declaremodule{standard}{atexit}
5\moduleauthor{Skip Montanaro}{skip@mojam.com}
6\sectionauthor{Skip Montanaro}{skip@mojam.com}
7\modulesynopsis{Register and execute cleanup functions.}
8
Fred Drake30f76ff2000-06-30 16:06:19 +00009\versionadded{2.0}
Fred Drakebe93a832000-06-28 22:07:55 +000010
Fred Drakec19425d2000-06-28 15:07:31 +000011The \module{atexit} module defines a single function to register
12cleanup functions. Functions thus registered are automatically
13executed upon normal interpreter termination.
14
15Note: the functions registered via this module are not called when the program is killed by a
16signal, when a Python fatal internal error is detected, or when
Fred Drake3c62d9e2000-07-06 04:51:04 +000017\function{os._exit()} is called.
Fred Drakec19425d2000-06-28 15:07:31 +000018
19This is an alternate interface to the functionality provided by the
20\code{sys.exitfunc} variable.
21\withsubitem{(in sys)}{\ttindex{exitfunc}}
22
Skip Montanaro09151652000-07-05 23:11:26 +000023Note: This module is unlikely to work correctly when used with other code
24that sets \code{sys.exitfunc}. In particular, other core Python modules are
25free to use \module{atexit} without the programmer's knowledge. Authors who
26use \code{sys.exitfunc} should convert their code to use
27\module{atexit} instead. The simplest way to convert code that sets
28\code{sys.exitfunc} is to import \module{atexit} and register the function
29that had been bound to \code{sys.exitfunc}.
30
Fred Drakec19425d2000-06-28 15:07:31 +000031\begin{funcdesc}{register}{func\optional{, *args\optional{, **kargs}}}
32Register \var{func} as a function to be executed at termination. Any
33optional arguments that are to be passed to \var{func} must be passed
34as arguments to \function{register()}.
35
36At normal program termination (for instance, if
37\function{sys.exit()} is called or the main module's execution
38completes), all functions registered are called in last in, first out
39order. The assumption is that lower level modules will normally be
40imported before higher level modules and thus must be cleaned up
41later.
42\end{funcdesc}
43
44
Fred Drake1c4efad2000-09-09 03:25:11 +000045\begin{seealso}
46 \seemodule{readline}{Useful example of \module{atexit} to read and
47 write \refmodule{readline} history files.}
48\end{seealso}
49
50
Fred Drakec19425d2000-06-28 15:07:31 +000051\subsection{\module{atexit} Example \label{atexit-example}}
52
53The following simple example demonstrates how a module can initialize
54a counter from a file when it is imported and save the counter's
55updated value automatically when the program terminates without
56relying on the application making an explicit call into this module at
57termination.
58
59\begin{verbatim}
60try:
61 _count = int(open("/tmp/counter").read())
62except IOError:
63 _count = 0
64
65def incrcounter(n):
66 global _count
67 _count = _count + n
68
69def savecounter():
70 open("/tmp/counter", "w").write("%d" % _count)
71
72import atexit
73atexit.register(savecounter)
74\end{verbatim}
Fred Drake2c2068c2003-04-08 17:46:53 +000075
76Positional and keyword arguments may also be passed to
77\function{register()} to be passed along to the registered function
78when it is called:
79
80\begin{verbatim}
81def goodbye(name, adjective):
82 print 'Goodbye, %s, it was %s to meet you.' % (name, adjective)
83
84import atexit
85atexit.register(goodbye, 'Donny', 'nice')
86
87# or:
88atexit.register(goodbye, adjective='nice', name='Donny')
89\end{verbatim}