~dkuhlman/python-training-materials/Materials

<h1>28.10. <a class="reference internal" href="#module-traceback" title="traceback: Print or retrieve a stack traceback."><code class="xref py py-mod docutils literal">traceback</code></a> — Print or retrieve a stack traceback<a class="headerlink" href="#module-traceback" title="Permalink to this headline">¶</a></h1>

This module provides a standard interface to extract, format and print stack

traces of Python programs. It exactly mimics the behavior of the Python

interpreter when it prints a stack trace. This is useful when you want to print

stack traces under program control, such as in a “wrapper” around the

interpreter.

The module uses traceback objects — this is the object type that is stored in

the variables <a class="reference internal" href="sys.html#sys.exc_traceback" title="sys.exc_traceback"><code class="xref py py-data docutils literal">sys.exc_traceback</code></a> (deprecated) and

<a class="reference internal" href="sys.html#sys.last_traceback" title="sys.last_traceback"><code class="xref py py-data docutils literal">sys.last_traceback</code></a> and returned as the third item from

<a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal">sys.exc_info()</code></a>.

The module defines the following functions:

<code class="descclassname">traceback.</code><code class="descname">print_tb</code>(tb[, limit[, file]])<a class="headerlink" href="#traceback.print_tb" title="Permalink to this definition">¶</a></dt>

<dd>Print up to limit stack trace entries from the traceback object tb. If

limit is omitted or <code class="docutils literal">None</code>, all entries are printed. If file is omitted

or <code class="docutils literal">None</code>, the output goes to <code class="docutils literal">sys.stderr</code>; otherwise it should be an

open file or file-like object to receive the output.

</dd></dl>

100

<code class="descclassname">traceback.</code><code class="descname">print_exception</code>(etype, value, tb[, limit[, file]])<a class="headerlink" href="#traceback.print_exception" title="Permalink to this definition">¶</a></dt>

101

<dd>Print exception information and up to limit stack trace entries from the

102

traceback tb to file. This differs from <a class="reference internal" href="#traceback.print_tb" title="traceback.print_tb"><code class="xref py py-func docutils literal">print_tb()</code></a> in the following

103

ways: (1) if tb is not <code class="docutils literal">None</code>, it prints a header <code class="docutils literal">Traceback (most

104

recent call last):</code>; (2) it prints the exception etype and value after

105

the stack trace; (3) if etype is <a class="reference internal" href="exceptions.html#exceptions.SyntaxError" title="exceptions.SyntaxError"><code class="xref py py-exc docutils literal">SyntaxError</code></a> and value has the

106

appropriate format, it prints the line where the syntax error occurred with a

107

caret indicating the approximate position of the error.

108

</dd></dl>

109

110

111

112

<code class="descclassname">traceback.</code><code class="descname">print_exc</code>([limit[, file]])<a class="headerlink" href="#traceback.print_exc" title="Permalink to this definition">¶</a></dt>

113

<dd>This is a shorthand for <code class="docutils literal">print_exception(sys.exc_type, sys.exc_value,

114

sys.exc_traceback, limit, file)</code>. (In fact, it uses <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal">sys.exc_info()</code></a> to

115

retrieve the same information in a thread-safe way instead of using the

116

deprecated variables.)

117

</dd></dl>

118

119

120

121

<code class="descclassname">traceback.</code><code class="descname">format_exc</code>([limit])<a class="headerlink" href="#traceback.format_exc" title="Permalink to this definition">¶</a></dt>

122

<dd>This is like <code class="docutils literal">print_exc(limit)</code> but returns a string instead of printing to

123

a file.

124

125

New in version 2.4.

126

</div>

127

</dd></dl>

128

129

130

131

<code class="descclassname">traceback.</code><code class="descname">print_last</code>([limit[, file]])<a class="headerlink" href="#traceback.print_last" title="Permalink to this definition">¶</a></dt>

132

<dd>This is a shorthand for <code class="docutils literal">print_exception(sys.last_type, sys.last_value,

133

sys.last_traceback, limit, file)</code>. In general it will work only after

134

an exception has reached an interactive prompt (see <a class="reference internal" href="sys.html#sys.last_type" title="sys.last_type"><code class="xref py py-data docutils literal">sys.last_type</code></a>).

135

</dd></dl>

136

137

138

139

<code class="descclassname">traceback.</code><code class="descname">print_stack</code>([f[, limit[, file]]])<a class="headerlink" href="#traceback.print_stack" title="Permalink to this definition">¶</a></dt>

140

<dd>This function prints a stack trace from its invocation point. The optional

141

