# Copyright (C) 2001-2018, Python Software Foundation # For licence information, see README file. # msgid "" msgstr "" "Project-Id-Version: Python 3\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2020-10-01 16:00+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: FRENCH \n" "Language: fr\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: library/doctest.rst:2 msgid ":mod:`doctest` --- Test interactive Python examples" msgstr "" #: library/doctest.rst:12 #, fuzzy msgid "**Source code:** :source:`Lib/doctest.py`" msgstr "**Code source:** :source:`Lib/os.py`" #: library/doctest.rst:16 msgid "" "The :mod:`doctest` module searches for pieces of text that look like " "interactive Python sessions, and then executes those sessions to verify that " "they work exactly as shown. There are several common ways to use doctest:" msgstr "" #: library/doctest.rst:20 msgid "" "To check that a module's docstrings are up-to-date by verifying that all " "interactive examples still work as documented." msgstr "" #: library/doctest.rst:23 msgid "" "To perform regression testing by verifying that interactive examples from a " "test file or a test object work as expected." msgstr "" #: library/doctest.rst:26 msgid "" "To write tutorial documentation for a package, liberally illustrated with " "input-output examples. Depending on whether the examples or the expository " "text are emphasized, this has the flavor of \"literate testing\" or " "\"executable documentation\"." msgstr "" #: library/doctest.rst:31 msgid "Here's a complete but small example module::" msgstr "" #: library/doctest.rst:88 msgid "" "If you run :file:`example.py` directly from the command line, :mod:`doctest` " "works its magic:" msgstr "" #: library/doctest.rst:96 msgid "" "There's no output! That's normal, and it means all the examples worked. " "Pass ``-v`` to the script, and :mod:`doctest` prints a detailed log of what " "it's trying, and prints a summary at the end:" msgstr "" #: library/doctest.rst:114 msgid "And so on, eventually ending with:" msgstr "" #: library/doctest.rst:133 msgid "" "That's all you need to know to start making productive use of :mod:" "`doctest`! Jump in. The following sections provide full details. Note that " "there are many examples of doctests in the standard Python test suite and " "libraries. Especially useful examples can be found in the standard test " "file :file:`Lib/test/test_doctest.py`." msgstr "" #: library/doctest.rst:143 msgid "Simple Usage: Checking Examples in Docstrings" msgstr "" #: library/doctest.rst:145 msgid "" "The simplest way to start using doctest (but not necessarily the way you'll " "continue to do it) is to end each module :mod:`M` with::" msgstr "" #: library/doctest.rst:152 msgid ":mod:`doctest` then examines docstrings in module :mod:`M`." msgstr "" #: library/doctest.rst:154 msgid "" "Running the module as a script causes the examples in the docstrings to get " "executed and verified::" msgstr "" #: library/doctest.rst:159 msgid "" "This won't display anything unless an example fails, in which case the " "failing example(s) and the cause(s) of the failure(s) are printed to stdout, " "and the final line of output is ``***Test Failed*** N failures.``, where *N* " "is the number of examples that failed." msgstr "" #: library/doctest.rst:164 msgid "Run it with the ``-v`` switch instead::" msgstr "" #: library/doctest.rst:168 msgid "" "and a detailed report of all examples tried is printed to standard output, " "along with assorted summaries at the end." msgstr "" #: library/doctest.rst:171 msgid "" "You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, " "or prohibit it by passing ``verbose=False``. In either of those cases, " "``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not " "has no effect)." msgstr "" #: library/doctest.rst:176 msgid "" "There is also a command line shortcut for running :func:`testmod`. You can " "instruct the Python interpreter to run the doctest module directly from the " "standard library and pass the module name(s) on the command line::" msgstr "" #: library/doctest.rst:182 msgid "" "This will import :file:`example.py` as a standalone module and run :func:" "`testmod` on it. Note that this may not work correctly if the file is part " "of a package and imports other submodules from that package." msgstr "" #: library/doctest.rst:186 msgid "" "For more information on :func:`testmod`, see section :ref:`doctest-basic-" "api`." msgstr "" #: library/doctest.rst:192 msgid "Simple Usage: Checking Examples in a Text File" msgstr "" #: library/doctest.rst:194 msgid "" "Another simple application of doctest is testing interactive examples in a " "text file. This can be done with the :func:`testfile` function::" msgstr "" #: library/doctest.rst:200 msgid "" "That short script executes and verifies any interactive Python examples " "contained in the file :file:`example.txt`. The file content is treated as " "if it were a single giant docstring; the file doesn't need to contain a " "Python program! For example, perhaps :file:`example.txt` contains this:" msgstr "" #: library/doctest.rst:223 msgid "" "Running ``doctest.testfile(\"example.txt\")`` then finds the error in this " "documentation::" msgstr "" #: library/doctest.rst:234 msgid "" "As with :func:`testmod`, :func:`testfile` won't display anything unless an " "example fails. If an example does fail, then the failing example(s) and the " "cause(s) of the failure(s) are printed to stdout, using the same format as :" "func:`testmod`." msgstr "" #: library/doctest.rst:239 msgid "" "By default, :func:`testfile` looks for files in the calling module's " "directory. See section :ref:`doctest-basic-api` for a description of the " "optional arguments that can be used to tell it to look for files in other " "locations." msgstr "" #: library/doctest.rst:243 msgid "" "Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the ``-" "v`` command-line switch or with the optional keyword argument *verbose*." msgstr "" #: library/doctest.rst:247 msgid "" "There is also a command line shortcut for running :func:`testfile`. You can " "instruct the Python interpreter to run the doctest module directly from the " "standard library and pass the file name(s) on the command line::" msgstr "" #: library/doctest.rst:253 msgid "" "Because the file name does not end with :file:`.py`, :mod:`doctest` infers " "that it must be run with :func:`testfile`, not :func:`testmod`." msgstr "" #: library/doctest.rst:256 msgid "" "For more information on :func:`testfile`, see section :ref:`doctest-basic-" "api`." msgstr "" #: library/doctest.rst:262 msgid "How It Works" msgstr "" #: library/doctest.rst:264 msgid "" "This section examines in detail how doctest works: which docstrings it looks " "at, how it finds interactive examples, what execution context it uses, how " "it handles exceptions, and how option flags can be used to control its " "behavior. This is the information that you need to know to write doctest " "examples; for information about actually running doctest on these examples, " "see the following sections." msgstr "" #: library/doctest.rst:275 msgid "Which Docstrings Are Examined?" msgstr "" #: library/doctest.rst:277 msgid "" "The module docstring, and all function, class and method docstrings are " "searched. Objects imported into the module are not searched." msgstr "" #: library/doctest.rst:280 msgid "" "In addition, if ``M.__test__`` exists and \"is true\", it must be a dict, " "and each entry maps a (string) name to a function object, class object, or " "string. Function and class object docstrings found from ``M.__test__`` are " "searched, and strings are treated as if they were docstrings. In output, a " "key ``K`` in ``M.__test__`` appears with name ::" msgstr "" #: library/doctest.rst:288 msgid "" "Any classes found are recursively searched similarly, to test docstrings in " "their contained methods and nested classes." msgstr "" #: library/doctest.rst:299 msgid "How are Docstring Examples Recognized?" msgstr "" #: library/doctest.rst:301 msgid "" "In most cases a copy-and-paste of an interactive console session works fine, " "but doctest isn't trying to do an exact emulation of any specific Python " "shell." msgstr "" #: library/doctest.rst:326 msgid "" "Any expected output must immediately follow the final ``'>>> '`` or ``'... " "'`` line containing the code, and the expected output (if any) extends to " "the next ``'>>> '`` or all-whitespace line." msgstr "" #: library/doctest.rst:330 msgid "The fine print:" msgstr "" #: library/doctest.rst:332 msgid "" "Expected output cannot contain an all-whitespace line, since such a line is " "taken to signal the end of expected output. If expected output does contain " "a blank line, put ```` in your doctest example each place a blank " "line is expected." msgstr "" #: library/doctest.rst:337 msgid "" "All hard tab characters are expanded to spaces, using 8-column tab stops. " "Tabs in output generated by the tested code are not modified. Because any " "hard tabs in the sample output *are* expanded, this means that if the code " "output includes hard tabs, the only way the doctest can pass is if the :" "const:`NORMALIZE_WHITESPACE` option or :ref:`directive ` " "is in effect. Alternatively, the test can be rewritten to capture the output " "and compare it to an expected value as part of the test. This handling of " "tabs in the source was arrived at through trial and error, and has proven to " "be the least error prone way of handling them. It is possible to use a " "different algorithm for handling tabs by writing a custom :class:" "`DocTestParser` class." msgstr "" #: library/doctest.rst:349 msgid "" "Output to stdout is captured, but not output to stderr (exception tracebacks " "are captured via a different means)." msgstr "" #: library/doctest.rst:352 msgid "" "If you continue a line via backslashing in an interactive session, or for " "any other reason use a backslash, you should use a raw docstring, which will " "preserve your backslashes exactly as you type them::" msgstr "" #: library/doctest.rst:361 msgid "" "Otherwise, the backslash will be interpreted as part of the string. For " "example, the ``\\n`` above would be interpreted as a newline character. " "Alternatively, you can double each backslash in the doctest version (and not " "use a raw string)::" msgstr "" #: library/doctest.rst:370 msgid "The starting column doesn't matter::" msgstr "" #: library/doctest.rst:377 msgid "" "and as many leading whitespace characters are stripped from the expected " "output as appeared in the initial ``'>>> '`` line that started the example." msgstr "" #: library/doctest.rst:384 msgid "What's the Execution Context?" msgstr "" #: library/doctest.rst:386 msgid "" "By default, each time :mod:`doctest` finds a docstring to test, it uses a " "*shallow copy* of :mod:`M`'s globals, so that running tests doesn't change " "the module's real globals, and so that one test in :mod:`M` can't leave " "behind crumbs that accidentally allow another test to work. This means " "examples can freely use any names defined at top-level in :mod:`M`, and " "names defined earlier in the docstring being run. Examples cannot see names " "defined in other docstrings." msgstr "" #: library/doctest.rst:394 msgid "" "You can force use of your own dict as the execution context by passing " "``globs=your_dict`` to :func:`testmod` or :func:`testfile` instead." msgstr "" #: library/doctest.rst:401 msgid "What About Exceptions?" msgstr "" #: library/doctest.rst:403 msgid "" "No problem, provided that the traceback is the only output produced by the " "example: just paste in the traceback. [#]_ Since tracebacks contain details " "that are likely to change rapidly (for example, exact file paths and line " "numbers), this is one case where doctest works hard to be flexible in what " "it accepts." msgstr "" #: library/doctest.rst:409 msgid "Simple example::" msgstr "" #: library/doctest.rst:416 msgid "" "That doctest succeeds if :exc:`ValueError` is raised, with the ``list." "remove(x): x not in list`` detail as shown." msgstr "" #: library/doctest.rst:419 msgid "" "The expected output for an exception must start with a traceback header, " "which may be either of the following two lines, indented the same as the " "first line of the example::" msgstr "" #: library/doctest.rst:426 msgid "" "The traceback header is followed by an optional traceback stack, whose " "contents are ignored by doctest. The traceback stack is typically omitted, " "or copied verbatim from an interactive session." msgstr "" #: library/doctest.rst:430 msgid "" "The traceback stack is followed by the most interesting part: the line(s) " "containing the exception type and detail. This is usually the last line of " "a traceback, but can extend across multiple lines if the exception has a " "multi-line detail::" msgstr "" #: library/doctest.rst:442 msgid "" "The last three lines (starting with :exc:`ValueError`) are compared against " "the exception's type and detail, and the rest are ignored." msgstr "" #: library/doctest.rst:445 msgid "" "Best practice is to omit the traceback stack, unless it adds significant " "documentation value to the example. So the last example is probably better " "as::" msgstr "" #: library/doctest.rst:455 msgid "" "Note that tracebacks are treated very specially. In particular, in the " "rewritten example, the use of ``...`` is independent of doctest's :const:" "`ELLIPSIS` option. The ellipsis in that example could be left out, or could " "just as well be three (or three hundred) commas or digits, or an indented " "transcript of a Monty Python skit." msgstr "" #: library/doctest.rst:461 msgid "Some details you should read once, but won't need to remember:" msgstr "" #: library/doctest.rst:463 msgid "" "Doctest can't guess whether your expected output came from an exception " "traceback or from ordinary printing. So, e.g., an example that expects " "``ValueError: 42 is prime`` will pass whether :exc:`ValueError` is actually " "raised or if the example merely prints that traceback text. In practice, " "ordinary output rarely begins with a traceback header line, so this doesn't " "create real problems." msgstr "" #: library/doctest.rst:470 msgid "" "Each line of the traceback stack (if present) must be indented further than " "the first line of the example, *or* start with a non-alphanumeric character. " "The first line following the traceback header indented the same and starting " "with an alphanumeric is taken to be the start of the exception detail. Of " "course this does the right thing for genuine tracebacks." msgstr "" #: library/doctest.rst:476 msgid "" "When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is specified, " "everything following the leftmost colon and any module information in the " "exception name is ignored." msgstr "" #: library/doctest.rst:480 msgid "" "The interactive shell omits the traceback header line for some :exc:" "`SyntaxError`\\ s. But doctest uses the traceback header line to " "distinguish exceptions from non-exceptions. So in the rare case where you " "need to test a :exc:`SyntaxError` that omits the traceback header, you will " "need to manually add the traceback header line to your test example." msgstr "" #: library/doctest.rst:488 msgid "" "For some :exc:`SyntaxError`\\ s, Python displays the character position of " "the syntax error, using a ``^`` marker::" msgstr "" #: library/doctest.rst:497 msgid "" "Since the lines showing the position of the error come before the exception " "type and detail, they are not checked by doctest. For example, the " "following test would pass, even though it puts the ``^`` marker in the wrong " "location::" msgstr "" #: library/doctest.rst:513 msgid "Option Flags" msgstr "" #: library/doctest.rst:515 msgid "" "A number of option flags control various aspects of doctest's behavior. " "Symbolic names for the flags are supplied as module constants, which can be :" "ref:`bitwise ORed ` together and passed to various functions. The " "names can also be used in :ref:`doctest directives `, " "and may be passed to the doctest command line interface via the ``-o`` " "option." msgstr "" #: library/doctest.rst:521 msgid "The ``-o`` command line option." msgstr "" #: library/doctest.rst:524 msgid "" "The first group of options define test semantics, controlling aspects of how " "doctest decides whether actual output matches an example's expected output:" msgstr "" #: library/doctest.rst:530 msgid "" "By default, if an expected output block contains just ``1``, an actual " "output block containing just ``1`` or just ``True`` is considered to be a " "match, and similarly for ``0`` versus ``False``. When :const:" "`DONT_ACCEPT_TRUE_FOR_1` is specified, neither substitution is allowed. The " "default behavior caters to that Python changed the return type of many " "functions from integer to boolean; doctests expecting \"little integer\" " "output still work in these cases. This option will probably go away, but " "not for several years." msgstr "" #: library/doctest.rst:542 msgid "" "By default, if an expected output block contains a line containing only the " "string ````, then that line will match a blank line in the actual " "output. Because a genuinely blank line delimits the expected output, this " "is the only way to communicate that a blank line is expected. When :const:" "`DONT_ACCEPT_BLANKLINE` is specified, this substitution is not allowed." msgstr "" #: library/doctest.rst:551 msgid "" "When specified, all sequences of whitespace (blanks and newlines) are " "treated as equal. Any sequence of whitespace within the expected output " "will match any sequence of whitespace within the actual output. By default, " "whitespace must match exactly. :const:`NORMALIZE_WHITESPACE` is especially " "useful when a line of expected output is very long, and you want to wrap it " "across multiple lines in your source." msgstr "" #: library/doctest.rst:562 msgid "" "When specified, an ellipsis marker (``...``) in the expected output can " "match any substring in the actual output. This includes substrings that " "span line boundaries, and empty substrings, so it's best to keep usage of " "this simple. Complicated uses can lead to the same kinds of \"oops, it " "matched too much!\" surprises that ``.*`` is prone to in regular expressions." msgstr "" #: library/doctest.rst:571 msgid "" "When specified, an example that expects an exception passes if an exception " "of the expected type is raised, even if the exception detail does not " "match. For example, an example expecting ``ValueError: 42`` will pass if " "the actual exception raised is ``ValueError: 3*14``, but will fail, e.g., " "if :exc:`TypeError` is raised." msgstr "" #: library/doctest.rst:577 msgid "" "It will also ignore the module name used in Python 3 doctest reports. Hence " "both of these variations will work with the flag specified, regardless of " "whether the test is run under Python 2.7 or Python 3.2 (or later versions)::" msgstr "" #: library/doctest.rst:589 msgid "" "Note that :const:`ELLIPSIS` can also be used to ignore the details of the " "exception message, but such a test may still fail based on whether or not " "the module details are printed as part of the exception name. Using :const:" "`IGNORE_EXCEPTION_DETAIL` and the details from Python 2.3 is also the only " "clear way to write a doctest that doesn't care about the exception detail " "yet continues to pass under Python 2.3 or earlier (those releases do not " "support :ref:`doctest directives ` and ignore them as " "irrelevant comments). For example::" msgstr "" #: library/doctest.rst:603 msgid "" "passes under Python 2.3 and later Python versions with the flag specified, " "even though the detail changed in Python 2.4 to say \"does not\" instead of " "\"doesn't\"." msgstr "" #: library/doctest.rst:607 msgid "" ":const:`IGNORE_EXCEPTION_DETAIL` now also ignores any information relating " "to the module containing the exception under test." msgstr "" #: library/doctest.rst:614 msgid "" "When specified, do not run the example at all. This can be useful in " "contexts where doctest examples serve as both documentation and test cases, " "and an example should be included for documentation purposes, but should not " "be checked. E.g., the example's output might be random; or the example " "might depend on resources which would be unavailable to the test driver." msgstr "" #: library/doctest.rst:620 msgid "" "The SKIP flag can also be used for temporarily \"commenting out\" examples." msgstr "" #: library/doctest.rst:625 msgid "A bitmask or'ing together all the comparison flags above." msgstr "" #: library/doctest.rst:627 msgid "The second group of options controls how test failures are reported:" msgstr "" #: library/doctest.rst:632 msgid "" "When specified, failures that involve multi-line expected and actual outputs " "are displayed using a unified diff." msgstr "" #: library/doctest.rst:638 msgid "" "When specified, failures that involve multi-line expected and actual outputs " "will be displayed using a context diff." msgstr "" #: library/doctest.rst:644 msgid "" "When specified, differences are computed by ``difflib.Differ``, using the " "same algorithm as the popular :file:`ndiff.py` utility. This is the only " "method that marks differences within lines as well as across lines. For " "example, if a line of expected output contains digit ``1`` where actual " "output contains letter ``l``, a line is inserted with a caret marking the " "mismatching column positions." msgstr "" #: library/doctest.rst:653 msgid "" "When specified, display the first failing example in each doctest, but " "suppress output for all remaining examples. This will prevent doctest from " "reporting correct examples that break because of earlier failures; but it " "might also hide incorrect examples that fail independently of the first " "failure. When :const:`REPORT_ONLY_FIRST_FAILURE` is specified, the " "remaining examples are still run, and still count towards the total number " "of failures reported; only the output is suppressed." msgstr "" #: library/doctest.rst:664 msgid "" "When specified, exit after the first failing example and don't attempt to " "run the remaining examples. Thus, the number of failures reported will be at " "most 1. This flag may be useful during debugging, since examples after the " "first failure won't even produce debugging output." msgstr "" #: library/doctest.rst:669 msgid "" "The doctest command line accepts the option ``-f`` as a shorthand for ``-o " "FAIL_FAST``." msgstr "" #: library/doctest.rst:677 msgid "A bitmask or'ing together all the reporting flags above." msgstr "" #: library/doctest.rst:680 msgid "" "There is also a way to register new option flag names, though this isn't " "useful unless you intend to extend :mod:`doctest` internals via subclassing:" msgstr "" #: library/doctest.rst:686 msgid "" "Create a new option flag with a given name, and return the new flag's " "integer value. :func:`register_optionflag` can be used when subclassing :" "class:`OutputChecker` or :class:`DocTestRunner` to create new options that " "are supported by your subclasses. :func:`register_optionflag` should always " "be called using the following idiom::" msgstr "" #: library/doctest.rst:702 #, fuzzy msgid "Directives" msgstr "Directive" #: library/doctest.rst:704 msgid "" "Doctest directives may be used to modify the :ref:`option flags ` for an individual example. Doctest directives are special Python " "comments following an example's source code:" msgstr "" #: library/doctest.rst:715 msgid "" "Whitespace is not allowed between the ``+`` or ``-`` and the directive " "option name. The directive option name can be any of the option flag names " "explained above." msgstr "" #: library/doctest.rst:719 msgid "" "An example's doctest directives modify doctest's behavior for that single " "example. Use ``+`` to enable the named behavior, or ``-`` to disable it." msgstr "" #: library/doctest.rst:722 msgid "For example, this test passes::" msgstr "" #: library/doctest.rst:728 msgid "" "Without the directive it would fail, both because the actual output doesn't " "have two blanks before the single-digit list elements, and because the " "actual output is on a single line. This test also passes, and also requires " "a directive to do so::" msgstr "" #: library/doctest.rst:736 msgid "" "Multiple directives can be used on a single physical line, separated by " "commas::" msgstr "" #: library/doctest.rst:742 msgid "" "If multiple directive comments are used for a single example, then they are " "combined::" msgstr "" #: library/doctest.rst:749 msgid "" "As the previous example shows, you can add ``...`` lines to your example " "containing only directives. This can be useful when an example is too long " "for a directive to comfortably fit on the same line::" msgstr "" #: library/doctest.rst:757 msgid "" "Note that since all options are disabled by default, and directives apply " "only to the example they appear in, enabling options (via ``+`` in a " "directive) is usually the only meaningful choice. However, option flags can " "also be passed to functions that run doctests, establishing different " "defaults. In such cases, disabling an option via ``-`` in a directive can " "be useful." msgstr "" #: library/doctest.rst:767 msgid "Warnings" msgstr "Avertissements" #: library/doctest.rst:769 msgid "" ":mod:`doctest` is serious about requiring exact matches in expected output. " "If even a single character doesn't match, the test fails. This will " "probably surprise you a few times, as you learn exactly what Python does and " "doesn't guarantee about output. For example, when printing a set, Python " "doesn't guarantee that the element is printed in any particular order, so a " "test like ::" msgstr "" #: library/doctest.rst:778 msgid "is vulnerable! One workaround is to do ::" msgstr "" #: library/doctest.rst:783 msgid "instead. Another is to do ::" msgstr "" #: library/doctest.rst:791 msgid "" "Before Python 3.6, when printing a dict, Python did not guarantee that the " "key-value pairs was printed in any particular order." msgstr "" #: library/doctest.rst:794 msgid "There are others, but you get the idea." msgstr "" #: library/doctest.rst:796 msgid "" "Another bad idea is to print things that embed an object address, like ::" msgstr "" #: library/doctest.rst:804 msgid "" "The :const:`ELLIPSIS` directive gives a nice approach for the last example::" msgstr "" #: library/doctest.rst:809 msgid "" "Floating-point numbers are also subject to small output variations across " "platforms, because Python defers to the platform C library for float " "formatting, and C libraries vary widely in quality here. ::" msgstr "" #: library/doctest.rst:820 msgid "" "Numbers of the form ``I/2.**J`` are safe across all platforms, and I often " "contrive doctest examples to produce numbers of that form::" msgstr "" #: library/doctest.rst:826 msgid "" "Simple fractions are also easier for people to understand, and that makes " "for better documentation." msgstr "" #: library/doctest.rst:833 msgid "Basic API" msgstr "" #: library/doctest.rst:835 msgid "" "The functions :func:`testmod` and :func:`testfile` provide a simple " "interface to doctest that should be sufficient for most basic uses. For a " "less formal introduction to these two functions, see sections :ref:`doctest-" "simple-testmod` and :ref:`doctest-simple-testfile`." msgstr "" #: library/doctest.rst:843 msgid "" "All arguments except *filename* are optional, and should be specified in " "keyword form." msgstr "" #: library/doctest.rst:846 msgid "" "Test examples in the file named *filename*. Return ``(failure_count, " "test_count)``." msgstr "" #: library/doctest.rst:849 msgid "" "Optional argument *module_relative* specifies how the filename should be " "interpreted:" msgstr "" #: library/doctest.rst:852 msgid "" "If *module_relative* is ``True`` (the default), then *filename* specifies an " "OS-independent module-relative path. By default, this path is relative to " "the calling module's directory; but if the *package* argument is specified, " "then it is relative to that package. To ensure OS-independence, *filename* " "should use ``/`` characters to separate path segments, and may not be an " "absolute path (i.e., it may not begin with ``/``)." msgstr "" #: library/doctest.rst:859 msgid "" "If *module_relative* is ``False``, then *filename* specifies an OS-specific " "path. The path may be absolute or relative; relative paths are resolved " "with respect to the current working directory." msgstr "" #: library/doctest.rst:863 msgid "" "Optional argument *name* gives the name of the test; by default, or if " "``None``, ``os.path.basename(filename)`` is used." msgstr "" #: library/doctest.rst:866 msgid "" "Optional argument *package* is a Python package or the name of a Python " "package whose directory should be used as the base directory for a module-" "relative filename. If no package is specified, then the calling module's " "directory is used as the base directory for module-relative filenames. It " "is an error to specify *package* if *module_relative* is ``False``." msgstr "" #: library/doctest.rst:872 msgid "" "Optional argument *globs* gives a dict to be used as the globals when " "executing examples. A new shallow copy of this dict is created for the " "doctest, so its examples start with a clean slate. By default, or if " "``None``, a new empty dict is used." msgstr "" #: library/doctest.rst:877 msgid "" "Optional argument *extraglobs* gives a dict merged into the globals used to " "execute examples. This works like :meth:`dict.update`: if *globs* and " "*extraglobs* have a common key, the associated value in *extraglobs* appears " "in the combined dict. By default, or if ``None``, no extra globals are " "used. This is an advanced feature that allows parameterization of " "doctests. For example, a doctest can be written for a base class, using a " "generic name for the class, then reused to test any number of subclasses by " "passing an *extraglobs* dict mapping the generic name to the subclass to be " "tested." msgstr "" #: library/doctest.rst:886 msgid "" "Optional argument *verbose* prints lots of stuff if true, and prints only " "failures if false; by default, or if ``None``, it's true if and only if ``'-" "v'`` is in ``sys.argv``." msgstr "" #: library/doctest.rst:890 msgid "" "Optional argument *report* prints a summary at the end when true, else " "prints nothing at the end. In verbose mode, the summary is detailed, else " "the summary is very brief (in fact, empty if all tests passed)." msgstr "" #: library/doctest.rst:894 msgid "" "Optional argument *optionflags* (default value 0) takes the :ref:`bitwise OR " "` of option flags. See section :ref:`doctest-options`." msgstr "" #: library/doctest.rst:898 msgid "" "Optional argument *raise_on_error* defaults to false. If true, an exception " "is raised upon the first failure or unexpected exception in an example. " "This allows failures to be post-mortem debugged. Default behavior is to " "continue running examples." msgstr "" #: library/doctest.rst:1043 msgid "" "Optional argument *parser* specifies a :class:`DocTestParser` (or subclass) " "that should be used to extract tests from the files. It defaults to a " "normal parser (i.e., ``DocTestParser()``)." msgstr "" #: library/doctest.rst:1047 msgid "" "Optional argument *encoding* specifies an encoding that should be used to " "convert the file to unicode." msgstr "" #: library/doctest.rst:913 msgid "" "All arguments are optional, and all except for *m* should be specified in " "keyword form." msgstr "" #: library/doctest.rst:916 msgid "" "Test examples in docstrings in functions and classes reachable from module " "*m* (or module :mod:`__main__` if *m* is not supplied or is ``None``), " "starting with ``m.__doc__``." msgstr "" #: library/doctest.rst:920 msgid "" "Also test examples reachable from dict ``m.__test__``, if it exists and is " "not ``None``. ``m.__test__`` maps names (strings) to functions, classes and " "strings; function and class docstrings are searched for examples; strings " "are searched directly, as if they were docstrings." msgstr "" #: library/doctest.rst:925 msgid "" "Only docstrings attached to objects belonging to module *m* are searched." msgstr "" #: library/doctest.rst:927 msgid "Return ``(failure_count, test_count)``." msgstr "" #: library/doctest.rst:929 msgid "" "Optional argument *name* gives the name of the module; by default, or if " "``None``, ``m.__name__`` is used." msgstr "" #: library/doctest.rst:932 msgid "" "Optional argument *exclude_empty* defaults to false. If true, objects for " "which no doctests are found are excluded from consideration. The default is " "a backward compatibility hack, so that code still using :meth:`doctest." "master.summarize` in conjunction with :func:`testmod` continues to get " "output for objects with no tests. The *exclude_empty* argument to the newer :" "class:`DocTestFinder` constructor defaults to true." msgstr "" #: library/doctest.rst:939 msgid "" "Optional arguments *extraglobs*, *verbose*, *report*, *optionflags*, " "*raise_on_error*, and *globs* are the same as for function :func:`testfile` " "above, except that *globs* defaults to ``m.__dict__``." msgstr "" #: library/doctest.rst:946 msgid "" "Test examples associated with object *f*; for example, *f* may be a string, " "a module, a function, or a class object." msgstr "" #: library/doctest.rst:949 msgid "" "A shallow copy of dictionary argument *globs* is used for the execution " "context." msgstr "" #: library/doctest.rst:951 msgid "" "Optional argument *name* is used in failure messages, and defaults to ``" "\"NoName\"``." msgstr "" #: library/doctest.rst:954 msgid "" "If optional argument *verbose* is true, output is generated even if there " "are no failures. By default, output is generated only in case of an example " "failure." msgstr "" #: library/doctest.rst:957 msgid "" "Optional argument *compileflags* gives the set of flags that should be used " "by the Python compiler when running the examples. By default, or if " "``None``, flags are deduced corresponding to the set of future features " "found in *globs*." msgstr "" #: library/doctest.rst:961 msgid "" "Optional argument *optionflags* works as for function :func:`testfile` above." msgstr "" #: library/doctest.rst:967 msgid "Unittest API" msgstr "" #: library/doctest.rst:969 msgid "" "As your collection of doctest'ed modules grows, you'll want a way to run all " "their doctests systematically. :mod:`doctest` provides two functions that " "can be used to create :mod:`unittest` test suites from modules and text " "files containing doctests. To integrate with :mod:`unittest` test " "discovery, include a :func:`load_tests` function in your test module::" msgstr "" #: library/doctest.rst:983 msgid "" "There are two main functions for creating :class:`unittest.TestSuite` " "instances from text files and modules with doctests:" msgstr "" #: library/doctest.rst:989 msgid "" "Convert doctest tests from one or more text files to a :class:`unittest." "TestSuite`." msgstr "" #: library/doctest.rst:992 msgid "" "The returned :class:`unittest.TestSuite` is to be run by the unittest " "framework and runs the interactive examples in each file. If an example in " "any file fails, then the synthesized unit test fails, and a :exc:" "`failureException` exception is raised showing the name of the file " "containing the test and a (sometimes approximate) line number." msgstr "" #: library/doctest.rst:998 msgid "Pass one or more paths (as strings) to text files to be examined." msgstr "" #: library/doctest.rst:1000 msgid "Options may be provided as keyword arguments:" msgstr "" #: library/doctest.rst:1002 msgid "" "Optional argument *module_relative* specifies how the filenames in *paths* " "should be interpreted:" msgstr "" #: library/doctest.rst:1005 msgid "" "If *module_relative* is ``True`` (the default), then each filename in " "*paths* specifies an OS-independent module-relative path. By default, this " "path is relative to the calling module's directory; but if the *package* " "argument is specified, then it is relative to that package. To ensure OS-" "independence, each filename should use ``/`` characters to separate path " "segments, and may not be an absolute path (i.e., it may not begin with ``/" "``)." msgstr "" #: library/doctest.rst:1013 msgid "" "If *module_relative* is ``False``, then each filename in *paths* specifies " "an OS-specific path. The path may be absolute or relative; relative paths " "are resolved with respect to the current working directory." msgstr "" #: library/doctest.rst:1017 msgid "" "Optional argument *package* is a Python package or the name of a Python " "package whose directory should be used as the base directory for module-" "relative filenames in *paths*. If no package is specified, then the calling " "module's directory is used as the base directory for module-relative " "filenames. It is an error to specify *package* if *module_relative* is " "``False``." msgstr "" #: library/doctest.rst:1024 msgid "" "Optional argument *setUp* specifies a set-up function for the test suite. " "This is called before running the tests in each file. The *setUp* function " "will be passed a :class:`DocTest` object. The setUp function can access the " "test globals as the *globs* attribute of the test passed." msgstr "" #: library/doctest.rst:1029 msgid "" "Optional argument *tearDown* specifies a tear-down function for the test " "suite. This is called after running the tests in each file. The *tearDown* " "function will be passed a :class:`DocTest` object. The setUp function can " "access the test globals as the *globs* attribute of the test passed." msgstr "" #: library/doctest.rst:1068 msgid "" "Optional argument *globs* is a dictionary containing the initial global " "variables for the tests. A new copy of this dictionary is created for each " "test. By default, *globs* is a new empty dictionary." msgstr "" #: library/doctest.rst:1038 msgid "" "Optional argument *optionflags* specifies the default doctest options for " "the tests, created by or-ing together individual option flags. See section :" "ref:`doctest-options`. See function :func:`set_unittest_reportflags` below " "for a better way to set reporting options." msgstr "" #: library/doctest.rst:1050 msgid "" "The global ``__file__`` is added to the globals provided to doctests loaded " "from a text file using :func:`DocFileSuite`." msgstr "" #: library/doctest.rst:1056 msgid "Convert doctest tests for a module to a :class:`unittest.TestSuite`." msgstr "" #: library/doctest.rst:1058 msgid "" "The returned :class:`unittest.TestSuite` is to be run by the unittest " "framework and runs each doctest in the module. If any of the doctests fail, " "then the synthesized unit test fails, and a :exc:`failureException` " "exception is raised showing the name of the file containing the test and a " "(sometimes approximate) line number." msgstr "" #: library/doctest.rst:1064 msgid "" "Optional argument *module* provides the module to be tested. It can be a " "module object or a (possibly dotted) module name. If not specified, the " "module calling this function is used." msgstr "" #: library/doctest.rst:1072 msgid "" "Optional argument *extraglobs* specifies an extra set of global variables, " "which is merged into *globs*. By default, no extra globals are used." msgstr "" #: library/doctest.rst:1075 msgid "" "Optional argument *test_finder* is the :class:`DocTestFinder` object (or a " "drop-in replacement) that is used to extract doctests from the module." msgstr "" #: library/doctest.rst:1078 msgid "" "Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as " "for function :func:`DocFileSuite` above." msgstr "" #: library/doctest.rst:1081 msgid "This function uses the same search technique as :func:`testmod`." msgstr "" #: library/doctest.rst:1083 msgid "" ":func:`DocTestSuite` returns an empty :class:`unittest.TestSuite` if " "*module* contains no docstrings instead of raising :exc:`ValueError`." msgstr "" #: library/doctest.rst:1088 msgid "" "Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` " "out of :class:`doctest.DocTestCase` instances, and :class:`DocTestCase` is a " "subclass of :class:`unittest.TestCase`. :class:`DocTestCase` isn't " "documented here (it's an internal detail), but studying its code can answer " "questions about the exact details of :mod:`unittest` integration." msgstr "" #: library/doctest.rst:1094 msgid "" "Similarly, :func:`DocFileSuite` creates a :class:`unittest.TestSuite` out " "of :class:`doctest.DocFileCase` instances, and :class:`DocFileCase` is a " "subclass of :class:`DocTestCase`." msgstr "" #: library/doctest.rst:1098 msgid "" "So both ways of creating a :class:`unittest.TestSuite` run instances of :" "class:`DocTestCase`. This is important for a subtle reason: when you run :" "mod:`doctest` functions yourself, you can control the :mod:`doctest` options " "in use directly, by passing option flags to :mod:`doctest` functions. " "However, if you're writing a :mod:`unittest` framework, :mod:`unittest` " "ultimately controls when and how tests get run. The framework author " "typically wants to control :mod:`doctest` reporting options (perhaps, e.g., " "specified by command line options), but there's no way to pass options " "through :mod:`unittest` to :mod:`doctest` test runners." msgstr "" #: library/doctest.rst:1108 msgid "" "For this reason, :mod:`doctest` also supports a notion of :mod:`doctest` " "reporting flags specific to :mod:`unittest` support, via this function:" msgstr "" #: library/doctest.rst:1114 msgid "Set the :mod:`doctest` reporting flags to use." msgstr "" #: library/doctest.rst:1116 msgid "" "Argument *flags* takes the :ref:`bitwise OR ` of option flags. See " "section :ref:`doctest-options`. Only \"reporting flags\" can be used." msgstr "" #: library/doctest.rst:1119 msgid "" "This is a module-global setting, and affects all future doctests run by " "module :mod:`unittest`: the :meth:`runTest` method of :class:`DocTestCase` " "looks at the option flags specified for the test case when the :class:" "`DocTestCase` instance was constructed. If no reporting flags were " "specified (which is the typical and expected case), :mod:`doctest`'s :mod:" "`unittest` reporting flags are :ref:`bitwise ORed ` into the option " "flags, and the option flags so augmented are passed to the :class:" "`DocTestRunner` instance created to run the doctest. If any reporting flags " "were specified when the :class:`DocTestCase` instance was constructed, :mod:" "`doctest`'s :mod:`unittest` reporting flags are ignored." msgstr "" #: library/doctest.rst:1130 msgid "" "The value of the :mod:`unittest` reporting flags in effect before the " "function was called is returned by the function." msgstr "" #: library/doctest.rst:1137 msgid "Advanced API" msgstr "" #: library/doctest.rst:1139 msgid "" "The basic API is a simple wrapper that's intended to make doctest easy to " "use. It is fairly flexible, and should meet most users' needs; however, if " "you require more fine-grained control over testing, or wish to extend " "doctest's capabilities, then you should use the advanced API." msgstr "" #: library/doctest.rst:1144 msgid "" "The advanced API revolves around two container classes, which are used to " "store the interactive examples extracted from doctest cases:" msgstr "" #: library/doctest.rst:1147 msgid "" ":class:`Example`: A single Python :term:`statement`, paired with its " "expected output." msgstr "" #: library/doctest.rst:1150 msgid "" ":class:`DocTest`: A collection of :class:`Example`\\ s, typically extracted " "from a single docstring or text file." msgstr "" #: library/doctest.rst:1153 msgid "" "Additional processing classes are defined to find, parse, and run, and check " "doctest examples:" msgstr "" #: library/doctest.rst:1156 msgid "" ":class:`DocTestFinder`: Finds all docstrings in a given module, and uses a :" "class:`DocTestParser` to create a :class:`DocTest` from every docstring that " "contains interactive examples." msgstr "" #: library/doctest.rst:1160 msgid "" ":class:`DocTestParser`: Creates a :class:`DocTest` object from a string " "(such as an object's docstring)." msgstr "" #: library/doctest.rst:1163 msgid "" ":class:`DocTestRunner`: Executes the examples in a :class:`DocTest`, and " "uses an :class:`OutputChecker` to verify their output." msgstr "" #: library/doctest.rst:1166 msgid "" ":class:`OutputChecker`: Compares the actual output from a doctest example " "with the expected output, and decides whether they match." msgstr "" #: library/doctest.rst:1169 msgid "" "The relationships among these processing classes are summarized in the " "following diagram::" msgstr "" #: library/doctest.rst:1185 msgid "DocTest Objects" msgstr "" #: library/doctest.rst:1190 msgid "" "A collection of doctest examples that should be run in a single namespace. " "The constructor arguments are used to initialize the attributes of the same " "names." msgstr "" #: library/doctest.rst:1194 msgid "" ":class:`DocTest` defines the following attributes. They are initialized by " "the constructor, and should not be modified directly." msgstr "" #: library/doctest.rst:1200 msgid "" "A list of :class:`Example` objects encoding the individual interactive " "Python examples that should be run by this test." msgstr "" #: library/doctest.rst:1206 msgid "" "The namespace (aka globals) that the examples should be run in. This is a " "dictionary mapping names to values. Any changes to the namespace made by " "the examples (such as binding new variables) will be reflected in :attr:" "`globs` after the test is run." msgstr "" #: library/doctest.rst:1214 msgid "" "A string name identifying the :class:`DocTest`. Typically, this is the name " "of the object or file that the test was extracted from." msgstr "" #: library/doctest.rst:1220 msgid "" "The name of the file that this :class:`DocTest` was extracted from; or " "``None`` if the filename is unknown, or if the :class:`DocTest` was not " "extracted from a file." msgstr "" #: library/doctest.rst:1227 msgid "" "The line number within :attr:`filename` where this :class:`DocTest` begins, " "or ``None`` if the line number is unavailable. This line number is zero-" "based with respect to the beginning of the file." msgstr "" #: library/doctest.rst:1234 msgid "" "The string that the test was extracted from, or ``None`` if the string is " "unavailable, or if the test was not extracted from a string." msgstr "" #: library/doctest.rst:1241 msgid "Example Objects" msgstr "" #: library/doctest.rst:1246 msgid "" "A single interactive example, consisting of a Python statement and its " "expected output. The constructor arguments are used to initialize the " "attributes of the same names." msgstr "" #: library/doctest.rst:1251 msgid "" ":class:`Example` defines the following attributes. They are initialized by " "the constructor, and should not be modified directly." msgstr "" #: library/doctest.rst:1257 msgid "" "A string containing the example's source code. This source code consists of " "a single Python statement, and always ends with a newline; the constructor " "adds a newline when necessary." msgstr "" #: library/doctest.rst:1264 msgid "" "The expected output from running the example's source code (either from " "stdout, or a traceback in case of exception). :attr:`want` ends with a " "newline unless no output is expected, in which case it's an empty string. " "The constructor adds a newline when necessary." msgstr "" #: library/doctest.rst:1272 msgid "" "The exception message generated by the example, if the example is expected " "to generate an exception; or ``None`` if it is not expected to generate an " "exception. This exception message is compared against the return value of :" "func:`traceback.format_exception_only`. :attr:`exc_msg` ends with a newline " "unless it's ``None``. The constructor adds a newline if needed." msgstr "" #: library/doctest.rst:1281 msgid "" "The line number within the string containing this example where the example " "begins. This line number is zero-based with respect to the beginning of the " "containing string." msgstr "" #: library/doctest.rst:1288 msgid "" "The example's indentation in the containing string, i.e., the number of " "space characters that precede the example's first prompt." msgstr "" #: library/doctest.rst:1294 msgid "" "A dictionary mapping from option flags to ``True`` or ``False``, which is " "used to override default options for this example. Any option flags not " "contained in this dictionary are left at their default value (as specified " "by the :class:`DocTestRunner`'s :attr:`optionflags`). By default, no options " "are set." msgstr "" #: library/doctest.rst:1303 msgid "DocTestFinder objects" msgstr "" #: library/doctest.rst:1308 msgid "" "A processing class used to extract the :class:`DocTest`\\ s that are " "relevant to a given object, from its docstring and the docstrings of its " "contained objects. :class:`DocTest`\\ s can be extracted from modules, " "classes, functions, methods, staticmethods, classmethods, and properties." msgstr "" #: library/doctest.rst:1313 msgid "" "The optional argument *verbose* can be used to display the objects searched " "by the finder. It defaults to ``False`` (no output)." msgstr "" #: library/doctest.rst:1316 msgid "" "The optional argument *parser* specifies the :class:`DocTestParser` object " "(or a drop-in replacement) that is used to extract doctests from docstrings." msgstr "" #: library/doctest.rst:1319 msgid "" "If the optional argument *recurse* is false, then :meth:`DocTestFinder.find` " "will only examine the given object, and not any contained objects." msgstr "" #: library/doctest.rst:1322 msgid "" "If the optional argument *exclude_empty* is false, then :meth:`DocTestFinder." "find` will include tests for objects with empty docstrings." msgstr "" #: library/doctest.rst:1326 msgid ":class:`DocTestFinder` defines the following method:" msgstr "" #: library/doctest.rst:1331 msgid "" "Return a list of the :class:`DocTest`\\ s that are defined by *obj*'s " "docstring, or by any of its contained objects' docstrings." msgstr "" #: library/doctest.rst:1334 msgid "" "The optional argument *name* specifies the object's name; this name will be " "used to construct names for the returned :class:`DocTest`\\ s. If *name* is " "not specified, then ``obj.__name__`` is used." msgstr "" #: library/doctest.rst:1338 msgid "" "The optional parameter *module* is the module that contains the given " "object. If the module is not specified or is ``None``, then the test finder " "will attempt to automatically determine the correct module. The object's " "module is used:" msgstr "" #: library/doctest.rst:1342 msgid "As a default namespace, if *globs* is not specified." msgstr "" #: library/doctest.rst:1344 msgid "" "To prevent the DocTestFinder from extracting DocTests from objects that are " "imported from other modules. (Contained objects with modules other than " "*module* are ignored.)" msgstr "" #: library/doctest.rst:1348 msgid "To find the name of the file containing the object." msgstr "" #: library/doctest.rst:1350 msgid "To help find the line number of the object within its file." msgstr "" #: library/doctest.rst:1352 msgid "" "If *module* is ``False``, no attempt to find the module will be made. This " "is obscure, of use mostly in testing doctest itself: if *module* is " "``False``, or is ``None`` but cannot be found automatically, then all " "objects are considered to belong to the (non-existent) module, so all " "contained objects will (recursively) be searched for doctests." msgstr "" #: library/doctest.rst:1358 msgid "" "The globals for each :class:`DocTest` is formed by combining *globs* and " "*extraglobs* (bindings in *extraglobs* override bindings in *globs*). A new " "shallow copy of the globals dictionary is created for each :class:`DocTest`. " "If *globs* is not specified, then it defaults to the module's *__dict__*, if " "specified, or ``{}`` otherwise. If *extraglobs* is not specified, then it " "defaults to ``{}``." msgstr "" #: library/doctest.rst:1369 msgid "DocTestParser objects" msgstr "" #: library/doctest.rst:1374 msgid "" "A processing class used to extract interactive examples from a string, and " "use them to create a :class:`DocTest` object." msgstr "" #: library/doctest.rst:1446 msgid ":class:`DocTestParser` defines the following methods:" msgstr "" #: library/doctest.rst:1383 msgid "" "Extract all doctest examples from the given string, and collect them into a :" "class:`DocTest` object." msgstr "" #: library/doctest.rst:1386 msgid "" "*globs*, *name*, *filename*, and *lineno* are attributes for the new :class:" "`DocTest` object. See the documentation for :class:`DocTest` for more " "information." msgstr "" #: library/doctest.rst:1393 msgid "" "Extract all doctest examples from the given string, and return them as a " "list of :class:`Example` objects. Line numbers are 0-based. The optional " "argument *name* is a name identifying this string, and is only used for " "error messages." msgstr "" #: library/doctest.rst:1400 msgid "" "Divide the given string into examples and intervening text, and return them " "as a list of alternating :class:`Example`\\ s and strings. Line numbers for " "the :class:`Example`\\ s are 0-based. The optional argument *name* is a " "name identifying this string, and is only used for error messages." msgstr "" #: library/doctest.rst:1409 msgid "DocTestRunner objects" msgstr "" #: library/doctest.rst:1414 msgid "" "A processing class used to execute and verify the interactive examples in a :" "class:`DocTest`." msgstr "" #: library/doctest.rst:1417 msgid "" "The comparison between expected outputs and actual outputs is done by an :" "class:`OutputChecker`. This comparison may be customized with a number of " "option flags; see section :ref:`doctest-options` for more information. If " "the option flags are insufficient, then the comparison may also be " "customized by passing a subclass of :class:`OutputChecker` to the " "constructor." msgstr "" #: library/doctest.rst:1423 msgid "" "The test runner's display output can be controlled in two ways. First, an " "output function can be passed to :meth:`TestRunner.run`; this function will " "be called with strings that should be displayed. It defaults to ``sys." "stdout.write``. If capturing the output is not sufficient, then the display " "output can be also customized by subclassing DocTestRunner, and overriding " "the methods :meth:`report_start`, :meth:`report_success`, :meth:" "`report_unexpected_exception`, and :meth:`report_failure`." msgstr "" #: library/doctest.rst:1431 msgid "" "The optional keyword argument *checker* specifies the :class:`OutputChecker` " "object (or drop-in replacement) that should be used to compare the expected " "outputs to the actual outputs of doctest examples." msgstr "" #: library/doctest.rst:1435 msgid "" "The optional keyword argument *verbose* controls the :class:" "`DocTestRunner`'s verbosity. If *verbose* is ``True``, then information is " "printed about each example, as it is run. If *verbose* is ``False``, then " "only failures are printed. If *verbose* is unspecified, or ``None``, then " "verbose output is used iff the command-line switch ``-v`` is used." msgstr "" #: library/doctest.rst:1441 msgid "" "The optional keyword argument *optionflags* can be used to control how the " "test runner compares expected output to actual output, and how it displays " "failures. For more information, see section :ref:`doctest-options`." msgstr "" #: library/doctest.rst:1451 msgid "" "Report that the test runner is about to process the given example. This " "method is provided to allow subclasses of :class:`DocTestRunner` to " "customize their output; it should not be called directly." msgstr "" #: library/doctest.rst:1455 msgid "" "*example* is the example about to be processed. *test* is the test " "*containing example*. *out* is the output function that was passed to :meth:" "`DocTestRunner.run`." msgstr "" #: library/doctest.rst:1462 msgid "" "Report that the given example ran successfully. This method is provided to " "allow subclasses of :class:`DocTestRunner` to customize their output; it " "should not be called directly." msgstr "" #: library/doctest.rst:1477 msgid "" "*example* is the example about to be processed. *got* is the actual output " "from the example. *test* is the test containing *example*. *out* is the " "output function that was passed to :meth:`DocTestRunner.run`." msgstr "" #: library/doctest.rst:1473 msgid "" "Report that the given example failed. This method is provided to allow " "subclasses of :class:`DocTestRunner` to customize their output; it should " "not be called directly." msgstr "" #: library/doctest.rst:1484 msgid "" "Report that the given example raised an unexpected exception. This method is " "provided to allow subclasses of :class:`DocTestRunner` to customize their " "output; it should not be called directly." msgstr "" #: library/doctest.rst:1488 msgid "" "*example* is the example about to be processed. *exc_info* is a tuple " "containing information about the unexpected exception (as returned by :func:" "`sys.exc_info`). *test* is the test containing *example*. *out* is the " "output function that was passed to :meth:`DocTestRunner.run`." msgstr "" #: library/doctest.rst:1496 msgid "" "Run the examples in *test* (a :class:`DocTest` object), and display the " "results using the writer function *out*." msgstr "" #: library/doctest.rst:1499 msgid "" "The examples are run in the namespace ``test.globs``. If *clear_globs* is " "true (the default), then this namespace will be cleared after the test runs, " "to help with garbage collection. If you would like to examine the namespace " "after the test completes, then use *clear_globs=False*." msgstr "" #: library/doctest.rst:1504 msgid "" "*compileflags* gives the set of flags that should be used by the Python " "compiler when running the examples. If not specified, then it will default " "to the set of future-import flags that apply to *globs*." msgstr "" #: library/doctest.rst:1508 msgid "" "The output of each example is checked using the :class:`DocTestRunner`'s " "output checker, and the results are formatted by the :meth:`DocTestRunner." "report_\\*` methods." msgstr "" #: library/doctest.rst:1515 msgid "" "Print a summary of all the test cases that have been run by this " "DocTestRunner, and return a :term:`named tuple` ``TestResults(failed, " "attempted)``." msgstr "" #: library/doctest.rst:1518 msgid "" "The optional *verbose* argument controls how detailed the summary is. If " "the verbosity is not specified, then the :class:`DocTestRunner`'s verbosity " "is used." msgstr "" #: library/doctest.rst:1525 msgid "OutputChecker objects" msgstr "" #: library/doctest.rst:1530 msgid "" "A class used to check the whether the actual output from a doctest example " "matches the expected output. :class:`OutputChecker` defines two methods: :" "meth:`check_output`, which compares a given pair of outputs, and returns " "``True`` if they match; and :meth:`output_difference`, which returns a " "string describing the differences between two outputs." msgstr "" #: library/doctest.rst:1537 msgid ":class:`OutputChecker` defines the following methods:" msgstr "" #: library/doctest.rst:1541 msgid "" "Return ``True`` iff the actual output from an example (*got*) matches the " "expected output (*want*). These strings are always considered to match if " "they are identical; but depending on what option flags the test runner is " "using, several non-exact match types are also possible. See section :ref:" "`doctest-options` for more information about option flags." msgstr "" #: library/doctest.rst:1550 msgid "" "Return a string describing the differences between the expected output for a " "given example (*example*) and the actual output (*got*). *optionflags* is " "the set of option flags used to compare *want* and *got*." msgstr "" #: library/doctest.rst:1558 msgid "Debugging" msgstr "" #: library/doctest.rst:1560 msgid "Doctest provides several mechanisms for debugging doctest examples:" msgstr "" #: library/doctest.rst:1562 msgid "" "Several functions convert doctests to executable Python programs, which can " "be run under the Python debugger, :mod:`pdb`." msgstr "" #: library/doctest.rst:1565 msgid "" "The :class:`DebugRunner` class is a subclass of :class:`DocTestRunner` that " "raises an exception for the first failing example, containing information " "about that example. This information can be used to perform post-mortem " "debugging on the example." msgstr "" #: library/doctest.rst:1570 msgid "" "The :mod:`unittest` cases generated by :func:`DocTestSuite` support the :" "meth:`debug` method defined by :class:`unittest.TestCase`." msgstr "" #: library/doctest.rst:1573 msgid "" "You can add a call to :func:`pdb.set_trace` in a doctest example, and you'll " "drop into the Python debugger when that line is executed. Then you can " "inspect current values of variables, and so on. For example, suppose :file:" "`a.py` contains just this module docstring::" msgstr "" #: library/doctest.rst:1588 msgid "Then an interactive Python session may look like this::" msgstr "" #: library/doctest.rst:1621 msgid "" "Functions that convert doctests to Python code, and possibly run the " "synthesized code under the debugger:" msgstr "" #: library/doctest.rst:1627 msgid "Convert text with examples to a script." msgstr "" #: library/doctest.rst:1629 msgid "" "Argument *s* is a string containing doctest examples. The string is " "converted to a Python script, where doctest examples in *s* are converted to " "regular code, and everything else is converted to Python comments. The " "generated script is returned as a string. For example, ::" msgstr "" #: library/doctest.rst:1644 msgid "displays::" msgstr "" #: library/doctest.rst:1654 msgid "" "This function is used internally by other functions (see below), but can " "also be useful when you want to transform an interactive Python session into " "a Python script." msgstr "" #: library/doctest.rst:1661 msgid "Convert the doctest for an object to a script." msgstr "" #: library/doctest.rst:1663 msgid "" "Argument *module* is a module object, or dotted name of a module, containing " "the object whose doctests are of interest. Argument *name* is the name " "(within the module) of the object with the doctests of interest. The result " "is a string, containing the object's docstring converted to a Python script, " "as described for :func:`script_from_examples` above. For example, if " "module :file:`a.py` contains a top-level function :func:`f`, then ::" msgstr "" #: library/doctest.rst:1673 msgid "" "prints a script version of function :func:`f`'s docstring, with doctests " "converted to code, and the rest placed in comments." msgstr "" #: library/doctest.rst:1679 msgid "Debug the doctests for an object." msgstr "" #: library/doctest.rst:1681 msgid "" "The *module* and *name* arguments are the same as for function :func:" "`testsource` above. The synthesized Python script for the named object's " "docstring is written to a temporary file, and then that file is run under " "the control of the Python debugger, :mod:`pdb`." msgstr "" #: library/doctest.rst:1686 msgid "" "A shallow copy of ``module.__dict__`` is used for both local and global " "execution context." msgstr "" #: library/doctest.rst:1689 msgid "" "Optional argument *pm* controls whether post-mortem debugging is used. If " "*pm* has a true value, the script file is run directly, and the debugger " "gets involved only if the script terminates via raising an unhandled " "exception. If it does, then post-mortem debugging is invoked, via :func:" "`pdb.post_mortem`, passing the traceback object from the unhandled " "exception. If *pm* is not specified, or is false, the script is run under " "the debugger from the start, via passing an appropriate :func:`exec` call " "to :func:`pdb.run`." msgstr "" #: library/doctest.rst:1700 msgid "Debug the doctests in a string." msgstr "" #: library/doctest.rst:1702 msgid "" "This is like function :func:`debug` above, except that a string containing " "doctest examples is specified directly, via the *src* argument." msgstr "" #: library/doctest.rst:1705 msgid "" "Optional argument *pm* has the same meaning as in function :func:`debug` " "above." msgstr "" #: library/doctest.rst:1707 msgid "" "Optional argument *globs* gives a dictionary to use as both local and global " "execution context. If not specified, or ``None``, an empty dictionary is " "used. If specified, a shallow copy of the dictionary is used." msgstr "" #: library/doctest.rst:1712 msgid "" "The :class:`DebugRunner` class, and the special exceptions it may raise, are " "of most interest to testing framework authors, and will only be sketched " "here. See the source code, and especially :class:`DebugRunner`'s docstring " "(which is a doctest!) for more details:" msgstr "" #: library/doctest.rst:1720 msgid "" "A subclass of :class:`DocTestRunner` that raises an exception as soon as a " "failure is encountered. If an unexpected exception occurs, an :exc:" "`UnexpectedException` exception is raised, containing the test, the example, " "and the original exception. If the output doesn't match, then a :exc:" "`DocTestFailure` exception is raised, containing the test, the example, and " "the actual output." msgstr "" #: library/doctest.rst:1727 msgid "" "For information about the constructor parameters and methods, see the " "documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-" "api`." msgstr "" #: library/doctest.rst:1730 msgid "" "There are two exceptions that may be raised by :class:`DebugRunner` " "instances:" msgstr "" #: library/doctest.rst:1735 msgid "" "An exception raised by :class:`DocTestRunner` to signal that a doctest " "example's actual output did not match its expected output. The constructor " "arguments are used to initialize the attributes of the same names." msgstr "" #: library/doctest.rst:1739 msgid ":exc:`DocTestFailure` defines the following attributes:" msgstr "" #: library/doctest.rst:1768 msgid "The :class:`DocTest` object that was being run when the example failed." msgstr "" #: library/doctest.rst:1773 msgid "The :class:`Example` that failed." msgstr "" #: library/doctest.rst:1754 msgid "The example's actual output." msgstr "" #: library/doctest.rst:1759 msgid "" "An exception raised by :class:`DocTestRunner` to signal that a doctest " "example raised an unexpected exception. The constructor arguments are used " "to initialize the attributes of the same names." msgstr "" #: library/doctest.rst:1763 msgid ":exc:`UnexpectedException` defines the following attributes:" msgstr "" #: library/doctest.rst:1778 msgid "" "A tuple containing information about the unexpected exception, as returned " "by :func:`sys.exc_info`." msgstr "" #: library/doctest.rst:1785 msgid "Soapbox" msgstr "" #: library/doctest.rst:1787 msgid "" "As mentioned in the introduction, :mod:`doctest` has grown to have three " "primary uses:" msgstr "" #: library/doctest.rst:1790 msgid "Checking examples in docstrings." msgstr "" #: library/doctest.rst:1792 msgid "Regression testing." msgstr "" #: library/doctest.rst:1794 msgid "Executable documentation / literate testing." msgstr "" #: library/doctest.rst:1796 msgid "" "These uses have different requirements, and it is important to distinguish " "them. In particular, filling your docstrings with obscure test cases makes " "for bad documentation." msgstr "" #: library/doctest.rst:1800 msgid "" "When writing a docstring, choose docstring examples with care. There's an " "art to this that needs to be learned---it may not be natural at first. " "Examples should add genuine value to the documentation. A good example can " "often be worth many words. If done with care, the examples will be " "invaluable for your users, and will pay back the time it takes to collect " "them many times over as the years go by and things change. I'm still amazed " "at how often one of my :mod:`doctest` examples stops working after a " "\"harmless\" change." msgstr "" #: library/doctest.rst:1808 msgid "" "Doctest also makes an excellent tool for regression testing, especially if " "you don't skimp on explanatory text. By interleaving prose and examples, it " "becomes much easier to keep track of what's actually being tested, and why. " "When a test fails, good prose can make it much easier to figure out what the " "problem is, and how it should be fixed. It's true that you could write " "extensive comments in code-based testing, but few programmers do. Many have " "found that using doctest approaches instead leads to much clearer tests. " "Perhaps this is simply because doctest makes writing prose a little easier " "than writing code, while writing comments in code is a little harder. I " "think it goes deeper than just that: the natural attitude when writing a " "doctest-based test is that you want to explain the fine points of your " "software, and illustrate them with examples. This in turn naturally leads to " "test files that start with the simplest features, and logically progress to " "complications and edge cases. A coherent narrative is the result, instead " "of a collection of isolated functions that test isolated bits of " "functionality seemingly at random. It's a different attitude, and produces " "different results, blurring the distinction between testing and explaining." msgstr "" #: library/doctest.rst:1826 msgid "" "Regression testing is best confined to dedicated objects or files. There " "are several options for organizing tests:" msgstr "" #: library/doctest.rst:1829 msgid "" "Write text files containing test cases as interactive examples, and test the " "files using :func:`testfile` or :func:`DocFileSuite`. This is recommended, " "although is easiest to do for new projects, designed from the start to use " "doctest." msgstr "" #: library/doctest.rst:1834 msgid "" "Define functions named ``_regrtest_topic`` that consist of single " "docstrings, containing test cases for the named topics. These functions can " "be included in the same file as the module, or separated out into a separate " "test file." msgstr "" #: library/doctest.rst:1838 msgid "" "Define a ``__test__`` dictionary mapping from regression test topics to " "docstrings containing test cases." msgstr "" #: library/doctest.rst:1841 msgid "" "When you have placed your tests in a module, the module can itself be the " "test runner. When a test fails, you can arrange for your test runner to re-" "run only the failing doctest while you debug the problem. Here is a minimal " "example of such a test runner::" msgstr "" #: library/doctest.rst:1863 msgid "Footnotes" msgstr "Notes" #: library/doctest.rst:1864 msgid "" "Examples containing both expected output and an exception are not supported. " "Trying to guess where one ends and the other begins is too error-prone, and " "that also makes for a confusing test." msgstr ""