Permalink
Browse files

DOC: extensions/autoreload: better extension module docstring

  • Loading branch information...
1 parent 7fd3f13 commit 632ea8f69dcf24f9580c00c46f3aac5dabe3a508 @pv committed Sep 18, 2011
Showing with 85 additions and 4 deletions.
  1. +85 −4 IPython/extensions/autoreload.py
@@ -1,11 +1,92 @@
"""
-IPython extension: autoreload modules before executing the next line
+``autoreload`` is an IPython extension that reloads modules
+automatically before executing the line of code typed.
-Try::
+This makes for example the following workflow possible:
- %autoreload?
+.. sourcecode:: ipython
+
+ In [1]: %load_ext autoreload
+
+ In [2]: %autoreload 2
+
+ In [3]: from foo import some_function
+
+ In [4]: some_function()
+ Out[4]: 42
+
+ In [5]: # open foo.py in an editor and change some_function to return 43
+
+ In [6]: some_function()
+ Out[6]: 43
+
+The module was reloaded without reloading it explicitly, and the
+object imported with ``from foo import ...`` was also updated.
+
+Usage
+=====
+
+The following magic commands are provided:
+
+``%autoreload``
+
+ Reload all modules (except those excluded by ``%aimport``)
+ automatically now.
+
+``%autoreload 0``
+
+ Disable automatic reloading.
+
+``%autoreload 1``
+
+ Reload all modules imported with ``%aimport`` every time before
+ executing the Python code typed.
+
+``%autoreload 2``
+
+ Reload all modules (except those excluded by ``%aimport``) every
+ time before executing the Python code typed.
+
+``%aimport``
+
+ List modules which are to be automatically imported or not to be imported.
+
+``%aimport foo``
+
+ Import module 'foo' and mark it to be autoreloaded for ``%autoreload 1``
+
+``%aimport -foo``
+
+ Mark module 'foo' to not be autoreloaded.
+
+Caveats
+=======
+
+Reloading Python modules in a reliable way is in general difficult,
+and unexpected things may occur. ``%autoreload`` tries to work around
+common pitfalls by replacing function code objects and parts of
+classes previously in the module with new versions. This makes the
+following things to work:
+
+- Functions and classes imported via 'from xxx import foo' are upgraded
+ to new versions when 'xxx' is reloaded.
+
+- Methods and properties of classes are upgraded on reload, so that
+ calling 'c.foo()' on an object 'c' created before the reload causes
+ the new code for 'foo' to be executed.
+
+Some of the known remaining caveats are:
+
+- Replacing code objects does not always succeed: changing a @property
+ in a class to an ordinary method or a method to a member variable
+ can cause problems (but in old objects only).
+
+- Functions that are removed (eg. via monkey-patching) from a module
+ before it is reloaded are not upgraded.
+
+- C extension modules cannot be reloaded, and so cannot be
+ autoreloaded.
-for documentation.
"""
# Pauli Virtanen <pav@iki.fi>, 2008.

0 comments on commit 632ea8f

Please sign in to comment.