ipinb 0.1.0__py3-none-any.whl

ipi/__init__.py

@@ -0,0 +1,5 @@
+"""IPi: persistent IPython kernels for MCP agents."""
+
+from toolfuncs import import_path
+
+__all__ = ("import_path",)

ipi/_ansi.py

@@ -0,0 +1,274 @@
+"""ANSI/control-sequence removal for model-facing text."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Literal, cast
+
+_AnsiState = Literal[
+    "text",
+    "escape",
+    "escape_intermediate",
+    "csi",
+    "osc",
+    "control_string",
+    "string_escape",
+]
+_ControlStringState = Literal["osc", "control_string"]
+
+_HEX_DIGITS = frozenset("0123456789abcdefABCDEF")
+_OCTAL_DIGITS = frozenset("01234567")
+_CONTROL_STRING_ESC_STARTS = frozenset({"P", "X", "^", "_"})
+_CONTROL_STRING_C1_STARTS = frozenset({"\x90", "\x98", "\x9e", "\x9f"})
+_C1_RE = re.compile("[\x80-\x9f]")
+
+
+class _SerializedControlDecoder:
+    """Decode printable Python/JSON spellings of ESC and C1 controls."""
+
+    def __init__(self) -> None:
+        self._pending = ""
+        self._serialized_escape_width: int | None = None
+
+    def feed(self, text: str) -> str:
+        if not self._pending and self._serialized_escape_width is None and "\\" not in text:
+            return text
+        source = self._pending + text
+        self._pending = ""
+        output: list[str] = []
+        index = 0
+
+        while index < len(source):
+            slash = source.find("\\", index)
+            if slash < 0:
+                output.append(source[index:])
+                if source[index:]:
+                    self._serialized_escape_width = None
+                break
+            if prefix := source[index:slash]:
+                output.append(prefix)
+                self._serialized_escape_width = None
+
+            after_slashes = slash
+            while after_slashes < len(source) and source[after_slashes] == "\\":
+                after_slashes += 1
+            if after_slashes == len(source):
+                self._pending = source[slash:]
+                break
+
+            consumed, control = _decode_serialized_control(source, after_slashes)
+            if consumed < 0:
+                self._pending = source[slash:]
+                break
+            slash_count = after_slashes - slash
+            if self._serialized_escape_width is not None and control is None:
+                # repr()/JSON doubles both the leading slash in a serialized ESC
+                # and the slash in its ESC + "\\" string terminator at each
+                # nesting layer. Decode only the terminator's source characters;
+                # any remaining slashes are visible text and must stay serialized.
+                terminator_width = min(slash_count, 2 * self._serialized_escape_width)
+                output.append("\\")
+                output.append("\\" * (slash_count - terminator_width))
+                self._serialized_escape_width = None
+                index = after_slashes
+                continue
+            if consumed == 0:
+                output.append(source[slash:after_slashes])
+                index = after_slashes
+                continue
+            if control is None:
+                output.append(source[slash : after_slashes + consumed])
+            else:
+                # Consume the complete slash run so nested repr()/JSON layers
+                # collapse to the one control character they represent.
+                output.append(control)
+                self._serialized_escape_width = slash_count if control == "\x1b" else None
+            index = after_slashes + consumed
+
+        return "".join(output)
+
+    def finish(self) -> str:
+        pending, self._pending = self._pending, ""
+        if self._serialized_escape_width is not None and pending and set(pending) == {"\\"}:
+            terminator_width = min(len(pending), 2 * self._serialized_escape_width)
+            pending = "\\" + "\\" * (len(pending) - terminator_width)
+        self._serialized_escape_width = None
+        return pending
+
+
+def _decode_serialized_control(source: str, index: int) -> tuple[int, str | None]:
+    """Return ``(consumed, control)``; ``consumed == -1`` means incomplete."""
+
+    lead = source[index]
+    widths = {"x": 2, "u": 4, "U": 8}
+    if (width := widths.get(lead)) is not None:
+        end = index + 1 + width
+        digits = source[index + 1 : end]
+        if end > len(source):
+            return (
+                (-1, None) if all(character in _HEX_DIGITS for character in digits) else (1, None)
+            )
+        if any(character not in _HEX_DIGITS for character in digits):
+            return 1, None
+        return 1 + width, _control_character(int(digits, 16))
+
+    if lead in "0123":
+        end = index + 3
+        digits = source[index:end]
+        if end > len(source):
+            return (
+                (-1, None) if all(character in _OCTAL_DIGITS for character in digits) else (1, None)
+            )
+        if any(character not in _OCTAL_DIGITS for character in digits):
+            return 1, None
+        return 3, _control_character(int(digits, 8))
+
+    return 0, None
+
+
+def _control_character(codepoint: int) -> str | None:
+    if codepoint == 0x1B or 0x80 <= codepoint <= 0x9F:
+        return chr(codepoint)
+    return None
+
+
+def _contains_c1(text: str) -> bool:
+    return _C1_RE.search(text) is not None
+
+
+class _AnsiControlStripper:
+    """Incrementally remove ECMA-48 controls while retaining visible text."""
+
+    def __init__(self) -> None:
+        self._state: _AnsiState = "text"
+        self._control_string_state: _ControlStringState | None = None
+
+    def feed(self, text: str) -> str:
+        if self._state == "text" and "\x1b" not in text and not _contains_c1(text):
+            return text
+        output: list[str] = []
+        for character in text:
+            self._consume(character, output)
+        return "".join(output)
+
+    def finish(self) -> str:
+        # An unfinished control sequence has no visible terminal representation.
+        self._state = "text"
+        self._control_string_state = None
+        return ""
+
+    def _consume(self, character: str, output: list[str]) -> None:
+        state = self._state
+        codepoint = ord(character)
+
+        if state == "text":
+            if character == "\x1b":
+                self._state = "escape"
+            elif character == "\x9b":
+                self._state = "csi"
+            elif character == "\x9d":
+                self._state = "osc"
+            elif character in _CONTROL_STRING_C1_STARTS:
+                self._state = "control_string"
+            elif not 0x80 <= codepoint <= 0x9F:
+                output.append(character)
+            return
+
+        if state == "escape":
+            if character == "[":
+                self._state = "csi"
+            elif character == "]":
+                self._state = "osc"
+            elif character in _CONTROL_STRING_ESC_STARTS:
+                self._state = "control_string"
+            elif "\x20" <= character <= "\x2f":
+                self._state = "escape_intermediate"
+            elif "\x30" <= character <= "\x7e":
+                self._state = "text"
+            elif character != "\x1b":
+                self._state = "text"
+                self._consume(character, output)
+            return
+
+        if state == "escape_intermediate":
+            if "\x20" <= character <= "\x2f":
+                return
+            self._state = "text"
+            if not "\x30" <= character <= "\x7e":
+                self._consume(character, output)
+            return
+
+        if state == "csi":
+            if "\x30" <= character <= "\x3f" or "\x20" <= character <= "\x2f":
+                return
+            if "\x40" <= character <= "\x7e":
+                self._state = "text"
+            elif character == "\x1b":
+                self._state = "escape"
+            else:
+                self._state = "text"
+                self._consume(character, output)
+            return
+
+        if state in {"osc", "control_string"}:
+            if character == "\x9c" or (state == "osc" and character == "\x07"):
+                self._state = "text"
+            elif character == "\x1b":
+                self._control_string_state = cast(_ControlStringState, state)
+                self._state = "string_escape"
+            return
+
+        if state == "string_escape":
+            if character in {"\\", "\x9c"}:
+                self._state = "text"
+                self._control_string_state = None
+            elif character != "\x1b":
+                self._state = self._control_string_state or "control_string"
+            return
+
+        raise AssertionError(f"unknown ANSI parser state: {state}")
+
+
+class AnsiSanitizer:
+    """Incrementally strip actual and serialized ANSI control sequences."""
+
+    def __init__(self) -> None:
+        self._decoder = _SerializedControlDecoder()
+        self._stripper = _AnsiControlStripper()
+
+    def feed(self, text: str) -> str:
+        """Consume one text chunk and return currently complete visible text."""
+
+        return self._stripper.feed(self._decoder.feed(text))
+
+    def finish(self) -> str:
+        """Finish the stream, preserving incomplete plain text and dropping controls."""
+
+        return self._stripper.feed(self._decoder.finish()) + self._stripper.finish()
+
+
+def strip_ansi(text: str) -> str:
+    """Remove actual or serialized ANSI controls from complete text."""
+
+    sanitizer = AnsiSanitizer()
+    return sanitizer.feed(text) + sanitizer.finish()
+
+
+def strip_ansi_deep(value: Any) -> Any:
+    """Recursively strip ANSI controls from string keys and values in JSON-like data."""
+
+    if isinstance(value, str):
+        return strip_ansi(value)
+    if isinstance(value, list):
+        return [strip_ansi_deep(item) for item in cast(list[Any], value)]
+    if isinstance(value, tuple):
+        return tuple(strip_ansi_deep(item) for item in cast(tuple[Any, ...], value))
+    if isinstance(value, dict):
+        return {
+            strip_ansi(key) if isinstance(key, str) else key: strip_ansi_deep(item)
+            for key, item in cast(dict[Any, Any], value).items()
+        }
+    return value
+
+
+__all__ = ["AnsiSanitizer", "strip_ansi", "strip_ansi_deep"]

ipi/_dependency_metadata.py

@@ -0,0 +1,149 @@
+"""Dependency metadata for local plugins."""
+
+from __future__ import annotations
+
+import re
+import sys
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
+from packaging.version import Version
+
+from ipi._toml import TomlParseError, read_toml, read_toml_text
+
+# The canonical PEP 723 block shape, restricted to standardized ``script``
+# blocks when extracting dependency metadata.
+_PEP723_BLOCK = re.compile(
+    r"(?m)^# /// (?P<type>[a-zA-Z0-9-]+)[ \t]*$[\r\n]"
+    r"(?P<content>(?:^#(?:| .*)$[\r\n]?)+)^# ///[ \t]*$"
+)
+
+
+class DependencyMetadataError(ValueError):
+    """A Python source's dependency declaration is invalid."""
+
+
+@dataclass(frozen=True, slots=True)
+class DependencyDeclaration:
+    """Validated dependencies declared by one Python source."""
+
+    requirements: tuple[str, ...]
+    requires_python: str | None
+    source: str
+
+    def __bool__(self) -> bool:
+        return bool(self.requirements)
+
+
+def script_dependencies(module_path: Path) -> DependencyDeclaration:
+    """Read PEP 723 dependency metadata from one Python file."""
+
+    source = str(module_path)
+    try:
+        text = module_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise DependencyMetadataError(f"could not read Python source {source}: {exc}") from exc
+
+    blocks = [match for match in _PEP723_BLOCK.finditer(text) if match.group("type") == "script"]
+    if not blocks:
+        return DependencyDeclaration((), None, source)
+    if len(blocks) > 1:
+        raise DependencyMetadataError(
+            f"Python source {source} contains more than one PEP 723 'script' block"
+        )
+
+    content = "\n".join(
+        line[2:] if line.startswith("# ") else line[1:]
+        for line in blocks[0].group("content").splitlines()
+    )
+    try:
+        data = read_toml_text(content)
+    except TomlParseError as exc:
+        raise DependencyMetadataError(
+            f"Python source {source} has an invalid PEP 723 'script' block: {exc}"
+        ) from exc
+    if data is None:
+        raise DependencyMetadataError(
+            f"Python source {source} has a PEP 723 'script' block that is not a TOML table"
+        )
+    return _declaration_from_table(data, source=f"{source} (PEP 723 script block)")
+
+
+def project_dependencies(pyproject_path: Path) -> DependencyDeclaration:
+    """Read ``[project]`` dependencies from one adjacent ``pyproject.toml``."""
+
+    source = str(pyproject_path)
+    try:
+        data = read_toml(pyproject_path)
+    except TomlParseError as exc:
+        raise DependencyMetadataError(f"invalid pyproject at {source}: {exc}") from exc
+    if data is None:
+        return DependencyDeclaration((), None, source)
+    raw_project = data.get("project")
+    if raw_project is None:
+        return DependencyDeclaration((), None, source)
+    if not isinstance(raw_project, Mapping):
+        raise DependencyMetadataError(f"{source}: [project] must be a table")
+    return _declaration_from_table(cast(Mapping[str, object], raw_project), source=source)
+
+
+def _declaration_from_table(
+    table: Mapping[str, object],
+    *,
+    source: str,
+) -> DependencyDeclaration:
+    raw_dependencies = table.get("dependencies", [])
+    if not isinstance(raw_dependencies, list):
+        raise DependencyMetadataError(f"{source}: 'dependencies' must be a list of strings")
+
+    requirements: list[str] = []
+    for raw in cast(list[object], raw_dependencies):
+        if not isinstance(raw, str):
+            raise DependencyMetadataError(f"{source}: 'dependencies' must be a list of strings")
+        requirement_text = raw.strip()
+        if not requirement_text:
+            raise DependencyMetadataError(f"{source}: dependency entries must be nonempty")
+        try:
+            Requirement(requirement_text)
+        except InvalidRequirement as exc:
+            raise DependencyMetadataError(
+                f"{source}: invalid dependency requirement {requirement_text!r}: {exc}"
+            ) from exc
+        requirements.append(requirement_text)
+
+    requires_python: str | None = None
+    raw_requires_python = table.get("requires-python")
+    if raw_requires_python is not None:
+        if not isinstance(raw_requires_python, str):
+            raise DependencyMetadataError(f"{source}: 'requires-python' must be a string")
+        requires_python = raw_requires_python.strip()
+        _require_compatible_python(requires_python, source=source)
+
+    return DependencyDeclaration(tuple(requirements), requires_python, source)
+
+
+def _require_compatible_python(specifier_text: str, *, source: str) -> None:
+    try:
+        specifier = SpecifierSet(specifier_text)
+    except InvalidSpecifier as exc:
+        raise DependencyMetadataError(
+            f"{source}: invalid 'requires-python' specifier {specifier_text!r}"
+        ) from exc
+    interpreter = Version(".".join(str(part) for part in sys.version_info[:3]))
+    if not specifier.contains(interpreter, prereleases=True):
+        raise DependencyMetadataError(
+            f"{source}: 'requires-python' {specifier_text!r} does not admit the running "
+            f"interpreter {interpreter}"
+        )
+
+
+__all__ = [
+    "DependencyDeclaration",
+    "DependencyMetadataError",
+    "project_dependencies",
+    "script_dependencies",
+]

