apdb 0.1.0__py3-none-any.whl

apdb/__init__.py

@@ -0,0 +1,5 @@
+from .debugger import APDBError, AgentPdbSession, set_trace
+
+__version__ = "0.1.0"
+
+__all__ = ["APDBError", "AgentPdbSession", "__version__", "set_trace"]

apdb/cli.py

@@ -0,0 +1,57 @@
+import argparse
+import json
+import socket
+import sys
+
+from .protocol import dumps_response, loads_json_line
+
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_TIMEOUT = 2.0
+
+
+def build_parser():
+    shared = argparse.ArgumentParser(add_help=False)
+    shared.add_argument("--host", default=DEFAULT_HOST)
+    shared.add_argument("--port", type=int, required=True)
+    shared.add_argument("--timeout", type=float, default=DEFAULT_TIMEOUT)
+
+    parser = argparse.ArgumentParser(prog="apdb_cli")
+    subparsers = parser.add_subparsers(dest="cmd", required=True)
+    for name in ("ping", "state", "where", "locals", "next", "step", "continue", "quit"):
+        subparsers.add_parser(name, parents=[shared])
+
+    eval_parser = subparsers.add_parser("eval", parents=[shared])
+    eval_parser.add_argument("expr")
+    return parser
+
+
+def make_request(args):
+    request = {"id": 1, "cmd": args.cmd}
+    if args.cmd == "eval":
+        request["expr"] = args.expr
+    return request
+
+
+def send_command(host, port, request, timeout=DEFAULT_TIMEOUT):
+    with socket.create_connection((host, port), timeout=timeout) as sock:
+        sock.sendall(dumps_response(request))
+        with sock.makefile("rb") as reader:
+            return loads_json_line(reader.readline())
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        response = send_command(args.host, args.port, make_request(args), args.timeout)
+    except OSError as exc:
+        print(f"connection failed: {exc}", file=sys.stderr)
+        return 2
+
+    print(json.dumps(response, sort_keys=True))
+    return 0 if response.get("ok") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

apdb/debugger.py

