Doc/lib/libatexit.tex

   1 \section{\module{atexit} ---
   2          Exit handlers}
   3
   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
   9 \versionadded{2.0}
  10
  11 The \module{atexit} module defines a single function to register
  12 cleanup functions.  Functions thus registered are automatically
  13 executed upon normal interpreter termination.
  14
  15 Note: the functions registered via this module are not called when the program is killed by a
  16 signal, when a Python fatal internal error is detected, or when
  17 \function{os._exit()} is called.
  18
  19 This is an alternate interface to the functionality provided by the
  20 \code{sys.exitfunc} variable.
  21 \withsubitem{(in sys)}{\ttindex{exitfunc}}
  22
  23 Note: This module is unlikely to work correctly when used with other code
  24 that sets \code{sys.exitfunc}.  In particular, other core Python modules are
  25 free to use \module{atexit} without the programmer's knowledge.  Authors who
  26 use \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
  29 that had been bound to \code{sys.exitfunc}.
  30
  31 \begin{funcdesc}{register}{func\optional{, *args\optional{, **kargs}}}
  32 Register \var{func} as a function to be executed at termination.  Any
  33 optional arguments that are to be passed to \var{func} must be passed
  34 as arguments to \function{register()}.
  35
  36 At normal program termination (for instance, if
  37 \function{sys.exit()} is called or the main module's execution
  38 completes), all functions registered are called in last in, first out
  39 order.  The assumption is that lower level modules will normally be
  40 imported before higher level modules and thus must be cleaned up
  41 later.
  42
  43 If an exception is raised during execution of the exit handlers, a
  44 traceback is printed (unless \exception{SystemExit} is raised) and the
  45 exception information is saved.  After all exit handlers have had a
  46 chance to run the last exception to be raised is re-raised.
  47
  48 \versionchanged[This function now returns \var{func} which makes it
  49                 possible to use it as a decorator without binding the
  50                 original name to \code{None}]{2.6}
  51 \end{funcdesc}
  52
  53
  54 \begin{seealso}
  55   \seemodule{readline}{Useful example of \module{atexit} to read and
  56                        write \refmodule{readline} history files.}
  57 \end{seealso}
  58
  59
  60 \subsection{\module{atexit} Example \label{atexit-example}}
  61
  62 The following simple example demonstrates how a module can initialize
  63 a counter from a file when it is imported and save the counter's
  64 updated value automatically when the program terminates without
  65 relying on the application making an explicit call into this module at
  66 termination.
  67
  68 \begin{verbatim}
  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 \end{verbatim}
  84
  85 Positional and keyword arguments may also be passed to
  86 \function{register()} to be passed along to the registered function
  87 when it is called:
  88
  89 \begin{verbatim}
  90 def goodbye(name, adjective):
  91     print 'Goodbye, %s, it was %s to meet you.' % (name, adjective)
  92
  93 import atexit
  94 atexit.register(goodbye, 'Donny', 'nice')
  95
  96 # or:
  97 atexit.register(goodbye, adjective='nice', name='Donny')
  98 \end{verbatim}
  99
 100 Usage as a decorator:
 101
 102 \begin{verbatim}
 103 import atexit
 104
 105 @atexit.register
 106 def goodbye():
 107     print "You are now leaving the Python sector."
 108 \end{verbatim}
 109
 110 This obviously only works with functions that don't take arguments.