ipi/_exception_groups.py

@@ -0,0 +1,12 @@
+"""Python 3.10/3.11-compatible exception-group types."""
+
+from __future__ import annotations
+
+import sys
+
+if sys.version_info < (3, 11):
+    from exceptiongroup import BaseExceptionGroup, ExceptionGroup
+else:
+    from builtins import BaseExceptionGroup, ExceptionGroup
+
+__all__ = ["BaseExceptionGroup", "ExceptionGroup"]

ipi/_git_provenance.py

@@ -0,0 +1,122 @@
+"""Credential-aware, immutable Git source reconstruction from PEP 610 metadata."""
+
+from __future__ import annotations
+
+from urllib.parse import ParseResult, urldefrag, urlparse
+
+from packaging.requirements import InvalidRequirement, Requirement
+
+
+def authenticated_git_source(
+    metadata_url: str,
+    *,
+    configured_requirement: str | None,
+    configured_name: str,
+    missing_requirement_name: str,
+    purpose: str,
+    repository_label: str = "installed IPi Git repository",
+    install_subject: str = "IPi",
+) -> str:
+    """Recover credentials only from a configured requirement for the same repository."""
+
+    if configured_requirement is None:
+        if has_redacted_credentials(metadata_url):
+            raise RuntimeError(
+                f"{purpose} cannot use Git provenance with redacted credentials. Set "
+                f"{missing_requirement_name} to the authenticated Git requirement used "
+                f"to install {install_subject}."
+            )
+        return metadata_url
+
+    candidate = requirement_url(configured_requirement)
+    if candidate is None or not same_git_repository(candidate, metadata_url):
+        raise RuntimeError(f"{configured_name} does not select the {repository_label}")
+    return candidate
+
+
+def requirement_url(value: str) -> str | None:
+    """Extract a PEP 508 URL, accepting a bare VCS URL for launcher compatibility."""
+
+    text = value.strip()
+    try:
+        requirement = Requirement(text)
+    except InvalidRequirement:
+        requirement = None
+    if requirement is not None:
+        return requirement.url
+    return text if urlparse(text).scheme.casefold().startswith("git+") else None
+
+
+def has_redacted_credentials(url: str) -> bool:
+    """Return whether URL user information contains uv's credential redaction marker."""
+
+    parsed = urlparse(url)
+    userinfo = parsed.netloc.rpartition("@")[0] if "@" in parsed.netloc else ""
+    return "****" in userinfo
+
+
+def strip_redacted_git_credentials(url: str) -> str:
+    """Remove invalid redacted user information while preserving the repository URL."""
+
+    if not has_redacted_credentials(url):
+        return url
+    parsed = urlparse(url)
+    return parsed._replace(netloc=credential_free_netloc(parsed)).geturl()
+
+
+def pin_git_source(url: str, commit: str) -> str:
+    """Return a Git requirement URL pinned to an immutable commit."""
+
+    source, _fragment = urldefrag(url)
+    if not source.startswith("git+"):
+        source = f"git+{source}"
+    parsed = urlparse(source)
+    path, separator, revision = parsed.path.rpartition("@")
+    if separator and revision:
+        parsed = parsed._replace(path=path)
+    return f"{parsed.geturl()}@{commit}"
+
+
+def same_git_repository(left: str, right: str) -> bool:
+    """Compare Git URLs without credentials, revisions, or fragments."""
+
+    return git_repository_key(left) == git_repository_key(right)
+
+
+def git_repository_key(url: str) -> tuple[str, str, str, str]:
+    """Return a credential-free repository identity suitable for equality checks."""
+
+    source, _fragment = urldefrag(url)
+    if not source.startswith("git+"):
+        source = f"git+{source}"
+    parsed = urlparse(source)
+    vcs, separator, transport = parsed.scheme.partition("+")
+    if vcs.casefold() != "git" or not separator or not transport:
+        raise RuntimeError("IPi installation requires a Git source URL")
+    path, revision_separator, revision = parsed.path.rpartition("@")
+    if revision_separator and revision:
+        parsed = parsed._replace(path=path)
+    return (
+        transport.casefold(),
+        credential_free_netloc(parsed).casefold(),
+        parsed.path.rstrip("/"),
+        parsed.query,
+    )
+
+
+def credential_free_netloc(parsed: ParseResult) -> str:
+    """Remove URL user information without changing the host or port."""
+
+    return parsed.netloc.rpartition("@")[2] if "@" in parsed.netloc else parsed.netloc
+
+
+__all__ = [
+    "authenticated_git_source",
+    "credential_free_netloc",
+    "git_repository_key",
+    "has_redacted_credentials",
+    "pin_git_source",
+    "requirement_url",
+    "same_git_repository",
+    "strip_redacted_git_credentials",
+]

