Fred Drake | c19425d | 2000-06-28 15:07:31 +0000 | [diff] [blame] | 1 | \section{\module{atexit} --- |
Fred Drake | 3c62d9e | 2000-07-06 04:51:04 +0000 | [diff] [blame] | 2 | Exit handlers} |
Fred Drake | c19425d | 2000-06-28 15:07:31 +0000 | [diff] [blame] | 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 | |
Fred Drake | 30f76ff | 2000-06-30 16:06:19 +0000 | [diff] [blame] | 9 | \versionadded{2.0} |
Fred Drake | be93a83 | 2000-06-28 22:07:55 +0000 | [diff] [blame] | 10 | |
Fred Drake | c19425d | 2000-06-28 15:07:31 +0000 | [diff] [blame] | 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 |
Fred Drake | 3c62d9e | 2000-07-06 04:51:04 +0000 | [diff] [blame] | 17 | \function{os._exit()} is called. |
Fred Drake | c19425d | 2000-06-28 15:07:31 +0000 | [diff] [blame] | 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 | |
Skip Montanaro | 0915165 | 2000-07-05 23:11:26 +0000 | [diff] [blame] | 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 | |
Fred Drake | c19425d | 2000-06-28 15:07:31 +0000 | [diff] [blame] | 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 | |
Fred Drake | 1c4efad | 2000-09-09 03:25:11 +0000 | [diff] [blame] | 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 | |
Fred Drake | c19425d | 2000-06-28 15:07:31 +0000 | [diff] [blame] | 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} |
Fred Drake | 2c2068c | 2003-04-08 17:46:53 +0000 | [diff] [blame] | 75 | |
| 76 | Positional and keyword arguments may also be passed to |
| 77 | \function{register()} to be passed along to the registered function |
| 78 | when it is called: |
| 79 | |
| 80 | \begin{verbatim} |
| 81 | def goodbye(name, adjective): |
| 82 | print 'Goodbye, %s, it was %s to meet you.' % (name, adjective) |
| 83 | |
| 84 | import atexit |
| 85 | atexit.register(goodbye, 'Donny', 'nice') |
| 86 | |
| 87 | # or: |
| 88 | atexit.register(goodbye, adjective='nice', name='Donny') |
| 89 | \end{verbatim} |