pip-auto 0.3.0__py3-none-any.whl

autopip/__init__.py

@@ -0,0 +1,730 @@
+"""autopip: import した瞬間に無いモジュールを PyPI から自動で入れる。
+
+有効化すると sys.meta_path の最後にフックが入る。
+普通の import が全部失敗したときだけ呼ばれるので、既にあるモジュールには一切触らない。
+"""
+import _thread
+import importlib
+import importlib.machinery
+import os
+import sys
+import time
+
+
+class _Lazy:
+    """使うまで import しない(.pth で毎回起動時に読まれるので、起動を重くしない)"""
+
+    def __init__(self, name):
+        self._name, self._mod = name, None
+
+    def __getattr__(self, a):
+        if self._mod is None:
+            self._mod = importlib.import_module(self._name)
+        return getattr(self._mod, a)
+
+
+ast = _Lazy("ast")
+json = _Lazy("json")
+subprocess = _Lazy("subprocess")
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+HOME = os.environ.get("AUTOPIP_HOME") or os.path.join(os.path.expanduser("~"), ".autopip")
+
+# import名 と pip名 が違う有名どころ(これに無いものは下の対応表 → 名前の変種の順で探す)
+NAME_MAP = {
+    "cv2": "opencv-python",
+    "PIL": "pillow",
+    "sklearn": "scikit-learn",
+    "skimage": "scikit-image",
+    "yaml": "pyyaml",
+    "bs4": "beautifulsoup4",
+    "dateutil": "python-dateutil",
+    "dotenv": "python-dotenv",
+    "Crypto": "pycryptodome",
+    "serial": "pyserial",
+    "usb": "pyusb",
+    "win32api": "pywin32",
+    "win32con": "pywin32",
+    "win32gui": "pywin32",
+    "pythoncom": "pywin32",
+    "wx": "wxPython",
+    "gi": "PyGObject",
+    "attr": "attrs",
+    "jwt": "PyJWT",
+    "magic": "python-magic",
+    "docx": "python-docx",
+    "pptx": "python-pptx",
+    "fitz": "PyMuPDF",
+    "telegram": "python-telegram-bot",
+    "discord": "discord.py",
+    "google.generativeai": "google-generativeai",
+    "google.genai": "google-genai",
+    "googleapiclient": "google-api-python-client",
+    "OpenGL": "PyOpenGL",
+    "Levenshtein": "python-Levenshtein",
+    "zmq": "pyzmq",
+    "MySQLdb": "mysqlclient",
+    "psycopg2": "psycopg2-binary",
+    "websocket": "websocket-client",
+    "pkg_resources": "setuptools",
+}
+_MAP_URL = "https://raw.githubusercontent.com/bndr/pipreqs/master/pipreqs/mapping"
+
+_STDLIB = set(getattr(sys, "stdlib_module_names", ())) | set(sys.builtin_module_names)
+# Python 自身が起動時などに「あれば読む」名前。PyPI に探しに行かない
+_STDLIB |= {"sitecustomize", "usercustomize", "__main__", "__mp_main__", "_virtualenv", "_distutils_hack"}
+_tried = set()
+_enabled = False
+_busy = _thread.allocate_lock()
+
+
+def _log(msg):
+    if not os.environ.get("AUTOPIP_QUIET"):
+        print(f"[autopip] {msg}", file=sys.stderr, flush=True)
+
+
+def _cfg():
+    from .fast import load_config
+    return load_config()
+
+
+# ---------------- 失敗の記録(次の実行でも覚えておく) ----------------
+_FAILED = os.path.join(HOME, "failed.json")
+RETRY_AFTER = 24 * 3600
+
+
+def _failed_load():
+    try:
+        with open(_FAILED, encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return {}
+
+
+def _failed_save(d):
+    try:
+        os.makedirs(HOME, exist_ok=True)
+        with open(_FAILED, "w", encoding="utf-8") as f:
+            json.dump(d, f, ensure_ascii=False, indent=1)
+    except OSError:
+        pass
+
+
+def failed_recent(mod):
+    if os.environ.get("AUTOPIP_RETRY"):
+        return False
+    ts = _failed_load().get(mod)
+    return ts is not None and time.time() - ts < RETRY_AFTER
+
+
+def failed_add(mod):
+    d = _failed_load()
+    d[mod] = time.time()
+    _failed_save(d)
+
+
+def failed_clear(mod=None):
+    d = {} if mod is None else {k: v for k, v in _failed_load().items() if k != mod}
+    _failed_save(d)
+
+
+# ---------------- import名 → パッケージ名 ----------------
+_mapping_cache = None
+
+
+def _mapping():
+    """pipreqs の import名:パッケージ名 対応表(約 1000 件)。30 日キャッシュ。"""
+    global _mapping_cache
+    if _mapping_cache is not None:
+        return _mapping_cache
+    p = os.path.join(HOME, "mapping.txt")
+    if not os.path.exists(p) or time.time() - os.path.getmtime(p) > 30 * 86400:
+        try:
+            import urllib.request
+            data = urllib.request.urlopen(_MAP_URL, timeout=5).read()
+            os.makedirs(HOME, exist_ok=True)
+            with open(p, "wb") as f:
+                f.write(data)
+        except Exception:
+            pass
+    out = {}
+    try:
+        with open(p, encoding="utf-8") as f:
+            for line in f:
+                a, _, b = line.strip().partition(":")
+                if a and b:
+                    out.setdefault(a, b)
+    except OSError:
+        pass
+    _mapping_cache = out
+    return out
+
+
+def _prefixes(n):
+    parts = n.split(".")
+    return [".".join(parts[:i]) for i in range(len(parts), 0, -1)]
+
+
+def candidates(fullname, stmt=()):
+    """[(パッケージ名, そのパッケージが含むべきモジュール)] を優先順で。
+    stmt: import 文から拾った [(名前, from由来か)]"""
+    from .fast import norm, modindex
+    rel = lambda n: n == fullname or n.startswith(fullname + ".")
+    imp = sorted({n for n, frm in stmt if not frm and rel(n)} | {fullname}, key=len, reverse=True)
+    frm = sorted({n for n, f in stmt if f and rel(n)} - set(imp), key=len, reverse=True)
+    mp, learned = _mapping(), modindex()
+
+    def known(p):
+        return [m for m in (NAME_MAP.get(p), *learned.get(p, ()), mp.get(p)) if m]
+
+    out = []
+    for n in imp:                                        # 1. import 文の名前: 長い方から「対応表・学習済み → a.b→a-b」
+        for p in _prefixes(n):
+            out += [(m, p) for m in known(p)]
+            if "." in p:
+                out.append((p.replace(".", "-"), p))
+    top = fullname.split(".")[0]                         # 2. 名前そのもの + よくある変種
+    for v in (top, top.replace("_", "-"), f"python-{top}", f"py{top}", f"{top}-python", f"py-{top}", f"{top}-py"):
+        out.append((v, top))
+    for n in frm:                                        # 3. from a import b 由来(b は関数かもしれないので後回し)
+        for p in _prefixes(n):
+            out += [(m, p) for m in known(p)]
+            if "." in p:
+                out.append((p.replace(".", "-"), p))
+    seen, res = set(), []
+    for pkg, mod in out:
+        if (mod == fullname or mod.startswith(fullname + ".")) and norm(pkg) not in seen:
+            seen.add(norm(pkg))
+            res.append((pkg, mod))
+    return res
+
+
+def find_package(fullname, stmt=(), log=_log):
+    """中身まで確かめて、fullname を本当に提供するパッケージを返す。(pkg, mod) / None
+    候補の存在確認も中身の確認も全部並列で投げ、優先順で最初に当たったものを採る"""
+    from concurrent.futures import ThreadPoolExecutor
+    from . import fast
+    cands = candidates(fullname, stmt)
+    quiet = lambda m: None
+    with ThreadPoolExecutor(16) as ex:
+        exists = list(ex.map(lambda c: bool(fast._quiet(fast.project, c[0])), cands))
+        live = [c for c, e in zip(cands, exists) if e]
+        futs = [ex.submit(fast.check_provides, pkg, mod, quiet) for pkg, mod in live]
+        for (pkg, mod), f in zip(live, futs):
+            r = f.result()
+            if r:
+                for g in futs:
+                    g.cancel()
+                return pkg, mod
+            if r is False:
+                log(f"PyPI の {pkg} は '{mod}' を含まない(別物)→ 次を探す")
+    return None
+
+
+# ---------------- 誰が import したか ----------------
+_trees = {}
+
+
+def _tree(fn):
+    if fn not in _trees:
+        try:
+            with open(fn, encoding="utf-8", errors="replace") as f:
+                _trees[fn] = ast.parse(f.read(), fn)
+        except Exception:
+            _trees[fn] = None
+    return _trees[fn]
+
+
+_IMPORT_ERRORS = {"ImportError", "ModuleNotFoundError", "Exception", "BaseException"}
+
+
+def _catches_import_error(h):
+    if h.type is None:
+        return True
+    ts = h.type.elts if isinstance(h.type, ast.Tuple) else [h.type]
+    for t in ts:
+        name = t.id if isinstance(t, ast.Name) else t.attr if isinstance(t, ast.Attribute) else None
+        if name in _IMPORT_ERRORS:
+            return True
+    return False
+
+
+def stmt_info(fn, line):
+    """(try: で ImportError を拾っているか, [(import名, from由来か)])"""
+    tree = _tree(fn)
+    if tree is None:
+        return False, []
+    guarded, names = False, []
+    tries = tuple(t for t in (getattr(ast, "Try", None), getattr(ast, "TryStar", None)) if t)
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Import, ast.ImportFrom)) and node.lineno <= line <= (node.end_lineno or node.lineno):
+            if isinstance(node, ast.Import):
+                names += [(a.name, False) for a in node.names]
+            elif node.module and not node.level:
+                names.append((node.module, False))
+                names += [(f"{node.module}.{a.name}", True) for a in node.names if a.name != "*"]
+        elif isinstance(node, tries) and node.body:
+            if node.body[0].lineno <= line <= (node.body[-1].end_lineno or node.body[-1].lineno):
+                if any(_catches_import_error(h) for h in node.handlers):
+                    guarded = True
+    return guarded, names
+
+
+_PROBES = {"find_spec", "find_loader", "get_loader", "iter_modules", "_find_spec"}
+
+
+def _origin():
+    """import を書いた場所のフレームと、find_spec などでの「有無チェック」かどうか"""
+    f = sys._getframe(2)
+    probe = False
+    while f:
+        fn = f.f_code.co_filename
+        low = fn.replace("\\", "/")
+        if low.startswith("<frozen"):
+            f = f.f_back
+            continue
+        if not fn.startswith("<") and os.path.dirname(os.path.abspath(fn)) == _HERE:
+            return None, True               # autopip 自身の import(packaging があれば使う等)には反応しない
+        if "/importlib/" in low or low.endswith("/pkgutil.py"):
+            if f.f_code.co_name in _PROBES and low.endswith(("/importlib/util.py", "/pkgutil.py")):
+                probe = True
+            f = f.f_back
+            continue
+        return f, probe
+    return None, probe
+
+
+def _kind(fn):
+    if fn.startswith("<"):
+        return "user"
+    low = os.path.abspath(fn).replace("\\", "/").lower()
+    if "/site-packages/" in low or "/dist-packages/" in low:
+        return "lib"
+    for base in {sys.base_prefix, sys.prefix}:
+        b = os.path.abspath(base).replace("\\", "/").lower()
+        if low.startswith(b + "/lib/"):
+            return "stdlib"
+    # そのファイルを含む一番深い sys.path の場所で決める:
+    # スクリプトのフォルダ(sys.path[0])やカレントなら自分のコード、それ以外(site-packages・PYTHONPATH)はライブラリ
+    best, best_is_user = "", True
+    user_dirs = {os.path.abspath(sys.path[0] or os.getcwd()).replace("\\", "/").lower(),
+                 os.getcwd().replace("\\", "/").lower()} if sys.path else set()
+    for d in sys.path:
+        if not d:
+            continue
+        dd = os.path.abspath(d).replace("\\", "/").lower().rstrip("/")
+        if low.startswith(dd + "/") and len(dd) > len(best):
+            best, best_is_user = dd, dd in user_dirs
+    return "user" if best_is_user else "lib"
+
+
+# ---------------- import ロックを外して作業する ----------------
+def _without_import_lock(fn):
+    """import 中はグローバル import ロックを握っているので、一時的に外してスレッドを使えるようにする"""
+    import _imp
+    held = False
+    try:
+        _imp.release_lock()
+        held = True
+    except RuntimeError:
+        pass
+    try:
+        return fn()
+    finally:
+        if held:
+            _imp.acquire_lock()
+
+
+# ---------------- 確認 ----------------
+def _ask(fullname, pkg):
+    ask = os.environ.get("AUTOPIP_ASK") or _cfg().get("ask")
+    if not ask or str(ask).lower() in ("0", "false", "no"):
+        return True
+    line = console_input(f"[autopip] '{fullname}' のために {pkg} を入れる? [Y/n] ")
+    if line is None:
+        _log(f"確認モードだけど聞ける画面が無い → {pkg} は入れない")
+        return False
+    if not line:                     # 何も入力されずに終わった → いいえ
+        return False
+    return line.strip().lower() in ("", "y", "yes", "はい")
+
+
+def console_input(prompt):
+    """標準入力ではなく端末(Windows: CONIN$ / それ以外: /dev/tty)から直接 1 行読む。
+    標準入力がパイプやファイルでも聞ける。端末が無ければ None"""
+    timeout = float(os.environ.get("AUTOPIP_ASK_TIMEOUT", "60"))
+    fin = fout = None
+    try:
+        if os.name == "nt":
+            import ctypes
+            import msvcrt
+            k32, u32 = ctypes.windll.kernel32, ctypes.windll.user32
+            hwnd = k32.GetConsoleWindow()
+            if not hwnd or not u32.IsWindowVisible(hwnd):
+                return None          # コンソールが無い / 見えない(誰も答えられない)
+            fout = open("CONOUT$", "w", errors="replace")
+            fout.write(prompt)
+            fout.flush()
+            buf, end = [], time.time() + timeout
+            while time.time() < end:
+                if not msvcrt.kbhit():
+                    time.sleep(0.05)
+                    continue
+                ch = msvcrt.getwch()
+                if ch in ("\r", "\n"):
+                    fout.write("\n")
+                    return "".join(buf) + "\n"
+                if ch == "\x03":
+                    raise KeyboardInterrupt
+                if ch == "\b":
+                    if buf:
+                        buf.pop()
+                        fout.write("\b \b")
+                else:
+                    buf.append(ch)
+                    fout.write(ch)
+                fout.flush()
+            fout.write("\n(時間切れ)\n")
+            return ""
+        import select
+        fin = open("/dev/tty", "r")
+        fout = open("/dev/tty", "w")
+        fout.write(prompt)
+        fout.flush()
+        if not select.select([fin], [], [], timeout)[0]:
+            fout.write("\n(時間切れ)\n")
+            return ""
+        line = fin.readline()
+        if not line:
+            fout.write("\n")
+        return line
+    except OSError:
+        return None
+    finally:
+        for f in (fin, fout):
+            if f:
+                try:
+                    f.close()
+                except OSError:
+                    pass
+
+
+# ---------------- 本体 ----------------
+def _safe_to_install(pkg, fullname, log):
+    """安全チェック。strict で怪しければ入れない"""
+    from . import safety
+    ok, reasons = safety.check(pkg, fullname)
+    for r in reasons:
+        log(f"注意: {pkg}: {r}")
+    if not ok:
+        log(f"安全のため {pkg} は自動では入れない。本当に要るなら: python -m autopip install {pkg}"
+            f"(または python -m autopip config safety warn)")
+    return ok
+
+
+def _install_reqs(reqs, why, log):
+    """要求を入れる。自前が失敗したら pip。入ったもののリスト / None"""
+    from . import fast, usage
+    try:
+        got = fast.install(reqs, log=log)
+    except Exception as e:
+        log(f"高速インストール失敗 ({e}) → pip で試す")
+        got = None
+        for r in reqs:
+            g = _pip_install(r, log)
+            if g is None:
+                return None
+            got = (got or []) + g
+    if got:
+        usage.note_installed(got, why)
+    return got
+
+
+_pep723_done = set()
+
+
+def _ensure_pep723(log):
+    """__main__ のスクリプトに PEP 723 の依存が書いてあれば、最初の 1 回でまとめて入れる"""
+    main = getattr(sys.modules.get("__main__"), "__file__", None)
+    if not main or main in _pep723_done:
+        return False
+    _pep723_done.add(main)
+    from . import smart
+    try:
+        meta = smart.pep723(main)
+    except Exception as e:
+        log(f"PEP 723 ブロックが読めない: {e}")
+        return False
+    if not meta or not meta["dependencies"]:
+        return False
+    log(f"スクリプトに書かれた依存をまとめて入れる: {', '.join(meta['dependencies'])}")
+    return _install_reqs(meta["dependencies"], f"PEP 723 ({os.path.basename(main)})", log) is not None
+
+
+def ensure(fullname, stmt=(), log=_log, src=None):
+    """fullname を import できるようにする。できたら True
+    src: (import を書いたファイル, 行) ─ 行末の `# autopip: 要求` を読むのに使う"""
+    from . import fast, smart
+    t0 = time.perf_counter()
+    top = fullname.split(".")[0]
+
+    # 1. スクリプトの PEP 723 ブロック
+    if _ensure_pep723(log):
+        importlib.invalidate_caches()
+        if importlib.machinery.PathFinder.find_spec(top) is not None:
+            return True
+
+    # 2. 行末コメント `# autopip: numpy<2` があればその通りに
+    req = smart.comment_req_for(*src) if src else None
+    if req:
+        if not _ask(fullname, req):
+            return False
+        log(f"'{fullname}' が無い → コメントの指定どおり {req} を入れる")
+        got = _install_reqs([req], f"コメント指定 {req}", log)
+        importlib.invalidate_caches()
+        if got is not None and importlib.machinery.PathFinder.find_spec(top) is not None:
+            log(f"{', '.join(got) or req} 入った ({time.perf_counter() - t0:.2f}s)")
+            return True
+        log(f"{req} を入れても '{fullname}' が使えなかった")
+        if got:
+            fast.uninstall(got)
+        return False
+
+    # 3. 名前から探す
+    if failed_recent(fullname):
+        log(f"'{fullname}' は最近失敗したので飛ばす(AUTOPIP_RETRY=1 か python -m autopip forget で再挑戦)")
+        return False
+    try:
+        found = find_package(fullname, stmt, log)
+    except Exception as e:
+        log(f"探せなかった: {e}")
+        return False
+    if not found:
+        log(f"'{fullname}' を提供するパッケージが PyPI に見つからない")
+        failed_add(fullname)
+        return False
+    pkg, mod = found
+    if not _safe_to_install(pkg, fullname, log):
+        failed_add(fullname)
+        return False
+    if not _ask(fullname, pkg):
+        return False
+    log(f"'{fullname}' が無い → {pkg} を入れる")
+    got = _install_reqs([pkg], f"import {fullname}", log)
+    if got is None:
+        failed_add(fullname)
+        return False
+    importlib.invalidate_caches()
+    if importlib.machinery.PathFinder.find_spec(mod.split(".")[0]) is None:
+        log(f"'{mod}' が使えなかった → 今回入ったものを全部消す: {', '.join(got)}")
+        fast.uninstall(got)
+        failed_add(fullname)
+        return False
+    failed_clear(fullname)
+    log(f"{', '.join(got) or pkg} 入った ({time.perf_counter() - t0:.2f}s)")
+    return True
+
+
+def _pip_install(pkg, log):
+    """最後の手段。前後の差分で入ったものを返す(失敗したら差分を全部消して None)"""
+    from . import fast
+    t = fast.Target.current()
+    before = set(t.dists())
+    env = dict(os.environ, AUTOPIP_DISABLE="1")
+    r = subprocess.run([sys.executable, "-m", "pip", "install", "-q", "--disable-pip-version-check", pkg], env=env)
+    importlib.invalidate_caches()
+    added = sorted(set(t.dists()) - before)
+    if r.returncode != 0:
+        if added:
+            subprocess.run([sys.executable, "-m", "pip", "uninstall", "-y", "-q", *added], env=env)
+        return None
+    return added
+
+
+class AutoPipFinder:
+    def find_spec(self, fullname, path=None, target=None):
+        if os.environ.get("AUTOPIP_DISABLE") or _busy.locked():
+            return None
+        top = fullname.split(".")[0]
+        if top in _STDLIB or top.startswith("_") or fullname in _tried:
+            return None
+        # 自分より後ろに登録された finder (six.moves など) に先に聞く
+        mp = sys.meta_path
+        if self in mp:
+            for f in mp[mp.index(self) + 1:]:
+                fs = getattr(f, "find_spec", None)
+                spec = fs(fullname, path, target) if fs else None
+                if spec is not None:
+                    return spec
+        if "." in fullname and sys.modules.get(fullname.rpartition(".")[0]) is None:
+            return None
+        frame, probe = _origin()
+        if probe:
+            return None                     # importlib.util.find_spec("x") みたいな「あるかチェック」
+        kind = _kind(frame.f_code.co_filename) if frame else "user"
+        if kind == "stdlib":
+            return None
+        fn, line = (frame.f_code.co_filename, frame.f_lineno) if frame else (None, 0)
+        guarded, stmt = stmt_info(fn, line) if frame else (False, [])
+        if kind == "lib" and guarded:
+            return None                     # ライブラリの try: import optional は入れない
+        _tried.add(fullname)
+        with _busy:
+            ok = _without_import_lock(lambda: ensure(fullname, stmt, src=(fn, line) if kind == "user" else None))
+        if not ok:
+            return None
+        importlib.invalidate_caches()
+        return importlib.machinery.PathFinder.find_spec(fullname, path)
+
+
+def enable():
+    global _enabled
+    if _enabled or os.environ.get("AUTOPIP_DISABLE"):
+        return
+    sys.meta_path.append(AutoPipFinder())
+    _enabled = True
+    if not os.environ.get("AUTOPIP_NO_USAGE"):
+        import atexit
+        global _startup_modules
+        _startup_modules = set(sys.modules)      # 起動時に .pth などで読まれただけのものは「使った」に数えない
+        atexit.register(_record_usage)
+
+
+_startup_modules = set()
+
+
+def usage_file(prefix=None):
+    key = "".join(c if c.isalnum() else "_" for c in os.path.normcase(os.path.abspath(prefix or sys.prefix)))
+    return os.path.join(HOME, "usage", key[-120:] + ".txt")
+
+
+def read_usage(prefix=None):
+    """{トップ名: 最後に使った日 (epoch 日数)}"""
+    out = {}
+    try:
+        with open(usage_file(prefix), encoding="utf-8") as f:
+            for line in f:
+                name, _, day = line.strip().partition(" ")
+                if day.isdigit():
+                    out[name] = int(day)
+    except OSError:
+        pass
+    return out
+
+
+def write_usage(tops):
+    """tops を今日使ったことにする。もう今日の記録があれば何もしない(json も hashlib も使わない)"""
+    today = int(time.time() // 86400)
+    d = read_usage()
+    if all(d.get(t) == today for t in tops):
+        return
+    for t in tops:
+        d[t] = today
+    p = usage_file()
+    try:
+        os.makedirs(os.path.dirname(p), exist_ok=True)
+        tmp = f"{p}.{os.getpid()}"
+        with open(tmp, "w", encoding="utf-8") as f:
+            f.write("".join(f"{k} {v}\n" for k, v in sorted(d.items())))
+        os.replace(tmp, p)
+    except OSError:
+        pass
+
+
+def site_tops(only=None):
+    """site-packages から読み込まれたトップレベルのモジュール名"""
+    st = sys.modules.get("site")                 # 起動時に必ず読まれている(sysconfig は読まれていないことがある)
+    if st is None:
+        return []
+    dirs = list(getattr(st, "getsitepackages", lambda: [])())
+    try:
+        dirs.append(st.getusersitepackages())
+    except Exception:
+        pass
+    roots = tuple({os.path.normcase(os.path.abspath(d)) + os.sep for d in dirs})
+    out = []
+    for name, m in list(sys.modules.items()):
+        if "." in name or m is None or name in _STDLIB or (only is not None and name not in only):
+            continue
+        f = getattr(m, "__file__", None)
+        if f and os.path.normcase(os.path.abspath(f)).startswith(roots):
+            out.append(name)
+    return out
+
+
+def _record_usage():
+    if "pip._internal" in sys.modules or os.environ.get("AUTOPIP_NO_USAGE"):
+        return                                   # pip の実行中は触らない
+    new = {n for n in sys.modules if "." not in n and n not in _startup_modules}
+    if not new:
+        return                                   # 何も使ってなければ即終了
+    tops = site_tops(new)
+    if tops:
+        write_usage(tops)
+
+
+def scan(path):
+    """ファイルを実行せずに AST から import を全部拾う。無いものだけ返す [(名前, stmt, 行)]"""
+    with open(path, encoding="utf-8") as fp:
+        tree = ast.parse(fp.read(), path)
+    found, lines = {}, {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for a in node.names:
+                t = a.name.split(".")[0]
+                found.setdefault(t, []).append((a.name, False))
+                lines.setdefault(t, node.lineno)
+        elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+            t = node.module.split(".")[0]
+            found.setdefault(t, []).extend(
+                [(node.module, False)] + [(f"{node.module}.{a.name}", True) for a in node.names if a.name != "*"])
+            lines.setdefault(t, node.lineno)
+    here = os.path.dirname(os.path.abspath(path))
+    missing = []
+    for top in sorted(found):
+        if top in _STDLIB:
+            continue
+        if os.path.exists(os.path.join(here, top + ".py")) or os.path.isdir(os.path.join(here, top)):
+            continue
+        try:
+            if __import__("importlib.util").util.find_spec(top) is not None:
+                continue
+        except (ImportError, ValueError):
+            pass
+        missing.append((top, found[top], lines[top]))
+    return missing
+
+
+def plan_file(path, log=_log):
+    """ファイルが必要とする要求の一覧: PEP 723 > 行末コメント > 名前から探す"""
+    from concurrent.futures import ThreadPoolExecutor
+    from . import smart
+    reqs = []
+    meta = smart.pep723(path)
+    if meta and meta["dependencies"]:
+        reqs += meta["dependencies"]
+    comments = smart.comment_reqs(path)
+    miss = scan(path)
+    todo = []
+    for name, stmt, line in miss:
+        if line in comments:
+            reqs.append(comments[line])
+        elif not meta or not meta["dependencies"]:
+            todo.append((name, stmt))
+    with ThreadPoolExecutor(8) as ex:
+        found = list(ex.map(lambda m: find_package(m[0], m[1], log), todo))
+    for (name, _), f in zip(todo, found):
+        if f is None:
+            log(f"'{name}' を提供するパッケージが見つからない")
+        elif _safe_to_install(f[0], name, log) and _ask(name, f[0]):
+            reqs.append(f[0])
+    return list(dict.fromkeys(reqs))
+
+
+def ensure_file(path, log=_log):
+    """ファイルが使うのに無いものを、全部まとめて 1 回で入れる"""
+    reqs = plan_file(path, log)
+    if not reqs:
+        return []
+    log(f"まとめて入れる: {', '.join(reqs)}")
+    return _install_reqs(reqs, f"run {os.path.basename(path)}", log) or []