summaryrefslogtreecommitdiffstats
path: root/Doc/library/atexit.rst
diff options
context:
space:
mode:
authorGeorg Brandl <georg@python.org>2007-08-15 14:28:22 (GMT)
committerGeorg Brandl <georg@python.org>2007-08-15 14:28:22 (GMT)
commit116aa62bf54a39697e25f21d6cf6799f7faa1349 (patch)
tree8db5729518ed4ca88e26f1e26cc8695151ca3eb3 /Doc/library/atexit.rst
parent739c01d47b9118d04e5722333f0e6b4d0c8bdd9e (diff)
downloadcpython-116aa62bf54a39697e25f21d6cf6799f7faa1349.zip
cpython-116aa62bf54a39697e25f21d6cf6799f7faa1349.tar.gz
cpython-116aa62bf54a39697e25f21d6cf6799f7faa1349.tar.bz2
Move the 3k reST doc tree in place.
Diffstat (limited to 'Doc/library/atexit.rst')
-rw-r--r--Doc/library/atexit.rst105
1 files changed, 105 insertions, 0 deletions
diff --git a/Doc/library/atexit.rst b/Doc/library/atexit.rst
new file mode 100644
index 0000000..94d750b
--- /dev/null
+++ b/Doc/library/atexit.rst
@@ -0,0 +1,105 @@
+
+:mod:`atexit` --- Exit handlers
+===============================
+
+.. module:: atexit
+ :synopsis: Register and execute cleanup functions.
+.. moduleauthor:: Skip Montanaro <skip@mojam.com>
+.. sectionauthor:: Skip Montanaro <skip@mojam.com>
+
+
+.. versionadded:: 2.0
+
+The :mod:`atexit` module defines functions to register and unregister cleanup
+functions. Functions thus registered are automatically executed upon normal
+interpreter termination.
+
+Note: the functions registered via this module are not called when the program
+is killed by a signal, when a Python fatal internal error is detected, or when
+:func:`os._exit` is called.
+
+
+.. function:: register(func[, *args[, **kargs]])
+
+ Register *func* as a function to be executed at termination. Any optional
+ arguments that are to be passed to *func* must be passed as arguments to
+ :func:`register`.
+
+ At normal program termination (for instance, if :func:`sys.exit` is called or
+ the main module's execution completes), all functions registered are called in
+ last in, first out order. The assumption is that lower level modules will
+ normally be imported before higher level modules and thus must be cleaned up
+ later.
+
+ If an exception is raised during execution of the exit handlers, a traceback is
+ printed (unless :exc:`SystemExit` is raised) and the exception information is
+ saved. After all exit handlers have had a chance to run the last exception to
+ be raised is re-raised.
+
+ .. versionchanged:: 2.6
+ This function now returns *func* which makes it possible to use it as a
+ decorator without binding the original name to ``None``.
+
+
+.. function:: unregister(func)
+
+ Remove a function *func* from the list of functions to be run at interpreter-
+ shutdown. After calling :func:`unregister`, *func* is guaranteed not to be
+ called when the interpreter shuts down.
+
+ .. versionadded:: 3.0
+
+
+.. seealso::
+
+ Module :mod:`readline`
+ Useful example of :mod:`atexit` to read and write :mod:`readline` history files.
+
+
+.. _atexit-example:
+
+:mod:`atexit` Example
+---------------------
+
+The following simple example demonstrates how a module can initialize a counter
+from a file when it is imported and save the counter's updated value
+automatically when the program terminates without relying on the application
+making an explicit call into this module at termination. ::
+
+ try:
+ _count = int(open("/tmp/counter").read())
+ except IOError:
+ _count = 0
+
+ def incrcounter(n):
+ global _count
+ _count = _count + n
+
+ def savecounter():
+ open("/tmp/counter", "w").write("%d" % _count)
+
+ import atexit
+ atexit.register(savecounter)
+
+Positional and keyword arguments may also be passed to :func:`register` to be
+passed along to the registered function when it is called::
+
+ def goodbye(name, adjective):
+ print 'Goodbye, %s, it was %s to meet you.' % (name, adjective)
+
+ import atexit
+ atexit.register(goodbye, 'Donny', 'nice')
+
+ # or:
+ atexit.register(goodbye, adjective='nice', name='Donny')
+
+Usage as a decorator::
+
+ import atexit
+
+ @atexit.register
+ def goodbye():
+ print "You are now leaving the Python sector."
+
+This obviously only works with functions that don't take arguments.
+