diff --git a/Doc/library/imp.rst b/Doc/library/imp.rst --- a/Doc/library/imp.rst +++ b/Doc/library/imp.rst @@ -166,16 +166,19 @@ This module provides an interface to the redefine the objects imported from it --- one way around this is to re-execute the :keyword:`from` statement, another is to use :keyword:`import` and qualified names (*module*.*name*) instead. If a module instantiates instances of a class, reloading the module that defines the class does not affect the method definitions of the instances --- they continue to use the old class definition. The same is true for derived classes. + .. deprecated:: 3.4 + Use :func:`importlib.reload` instead. + The following functions are conveniences for handling :pep:`3147` byte-compiled file paths. .. versionadded:: 3.2 .. function:: cache_from_source(path, debug_override=None) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -110,16 +110,79 @@ Functions Invalidate the internal caches of finders stored at :data:`sys.meta_path`. If a finder implements ``invalidate_caches()`` then it will be called to perform the invalidation. This function should be called if any modules are created/installed while your program is running to guarantee all finders will notice the new module's existence. .. versionadded:: 3.3 +.. function:: reload(module) + + Reload a previously imported *module*. The argument must be a module object, so + it must have been successfully imported before. This is useful if you have + edited the module source file using an external editor and want to try out the + new version without leaving the Python interpreter. The return value is the + module object (the same as the *module* argument). + + When :func:`.reload` is executed: + + * Python modules' code is recompiled and the module-level code reexecuted, + defining a new set of objects which are bound to names in the module's + dictionary. The ``init`` function of extension modules is not called a second + time. + + * As with all other objects in Python the old objects are only reclaimed after + their reference counts drop to zero. + + * The names in the module namespace are updated to point to any new or changed + objects. + + * Other references to the old objects (such as names external to the module) are + not rebound to refer to the new objects and must be updated in each namespace + where they occur if that is desired. + + There are a number of other caveats: + + If a module is syntactically correct but its initialization fails, the first + :keyword:`import` statement for it does not bind its name locally, but does + store a (partially initialized) module object in ``sys.modules``. To reload the + module you must first :keyword:`import` it again (this will bind the name to the + partially initialized module object) before you can :func:`reload` it. + + When a module is reloaded, its dictionary (containing the module's global + variables) is retained. Redefinitions of names will override the old + definitions, so this is generally not a problem. If the new version of a module + does not define a name that was defined by the old version, the old definition + remains. This feature can be used to the module's advantage if it maintains a + global table or cache of objects --- with a :keyword:`try` statement it can test + for the table's presence and skip its initialization if desired:: + + try: + cache + except NameError: + cache = {} + + It is legal though generally not very useful to reload built-in or dynamically + loaded modules, except for :mod:`sys`, :mod:`__main__` and :mod:`__builtin__`. + In many cases, however, extension modules are not designed to be initialized + more than once, and may fail in arbitrary ways when reloaded. + + If a module imports objects from another module using :keyword:`from` ... + :keyword:`import` ..., calling :func:`reload` for the other module does not + redefine the objects imported from it --- one way around this is to re-execute + the :keyword:`from` statement, another is to use :keyword:`import` and qualified + names (*module*.*name*) instead. + + If a module instantiates instances of a class, reloading the module that defines + the class does not affect the method definitions of the instances --- they + continue to use the old class definition. The same is true for derived classes. + + .. versionadded:: 3.4 + :mod:`importlib.abc` -- Abstract base classes related to import --------------------------------------------------------------- .. module:: importlib.abc :synopsis: Abstract base classes related to import The :mod:`importlib.abc` module contains all of the core abstract base classes diff --git a/Lib/imp.py b/Lib/imp.py --- a/Lib/imp.py +++ b/Lib/imp.py @@ -244,17 +244,19 @@ def find_module(name, path=None): encoding = tokenize.detect_encoding(file.readline)[0] file = open(file_path, mode, encoding=encoding) return file, file_path, (suffix, mode, type_) _RELOADING = {} def reload(module): - """Reload the module and return it. + """**DEPRECATED** + + Reload the module and return it. The module must have been successfully imported before. """ if not module or type(module) != type(sys): raise TypeError("reload() argument must be module") name = module.__name__ if name not in sys.modules: diff --git a/Lib/importlib/__init__.py b/Lib/importlib/__init__.py --- a/Lib/importlib/__init__.py +++ b/Lib/importlib/__init__.py @@ -6,16 +6,17 @@ # Until bootstrapping is complete, DO NOT import any modules that attempt # to import importlib._bootstrap (directly or indirectly). Since this # partially initialised package would be present in sys.modules, those # modules would get an uninitialised copy of the source version, instead # of a fully initialised version (either the frozen one or the one # initialised below if the frozen one is not available). import _imp # Just the builtin component, NOT the full Python module import sys +import types try: import _frozen_importlib as _bootstrap except ImportError: from . import _bootstrap _bootstrap._setup(sys, _imp) else: # importlib._bootstrap is the built-in import, ensure we don't create @@ -85,8 +86,38 @@ def import_module(name, package=None): if name.startswith('.'): if not package: raise TypeError("relative imports require the 'package' argument") for character in name: if character != '.': break level += 1 return _bootstrap._gcd_import(name[level:], package, level) + + +_RELOADING = {} + +def reload(module): + """Reload the module and return it. + + The module must have been successfully imported before. + + """ + if not module or type(module) != types.ModuleType: + raise TypeError("reload() argument must be module") + name = module.__name__ + if name not in sys.modules: + msg = "module {} not in sys.modules" + raise ImportError(msg.format(name), name=name) + if name in _RELOADING: + return _RELOADING[name] + _RELOADING[name] = module + try: + parent_name = name.rpartition('.')[0] + if parent_name and parent_name not in sys.modules: + msg = "parent {!r} not in sys.modules" + raise ImportError(msg.format(parentname), name=parent_name) + return module.__loader__.load_module(name) + finally: + try: + del _RELOADING[name] + except KeyError: + pass diff --git a/Lib/test/test_importlib/test_api.py b/Lib/test/test_importlib/test_api.py --- a/Lib/test/test_importlib/test_api.py +++ b/Lib/test/test_importlib/test_api.py @@ -146,16 +146,44 @@ class FindLoaderTests(unittest.TestCase) self.assertEqual((name, path), importlib.find_loader(name, path)) def test_nothing(self): # None is returned upon failure to find a loader. self.assertIsNone(importlib.find_loader('nevergoingtofindthismodule')) +class ReloadTests(unittest.TestCase): + + """Very basic tests to make sure that importlib.reload() operates just like + reload().""" + + def test_source(self): + # XXX (ncoghlan): It would be nice to use test.support.CleanImport + # here, but that breaks because the os module registers some + # handlers in copy_reg on import. Since CleanImport doesn't + # revert that registration, the module is left in a broken + # state after reversion. Reinitialising the module contents + # and just reverting os.environ to its previous state is an OK + # workaround + with support.EnvironmentVarGuard(): + import os + imp.reload(os) + + def test_extension(self): + with support.CleanImport('time'): + import time + imp.reload(time) + + def test_builtin(self): + with support.CleanImport('marshal'): + import marshal + imp.reload(marshal) + + class InvalidateCacheTests(unittest.TestCase): def test_method_called(self): # If defined the method should be called. class InvalidatingNullFinder: def __init__(self, *ignored): self.called = False def find_module(self, *args):