Merge branch 'main' into compatibility-for-python3.12

Author: uncle-lv

README.md

@@ -5,9 +5,10 @@ English | [简体中文](README_zh.md)
 It's a fork/optimized version from [elifiner/pydump](https://github.com/elifiner/pydump).The main optimization points are：
 * Save the `Python traceback` anywhere, not just when it's an exception.
 * Optimize code structure && remove redundant code
-* fix bug in python2.7 && support python3.10+
+* fix bug in python3.10+
 * supported more pdb commnd
 * a useful command line tool for debug
+* supported remote debug (rpdb)
 
 
 Pydumpling writes the `python current traceback` into a file and 
@@ -22,11 +23,10 @@ pdb and with other popular debuggers (pudb, ipdb and pdbpp).
 * If we were able to save the exception error and then use the debugger to recover the traceback at that time, we could see the entire stack variables along the traceback as if you had caught the exception at the local breakpoint.
 
 ## Install pydumpling
-Python version：>= 2.7, >=3.6
+Python version：>=3.7
 
-Not published in pypi，so use the `.whl` file install pydumpling in the dist path.
 ```
-pip install dist/pydumpling-0.1.1-py2.py3-none-any.whl
+pip install pydumpling
 ```
 
 ## How to use pydumpling
@@ -129,7 +129,7 @@ Type "help", "copyright", "credits" or "license" for more information.
 
 ### Use Command Line
 
-Use command line to print the traceback:
+#### Use command line to print the traceback:
 `python -m pydumpling --print test.deump`
 
 It will print:
@@ -145,7 +145,7 @@ TypeError: unsupported operand type(s) for +: 'int' and 'str'
 ```
 
 
-Use command line to do pdb debug:
+#### Use command line to do pdb debug:
 `python -m pydumpling --debug test.deump`
 
 It will open the pdb window:
@@ -154,5 +154,11 @@ It will open the pdb window:
 (Pdb) 
 ```
 
+#### Use command line to do remote pdb debug:
+`python -m pydumpling --rdebug test.deump`
+It will open the debugger on port 4444, then we can access pdb using telnet、netcat... :
+`nc 127.0.0.1 4444`
+![alt text](static/rpdb.png)
+
 ## TODO
 - []

README_zh.md

@@ -3,9 +3,10 @@
 这是 [elifiner/pydump](https://github.com/elifiner/pydump) 的fork/优化版本, 主要优化点有:
 * 支持在任何地方保存`Python traceback`，而不是只在异常发生的时候
 * 优化代码结构, 去除冗余代码
-* 修复其在2.7及3.10版本中的bug
+* 修复其在3.10+版本中的bug
 * 支持更多的pdb命令
 * 提供了一个方便用来调试的命令行工具
+* 支持服务器远程调试(remote pdb)
 
 pydumpling可以在代码的任何位置中，将当前Python程序的traceback写到一个文件中，可以稍后在Python调试器中加载它。目前pydump支持很多兼容PDB api的调试器（pdbpp, udb, ipdb)
 
@@ -17,11 +18,10 @@ pydumpling可以在代码的任何位置中，将当前Python程序的traceback
 * 如果我们能够把线上的异常现场保存下来，然后通过调试器去恢复当时的异常堆栈，我们可以看到这个异常的整条调用链路以及链路上的堆栈变量，就如同你在本地断点捕获到了这个异常一样。
 
 ## 安装方法
-Python版本支持：>= 2.7, >=3.6
+Python版本支持：>=3.7
 
-目前还没有在Pypi上面进行发布，因此直接使用PIP安装dist目录下的whl文件
 ```
-pip install dist/pydumpling-0.1.1-py2.py3-none-any.whl
+pip install -i pydumpling
 ```
 
 ## 使用方法
@@ -125,7 +125,7 @@ Type "help", "copyright", "credits" or "license" for more information.
 
 ### 命令行使用
 
-使用命令行来打印traceback:
+#### 使用命令行来打印traceback:
 `python -m pydumpling --print test.deump`
 
 将会输出:
@@ -141,7 +141,7 @@ TypeError: unsupported operand type(s) for +: 'int' and 'str'
 ```
 
 
-使用命令行来进行pdb调试:
+#### 使用命令行来进行pdb调试:
 `python -m pydumpling --debug test.deump`
 
 将会打开pdb调试会话:
@@ -150,5 +150,11 @@ TypeError: unsupported operand type(s) for +: 'int' and 'str'
 (Pdb) 
 ```
 
