python-docs-fr/library/doctest.po

# 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 <EMAIL@ADDRESS>\n"
"Language-Team: FRENCH <traductions@lists.afpy.org>\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 ``<BLANKLINE>`` 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 <doctest-directives>` "
"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 <bitwise>` together and passed to various functions. The "
"names can also be used in :ref:`doctest directives <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 ``<BLANKLINE>``, 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 <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 <doctest-"
"options>` 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 "
"<bitwise>` 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 <bitwise>` 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 <bitwise>` 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 ""