@@ -0,0 +1,194 @@
+import bdb
+import linecache
+import sys
+import threading
+
+from .protocol import error_response, ok_response
+from .server import APDBTCPServer
+
+
+RELEASE_COMMANDS = {"continue", "next", "step", "quit"}
+
+
+class APDBError(RuntimeError):
+    pass
+
+
+class AgentPdbSession:
+    def __init__(self, host, port, header=None):
+        self.host = host
+        self.port = port
+        self.header = header
+        self._condition = threading.Condition()
+        self._release_event = threading.Event()
+        self._server = None
+        self._server_thread = None
+        self._current_frame = None
+        self._current_action = None
+        self._done = False
+        self._paused = False
+        self._trace_mode = None
+        self._next_frame = None
+
+    def start(self):
+        try:
+            self._server = APDBTCPServer((self.host, self.port), self)
+        except OSError as exc:
+            raise APDBError(f"could not start apdb server on {self.host}:{self.port}: {exc}") from exc
+
+        self._server_thread = threading.Thread(
+            target=self._server.serve_forever,
+            name=f"apdb:{self.host}:{self.port}",
+            daemon=True,
+        )
+        self._server_thread.start()
+
+    def close(self):
+        self._done = True
+        if self._server is not None:
+            self._server.shutdown()
+            self._server.server_close()
+            self._server = None
+
+    def pause(self, frame):
+        with self._condition:
+            self._current_frame = frame
+            self._current_action = None
+            self._paused = True
+            self._release_event.clear()
+            self._condition.notify_all()
+
+        self._release_event.wait()
+
+        with self._condition:
+            self._paused = False
+            return self._current_action
+
+    def handle_request(self, request):
+        cmd = request["cmd"]
+        try:
+            if cmd == "ping":
+                return ok_response(request, {"status": "online"})
+            if cmd == "state":
+                return ok_response(request, self._state())
+            if cmd == "where":
+                return ok_response(request, {"frames": self._stack()})
+            if cmd == "locals":
+                return ok_response(request, self._locals())
+            if cmd == "eval":
+                return ok_response(request, self._eval(request.get("expr", "")))
+            if cmd in RELEASE_COMMANDS:
+                return self._release(request, cmd)
+            return error_response(request, "unknown_command", f"unknown command: {cmd}")
+        except Exception as exc:
+            return error_response(request, "command_error", f"{type(exc).__name__}: {exc}")
+
+    def trace_dispatch(self, frame, event, arg):
+        if self._done:
+            return None
+        if self._should_pause_for_trace(frame, event):
+            action = self.pause(frame)
+            return self._after_action(action, frame)
+        return self.trace_dispatch
+
+    def _release(self, request, action):
+        with self._condition:
+            self._current_action = action
+            self._release_event.set()
+        status = {
+            "continue": "continuing",
+            "next": "next",
+            "step": "step",
+            "quit": "quitting",
+        }[action]
+        return ok_response(request, {"status": status})
+
+    def _state(self):
+        frame = self._current_frame
+        result = {"status": "paused" if self._paused else "running"}
+        if frame is not None:
+            result.update(self._frame_info(frame, index=0))
+        return result
+
+    def _stack(self):
+        frames = []
+        frame = self._current_frame
+        index = 0
+        while frame is not None:
+            frames.append(self._frame_info(frame, index=index))
+            frame = frame.f_back
+            index += 1
+        return frames
+
+    def _locals(self):
+        frame = self._require_frame()
+        return {name: safe_repr(value) for name, value in sorted(frame.f_locals.items())}
+
+    def _eval(self, expr):
+        if not expr:
+            raise ValueError("eval command requires expr")
+        frame = self._require_frame()
+        value = eval(expr, frame.f_globals, frame.f_locals)
+        return {"repr": safe_repr(value), "type": type(value).__name__}
+
+    def _require_frame(self):
+        if self._current_frame is None:
+            raise RuntimeError("debugger is not paused at a frame")
+        return self._current_frame
+
+    def _frame_info(self, frame, index):
+        filename = frame.f_code.co_filename
+        line = linecache.getline(filename, frame.f_lineno).strip()
+        return {
+            "index": index,
+            "file": filename,
+            "line": frame.f_lineno,
+            "function": frame.f_code.co_name,
+            "code": line,
+        }
+
+    def _should_pause_for_trace(self, frame, event):
+        if event != "line":
+            return False
+        if self._trace_mode == "step":
+            return True
+        if self._trace_mode == "next":
+            return frame is self._next_frame
+        return False
+
+    def _after_action(self, action, frame):
+        if action == "continue":
+            self.close()
+            sys.settrace(None)
+            return None
+        if action == "quit":
+            self.close()
+            sys.settrace(None)
+            raise bdb.BdbQuit()
+        if action in {"next", "step"}:
+            self._trace_mode = action
+            self._next_frame = frame
+            frame.f_trace = self.trace_dispatch
+            sys.settrace(self.trace_dispatch)
+            return self.trace_dispatch
+        self.close()
+        sys.settrace(None)
+        return None
+
+
+def safe_repr(value):
+    try:
+        return repr(value)
+    except Exception:
+        return f"<unrepresentable {type(value).__name__}>"
+
+
+def set_trace(host="127.0.0.1", port=None, header=None):
+    if port is None:
+        raise TypeError("apdb.set_trace() missing required keyword argument: 'port'")
+
+    frame = sys._getframe().f_back
+    session = AgentPdbSession(host=host, port=port, header=header)
+    session.start()
+    action = session.pause(frame)
+    return session._after_action(action, frame)

apdb/protocol.py

@@ -0,0 +1,45 @@
+import json
+
+
+class ProtocolError(ValueError):
+    def __init__(self, code, message):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+def loads_request(line):
+    request = loads_json_line(line)
+    if not isinstance(request, dict):
+        raise ProtocolError("invalid_request", "request must be a JSON object")
+    if not request.get("cmd"):
+        raise ProtocolError("missing_command", "request must include cmd")
+    if not isinstance(request["cmd"], str):
+        raise ProtocolError("invalid_command", "cmd must be a string")
+    return request
+
+
+def loads_json_line(line):
+    try:
+        payload = json.loads(line.decode("utf-8"))
+    except UnicodeDecodeError as exc:
+        raise ProtocolError("invalid_encoding", str(exc)) from exc
+    except json.JSONDecodeError as exc:
+        raise ProtocolError("invalid_json", str(exc)) from exc
+    return payload
+
+
+def dumps_response(response):
+    return (json.dumps(response, sort_keys=True) + "\n").encode("utf-8")
+
+
+def ok_response(request, result):
+    return {"id": request.get("id"), "ok": True, "result": result}
+
+
+def error_response(request, code, message):
+    return {
+        "id": request.get("id"),
+        "ok": False,
+        "error": {"code": code, "message": message},
+    }

apdb/server.py