+#### 使用命令行来进行remote pdb调试
+`python -m pydumpling --rdebug test.deump`
+它会在机器的4444端口上打开pdb调试器，然后我们可以在另外一台机器上使用telnet、netcat来进行远程调试：
+`nc 127.0.0.1 4444`
+![alt text](static/rpdb.png)
+
 ## TODO
 - []

pydumpling/__init__.py

@@ -1,7 +1,9 @@
 from __future__ import absolute_import, division, print_function, unicode_literals
 
+from .rpdb import r_post_mortem
 from .debug_dumpling import debug_dumpling, load_dumpling
 from .pydumpling import save_dumping, dump_current_traceback, __version__
 
+
 __version__ == __version__
-__all__ = ["debug_dumpling", "load_dumpling", "save_dumping", "dump_current_traceback"]
+__all__ = ["debug_dumpling", "load_dumpling", "save_dumping", "dump_current_traceback", "r_post_mortem"]

pydumpling/cli.py

@@ -1,6 +1,7 @@
 import argparse
 import os.path
 from .debug_dumpling import debug_dumpling, load_dumpling
+from .rpdb import r_post_mortem
 from .helpers import print_traceback_and_except
 
 DUMP_FILE_EXTENSION: str = ".dump"
@@ -36,6 +37,12 @@ def validate_file_name(file_name: str) -> str:
     help="enter pdb debugging interface"
 )
 
