pyflyby 1.10.1__cp311-cp311-manylinux_2_24_x86_64.whl

pyflyby/_autoimp.py

@@ -0,0 +1,2229 @@
+# pyflyby/_autoimp.py.
+# Copyright (C) 2011, 2012, 2013, 2014, 2015, 2018, 2019, 2024 Karl Chen.
+# License: MIT http://opensource.org/licenses/MIT
+
+
+
+from __future__ import annotations, print_function
+
+import ast
+import builtins
+from   collections.abc          import Sequence
+import contextlib
+import copy
+
+from   pyflyby._file            import FileText, Filename
+from   pyflyby._flags           import CompilerFlags
+from   pyflyby._idents          import (BadDottedIdentifierError,
+                                        DottedIdentifier, brace_identifiers)
+from   pyflyby._importdb        import ImportDB
+from   pyflyby._importstmt      import Import
+from   pyflyby._log             import logger
+from   pyflyby._modules         import ModuleHandle
+from   pyflyby._parse           import (MatchAs, PythonBlock, _is_ast_str,
+                                        infer_compile_mode)
+
+from   six                      import reraise
+import sys
+import types
+from   typing                   import (Any, Dict, List, Optional, Set, Tuple,
+                                        Union)
+
+
+if sys.version_info >= (3, 13):
+    def f():
+        return sys._getframe().f_locals
+
+    FrameLocalsProxyType = type(f())
+else:
+    FrameLocalsProxyType = dict
+
+if sys.version_info >= (3, 12):
+    ATTRIBUTE_NAME = "value"
+else:
+    ATTRIBUTE_NAME = "s"
+
+if sys.version_info > (3, 11):
+    LOAD_SHIFT = 1
+else:
+    LOAD_SHIFT = 0
+
+
+if sys.version_info >= (3, 10):
+    from types import NoneType, EllipsisType
+else:
+    NoneType = type(None)
+    EllipsisType = type(Ellipsis)
+
+
+class _ClassScope(dict):
+    pass
+
+
+    def __repr__(self):
+        return "_ClassScope(" + repr(super()) + ")"
+
+
+_builtins2 = {"__file__": None}
+
+
+class ScopeStack(Sequence):
+    """
+    A stack of namespace scopes, as a tuple of ``dict`` s.
+
+    Each entry is a ``dict``.
+
+    Ordered from most-global to most-local.
+    Builtins are always included.
+    Duplicates are removed.
+    """
+
+    _cached_has_star_import = False
+
+    def __init__(self, arg, _class_delayed=None):
+        """
+        Interpret argument as a ``ScopeStack``.
+
+        :type arg:
+          ``ScopeStack``, ``dict``, ``list`` of ``dict``
+        :param arg:
+          Input namespaces
+        :rtype:
+          ``ScopeStack``
+        """
+        if isinstance(arg, ScopeStack):
+            scopes = list(arg._tup)
+        elif isinstance(arg, dict):
+            scopes = [arg]
+        elif isinstance(arg, (tuple, list)):
+            scopes = list(arg)
+        else:
+            raise TypeError(
+                "ScopeStack: expected a sequence of dicts; got a %s"
+                % (type(arg).__name__,))
+        if not len(scopes):
+            raise TypeError("ScopeStack: no scopes given")
+        if not all(isinstance(scope, (dict, FrameLocalsProxyType)) for scope in scopes):
+            raise TypeError("ScopeStack: Expected list of dict or FrameLocalsProxy objects; got a sequence of %r"
+                            % ([type(x).__name__ for x in scopes]))
+        scopes = [builtins.__dict__, _builtins2] + scopes
+        result = []
+        seen = set()
+        # Keep only unique items, checking uniqueness by object identity.
+        for scope in scopes:
+            if id(scope) in seen:
+                continue
+            seen.add(id(scope))
+            result.append(scope)
+        tup = tuple(result)
+        self._tup = tup
+
+        # class name definitions scope may need to be delayed.
+        # so we store them separately, and if they are present in methods def, we can readd them
+        if _class_delayed is None:
+            _class_delayed = {}
+        self._class_delayed = _class_delayed
+
+    def __contains__(self, item):
+        if isinstance(item, DottedIdentifier):
+            item = item.name
+        if isinstance(item, str):
+            for sub in self:
+                if item in sub.keys():
+                    return True
+
+        return False
+
+    def __getitem__(self, item):
+        if isinstance(item, slice):
+            return self.__class__(self._tup[item])
+        return self._tup[item]
+
+    def __len__(self):
+        return len(self._tup)
+
+    def _with_new_scope(
+        self,
+        *,
+        include_class_scopes: bool,
+        new_class_scope: bool,
+        unhide_classdef: bool,
+    ) -> ScopeStack:
+        """
+        Return a new ``ScopeStack`` with an additional empty scope.
+
+        :param include_class_scopes:
+          Whether to include previous scopes that are meant for ClassDefs.
+        :param new_class_scope:
+          Whether the new scope is for a ClassDef.
+        :param unhide_classdef:
+          Unhide class definitiion scope (when we enter a method)
+        :rtype:
+          ``ScopeStack``
+        """
+        if include_class_scopes:
+            scopes = tuple(self)
+        else:
+            scopes = tuple(s for s in self if not isinstance(s, _ClassScope))
+        new_scope: Union[_ClassScope, Dict[str, Any]]
+        if new_class_scope:
+            new_scope = _ClassScope()
+        else:
+            new_scope = {}
+        cls = type(self)
+        if unhide_classdef and self._class_delayed:
+            scopes = tuple([self._class_delayed]) + scopes
+        result = cls(scopes + (new_scope,), _class_delayed=self._class_delayed)
+        return result
+
+    def clone_top(self):
+        """
+        Return a new ``ScopeStack`` referencing the same namespaces as ``self``,
+        but cloning the topmost namespace (and aliasing the others).
+        """
+        scopes = list(self)
+        scopes[-1] = copy.copy(scopes[-1])
+        cls = type(self)
+        return cls(scopes)
+
+    def merged_to_two(self):
+        """
+        Return a 2-tuple of dicts.
+
+        These can be used for functions that take a ``globals`` and ``locals``
+        argument, such as ``eval``.
+
+        If there is only one entry, then return it twice.
+
+        If there are more than two entries, then create a new dict that merges
+        the more-global ones.  The most-local stack will alias the dict from
+        the existing ScopeStack.
+
+        :rtype:
+          ``tuple`` of (``dict``, ``dict``)
+        """
+        assert len(self) >= 1
+        if len(self) == 1:
+            return (self[0], self[0])
+        if len(self) == 2:
+            return tuple(self)
+        d = {}
+        for scope in self[:-1]:
+            d.update(scope)
+        # Return as a 2-tuple.  We don't cast the result to ScopeStack because
+        # it may add __builtins__ again, creating something of length 3.
+        return (d, self[-1])
+
+
+    def has_star_import(self) -> bool:
+        """
+        Return whether there are any star-imports in this ScopeStack.
+        Only relevant in AST-based static analysis mode.
+        """
+        if self._cached_has_star_import:
+            return True
+        if any('*' in scope for scope in self):
+            # There was a star import.  Cache that fact before returning.  We
+            # can cache a positive result because a star import can't be undone.
+            self._cached_has_star_import = True
+            return True
+        else:
+            # There was no star import yet.  We can't cache that fact because
+            # there might be a star import later.
+            return False
+
+    def __repr__(self):
+        scopes_reprs = [
+            "{:2}".format(i) + " : " + repr(namespace)
+            for i, namespace in enumerate(self)
+        ][1:]
+
+        return (
+            "<{class_name} object at 0x{hex_id} with namespaces: [\n".format(
+                class_name=self.__class__.__name__, hex_id=id(self)
+            )
+            + " 0 : {builtins namespace elided.}\n"
+            + "\n".join(scopes_reprs)
+            + "\n]>"
+        )
+
+
+def symbol_needs_import(fullname, namespaces):
+    """
+    Return whether ``fullname`` is a symbol that needs to be imported, given
+    the current namespace scopes.
+
+    A symbol needs importing if it is not previously imported or otherwise
+    assigned.  ``namespaces`` normally includes builtins and globals as well as
+    symbols imported/assigned locally within the scope.
+
+    If the user requested "foo.bar.baz", and we see that "foo.bar" exists
+    and is not a module, we assume nothing under foo.bar needs import.
+    This is intentional because (1) the import would not match what is
+    already in the namespace, and (2) we don't want to do call
+    getattr(foo.bar, "baz"), since that could invoke code that is slow or
+    has side effects.
+
+    :type fullname:
+      ``DottedIdentifier``
+    :param fullname:
+      Fully-qualified symbol name, e.g. "os.path.join".
+    :type namespaces:
+      ``list`` of ``dict``
+    :param namespaces:
+      Stack of namespaces to search for existing items.
+    :rtype:
+      ``bool``
+    :return:
+      ``True`` if ``fullname`` needs import, else ``False``
+    """
+    namespaces = ScopeStack(namespaces)
+    fullname = DottedIdentifier(fullname)
+    partial_names = fullname.prefixes[::-1]
+    # Iterate over local scopes.
+    for ns_idx, ns in reversed(list(enumerate(namespaces))):
+        # Iterate over partial names: "foo.bar.baz.quux", "foo.bar.baz", ...
+        for partial_name in partial_names:
+            # Check if this partial name was imported/assigned in this
+            # scope.  In the common case, there will only be one namespace
+            # in the namespace stack, i.e. the user globals.
+            try:
+                var = ns[str(partial_name)]
+            except KeyError:
+                continue
+            # If we're doing static analysis where we also care about which
+            # imports are unused, then mark the used ones now.
+            if isinstance(var, _UseChecker):
+                var.used = True
+            # Suppose the user accessed fullname="foo.bar.baz.quux" and
+            # suppose we see "foo.bar" was imported (or otherwise assigned) in
+            # the scope vars (most commonly this means it was imported
+            # globally).  Let's check if foo.bar already has a "baz".
+            prefix_len = len(partial_name.parts)
+            suffix_parts = fullname.parts[prefix_len:]
+            pname = str(partial_name)
+            for part in suffix_parts:
+                # Check if the var so far is a module -- in fact that it's
+                # *the* module of a given name.  That is, for var ==
+                # foo.bar.baz, check if var is sys.modules['foo.bar.baz'].  We
+                # used to just check if isinstance(foo.bar.baz, ModuleType).
+                # However, that naive check is wrong for these situations:
+                #   - A module that contains an import of anything other than a
+                #     submodule with its exact name.  For example, suppose
+                #     foo.bar contains 'import sqlalchemy'.
+                #     foo.bar.sqlalchemy is of ModuleType, but that doesn't
+                #     mean that we could import foo.bar.sqlalchemy.orm.
+                #     Similar case if foo.bar contains 'from . import baz as
+                #     baz2'.  Mistaking these doesn't break much, but might as
+                #     well avoid an unnecessary import attempt.
+                #   - A "proxy module".  Suppose foo.bar replaces itself with
+                #     an object with a __getattr__, using
+                #     'sys.modules[__name__] = ...'  Submodules are still
+                #     importable, but sys.modules['foo.bar'] would not be of
+                #     type ModuleType.
+                if var is not sys.modules.get(pname, object()):
+                    # The variable is not a module.  (If this came from a
+                    # local assignment then ``var`` will just be "None"
+                    # here to indicate we know it was assigned but don't
+                    # know about its type.)  Thus nothing under it needs
+                    # import.
+                    logger.debug("symbol_needs_import(%r): %s is in namespace %d (under %r) and not a global module, so it doesn't need import", fullname, pname, ns_idx, partial_name)
+                    return False
+                try:
+                    var = getattr(var, part)
+                except AttributeError:
+                    # We saw that "foo.bar" is imported, and is a module, but
+                    # it does not have a "baz" attribute.  Thus, as far as we
+                    # know so far, foo.bar.baz requires import.  But continue
+                    # on to the next scope.
+                    logger.debug("symbol_needs_import(%r): %s is a module in namespace %d (under %r), but has no %r attribute", fullname, pname, ns_idx, partial_name, part)
+                    break # continue outer loop
+                pname = "%s.%s" % (pname, part)
+            else:
+                # We saw that "foo.bar" is imported, and checked that
+                # foo.bar has an attribute "baz", which has an
+                # attribute "quux" - so foo.bar.baz.quux does not need
+                # to be imported.
+                assert pname == str(fullname)
+                logger.debug("symbol_needs_import(%r): found it in namespace %d (under %r), so it doesn't need import", fullname, ns_idx, partial_name)
+                return False
+    # We didn't find any scope that defined the name.  Therefore it needs
+    # import.
+    logger.debug(
+        "symbol_needs_import(%r): no match found in namespaces %s; it needs import",
+        fullname,
+        namespaces,
+    )
+    return True
+
+
+class _UseChecker:
+    """
+    An object that can check whether it was used.
+    """
+
+    used: bool = False
+    name: str
+    source: str
+    lineno: int
+
+    def __init__(self, name: str, source: str, lineno: int):
+        self.name = name
+        self.source = source # generally an Import
+        self.lineno = lineno
+        logger.debug("Create _UseChecker : %r", self)
+
+    def __repr__(self):
+        return f"<{type(self).__name__}: name:{self.name!r} source:{self.source!r} lineno:{self.lineno} used:{self.used}>"
+
+
+class _MissingImportFinder:
+    """
+    A helper class to be used only by `_find_missing_imports_in_ast`.
+
+    This class visits every AST node and collects symbols that require
+    importing.  A symbol requires importing if it is not already imported or
+    otherwise defined/assigned in this scope.
+
+    For attributes like "foo.bar.baz", we need to be more sophisticated:
+
+    Suppose the user imports "foo.bar" and then accesses "foo.bar.baz.quux".
+    Baz may be already available just by importing foo.bar, or it may require
+    further import.  We decide as follows.  If foo.bar is not a module, then
+    we assume whatever's under it can't be imported.  If foo.bar is a module
+    but does not have a 'baz' attribute, then it does require import.
+
+    """
+
+    scopestack: ScopeStack
+    _lineno: Optional[int]
+    missing_imports: List[Tuple[Optional[int], DottedIdentifier]]
+    parse_docstrings: bool
+    unused_imports: Optional[List[Tuple[int, str]]]
+    _deferred_load_checks: list[tuple[str, ScopeStack, Optional[int]]]
+
+    def __init__(self, scopestack, *, find_unused_imports:bool, parse_docstrings:bool):
+        """
+        Construct the AST visitor.
+
+        :type scopestack:
+          `ScopeStack`
+        :param scopestack:
+          Initial scope stack.
+        """
+        # Create a stack of namespaces.  The caller should pass in a list that
+        # includes the globals dictionary.  ScopeStack() will make sure this
+        # includes builtins.
+        _scopestack = ScopeStack(scopestack)
+
+        # Add an empty namespace to the stack.  This facilitates adding stuff
+        # to scopestack[-1] without ever modifying user globals.
+        self.scopestack = _scopestack._with_new_scope(
+            include_class_scopes=False, new_class_scope=False, unhide_classdef=False
+        )
+
+        # Create data structure to hold the result.
+        # missing_imports is a list of (lineno, DottedIdentifier) tuples.
+        self.missing_imports = []
+
+        # unused_imports is a list of (lineno, Import) tuples, if enabled.
+        self.unused_imports = [] if find_unused_imports else None
+
+        self.parse_docstrings = parse_docstrings
+
+        # Function bodies that we need to check after defining names in this
+        # function scope.
+        self._deferred_load_checks = []
+
+        # Whether we're currently in a FunctionDef.
+        self._in_FunctionDef = False
+        # Current lineno.
+        self._lineno = None
+        self._in_class_def = 0
+
+    def find_missing_imports(self, node):
+        self._scan_node(node)
+        return sorted(set(imp for lineno,imp in self.missing_imports))
+
+    def _scan_node(self, node):
+        oldscopestack = self.scopestack
+        myglobals = self.scopestack[-1]
+        try:
+            self.visit(node)
+            self._finish_deferred_load_checks()
+            assert self.scopestack is oldscopestack
+            assert self.scopestack[-1] is myglobals
+        finally:
+            self.scopestack = oldscopestack
+
+    def scan_for_import_issues(self, codeblock: PythonBlock):
+        assert isinstance(codeblock, PythonBlock)
+        # See global `scan_for_import_issues`
+        if not isinstance(codeblock, PythonBlock):
+            codeblock = PythonBlock(codeblock)
+        node = codeblock.ast_node
+        self._scan_node(node)
+        # Get missing imports now, before handling docstrings.  We don't want
+        # references in doctests to be noted as missing-imports.  For now we
+        # just let the code accumulate into self.missing_imports and ignore
+        # the result.
+        logger.debug("unused: %r", self.unused_imports)
+        missing_imports = sorted(self.missing_imports)
+        if self.parse_docstrings and self.unused_imports is not None:
+            doctest_blocks = codeblock.get_doctests()
+            # Parse each doctest.  Don't report missing imports in doctests,
+            # but do treat existing imports as 'used' if they are used in
+            # doctests.  The linenos are currently wrong, but we don't use
+            # them so it's not important to fix.
+            for block in doctest_blocks:
+                # There are doctests.  Parse them.
+                # Doctest blocks inherit the global scope after parsing all
+                # non-doctest code, and each doctest block individually creates a new
+                # scope (not shared between doctest blocks).
+                # TODO: Theoretically we should clone the entire scopestack,
+                # not just add a new scope, in case the doctest uses 'global'.
+                # Currently we don't support the 'global' keyword anyway so
+                # this doesn't matter yet, and it's uncommon to use 'global'
+                # in a doctest, so this is low priority to fix.
+                with self._NewScopeCtx(check_unused_imports=False):
+                    self._scan_node(block.ast_node)
+            # Find literal brace identifiers like "... `Foo` ...".
+            # TODO: Do this inline: (1) faster; (2) can use proper scope of vars
+            # Once we do that, use _check_load() with new args
+            # check_missing_imports=False, check_unused_imports=True
+            literal_brace_identifiers = set(
+                iden
+                for f in codeblock.string_literals()
+                for iden in brace_identifiers(getattr(f, ATTRIBUTE_NAME))
+            )
+            if literal_brace_identifiers:
+                for ident in literal_brace_identifiers:
+                    try:
+                        ident = DottedIdentifier(ident)
+                    except BadDottedIdentifierError:
+                        continue
+                    symbol_needs_import(ident, self.scopestack)
+        self._scan_unused_imports()
+        logger.debug("missing: %s, unused: %s", missing_imports, self.unused_imports)
+        return missing_imports, self.unused_imports
+
+    def visit(self, node):
+        """
+        Visit a node.
+
+        :type node:
+          ``ast.AST`` or ``list`` of ``ast.AST``
+        """
+        # Modification of ast.NodeVisitor.visit().  Support list inputs.
+        logger.debug("_MissingImportFinder.visit(%r)", node)
+        lineno = getattr(node, 'lineno', None)
+        if lineno:
+            self._lineno = lineno
+        if isinstance(node, list):
+            for item in node:
+                self.visit(item)
+        elif isinstance(node, ast.AST):
+            method = 'visit_' + node.__class__.__name__
+            if not hasattr(self, method):
+                logger.debug(
+                    "_MissingImportFinder has no method %r, using generic_visit", method
+                )
+            if hasattr(self, method):
+                visitor = getattr(self, method)
+            else:
+                logger.debug("No method `%s`, using `generic_visit`", method)
+                visitor = self.generic_visit
+            return visitor(node)
+        else:
+            raise TypeError("unexpected %s" % (type(node).__name__,))
+
+    def generic_visit(self, node):
+        """
+        Generic visitor that visits all of the node's field values, in the
+        order declared by ``node._fields``.
+
+        Called if no explicit visitor function exists for a node.
+        """
+        # Modification of ast.NodeVisitor.generic_visit: recurse to visit()
+        # even for lists, and be more explicit about type checking.
+        for field, value in ast.iter_fields(node):
+            if isinstance(value, ast.AST):
+                self.visit(value)
+            elif isinstance(value, list):
+                if all(isinstance(v, str) for v in value):
+                    pass
+                elif all(isinstance(v, ast.AST) for v in value):
+                    self.visit(value)
+                else:
+                    raise TypeError(
+                        "unexpected %s" % (", ".join(type(v).__name__ for v in value))
+                    )
+            elif isinstance(
+                value, (int, float, complex, str, NoneType, bytes, EllipsisType)
+            ):
+                pass
+            else:
+                raise TypeError(
+                    "unexpected %s for %s.%s"
+                    % (type(value).__name__, type(node).__name__, field))
+
+
+    @contextlib.contextmanager
+    def _NewScopeCtx(
+        self,
+        include_class_scopes=False,
+        new_class_scope=False,
+        unhide_classdef=False,
+        check_unused_imports=True,
+    ):
+        """
+        Context manager that temporarily pushes a new empty namespace onto the
+        stack of namespaces.
+        """
+        prev_scopestack = self.scopestack
+        new_scopestack = prev_scopestack._with_new_scope(
+            include_class_scopes=include_class_scopes,
+            new_class_scope=new_class_scope,
+            unhide_classdef=unhide_classdef,
+        )
+        self.scopestack = new_scopestack
+        try:
+            yield
+        finally:
+            logger.debug("throwing last scope from scopestack: %r", new_scopestack[-1])
+            for name, use_checker in new_scopestack[-1].items():
+                if use_checker and use_checker.used == False and check_unused_imports:
+                    logger.debug(
+                        "unused checker %r scopestack_depth %r",
+                        use_checker,
+                        len(self.scopestack),
+                    )
+                    self.unused_imports.append((use_checker.lineno, use_checker.source))
+            assert self.scopestack is new_scopestack
+            self.scopestack = prev_scopestack
+
+    @contextlib.contextmanager
+    def _UpScopeCtx(self):
+        """
+        Context manager that temporarily moves up one in the scope stack
+        """
+        if len(self.scopestack) < 2:
+            raise ValueError("There must be at least two scopes on the stack to move up a scope.")
+        prev_scopestack = self.scopestack
+        new_scopestack = prev_scopestack[:-1]
+        try:
+            self.scopestack = new_scopestack
+            yield
+        finally:
+            assert self.scopestack is new_scopestack
+            self.scopestack = prev_scopestack
+
+    def visit_Assign(self, node):
+        # Visit an assignment statement (lhs = rhs).  This implementation of
+        # visit_Assign is just like the generic one, but we make sure we visit
+        # node.value (RHS of assignment operator), then node.targets (LHS of
+        # assignment operator).  The default would have been to visit LHS,
+        # then RHS.  The reason we need to visit RHS first is the following.
+        # If the code is 'foo = foo + 1', we want to first process the Load
+        # for foo (RHS) before we process the Store for foo (LHS).  If we
+        # visited LHS then RHS, we would have a bug in the following sample
+        # code:
+        #    from bar import foo  # L1
+        #    foo = foo + 1        # L2
+        # The good RHS-then-LHS visit-order would see the Load('foo') on L2,
+        # understand that it got used before the Store('foo') overwrote it.
+        # The bad LHS-then-RHS visit-order would visit Store('foo') on L2, and
+        # think that foo was never referenced before it was overwritten, and
+        # therefore think that the 'import foo' on L1 could be removed.
+        self.visit(node.value)
+        self.visit(node.targets)
+        self._visit__all__(node)
+
+    def _visit__all__(self, node):
+        if self._in_FunctionDef:
+            return
+        if (len(node.targets) == 1 and isinstance(node.targets[0], ast.Name)
+            and node.targets[0].id == '__all__'):
+            if not isinstance(node.value, (ast.List, ast.Tuple)):
+                logger.warning("Don't know how to handle __all__ as (%s)" % node.value)
+                return
+            if not all(_is_ast_str(e) for e in node.value.elts):
+                logger.warning("Don't know how to handle __all__ with list elements other than str")
+                return
+            for e in node.value.elts:
+                if sys.version_info > (3,10):
+                    self._visit_Load_defered_global(e.value)
+                else:
+                    self._visit_Load_defered_global(e.s)
+
+    def visit_ClassDef(self, node):
+        logger.debug("visit_ClassDef(%r)", node)
+        if sys.version_info > (3,12):
+            # we don't visit type_params, so autoimport won't work yet for type annotations
+            assert node._fields == ('name', 'bases', 'keywords', 'body', 'decorator_list', 'type_params'), node._fields
+        else:
+            assert node._fields == ('name', 'bases', 'keywords', 'body', 'decorator_list'), node._fields
+        self.visit(node.bases)
+        self.visit(node.decorator_list)
+        # The class's name is only visible to others (not to the body to the
+        # class), but is accessible in the methods themselves. See https://github.com/deshaw/pyflyby/issues/147
+        self.visit(node.keywords)
+
+        # we only care about the first defined class,
+        # we don't detect issues with nested classes.
+        if self._in_class_def == 0:
+            self.scopestack._class_delayed[node.name] = None
+        with self._NewScopeCtx(new_class_scope=True):
+            self._in_class_def += 1
+            self._visit_Store(node.name)
+            self.visit(node.body)
+            self._in_class_def -= 1
+        assert self._in_class_def >= 0
+        self._remove_from_missing_imports(node.name)
+        self._visit_Store(node.name)
+
+    def visit_AsyncFunctionDef(self, node):
+        return self.visit_FunctionDef(node)
+
+    def visit_FunctionDef(self, node):
+        # Visit a function definition.
+        #   - Visit args and decorator list normally.
+        #   - Visit function body in a special mode where we defer checking
+        #     loads until later, and don't load names from the parent ClassDef
+        #     scope.
+        #   - Store the name in the current scope (but not visibly to
+        #     args/decorator_list).
+        if sys.version_info > (3, 12):
+            # we don't visit type_params, so autoimport won't work yet for type annotations
+            assert node._fields ==  ('name', 'args', 'body', 'decorator_list', 'returns', 'type_comment', 'type_params'), node._fields
+        else:
+            assert node._fields ==  ('name', 'args', 'body', 'decorator_list', 'returns', 'type_comment'), node._fields
+        with self._NewScopeCtx(include_class_scopes=True):
+            # we want `__class__` to only be defined in
+            # methods and not class body
+            if self._in_class_def:
+                self.scopestack[-1]["__class__"] = None  # we just need to to be defined
+            self.visit(node.decorator_list)
+            self.visit(node.args)
+            if node.returns:
+                self.visit(node.returns)
+            self._visit_typecomment(node.type_comment)
+            old_in_FunctionDef = self._in_FunctionDef
+            self._in_FunctionDef = True
+            with self._NewScopeCtx(unhide_classdef=True):
+                if not self._in_class_def:
+                    self._visit_Store(node.name)
+                self.visit(node.body)
+            self._in_FunctionDef = old_in_FunctionDef
+        self._visit_Store(node.name)
+
+    def visit_Lambda(self, node):
+        # Like FunctionDef, but without the decorator_list or name.
+        assert node._fields == ('args', 'body'), node._fields
+        with self._NewScopeCtx(include_class_scopes=True):
+            self.visit(node.args)
+            old_in_FunctionDef = self._in_FunctionDef
+            self._in_FunctionDef = True
+            with self._NewScopeCtx():
+                self.visit(node.body)
+            self._in_FunctionDef = old_in_FunctionDef
+
+    def _visit_typecomment(self, typecomment: str) -> None:
+        """
+        Warning, when a type comment the node is a string, not an ast node.
+        We also get two types of type comments:
+
+
+        The signature one just after a function definition
+
+            def foo(a):
+                # type: int -> None
+                pass
+
+        And the variable annotation ones:
+
+            def foo(a #type: int
+                ):
+                pass
+
+        ast parse  "func_type" mode only support the first one.
+
+        """
+        if typecomment is None:
+            return
+        node: Union[ast.Module, ast.FunctionType]
+        if '->' in typecomment:
+            node = ast.parse(typecomment, mode='func_type')
+        else:
+            node = ast.parse(typecomment)
+
+        self.visit(node)
+
+    def visit_arguments(self, node) -> None:
+        assert node._fields == ('posonlyargs', 'args', 'vararg', 'kwonlyargs', 'kw_defaults', 'kwarg', 'defaults'), node._fields
+        # Argument/parameter list.  Note that the defaults should be
+        # considered "Load"s from the upper scope, and the argument names are
+        # "Store"s in the function scope.
+
+        # E.g. consider:
+        #    def f(x=y, y=x): pass
+        # Both x and y should be considered undefined (unless they were indeed
+        # defined before the def).
+        # We assume visit_arguments is always called from a _NewScopeCtx
+        # context
+        with self._UpScopeCtx():
+            self.visit(node.defaults)
+            for i in node.kw_defaults:
+                if i:
+                    self.visit(i)
+        # Store arg names.
+        self.visit(node.args)
+        self.visit(node.kwonlyargs)
+        self.visit(node.posonlyargs)
+        # may be None.
+        if node.vararg:
+            self.visit(node.vararg)
+        else:
+            self._visit_Store(node.vararg)
+        if node.kwarg:
+            self.visit(node.kwarg)
+        else:
+            self._visit_Store(node.kwarg)
+
+    def visit_ExceptHandler(self, node) -> None:
+        assert node._fields == ('type', 'name', 'body')
+        if node.type:
+            self.visit(node.type)
+        if node.name:
+            self._visit_Store(node.name)
+        self.visit(node.body)
+
+    def visit_Dict(self, node):
+        assert node._fields == ('keys', 'values')
+        # In Python 3, keys can be None, indicating a ** expression
+        for key in node.keys:
+            if key:
+                self.visit(key)
+        self.visit(node.values)
+
+    def visit_comprehension(self, node):
+        # Visit a "comprehension" node, which is a component of list
+        # comprehensions and generator expressions.
+        self.visit(node.iter)
+        def visit_target(target):
+            if isinstance(target, ast.Name):
+                self._visit_Store(target.id)
+            elif isinstance(target, (ast.Tuple, ast.List)):
+                for elt in target.elts:
+                    visit_target(elt)
+            else:
+                # Unusual stuff like:
+                #   [f(x) for x[0] in mylist]
+                #   [f(x) for x.foo in mylist]
+                #   [f(x) for x.foo[0].foo in mylist]
+                self.visit(target)
+        visit_target(node.target)
+        self.visit(node.ifs)
+
+    def visit_ListComp(self, node):
+        # Visit a list comprehension node.
+        # This is basically the same as the generic visit, except that we
+        # visit the comprehension node(s) before the elt node.
+        # (generic_visit() would visit the elt first, because that comes first
+        # in ListComp._fields).
+        # For Python2, we intentionally don't enter a new scope here, because
+        # a list comprehensive _does_ leak variables out of its scope (unlike
+        # generator expressions).
+        # For Python3, we do need to enter a new scope here.
+        with self._NewScopeCtx(include_class_scopes=True):
+            self.visit(node.generators)
+            self.visit(node.elt)
+
+    def visit_DictComp(self, node):
+        # Visit a dict comprehension node.
+        # This is similar to the generic visit, except:
+        #  - We visit the comprehension node(s) before the elt node.
+        #  - We create a new scope for the variables.
+        # We do enter a new scope.  A dict comprehension
+        # does _not_ leak variables out of its scope (unlike py2 list
+        # comprehensions).
+        with self._NewScopeCtx(include_class_scopes=True):
+            self.visit(node.generators)
+            self.visit(node.key)
+            self.visit(node.value)
+
+    def visit_SetComp(self, node):
+        # Visit a set comprehension node.
+        # We do enter a new scope.  A set comprehension
+        # does _not_ leak variables out of its scope (unlike py2 list
+        # comprehensions).
+        with self._NewScopeCtx(include_class_scopes=True):
+            self.visit(node.generators)
+            self.visit(node.elt)
+
+    def visit_GeneratorExp(self, node):
+        # Visit a generator expression node.
+        # We do enter a new scope.  A generator
+        # expression does _not_ leak variables out of its scope (unlike py2
+        # list comprehensions).
+        with self._NewScopeCtx(include_class_scopes=True):
+            self.visit(node.generators)
+            self.visit(node.elt)
+
+    def visit_ImportFrom(self, node):
+        modulename = "." * node.level + (node.module or "")
+        logger.debug("visit_ImportFrom(%r, ...)", modulename)
+        for alias_node in node.names:
+            self.visit_alias(alias_node, modulename)
+
+    def visit_alias(self, node, modulename=None):
+        # Visit an import alias node.
+        # TODO: Currently we treat 'import foo' the same as if the user did
+        # 'foo = 123', i.e. we treat it as a black box (non-module).  This is
+        # to avoid actually importing it yet.  But this means we won't know
+        # whether foo.bar is available so we won't auto-import it.  Maybe we
+        # should give up on not importing it and just import it in a scratch
+        # namespace, so we can check.
+        self._visit_StoreImport(node, modulename)
+        self.generic_visit(node)
+
+    if sys.version_info >= (3,10):
+        def visit_match_case(self, node:ast.match_case):
+            logger.debug("visit_match_case(%r)", node)
+            return self.generic_visit(node)
+
+        def visit_Match(self, node:ast.Match):
+            logger.debug("visit_Match(%r)", node)
+            return self.generic_visit(node)
+
+        def visit_MatchMapping(self, node:ast.MatchMapping):
+            logger.debug("visit_MatchMapping(%r)", node)
+            return self.generic_visit(node)
+
+        def visit_MatchAs(self, node:MatchAs):
+            logger.debug("visit_MatchAs(%r)", node)
+            if node.name is None:
+                return
+            isinstance(node.name, str), node.name
+            return self._visit_Store(node.name)
+
+    def visit_Call(self, node:ast.Call):
+        logger.debug("visit_Call(%r)", node)
+        return self.generic_visit(node)
+
+    def visit_Pass(self, node:ast.Pass):
+        logger.debug("visit_Pass(%r)", node)
+        return self.generic_visit(node)
+
+    def visit_Constant(self, node:ast.Constant):
+        logger.debug("visit_Constant(%r)", node)
+        return self.generic_visit(node)
+
+    def visit_Module(self, node:ast.Module):
+        logger.debug("visit_Module(%r)", node)
+        return self.generic_visit(node)
+
+    def visit_Expr(self, node:ast.Expr):
+        logger.debug("visit_Expr(%r)", node)
+        return self.generic_visit(node)
+
+
+    def visit_Name(self, node):
+        logger.debug("visit_Name(%r)", node.id)
+        self._visit_fullname(node.id, node.ctx)
+
+    def visit_arg(self, node):
+        assert node._fields == ('arg', 'annotation', 'type_comment'), node._fields
+        if node.annotation:
+            self.visit(node.annotation)
+        # Treat it like a Name node would from Python 2
+        self._visit_fullname(node.arg, ast.Param())
+        self._visit_typecomment(node.type_comment)
+
+    def visit_Attribute(self, node):
+        name_revparts = []
+        n = node
+        while isinstance(n, ast.Attribute):
+            name_revparts.append(n.attr)
+            n = n.value
+        if not isinstance(n, ast.Name):
+            # Attribute of a non-symbol, e.g. (a+b).c
+            # We do nothing about "c", but we do recurse on (a+b) since those
+            # may have symbols we care about.
+            self.generic_visit(node)
+            return
+        name_revparts.append(n.id)
+        name_parts = name_revparts[::-1]
+        fullname = ".".join(name_parts)
+        logger.debug("visit_Attribute(%r): fullname=%r, ctx=%r", node.attr, fullname, node.ctx)
+        self._visit_fullname(fullname, node.ctx)
+
+    def _visit_fullname(self, fullname, ctx):
+        if isinstance(ctx, (ast.Store, ast.Param)):
+            self._visit_Store(fullname)
+        elif isinstance(ctx, ast.Load):
+            self._visit_Load(fullname)
+
+    def _visit_StoreImport(self, node, modulename):
+        name = node.asname or node.name
+        logger.debug("_visit_StoreImport(asname=%r, name=%r)", node.asname, node.name)
+        is_star = node.name == "*"
+        if is_star:
+            logger.debug("Got star import: line %s: 'from %s import *'",
+                         self._lineno, modulename)
+        if not node.asname and not is_star:
+            # Handle leading prefixes so we don't think they're unused
+            for prefix in DottedIdentifier(node.name).prefixes[:-1]:
+                self._visit_Store(str(prefix), None)
+        if self.unused_imports is None or is_star or modulename == "__future__":
+            value = None
+        else:
+            imp = Import.from_split((modulename, node.name, name))
+            logger.debug("_visit_StoreImport(): imp = %r", imp)
+            # Keep track of whether we've used this import.
+            value = _UseChecker(name, imp, self._lineno)
+        self._visit_Store(name, value)
+
+    def _visit_Store(self, fullname: str, value: Optional[_UseChecker] = None):
+        """
+        Visit a Store action, check for unused import
+        and add current value to the last scope.
+        """
+        assert isinstance(value, (_UseChecker, type(None)))
+        logger.debug("_visit_Store(%r)", fullname)
+        if fullname is None:
+            return
+        scope = self.scopestack[-1]
+        if isinstance(fullname, ast.arg):
+            fullname = fullname.arg
+        if self.unused_imports is not None:
+            if fullname != '*':
+                # If we're storing "foo.bar.baz = 123", then "foo" and
+                # "foo.bar" have now been used and the import should not be
+                # removed.
+                for ancestor in DottedIdentifier(fullname).prefixes[:-1]:
+                    if symbol_needs_import(ancestor, self.scopestack):
+                        m = (self._lineno, DottedIdentifier(fullname, scope_info=self._get_scope_info()))
+                        if m not in self.missing_imports:
+                            self.missing_imports.append(m)
+            # If we're redefining something, and it has not been used, then
+            # record it as unused.
+            oldvalue = scope.get(fullname)
+            if isinstance(oldvalue, _UseChecker) and not oldvalue.used:
+                logger.debug("Adding to unused %s", oldvalue)
+                self.unused_imports.append((oldvalue.lineno, oldvalue.source))
+        scope[fullname] = value
+
+    def _remove_from_missing_imports(self, fullname):
+        for missing_import in self.missing_imports:
+            # If it was defined inside a class method, then it wouldn't have been added to
+            # the missing imports anyways (except in that case of annotations)
+            # See the following tests:
+            # - tests.test_autoimp.test_method_reference_current_class
+            # - tests.test_autoimp.test_find_missing_imports_class_name_1
+            # - tests.test_autoimp.test_scan_for_import_issues_class_defined_after_use
+            scopestack = missing_import[1].scope_info['scopestack']
+            in_class_scope = isinstance(scopestack[-1], _ClassScope)
+            inside_class = missing_import[1].scope_info.get('_in_class_def')
+            if missing_import[1].startswith(fullname):
+                if in_class_scope or not inside_class:
+                    self.missing_imports.remove(missing_import)
+
+    def _get_scope_info(self):
+        return {
+            "scopestack": self.scopestack,
+            "_in_class_def": self._in_class_def,
+        }
+
+    def visit_Delete(self, node):
+        scope = self.scopestack[-1]
+        for target in node.targets:
+            if isinstance(target, ast.Name):
+                # 'del foo'
+                if target.id not in scope:
+                    # 'del x' without 'x' in current scope.  Should we warn?
+                    continue
+                del scope[target.id]
+            elif isinstance(target, ast.Attribute):
+                # 'del foo.bar.baz', 'del foo().bar', etc
+                # We ignore the 'del ...bar' part and just visit the
+                # left-hand-side of the delattr.  We need to do this explicitly
+                # instead of relying on a generic_visit on ``node`` itself.
+                # Reason: We want visit_Attribute to process a getattr for
+                # 'foo.bar'.
+                self.visit(target.value)
+            else:
+                # 'del foo.bar[123]' (ast.Subscript), etc.
+                # We can generically-visit the entire target node here.
+                self.visit(target)
+        # Don't call generic_visit(node) here.  Reason: We already visit the
+        # parts above, if relevant.
+
+    def _visit_Load_defered_global(self, fullname:str):
+        """
+        Some things will be resolved in global scope later.
+        """
+        assert isinstance(fullname, str), fullname
+        logger.debug("_visit_Load_defered_global(%r)", fullname)
+        if symbol_needs_import(fullname, self.scopestack):
+            data = (fullname, self.scopestack, self._lineno)
+            self._deferred_load_checks.append(data)
+
+
+    def _visit_Load_defered(self, fullname):
+        logger.debug("_visit_Load_defered(%r)", fullname)
+        if symbol_needs_import(fullname, self.scopestack):
+            data = (fullname, self.scopestack.clone_top(), self._lineno)
+            self._deferred_load_checks.append(data)
+
+    def _visit_Load_immediate(self, fullname):
+        logger.debug("_visit_Load_immediate(%r)", fullname)
+        self._check_load(fullname, self.scopestack, self._lineno)
+
+
+
+    def _visit_Load(self, fullname):
+        logger.debug("_visit_Load(%r)", fullname)
+        if self._in_FunctionDef:
+            self._visit_Load_defered(fullname)
+            # We're in a FunctionDef.  We need to defer checking whether this
+            # references undefined names.  The reason is that globals (or
+            # stores in a parent function scope) may be stored later.
+            # For example, bar() is defined later after the body of foo(), but
+            # still available to foo() when it is called:
+            #    def foo():
+            #        return bar()
+            #    def bar():
+            #        return 42
+            #    foo()
+            # To support this, we clone the top of the scope stack and alias
+            # the other scopes in the stack.  Later stores in the same scope
+            # shouldn't count, e.g. x should be considered undefined in the
+            # following example:
+            #    def foo():
+            #        print x
+            #        x = 1
+            # On the other hand, we intentionally alias the other scopes
+            # rather than cloning them, because the point is to allow them to
+            # be modified until we do the check at the end.
+            self._visit_Load_defered(fullname)
+
+        else:
+            # We're not in a FunctionDef.  Deferring would give us the same
+            # result; we do the check now to avoid the overhead of cloning the
+            # stack.
+            self._visit_Load_immediate(fullname)
+
+    def _check_load(self, fullname, scopestack, lineno):
+        """
+        Check if the symbol needs import.  (As a side effect, if the object
+        is a _UseChecker, this will mark it as used.
+
+        TODO: It would be
+        better to refactor symbol_needs_import so that it just returns the
+        object it found, and we mark it as used here.)
+        """
+        fullname = DottedIdentifier(fullname, scope_info=self._get_scope_info())
+        if symbol_needs_import(fullname, scopestack) and not scopestack.has_star_import():
+            if (lineno, fullname) not in self.missing_imports:
+                self.missing_imports.append((lineno, fullname))
+
+    def _finish_deferred_load_checks(self):
+        for fullname, scopestack, lineno in self._deferred_load_checks:
+            self._check_load(fullname, scopestack, lineno)
+        self._deferred_load_checks = []
+
+    def _scan_unused_imports(self):
+        # If requested, then check which of our imports were unused.
+        # For now we only scan the top level.  If we wanted to support
+        # non-global unused-import checking, then we should check this
+        # whenever popping a scopestack.
+        unused_imports = self.unused_imports
+        if unused_imports is None:
+            return
+        scope = self.scopestack[-1]
+        for name, value in scope.items():
+            if not isinstance(value, _UseChecker):
+                continue
+            if value.used:
+                continue
+            logger.debug("Also Adding to usunsed import: %s ", value)
+            unused_imports.append(( value.lineno, value.source ))
+        unused_imports.sort()
+
+
+def scan_for_import_issues(
+    codeblock: PythonBlock,
+    find_unused_imports: bool = True,
+    parse_docstrings: bool = False,
+):
+    """
+    Find missing and unused imports, by lineno.
+
+      >>> arg = "import numpy, aa.bb as cc\\nnumpy.arange(x)\\narange(x)"
+      >>> missing, unused = scan_for_import_issues(arg)
+      >>> missing
+      [(2, DottedIdentifier('x')), (3, DottedIdentifier('arange')), (3, DottedIdentifier('x'))]
+      >>> unused
+      [(1, Import('from aa import bb as cc'))]
+
+    :type codeblock:
+      ``PythonBlock``
+    :type namespaces:
+      ``dict`` or ``list`` of ``dict``
+    :param parse_docstrings:
+      Whether to parse docstrings.
+      Compare the following examples.  When parse_docstrings=True, 'bar' is
+      not considered unused because there is a string that references it in
+      braces::
+
+        >>> scan_for_import_issues("import foo as bar, baz\\n'{bar}'\\n")
+        ([], [(1, Import('import baz')), (1, Import('import foo as bar'))])
+        >>> scan_for_import_issues("import foo as bar, baz\\n'{bar}'\\n", parse_docstrings=True)
+        ([], [(1, Import('import baz'))])
+
+    """
+    logger.debug("global scan_for_import_issues()")
+    if not isinstance(codeblock, PythonBlock):
+        codeblock = PythonBlock(codeblock)
+    namespaces = ScopeStack([{}])
+    finder = _MissingImportFinder(namespaces,
+                                  find_unused_imports=find_unused_imports,
+                                  parse_docstrings=parse_docstrings)
+    return finder.scan_for_import_issues(codeblock)
+
+
+def _find_missing_imports_in_ast(node, namespaces):
+    """
+    Find missing imports in an AST node.
+    Helper function to `find_missing_imports`.
+
+      >>> node = ast.parse("import numpy; numpy.arange(x) + arange(x)")
+      >>> _find_missing_imports_in_ast(node, [{}])
+      [DottedIdentifier('arange'), DottedIdentifier('x')]
+
+    :type node:
+      ``ast.AST``
+    :type namespaces:
+      ``dict`` or ``list`` of ``dict``
+    :rtype:
+      ``list`` of ``DottedIdentifier``
+    """
+    if not isinstance(node, ast.AST):
+        raise TypeError
+    # Traverse the abstract syntax tree.
+    if logger.debug_enabled:
+        logger.debug("ast=%s", ast.dump(node))
+    return _MissingImportFinder(
+                 namespaces,
+                 find_unused_imports=False,
+                 parse_docstrings=False).find_missing_imports(node)
+
+# TODO: maybe we should replace _find_missing_imports_in_ast with
+# _find_missing_imports_in_code(compile(node)).  The method of parsing opcodes
+# is simpler, because Python takes care of the scoping issue for us and we
+# don't have to worry about locals.  It does, however, depend on CPython
+# implementation details, whereas the AST is well-defined by the language.
+
+
+def _find_missing_imports_in_code(co, namespaces):
+    """
+    Find missing imports in a code object.
+    Helper function to `find_missing_imports`.
+
+      >>> f = lambda: foo.bar(x) + baz(y)
+      >>> [str(m) for m in _find_missing_imports_in_code(f.__code__, [{}])]
+      ['baz', 'foo.bar', 'x', 'y']
+
+      >>> f = lambda x: (lambda: x+y)
+      >>> _find_missing_imports_in_code(f.__code__, [{}])
+      [DottedIdentifier('y')]
+
+    :type co:
+      ``types.CodeType``
+    :type namespaces:
+      ``dict`` or ``list`` of ``dict``
+    :rtype:
+      ``list`` of ``str``
+    """
+    loads_without_stores = set()
+    _find_loads_without_stores_in_code(co, loads_without_stores)
+    missing_imports = [
+        DottedIdentifier(fullname) for fullname in sorted(loads_without_stores)
+        if symbol_needs_import(fullname, namespaces)
+        ]
+    return missing_imports
+
+
+def _find_loads_without_stores_in_code(co, loads_without_stores):
+    """
+    Find global LOADs without corresponding STOREs, by disassembling code.
+    Recursive helper for `_find_missing_imports_in_code`.
+
+    :type co:
+      ``types.CodeType``
+    :param co:
+      Code object, e.g. ``function.__code__``
+    :type loads_without_stores:
+      ``set``
+    :param loads_without_stores:
+      Mutable set to which we add loads without stores.
+    :return:
+      ``None``
+    """
+    if not isinstance(co, types.CodeType):
+        raise TypeError(
+            "_find_loads_without_stores_in_code(): expected a CodeType; got a %s"
+            % (type(co).__name__,))
+    # Initialize local constants for fast access.
+    from opcode import EXTENDED_ARG, opmap
+
+    LOAD_ATTR    = opmap['LOAD_ATTR']
+    # LOAD_METHOD is _supposed_ to be removed in 3.12 but still present in opmap
+    # if sys.version_info < (3, 12):
+    LOAD_METHOD  = opmap['LOAD_METHOD']
+    # endif
+    LOAD_GLOBAL  = opmap['LOAD_GLOBAL']
+    LOAD_NAME    = opmap['LOAD_NAME']
+    STORE_ATTR   = opmap['STORE_ATTR']
+    STORE_GLOBAL = opmap['STORE_GLOBAL']
+    STORE_NAME   = opmap['STORE_NAME']
+
+    if sys.version_info > (3, 11):
+        CACHE = opmap["CACHE"]
+    else:
+        CACHE = object()
+    # Keep track of the partial name so far that started with a LOAD_GLOBAL.
+    # If ``pending`` is not None, then it is a list representing the name
+    # components we've seen so far.
+    pending = None
+    # Disassemble the code.  Look for LOADs and STOREs.  This code is based on
+    # ``dis.disassemble``.
+    #
+    # Scenarios:
+    #
+    #   * Function-level load a toplevel global
+    #         def f():
+    #             aa
+    #         => LOAD_GLOBAL; other (not LOAD_ATTR or STORE_ATTR)
+    #   * Function-level load an attribute of global
+    #         def f():
+    #             aa.bb.cc
+    #         => LOAD_GLOBAL; LOAD_ATTR; LOAD_ATTR; other
+    #   * Function-level store a toplevel global
+    #         def f():
+    #             global aa
+    #             aa = 42
+    #         => STORE_GLOBAL
+    #   * Function-level store an attribute of global
+    #         def f():
+    #             aa.bb.cc = 42
+    #         => LOAD_GLOBAL, LOAD_ATTR, STORE_ATTR
+    #   * Function-level load a local
+    #         def f():
+    #             aa = 42
+    #             return aa
+    #         => LOAD_FAST or LOAD_NAME
+    #   * Function-level store a local
+    #         def f():
+    #             aa = 42
+    #         => STORE_FAST or STORE_NAME
+    #   * Function-level load an attribute of a local
+    #         def f():
+    #             aa = 42
+    #             return aa.bb.cc
+    #         => LOAD_FAST; LOAD_ATTR; LOAD_ATTR
+    #   * Function-level store an attribute of a local
+    #         def f():
+    #             aa == 42
+    #             aa.bb.cc = 99
+    #         => LOAD_FAST; LOAD_ATTR; STORE_ATTR
+    #   * Function-level load an attribute of an expression other than a name
+    #         def f():
+    #             foo().bb.cc
+    #         => [CALL_FUNCTION, etc]; LOAD_ATTR; LOAD_ATTR
+    #   * Function-level store an attribute of an expression other than a name
+    #         def f():
+    #             foo().bb.cc = 42
+    #         => [CALL_FUNCTION, etc]; LOAD_ATTR; STORE_ATTR
+    #   * Function-level import
+    #         def f():
+    #             import aa.bb.cc
+    #         => IMPORT_NAME "aa.bb.cc", STORE_FAST "aa"
+    #   * Module-level load of a top-level global
+    #         aa
+    #         => LOAD_NAME
+    #   * Module-level store of a top-level global
+    #         aa = 42
+    #         => STORE_NAME
+    #   * Module-level load of an attribute of a global
+    #         aa.bb.cc
+    #         => LOAD_NAME, LOAD_ATTR, LOAD_ATTR
+    #   * Module-level store of an attribute of a global
+    #         aa.bb.cc = 42
+    #         => LOAD_NAME, LOAD_ATTR, STORE_ATTR
+    #   * Module-level import
+    #         import aa.bb.cc
+    #         IMPORT_NAME "aa.bb.cc", STORE_NAME "aa"
+    #   * Closure
+    #         def f():
+    #             aa = 42
+    #             return lambda: aa
+    #         f: STORE_DEREF, LOAD_CLOSURE, MAKE_CLOSURE
+    #         g = f(): LOAD_DEREF
+    bytecode = co.co_code
+    n = len(bytecode)
+    i = 0
+    extended_arg = 0
+    stores = set()
+    loads_after_label = set()
+    loads_before_label_without_stores = set()
+    # Find the earliest target of a backward jump.
+    earliest_backjump_label = _find_earliest_backjump_label(bytecode)
+    # Loop through bytecode.
+    while i < n:
+        op = bytecode[i]
+        i += 1
+        if op == CACHE:
+            continue
+        if take_arg(op):
+            oparg = bytecode[i] | extended_arg
+            extended_arg = 0
+            if op == EXTENDED_ARG:
+                extended_arg = (oparg << 8)
+                continue
+            i += 1
+
+        if pending is not None:
+            if op == STORE_ATTR:
+                # {LOAD_GLOBAL|LOAD_NAME} {LOAD_ATTR}* {STORE_ATTR}
+                pending.append(co.co_names[oparg])
+                fullname = ".".join(pending)
+                pending = None
+                stores.add(fullname)
+                continue
+            if op in [LOAD_ATTR, LOAD_METHOD]:
+                if sys.version_info >= (3,12):
+                    # from the docs:
+                    #
+                    # If the low bit of namei is not set, this replaces
+                    # STACK[-1] with getattr(STACK[-1], co_names[namei>>1]).
+                    #
+                    # If the low bit of namei is set, this will attempt to load
+                    # a method named co_names[namei>>1] from the STACK[-1]
+                    # object. STACK[-1] is popped. This bytecode distinguishes
+                    # two cases: if STACK[-1] has a method with the correct
+                    # name, the bytecode pushes the unbound method and
+                    # STACK[-1]. STACK[-1] will be used as the first argument
+                    # (self) by CALL when calling the unbound method. Otherwise,
+                    # NULL and the object returned by the attribute lookup are
+                    # pushed.
+                    #
+                    # Changed in version 3.12: If the low bit of namei is set,
+                    # then a NULL or self is pushed to the stack before the
+                    # attribute or unbound method respectively.
+                    #
+                    # Implication for Pyflyby
+                    #
+                    # In our case I think it means we are always looking at
+                    # oparg>>1 as the name of the names we need to load,
+                    # Though we don't keep track of the stack, and so we may get
+                    # wrong results ?
+                    #
+                    # In any case this seem to match what load_method was doing
+                    # before.
+                    pending.append(co.co_names[oparg>>1])
+                else:
+                    # {LOAD_GLOBAL|LOAD_NAME} {LOAD_ATTR}* so far;
+                    # possibly more LOAD_ATTR/STORE_ATTR will follow
+                    pending.append(co.co_names[oparg])
+                continue
+            # {LOAD_GLOBAL|LOAD_NAME} {LOAD_ATTR}* (and no more
+            # LOAD_ATTR/STORE_ATTR)
+            fullname = ".".join(pending)
+            pending = None
+            if i >= earliest_backjump_label:
+                loads_after_label.add(fullname)
+            elif fullname not in stores:
+                loads_before_label_without_stores.add(fullname)
+            # Fall through.
+
+        if op is LOAD_GLOBAL:
+            # Starting with 3.11, the low bit is used to tell whether to
+            # push an extra null on the stack, so we need to >> 1
+            # >> 0 does nothing
+            pending = [co.co_names[oparg >> LOAD_SHIFT]]
+            continue
+        if op is LOAD_NAME:
+            pending = [co.co_names[oparg]]
+            continue
+
+        if op in [STORE_GLOBAL, STORE_NAME]:
+            stores.add(co.co_names[oparg])
+            continue
+
+        # We don't need to worry about: LOAD_FAST, STORE_FAST, LOAD_CLOSURE,
+        # LOAD_DEREF, STORE_DEREF.  LOAD_FAST and STORE_FAST refer to local
+        # variables; LOAD_CLOSURE, LOAD_DEREF, and STORE_DEREF relate to
+        # closure variables.  In both cases we know these are not missing
+        # imports.  It's convenient that these are separate opcodes, because
+        # then we don't need to deal with them manually.
+
+    # Record which variables we saw that were loaded in this module without a
+    # corresponding store.  We handle two cases.
+    #
+    #   1. Load-before-store; no loops (i.e. no backward jumps).
+    #      Example A::
+    #          foo.bar()
+    #          import foo
+    #      In the above example A, "foo" was used before it was imported.  We
+    #      consider it a candidate for auto-import.
+    #      Example B:
+    #          if condition1():         # L1
+    #             import foo1           # L2
+    #          foo1.bar() + foo2.bar()  # L3
+    #          import foo2              # L4
+    #      In the above example B, "foo2" was used before it was imported; the
+    #      fact that there is a jump target at L3 is irrelevant because it is
+    #      the target of a forward jump; there is no way that foo2 can be
+    #      imported (L4) before foo2 is used (L3).
+    #      On the other hand, we don't know whether condition1 will be true,
+    #      so we assume L2 will be executed and therefore don't consider the
+    #      use of "foo1" at L3 to be problematic.
+    #
+    #   2. Load-before-store; with loops (backward jumps).  Example:
+    #         for i in range(10):
+    #            if i > 0:
+    #                print x
+    #            else:
+    #                x = "hello"
+    #       In the above example, "x" is actually always stored before load,
+    #       even though in a linear reading of the bytecode we would see the
+    #       store before any loads.
+    #
+    # It would be impossible to perfectly follow conditional code, because
+    # code could be arbitrarily complicated and would require a flow control
+    # analysis that solves the halting problem.  We do the best we can and
+    # handle case 1 as a common case.
+    #
+    # Case 1: If we haven't seen a label, then we know that any load
+    #         before a preceding store is definitely too early.
+    # Case 2: If we have seen a label, then we consider any preceding
+    #         or subsequent store to potentially match the load.
+    loads_without_stores.update( loads_before_label_without_stores ) # case 1
+    loads_without_stores.update( loads_after_label - stores )        # case 2
+
+    # The ``pending`` variable should have been reset at this point, because a
+    # function should always end with a RETURN_VALUE opcode and therefore not
+    # end in a LOAD_ATTR.
+    assert pending is None
+
+    # Recurse on inner function definitions, lambdas, generators, etc.
+    for arg in co.co_consts:
+        if isinstance(arg, types.CodeType):
+            _find_loads_without_stores_in_code(arg, loads_without_stores)
+
+if sys.version_info >= (3,12):
+    from dis import hasarg
+    def take_arg(op):
+        return op in hasarg
+else:
+    def take_arg(op):
+        from opcode import HAVE_ARGUMENT
+        return op >= HAVE_ARGUMENT
+
+def _find_earliest_backjump_label(bytecode):
+    """
+    Find the earliest target of a backward jump.
+
+    These normally represent loops.
+
+    For example, given the source code::
+
+      >>> def f():
+      ...     if foo1():
+      ...         foo2()
+      ...     else:
+      ...         foo3()
+      ...     foo4()
+      ...     while foo5():  # L7
+      ...         foo6()
+
+    The earliest target of a backward jump would be the 'while' loop at L7, at
+    bytecode offset 38::
+
+      >>> _find_earliest_backjump_label(f.__code__.co_code) # doctest: +SKIP
+      38
+
+    Note that in this example there are earlier targets of jumps at bytecode
+    offsets 20 and 28, but those are targets of _forward_ jumps, and the
+    clients of this function care about the earliest _backward_ jump.
+
+    If there are no backward jumps, return an offset that points after the end
+    of the bytecode.
+
+    :type bytecode:
+      ``bytes``
+    :param bytecode:
+      Compiled bytecode, e.g. ``function.__code__.co_code``.
+    :rtype:
+      ``int``
+    :return:
+      The earliest target of a backward jump, as an offset into the bytecode.
+    """
+    # Code based on dis.findlabels().
+    from opcode import hasjrel, hasjabs
+    if not isinstance(bytecode, bytes):
+        raise TypeError
+    n = len(bytecode)
+    earliest_backjump_label = n
+    i = 0
+    while i < n:
+        op = bytecode[i]
+        i += 1
+        if not take_arg(op):
+            continue
+        if i+1 >= len(bytecode):
+            break
+        oparg = bytecode[i] + bytecode[i+1]*256
+        i += 2
+        label = None
+        if op in hasjrel:
+            label = i+oparg
+        elif op in hasjabs:
+            label = oparg
+        else:
+            # No label
+            continue
+        if label >= i:
+            # Label is a forward jump
+            continue
+        # Found a backjump label.  Keep track of the earliest one.
+        earliest_backjump_label = min(earliest_backjump_label, label)
+    return earliest_backjump_label
+
+
+def find_missing_imports(arg, namespaces):
+    """
+    Find symbols in the given code that require import.
+
+    We consider a symbol to require import if we see an access ("Load" in AST
+    terminology) without an import or assignment ("Store" in AST terminology)
+    in the same lexical scope.
+
+    For example, if we use an empty list of namespaces, then "os.path.join" is
+    a symbol that requires import::
+
+      >>> [str(m) for m in find_missing_imports("os.path.join", namespaces=[{}])]
+      ['os.path.join']
+
+    But if the global namespace already has the "os" module imported, then we
+    know that ``os`` has a "path" attribute, which has a "join" attribute, so
+    nothing needs import::
+
+      >>> import os
+      >>> find_missing_imports("os.path.join", namespaces=[{"os":os}])
+      []
+
+    Builtins are always included::
+
+      >>> [str(m) for m in find_missing_imports("os, sys, eval", [{"os": os}])]
+      ['sys']
+
+    All symbols that are not defined are included::
+
+      >>> [str(m) for m in find_missing_imports("numpy.arange(x) + arange(y)", [{"y": 3}])]
+      ['arange', 'numpy.arange', 'x']
+
+    If something is imported/assigned/etc within the scope, then we assume it
+    doesn't require importing::
+
+      >>> [str(m) for m in find_missing_imports("import numpy; numpy.arange(x) + arange(x)", [{}])]
+      ['arange', 'x']
+
+      >>> [str(m) for m in find_missing_imports("from numpy import pi; numpy.pi + pi + x", [{}])]
+      ['numpy.pi', 'x']
+
+      >>> [str(m) for m in find_missing_imports("for x in range(3): print(numpy.arange(x))", [{}])]
+      ['numpy.arange']
+
+      >>> [str(m) for m in find_missing_imports("foo1 = func(); foo1.bar + foo2.bar", [{}])]
+      ['foo2.bar', 'func']
+
+      >>> [str(m) for m in find_missing_imports("a.b.y = 1; a.b.x, a.b.y, a.b.z", [{}])]
+      ['a.b.x', 'a.b.z']
+
+    find_missing_imports() parses the AST, so it understands scoping.  In the
+    following example, ``x`` is never undefined::
+
+      >>> find_missing_imports("(lambda x: x*x)(7)", [{}])
+      []
+
+    but this example, ``x`` is undefined at global scope::
+
+      >>> [str(m) for m in find_missing_imports("(lambda x: x*x)(7) + x", [{}])]
+      ['x']
+
+      >>> # Python 3
+      >>> [str(m) for m in find_missing_imports("[x+y+z for x,y in [(1,2)]], y", [{}])]
+      ['y', 'z']
+
+      >>> [str(m) for m in find_missing_imports("(x+y+z for x,y in [(1,2)]), y", [{}])]
+      ['y', 'z']
+
+    Only fully-qualified names starting at top-level are included::
+
+      >>> [str(m) for m in find_missing_imports("( ( a . b ) . x ) . y + ( c + d ) . x . y", [{}])]
+      ['a.b.x.y', 'c', 'd']
+
+    :type arg:
+      ``str``, ``ast.AST``, `PythonBlock`, ``callable``, or ``types.CodeType``
+    :param arg:
+      Python code, either as source text, a parsed AST, or compiled code; can
+      be as simple as a single qualified name, or as complex as an entire
+      module text.
+    :type namespaces:
+      ``dict`` or ``list`` of ``dict``
+    :param namespaces:
+      Stack of namespaces of symbols that exist per scope.
+    :rtype:
+      ``list`` of ``DottedIdentifier``
+    """
+    namespaces = ScopeStack(namespaces)
+    if isinstance(arg, (DottedIdentifier, str)):
+        try:
+            arg = DottedIdentifier(arg)
+        except BadDottedIdentifierError:
+            pass
+        else:
+            # The string is a single identifier.  Check directly whether it
+            # needs import.  This is an optimization to not bother parsing an
+            # AST.
+            if symbol_needs_import(arg, namespaces):
+                return [arg]
+            else:
+                return []
+        # Parse the string into an AST.
+        node = ast.parse(arg, type_comments=True) # may raise SyntaxError
+        # Get missing imports from AST.
+        return _find_missing_imports_in_ast(node, namespaces)
+    elif isinstance(arg, PythonBlock):
+        return _find_missing_imports_in_ast(arg.ast_node, namespaces)
+    elif isinstance(arg, ast.AST):
+        return _find_missing_imports_in_ast(arg, namespaces)
+    elif isinstance(arg, types.CodeType):
+        return _find_missing_imports_in_code(arg, namespaces)
+    elif callable(arg):
+        # Find the code object.
+        try:
+            co = arg.__code__
+        except AttributeError:
+            # User-defined callable
+            try:
+                co = arg.__call__.__code__
+            except AttributeError:
+                # Built-in function; no auto importing needed.
+                return []
+        # Get missing imports from code object.
+        return _find_missing_imports_in_code(co, namespaces)
+    else:
+        raise TypeError(
+            "find_missing_imports(): expected a string, AST node, or code object; got a %s"
+            % (type(arg).__name__,))
+
+
+def get_known_import(fullname, db=None):
+    """
+    Get the deepest known import.
+
+    For example, suppose:
+
+      - The user accessed "foo.bar.baz",
+      - We know imports for "foo", "foo.bar", and "foo.bar.quux".
+
+    Then we return "import foo.bar".
+
+    :type fullname:
+      `DottedIdentifier`
+    :param fullname:
+      Fully-qualified name, such as "scipy.interpolate"
+    """
+    # Get the import database.
+    db = ImportDB.interpret_arg(db, target_filename=".")
+    fullname = DottedIdentifier(fullname)
+    # Look for the "deepest" import we know about.  Suppose the user
+    # accessed "foo.bar.baz".  If we have an auto-import for "foo.bar",
+    # then import that.  (Presumably, the auto-import for "foo", if it
+    # exists, refers to the same foo.)
+    for partial_name in fullname.prefixes[::-1]:
+        try:
+            result = db.by_fullname_or_import_as[str(partial_name)]
+            logger.debug("get_known_import(%r): found %r", fullname, result)
+            return result
+        except KeyError:
+            logger.debug("get_known_import(%r): no known import for %r", fullname, partial_name)
+            pass
+    logger.debug("get_known_import(%r): found nothing", fullname)
+    return None
+
+
+_IMPORT_FAILED:Set[Any] = set()
+"""
+Set of imports we've already attempted and failed.
+"""
+
+
+def clear_failed_imports_cache():
+    """
+    Clear the cache of previously failed imports.
+    """
+    if _IMPORT_FAILED:
+        logger.debug("Clearing all %d entries from cache of failed imports",
+                     len(_IMPORT_FAILED))
+        _IMPORT_FAILED.clear()
+
+
+def _try_import(imp, namespace):
+    """
+    Try to execute an import.  Import the result into the namespace
+    ``namespace``.
+
+    Print to stdout what we're about to do.
+
+    Only import into ``namespace`` if we won't clobber an existing definition.
+
+    :type imp:
+      ``Import`` or ``str``
+    :param imp:
+      The import to execute, e.g. "from numpy import arange"
+    :type namespace:
+      ``dict``
+    :param namespace:
+      Namespace to import into.
+    :return:
+      ``True`` on success, ``False`` on failure
+    """
+    # TODO: generalize "imp" to any python statement whose toplevel is a
+    # single Store (most importantly import and assignment, but could also
+    # include def & cdef).  For things other than imports, we would want to
+    # first run handle_auto_imports() on the code.
+    imp = Import(imp)
+    if imp in _IMPORT_FAILED:
+        logger.debug("Not attempting previously failed %r", imp)
+        return False
+    impas = imp.import_as
+    name0 = impas.split(".", 1)[0]
+    stmt = str(imp)
+    logger.info(stmt)
+    # Do the import in a temporary namespace, then copy it to ``namespace``
+    # manually.  We do this instead of just importing directly into
+    # ``namespace`` for the following reason: Suppose the user wants "foo.bar",
+    # but "foo" already exists in the global namespace.  In order to import
+    # "foo.bar" we need to import its parent module "foo".  We only want to do
+    # the "foo.bar" import if what we import as "foo" is the same as the
+    # preexisting "foo".  OTOH, we _don't_ want to do the "foo.bar" import if
+    # the user had for some reason done "import fool as foo".  So we (1)
+    # import into a scratch namespace, (2) check that the top-level matches,
+    # then (3) copy into the user's namespace if it didn't already exist.
+    scratch_namespace = {}
+    try:
+        exec(stmt, scratch_namespace)
+        imported = scratch_namespace[name0]
+    except Exception as e:
+        logger.warning("Error attempting to %r: %s: %s", stmt, type(e).__name__, e,
+                       exc_info=True)
+        _IMPORT_FAILED.add(imp)
+        return False
+    try:
+        preexisting = namespace[name0]
+    except KeyError:
+        # The top-level symbol didn't previously exist in the user's global
+        # namespace.  Add it.
+        namespace[name0] = imported
+    else:
+        # The top-level symbol already existed in the user's global namespace.
+        # Check that it matched.
+        if preexisting is not imported:
+            logger.info("  => Failed: pre-existing %r (%r) differs from imported %r",
+                        name0, preexisting, name0)
+            return False
+    return True
+
+
+def auto_import_symbol(fullname, namespaces, db=None, autoimported=None, post_import_hook=None):
+    """
+    Try to auto-import a single name.
+
+    :type fullname:
+      ``str``
+    :param fullname:
+      Fully-qualified module name, e.g. "sqlalchemy.orm".
+    :type namespaces:
+      ``list`` of ``dict``, e.g. [globals()].
+    :param namespaces:
+      Namespaces to check.  Namespace[-1] is the namespace to import into.
+    :type db:
+      `ImportDB`
+    :param db:
+      Import database to use.
+    :param autoimported:
+      If not ``None``, then a dictionary of identifiers already attempted.
+      ``auto_import`` will not attempt to auto-import symbols already in this
+      dictionary, and will add attempted symbols to this dictionary, with
+      value ``True`` if the autoimport succeeded, or ``False`` if the autoimport
+      did not succeed.
+    :rtype:
+      ``bool``
+    :param post_import_hook:
+      A callable that is invoked if an import was successfully made.
+      It is invoked with the `Import` object representing the successful import
+    :type post_import_hook:
+      ``callable``
+    :return:
+      ``True`` if the symbol was already in the namespace, or the auto-import
+      succeeded; ``False`` if the auto-import failed.
+    """
+    namespaces = ScopeStack(namespaces)
+    if not symbol_needs_import(fullname, namespaces):
+        return True
+    if autoimported is None:
+        autoimported = {}
+    if DottedIdentifier(fullname) in autoimported:
+        logger.debug("auto_import_symbol(%r): already attempted", fullname)
+        return False
+    # See whether there's a known import for this name.  This is mainly
+    # important for things like "from numpy import arange".  Imports such as
+    # "import sqlalchemy.orm" will also be handled by this, although it's less
+    # important, since we're going to attempt that import anyway if it looks
+    # like a "sqlalchemy" package is importable.
+    imports = get_known_import(fullname, db=db)
+    # successful_import will store last successfully executed import statement
+    # to be passed to post_import_hook
+    successful_import = None
+    logger.debug("auto_import_symbol(%r): get_known_import() => %r",
+                 fullname, imports)
+    if imports is None:
+        # No known imports.
+        pass
+    else:
+        assert len(imports) >= 1
+        if len(imports) > 1:
+            # Doh, multiple imports.
+            logger.info("Multiple candidate imports for %s.  Please pick one:", fullname)
+            for imp in imports:
+                logger.info("  %s", imp)
+            autoimported[DottedIdentifier(fullname)] = False
+            return False
+        imp, = imports
+        if symbol_needs_import(imp.import_as, namespaces=namespaces):
+            # We're ready for some real action.  The input code references a
+            # name/attribute that (a) is not locally assigned, (b) is not a
+            # global, (c) is not yet imported, (d) is a known auto-import, (e)
+            # has only one definition
+            # TODO: label which known_imports file the autoimport came from
+            if not _try_import(imp, namespaces[-1]):
+                # Failed; don't do anything else.
+                autoimported[DottedIdentifier(fullname)] = False
+                return False
+            # Succeeded.
+            successful_import = imp
+            autoimported[DottedIdentifier(imp.import_as)] = True
+            if imp.import_as == fullname:
+                if post_import_hook:
+                    post_import_hook(imp)
+                # We got what we wanted, so nothing more to do.
+                return True
+            if imp.import_as != imp.fullname:
+                if post_import_hook:
+                    post_import_hook(imp)
+                # This is not just an 'import foo.bar'; rather, it's a 'import
+                # foo.bar as baz' or 'from foo import bar'.  So don't go any
+                # further.
+                return True
+        # Fall through.
+    # We haven't yet imported what we want.  Either there was no entry in the
+    # known imports database, or it wasn't "complete" (e.g. the user wanted
+    # "foo.bar.baz", and the known imports database only knew about "import
+    # foo.bar").  For each component that may need importing, check if the
+    # loader thinks it should be importable, and if so import it.
+    for pmodule in ModuleHandle(fullname).ancestors:
+        if not symbol_needs_import(pmodule.name, namespaces):
+            continue
+        pmodule_name = DottedIdentifier(pmodule.name)
+        if pmodule_name in autoimported:
+            if not autoimported[pmodule_name]:
+                logger.debug("auto_import_symbol(%r): stopping because "
+                             "already previously failed to autoimport %s",
+                             fullname, pmodule_name)
+                return False
+        if not pmodule.exists:
+            logger.debug("auto_import_symbol(%r): %r doesn't exist according to pkgutil",
+                         fullname, pmodule)
+            autoimported[pmodule_name] = False
+            return False
+        imp_stmt = "import %s" % pmodule_name
+        result = _try_import(imp_stmt, namespaces[-1])
+        autoimported[pmodule_name] = result
+        if not result:
+            return False
+        else:
+            successful_import = Import(imp_stmt)
+    if post_import_hook and successful_import:
+        post_import_hook(successful_import)
+    return True
+
+
+def auto_import(arg, namespaces, db=None, autoimported=None, post_import_hook=None, *, extra_db=None):
+    """
+    Parse ``arg`` for symbols that need to be imported and automatically import
+    them.
+
+    :type arg:
+      ``str``, ``ast.AST``, `PythonBlock`, ``callable``, or ``types.CodeType``
+    :param arg:
+      Python code, either as source text, a parsed AST, or compiled code; can
+      be as simple as a single qualified name, or as complex as an entire
+      module text.
+    :type namespaces:
+      ``dict`` or ``list`` of ``dict``
+    :param namespaces:
+      Namespaces to check.  Namespace[-1] is the namespace to import into.
+    :type db:
+      `ImportDB`
+    :param db:
+      Import database to use.
+    :type autoimported:
+      ``dict``
+    :param autoimported:
+      If not ``None``, then a dictionary of identifiers already attempted.
+      ``auto_import`` will not attempt to auto-import symbols already in this
+      dictionary, and will add attempted symbols to this dictionary, with
+      value ``True`` if the autoimport succeeded, or ``False`` if the autoimport
+      did not succeed.
+    :rtype:
+      ``bool``
+    :param post_import_hook:
+      A callable invoked on each successful import. This is passed to
+      `auto_import_symbol`
+    :type post_import_hook:
+      ``callable``
+    :return:
+      ``True`` if all symbols are already in the namespace or successfully
+      auto-imported; ``False`` if any auto-imports failed.
+    """
+    namespaces = ScopeStack(namespaces)
+    if isinstance(arg, PythonBlock):
+        filename = arg.filename
+    else:
+        filename = "."
+    try:
+        fullnames = find_missing_imports(arg, namespaces)
+    except SyntaxError:
+        logger.debug("syntax error parsing %r", arg)
+        return False
+    logger.debug("Missing imports: %r", fullnames)
+    if not fullnames:
+        return True
+    if autoimported is None:
+        autoimported = {}
+    db = ImportDB.interpret_arg(db, target_filename=filename)
+    if extra_db:
+        db = db|extra_db
+    ok = True
+    for fullname in fullnames:
+        ok &= auto_import_symbol(fullname, namespaces, db, autoimported, post_import_hook=post_import_hook)
+    return ok
+
+
+def auto_eval(arg, filename=None, mode=None,
+              flags=None, auto_flags=True, globals=None, locals=None,
+              db=None):
+    """
+    Evaluate/execute the given code, automatically importing as needed.
+
+    ``auto_eval`` will default the compilation ``mode`` to "eval" if possible::
+
+    >>> auto_eval("b64decode('aGVsbG8=')") + b"!"
+    [PYFLYBY] from base64 import b64decode
+    b'hello!'
+
+    ``auto_eval`` will default the compilation ``mode`` to "exec" if the input
+    is not a single expression::
+
+    >>> auto_eval("if True: print(b64decode('aGVsbG8=').decode('utf-8'))")
+    [PYFLYBY] from base64 import b64decode
+    hello
+
+    This is roughly equivalent to "auto_import(arg); eval(arg)", but handles
+    details better and more efficiently.
+
+    :type arg:
+      ``str``, ``ast.AST``, ``code``, `Filename`, `FileText`, `PythonBlock`
+    :param arg:
+      Code to evaluate.
+    :type filename:
+      ``str``
+    :param filename:
+      Filename for compilation error messages.  If ``None``, defaults to
+      ``arg.filename`` if relevant, else ``"<stdin>"``.
+    :type mode:
+      ``str``
+    :param mode:
+      Compilation mode: ``None``, "exec", "single", or "eval".  "exec",
+      "single", and "eval" work as the built-in ``compile`` function do.
+      If ``None``, then default to "eval" if the input is a string with a
+      single expression, else "exec".
+    :type flags:
+      ``CompilerFlags`` or convertible (``int``, ``list`` of ``str``, etc.)
+    :param flags:
+      Compilation feature flags, e.g. ["division", "with_statement"].  If
+      ``None``, defaults to no flags.  Does not inherit flags from parent
+      scope.
+    :type auto_flags:
+      ``bool``
+    :param auto_flags:
+      Whether to try other flags if ``flags`` causes SyntaxError.
+    :type globals:
+      ``dict``
+    :param globals:
+      Globals for evaluation.  If ``None``, use an empty dictionary.
+    :type locals:
+      ``dict``
+    :param locals:
+      Locals for evaluation.  If ``None``, use ``globals``.
+    :type db:
+      `ImportDB`
+    :param db:
+      Import database to use.
+    :return:
+      Result of evaluation (for mode="eval")
+    """
+    if isinstance(flags, int):
+        assert isinstance(flags, CompilerFlags)
+    if isinstance(arg, (str, Filename, FileText, PythonBlock)):
+        block = PythonBlock(arg, filename=filename, flags=flags,
+                            auto_flags=auto_flags)
+        flags = block.flags
+        filename = block.filename
+        arg = block.parse(mode=mode)
+    elif isinstance(arg, (ast.AST, types.CodeType)):
+        pass
+    else:
+        raise TypeError(
+            "auto_eval(): expected some form of code; got a %s"
+            % (type(arg).__name__,))
+    # Canonicalize other args.
+    if filename:
+        filename = Filename(filename)
+    else:
+        filename = None
+    if globals is None:
+        globals = {}
+    if locals is None:
+        locals = globals
+    db = ImportDB.interpret_arg(db, target_filename=filename)
+    namespaces = [globals, locals]
+    # Import as needed.
+    auto_import(arg, namespaces, db)
+    # Compile from AST to code object.
+    if isinstance(arg, types.CodeType):
+        code = arg
+    else:
+        # Infer mode from ast object.
+        mode = infer_compile_mode(arg)
+        # Compile ast node => code object.  This step is necessary because
+        # eval() doesn't work on AST objects.  We don't need to pass ``flags``
+        # to compile() because flags are irrelevant when we already have an
+        # AST node.
+        code = compile(arg, str(filename or "<unknown>"), mode)
+    # Evaluate/execute.
+    return eval(code, globals, locals)
+
+
+class LoadSymbolError(Exception):
+
+    def __str__(self):
+        r = ": ".join(map(str, self.args))
+        e = getattr(self, "__cause__", None)
+        if e:
+            r += ": %s: %s" % (type(e).__name__, e)
+        return r
+
+
+def load_symbol(fullname, namespaces, autoimport=False, db=None,
+                autoimported=None):
+    """
+    Load the symbol ``fullname``.
+
+    >>> import os
+    >>> load_symbol("os.path.join.__name__", {"os": os})
+    'join'
+
+    >>> load_symbol("os.path.join.asdf", {"os": os})
+    Traceback (most recent call last):
+    ...
+    pyflyby._autoimp.LoadSymbolError: os.path.join.asdf: AttributeError: 'function' object has no attribute 'asdf'
+
+    >>> load_symbol("os.path.join", {})
+    Traceback (most recent call last):
+    ...
+    pyflyby._autoimp.LoadSymbolError: os.path.join: NameError: os
+
+    :type fullname:
+      ``str``
+    :param fullname:
+      Fully-qualified symbol name, e.g. "os.path.join".
+    :type namespaces:
+      ``dict`` or ``list`` of ``dict``
+    :param namespaces:
+      Namespaces to check.
+    :param autoimport:
+      If ``False`` (default), the symbol must already be imported.
+      If ``True``, then auto-import the symbol first.
+    :type db:
+      `ImportDB`
+    :param db:
+      Import database to use when ``autoimport=True``.
+    :param autoimported:
+      If not ``None``, then a dictionary of identifiers already attempted.
+      ``auto_import`` will not attempt to auto-import symbols already in this
+      dictionary, and will add attempted symbols to this dictionary, with
+      value ``True`` if the autoimport succeeded, or ``False`` if the autoimport
+      did not succeed.
+    :return:
+      Object.
+    :raise LoadSymbolError:
+      Object was not found or there was another exception.
+    """
+    namespaces = ScopeStack(namespaces)
+    if autoimport:
+        # Auto-import the symbol first.
+        # We do the lookup as a separate step after auto-import.  (An
+        # alternative design could be to have auto_import_symbol() return the
+        # symbol if possible.  We don't do that because most users of
+        # auto_import_symbol() don't need to follow down arbitrary (possibly
+        # non-module) attributes.)
+        auto_import_symbol(fullname, namespaces, db, autoimported=autoimported)
+    name_parts = fullname.split(".")
+    name0 = name_parts[0]
+    for namespace in namespaces:
+        try:
+            obj = namespace[name0]
+        except KeyError:
+            pass
+        else:
+            for n in name_parts[1:]:
+                try:
+                    # Do the getattr.  This may raise AttributeError or
+                    # other exception.
+                    obj = getattr(obj, n)
+                except Exception as e:
+                    e2 = LoadSymbolError(fullname)
+                    e2.__cause__ = e
+                    reraise(LoadSymbolError, e2, sys.exc_info()[2])
+            return obj
+    else:
+        # Not found in any namespace.
+        e2 = LoadSymbolError(fullname)
+        e2.__cause__ = NameError(name0)
+        raise e2