pdb-attach

library3.0.1pypypi✓ verified 85d ago

pdb-attach is a Python debugger extension that allows users to attach to already running Python processes. Unlike standard `pdb.set_trace()`, it facilitates debugging long-running or unresponsive applications by enabling remote connection. It's currently at version 3.0.1 and appears to be actively maintained, with a focus on POSIX-compliant operating systems.

testing

pip install pdb-attach

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · PDB-ATTACH

pdb-attach

testingpythonv3.0.1

Install

1.5s avg

Import

129ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.140s · 17.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.119s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

listen

✓ from pdb_attach import listen

Used in the target program to enable remote attachment.

pdb_attach (command)

✓ pdb_attach <PID> <PORT>

Command-line utility to attach to a listening process.

To use `pdb-attach`, the target Python program must first be modified to call `pdb_attach.listen()` at the desired point where debugging should be enabled. This function sets up a listening socket. Then, from a separate terminal, the `pdb_attach` command-line tool is used with the target process's PID and the specified port to initiate a debugging session.

import pdb_attach import time import os def my_long_running_function(): print(f"Process PID: {os.getpid()}") print("Starting long-running function...") pdb_attach.listen(port=5555) print("pdb_attach is listening on port 5555. Attach with: pdb_attach PID 5555") for i in range(100): # Simulate work time.sleep(1) if i % 10 == 0: print(f"Iteration {i}") print("Function finished.") if __name__ == "__main__": my_long_running_function()

Debug

Known issues

breakingpdb-attach does not work on Windows operating systems. It relies on POSIX signals for its implementation, which are not available on Windows. Although it can be imported on Windows, the `listen` function will not operate, and a warning will be raised.

fix

Use a POSIX-compliant OS (Linux, macOS) for `pdb-attach`, or explore alternative debugging tools for Windows.

affects: All versions

gotchaThe target Python process must explicitly import and call `pdb_attach.listen()` *before* you can attach to it. It cannot attach to an arbitrary, unprepared running Python process.

fix

Modify the target application's code to include `from pdb_attach import listen; listen(port=<some_port>)` at the point where you wish to enable attachment.

affects: All versions

gotchaUsing `pdb-attach` introduces a potential security risk. It uses sockets for communication, meaning that a malicious actor with access to your machine could connect to the debugging port, inspect the running process's source code and state, and even execute arbitrary Python code.

fix

Only use `pdb-attach` in secure, controlled environments. Be aware of the risks when debugging processes on machines with untrusted access.

affects: All versions

gotchapdb-attach may not work correctly in multi-threaded Python applications. Breakpoints and debugging behavior can be inconsistent across threads.

fix

Be cautious when using in multi-threaded contexts. Consider alternative debugging strategies or carefully test its behavior with your specific multi-threaded code.

affects: All versions

gotchaWhen running inside a container (e.g., Docker) and attempting to attach to a host process, `pdb-attach` might cause segmentation faults due to `ptrace(2)` relying on `struct user_regs_struct` definitions that vary between platforms.

fix

Avoid using `pdb-attach` across container/host boundaries. Debug processes within the same container or on the host directly.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pdb_attach'

The 'pdb-attach' package is not installed in the Python environment where you are trying to use it.

fix

Install the package using pip: `pip install pdb-attach`

ConnectionRefusedError: [Errno 111] Connection refused

The target Python process is not actively listening for a connection from 'pdb-attach', possibly because `pdb_attach.listen()` was not called, the process is on an unsupported OS (like Windows), or a network issue/firewall is blocking the connection. Other common error numbers for 'Connection refused' include `Errno 61` on macOS.

fix

Ensure `import pdb_attach; pdb_attach.listen()` is explicitly called within the Python program you intend to debug. Confirm the target process is running on a POSIX-compliant operating system. Verify the correct PID and port are used, and check any firewall rules that might prevent the connection.

Permission denied

The 'pdb-attach' command-line tool lacks the necessary operating system privileges (e.g., `ptrace` permissions on Linux) to attach to another running process.

fix

Run the `pdb-attach` command with elevated privileges (e.g., `sudo pdb-attach --pid <PID>`) or configure your operating system's `ptrace` settings to allow non-root debugging (e.g., by modifying `/proc/sys/kernel/yama/ptrace_scope` on Linux, though this has security implications).

Upgrade

Version history

3.0.1latest on PyPI · released Sep 23, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/smitchell556/pdb-attach ↗

packagehttps://pypi.org/project/pdb-attach/ ↗

docshttps://github.com/smitchell556/pdb-attach ↗