+pydumpling_cli_action_group.add_argument(
+    "--rdebug",
+    action="store_true",
+    help="enter rpdb debugging interface"
+)
+
 parser.add_argument(
     "filename",
     type=validate_file_name,
@@ -51,3 +58,5 @@ def main() -> None:
         print_traceback_and_except(dumpling_)
     elif args.debug:
         debug_dumpling(file_name)
+    elif args.rdebug:
+        r_post_mortem(file_name)

pydumpling/debug_dumpling.py

@@ -18,13 +18,17 @@ def load_dumpling(filename):
             return pickle.load(f)
 
 
-def debug_dumpling(dump_file, pdb=pdb):
+def mock_inspect():
     inspect.isframe = lambda obj: isinstance(
         obj, types.FrameType) or obj.__class__ == FakeFrame
     inspect.istraceback = lambda obj: isinstance(
         obj, types.TracebackType) or obj.__class__ == FakeTraceback
     inspect.iscode = lambda obj: isinstance(
         obj, types.CodeType) or obj.__class__ == FakeCode
+
+
+def debug_dumpling(dump_file, pdb=pdb):
+    mock_inspect()
     dumpling = load_dumpling(dump_file)
     if not parse("0.0.1") <= parse(dumpling["version"]) < parse("1.0.0"):
         raise ValueError("Unsupported dumpling version: %s" %

pydumpling/fake_types.py

@@ -1,7 +1,7 @@
 from __future__ import absolute_import, division, print_function, unicode_literals
 
 import os
-import six
+import sys
 import dill
 
 
@@ -43,7 +43,7 @@ def _convert(cls, v):
         else:
             from datetime import date, time, datetime, timedelta
 
-            BUILTIN = (str, unicode, int, long, float, date, time, datetime, timedelta) if six.PY2 \
+            BUILTIN = (str, unicode, int, long, float, date, time, datetime, timedelta) if sys.version_info.major == 2 \
                 else (str, int, float, date, time, datetime, timedelta)  # noqa: F821
 
             if type(v) in BUILTIN:

pydumpling/pydumpling.py

@@ -8,7 +8,7 @@
 import inspect
 from .fake_types import FakeFrame, FakeTraceback
 
-__version__ = "0.1.1"
+__version__ = "0.1.4"
 
 
 def save_dumping(filename=None, tb=None):

pydumpling/rpdb.py

@@ -0,0 +1,136 @@
+import pdb
+import socket
+import threading
+import sys
+from .debug_dumpling import load_dumpling, mock_inspect
+
+DEFAULT_ADDR = "127.0.0.1"
+DEFAULT_PORT = 4444
+
+
+class FileObjectWrapper(object):
+    def __init__(self, fileobject, stdio):
+        self._obj = fileobject
+        self._io = stdio
+
+    def __getattr__(self, attr):
+        if hasattr(self._obj, attr):
+            attr = getattr(self._obj, attr)
+        elif hasattr(self._io, attr):
+            attr = getattr(self._io, attr)
+        else:
+            raise AttributeError("Attribute %s is not found" % attr)
+        return attr
+
+
+class Rpdb(pdb.Pdb):
+
+    def __init__(self, addr=DEFAULT_ADDR, port=DEFAULT_PORT):
+        """Initialize the socket and initialize pdb."""
+
+        # Backup stdin and stdout before replacing them by the socket handle
+        self.old_stdout = sys.stdout
+        self.old_stdin = sys.stdin
+        self.port = port
+
+        # Open a 'reusable' socket to let the webapp reload on the same port
+        self.skt = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self.skt.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, True)
+        self.skt.bind((addr, port))
+        self.skt.listen(1)
+
+        # Writes to stdout are forbidden in mod_wsgi environments
+        try:
+            sys.stderr.write("pdb is running on %s:%d\n"
+                             % self.skt.getsockname())
+        except IOError:
+            pass
+
+        (clientsocket, address) = self.skt.accept()
+        handle = clientsocket.makefile('rw')
+        pdb.Pdb.__init__(self, completekey='tab',
+                         stdin=FileObjectWrapper(handle, self.old_stdin),
+                         stdout=FileObjectWrapper(handle, self.old_stdin))
+        sys.stdout = sys.stdin = handle
+        self.handle = handle
+        OCCUPIED.claim(port, sys.stdout)
+
+    def shutdown(self):
+        """Revert stdin and stdout, close the socket."""
+        sys.stdout = self.old_stdout
+        sys.stdin = self.old_stdin
+        self.handle.close()
+        OCCUPIED.unclaim(self.port)
+        self.skt.shutdown(socket.SHUT_RDWR)
+        self.skt.close()
+
+    def do_continue(self, arg):
+        """Clean-up and do underlying continue."""
+        try:
+            return pdb.Pdb.do_continue(self, arg)
+        finally:
+            self.shutdown()
+
+    do_c = do_cont = do_continue
+
+    def do_quit(self, arg):
+        """Clean-up and do underlying quit."""
+        try:
+            return pdb.Pdb.do_quit(self, arg)
+        finally:
+            self.shutdown()
+
+    do_q = do_exit = do_quit
+
+    def do_EOF(self, arg):
+        """Clean-up and do underlying EOF."""
+        try:
+            return pdb.Pdb.do_EOF(self, arg)
+        finally:
+            self.shutdown()
+
+
+class OccupiedPorts(object):
+    """Maintain rpdb port versus stdin/out file handles.
+
+    Provides the means to determine whether or not a collision binding to a
+    particular port is with an already operating rpdb session.
+
+    Determination is according to whether a file handle is equal to what is
+    registered against the specified port.
+    """
+
+    def __init__(self):
+        self.lock = threading.RLock()
+        self.claims = {}
+
+    def claim(self, port, handle):
+        self.lock.acquire(True)
+        self.claims[port] = id(handle)
+        self.lock.release()
+
+    def is_claimed(self, port, handle):
+        self.lock.acquire(True)
+        got = (self.claims.get(port) == id(handle))
+        self.lock.release()
+        return got
+
+    def unclaim(self, port):
+        self.lock.acquire(True)
+        del self.claims[port]
+        self.lock.release()
+
+
+# {port: sys.stdout} pairs to track recursive rpdb invocation on same port.
+# This scheme doesn't interfere with recursive invocations on separate ports -
+# useful, eg, for concurrently debugging separate threads.
+OCCUPIED = OccupiedPorts()
+
+
+def r_post_mortem(dump_file, addr=DEFAULT_ADDR, port=DEFAULT_PORT):
+    mock_inspect()
+    dumpling = load_dumpling(dump_file)
+    tb = dumpling["traceback"]
+    debugger = Rpdb(addr=addr, port=port)
+    debugger.reset()
+    debugger.interaction(None, tb)

pyproject.toml

@@ -11,7 +11,6 @@ includes = ["pydumpling/*.py"]
 test = [
     "pytest-order>=1.2.0",
     "flake8>=5.0.4",
-    "six>=1.16.0",
 ]
 dev = [
     "tox-pdm>=0.6.1",
@@ -23,8 +22,8 @@ build-backend = "pdm.backend"
 
 [project]
 name = "pydumpling"
-version = "0.1.2"
-description = ""
+version = "0.1.4"
+description = "Python post-mortem debugger"
 authors = [
     {name = "cocolato", email = "[email protected]"},
 ]
@@ -36,3 +35,7 @@ dependencies = [
 requires-python = ">=3.7"
 readme = "README.md"
 license = {text = "MIT"}
+
+
+[project.urls]
+homepage = "https://github.com/cocolato/pydumpling"