wrapt 2.1.0rc1__cp313-cp313t-macosx_11_0_arm64.whl

wrapt/importer.py

@@ -0,0 +1,332 @@
+"""This module implements a post import hook mechanism styled after what is
+described in PEP-369. Note that it doesn't cope with modules being reloaded.
+
+"""
+
+import importlib.metadata
+import sys
+import threading
+from importlib.util import find_spec
+from typing import Callable, Dict, List
+
+from .__wrapt__ import BaseObjectProxy
+
+# The dictionary registering any post import hooks to be triggered once
+# the target module has been imported. Once a module has been imported
+# and the hooks fired, the list of hooks recorded against the target
+# module will be truncated but the list left in the dictionary. This
+# acts as a flag to indicate that the module had already been imported.
+
+_post_import_hooks: Dict[str, List[Callable]] = {}
+_post_import_hooks_init = False
+_post_import_hooks_lock = threading.RLock()
+
+# Register a new post import hook for the target module name. This
+# differs from the PEP-369 implementation in that it also allows the
+# hook function to be specified as a string consisting of the name of
+# the callback in the form 'module:function'. This will result in a
+# proxy callback being registered which will defer loading of the
+# specified module containing the callback function until required.
+
+
+def _create_import_hook_from_string(name):
+    def import_hook(module):
+        module_name, function = name.split(":")
+        attrs = function.split(".")
+        __import__(module_name)
+        callback = sys.modules[module_name]
+        for attr in attrs:
+            callback = getattr(callback, attr)
+        return callback(module)
+
+    return import_hook
+
+
+def register_post_import_hook(hook, name):
+    """
+    Register a post import hook for the target module `name`. The `hook`
+    function will be called once the module is imported and will be passed the
+    module as argument. If the module is already imported, the `hook` will be
+    called immediately. If you also want to defer loading of the module containing
+    the `hook` function until required, you can specify the `hook` as a string in
+    the form 'module:function'. This will result in a proxy hook function being
+    registered which will defer loading of the specified module containing the
+    callback function until required.
+    """
+
+    # Create a deferred import hook if hook is a string name rather than
+    # a callable function.
+
+    if isinstance(hook, str):
+        hook = _create_import_hook_from_string(hook)
+
+    with _post_import_hooks_lock:
+        # Automatically install the import hook finder if it has not already
+        # been installed.
+
+        global _post_import_hooks_init
+
+        if not _post_import_hooks_init:
+            _post_import_hooks_init = True
+            sys.meta_path.insert(0, ImportHookFinder())
+
+        # Check if the module is already imported. If not, register the hook
+        # to be called after import.
+
+        module = sys.modules.get(name, None)
+
+        if module is None:
+            _post_import_hooks.setdefault(name, []).append(hook)
+
+    # If the module is already imported, we fire the hook right away. Note that
+    # the hook is called outside of the lock to avoid deadlocks if code run as a
+    # consequence of calling the module import hook in turn triggers a separate
+    # thread which tries to register an import hook.
+
+    if module is not None:
+        hook(module)
+
+
+# Register post import hooks defined as package entry points.
+
+
+def _create_import_hook_from_entrypoint(entrypoint):
+    def import_hook(module):
+        entrypoint_value = entrypoint.value.split(":")
+        module_name = entrypoint_value[0]
+        __import__(module_name)
+        callback = sys.modules[module_name]
+
+        if len(entrypoint_value) > 1:
+            attrs = entrypoint_value[1].split(".")
+            for attr in attrs:
+                callback = getattr(callback, attr)
+        return callback(module)
+
+    return import_hook
+
+
+def discover_post_import_hooks(group):
+    """
+    Discover and register post import hooks defined as package entry points
+    in the specified `group`. The group should be a string that matches the
+    entry point group name used in the package metadata.
+    """
+
+    try:
+        # Python 3.10+ style with select parameter
+        entrypoints = importlib.metadata.entry_points(group=group)
+    except TypeError:
+        # Python 3.8-3.9 style that returns a dict
+        entrypoints = importlib.metadata.entry_points().get(group, ())
+
+    for entrypoint in entrypoints:
+        callback = entrypoint.load()  # Use the loaded callback directly
+        register_post_import_hook(callback, entrypoint.name)
+
+
+# Indicate that a module has been loaded. Any post import hooks which
+# were registered against the target module will be invoked. If an
+# exception is raised in any of the post import hooks, that will cause
+# the import of the target module to fail.
+
+
+def notify_module_loaded(module):
+    """
+    Notify that a `module` has been loaded and invoke any post import hooks
+    registered against the module. If the module is not registered, this
+    function does nothing.
+    """
+
+    name = getattr(module, "__name__", None)
+
+    with _post_import_hooks_lock:
+        hooks = _post_import_hooks.pop(name, ())
+
+    # Note that the hook is called outside of the lock to avoid deadlocks if
+    # code run as a consequence of calling the module import hook in turn
+    # triggers a separate thread which tries to register an import hook.
+
+    for hook in hooks:
+        hook(module)
+
+
+# A custom module import finder. This intercepts attempts to import
+# modules and watches out for attempts to import target modules of
+# interest. When a module of interest is imported, then any post import
+# hooks which are registered will be invoked.
+
+
+class _ImportHookLoader:
+
+    def load_module(self, fullname):
+        module = sys.modules[fullname]
+        notify_module_loaded(module)
+
+        return module
+
+
+class _ImportHookChainedLoader(BaseObjectProxy):
+
+    def __init__(self, loader):
+        super(_ImportHookChainedLoader, self).__init__(loader)
+
+        if hasattr(loader, "load_module"):
+            self.__self_setattr__("load_module", self._self_load_module)
+        if hasattr(loader, "create_module"):
+            self.__self_setattr__("create_module", self._self_create_module)
+        if hasattr(loader, "exec_module"):
+            self.__self_setattr__("exec_module", self._self_exec_module)
+
+    def _self_set_loader(self, module):
+        # Set module's loader to self.__wrapped__ unless it's already set to
+        # something else. Import machinery will set it to spec.loader if it is
+        # None, so handle None as well. The module may not support attribute
+        # assignment, in which case we simply skip it. Note that we also deal
+        # with __loader__ not existing at all. This is to future proof things
+        # due to proposal to remove the attribute as described in the GitHub
+        # issue at https://github.com/python/cpython/issues/77458. Also prior
+        # to Python 3.3, the __loader__ attribute was only set if a custom
+        # module loader was used. It isn't clear whether the attribute still
+        # existed in that case or was set to None.
+
+        class UNDEFINED:
+            pass
+
+        if getattr(module, "__loader__", UNDEFINED) in (None, self):
+            try:
+                module.__loader__ = self.__wrapped__
+            except AttributeError:
+                pass
+
+        if (
+            getattr(module, "__spec__", None) is not None
+            and getattr(module.__spec__, "loader", None) is self
+        ):
+            module.__spec__.loader = self.__wrapped__
+
+    def _self_load_module(self, fullname):
+        module = self.__wrapped__.load_module(fullname)
+        self._self_set_loader(module)
+        notify_module_loaded(module)
+
+        return module
+
+    # Python 3.4 introduced create_module() and exec_module() instead of
+    # load_module() alone. Splitting the two steps.
+
+    def _self_create_module(self, spec):
+        return self.__wrapped__.create_module(spec)
+
+    def _self_exec_module(self, module):
+        self._self_set_loader(module)
+        self.__wrapped__.exec_module(module)
+        notify_module_loaded(module)
+
+
+class ImportHookFinder:
+
+    def __init__(self):
+        self.in_progress = {}
+
+    def find_module(self, fullname, path=None):
+        # If the module being imported is not one we have registered
+        # post import hooks for, we can return immediately. We will
+        # take no further part in the importing of this module.
+
+        with _post_import_hooks_lock:
+            if fullname not in _post_import_hooks:
+                return None
+
+        # When we are interested in a specific module, we will call back
+        # into the import system a second time to defer to the import
+        # finder that is supposed to handle the importing of the module.
+        # We set an in progress flag for the target module so that on
+        # the second time through we don't trigger another call back
+        # into the import system and cause a infinite loop.
+
+        if fullname in self.in_progress:
+            return None
+
+        self.in_progress[fullname] = True
+
+        # Now call back into the import system again.
+
+        try:
+            # For Python 3 we need to use find_spec().loader
+            # from the importlib.util module. It doesn't actually
+            # import the target module and only finds the
+            # loader. If a loader is found, we need to return
+            # our own loader which will then in turn call the
+            # real loader to import the module and invoke the
+            # post import hooks.
+
+            loader = getattr(find_spec(fullname), "loader", None)
+
+            if loader and not isinstance(loader, _ImportHookChainedLoader):
+                return _ImportHookChainedLoader(loader)
+
+        finally:
+            del self.in_progress[fullname]
+
+    def find_spec(self, fullname, path=None, target=None):
+        # Since Python 3.4, you are meant to implement find_spec() method
+        # instead of find_module() and since Python 3.10 you get deprecation
+        # warnings if you don't define find_spec().
+
+        # If the module being imported is not one we have registered
+        # post import hooks for, we can return immediately. We will
+        # take no further part in the importing of this module.
+
+        with _post_import_hooks_lock:
+            if fullname not in _post_import_hooks:
+                return None
+
+        # When we are interested in a specific module, we will call back
+        # into the import system a second time to defer to the import
+        # finder that is supposed to handle the importing of the module.
+        # We set an in progress flag for the target module so that on
+        # the second time through we don't trigger another call back
+        # into the import system and cause a infinite loop.
+
+        if fullname in self.in_progress:
+            return None
+
+        self.in_progress[fullname] = True
+
+        # Now call back into the import system again.
+
+        try:
+            # This should only be Python 3 so find_spec() should always
+            # exist so don't need to check.
+
+            spec = find_spec(fullname)
+            loader = getattr(spec, "loader", None)
+
+            if loader and not isinstance(loader, _ImportHookChainedLoader):
+                spec.loader = _ImportHookChainedLoader(loader)
+
+            return spec
+
+        finally:
+            del self.in_progress[fullname]
+
+
+# Decorator for marking that a function should be called as a post
+# import hook when the target module is imported.
+
+
+def when_imported(name):
+    """
+    Returns a decorator that registers the decorated function as a post import
+    hook for the module specified by `name`. The function will be called once
+    the module with the specified name is imported, and will be passed the
+    module as argument. If the module is already imported, the function will
+    be called immediately.
+    """
+
+    def register(hook):
+        register_post_import_hook(hook, name)
+        return hook
+
+    return register