@@ -0,0 +1,24 @@
+import socketserver
+
+from .protocol import ProtocolError, dumps_response, error_response, loads_request
+
+
+class APDBRequestHandler(socketserver.StreamRequestHandler):
+    def handle(self):
+        line = self.rfile.readline()
+        try:
+            request = loads_request(line)
+        except ProtocolError as exc:
+            response = error_response({"id": None}, exc.code, exc.message)
+        else:
+            response = self.server.session.handle_request(request)
+        self.wfile.write(dumps_response(response))
+
+
+class APDBTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
+    allow_reuse_address = True
+    daemon_threads = True
+
+    def __init__(self, server_address, session):
+        self.session = session
+        super().__init__(server_address, APDBRequestHandler)

apdb-0.1.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: apdb
+Version: 0.1.0
+Summary: Agent-friendly remote Python debugger over a zero-dependency TCP API
+Author: apdb contributors
+License-Expression: BSD-2-Clause
+Keywords: debugger,pdb,agent,tcp,remote-debugger
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# apdb
+
+`apdb` is an agent-friendly Python debugger inspired by `remote-pdb`.
+It keeps the Python call site close to `pdb`, but exposes debugger control over
+a newline-delimited JSON TCP API instead of a human interactive shell.
+
+The runtime and CLI use only the Python standard library.
+
+## Python API
+
+```python
+import apdb
+
+answer = 41
+apdb.set_trace(port=4444)
+print(answer + 1)
+```
+
+`set_trace()` blocks the target process whether or not a client is connected.
+The process resumes only after the TCP API receives a release command such as
+`continue`, `next`, `step`, or `quit`.
+
+By default, `apdb` binds to `127.0.0.1` and uses no authentication:
+
+```python
+apdb.set_trace(port=4444, host="127.0.0.1")
+```
+
+## CLI
+
+The package installs `apdb_cli`:
+
+```bash
+apdb_cli ping --port 4444
+apdb_cli state --port 4444
+apdb_cli where --port 4444
+apdb_cli locals --port 4444
+apdb_cli eval 'answer + 1' --port 4444
+apdb_cli next --port 4444
+apdb_cli step --port 4444
+apdb_cli continue --port 4444
+```
+
+The CLI prints one JSON response to stdout and exits nonzero for connection
+failures or API errors.
+
+## TCP API
+
+The TCP API speaks newline-delimited JSON. Each request and response is one JSON
+object followed by `\n`.
+
+Request:
+
+```json
+{"id": 1, "cmd": "state"}
+```
+
+Response:
+
+```json
+{"id": 1, "ok": true, "result": {"status": "paused"}}
+```
+
+Supported v0 commands:
+
+- `ping`
+- `state`
+- `where`
+- `locals`
+- `eval`
+- `next`
+- `step`
+- `continue`
+- `quit`
+
+## Security
+
+`apdb` has no authentication in v0. Debugger access can inspect and evaluate
+code inside the target process. Bind to `127.0.0.1` unless you explicitly want
+to expose that control surface.

apdb-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+apdb/__init__.py,sha256=xLXWQawoqb5qFQnFuULx9kd2v1FoQfOLg905iMN6Eew,155
+apdb/cli.py,sha256=maNWSdMO4FMKOtlGrvkp5y-P5DO8l2DyG1ah7fIciOk,1679
+apdb/debugger.py,sha256=LFbPCKWOuU5Z_cuZ_QiGN6398nT8ifohxBmsyDslxSA,6153
+apdb/protocol.py,sha256=etPnmmVPaIn64C1hF4HxTTUNMn3yOgAW-k4s522xSzo,1293
+apdb/server.py,sha256=-NmcEBHChmfEUs1EbI9GHax94vSmZ4pdfDxB-YHjKcQ,800
+apdb-0.1.0.dist-info/licenses/LICENSE,sha256=lvGLyG5yWbZsUmKNvQoD1wcjE1lpKc2rNTP1L25V0MI,1306
+apdb-0.1.0.dist-info/METADATA,sha256=wkiX5VyhdbPNGw6e56e_Hhiu7yBClQC1f4xRHJ04kz4,2535
+apdb-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+apdb-0.1.0.dist-info/entry_points.txt,sha256=DZTiyDDhf5HZdZcEWKzw-nY2SNm_NUH6bY3BumeHARc,43
+apdb-0.1.0.dist-info/top_level.txt,sha256=FcE0oU1p-OxPclBZ9-Ux3fedckbLNW1-FCK7UB-JRkU,5
+apdb-0.1.0.dist-info/RECORD,,

apdb-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

apdb-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+apdb_cli = apdb.cli:main

apdb-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, apdb contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

apdb-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+apdb