import-effects 0.0.1__py3-none-any.whl

import_effects/__init__.py

@@ -0,0 +1,15 @@
+from .inspector import InspectionError, assert_no_effects, inspect_import
+from .models import Attribution, Confidence, Effect, EffectKind, ImportReport
+
+__all__ = [
+    "Attribution",
+    "Confidence",
+    "Effect",
+    "EffectKind",
+    "ImportReport",
+    "InspectionError",
+    "assert_no_effects",
+    "inspect_import",
+]
+
+__version__ = "0.0.1"

import_effects/__main__.py

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

import_effects/_probe.py

@@ -0,0 +1,321 @@
+from __future__ import annotations
+
+import importlib
+import inspect
+import json
+import logging
+import multiprocessing
+import os
+import platform
+import re
+import signal
+import sys
+import threading
+import time
+import warnings
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from .models import Attribution, Confidence, Effect, EffectKind, ImportReport
+
+_SECRET_RE = re.compile(
+    r"(?i)(token|secret|password|passwd|api[-_]?key|authorization)(=|:)([^\s]+)"
+)
+_WRITE_FLAGS = os.O_WRONLY | os.O_RDWR | os.O_CREAT | os.O_TRUNC | os.O_APPEND
+
+
+@dataclass(frozen=True)
+class _Snapshot:
+    cwd: str
+    environment: dict[str, str]
+    sys_path: tuple[str, ...]
+    warning_filters: tuple[str, ...]
+    logging_handlers: tuple[tuple[str, str], ...]
+    signal_handlers: dict[int, str]
+    modules: frozenset[str]
+
+
+class _Observer:
+    def __init__(self, target: str, report_path: Path) -> None:
+        self.target = target
+        self.report_path = report_path.resolve()
+        self.effects: list[Effect] = []
+        self.active = False
+        self._keys: set[tuple[str, str]] = set()
+
+    def add(
+        self,
+        kind: EffectKind,
+        detail: str,
+        *,
+        confidence: Confidence = "high",
+        source: str | None = None,
+        attribution: Attribution | None = None,
+        metadata: Mapping[str, str | int | float | bool | None] | None = None,
+    ) -> None:
+        if not self.active:
+            return
+        clean_detail = _redact(detail)
+        key = (kind, clean_detail)
+        if key in self._keys:
+            return
+        self._keys.add(key)
+        inferred_source, inferred_attribution = self._infer_source()
+        self.effects.append(
+            Effect(
+                kind=kind,
+                detail=clean_detail,
+                source=source or inferred_source,
+                confidence=confidence,
+                attribution=attribution or inferred_attribution,
+                metadata=metadata or {},
+            )
+        )
+
+    def _infer_source(self) -> tuple[str | None, Attribution]:
+        frame = inspect.currentframe()
+        try:
+            while frame:
+                name = str(frame.f_globals.get("__name__", ""))
+                if name == self.target or name.startswith(self.target + "."):
+                    return name, "target"
+                if name and not name.startswith(("import_effects", "importlib", "threading")):
+                    path = frame.f_globals.get("__file__")
+                    if path and "site-packages" in os.fspath(path):
+                        return name, "dependency"
+                frame = frame.f_back
+        finally:
+            del frame
+        return None, "observed-during-import"
+
+    def audit(self, event: str, args: tuple[Any, ...]) -> None:
+        if not self.active:
+            return
+        try:
+            if event == "open":
+                self._audit_open(args)
+            elif event in {"os.remove", "os.unlink"}:
+                path = _path(args[0])
+                if not _is_runtime_path(path):
+                    self.add("file-delete", path)
+            elif event in {"os.rename", "os.replace"}:
+                source, destination = _path(args[0]), _path(args[1])
+                if not (_is_runtime_path(source) or _is_runtime_path(destination)):
+                    self.add("file-rename", f"{source} -> {destination}")
+            elif event in {"os.mkdir", "os.rmdir"}:
+                path = _path(args[0])
+                if not _is_runtime_path(path):
+                    action = "mkdir" if event == "os.mkdir" else "rmdir"
+                    self.add("directory", f"{action} {path}")
+            elif event == "socket.connect":
+                self.add("network", _address(args[-1]), metadata={"operation": "connect"})
+            elif event == "socket.bind":
+                self.add("network", f"bind {_address(args[-1])}", metadata={"operation": "bind"})
+            elif event == "socket.getaddrinfo":
+                host = args[0] if args else "unknown"
+                port = args[1] if len(args) > 1 else None
+                self.add(
+                    "network",
+                    _address((host, port)),
+                    confidence="medium",
+                    metadata={"operation": "dns"},
+                )
+            elif event == "subprocess.Popen":
+                executable = args[0] if args else "unknown"
+                arguments = args[1] if len(args) > 1 else ()
+                self.add("subprocess", _command(executable, arguments))
+            elif event in {"os.system", "os.posix_spawn", "os.posix_spawnp"}:
+                self.add("subprocess", _command(args[0] if args else "unknown", ()))
+            elif event in {"os.fork", "os.forkpty"}:
+                self.add("multiprocessing", "forked child process")
+        except Exception:
+            # Audit hooks must never break the target import.
+            return
+
+    def _audit_open(self, args: tuple[Any, ...]) -> None:
+        if not args:
+            return
+        if isinstance(args[0], int):
+            return
+        path = _path(args[0])
+        if _is_internal_write(path, self.report_path):
+            return
+        mode = args[1] if len(args) > 1 else None
+        flags = args[2] if len(args) > 2 else 0
+        writes = isinstance(mode, str) and any(character in mode for character in "wax+")
+        writes = writes or (isinstance(flags, int) and bool(flags & _WRITE_FLAGS))
+        if writes:
+            self.add("file-write", path)
+
+
+def _snapshot() -> _Snapshot:
+    return _Snapshot(
+        cwd=os.getcwd(),
+        environment=dict(os.environ),
+        sys_path=tuple(sys.path),
+        warning_filters=tuple(repr(item) for item in warnings.filters),
+        logging_handlers=tuple(
+            sorted(
+                (logger_name or "root", type(handler).__name__)
+                for logger_name, logger in [
+                    ("", logging.getLogger()),
+                    *logging.Logger.manager.loggerDict.items(),
+                ]
+                if isinstance(logger, logging.Logger)
+                for handler in logger.handlers
+            )
+        ),
+        signal_handlers={
+            number: _handler_name(signal.getsignal(number)) for number in _available_signals()
+        },
+        modules=frozenset(sys.modules),
+    )
+
+
+def _compare(observer: _Observer, before: _Snapshot, after: _Snapshot) -> None:
+    if before.cwd != after.cwd:
+        observer.add("cwd", f"{before.cwd} -> {after.cwd}", confidence="high")
+    before_keys, after_keys = set(before.environment), set(after.environment)
+    for key in sorted(after_keys - before_keys):
+        observer.add("environment", f"added {key}", confidence="high")
+    for key in sorted(before_keys - after_keys):
+        observer.add("environment", f"removed {key}", confidence="high")
+    for key in sorted(before_keys & after_keys):
+        if before.environment[key] != after.environment[key]:
+            observer.add("environment", f"changed {key}", confidence="high")
+    if before.sys_path != after.sys_path:
+        observer.add("sys-path", "sys.path changed", confidence="medium")
+    if before.warning_filters != after.warning_filters:
+        observer.add("warnings", "warnings filters changed", confidence="medium")
+    added_handlers = list(after.logging_handlers)
+    for original_handler in before.logging_handlers:
+        if original_handler in added_handlers:
+            added_handlers.remove(original_handler)
+    for logger_name, handler_name in added_handlers:
+        observer.add("logging", f"added {handler_name} handler to {logger_name}")
+    for number, signal_handler in after.signal_handlers.items():
+        if before.signal_handlers.get(number) != signal_handler:
+            observer.add("signal", f"{_signal_name(number)} handler changed", confidence="medium")
+
+
+def run_probe(module: str, report_path: Path) -> int:
+    observer = _Observer(module, report_path)
+    sys.addaudithook(observer.audit)
+    original_thread_start = threading.Thread.start
+    original_process_start = multiprocessing.process.BaseProcess.start
+
+    def thread_start(thread: threading.Thread, *args: Any, **kwargs: Any) -> Any:
+        observer.add("thread", thread.name or type(thread).__name__)
+        return original_thread_start(thread, *args, **kwargs)
+
+    def process_start(
+        process: multiprocessing.process.BaseProcess, *args: Any, **kwargs: Any
+    ) -> Any:
+        observer.add("multiprocessing", process.name or type(process).__name__)
+        return original_process_start(process, *args, **kwargs)
+
+    threading.Thread.start = thread_start  # type: ignore[assignment]
+    multiprocessing.process.BaseProcess.start = process_start  # type: ignore[assignment]
+    before = _snapshot()
+    observer.active = True
+    started = time.perf_counter()
+    success = True
+    exception_type: str | None = None
+    exception_message: str | None = None
+    try:
+        importlib.import_module(module)
+    except BaseException as error:
+        success = False
+        exception_type = type(error).__name__
+        exception_message = _redact(str(error))[:1000]
+    duration_ms = (time.perf_counter() - started) * 1000
+    after = _snapshot()
+    _compare(observer, before, after)
+    observer.active = False
+    threading.Thread.start = original_thread_start  # type: ignore[method-assign]
+    multiprocessing.process.BaseProcess.start = original_process_start  # type: ignore[method-assign]
+    imported_modules = tuple(sorted(after.modules - before.modules))
+    report = ImportReport(
+        module=module,
+        duration_ms=duration_ms,
+        effects=tuple(observer.effects),
+        imported_modules=imported_modules,
+        success=success,
+        exception_type=exception_type,
+        exception_message=exception_message,
+        platform=platform.platform(),
+        python_version=platform.python_version(),
+    )
+    report_path.write_text(json.dumps(asdict(report), sort_keys=True), encoding="utf-8")
+    return 0
+
+
+def _path(value: Any) -> str:
+    try:
+        return os.path.abspath(os.fsdecode(value))
+    except (TypeError, ValueError):
+        return "<unprintable path>"
+
+
+def _address(value: Any) -> str:
+    if isinstance(value, tuple) and len(value) >= 2:
+        return f"{value[0]}:{value[1]}"
+    return str(value)
+
+
+def _command(executable: Any, arguments: Any) -> str:
+    if isinstance(arguments, (list, tuple)):
+        rendered = " ".join(str(item) for item in arguments[:12])
+        return rendered or str(executable)
+    if isinstance(arguments, (str, bytes)):
+        return os.fsdecode(arguments)
+    return str(executable)
+
+
+def _redact(value: str) -> str:
+    return _SECRET_RE.sub(lambda match: f"{match.group(1)}{match.group(2)}<redacted>", value)
+
+
+def _is_internal_write(path: str, report_path: Path) -> bool:
+    return Path(path) == report_path or _is_runtime_path(path)
+
+
+def _is_runtime_path(path: str) -> bool:
+    return path.endswith((".pyc", ".pyo")) or "__pycache__" in path
+
+
+def _available_signals() -> list[int]:
+    values: list[int] = []
+    for member in signal.Signals:
+        try:
+            signal.getsignal(member.value)
+        except (OSError, RuntimeError, ValueError):
+            continue
+        values.append(member.value)
+    return values
+
+
+def _handler_name(handler: Any) -> str:
+    if handler in {signal.SIG_DFL, signal.SIG_IGN, None}:
+        return str(handler)
+    return getattr(handler, "__qualname__", type(handler).__name__)
+
+
+def _signal_name(number: int) -> str:
+    try:
+        return signal.Signals(number).name
+    except ValueError:
+        return str(number)
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = sys.argv[1:] if argv is None else argv
+    if len(arguments) != 2:
+        return 2
+    return run_probe(arguments[0], Path(arguments[1]))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