f argument can be used to specify an alternate stack frame to start. The

142

optional limit* and file arguments have the same meaning as for

143

<a class="reference internal" href="#traceback.print_exception" title="traceback.print_exception"><code class="xref py py-func docutils literal">print_exception()</code></a>.

144

</dd></dl>

145

146

147

148

<code class="descclassname">traceback.</code><code class="descname">extract_tb</code>(tb[, limit])<a class="headerlink" href="#traceback.extract_tb" title="Permalink to this definition">¶</a></dt>

149

<dd>Return a list of up to limit “pre-processed” stack trace entries extracted

150

from the traceback object tb. It is useful for alternate formatting of

151

stack traces. If limit is omitted or <code class="docutils literal">None</code>, all entries are extracted.

152

A “pre-processed” stack trace entry is a 4-tuple (filename, line number,

153

function name*, text) representing the information that is usually printed

154

for a stack trace. The text is a string with leading and trailing

155

whitespace stripped; if the source is not available it is <code class="docutils literal">None</code>.

156

</dd></dl>

157

158

159

160

<code class="descclassname">traceback.</code><code class="descname">extract_stack</code>([f[, limit]])<a class="headerlink" href="#traceback.extract_stack" title="Permalink to this definition">¶</a></dt>

161

<dd>Extract the raw traceback from the current stack frame. The return value has

162

the same format as for <a class="reference internal" href="#traceback.extract_tb" title="traceback.extract_tb"><code class="xref py py-func docutils literal">extract_tb()</code></a>. The optional f and limit

163

arguments have the same meaning as for <a class="reference internal" href="#traceback.print_stack" title="traceback.print_stack"><code class="xref py py-func docutils literal">print_stack()</code></a>.

164

</dd></dl>

165

166

167

168

<code class="descclassname">traceback.</code><code class="descname">format_list</code>(extracted_list)<a class="headerlink" href="#traceback.format_list" title="Permalink to this definition">¶</a></dt>

169

<dd>Given a list of tuples as returned by <a class="reference internal" href="#traceback.extract_tb" title="traceback.extract_tb"><code class="xref py py-func docutils literal">extract_tb()</code></a> or

170

<a class="reference internal" href="#traceback.extract_stack" title="traceback.extract_stack"><code class="xref py py-func docutils literal">extract_stack()</code></a>, return a list of strings ready for printing. Each

171

string in the resulting list corresponds to the item with the same index in

172

the argument list. Each string ends in a newline; the strings may contain

173

internal newlines as well, for those items whose source text line is not

174

<code class="docutils literal">None</code>.

175

</dd></dl>

176

177

178

179

<code class="descclassname">traceback.</code><code class="descname">format_exception_only</code>(etype, value)<a class="headerlink" href="#traceback.format_exception_only" title="Permalink to this definition">¶</a></dt>

180

<dd>Format the exception part of a traceback. The arguments are the exception

181

type, etype and value such as given by <code class="docutils literal">sys.last_type</code> and

182

<code class="docutils literal">sys.last_value</code>. The return value is a list of strings, each ending in a

183

newline. Normally, the list contains a single string; however, for

184

<a class="reference internal" href="exceptions.html#exceptions.SyntaxError" title="exceptions.SyntaxError"><code class="xref py py-exc docutils literal">SyntaxError</code></a> exceptions, it contains several lines that (when printed)

185

display detailed information about where the syntax error occurred. The

186

message indicating which exception occurred is the always last string in the

187

list.

188

</dd></dl>

189

190

191

192

<code class="descclassname">traceback.</code><code class="descname">format_exception</code>(etype, value, tb[, limit])<a class="headerlink" href="#traceback.format_exception" title="Permalink to this definition">¶</a></dt>

193

<dd>Format a stack trace and the exception information. The arguments have the

194

same meaning as the corresponding arguments to <a class="reference internal" href="#traceback.print_exception" title="traceback.print_exception"><code class="xref py py-func docutils literal">print_exception()</code></a>. The

195

return value is a list of strings, each ending in a newline and some

196

containing internal newlines. When these lines are concatenated and printed,

197

exactly the same text is printed as does <a class="reference internal" href="#traceback.print_exception" title="traceback.print_exception"><code class="xref py py-func docutils literal">print_exception()</code></a>.

198

</dd></dl>

199

200

201

202

<code class="descclassname">traceback.</code><code class="descname">format_tb</code>(tb[, limit])<a class="headerlink" href="#traceback.format_tb" title="Permalink to this definition">¶</a></dt>

203

<dd>A shorthand for <code class="docutils literal">format_list(extract_tb(tb, limit))</code>.