ipi/_kernel_argv.py

@@ -0,0 +1,25 @@
+"""Kernel command-line helpers shared by direct and Jupyter launches."""
+
+from __future__ import annotations
+
+_CONNECTION_FILE_PLACEHOLDER = "{connection_file}"
+
+
+def build_ipykernel_argv(
+    *,
+    python_argv: list[str],
+    disable_standard_streams: bool,
+    connection_file: str = _CONNECTION_FILE_PLACEHOLDER,
+) -> list[str]:
+    argv = [
+        *python_argv,
+        "-m",
+        "ipykernel_launcher",
+        "-f",
+        connection_file,
+        "--HistoryManager.hist_file=:memory:",
+    ]
+    if disable_standard_streams:
+        argv.extend(["--no-stdout", "--no-stderr"])
+    argv.append("--colors=NoColor")
+    return argv

ipi/_kernel_launcher.py

@@ -0,0 +1,56 @@
+"""Kernel launcher wrapper with parent-death cleanup and optional log capture."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+from typing import NoReturn
+
+from ipi._parent_process import set_parent_death_signal
+
+
+def _parse_args(
+    argv: list[str] | None = None,
+) -> tuple[int | None, bool, Path | None, Path | None, list[str]]:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--parent-pid", type=int)
+    parser.add_argument("--parent-death-signal", action="store_true")
+    parser.add_argument("--stdout-path", type=Path)
+    parser.add_argument("--stderr-path", type=Path)
+    parser.add_argument("command", nargs=argparse.REMAINDER)
+    ns = parser.parse_args(argv)
+
+    command = list(ns.command)
+    if command[:1] == ["--"]:
+        command = command[1:]
+    if not command:
+        raise SystemExit("kernel launcher requires a command after '--'")
+    return ns.parent_pid, ns.parent_death_signal, ns.stdout_path, ns.stderr_path, command
+
+
+def _redirect_fd(fd: int, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    handle_fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+    os.dup2(handle_fd, fd)
+    os.close(handle_fd)
+
+
+def _exec(command: list[str]) -> NoReturn:
+    os.execvpe(command[0], command, os.environ.copy())
+    raise AssertionError("os.execvpe should never return")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parent_pid, parent_death_signal, stdout_path, stderr_path, command = _parse_args(argv)
+    if stdout_path is not None:
+        _redirect_fd(1, stdout_path)
+    if stderr_path is not None:
+        _redirect_fd(2, stderr_path)
+    if parent_pid is not None or parent_death_signal:
+        set_parent_death_signal(parent_pid)
+    _exec(command)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ipi/_launch_gate.py

@@ -0,0 +1,29 @@
+"""Per-owner abort signal for in-flight kernel launches.
+
+Kernel launches run inside executor threads that the interpreter joins at
+exit. A cold launch (fresh uv environment) can legitimately spend up to the
+kernel ready timeout waiting, so a closing runtime owner triggers its signal
+to make those waits abort promptly; launch abandonment then closes the
+half-started kernel processes before the owner finishes exiting. The signal
+is owner-scoped (not process-global) so one server's shutdown cannot poison
+unrelated kernel launches in the same process, and it lives in its own module
+so the (deliberately lazy-imported) kernel machinery and the MCP server can
+share it without the server paying the kernel import chain.
+"""
+
+from __future__ import annotations
+
+import threading
+
+
+class LaunchAbort:
+    """Latched abort signal owned by one runtime manager."""
+
+    def __init__(self) -> None:
+        self._event = threading.Event()
+
+    def trigger(self) -> None:
+        self._event.set()
+
+    def triggered(self) -> bool:
+        return self._event.is_set()

ipi/_markdown.py

@@ -0,0 +1,14 @@
+"""Small Markdown rendering helpers shared by notebook artifacts."""
+
+from __future__ import annotations
+
+import re
+from html import escape
+
+_INLINE_ESCAPE_RE = re.compile(r"([\\`*_{}\[\]()#+.!|>$~-])")
+
+
+def escape_markdown_inline(value: str) -> str:
+    """Render arbitrary text literally in an inline Markdown context."""
+
+    return _INLINE_ESCAPE_RE.sub(r"\\\1", escape(value, quote=False))