depfix 0.1.0__py3-none-any.whl

depfix/__init__.py

@@ -0,0 +1,196 @@
+"""Depfix: version-resolved imports with per-package dependency realms.
+
+Importing this package performs no network, resolver, or subprocess work. Cold
+preparation begins only when a load API is called.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from types import ModuleType
+
+from ._version import __version__
+from .errors import (
+    ArtifactError,
+    BundleError,
+    DepfixError,
+    FrozenManifestError,
+    HashMismatchError,
+    ManifestError,
+    ManifestMismatchError,
+    ManifestNotFoundError,
+    ModuleDiscoveryError,
+    ModuleNotProvidedError,
+    MultipleImportModulesError,
+    NativeIsolationRequired,
+    NoImportModulesError,
+    OfflineArtifactMissingError,
+    ResolutionError,
+    SourceError,
+    SpecifierError,
+    UnsupportedManifestVersionError,
+    UnsupportedUvVersionError,
+    UvBackendError,
+    UvBootstrapError,
+    UvNotFoundError,
+)
+from .handles import PackageHandle
+from .manager import activate_manifest, prepare_request
+from .settings import Settings, configure, resolve_settings
+
+
+def import_module(
+    specifier: str,
+    *,
+    module: str | None = None,
+    refresh: bool = False,
+    manifest: str | os.PathLike[str] | None = None,
+    frozen: bool | None = None,
+    offline: bool | None = None,
+    isolation: str | None = None,
+) -> ModuleType:
+    """Return exactly one canonical module or raise a typed discovery error."""
+    settings = resolve_settings(manifest=manifest, frozen=frozen, offline=offline)
+    runtime, request = prepare_request(
+        specifier,
+        module=module,
+        api="import_module",
+        refresh=refresh,
+        isolation=isolation,
+        settings=settings,
+    )
+    if not request.module:
+        raise NoImportModulesError("The resolved request has no selected import module", request=specifier)
+    return runtime.import_for_node(request.node, request.module)
+
+
+def load_package(
+    specifier: str,
+    *,
+    refresh: bool = False,
+    manifest: str | os.PathLike[str] | None = None,
+    frozen: bool | None = None,
+    offline: bool | None = None,
+    isolation: str | None = None,
+) -> PackageHandle:
+    """Return one package handle without eagerly importing its root modules."""
+    settings = resolve_settings(manifest=manifest, frozen=frozen, offline=offline)
+    runtime, request = prepare_request(
+        specifier,
+        module=None,
+        api="load_package",
+        refresh=refresh,
+        isolation=isolation,
+        settings=settings,
+    )
+    return PackageHandle(runtime, request)
+
+
+async def import_module_async(
+    specifier: str,
+    *,
+    module: str | None = None,
+    refresh: bool = False,
+    manifest: str | os.PathLike[str] | None = None,
+    frozen: bool | None = None,
+    offline: bool | None = None,
+    isolation: str | None = None,
+) -> ModuleType:
+    """Async-friendly wrapper sharing canonical identity with `import_module`."""
+    return await asyncio.to_thread(
+        import_module,
+        specifier,
+        module=module,
+        refresh=refresh,
+        manifest=manifest,
+        frozen=frozen,
+        offline=offline,
+        isolation=isolation,
+    )
+
+
+async def load_package_async(
+    specifier: str,
+    *,
+    refresh: bool = False,
+    manifest: str | os.PathLike[str] | None = None,
+    frozen: bool | None = None,
+    offline: bool | None = None,
+    isolation: str | None = None,
+) -> PackageHandle:
+    return await asyncio.to_thread(
+        load_package,
+        specifier,
+        refresh=refresh,
+        manifest=manifest,
+        frozen=frozen,
+        offline=offline,
+        isolation=isolation,
+    )
+
+
+def activate(
+    manifest: str | os.PathLike[str] = ".depfix/imports.lock",
+    *,
+    cache_dir: str | os.PathLike[str] | None = None,
+) -> object:
+    """Activate an already installed manifest for notebooks or embedding."""
+    settings = resolve_settings(manifest=manifest, cache_dir=cache_dir, frozen=True, discover=False)
+    assert settings.manifest is not None
+    return activate_manifest(settings.manifest, settings)
+
+
+def _load_alias(name: str, identity: tuple[str, str, str, str]) -> ModuleType:
+    from .manager import load_generated_alias
+
+    return load_generated_alias(name, identity)
+
+
+def _load_package_alias(name: str, identity: tuple[str, str, str, str]) -> PackageHandle:
+    from .manager import load_generated_package
+
+    return load_generated_package(name, identity)
+
+
+def multiprocessing_initializer(
+    manifest: str | os.PathLike[str],
+    cache_dir: str | os.PathLike[str] | None = None,
+) -> None:
+    activate(manifest, cache_dir=cache_dir)
+
+
+__all__ = [
+    "ArtifactError",
+    "BundleError",
+    "DepfixError",
+    "FrozenManifestError",
+    "HashMismatchError",
+    "ManifestError",
+    "ManifestMismatchError",
+    "ManifestNotFoundError",
+    "ModuleDiscoveryError",
+    "ModuleNotProvidedError",
+    "MultipleImportModulesError",
+    "NativeIsolationRequired",
+    "NoImportModulesError",
+    "OfflineArtifactMissingError",
+    "PackageHandle",
+    "ResolutionError",
+    "Settings",
+    "SourceError",
+    "SpecifierError",
+    "UnsupportedManifestVersionError",
+    "UnsupportedUvVersionError",
+    "UvBackendError",
+    "UvBootstrapError",
+    "UvNotFoundError",
+    "activate",
+    "configure",
+    "import_module",
+    "import_module_async",
+    "load_package",
+    "load_package_async",
+    "multiprocessing_initializer",
+    "__version__",
+]

depfix/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

depfix/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

depfix/aliases.py

@@ -0,0 +1,189 @@
+"""Generate the physical alias namespace used by editors and runtime code."""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from pathlib import Path
+
+from .cache import Cache
+from .models import LockedGraph, Node
+
+
+def generate_aliases(graph: LockedGraph, cache: Cache, output_root: Path) -> Path:
+    package = output_root / "depfix_imports"
+    package.mkdir(parents=True, exist_ok=True)
+    alias_rows = {
+        alias.name: (graph.graph_id, alias.node, alias.module, alias.specifier)
+        for alias in sorted(graph.aliases, key=lambda value: value.name)
+    }
+    init = (
+        '"""Generated by Depfix; do not edit."""\n'
+        "from depfix import _load_alias as _depfix_load_alias\n"
+        "from depfix import _load_package_alias as _depfix_load_package_alias\n\n"
+        f"_ALIASES = {alias_rows!r}\n\n"
+        f"_PACKAGE_ALIASES = {sorted(alias.name for alias in graph.aliases if alias.api == 'load_package')!r}\n\n"
+        "def __getattr__(name):\n"
+        "    if name not in _ALIASES:\n"
+        "        raise AttributeError(name)\n"
+        "    loader = _depfix_load_package_alias if name in _PACKAGE_ALIASES else _depfix_load_alias\n"
+        "    value = loader(name, _ALIASES[name])\n"
+        "    globals()[name] = value\n"
+        "    return value\n\n"
+        f"__all__ = {sorted(alias_rows)!r}\n"
+    )
+    (package / "__init__.py").write_text(init, encoding="utf-8")
+    root_stub = "".join(f"from . import {name} as {name}\n" for name in sorted(alias_rows))
+    (package / "__init__.pyi").write_text(root_stub, encoding="utf-8")
+    (package / "py.typed").write_text("\n", encoding="utf-8")
+    manifest = {
+        "format_version": 1,
+        "graph_id": graph.graph_id,
+        "aliases": [
+            {"name": alias.name, "node": alias.node, "module": alias.module, "specifier": alias.specifier}
+            for alias in sorted(graph.aliases, key=lambda value: value.name)
+        ],
+    }
+    (package / "aliases.json").write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    source_map = {
+        "format_version": 1,
+        "manifest_id": graph.graph_id,
+        "aliases": {
+            alias.name: {
+                "source_file": alias.source_file,
+                "line": alias.source_line,
+                "column": alias.source_column,
+                "specifier": alias.specifier,
+                "logical_module": alias.module,
+                "node": alias.node,
+            }
+            for alias in sorted(graph.aliases, key=lambda value: value.name)
+        },
+    }
+    (package / "source-map.json").write_text(
+        json.dumps(source_map, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    nodes = graph.node_index
+    for alias in graph.aliases:
+        if alias.api == "load_package":
+            _generate_package_stub_tree(package, alias.name, nodes[alias.node], cache, alias_rows[alias.name])
+        else:
+            _generate_stub_tree(package, alias.name, alias.module, nodes[alias.node], cache)
+    _write_editor_snippets(output_root)
+    return package
+
+
+def _generate_stub_tree(package: Path, alias_name: str, logical_module: str, node: Node, cache: Cache) -> None:
+    alias_root = package / alias_name
+    if alias_root.exists():
+        shutil.rmtree(alias_root)
+    alias_root.mkdir(parents=True)
+    artifact_root = cache.unpacked_path(node.artifact) / "purelib"
+    source_root = artifact_root.joinpath(*logical_module.split("."))
+    if source_root.is_dir():
+        typed = (source_root / "py.typed").exists()
+        for source in source_root.rglob("*"):
+            if not source.is_file():
+                continue
+            relative = source.relative_to(source_root)
+            if source.suffix == ".pyi":
+                target = alias_root / relative
+            elif typed and source.suffix == ".py":
+                target = (alias_root / relative).with_suffix(".pyi")
+            else:
+                continue
+            target.parent.mkdir(parents=True, exist_ok=True)
+            _copy_stub(source, target, logical_module, f"depfix_imports.{alias_name}")
+    else:
+        source_file = source_root.with_suffix(".py")
+        stub_file = source_root.with_suffix(".pyi")
+        selected = stub_file if stub_file.is_file() else source_file if source_file.is_file() else None
+        if selected is not None:
+            _copy_stub(selected, alias_root / "__init__.pyi", logical_module, f"depfix_imports.{alias_name}")
+    fallback = alias_root / "__init__.pyi"
+    if not fallback.exists():
+        fallback.write_text("# Untyped artifact: API is intentionally unknown to static analyzers.\n", encoding="utf-8")
+
+
+def _generate_package_stub_tree(
+    package: Path,
+    alias_name: str,
+    node: Node,
+    cache: Cache,
+    identity: tuple[str, str, str, str],
+) -> None:
+    alias_root = package / alias_name
+    if alias_root.exists():
+        shutil.rmtree(alias_root)
+    alias_root.mkdir(parents=True)
+    runtime = (
+        '"""Generated Depfix package-module collection."""\n'
+        "from depfix import _load_package_alias\n"
+        f"_PACKAGE = _load_package_alias({alias_name!r}, {identity!r})\n"
+        "def __getattr__(name):\n"
+        "    try:\n"
+        "        return _PACKAGE.modules[name]\n"
+        "    except Exception as exc:\n"
+        "        raise AttributeError(name) from exc\n"
+        f"__all__ = {list(node.public_modules)!r}\n"
+    )
+    (alias_root / "__init__.py").write_text(runtime, encoding="utf-8")
+    imports: list[str] = []
+    artifact_root = cache.unpacked_path(node.artifact) / "purelib"
+    for logical in node.public_modules:
+        target_root = alias_root.joinpath(*logical.split("."))
+        source_root = artifact_root.joinpath(*logical.split("."))
+        if source_root.is_dir():
+            target_root.mkdir(parents=True, exist_ok=True)
+            typed = (source_root / "py.typed").exists()
+            for source in source_root.rglob("*"):
+                if not source.is_file() or (source.suffix != ".pyi" and not (typed and source.suffix == ".py")):
+                    continue
+                relative = source.relative_to(source_root)
+                target = target_root / relative
+                if target.suffix == ".py":
+                    target = target.with_suffix(".pyi")
+                _copy_stub(
+                    source, target, logical.split(".", 1)[0], f"depfix_imports.{alias_name}.{logical.split('.', 1)[0]}"
+                )
+            (target_root / "__init__.pyi").touch(exist_ok=True)
+        else:
+            selected = source_root.with_suffix(".pyi")
+            if not selected.is_file():
+                selected = source_root.with_suffix(".py")
+            target_root.parent.mkdir(parents=True, exist_ok=True)
+            target = target_root.with_suffix(".pyi")
+            if selected.is_file():
+                _copy_stub(
+                    selected,
+                    target,
+                    logical.split(".", 1)[0],
+                    f"depfix_imports.{alias_name}.{logical.split('.', 1)[0]}",
+                )
+            else:
+                target.write_text("# Untyped module.\n", encoding="utf-8")
+        top = logical.split(".", 1)[0]
+        imports.append(f"from . import {top} as {top}\n")
+    (alias_root / "__init__.pyi").write_text("".join(dict.fromkeys(imports)), encoding="utf-8")
+
+
+def _copy_stub(source: Path, target: Path, logical_root: str, alias_root: str) -> None:
+    target.parent.mkdir(parents=True, exist_ok=True)
+    text = source.read_text(encoding="utf-8")
+    escaped = re.escape(logical_root)
+    text = re.sub(rf"(?m)^(\s*from\s+){escaped}(?=\.|\s+import\b)", rf"\1{alias_root}", text)
+    text = re.sub(rf"(?m)^(\s*import\s+){escaped}(?=\.|\s|$)", rf"\1{alias_root}", text)
+    target.write_text(text, encoding="utf-8")
+
+
+def _write_editor_snippets(output_root: Path) -> None:
+    generated = str(output_root.resolve())
+    (output_root / "pyrightconfig.depfix.json").write_text(
+        json.dumps({"extraPaths": [generated], "stubPath": generated}, indent=2) + "\n", encoding="utf-8"
+    )
+    (output_root / "mypy.depfix.ini").write_text(f"[mypy]\nmypy_path = {generated}\n", encoding="utf-8")
+    (output_root / "PYCHARM.md").write_text(
+        "Mark this generated directory as a Sources Root in Settings > Project Structure.\n", encoding="utf-8"
+    )