204

</dd></dl>

205

206

207

208

<code class="descclassname">traceback.</code><code class="descname">format_stack</code>([f[, limit]])<a class="headerlink" href="#traceback.format_stack" title="Permalink to this definition">¶</a></dt>

209

<dd>A shorthand for <code class="docutils literal">format_list(extract_stack(f, limit))</code>.

210

</dd></dl>

211

212

213

214

<code class="descclassname">traceback.</code><code class="descname">tb_lineno</code>(tb)<a class="headerlink" href="#traceback.tb_lineno" title="Permalink to this definition">¶</a></dt>

215

<dd>This function returns the current line number set in the traceback object.

216

This function was necessary because in versions of Python prior to 2.3 when

217

the <a class="reference internal" href="../using/cmdline.html#cmdoption-O"><code class="xref std std-option docutils literal">-O</code></a> flag was passed to Python the <code class="docutils literal">tb.tb_lineno</code> was not

218

updated correctly. This function has no use in versions past 2.3.

219

</dd></dl>

220

221

222

<h2>28.10.1. Traceback Examples<a class="headerlink" href="#traceback-examples" title="Permalink to this headline">¶</a></h2>

223

This simple example implements a basic read-eval-print loop, similar to (but

224

less useful than) the standard Python interactive interpreter loop. For a more

225

complete implementation of the interpreter loop, refer to the <a class="reference internal" href="code.html#module-code" title="code: Facilities to implement read-eval-print loops."><code class="xref py py-mod docutils literal">code</code></a>

226

module.

227

<div class="highlight-python"><div class="highlight"><pre>import sys, traceback

228

229

def run_user_code(envdir):

230

source = raw_input(">>> ")

231

try:

232

exec source in envdir

233

except:

234

print "Exception in user code:"

235

print '-'*60

236

traceback.print_exc(file=sys.stdout)

237

print '-'*60

238

239

envdir = {}

240

while 1:

241

run_user_code(envdir)

242

</pre></div>

243

</div>

244

The following example demonstrates the different ways to print and format the

245

exception and traceback:

246

<div class="highlight-python"><div class="highlight"><pre>import sys, traceback

247

248

def lumberjack():

249

bright_side_of_death()

250

251

def bright_side_of_death():

252

return tuple()[0]

253

254

try:

255

lumberjack()

256

except IndexError:

257

exc_type, exc_value, exc_traceback = sys.exc_info()

258

print "*** print_tb:"

259

traceback.print_tb(exc_traceback, limit=1, file=sys.stdout)

260

print "*** print_exception:"

261

traceback.print_exception(exc_type, exc_value, exc_traceback,

262

limit=2, file=sys.stdout)

263

print "*** print_exc:"

264

traceback.print_exc()

265

print "*** format_exc, first and last line:"

266

formatted_lines = traceback.format_exc().splitlines()

267

print formatted_lines[0]

268

print formatted_lines[-1]

269

print "*** format_exception:"

270

print repr(traceback.format_exception(exc_type, exc_value,

271

exc_traceback))

272

print "*** extract_tb:"

273

print repr(traceback.extract_tb(exc_traceback))

274

print "*** format_tb:"

275

print repr(traceback.format_tb(exc_traceback))

276

print "*** tb_lineno:", exc_traceback.tb_lineno

277

</pre></div>

278

</div>

279

The output for the example would look similar to this:

280

<div class="highlight-python"><div class="highlight"><pre>*** print_tb:

281

File "<doctest...>", line 10, in <module>

282

lumberjack()

283

*** print_exception:

284

Traceback (most recent call last):

285

File "<doctest...>", line 10, in <module>

286

lumberjack()

287

File "<doctest...>", line 4, in lumberjack

288

bright_side_of_death()

289

IndexError: tuple index out of range

290

*** print_exc:

291

Traceback (most recent call last):

292

File "<doctest...>", line 10, in <module>

293

lumberjack()

294

File "<doctest...>", line 4, in lumberjack

295

bright_side_of_death()

296

IndexError: tuple index out of range

297

*** format_exc, first and last line:

298

Traceback (most recent call last):

299

IndexError: tuple index out of range

300

*** format_exception:

301

['Traceback (most recent call last):\n',

302

' File "<doctest...>", line 10, in <module>\n lumberjack()\n',

303

' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n',

304

' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n',

305

'IndexError: tuple index out of range\n']

306

*** extract_tb:

307

[('<doctest...>', 10, '<module>', 'lumberjack()'),

308

('<doctest...>', 4, 'lumberjack', 'bright_side_of_death()'),

309

('<doctest...>', 7, 'bright_side_of_death', 'return tuple()[0]')]

