Minor edits to faulthandler doc

[merwok]

BPO	12209
Nosy	@vstinner, @merwok
Files	faulthandler-doc.diff

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2014-03-25.11:36:24.625>
created_at = <Date 2011-05-29.17:30:03.275>
labels = ['docs']
title = 'Minor edits to faulthandler doc'
updated_at = <Date 2014-03-25.14:44:08.534>
user = 'https://github.com/merwok'

bugs.python.org fields:

activity = <Date 2014-03-25.14:44:08.534>
actor = 'eric.araujo'
assignee = 'docs@python'
closed = True
closed_date = <Date 2014-03-25.11:36:24.625>
closer = 'vstinner'
components = ['Documentation']
creation = <Date 2011-05-29.17:30:03.275>
creator = 'eric.araujo'
dependencies = []
files = ['22177']
hgrepos = []
issue_num = 12209
keywords = ['patch', 'needs review']
message_count = 8.0
messages = ['137206', '137231', '137265', '137274', '137275', '214811', '214812', '214827']
nosy_count = 4.0
nosy_names = ['vstinner', 'eric.araujo', 'docs@python', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'patch review'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue12209'
versions = ['Python 3.3']

[merwok]

I made some grammar fixes in faulthandler.rst and tweaked the example to better show what the module does.

I’d like to fix the synopsis too: “dump the Python traceback” is not very clear to me. It is the traceback or the stack trace? Why is it called “the” traceback? Something like “dumping the stack trace on CPython crashes” would be better IMO.

[vstinner]

What do you call a "stack trace"? I use this term in the C language, especially when using the "where" command of gdb. In Python, the stack trace is called a "traceback". Anyway, faulthandler prints the Python trace, not the C trace, so I prefer to call it a "traceback" than "stack trace".

faulthandler.dump_traceback() output is similar to:

try:
    raise ValueError()
except:
    exctype, value, tb = sys.exc_info()
    traceback.print_tb(tb)

faulthandler doesn't print the line from the script, only the function name, file name and line number; and the first line is different.

[merwok]

faulthandler prints the Python trace, not the C trace, so I prefer to
call it a "traceback" than "stack trace".
Okay. What do you think about this synopsis then: dumping the traceback on CPython crashes?

[vstinner]

dumping the traceback on CPython crashes?

faulthandler is no more specific to crashes: you can dump the tracebacks while Python is running using a signal or an explicit call to faulthandler.dump_traceback().

[merwok]

Okay, I understand now that the traceback always exists, not only during exceptions. The module gives control over the display of that traceback. Am I right?

[python-dev]

New changeset a97dcdee35f9 by Victor Stinner in branch '3.4':
Issue bpo-12209: Minor edits to faulthandler doc. Patch written by Éric Araujo.
http://hg.python.org/cpython/rev/a97dcdee35f9

New changeset 6f80ca0012ae by Victor Stinner in branch 'default':
(Merge 3.4) Issue bpo-12209: Minor edits to faulthandler doc. Patch written by
http://hg.python.org/cpython/rev/6f80ca0012ae

[vstinner]

Sorry for the delay. I applied your patch.

[merwok]

Thanks!