« back to all changes in this revision
Viewing changes to Doc/library/doctest.rst
- browse files at revision 39019
- compare with another revision
- download diff
- download tarball
- view history from revision 39019
- Committer: benjamin.peterson
- Date: 2008-04-25 01:29:10 UTC
- Revision ID: svn-v3-trunk1:6015fed2-1504-0410-9fe1-9d1591cc4771:python%2Ftrunk:62490
reformat some documentation of classes so methods and attributes are under the class directive
- files modified:
- Doc/library/asynchat.rst
added
removed
Doc/library/doctest.rst
1179
1179
1180
1180
.. versionadded:: 2.4
1181
1181
1182
:class:`DocTest` defines the following member variables. They are initialized
1183
by the constructor, and should not be modified directly.
1184
1185
1186
.. attribute:: DocTest.examples
1187
1188
A list of :class:`Example` objects encoding the individual interactive Python
1189
examples that should be run by this test.
1190
1191
1192
.. attribute:: DocTest.globs
1193
1194
The namespace (aka globals) that the examples should be run in. This is a
1195
dictionary mapping names to values. Any changes to the namespace made by the
1196
examples (such as binding new variables) will be reflected in :attr:`globs`
1197
after the test is run.
1198
1199
1200
.. attribute:: DocTest.name
1201
1202
A string name identifying the :class:`DocTest`. Typically, this is the name of
1203
the object or file that the test was extracted from.
1204
1205
1206
.. attribute:: DocTest.filename
1207
1208
The name of the file that this :class:`DocTest` was extracted from; or ``None``
1209
if the filename is unknown, or if the :class:`DocTest` was not extracted from a
1210
file.
1211
1212
1213
.. attribute:: DocTest.lineno
1214
1215
The line number within :attr:`filename` where this :class:`DocTest` begins, or
1216
``None`` if the line number is unavailable. This line number is zero-based with
1217
respect to the beginning of the file.
1218
1219
1220
.. attribute:: DocTest.docstring
1221
1222
The string that the test was extracted from, or 'None' if the string is
1223
unavailable, or if the test was not extracted from a string.
1182
:class:`DocTest` defines the following member variables. They are initialized by
1183
the constructor, and should not be modified directly.
1184
1185
1186
.. attribute:: examples
1187
1188
A list of :class:`Example` objects encoding the individual interactive Python
1189
examples that should be run by this test.
1190
1191
1192
.. attribute:: globs
1193
1194
The namespace (aka globals) that the examples should be run in. This is a
1195
dictionary mapping names to values. Any changes to the namespace made by the
1196
examples (such as binding new variables) will be reflected in :attr:`globs`
1197
after the test is run.
1198
1199
1200
.. attribute:: name
1201
1202
A string name identifying the :class:`DocTest`. Typically, this is the name
1203
of the object or file that the test was extracted from.
1204
1205
1206
.. attribute:: filename
1207
1208
The name of the file that this :class:`DocTest` was extracted from; or
1209
``None`` if the filename is unknown, or if the :class:`DocTest` was not
1210
extracted from a file.
1211
1212
1213
.. attribute:: lineno
1214
1215
The line number within :attr:`filename` where this :class:`DocTest` begins, or
1216
``None`` if the line number is unavailable. This line number is zero-based
1217
with respect to the beginning of the file.
1218
1219
1220
.. attribute:: docstring
1221
1222
The string that the test was extracted from, or 'None' if the string is
1223
unavailable, or if the test was not extracted from a string.
1224
1224
1225
1225
1226
1226
.. _doctest-example:
1237
1237
1238
1238
.. versionadded:: 2.4
1239
1239
1240
:class:`Example` defines the following member variables. They are initialized
1241
by the constructor, and should not be modified directly.
1242
1243
1244
.. attribute:: Example.source
1245
1246
A string containing the example's source code. This source code consists of a
1247
single Python statement, and always ends with a newline; the constructor adds a
1248
newline when necessary.
1249
1250
1251
.. attribute:: Example.want
1252
1253
The expected output from running the example's source code (either from stdout,
1254
or a traceback in case of exception). :attr:`want` ends with a newline unless
1255
no output is expected, in which case it's an empty string. The constructor adds
1256
a newline when necessary.
1257
1258
1259
.. attribute:: Example.exc_msg
1260
1261
The exception message generated by the example, if the example is expected to
1262
generate an exception; or ``None`` if it is not expected to generate an
1263
exception. This exception message is compared against the return value of
1264
:func:`traceback.format_exception_only`. :attr:`exc_msg` ends with a newline
1265
unless it's ``None``. The constructor adds a newline if needed.
1266
1267
1268
.. attribute:: Example.lineno
1269
1270
The line number within the string containing this example where the example
1271
begins. This line number is zero-based with respect to the beginning of the
1272
containing string.
1273
1274
1275
.. attribute:: Example.indent
1276
1277
The example's indentation in the containing string, i.e., the number of space
1278
characters that precede the example's first prompt.
1279
1280
1281
.. attribute:: Example.options
1282
1283
A dictionary mapping from option flags to ``True`` or ``False``, which is used
1284
to override default options for this example. Any option flags not contained in
1285
this dictionary are left at their default value (as specified by the
1286
:class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set.
1240
:class:`Example` defines the following member variables. They are initialized by
1241
the constructor, and should not be modified directly.
1242
1243
1244
.. attribute:: source
1245
1246
A string containing the example's source code. This source code consists of a
1247
single Python statement, and always ends with a newline; the constructor adds
1248
a newline when necessary.
1249
1250
1251
.. attribute:: want
1252
1253
The expected output from running the example's source code (either from
1254
stdout, or a traceback in case of exception). :attr:`want` ends with a
1255
newline unless no output is expected, in which case it's an empty string. The
1256
constructor adds a newline when necessary.
1257
1258
1259
.. attribute:: exc_msg
1260
1261
The exception message generated by the example, if the example is expected to
1262
generate an exception; or ``None`` if it is not expected to generate an
1263
exception. This exception message is compared against the return value of
1264
:func:`traceback.format_exception_only`. :attr:`exc_msg` ends with a newline
1265
unless it's ``None``. The constructor adds a newline if needed.
1266
1267
1268
.. attribute:: lineno
1269
1270
The line number within the string containing this example where the example
1271
begins. This line number is zero-based with respect to the beginning of the
1272
containing string.
1273
1274
1275
.. attribute:: indent
1276
1277
The example's indentation in the containing string, i.e., the number of space
1278
characters that precede the example's first prompt.
1279
1280
1281
.. attribute:: options
1282
1283
A dictionary mapping from option flags to ``True`` or ``False``, which is used
1284
to override default options for this example. Any option flags not contained
1285
in this dictionary are left at their default value (as specified by the
1286
:class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set.
1287
1287
1288
1288
1289
1289
.. _doctest-doctestfinder:
1314
1314
1315
1315
.. versionadded:: 2.4
1316
1316
1317
:class:`DocTestFinder` defines the following method:
1318
1319
1320
.. method:: DocTestFinder.find(obj[, name][, module][, globs][, extraglobs])
1321
1322
Return a list of the :class:`DocTest`\ s that are defined by *obj*'s docstring,
1323
or by any of its contained objects' docstrings.
1324
1325
The optional argument *name* specifies the object's name; this name will be used
1326
to construct names for the returned :class:`DocTest`\ s. If *name* is not
1327
specified, then ``obj.__name__`` is used.
1328
1329
The optional parameter *module* is the module that contains the given object.
1330
If the module is not specified or is None, then the test finder will attempt to
1331
automatically determine the correct module. The object's module is used:
1332
1333
* As a default namespace, if *globs* is not specified.
1334
1335
* To prevent the DocTestFinder from extracting DocTests from objects that are
1336
imported from other modules. (Contained objects with modules other than
1337
*module* are ignored.)
1338
1339
* To find the name of the file containing the object.
1340
1341
* To help find the line number of the object within its file.
1342
1343
If *module* is ``False``, no attempt to find the module will be made. This is
1344
obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
1345
is ``None`` but cannot be found automatically, then all objects are considered
1346
to belong to the (non-existent) module, so all contained objects will
1347
(recursively) be searched for doctests.
1348
1349
The globals for each :class:`DocTest` is formed by combining *globs* and
1350
*extraglobs* (bindings in *extraglobs* override bindings in *globs*). A new
1351
shallow copy of the globals dictionary is created for each :class:`DocTest`. If
1352
*globs* is not specified, then it defaults to the module's *__dict__*, if
1353
specified, or ``{}`` otherwise. If *extraglobs* is not specified, then it
1354
defaults to ``{}``.
1317
:class:`DocTestFinder` defines the following method:
1318
1319
1320
.. method:: find(obj[, name][, module][, globs][, extraglobs])
1321
1322
Return a list of the :class:`DocTest`\ s that are defined by *obj*'s
1323
docstring, or by any of its contained objects' docstrings.
1324
1325
The optional argument *name* specifies the object's name; this name will be
1326
used to construct names for the returned :class:`DocTest`\ s. If *name* is
1327
not specified, then ``obj.__name__`` is used.
1328
1329
The optional parameter *module* is the module that contains the given object.
1330
If the module is not specified or is None, then the test finder will attempt
1331
to automatically determine the correct module. The object's module is used:
1332
1333
* As a default namespace, if *globs* is not specified.
1334
1335
* To prevent the DocTestFinder from extracting DocTests from objects that are
1336
imported from other modules. (Contained objects with modules other than
1337
*module* are ignored.)
1338
1339
* To find the name of the file containing the object.
1340
1341
* To help find the line number of the object within its file.
1342
1343
If *module* is ``False``, no attempt to find the module will be made. This is
1344
obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
1345
is ``None`` but cannot be found automatically, then all objects are considered
1346
to belong to the (non-existent) module, so all contained objects will
1347
(recursively) be searched for doctests.
1348
1349
The globals for each :class:`DocTest` is formed by combining *globs* and
1350
*extraglobs* (bindings in *extraglobs* override bindings in *globs*). A new
1351
shallow copy of the globals dictionary is created for each :class:`DocTest`.
1352
If *globs* is not specified, then it defaults to the module's *__dict__*, if
1353
specified, or ``{}`` otherwise. If *extraglobs* is not specified, then it
1354
defaults to ``{}``.
1355
1355
1356
1356
1357
1357
.. _doctest-doctestparser:
1367
1367
1368
1368
.. versionadded:: 2.4
1369
1369
1370
:class:`DocTestParser` defines the following methods:
1371
1372
1373
.. method:: DocTestParser.get_doctest(string, globs, name, filename, lineno)
1374
1375
Extract all doctest examples from the given string, and collect them into a
1376
:class:`DocTest` object.
1377
1378
*globs*, *name*, *filename*, and *lineno* are attributes for the new
1379
:class:`DocTest` object. See the documentation for :class:`DocTest` for more
1380
information.
1381
1382
1383
.. method:: DocTestParser.get_examples(string[, name])
1384
1385
Extract all doctest examples from the given string, and return them as a list of
1386
:class:`Example` objects. Line numbers are 0-based. The optional argument
1387
*name* is a name identifying this string, and is only used for error messages.
1388
1389
1390
.. method:: DocTestParser.parse(string[, name])
1391
1392
Divide the given string into examples and intervening text, and return them as a
1393
list of alternating :class:`Example`\ s and strings. Line numbers for the
1394
:class:`Example`\ s are 0-based. The optional argument *name* is a name
1395
identifying this string, and is only used for error messages.
1370
:class:`DocTestParser` defines the following methods:
1371
1372
1373
.. method:: get_doctest(string, globs, name, filename, lineno)
1374
1375
Extract all doctest examples from the given string, and collect them into a
1376
:class:`DocTest` object.
1377
1378
*globs*, *name*, *filename*, and *lineno* are attributes for the new
1379
:class:`DocTest` object. See the documentation for :class:`DocTest` for more
1380
information.
1381
1382
1383
.. method:: get_examples(string[, name])
1384
1385
Extract all doctest examples from the given string, and return them as a list
1386
of :class:`Example` objects. Line numbers are 0-based. The optional argument
1387
*name* is a name identifying this string, and is only used for error messages.
1388
1389
1390
.. method:: parse(string[, name])
1391
1392
Divide the given string into examples and intervening text, and return them as
1393
a list of alternating :class:`Example`\ s and strings. Line numbers for the
1394
:class:`Example`\ s are 0-based. The optional argument *name* is a name
1395
identifying this string, and is only used for error messages.
1396
1396
1397
1397
1398
1398
.. _doctest-doctestrunner:
1436
1436
1437
1437
.. versionadded:: 2.4
1438
1438
1439
:class:`DocTestParser` defines the following methods:
1440
1441
1442
.. method:: DocTestRunner.report_start(out, test, example)
1443
1444
Report that the test runner is about to process the given example. This method
1445
is provided to allow subclasses of :class:`DocTestRunner` to customize their
1446
output; it should not be called directly.
1447
1448
*example* is the example about to be processed. *test* is the test containing
1449
*example*. *out* is the output function that was passed to
1450
:meth:`DocTestRunner.run`.
1451
1452
1453
.. method:: DocTestRunner.report_success(out, test, example, got)
1454
1455
Report that the given example ran successfully. This method is provided to
1456
allow subclasses of :class:`DocTestRunner` to customize their output; it should
1457
not be called directly.
1458
1459
*example* is the example about to be processed. *got* is the actual output from
1460
the example. *test* is the test containing *example*. *out* is the output
1461
function that was passed to :meth:`DocTestRunner.run`.
1462
1463
1464
.. method:: DocTestRunner.report_failure(out, test, example, got)
1465
1466
Report that the given example failed. This method is provided to allow
1467
subclasses of :class:`DocTestRunner` to customize their output; it should not be
1468
called directly.
1469
1470
*example* is the example about to be processed. *got* is the actual output from
1471
the example. *test* is the test containing *example*. *out* is the output
1472
function that was passed to :meth:`DocTestRunner.run`.
1473
1474
1475
.. method:: DocTestRunner.report_unexpected_exception(out, test, example, exc_info)
1476
1477
Report that the given example raised an unexpected exception. This method is
1478
provided to allow subclasses of :class:`DocTestRunner` to customize their
1479
output; it should not be called directly.
1480
1481
*example* is the example about to be processed. *exc_info* is a tuple containing
1482
information about the unexpected exception (as returned by
1483
:func:`sys.exc_info`). *test* is the test containing *example*. *out* is the
1484
output function that was passed to :meth:`DocTestRunner.run`.
1485
1486
1487
.. method:: DocTestRunner.run(test[, compileflags][, out][, clear_globs])
1488
1489
Run the examples in *test* (a :class:`DocTest` object), and display the results
1490
using the writer function *out*.
1491
1492
The examples are run in the namespace ``test.globs``. If *clear_globs* is true
1493
(the default), then this namespace will be cleared after the test runs, to help
1494
with garbage collection. If you would like to examine the namespace after the
1495
test completes, then use *clear_globs=False*.
1496
1497
*compileflags* gives the set of flags that should be used by the Python compiler
1498
when running the examples. If not specified, then it will default to the set of
1499
future-import flags that apply to *globs*.
1500
1501
The output of each example is checked using the :class:`DocTestRunner`'s output
1502
checker, and the results are formatted by the :meth:`DocTestRunner.report_\*`
1503
methods.
1504
1505
1506
.. method:: DocTestRunner.summarize([verbose])
1507
1508
Print a summary of all the test cases that have been run by this DocTestRunner,
1509
and return a :term:`named tuple` ``TestResults(failed, attempted)``.
1510
1511
The optional *verbose* argument controls how detailed the summary is. If the
1512
verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is used.
1513
1514
.. versionchanged:: 2.6
1515
Use a named tuple.
1439
:class:`DocTestParser` defines the following methods:
1440
1441
1442
.. method:: report_start(out, test, example)
1443
1444
Report that the test runner is about to process the given example. This method
1445
is provided to allow subclasses of :class:`DocTestRunner` to customize their
1446
output; it should not be called directly.
1447
1448
*example* is the example about to be processed. *test* is the test
1449
*containing example*. *out* is the output function that was passed to
1450
:meth:`DocTestRunner.run`.
1451
1452
1453
.. method:: report_success(out, test, example, got)
1454
1455
Report that the given example ran successfully. This method is provided to
1456
allow subclasses of :class:`DocTestRunner` to customize their output; it
1457
should not be called directly.
1458
1459
*example* is the example about to be processed. *got* is the actual output
1460
from the example. *test* is the test containing *example*. *out* is the
1461
output function that was passed to :meth:`DocTestRunner.run`.
1462
1463
1464
.. method:: report_failure(out, test, example, got)
1465
1466
Report that the given example failed. This method is provided to allow
1467
subclasses of :class:`DocTestRunner` to customize their output; it should not
1468
be called directly.
1469
1470
*example* is the example about to be processed. *got* is the actual output
1471
from the example. *test* is the test containing *example*. *out* is the
1472
output function that was passed to :meth:`DocTestRunner.run`.
1473
1474
1475
.. method:: report_unexpected_exception(out, test, example, exc_info)
1476
1477
Report that the given example raised an unexpected exception. This method is
1478
provided to allow subclasses of :class:`DocTestRunner` to customize their
1479
output; it should not be called directly.
1480
1481
*example* is the example about to be processed. *exc_info* is a tuple
1482
containing information about the unexpected exception (as returned by
1483
:func:`sys.exc_info`). *test* is the test containing *example*. *out* is the
1484
output function that was passed to :meth:`DocTestRunner.run`.
1485
1486
1487
.. method:: run(test[, compileflags][, out][, clear_globs])
1488
1489
Run the examples in *test* (a :class:`DocTest` object), and display the
1490
results using the writer function *out*.
1491
1492
The examples are run in the namespace ``test.globs``. If *clear_globs* is
1493
true (the default), then this namespace will be cleared after the test runs,
1494
to help with garbage collection. If you would like to examine the namespace
1495
after the test completes, then use *clear_globs=False*.
1496
1497
*compileflags* gives the set of flags that should be used by the Python
1498
compiler when running the examples. If not specified, then it will default to
1499
the set of future-import flags that apply to *globs*.
1500
1501
The output of each example is checked using the :class:`DocTestRunner`'s
1502
output checker, and the results are formatted by the
1503
:meth:`DocTestRunner.report_\*` methods.
1504
1505
1506
.. method:: summarize([verbose])
1507
1508
Print a summary of all the test cases that have been run by this DocTestRunner,
1509
and return a :term:`named tuple` ``TestResults(failed, attempted)``.
1510
1511
The optional *verbose* argument controls how detailed the summary is. If the
1512
verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is
1513
used.
1514
1515
.. versionchanged:: 2.6
1516
Use a named tuple.
1516
1517
1517
1518
1518
1519
.. _doctest-outputchecker:
1531
1532
1532
1533
.. versionadded:: 2.4
1533
1534
1534
:class:`OutputChecker` defines the following methods:
1535
1536
1537
.. method:: OutputChecker.check_output(want, got, optionflags)
1538
1539
Return ``True`` iff the actual output from an example (*got*) matches the
1540
expected output (*want*). These strings are always considered to match if they
1541
are identical; but depending on what option flags the test runner is using,
1542
several non-exact match types are also possible. See section
1543
:ref:`doctest-options` for more information about option flags.
1544
1545
1546
.. method:: OutputChecker.output_difference(example, got, optionflags)
1547
1548
Return a string describing the differences between the expected output for a
1549
given example (*example*) and the actual output (*got*). *optionflags* is the
1550
set of option flags used to compare *want* and *got*.
1535
:class:`OutputChecker` defines the following methods:
1536
1537
1538
.. method:: check_output(want, got, optionflags)
1539
1540
Return ``True`` iff the actual output from an example (*got*) matches the
1541
expected output (*want*). These strings are always considered to match if
1542
they are identical; but depending on what option flags the test runner is
1543
using, several non-exact match types are also possible. See section
1544
:ref:`doctest-options` for more information about option flags.
1545
1546
1547
.. method:: output_difference(example, got, optionflags)
1548
1549
Return a string describing the differences between the expected output for a
1550
given example (*example*) and the actual output (*got*). *optionflags* is the
1551
set of option flags used to compare *want* and *got*.
1551
1552
1552
1553
1553
1554
.. _doctest-debugging:
Loggerhead is a web-based interface for Breezy
Version: 2.0.1