wrapt/patches.py

@@ -0,0 +1,239 @@
+import inspect
+import sys
+
+from .__wrapt__ import FunctionWrapper
+
+# Helper functions for applying wrappers to existing functions.
+
+
+def resolve_path(target, name):
+    """
+    Resolves the dotted path supplied as `name` to an attribute on a target
+    object. The `target` can be a module, class, or instance of a class. If the
+    `target` argument is a string, it is assumed to be the name of a module,
+    which will be imported if necessary and then used as the target object.
+    Returns a tuple containing the parent object holding the attribute lookup
+    resolved to, the attribute name (path prefix removed if present), and the
+    original attribute value.
+    """
+
+    if isinstance(target, str):
+        __import__(target)
+        target = sys.modules[target]
+
+    parent = target
+
+    path = name.split(".")
+    attribute = path[0]
+
+    # We can't just always use getattr() because in doing
+    # that on a class it will cause binding to occur which
+    # will complicate things later and cause some things not
+    # to work. For the case of a class we therefore access
+    # the __dict__ directly. To cope though with the wrong
+    # class being given to us, or a method being moved into
+    # a base class, we need to walk the class hierarchy to
+    # work out exactly which __dict__ the method was defined
+    # in, as accessing it from __dict__ will fail if it was
+    # not actually on the class given. Fallback to using
+    # getattr() if we can't find it. If it truly doesn't
+    # exist, then that will fail.
+
+    def lookup_attribute(parent, attribute):
+        if inspect.isclass(parent):
+            for cls in inspect.getmro(parent):
+                if attribute in vars(cls):
+                    return vars(cls)[attribute]
+            else:
+                return getattr(parent, attribute)
+        else:
+            return getattr(parent, attribute)
+
+    original = lookup_attribute(parent, attribute)
+
+    for attribute in path[1:]:
+        parent = original
+        original = lookup_attribute(parent, attribute)
+
+    return (parent, attribute, original)
+
+
+def apply_patch(parent, attribute, replacement):
+    """
+    Convenience function for applying a patch to an attribute. Currently this
+    maps to the standard setattr() function, but in the future may be extended
+    to support more complex patching strategies.
+    """
+
+    setattr(parent, attribute, replacement)
+
+
+def wrap_object(target, name, factory, args=(), kwargs={}):
+    """
+    Wraps an object which is the attribute of a target object with a wrapper
+    object created by the `factory` function. The `target` can be a module,
+    class, or instance of a class. In the special case of `target` being a
+    string, it is assumed to be the name of a module, with the module being
+    imported if necessary and then used as the target object. The `name` is a
+    string representing the dotted path to the attribute. The `factory` function
+    should accept the original object and may accept additional positional and
+    keyword arguments which will be set by unpacking input arguments using
+    `*args` and `**kwargs` calling conventions. The factory function should
+    return a new object that will replace the original object.
+    """
+
+    (parent, attribute, original) = resolve_path(target, name)
+    wrapper = factory(original, *args, **kwargs)
+    apply_patch(parent, attribute, wrapper)
+
+    return wrapper
+
+
+# Function for applying a proxy object to an attribute of a class
+# instance. The wrapper works by defining an attribute of the same name
+# on the class which is a descriptor and which intercepts access to the
+# instance attribute. Note that this cannot be used on attributes which
+# are themselves defined by a property object.
+
+
+class AttributeWrapper:
+
+    def __init__(self, attribute, factory, args, kwargs):
+        self.attribute = attribute
+        self.factory = factory
+        self.args = args
+        self.kwargs = kwargs
+
+    def __get__(self, instance, owner):
+        value = instance.__dict__[self.attribute]
+        return self.factory(value, *self.args, **self.kwargs)
+
+    def __set__(self, instance, value):
+        instance.__dict__[self.attribute] = value
+
+    def __delete__(self, instance):
+        del instance.__dict__[self.attribute]
+
+
+def wrap_object_attribute(module, name, factory, args=(), kwargs={}):
+    """
+    Wraps an object which is the attribute of a class instance with a wrapper
+    object created by the `factory` function. It does this by patching the
+    class, not the instance, with a descriptor that intercepts access to the
+    instance attribute. The `module` can be a module, class, or instance of a
+    class. In the special case of `module` being a string, it is assumed to be
+    the name of a module, with the module being imported if necessary and then
+    used as the target object. The `name` is a string representing the dotted
+    path to the attribute. The `factory` function should accept the original
+    object and may accept additional positional and keyword arguments which will
+    be set by unpacking input arguments using `*args` and `**kwargs` calling
+    conventions. The factory function should return a new object that will
+    replace the original object.
+    """
+
+    path, attribute = name.rsplit(".", 1)
+    parent = resolve_path(module, path)[2]
+    wrapper = AttributeWrapper(attribute, factory, args, kwargs)
+    apply_patch(parent, attribute, wrapper)
+    return wrapper
+
+
+# Functions for creating a simple decorator using a FunctionWrapper,
+# plus short cut functions for applying wrappers to functions. These are
+# for use when doing monkey patching. For a more featured way of
+# creating decorators see the decorator decorator instead.
+
+
+def function_wrapper(wrapper):
+    """
+    Creates a decorator for wrapping a function with a `wrapper` function.
+    The decorator which is returned may also be applied to any other callable
+    objects such as lambda functions, methods, classmethods, and staticmethods,
+    or objects which implement the `__call__()` method. The `wrapper` function
+    should accept the `wrapped` function, `instance`, `args`, and `kwargs`,
+    arguments and return the result of calling the wrapped function or some
+    other appropriate value.
+    """
+
+    def _wrapper(wrapped, instance, args, kwargs):
+        target_wrapped = args[0]
+        if instance is None:
+            target_wrapper = wrapper
+        elif inspect.isclass(instance):
+            target_wrapper = wrapper.__get__(None, instance)
+        else:
+            target_wrapper = wrapper.__get__(instance, type(instance))
+        return FunctionWrapper(target_wrapped, target_wrapper)
+
+    return FunctionWrapper(wrapper, _wrapper)
+
+
+def wrap_function_wrapper(target, name, wrapper):
+    """
+    Wraps a function which is the attribute of a target object with a `wrapper`
+    function. The `target` can be a module, class, or instance of a class. In
+    the special case of `target` being a string, it is assumed to be the name
+    of a module, with the module being imported if necessary. The `name` is a
+    string representing the dotted path to the attribute. The `wrapper` function
+    should accept the `wrapped` function, `instance`, `args`, and `kwargs`
+    arguments, and would return the result of calling the wrapped attribute or
+    some other appropriate value.
+    """
+
+    return wrap_object(target, name, FunctionWrapper, (wrapper,))
+
+
+def patch_function_wrapper(target, name, enabled=None):
+    """
+    Creates a decorator which can be applied to a wrapper function, where the
+    wrapper function will be used to wrap a function which is the attribute of
+    a target object. The `target` can be a module, class, or instance of a class.
+    In the special case of `target` being a string, it is assumed to be the name
+    of a module, with the module being imported if necessary. The `name` is a
+    string representing the dotted path to the attribute. The `enabled`
+    argument can be a boolean or a callable that returns a boolean. When a
+    callable is provided, it will be called each time the wrapper is invoked to
+    determine if the wrapper function should be executed or whether the wrapped
+    function should be called directly. If `enabled` is not provided, the
+    wrapper is enabled by default.
+    """
+
+    def _wrapper(wrapper):
+        return wrap_object(target, name, FunctionWrapper, (wrapper, enabled))
+
+    return _wrapper
+
+
+def transient_function_wrapper(target, name):
+    """Creates a decorator that patches a target function with a wrapper
+    function, but only for the duration of the call that the decorator was
+    applied to. The `target` can be a module, class, or instance of a class.
+    In the special case of `target` being a string, it is assumed to be the name
+    of a module, with the module being imported if necessary. The `name` is a
+    string representing the dotted path to the attribute.
+    """
+
+    def _decorator(wrapper):
+        def _wrapper(wrapped, instance, args, kwargs):
+            target_wrapped = args[0]
+            if instance is None:
+                target_wrapper = wrapper
+            elif inspect.isclass(instance):
+                target_wrapper = wrapper.__get__(None, instance)
+            else:
+                target_wrapper = wrapper.__get__(instance, type(instance))
+
+            def _execute(wrapped, instance, args, kwargs):
+                (parent, attribute, original) = resolve_path(target, name)
+                replacement = FunctionWrapper(original, target_wrapper)
+                setattr(parent, attribute, replacement)
+                try:
+                    return wrapped(*args, **kwargs)
+                finally:
+                    setattr(parent, attribute, original)
+
+            return FunctionWrapper(target_wrapped, _execute)
+
+        return FunctionWrapper(wrapper, _wrapper)
+
+    return _decorator