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 \end{funcdesc}
  43
  44
  45 \begin{seealso}
  46   \seemodule{readline}{Useful example of \module{atexit} to read and
  47                        write \refmodule{readline} history files.}
  48 \end{seealso}
  49
  50
  51 \subsection{\module{atexit} Example \label{atexit-example}}
  52
  53 The following simple example demonstrates how a module can initialize
  54 a counter from a file when it is imported and save the counter's
  55 updated value automatically when the program terminates without
  56 relying on the application making an explicit call into this module at
  57 termination.
  58
  59 \begin{verbatim}
  60 try:
  61     _count = int(open("/tmp/counter").read())
  62 except IOError:
  63     _count = 0
  64
  65 def incrcounter(n):
  66     global _count
  67     _count = _count + n
  68
  69 def savecounter():
  70     open("/tmp/counter", "w").write("%d" % _count)
  71
  72 import atexit
  73 atexit.register(savecounter)
  74 \end{verbatim}