pdb — 파이썬 디버거

소스 코드: Lib/pdb.py

---

pdb 모듈은 파이썬 프로그램을 위한 대화형 소스 코드 디버거를 정의합니다. 소스 라인 단계의 중단점(breakpoint) 및 단계 실행(single stepping) 설정, 스택 프레임 검사, 소스 코드 목록, 그리고 모든 스택 프레임의 컨텍스트에서 임의의 파이썬 코드 평가를 지원합니다. 또한 포스트-모템(post-mortem) 디버깅을 지원하며, 프로그램 제어 하에서도 호출될 수 있습니다.

이 디버거는 확장이 가능합니다 – 디버거는 실제로 Pdb 클래스로 정의됩니다. 현재 문서화되어 있진 않지만, 소스를 읽어보시면 쉽게 이해하실 수 있습니다. 확장 인터페이스는 bdb 와 cmd 모듈을 활용합니다.

더 보기

Module faulthandler

Used to dump Python tracebacks explicitly, on a fault, after a timeout, or on a user signal.

Module traceback

Standard interface to extract, format and print stack traces of Python programs.

The typical usage to break into the debugger is to insert:

import pdb; pdb.set_trace()

Or:

breakpoint()

at the location you want to break into the debugger, and then run the program. You can then step through the code following this statement, and continue running without the debugger using the continue command.

버전 3.7에서 변경: The built-in breakpoint(), when called with defaults, can be used instead of import pdb; pdb.set_trace().

def double(x):
   breakpoint()
   return x * 2
val = 3
print(f"{val} * 2 is {double(val)}")

The debugger’s prompt is (Pdb), which is the indicator that you are in debug mode:

> ...(2)double()
-> breakpoint()
(Pdb) p x
3
(Pdb) continue
3 * 2 is 6

버전 3.3에서 변경: readline 모듈을 통한 탭-완성은 명령과 명령 인자에 사용할 수 있습니다, 예를 들면, 현재 전역 및 지역 이름들은 p 명령의 인자로 제공됩니다.

You can also invoke pdb from the command line to debug other scripts. For example:

python -m pdb myscript.py

When invoked as a module, 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.

버전 3.2에서 변경: Added the -c option to execute commands as if given in a .pdbrc file; see 디버거 명령들.

버전 3.7에서 변경: Added the -m option to execute modules similar to the way python -m does. As with a script, the debugger will pause execution just before the first line of the module.

Typical usage to execute a statement under control of the debugger is:

>>> import pdb
>>> def f(x):
...     print(1 / x)
>>> pdb.run("f(2)")
> <string>(1)<module>()
(Pdb) continue
0.5
>>>

에러가 발생하는 프로그램을 검사하는 일반적인 사용법은 다음과 같습니다:

