@@ -123,6 +123,68 @@ This module provides an interface to the mechanisms used to implement the
123123 function does nothing.
124124
125125
126+ .. function :: reload(module)
127+
128+ Reload a previously imported *module *. The argument must be a module object, so
129+ it must have been successfully imported before. This is useful if you have
130+ edited the module source file using an external editor and want to try out the
131+ new version without leaving the Python interpreter. The return value is the
132+ module object (the same as the *module * argument).
133+
134+ When ``reload(module) `` is executed:
135+
136+ * Python modules' code is recompiled and the module-level code reexecuted,
137+ defining a new set of objects which are bound to names in the module's
138+ dictionary. The ``init `` function of extension modules is not called a second
139+ time.
140+
141+ * As with all other objects in Python the old objects are only reclaimed after
142+ their reference counts drop to zero.
143+
144+ * The names in the module namespace are updated to point to any new or changed
145+ objects.
146+
147+ * Other references to the old objects (such as names external to the module) are
148+ not rebound to refer to the new objects and must be updated in each namespace
149+ where they occur if that is desired.
150+
151+ There are a number of other caveats:
152+
153+ If a module is syntactically correct but its initialization fails, the first
154+ :keyword: `import ` statement for it does not bind its name locally, but does
155+ store a (partially initialized) module object in ``sys.modules ``. To reload the
156+ module you must first :keyword: `import ` it again (this will bind the name to the
157+ partially initialized module object) before you can :func: `reload ` it.
158+
159+ When a module is reloaded, its dictionary (containing the module's global
160+ variables) is retained. Redefinitions of names will override the old
161+ definitions, so this is generally not a problem. If the new version of a module
162+ does not define a name that was defined by the old version, the old definition
163+ remains. This feature can be used to the module's advantage if it maintains a
164+ global table or cache of objects --- with a :keyword: `try ` statement it can test
165+ for the table's presence and skip its initialization if desired::
166+
167+ try:
168+ cache
169+ except NameError:
170+ cache = {}
171+
172+ It is legal though generally not very useful to reload built-in or dynamically
173+ loaded modules, except for :mod: `sys `, :mod: `__main__ ` and :mod: `__builtin__ `.
174+ In many cases, however, extension modules are not designed to be initialized
175+ more than once, and may fail in arbitrary ways when reloaded.
176+
177+ If a module imports objects from another module using :keyword: `from ` ...
178+ :keyword: `import ` ..., calling :func: `reload ` for the other module does not
179+ redefine the objects imported from it --- one way around this is to re-execute
180+ the :keyword: `from ` statement, another is to use :keyword: `import ` and qualified
181+ names (*module *.*name*) instead.
182+
183+ If a module instantiates instances of a class, reloading the module that defines
184+ the class does not affect the method definitions of the instances --- they
185+ continue to use the old class definition. The same is true for derived classes.
186+
187+
126188The following constants with integer values, defined in this module, are used to
127189indicate the search result of :func: `find_module `.
128190
0 commit comments