Python API

The ntoseye package’s API, generated from the type stub the package ships. For how the pieces fit together, see the SDK guide.

Module ntoseye

ntoseye.__version__: Final[str]

The ntoseye release version of this extension.

ntoseye.build: Final[str]

The git commit of this extension build (<commit>, <commit>-dirty, or unknown). Use it to find a stale extension in a long-lived interpreter.

ntoseye.attach(backend: Literal['kd', 'kdnet', 'gdb', 'memory', 'dmp'] = ..., connect: str | None = None, key: str | None = None, memory_source: Literal['auto', 'host', 'kd'] = ..., *, kd_handshake_timeout: 'int | None' = None) → Debugger

Attach to a guest and return a Debugger.

backend is one of "kd" (default), "kdnet", "gdb", "memory", or "dmp". connect is the backend target: a socket path or address for kd/kdnet/gdb, or the dump file path for dmp: a kernel crash dump, or a Windows user-mode minidump, whose process and threads Debugger.user_dump holds. Without connect, the function uses the default of the backend, but dmp has no default and needs a path. kdnet needs key. memory_source is auto, host, or kd for KD/KDNET. kd_handshake_timeout is keyword-only: positive integer seconds for the initial KD/KDNET handshake. It overrides NTOSEYE_KD_TIMEOUT; None uses the environment variable or the 8-second default. Other backends reject it.

For kd/kdnet/gdb, the function takes an instance lock for the target before it makes the backend, so a second live attach to the same target fails immediately without interfering with the handshake that the first session owns. The memory and dmp backends are passive.

ntoseye.decode_error(code: int) → ErrorCode

Decode an NTSTATUS, Win32, or HRESULT code into its name and description (!error). This function does not need a target.

Module ntoseye.repl

REPL command scripting helpers for ntoseye.

Command scripts in ~/.ntoseye/commands/ import this module. Inside the REPL (the ntoseye command that this package installs, or a build with embedded Python), register_command is the REPL’s own function. Anywhere else it raises an exception, so a command script that runs outside the REPL fails with a clear error.

Debugger is re-exported from ntoseye; a command receives a borrowed ntoseye.Debugger.

ntoseye.repl.register_command(name: str, help: str, fn: Callable[..., Any], strategies: list[str] | None = None) → None

Register a REPL command that the REPL calls as fn(dbg, *raw_args), where dbg is a borrowed Debugger that is valid only until the command returns.

ntoseye.repl.command(name: str, help: str, **completions: _Completion) → Callable[[_F], _F]

Decorator form of register_command. Keyword arguments bind completion markers to the parameters of the command by name. dbg (the first parameter) is a borrowed Debugger that is valid only until the command returns.

ntoseye.repl.Process

Completion marker: binds a command parameter to process completion in command(..., param=Process).

ntoseye.repl.Symbol

Completion marker: binds a command parameter to symbol completion in command(..., param=Symbol).

ntoseye.repl.Expression

Completion marker: binds a command parameter to expression completion in command(..., param=Expression).

ntoseye.repl.Type

Completion marker: binds a command parameter to type completion in command(..., param=Type).

ntoseye.repl.Driver

Completion marker: binds a command parameter to driver completion in command(..., param=Driver).

ntoseye.repl.Thread

Completion marker: binds a command parameter to thread completion in command(..., param=Thread).

ntoseye.repl.Vcpu

Completion marker: binds a command parameter to vcpu completion in command(..., param=Vcpu).

ntoseye.repl.Breakpoint

Completion marker: binds a command parameter to breakpoint completion in command(..., param=Breakpoint).

ntoseye.repl.Alias

Completion marker: binds a command parameter to alias completion in command(..., param=Alias).

ntoseye.repl.RegistryKey

Completion marker: binds a command parameter to registry-key completion in command(..., param=RegistryKey).

Classes

Results

What the inspect methods and other decodings return: records whose properties type each field. to_dict() gives the same shape as the MCP server’s JSON.