>>> import pdb
>>> def f(x):
...     print(1 / x)
...
>>> f(0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 2, in f
ZeroDivisionError: division by zero
>>> pdb.pm()
> <stdin>(2)f()
(Pdb) p x
0
(Pdb)

버전 3.13에서 변경: The implementation of PEP 667 means that name assignments made via pdb will immediately affect the active scope, even when running inside an optimized scope.

이 모듈은 다음과 같은 함수를 정의합니다; 각 함수는 조금 다른 방식으로 디버거로 진입합니다:

pdb.run(statement, globals=None, locals=None)

디버거 제어하에 statement (주어진 문자열 또는 코드 객체)를 실행합니다. 코드가 실행하기 전에 디버거 프롬프트가 나타납니다; 중단점을 지정하고 continue를 입력하거나, step 또는 next를 통해 문장을 단계별로 살펴볼 수 있습니다. (이 모든 명령은 아래에 설명되어 있습니다.) 선택적 인자 globals 와 locals는 코드가 실행되는 환경을 구체적으로 명시합니다; 기본적으로는 이 모듈의 딕셔너리 __main__ 이 사용됩니다. (내장 함수 exec() 또는 eval() 에 대한 설명 참조.)

pdb.runeval(expression, globals=None, locals=None)

Evaluate the expression (given as a string or a code object) under debugger control. When runeval() returns, it returns the value of the expression. Otherwise this function is similar to run().

pdb.runcall(function, *args, **kwds)

주어진 인자와 함께 function (문자열이 아닌, 함수 또는 메서드 객체)를 호출합니다. runcall() 이 반환될 때, 함수 호출로 반환된 값을 반환합니다. 디버거 프롬프트는 함수에 진입하자마자 나타납니다.

pdb.set_trace(*, header=None)

호출하는 스택 프레임에서 디버거에 진입합니다. 코드가 디버그 되지 않는 경우 일지라도 (예를 들면, assertion이 실패하는 경우), 프로그램의 특정 지점에 중단점을 하드 코딩할 때 유용하게 사용됩니다. header 값을 주면, 디버깅이 시작되기 바로 전에 그 값이 콘솔에 출력됩니다.

버전 3.7에서 변경: 키워드 전용 인자 header.

버전 3.13에서 변경: set_trace() will enter the debugger immediately, rather than on the next line of code to be executed.

pdb.post_mortem(traceback=None)

주어진 traceback 객체의 포스트-모템(post-mortem) 디버깅으로 진입합니다. 만약 traceback이 주어지지 않았다면, 현재 처리되고 있는 하나의 예외를 사용합니다. (기본값을 사용하는 경우 예외는 반드시 처리되고 있어야 합니다.)

pdb.pm()

Enter post-mortem debugging of the exception found in sys.last_exc.

run* 함수와 set_trace()는 Pdb 클래스를 인스턴스 화하고 같은 이름의 메서드를 호출하는 에일리어스(alias) 입니다. 더 많은 기능에 액세스하려면, 아래를 참고하여 직접 하셔야 합니다:

class pdb.Pdb(completekey='tab', stdin=None, stdout=None, skip=None, nosigint=False, readrc=True)

Pdb 는 디버거 클래스입니다.

completekey, stdin 그리고 stdout 인자는 내부 cmd.Cmd 클래스로 전달됩니다; 자세한 설명은 해당 클래스에서 확인할 수 있습니다.

skip 인자가 주어진다면, 반드시 글로브-스타일(glob-style) 모듈 이름 패턴의 이터러블(iterable) 이어야 합니다. 디버거는 이 패턴 중 하나와 일치하는 모듈에서 시작되는 프레임 단계로 들어가지 않습니다. [1]

By default, Pdb sets a handler for the SIGINT signal (which is sent when the user presses Ctrl-C on the console) when you give a continue command. This allows you to break into the debugger again by pressing Ctrl-C. If you want Pdb not to touch the SIGINT handler, set nosigint to true.

readrc 인자는 기본적으로 참이고 Pdb가 파일 시스템으로부터 .pdbrc를 불러올지 여부를 제어합니다.

skip으로 추적하기 위한 호출 예시:

import pdb; pdb.Pdb(skip=['django.*']).set_trace()

인자 없이 감사 이벤트 pdb.Pdb를 발생시킵니다.

버전 3.1에서 변경: Added the skip parameter.

버전 3.2에서 변경: Added the nosigint parameter. Previously, a SIGINT handler was never set by Pdb.

버전 3.6에서 변경: readrc 인자.

run(statement, globals=None, locals=None)

runeval(expression, globals=None, locals=None)

runcall(function, *args, **kwds)

set_trace()

위에 설명된 함수에 대한 설명서를 참조하시면 됩니다.

디버거 명령들

디버거가 인식할 수 있는 명령이 아래 나열되어 있습니다. 대부분의 명령은 한두 문자로 단축될 수 있습니다; 예를 들면, h(elp) 는 h 또는 help로 help 명령을 입력할 때 사용할 수 있습니다. (하지만 he, hel, H, Help 또는 HELP는 사용할 수 없습니다.) 인자는 반드시 명령과 공백(스페이스나 탭)으로 분리되어야 합니다. 선택적 인자는 명령 문법에서 대괄호([])로 묶여있습니다; 대괄호는 입력하지 않습니다. 명령 문법에서 대체 가능한 인자는 세로 바(|)로 분리되어 있습니다.

빈 줄을 입력하면 마지막으로 입력된 명령이 반복됩니다. 예외: 만약 마지막 명령이 list 명령이면, 다음 11줄이 나열됩니다.

디버거가 인식하지 못하는 명령은 파이썬 문장으로 가정하고 디버깅 중인 프로그램의 컨텍스트에서 실행됩니다. 파이썬 문장 앞에 느낌표(!)를 붙여 사용할 수도 있습니다. 이 방법은 디버깅 중인 프로그램을 검사하는 강력한 방법입니다. 변수를 변경하거나 함수를 호출하는 것도 가능합니다. 이 문장에서 예외가 발생하면, 예외 명은 출력되지만 디버거의 상태는 변경되지 않습니다.

버전 3.13에서 변경: Expressions/Statements whose prefix is a pdb command are now correctly identified and executed.

디버거는 에일리어스을 지원합니다. 에일리어스는 검사 중인 컨텍스트에서 특정 수준의 적응성을 허용하는 매개변수를 가질 수 있습니다.

Multiple commands may be entered on a single line, separated by ;;. (A single ; is not used as it is the separator for multiple commands in a line that is passed to the Python parser.) No intelligence is applied to separating the commands; the input is split at the first ;; pair, even if it is in the middle of a quoted string. A workaround for strings with double semicolons is to use implicit string concatenation ';'';' or ";"";".

To set a temporary global variable, use a convenience variable. A convenience variable is a variable whose name starts with $. For example, $foo = 1 sets a global variable $foo which you can use in the debugger session. The convenience variables are cleared when the program resumes execution so it’s less likely to interfere with your program compared to using normal variables like foo = 1.

There are three preset convenience variables:

• $_frame: the current frame you are debugging

• $_retval: the return value if the frame is returning

• $_exception: the exception if the frame is raising an exception

Added in version 3.12: Added the convenience variable feature.

If a file .pdbrc exists in the user’s home directory or in the current directory, it is read with 'utf-8' encoding and executed as if it had been typed at the debugger prompt, with the exception that empty lines and lines starting with # are ignored. This is particularly useful for aliases. If both files exist, the one in the home directory is read first and aliases defined there can be overridden by the local file.

버전 3.2에서 변경: .pdbrc 는 continue와 next같이 디버깅을 계속하는 명령을 포함할 수 있습니다. 이전에는, 이런 명령이 효과가 없었습니다.

버전 3.11에서 변경: .pdbrc is now read with 'utf-8' encoding. Previously, it was read with the system locale encoding.

h(elp) [command]

인자가 없는 경우에는, 사용 가능한 명령 리스트를 출력합니다. command 인자가 주어진 경우에는, 해당 명령의 도움말을 출력합니다. help pdb 는 전체 문서(pdb 모듈의 독스트링)를 표시합니다. command 인자는 반드시 식별자이어야 하므로, ! 명령의 도움말을 얻기 위해서 help exec 가 꼭 입력되어야 합니다.

w(here)

Print a stack trace, with the most recent frame at the bottom. An arrow (>) indicates the current frame, which determines the context of most commands.

d(own) [count]

스택 트레이스에서 현재 프레임을 count (기본 1) 단계 아래로 (새로운 프레임으로) 이동합니다.

u(p) [count]

스택 트레이스에서 현재 프레임을 count (기본 1) 단계 위로 (이전 프레임으로) 이동합니다.

b(reak) [([filename:]lineno | function) [, condition]]

With a lineno argument, set a break at line lineno in the current file. The line number may be prefixed with a filename and a colon, to specify a breakpoint in another file (possibly one that hasn’t been loaded yet). The file is searched on sys.path. Accepatable forms of filename are /abspath/to/file.py, relpath/file.py, module and package.module.

With a function argument, set a break at the first executable statement within that function. function can be any expression that evaluates to a function in the current namespace.

두 번째 인자가 있는 경우, 중단점을 적용하기 전에 표현식이 반드시 참이어야 합니다.

인자가 없다면, 각 중단점, 중단점에 도달한 횟수, 현재까지 무시 횟수, 그리고 관련 조건(있는 경우)을 포함한 모든 중단지점을 나열합니다.

Each breakpoint is assigned a number to which all the other breakpoint commands refer.

tbreak [([filename:]lineno | function) [, condition]]

한번 도달하면 제거되는 임시중단점입니다. 인자는 break과 동일합니다.

cl(ear) [filename:lineno | bpnumber ...]

filename:lineno 인자가 주어진 경우, 해당 줄에 있는 모든 중단점을 제거합니다. 공백으로 구분된 중단점 번호 배열이 주어진 경우, 해당 중단점을 제거합니다. 인자가 없는 경우, 모든 중단지점을 재차 확인 후 제거합니다.

disable bpnumber [bpnumber ...]

공백으로 구분된 중단점 번호로 해당 중단점을 비활성화합니다. 중단점을 비활성화하는 것은 프로그램이 실행을 중단할 수 없다는 것입니다, 하지만 중단점을 제거하는 것과는 달리, 중단점 목록에 남아있으며 (재-)활성화할 수 있습니다.

enable bpnumber [bpnumber ...]

지정된 중단점을 활성화합니다.

ignore bpnumber [count]

Set the ignore count for the given breakpoint number. If count is omitted, the ignore count is set to 0. A breakpoint becomes active when the ignore count is zero. When non-zero, the count is decremented each time the breakpoint is reached and the breakpoint is not disabled and any associated condition evaluates to true.

condition bpnumber [condition]

중단점에 새로운 condition을 설정합니다, 표현식이 참일 때만 중단점이 적용됩니다. 만약 condition이 없다면, 설정되어있던 모든 조건이 제거됩니다; 즉, 중단점에 적용되어있던 조건이 없어집니다.

commands [bpnumber]

중단점 번호 bpnumber 에 대한 명령을 지정합니다. 명령 목록은 다음 줄에 나타나게 됩니다. 명령을 종료하려면 end만 입력하면 됩니다. 예를 들면:

(Pdb) commands 1
(com) p some_variable
(com) end
(Pdb)

중단점에 지정된 모든 명령을 제거하려면, commands 입력 후에 바로 end를 입력하면 됩니다; 즉, 아무 명령을 설정하지 않는 것입니다.

bpnumber 인자가 주어지지 않으면, commands는 마지막 중단점 묶음을 참조하게 됩니다.

중단점 명령을 활용해서 프로그램을 다시 시작할 수도 있습니다. continue 명령이나, step 또는 실행을 재개하는 다른 명령을 사용하기만 하면 됩니다.

실행을 재개하는 아무 명령 (continue, step, next, return, jump, quit 및 해당 명령의 약어들)을 지정하는 것은 (end 명령을 붙인 것처럼) 해당 명령 목록을 끝내는 것입니다. 왜냐하면 실행을 재개할 때마다, 명령 목록을 가진 다른 중단점을 맞이할 수 있고, 어떤 목록을 실행해야 할지 모르는 상황이 생기기 때문입니다.

If you use the silent command in the command list, the usual message about stopping at a breakpoint is not printed. This may be desirable for breakpoints that are to print a specific message and then continue. If none of the other commands print anything, you see no sign that the breakpoint was reached.

s(tep)

현재 줄을 실행하고, 멈출 수 있는 가장 첫 번째 줄(호출되는 함수 또는 현재 함수의 다음 줄) 에서 멈춥니다.

n(ext)

현재 함수의 다음 줄에 도달하거나, 반환할 때까지 계속 실행합니다. next와 step의 차이점은 step은 호출된 함수 안에서 멈추고, next는 호출된 함수를 재빠르게 실행하고 현재 함수의 바로 다음 줄에서만 멈춥니다.

unt(il) [lineno]

인자가 없는 경우에는, 현재 줄 번호보다 높은 줄 번호에 도달할 때까지 계속 실행합니다.

With lineno, continue execution until a line with a number greater or equal to lineno is reached. In both cases, also stop when the current frame returns.

버전 3.2에서 변경: 줄 번호를 명시적으로 줄 수 있도록 허용합니다.

r(eturn)

현재 함수가 반환될 때까지 계속 실행합니다.

c(ont(inue))

중단점을 마주칠 때까지 계속 실행합니다.

j(ump) lineno

다음으로 실행될 줄을 설정할 수 있습니다. 프레임의 맨 마지막에서만 실행이 가능합니다. 이전 줄로 돌아가 코드를 재실행하거나, 실행을 원치 않는 코드를 건너뛸 수 있습니다.

중요한 점은 이 명령은 언제나 실행할 수 있진 않습니다 – for 루프 내부로 들어가거나 finally 절을 건너뛰는 것은 불가능합니다.

l(ist) [first[, last]]

현재 파일의 소스 코드를 나열합니다. 인자가 없는 경우, 현재 줄 주위로 11줄을 나열하거나 이전 줄을 이어서 나열합니다. 인자로 .을 입력한 경우, 현재 줄 주위로 11줄을 나열합니다. 한 인자만 주어진 경우, 해당 줄 주위로 11줄을 나열합니다. 두 인자가 주어진 경우, 두 인자 사이의 모든 줄을 나열합니다; 만약 두 번째 인자가 첫 번째 인자보다 작은 경우, 첫 번째 인자로부터 나열하는 줄 수로 인식합니다.

현재 프레임에서 현재 위치는 ->로 표시됩니다. 예외를 디버깅할 때, 예외가 최초로 발생하거나 전파된 줄이 현재 줄과 다른 경우에는 >>로 표시됩니다.

버전 3.2에서 변경: Added the >> marker.

ll | longlist

현재 함수나 프레임의 소스 코드 전체를 나열합니다. 참고할만한 줄은 list처럼 표시됩니다.

Added in version 3.2.

a(rgs)

Print the arguments of the current function and their current values.

p expression

Evaluate expression in the current context and print its value.

참고

디버거 명령은 아니지만, print()도 사용될 수 있습니다 — 이때는 파이썬의 print() 함수를 실행하게 됩니다.

pp expression

Like the p command, except the value of expression is pretty-printed using the pprint module.

whatis expression

Print the type of expression.

source expression

Try to get source code of expression and display it.

Added in version 3.2.

display [expression]

Display the value of expression if it changed, each time execution stops in the current frame.

Without expression, list all display expressions for the current frame.

참고

Display evaluates expression and compares to the result of the previous evaluation of expression, so when the result is mutable, display may not be able to pick up the changes.

Example:

lst = []
breakpoint()
pass
lst.append(1)
print(lst)

Display won’t realize lst has been changed because the result of evaluation is modified in place by lst.append(1) before being compared:

> example.py(3)<module>()
-> pass
(Pdb) display lst
display lst: []
(Pdb) n
> example.py(4)<module>()
-> lst.append(1)
(Pdb) n
> example.py(5)<module>()
-> print(lst)
(Pdb)

You can do some tricks with copy mechanism to make it work:

> example.py(3)<module>()
-> pass
(Pdb) display lst[:]
display lst[:]: []
(Pdb) n
> example.py(4)<module>()
-> lst.append(1)
(Pdb) n
> example.py(5)<module>()
-> print(lst)
display lst[:]: [1]  [old: []]
(Pdb)

Added in version 3.2.

undisplay [expression]

Do not display expression anymore in the current frame. Without expression, clear all display expressions for the current frame.

Added in version 3.2.

interact

Start an interactive interpreter (using the code module) in a new global namespace initialised from the local and global namespaces for the current scope. Use exit() or quit() to exit the interpreter and return to the debugger.

참고

As interact creates a new dedicated namespace for code execution, assignments to variables will not affect the original namespaces. However, modifications to any referenced mutable objects will be reflected in the original namespaces as usual.

Added in version 3.2.

버전 3.13에서 변경: exit() and quit() can be used to exit the interact command.

버전 3.13에서 변경: interact directs its output to the debugger’s output channel rather than sys.stderr.

alias [name [command]]

Create an alias called name that executes command. The command must not be enclosed in quotes. Replaceable parameters can be indicated by %1, %2, … and %9, while %* is replaced by all the parameters. If command is omitted, the current alias for name is shown. If no arguments are given, all aliases are listed.

에일리어스는 중첩될 수 있고 pdb 프롬프트 내에서 정당하게 입력할 수 있는 모든 것을 담을 수 있습니다. 주의할 점은 pdb 내부 명령들이 에일리어스에 의해 오버라이드 될 수 있습니다. 그 명령은 에일리어스가 없어질 때까지 사용할 수 없게 됩니다. 에일리어싱은 명령 줄의 첫 번째 단어에 회귀적으로 적용됩니다; 나머지 단어들은 적용되지 않습니다.

.pdbrc파일에 추가되면 특히 유용한 두 에일리어스 예시:

# Print instance variables (usage "pi classInst")
alias pi for k in %1.__dict__.keys(): print(f"%1.{k} = {%1.__dict__[k]}")
# Print instance variables in self
alias ps pi self

unalias name

Delete the specified alias name.

! statement

Execute the (one-line) statement in the context of the current stack frame. The exclamation point can be omitted unless the first word of the statement resembles a debugger command, e.g.:

(Pdb) ! n=42
(Pdb)

To set a global variable, you can prefix the assignment command with a global statement on the same line, e.g.:

(Pdb) global list_options; list_options = ['-l']
(Pdb)

run [args ...]

restart [args ...]

Restart the debugged Python program. If args is supplied, it is split with shlex and the result is used as the new sys.argv. History, breakpoints, actions and debugger options are preserved. restart is an alias for run.

q(uit)

디버거를 종료합니다. 실행되고 있는 프로그램이 종료됩니다.

debug code

Enter a recursive debugger that steps through code (which is an arbitrary expression or statement to be executed in the current environment).

retval

Print the return value for the last return of the current function.

exceptions [excnumber]

List or jump between chained exceptions.

When using pdb.pm() or Pdb.post_mortem(...) with a chained exception instead of a traceback, it allows the user to move between the chained exceptions using exceptions command to list exceptions, and exception <number> to switch to that exception.

Example:

def out():
    try:
        middle()
    except Exception as e:
        raise ValueError("reraise middle() error") from e

def middle():
    try:
        return inner(0)
    except Exception as e:
        raise ValueError("Middle fail")

def inner(x):
    1 / x

 out()

calling pdb.pm() will allow to move between exceptions:

> example.py(5)out()
-> raise ValueError("reraise middle() error") from e

(Pdb) exceptions
  0 ZeroDivisionError('division by zero')
  1 ValueError('Middle fail')
> 2 ValueError('reraise middle() error')

(Pdb) exceptions 0
> example.py(16)inner()
-> 1 / x

(Pdb) up
> example.py(10)middle()
-> return inner(0)

Added in version 3.13.

각주

[1]

프레임이 특정 모듈에서 시작되는 것으로 간주하는지 여부는 프레임 전역에 있는 __name__에 의해 결정됩니다.