autoreload

%autoreload

IPython extension to reload modules before executing user code.

autoreload reloads modules automatically before entering the execution of code typed at the IPython prompt.

This makes for example the following workflow possible:

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, %autoreload now

Reload all modules (except those excluded by %aimport) automatically now.

%autoreload 0, %autoreload off

Disable automatic reloading.

%autoreload 1, %autoreload explicit

Reload all modules imported with %aimport every time before executing the Python code typed.

%autoreload 2, %autoreload all

Reload all modules (except those excluded by %aimport) every time before executing the Python code typed.

%autoreload 3, %autoreload complete

Same as 2/all, but also adds any new objects in the module. See unit test at IPython/extensions/tests/test_autoreload.py::test_autoload_newly_added_objects

Adding --print or -p to the %autoreload line will print autoreload activity to standard out. --log or -l will do it to the log at INFO level; both can be used simultaneously.

%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, bar

Import modules ‘foo’, ‘bar’ and mark them to be autoreloaded for %autoreload 1

%aimport -foo

Mark module ‘foo’ to not be autoreloaded.

Import Conflict Resolution

In %autoreload 3 mode, the extension tracks from X import Y style imports and intelligently resolves conflicts when the same name is imported multiple ways.

Import tracking occurs after successful code execution, ensuring that only valid imports are tracked. This approach handles edge cases such as:

  • Importing a name that doesn’t initially exist in a module, then adding that name to the module and importing it again

  • Conflicts between aliased imports (from X import Y as Z) and direct imports (from X import Z)

When conflicts occur:

  • If you first do from X import Y as Z then later from X import Z, the extension will switch to reloading Z instead of Y under the name Z.

  • Similarly, if you first do from X import Z then later from X import Y as Z, the extension will switch to reloading Y as Z instead of the original Z.

  • The most recent successful import always takes precedence in conflict resolution.

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.

  • While comparing Enum and Flag, the ‘is’ Identity Operator is used (even in the case ‘==’ has been used (Similar to the ‘None’ keyword)).

  • Reloading a module, or importing the same module by a different name, creates new Enums. These may look the same, but are not.