ionelmc/python-remote-pdb

Remote vanilla PDB (over TCP sockets).

Overview

docs
tests
package

Remote vanilla PDB (over TCP sockets) done right: no extras, proper handling around connection failures and CI. Based on pdbx.

• Free software: BSD 2-Clause License

Installation

pip install remote-pdb

Usage

To open a remote PDB on first available port:

from remote_pdb import set_trace
set_trace() # you'll see the port number in the logs

To use some specific host/port:

from remote_pdb import RemotePdb
RemotePdb('127.0.0.1', 4444).set_trace()

To connect just run telnet 127.0.0.1 4444. When you are finished debugging, either exit the debugger, or press Control-], then Control-d.

Alternately, one can connect with NetCat: nc -C 127.0.0.1 4444 or Socat: socat readline tcp:127.0.0.1:4444 (for line editing and history support). When finished debugging, either exit the debugger, or press Control-c.

Note that newer Ubuntu disabled readline support in socat, so if you get unknown device/address "readline" try using rlwrap like this:

rlwrap socat - tcp:127.0.0.1:4444

Using in containers

If you want to connect from the host to remote-pdb running inside the container you should make sure that:

• The port you will use is mapped (eg: -p 4444:4444).
• The host is set to 0.0.0.0 (localhost` or127.0.0.1`` will not work because Docker doesn't map the port on the local interface).

Integration with breakpoint() in Python 3.7+

If you are using Python 3.7 one can use the new breakpoint() built in to invoke remote PDB. In this case the following environment variable must be set:

PYTHONBREAKPOINT=remote_pdb.set_trace

The debugger can then be invoked as follows, without any imports:

breakpoint()

As the breakpoint() function does not take any arguments, environment variables can be used to specify the host and port that the server should listen to. For example, to run script.py in such a way as to make telnet 127.0.0.1 4444 the correct way of connecting, one would run:

PYTHONBREAKPOINT=remote_pdb.set_trace REMOTE_PDB_HOST=127.0.0.1 REMOTE_PDB_PORT=4444 python script.py

If REMOTE_PDB_HOST is omitted then a default value of 127.0.0.1 will be used. If REMOTE_PDB_PORT is omitted then the first available port will be used. The connection information will be logged to the console, as with calls to remote_pdb.set_trace().

To quiet the output, set REMOTE_PDB_QUIET=1, this will prevent RemotePdb from producing any output -- you'll probably want to specify REMOTE_PDB_PORT as well since the randomized port won't be printed.

Note about OS X

In certain scenarios (backgrounded processes) OS X will prevent readline to be imported (and readline is a dependency of pdb). A workaround (run this early):

import signal
signal.signal(signal.SIGTTOU, signal.SIG_IGN)

See #9 and cpython#14892.

Requirements

Python 2.6, 2.7, 3.2, 3.3 and PyPy are supported.

Similar projects

• qdb

python-remote-pdb's Issues

python -m remote_pdb equivalent of python -m pdb

When invoked as a script, pdb will automatically enter post-mortem debugging if the program being debugged exits abnormally. After post-mortem debugging (or after normal exit of the program), pdb will restart the program. Automatic restarting preserves pdb’s state (such as breakpoints) and in most cases is more useful than quitting the debugger upon program’s exit.

Pdb doesn't stop on set_trace command.

When connected to remote pdb few commands after set_trace call are executed. In following code pdb would stop around x=3.

def test():
    import remote_pdb; rp = remote_pdb.RemotePdb(host='0.0.0.0', port=4444); rp.set_trace()
    return {}

test()
x = 3

Setting process group consumes I/O from debugger.

First, thanks for writing remote_pdb! It works very well to set breaks in child processes in normal circumstances.

There seems to be a communication problem when the main python program is under control of a program such as entr or when the main program is launched from ipython and sets it's own process group.

Could you please take a look at the question I posted a couple of days ago on SO? It's rather long so I won't repost the contents here.

http://stackoverflow.com/questions/43823564/python-3-debug-child-process-running-under-control-of-entr

Thanks,
Mike Ellis

Source code gets chopped off in a remote session

I'm using this module together with pdbpp. This promises to offer the sticky option of pdbpp also for remote sessions.

One problem however seems to be that the terminal size is for some reason fixed and this results in not all the code being shown.

I'm posting this here just to start the conversation, it if possible this might be a pdbpp issue.

pdbpp

pdbpp==0.10.2
remote-pdb==2.0.0
Python==3.8.0

The strangest thing. If I install pdbpp and remote-pdb, the first remote debugging session does not use pdbpp. Subsquent sessions it works.

What could be going wrong here?

autocompletion and [TAB] action does not work on linux

Hi,

I started using remote-pdb a few days ago and i noticed that the [TAB] action does not work under
linux. I am not sure if this is the case on other OSes too.
After telnet'ing when i press [TAB] the cursor just moves forward with a tab space.

i think it would be really cool if the TAB completion works via telnet.

i hope this will be takes into account and implemented, i'll be happy to contribute with some of my time in case i can be helpful.

Best,

pdb times out before I get a chance to connect to it

I either connect to it too early or too late.
Tried both alternatives, the one where it picks itself an available port and the one where I choose one.
It could be that Apache times out the connection.

Check compatibility with celery

Seems if CELERY_REDIRECT_STDOUTS=True there are some weird issues with the output.

It also gets worse if pdbpp is installed.

Interactive mode

For some reason, the interact pdb mode is displayed on a process tty (not in a telnet session) and exits immediately. Here is a demo:

Is that a known issue?

Is it possible for remote-pdb session to be started (and connected to) from within an AWS Lambda?

I am sure remote-pdb would start the session. Interested in the use-case. Could be a very useful use-case of the library.

set_trace call vs RemotePdb instance

Hi,
I was looking at doing a similar change as a PR for pudb and was looking at your source.

Going by your usage instructions - is there any reason to use the RemotePdb class when calling set_trace() with the same parameters seems to take care of that for you?

Thanks!

Add `post_mortem()`

It would be useful to have a post_mortem function like pdb has. This would allow calling remote_pdb right after an exception is raise (if it's raised). Like this:

    try:
        code_which_can_fail()
    except:
        extype, value, tb = sys.exc_info()
        traceback.print_exc()
        remote_pdb.post_mortem(tb)

This is useful in environments where remote_pdb can't be called directly

Something like this would work:

def post_mortem(t=None):
    # handling the default
    if t is None:
        # sys.exc_info() returns (type, value, traceback) if an exception is
        # being handled, otherwise it returns None
        t = sys.exc_info()[2]
    if t is None:
        raise ValueError("A valid traceback must be passed if no " "exception is being handled")

    p = remote_pdb.RemotePdb(
        host=os.environ.get("REMOTE_PDB_HOST", "127.0.0.1"), port=int(os.environ.get("REMOTE_PDB_PORT", "0")),
        # other args
    )
    p.reset()
    p.interaction(None, t)

I can make a PR if this feature is welcome

remote_pdb equivalents for pdb.run, pdb.runeval, pdb.runcall, pdb.post_mortem and pdb.pm()

I'm especially looking for pdb.post_mortem and pdb.pm()

Documentation: socat readline does not work

I'm using a Ubuntu 18.04 system, and when I try to use this:

socat readline tcp:<ipaddr>:<port>

I get this error:

2020/03/19 11:45:09 socat[21111] E unknown device/address "readline"

Instead, I found that either of the following seems to work, and gives me arrow keys to scroll through history and edit previous commands:

rlwrap telnet <ipaddr> <port>
rlwrap socat - tcp:<ipaddr>:<port>

How I can send SIGINT over a telnet session?

I want to break the execution of the script by sending SIGINT. Something like typing Ctrl-C or Ctrl-] send brk do not work.

Can't send Up arrow or navigate history?

Hi Ionel,
Thanks so much for making pyremotepdb, I use it as an alternate to GUI debuggers as I usually need to debug other processes over the network.

I was just wondering if it's a known issue (or limitation of telnet/nc) that one cannot use the Up arrow keyboard shortcut to reload the last run command. Indeed none of the arrow keys work, simple keyboard shortcuts don't work in my case. (all on Linux, kubuntu 18, etc).
I'm not intimately familiar with how stdin works so perhaps this is a limitation that can't be overcome? Would be a shame, I'd love to have remotepdb work just like pdb.

cheers,

Question: PyCharm Debugging with Remote-Pdb?

Is it possible to attach the PyCharm debugger to a process waiting after executing "RemotePdb("0.0.0.0", 5005).set_trace()"?

If so, how? I have tried every combination of remote, local, attach, run/debug config and anything else that I can find in the PyCharm UI but nothing seems cause it to connect. What is the PyCharm equivilent of "nc -C 127.0.0.1 5005"?

Connection in Docker drops immediately

I just started using remote-pdb and run into an issue. If I run the debugger inside a running Docker container I am not able to establish a persistent connection with the debugger from the host. If I start a shell inside the docker container and run nc -vv localhost 4444 I obtain the expected prompt:

localhost (127.0.0.1:4444) open
> [My code breakpoint info]
(Pdb) 

But if I run the same from the host, the connection is terminated immediately:

$ nc -vv localhost 4444
Notice: Real hostname for localhost [127.0.0.1] is workbox1
localhost [127.0.0.1] 4444 (krb524) open
Total received bytes: 0
Total sent bytes: 0

I'm mapping host port 4444 to guest:4444, and I tried other mappings to ensure that was not the problem, but I get the same result consistently.

I am using Python 3.7's breakpoint() command. I have the following env variables read by Docker:

PYTHONBREAKPOINT=remote_pdb.set_trace
REMOTE_PDB_HOST=127.0.0.1
REMOTE_PDB_PORT=4444

My host is Arch linux (GNU netcat 0.7.1) and the guest is Alpine (nc part of Busybox 1.30.1). I can reproduce the same issue with socat and telnet.

This is an increedibly useful tool and if I could use it from the host it would be so much more efficient. Any help is appreciated.

Jython Support

Could the project description include a brief statement about whether or not the debugger should function under Jython 2.7.2 ? I see Python 2.7 badge but I know Jython is a bit weird.

Always show session open message

Show the message "RemotePdb session open at %s:%s, waiting for connection" even when a port is given because:

1. This signals that a debugger is waiting.
2. This allows to differentiate between different given ports.

Silent / quiet mode

cool tool!

I'm playing around with curses right now and a remote debugger is exceptionally good for this -- the one thing that's a bit unfortunate is remote-pdb will always print output breaking the curses output:

would you accept a PR which allows an option (and environment variable) to silence this?