import_effects/cli.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import json
+import os
+import sys
+from collections import Counter
+from collections.abc import Sequence
+from dataclasses import replace
+
+from . import __version__
+from .inspector import InspectionError, inspect_import
+from .models import EffectKind, ImportReport
+
+_KINDS: tuple[EffectKind, ...] = (
+    "file-write",
+    "file-delete",
+    "file-rename",
+    "directory",
+    "network",
+    "subprocess",
+    "thread",
+    "multiprocessing",
+    "environment",
+    "cwd",
+    "logging",
+    "sys-path",
+    "warnings",
+    "signal",
+)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="import-effects",
+        description="See what Python does when you import.",
+        epilog=(
+            "Warning: the target module executes with your normal OS permissions. "
+            "This is not a sandbox."
+        ),
+    )
+    parser.add_argument("module", nargs="?", help="already-importable module or package")
+    parser.add_argument("--json", action="store_true", help="emit a machine-readable report")
+    parser.add_argument("--quiet", action="store_true", help="show only the summary or error")
+    parser.add_argument(
+        "--verbose", action="store_true", help="show attribution and imported modules"
+    )
+    parser.add_argument("--timeout", type=float, default=10.0, metavar="SECONDS")
+    parser.add_argument(
+        "--fail-on",
+        default="",
+        metavar="KINDS",
+        help="comma-separated effect kinds that should exit 1",
+    )
+    parser.add_argument(
+        "--ignore",
+        action="append",
+        default=[],
+        metavar="GLOB",
+        help="ignore matching effect details; may be repeated",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _parser()
+    arguments = parser.parse_args(argv)
+    if not arguments.module:
+        parser.error("the following arguments are required: module")
+    if arguments.timeout <= 0:
+        parser.error("--timeout must be greater than zero")
+    try:
+        fail_on = _parse_fail_on(arguments.fail_on)
+    except ValueError as error:
+        parser.error(str(error))
+    try:
+        report = inspect_import(arguments.module, timeout=arguments.timeout)
+    except ValueError as error:
+        parser.error(str(error))
+    except InspectionError as error:
+        print(f"import-effects: internal inspection failure: {error}", file=sys.stderr)
+        return 4
+    report = _apply_ignores(report, arguments.ignore)
+    if arguments.json:
+        _print_safe(json.dumps(report.to_dict(), indent=2, sort_keys=True))
+    else:
+        _print_safe(_format_text(report, quiet=arguments.quiet, verbose=arguments.verbose))
+    if not report.success:
+        return 3
+    if any(effect.kind in fail_on for effect in report.effects):
+        return 1
+    return 0
+
+
+def _parse_fail_on(value: str) -> set[EffectKind]:
+    if not value:
+        return set()
+    result: set[EffectKind] = set()
+    for raw in value.split(","):
+        kind = raw.strip()
+        if kind not in _KINDS:
+            choices = ", ".join(_KINDS)
+            raise ValueError(f"unknown --fail-on kind {kind!r}; choose from: {choices}")
+        result.add(kind)
+    return result
+
+
+def _apply_ignores(report: ImportReport, patterns: Sequence[str]) -> ImportReport:
+    expanded = [os.path.expanduser(pattern) for pattern in patterns]
+    if not expanded:
+        return report
+    effects = tuple(
+        effect
+        for effect in report.effects
+        if not any(fnmatch.fnmatch(effect.detail, pattern) for pattern in expanded)
+    )
+    return replace(report, effects=effects)
+
+
+def _format_text(report: ImportReport, *, quiet: bool, verbose: bool) -> str:
+    lines = [f"import {report.module}", ""]
+    if report.timed_out:
+        lines.append(f"✗ timed out after {report.duration_ms / 1000:g} s")
+    elif report.success:
+        lines.append(f"✓ imported in {report.duration_ms:.0f} ms")
+    else:
+        detail = report.exception_message or "unknown error"
+        lines.append(f"✗ {report.exception_type or 'ImportError'}: {detail}")
+    if quiet:
+        lines.extend(["", _summary(report)])
+        return "\n".join(lines)
+    if report.effects:
+        lines.extend(["", "SIDE EFFECTS"])
+        for effect in report.effects:
+            lines.extend(["", f"⚠ {effect.kind.upper().replace('-', ' ')}", f"  {effect.detail}"])
+            if verbose:
+                source = effect.source or "unknown source"
+                lines.append(
+                    f"  {effect.attribution}; {effect.confidence} confidence; source: {source}"
+                )
+    if verbose and report.imported_modules:
+        lines.extend(["", f"IMPORTED MODULES ({len(report.imported_modules)})"])
+        lines.append("  " + ", ".join(report.imported_modules))
+    if report.child_stdout:
+        lines.extend(["", "TARGET STDOUT", _indent(report.child_stdout.rstrip())])
+    if report.child_stderr:
+        lines.extend(["", "TARGET STDERR", _indent(report.child_stderr.rstrip())])
+    lines.extend(["", _summary(report)])
+    return "\n".join(lines)
+
+
+def _summary(report: ImportReport) -> str:
+    count = len(report.effects)
+    if count == 0:
+        return "No side effects detected"
+    counts = Counter(effect.kind for effect in report.effects)
+    kinds = " · ".join(f"{amount} {kind}" for kind, amount in sorted(counts.items()))
+    noun = "effect" if count == 1 else "effects"
+    return f"{count} side {noun} detected · {kinds}"
+
+
+def _indent(value: str) -> str:
+    return "\n".join(f"  {line}" for line in value.splitlines())
+
+
+def _print_safe(value: str) -> None:
+    encoding = sys.stdout.encoding or "utf-8"
+    printable = value.encode(encoding, errors="replace").decode(encoding)
+    print(printable)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

import_effects/inspector.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import signal
+import subprocess
+import sys
+import tempfile
+from collections.abc import Iterable
+from pathlib import Path
+
+from .models import EffectKind, ImportReport
+
+_MODULE_RE = re.compile(r"^[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*$")
+
+
+class InspectionError(RuntimeError):
+    """Raised when the isolated inspector cannot produce a valid report."""
+
+
+def _validate_module(module: str) -> None:
+    if not _MODULE_RE.fullmatch(module):
+        raise ValueError(f"Invalid module name: {module!r}")
+
+
+def inspect_import(
+    module: str,
+    *,
+    timeout: float = 10.0,
+    python_executable: str | os.PathLike[str] | None = None,
+) -> ImportReport:
+    """Inspect one import in a fresh child interpreter.
+
+    The target module is never imported into the caller. This is observation, not a
+    security sandbox: target code executes with the child's normal OS permissions.
+    """
+
+    _validate_module(module)
+    if timeout <= 0:
+        raise ValueError("timeout must be greater than zero")
+    executable = os.fspath(python_executable or sys.executable)
+    with tempfile.TemporaryDirectory(prefix="import-effects-") as directory:
+        report_path = Path(directory) / "report.json"
+        command = [executable, "-m", "import_effects._probe", module, os.fspath(report_path)]
+        try:
+            process = subprocess.Popen(
+                command,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                start_new_session=os.name == "posix",
+                creationflags=(
+                    getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0) if os.name == "nt" else 0
+                ),
+            )
+        except OSError as error:
+            raise InspectionError(f"Could not start child interpreter: {error}") from error
+        try:
+            stdout, stderr = process.communicate(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            _terminate_process_tree(process)
+            stdout, stderr = process.communicate()
+            return ImportReport(
+                module=module,
+                duration_ms=timeout * 1000,
+                success=False,
+                timed_out=True,
+                exception_type="TimeoutExpired",
+                exception_message=f"Import exceeded {timeout:g} seconds.",
+                child_stdout=_limit_output(stdout),
+                child_stderr=_limit_output(stderr),
+                platform=sys.platform,
+                python_version=sys.version.split()[0],
+            )
+        if not report_path.exists():
+            raise InspectionError(
+                f"Inspector exited with code {process.returncode} without producing a report."
+            )
+        try:
+            payload = json.loads(report_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise InspectionError("Inspector produced an unreadable report.") from error
+        payload["child_stdout"] = _limit_output(stdout)
+        payload["child_stderr"] = _limit_output(stderr)
+        return ImportReport.from_dict(payload)
+
+
+def assert_no_effects(
+    module: str,
+    *,
+    forbidden: Iterable[EffectKind] = ("network", "subprocess", "file-write"),
+    timeout: float = 10.0,
+) -> ImportReport:
+    """Inspect *module* and raise AssertionError for forbidden effects or import failure."""
+
+    report = inspect_import(module, timeout=timeout)
+    if not report.success:
+        message = report.exception_message or "unknown import failure"
+        raise AssertionError(f"Import of {module!r} failed: {message}")
+    forbidden_set = set(forbidden)
+    found = [effect for effect in report.effects if effect.kind in forbidden_set]
+    if found:
+        summary = ", ".join(sorted({effect.kind for effect in found}))
+        raise AssertionError(f"Import of {module!r} produced forbidden effects: {summary}")
+    return report
+
+
+def _terminate_process_tree(process: subprocess.Popen[str]) -> None:
+    try:
+        if os.name == "posix":
+            os.killpg(process.pid, signal.SIGKILL)
+        else:  # pragma: no cover - exercised by Windows CI
+            process.kill()
+    except ProcessLookupError:
+        pass
+
+
+def _limit_output(value: str, limit: int = 16_384) -> str:
+    if len(value) <= limit:
+        return value
+    return value[:limit] + "\n... output truncated by import-effects ..."

import_effects/models.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass, field
+from typing import Any, Literal
+
+EffectKind = Literal[
+    "file-write",
+    "file-delete",
+    "file-rename",
+    "directory",
+    "network",
+    "subprocess",
+    "thread",
+    "multiprocessing",
+    "environment",
+    "cwd",
+    "logging",
+    "sys-path",
+    "warnings",
+    "signal",
+]
+Confidence = Literal["high", "medium", "low"]
+Attribution = Literal["target", "dependency", "observed-during-import", "runtime"]
+
+
+@dataclass(frozen=True, slots=True)
+class Effect:
+    kind: EffectKind
+    detail: str
+    source: str | None = None
+    confidence: Confidence = "high"
+    attribution: Attribution = "observed-during-import"
+    metadata: Mapping[str, str | int | float | bool | None] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> Effect:
+        return cls(
+            kind=value["kind"],
+            detail=str(value["detail"]),
+            source=value.get("source"),
+            confidence=value.get("confidence", "high"),
+            attribution=value.get("attribution", "observed-during-import"),
+            metadata=value.get("metadata", {}),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ImportReport:
+    module: str
+    duration_ms: float
+    effects: tuple[Effect, ...] = ()
+    imported_modules: tuple[str, ...] = ()
+    success: bool = True
+    exception_type: str | None = None
+    exception_message: str | None = None
+    timed_out: bool = False
+    child_stdout: str = ""
+    child_stderr: str = ""
+    platform: str = ""
+    python_version: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ImportReport:
+        return cls(
+            module=str(value["module"]),
+            duration_ms=float(value.get("duration_ms", 0)),
+            effects=tuple(Effect.from_dict(item) for item in value.get("effects", [])),
+            imported_modules=tuple(value.get("imported_modules", [])),
+            success=bool(value.get("success", False)),
+            exception_type=value.get("exception_type"),
+            exception_message=value.get("exception_message"),
+            timed_out=bool(value.get("timed_out", False)),
+            child_stdout=str(value.get("child_stdout", "")),
+            child_stderr=str(value.get("child_stderr", "")),
+            platform=str(value.get("platform", "")),
+            python_version=str(value.get("python_version", "")),
+        )
+
+    def effects_of(self, *kinds: EffectKind) -> tuple[Effect, ...]:
+        wanted = set(kinds)
+        return tuple(effect for effect in self.effects if effect.kind in wanted)

import_effects/py.typed

@@ -0,0 +1 @@
+

import_effects-0.0.1.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: import-effects
+Version: 0.0.1
+Summary: See what Python does when you import.
+Project-URL: Homepage, https://github.com/royalpinto007/import-effects
+Project-URL: Documentation, https://github.com/royalpinto007/import-effects#readme
+Project-URL: Issues, https://github.com/royalpinto007/import-effects/issues
+Project-URL: Source, https://github.com/royalpinto007/import-effects
+Author-email: Royal Pinto <royalpinto007@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audit-hooks,cli,debugging,imports,observability,python,security,side-effects,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.3; extra == 'dev'
+Requires-Dist: mypy>=1.17; extra == 'dev'
+Requires-Dist: pytest-cov>=6.2; extra == 'dev'
+Requires-Dist: pytest>=8.4; extra == 'dev'
+Requires-Dist: ruff>=0.12; extra == 'dev'
+Requires-Dist: twine>=6.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# import-effects
+
+> See what Python does when you `import`.
+
+[![PyPI](https://img.shields.io/pypi/v/import-effects)](https://pypi.org/project/import-effects/) [![Python](https://img.shields.io/pypi/pyversions/import-effects)](https://pypi.org/project/import-effects/) [![CI](https://github.com/royalpinto007/import-effects/actions/workflows/ci.yml/badge.svg)](https://github.com/royalpinto007/import-effects/actions/workflows/ci.yml) [![license](https://img.shields.io/pypi/l/import-effects)](LICENSE)
+
+`import-effects` runs one import in a fresh child interpreter and reports file writes, sockets, subprocesses, threads, environment changes, and other observable import-time behavior.
+
+```bash
+pip install import-effects
+import-effects requests
+```
+
+![A Python import starts a thread, opens a socket, writes a file, and launches a subprocess](docs/assets/demo.gif)
+
+## 30-second quickstart
+
+```console
+$ import-effects mypackage
+import mypackage
+
+✓ imported in 143 ms
+
+SIDE EFFECTS
+
+⚠ FILE WRITE
+  /home/me/.cache/mypackage/config.json
+
+⚠ NETWORK
+  api.example.com:443
+
+⚠ THREAD
+  background-worker
+
+3 side effects detected · 1 file-write · 1 network · 1 thread
+```
+
+The target must already be importable. `import-effects` never installs it and normal inspection needs no server, database, Docker, network access, or elevated privileges.
+
+## CLI
+
+```bash
+import-effects package.submodule
+import-effects requests --json
+import-effects requests --quiet
+import-effects requests --verbose
+import-effects requests --timeout 10
+import-effects requests --fail-on network,subprocess,file-write
+import-effects requests --ignore '~/.cache/**'
+```
+
+`--fail-on` turns selected observations into policy failures without pretending every observation is inherently unsafe. `--ignore` matches the human-readable effect detail and may be repeated.
+
+Exit codes:
+
+| Code | Meaning                                           |
+| ---: | ------------------------------------------------- |
+|    0 | Import succeeded with no configured violation    |
+|    1 | A configured `--fail-on` effect was detected     |
+|    2 | Invalid CLI input                                |
+|    3 | Target import failed or timed out                |
+|    4 | Internal inspector failure                       |
+
+## Python API
+
+```python
+from import_effects import inspect_import
+
+report = inspect_import("mypackage", timeout=10)
+
+print(report.duration_ms)
+for effect in report.effects:
+    print(effect.kind, effect.detail, effect.confidence)
+```
+
+For tests:
+
+```python
+from import_effects import assert_no_effects
+
+
+def test_import_stays_quiet() -> None:
+    assert_no_effects("mypackage", forbidden=("network", "subprocess", "file-write"))
+```
+
+The models are frozen, typed dataclasses. Reports can be converted with `report.to_dict()` and filtered with `report.effects_of("network")`.
+
+## What it observes
+
+- files opened for writing, removal, rename, and directory operations
+- socket connect, bind, and DNS activity
+- subprocess spawning, `os.system`, and process forks
+- Python threads and `multiprocessing` children started
+- environment variable names added, removed, or changed, never their values
+- current directory, logging handlers, `sys.path`, warning filters, and signal handlers
+- newly imported module names, import duration, stdout/stderr, failures, crashes, and timeouts
+
+CPython audit events provide high-confidence observations for many OS operations. Before/after snapshots and lifecycle wrappers cover state changes and thread/process starts. Each effect includes confidence and attribution metadata because an effect may come from the target, one of its dependencies, or code merely observed during the import window.
+
+See [Architecture and limitations](docs/architecture.md) and the [API reference](docs/api.md).
+
+## Security warning
+
+**Importing untrusted Python code executes that code. `import-effects` is an observer, not a sandbox.**
+
+The target runs in a separate child interpreter, so it cannot directly mutate the parent Python process. It still runs as your user with normal filesystem, network, and process permissions. Use an OS sandbox or disposable virtual machine when inspecting code you do not trust.
+
+Target stdout and stderr are capped. Suspected credentials in captured messages are redacted, and environment variable values are never included. Audit hooks are visibility mechanisms, not a security boundary, and sufficiently hostile native code can evade or disable Python-level observation.
+
+## Platform support
+
+`import-effects` targets CPython 3.10 through 3.14 on Linux, macOS, and Windows. Audit event availability and process termination behavior differ by Python and OS. Linux currently provides the broadest coverage. Windows does not offer the same process-group cleanup guarantees as POSIX, and some native extensions perform operations below CPython's audit surface.
+
+## Development
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e '.[dev]'
+ruff format --check .
+ruff check .
+mypy
+pytest --cov
+python -m build
+twine check dist/*
+```
+
+See [Contributing](CONTRIBUTING.md), [Security](SECURITY.md), and the [Changelog](CHANGELOG.md).
+
+## License
+
+MIT
+

import_effects-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+import_effects/__init__.py,sha256=b9QPB7Y_v7r4TXYrbfBG4iuGmI_KHL2WDe6IctEBZBU,349
+import_effects/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+import_effects/_probe.py,sha256=XLzzo_dvozo7I9_4SOFH24n1zIYwI0_bGLOrwbiwiE4,11976
+import_effects/cli.py,sha256=tgZuxbdRP5TqXdJio4ZulklfxQg7NkY1WO2q8pygx-4,5997
+import_effects/inspector.py,sha256=_ftQ20NfX8NjbTnzjOKVMYHFR5E4UvHcqK_HisqrBXg,4518
+import_effects/models.py,sha256=yUDrdTb0OjbuBViEmJd_W1auWvH5zXPftsdT8djtm-U,2752
+import_effects/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+import_effects-0.0.1.dist-info/METADATA,sha256=7Xsbo-FJ4eVv2weEEDKcRcG36Q4-VY1GyjPKEo833xA,6834
+import_effects-0.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+import_effects-0.0.1.dist-info/entry_points.txt,sha256=Vsz30VUGVhVjYPek7PrmseTggoA5MYg19B6bzLGjXzw,59
+import_effects-0.0.1.dist-info/licenses/LICENSE,sha256=BEKTFnGcu1Vx4zP9S43oph8H13Mlz0gJr9u_lAKnrTk,1069
+import_effects-0.0.1.dist-info/RECORD,,

import_effects-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

import_effects-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+import-effects = import_effects.cli:main

import_effects-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Royal Pinto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+