310

*** format_tb:

311

[' File "<doctest...>", line 10, in <module>\n lumberjack()\n',

312

' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n',

313

' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n']

314

*** tb_lineno: 10

315

</pre></div>

316

</div>

317

The following example shows the different ways to print and format the stack:

318

<div class="highlight-python"><div class="highlight"><pre>>>> import traceback

319

>>> def another_function():

320

... lumberstack()

321

...

322

>>> def lumberstack():

323

... traceback.print_stack()

324

... print repr(traceback.extract_stack())

325

326

...

327

>>> another_function()

328

File "<doctest>", line 10, in <module>

329

another_function()

330

File "<doctest>", line 3, in another_function

331

lumberstack()

332

File "<doctest>", line 6, in lumberstack

333

traceback.print_stack()

334

[('<doctest>', 10, '<module>', 'another_function()'),

335

('<doctest>', 3, 'another_function', 'lumberstack()'),

336

('<doctest>', 7, 'lumberstack', 'print repr(traceback.extract_stack())')]

337

[' File "<doctest>", line 10, in <module>\n another_function()\n',

338

' File "<doctest>", line 3, in another_function\n lumberstack()\n',

339

' File "<doctest>", line 8, in lumberstack\n print repr(traceback.format_stack())\n']

340

</pre></div>

341

</div>

342

This last example demonstrates the final few formatting functions:

343

<div class="highlight-python"><div class="highlight"><pre>>>> import traceback

344

>>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),

345

... ('eggs.py', 42, 'eggs', 'return "bacon"')])

346

[' File "spam.py", line 3, in <module>\n spam.eggs()\n',

347

' File "eggs.py", line 42, in eggs\n return "bacon"\n']

348

>>> an_error = IndexError('tuple index out of range')

349

>>> traceback.format_exception_only(type(an_error), an_error)

350

['IndexError: tuple index out of range\n']

351

</pre></div>

352

</div>

353

</div>

354

</div>

355

356

357

</div>

358

</div>

359

</div>

360

361

362

<h3><a href="../contents.html">Table Of Contents</a></h3>

363

<ul>

364

<li><a class="reference internal" href="#">28.10. <code class="docutils literal">traceback</code> — Print or retrieve a stack traceback</a><ul>

365

<li><a class="reference internal" href="#traceback-examples">28.10.1. Traceback Examples</a></li>

366

</ul>

367

</li>

368

</ul>

369

370

<h4>Previous topic</h4>

371

<a href="atexit.html"

372

title="previous chapter">28.9. <code class="docutils literal">atexit</code> — Exit handlers</a>

373

<h4>Next topic</h4>

374

<a href="__future__.html"

375

title="next chapter">28.11. <code class="docutils literal">__future__</code> — Future statement definitions</a>

376

377

378

<li><a href="../bugs.html">Report a Bug</a></li>

379

<li><a href="../_sources/library/traceback.txt"

380

rel="nofollow">Show Source</a></li>

381

</ul>

382

383

384

<h3>Quick search</h3>

385

386

387

388

389

390

</form>

391

392

Enter search terms or a module, class or function name.

393

394

</div>

395

396

</div>

397

</div>

398

399

</div>

400

401

<h3>Navigation</h3>

402

<ul>

403

404

<a href="../genindex.html" title="General Index"

405

>index</a></li>

406

407

<a href="../py-modindex.html" title="Python Module Index"

408

>modules</a> |</li>

409

410

<a href="__future__.html" title="28.11. __future__ — Future statement definitions"

411

>next</a> |</li>

412

413

<a href="atexit.html" title="28.9. atexit — Exit handlers"

414

>previous</a> |</li>

415

<li><img src="../_static/py.png" alt=""

416

style="vertical-align: middle; margin-top: -1px"/></li>

417

<li><a href="https://www.python.org/">Python</a> »</li>

418

<li>

419

2.7.12

420

<a href="../index.html">Documentation</a> »

421

</li>

422

423

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>

424

<li class="nav-item nav-item-2"><a href="python.html" >28. Python Runtime Services</a> »</li>

425

</ul>

426

</div>

427

428

429

430

The Python Software Foundation is a non-profit corporation.

431

<a href="https://www.python.org/psf/donations/">Please donate.</a>

432

433

Last updated on Sep 20, 2016.

434

<a href="../bugs.html">Found a bug</a>?

435

436

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

437

</div>

438

439

</body>

440

</html>

b'\\ No newline at end of file'

Older »