doctest.po

# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001-2024, Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Python 3.12\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2025-02-17 21:03+0100\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \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
msgid "**Source code:** :source:`Lib/doctest.py`"
msgstr ""

#: 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:33
msgid ""
"\"\"\"\n"
"This is the \"example\" module.\n"
"\n"
"The example module supplies one function, factorial().  For example,\n"
"\n"
">>> factorial(5)\n"
"120\n"
"\"\"\"\n"
"\n"
"def factorial(n):\n"
"    \"\"\"Return the factorial of n, an exact integer >= 0.\n"
"\n"
"    >>> [factorial(n) for n in range(6)]\n"
"    [1, 1, 2, 6, 24, 120]\n"
"    >>> factorial(30)\n"
"    265252859812191058636308480000000\n"
"    >>> factorial(-1)\n"
"    Traceback (most recent call last):\n"
"        ...\n"
"    ValueError: n must be >= 0\n"
"\n"
"    Factorials of floats are OK, but the float must be an exact integer:\n"
"    >>> factorial(30.1)\n"
"    Traceback (most recent call last):\n"
"        ...\n"
"    ValueError: n must be exact integer\n"
"    >>> factorial(30.0)\n"
"    265252859812191058636308480000000\n"
"\n"
"    It must also not be ridiculously large:\n"
"    >>> factorial(1e100)\n"
"    Traceback (most recent call last):\n"
"        ...\n"
"    OverflowError: n too large\n"
"    \"\"\"\n"
"\n"
"    import math\n"
"    if not n >= 0:\n"
"        raise ValueError(\"n must be >= 0\")\n"
"    if math.floor(n) != n:\n"
"        raise ValueError(\"n must be exact integer\")\n"
"    if n+1 == n:  # catch a value like 1e300\n"
"        raise OverflowError(\"n too large\")\n"
"    result = 1\n"
"    factor = 2\n"
"    while factor <= n:\n"
"        result *= factor\n"
"        factor += 1\n"
"    return result\n"
"\n"
"\n"
"if __name__ == \"__main__\":\n"
"    import doctest\n"
"    doctest.testmod()"
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:91
msgid ""
"$ python example.py\n"
"$"
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:100
msgid ""
"$ python example.py -v\n"
"Trying:\n"
"    factorial(5)\n"
"Expecting:\n"
"    120\n"
"ok\n"
"Trying:\n"
"    [factorial(n) for n in range(6)]\n"
"Expecting:\n"
"    [1, 1, 2, 6, 24, 120]\n"
"ok"
msgstr ""

#: library/doctest.rst:114
msgid "And so on, eventually ending with:"
msgstr ""

#: library/doctest.rst:116
msgid ""
"Trying:\n"
"    factorial(1e100)\n"
"Expecting:\n"
"    Traceback (most recent call last):\n"
"        ...\n"
"    OverflowError: n too large\n"
"ok\n"
"2 items passed all tests:\n"
"   1 tests in __main__\n"
"   8 tests in __main__.factorial\n"
"9 tests in 2 items.\n"
"9 passed and 0 failed.\n"
"Test passed.\n"
"$"
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/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:148
msgid ""
"if __name__ == \"__main__\":\n"
"    import doctest\n"
"    doctest.testmod()"
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:157
msgid "python M.py"
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:166
msgid "python M.py -v"
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:180
msgid "python -m doctest -v example.py"
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:197
msgid ""
"import doctest\n"
"doctest.testfile(\"example.txt\")"
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:205
msgid ""
"The ``example`` module\n"
"======================\n"
"\n"
"Using ``factorial``\n"
"-------------------\n"
"\n"
"This is an example text file in reStructuredText format.  First import\n"
"``factorial`` from the ``example`` module:\n"
"\n"
"    >>> from example import factorial\n"
"\n"
"Now use it:\n"
"\n"
"    >>> factorial(6)\n"
"    120"
msgstr ""

#: library/doctest.rst:223
msgid ""
"Running ``doctest.testfile(\"example.txt\")`` then finds the error in this "
"documentation::"
msgstr ""

#: library/doctest.rst:226
msgid ""
"File \"./example.txt\", line 14, in example.txt\n"
"Failed example:\n"
"    factorial(6)\n"
"Expected:\n"
"    120\n"
"Got:\n"
"    720"
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:251
msgid "python -m doctest -v example.txt"
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, there are cases when you want tests to be part of a module but "
"not part of the help text, which requires that the tests not be included in "
"the docstring. Doctest looks for a module-level variable called ``__test__`` "
"and uses it to locate other tests. If ``M.__test__`` exists, 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 ``M."
"__test__.K``."
msgstr ""

#: library/doctest.rst:289
msgid "For example, place this block of code at the top of :file:`example.py`:"
msgstr ""

#: library/doctest.rst:291
msgid ""
"__test__ = {\n"
"    'numbers': \"\"\"\n"
">>> factorial(6)\n"
"720\n"
"\n"
">>> [factorial(n) for n in range(6)]\n"
"[1, 1, 2, 6, 24, 120]\n"
"\"\"\"\n"
"}"
msgstr ""

#: library/doctest.rst:303
msgid ""
"The value of ``example.__test__[\"numbers\"]`` will be treated as a "
"docstring and all the tests inside it will be run. It is important to note "
"that the value can be mapped to a function, class object, or module; if so, :"
"mod:`!doctest` searches them recursively for docstrings, which are then "
"scanned for tests."
msgstr ""

#: library/doctest.rst:309
msgid ""
"Any classes found are recursively searched similarly, to test docstrings in "
"their contained methods and nested classes."
msgstr ""

#: library/doctest.rst:316
msgid "How are Docstring Examples Recognized?"
msgstr ""

#: library/doctest.rst:318
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:323
msgid ""
">>> # comments are ignored\n"
">>> x = 12\n"
">>> x\n"
"12\n"
">>> if x == 13:\n"
"...     print(\"yes\")\n"
"... else:\n"
"...     print(\"no\")\n"
"...     print(\"NO\")\n"
"...     print(\"NO!!!\")\n"
"...\n"
"no\n"
"NO\n"
"NO!!!\n"
">>>"
msgstr ""

#: library/doctest.rst:343
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:347
msgid "The fine print:"
msgstr ""

#: library/doctest.rst:349
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:354
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:366
msgid ""
"Output to stdout is captured, but not output to stderr (exception tracebacks "
"are captured via a different means)."
msgstr ""

#: library/doctest.rst:369
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:373
msgid ""
">>> def f(x):\n"
"...     r'''Backslashes in a raw docstring: m\\n'''\n"
"...\n"
">>> print(f.__doc__)\n"
"Backslashes in a raw docstring: m\\n"
msgstr ""

#: library/doctest.rst:379
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:383
msgid ""
">>> def f(x):\n"
"...     '''Backslashes in a raw docstring: m\\\\n'''\n"
"...\n"
">>> print(f.__doc__)\n"
"Backslashes in a raw docstring: m\\n"
msgstr ""

#: library/doctest.rst:389
msgid "The starting column doesn't matter::"
msgstr ""

#: library/doctest.rst:391
msgid ""
">>> assert \"Easy!\"\n"
"      >>> import math\n"
"          >>> math.floor(1.9)\n"
"          1"
msgstr ""

#: library/doctest.rst:396
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:403
msgid "What's the Execution Context?"
msgstr ""

#: library/doctest.rst:405
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:413
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:420
msgid "What About Exceptions?"
msgstr ""

#: library/doctest.rst:422
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:428
msgid "Simple example::"
msgstr ""

#: library/doctest.rst:430
msgid ""
">>> [1, 2, 3].remove(42)\n"
"Traceback (most recent call last):\n"
"  File \"<stdin>\", line 1, in <module>\n"
"ValueError: list.remove(x): x not in list"
msgstr ""

#: library/doctest.rst:435
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:438
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:442
msgid ""
"Traceback (most recent call last):\n"
"Traceback (innermost last):"
msgstr ""

#: library/doctest.rst:445
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:449
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:454
msgid ""
">>> raise ValueError('multi\\n    line\\ndetail')\n"
"Traceback (most recent call last):\n"
"  File \"<stdin>\", line 1, in <module>\n"
"ValueError: multi\n"
"    line\n"
"detail"
msgstr ""

#: library/doctest.rst:461
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:464
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:467
msgid ""
">>> raise ValueError('multi\\n    line\\ndetail')\n"
"Traceback (most recent call last):\n"
"    ...\n"
"ValueError: multi\n"
"    line\n"
"detail"
msgstr ""

#: library/doctest.rst:474
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:480
msgid "Some details you should read once, but won't need to remember:"
msgstr ""

#: library/doctest.rst:482
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:489
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:495
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:499
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:507
msgid ""
"For some exceptions, Python displays the position of the error using ``^`` "
"markers and tildes::"
msgstr ""

#: library/doctest.rst:510
msgid ""
">>> 1 + None\n"
"  File \"<stdin>\", line 1\n"
"    1 + None\n"
"    ~~^~~~~~\n"
"TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'"
msgstr ""

#: library/doctest.rst:516
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:520
msgid ""
">>> 1 + None\n"
"  File \"<stdin>\", line 1\n"
"    1 + None\n"
"    ^~~~~~~~\n"
"TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'"
msgstr ""

#: library/doctest.rst:531
msgid "Option Flags"
msgstr ""

#: library/doctest.rst:533
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:539
msgid "The ``-o`` command line option."
msgstr ""

#: library/doctest.rst:542
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:548
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:560
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:569
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:580
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:589
msgid ""
"When specified, doctests expecting exceptions pass so long as an exception "
"of the expected type is raised, even if the details (message and fully "
"qualified exception name) don't match."
msgstr ""

#: library/doctest.rst:593
msgid ""
"For example, an example expecting ``ValueError: 42`` will pass if the actual "
"exception raised is ``ValueError: 3*14``, but will fail if, say, a :exc:"
"`TypeError` is raised instead. It will also ignore any fully qualified name "
"included before the exception class, which can vary between implementations "
"and versions of Python and the code/libraries in use. Hence, all three of "
"these variations will work with the flag specified:"
msgstr ""

#: library/doctest.rst:601
msgid ""
">>> raise Exception('message')\n"
"Traceback (most recent call last):\n"
"Exception: message\n"
"\n"
">>> raise Exception('message')\n"
"Traceback (most recent call last):\n"
"builtins.Exception: message\n"
"\n"
">>> raise Exception('message')\n"
"Traceback (most recent call last):\n"
"__main__.Exception: message"
msgstr ""

#: library/doctest.rst:615
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 the "
"module name is present or matches exactly."
msgstr ""

#: library/doctest.rst:619
msgid ""
":const:`IGNORE_EXCEPTION_DETAIL` now also ignores any information relating "
"to the module containing the exception under test."
msgstr ""

#: library/doctest.rst:626
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:632
msgid ""
"The SKIP flag can also be used for temporarily \"commenting out\" examples."
msgstr ""

#: library/doctest.rst:637
msgid "A bitmask or'ing together all the comparison flags above."
msgstr ""

#: library/doctest.rst:639
msgid "The second group of options controls how test failures are reported:"
msgstr ""

#: library/doctest.rst:644
msgid ""
"When specified, failures that involve multi-line expected and actual outputs "
"are displayed using a unified diff."
msgstr ""

#: library/doctest.rst:650
msgid ""
"When specified, failures that involve multi-line expected and actual outputs "
"will be displayed using a context diff."
msgstr ""

#: library/doctest.rst:656
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:665
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:676
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:681
msgid ""
"The doctest command line accepts the option ``-f`` as a shorthand for ``-o "
"FAIL_FAST``."
msgstr ""

#: library/doctest.rst:689
msgid "A bitmask or'ing together all the reporting flags above."
msgstr ""

#: library/doctest.rst:692
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:698
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:704
msgid "MY_FLAG = register_optionflag('MY_FLAG')"
msgstr ""

#: library/doctest.rst:714
msgid "Directives"
msgstr ""

#: library/doctest.rst:716
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:727
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:731
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:734
msgid "For example, this test passes:"
msgstr ""

#: library/doctest.rst:736
msgid ""
">>> print(list(range(20)))  # doctest: +NORMALIZE_WHITESPACE\n"
"[0,   1,  2,  3,  4,  5,  6,  7,  8,  9,\n"
"10,  11, 12, 13, 14, 15, 16, 17, 18, 19]"
msgstr ""

#: library/doctest.rst:743
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:748
msgid ""
">>> print(list(range(20)))  # doctest: +ELLIPSIS\n"
"[0, 1, ..., 18, 19]"
msgstr ""

#: library/doctest.rst:754
msgid ""
"Multiple directives can be used on a single physical line, separated by "
"commas:"
msgstr ""

#: library/doctest.rst:757
msgid ""
">>> print(list(range(20)))  # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE\n"
"[0,    1, ...,   18,    19]"
msgstr ""

#: library/doctest.rst:763
msgid ""
"If multiple directive comments are used for a single example, then they are "
"combined:"
msgstr ""

#: library/doctest.rst:766
msgid ""
">>> print(list(range(20)))  # doctest: +ELLIPSIS\n"
"...                         # doctest: +NORMALIZE_WHITESPACE\n"
"[0,    1, ...,   18,    19]"
msgstr ""

#: library/doctest.rst:773
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:777
msgid ""
">>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))\n"
"... # doctest: +ELLIPSIS\n"
"[0, ..., 4, 10, ..., 19, 30, ..., 39]"
msgstr ""

#: library/doctest.rst:784
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:794
msgid "Warnings"
msgstr ""

#: library/doctest.rst:796
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:802
msgid ""
">>> foo()\n"
"{\"spam\", \"eggs\"}"
msgstr ""

#: library/doctest.rst:805
msgid "is vulnerable!  One workaround is to do ::"
msgstr ""

#: library/doctest.rst:807
msgid ""
">>> foo() == {\"spam\", \"eggs\"}\n"
"True"
msgstr ""

#: library/doctest.rst:810
msgid "instead.  Another is to do ::"
msgstr ""

#: library/doctest.rst:812
msgid ""
">>> d = sorted(foo())\n"
">>> d\n"
"['eggs', 'spam']"
msgstr ""

#: library/doctest.rst:816
msgid "There are others, but you get the idea."
msgstr ""

#: library/doctest.rst:818
msgid "Another bad idea is to print things that embed an object address, like"
msgstr ""

#: library/doctest.rst:820
msgid ""
">>> id(1.0)  # certain to fail some of the time  \n"
"7948648\n"
">>> class C: pass\n"
">>> C()  # the default repr() for instances embeds an address   \n"
"<C object at 0x00AC18F0>"
msgstr ""

#: library/doctest.rst:828
msgid ""
"The :const:`ELLIPSIS` directive gives a nice approach for the last example:"
msgstr ""

#: library/doctest.rst:830
msgid ""
">>> C()  # doctest: +ELLIPSIS\n"
"<C object at 0x...>"
msgstr ""

#: library/doctest.rst:836
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:840
msgid ""
">>> 1./7  # risky\n"
"0.14285714285714285\n"
">>> print(1./7) # safer\n"
"0.142857142857\n"
">>> print(round(1./7, 6)) # much safer\n"
"0.142857"
msgstr ""

#: library/doctest.rst:847
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:850
msgid ""
">>> 3./4  # utterly safe\n"
"0.75"
msgstr ""

#: library/doctest.rst:853
msgid ""
"Simple fractions are also easier for people to understand, and that makes "
"for better documentation."
msgstr ""

#: library/doctest.rst:860
msgid "Basic API"
msgstr ""

#: library/doctest.rst:862
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:870
msgid ""
"All arguments except *filename* are optional, and should be specified in "
"keyword form."
msgstr ""

#: library/doctest.rst:873
msgid ""
"Test examples in the file named *filename*.  Return ``(failure_count, "
"test_count)``."
msgstr ""

#: library/doctest.rst:876
msgid ""
"Optional argument *module_relative* specifies how the filename should be "
"interpreted:"
msgstr ""

#: library/doctest.rst:879
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:886
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:890
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:893
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:899
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:904
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:913
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:917
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:921
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:925
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:1071
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:1075
msgid ""
"Optional argument *encoding* specifies an encoding that should be used to "
"convert the file to unicode."
msgstr ""

#: library/doctest.rst:940
msgid ""
"All arguments are optional, and all except for *m* should be specified in "
"keyword form."
msgstr ""

#: library/doctest.rst:943
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:947
msgid ""
"Also test examples reachable from dict ``m.__test__``, if it exists. ``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:952
msgid ""
"Only docstrings attached to objects belonging to module *m* are searched."
msgstr ""

#: library/doctest.rst:954
msgid "Return ``(failure_count, test_count)``."
msgstr ""

#: library/doctest.rst:956
msgid ""
"Optional argument *name* gives the name of the module; by default, or if "
"``None``, ``m.__name__`` is used."
msgstr ""

#: library/doctest.rst:959
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 <DocTestRunner.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:967
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:974
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:977
msgid ""
"A shallow copy of dictionary argument *globs* is used for the execution "
"context."
msgstr ""

#: library/doctest.rst:979
msgid ""
"Optional argument *name* is used in failure messages, and defaults to "
"``\"NoName\"``."
msgstr ""

#: library/doctest.rst:982
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:985
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:989
msgid ""
"Optional argument *optionflags* works as for function :func:`testfile` above."
msgstr ""

#: library/doctest.rst:995
msgid "Unittest API"
msgstr ""

#: library/doctest.rst:997
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 :ref:`load_tests <load_tests-protocol>` function in "
"your test module::"
msgstr ""

#: library/doctest.rst:1003
msgid ""
"import unittest\n"
"import doctest\n"
"import my_module_with_doctests\n"
"\n"
"def load_tests(loader, tests, ignore):\n"
"    tests.addTests(doctest.DocTestSuite(my_module_with_doctests))\n"
"    return tests"
msgstr ""

#: library/doctest.rst:1011
msgid ""
"There are two main functions for creating :class:`unittest.TestSuite` "
"instances from text files and modules with doctests:"
msgstr ""

#: library/doctest.rst:1017
msgid ""
"Convert doctest tests from one or more text files to a :class:`unittest."
"TestSuite`."
msgstr ""

#: library/doctest.rst:1020
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:1026
msgid "Pass one or more paths (as strings) to text files to be examined."
msgstr ""

#: library/doctest.rst:1028
msgid "Options may be provided as keyword arguments:"
msgstr ""

#: library/doctest.rst:1030
msgid ""
"Optional argument *module_relative* specifies how the filenames in *paths* "
"should be interpreted:"
msgstr ""

#: library/doctest.rst:1033
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:1041
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:1045
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:1052
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:1057
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:1096
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:1066
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:1078
msgid ""
"The global ``__file__`` is added to the globals provided to doctests loaded "
"from a text file using :func:`DocFileSuite`."
msgstr ""

#: library/doctest.rst:1084
msgid "Convert doctest tests for a module to a :class:`unittest.TestSuite`."
msgstr ""

#: library/doctest.rst:1086
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:1092
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:1100
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:1103
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:1106
msgid ""
"Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as "
"for function :func:`DocFileSuite` above."
msgstr ""

#: library/doctest.rst:1109
msgid "This function uses the same search technique as :func:`testmod`."
msgstr ""

#: library/doctest.rst:1111
msgid ""
":func:`DocTestSuite` returns an empty :class:`unittest.TestSuite` if "
"*module* contains no docstrings instead of raising :exc:`ValueError`."
msgstr ""

#: library/doctest.rst:1117
msgid ""
"When doctests which have been converted to unit tests by :func:"
"`DocFileSuite` or :func:`DocTestSuite` fail, this exception is raised "
"showing the name of the file containing the test and a (sometimes "
"approximate) line number."
msgstr ""

#: library/doctest.rst:1121
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:1127
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:1131
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:1141
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:1147
msgid "Set the :mod:`doctest` reporting flags to use."
msgstr ""

#: library/doctest.rst:1149
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:1152
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:1163
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:1170
msgid "Advanced API"
msgstr ""

#: library/doctest.rst:1172
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:1177
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:1180
msgid ""
":class:`Example`: A single Python :term:`statement`, paired with its "
"expected output."
msgstr ""

#: library/doctest.rst:1183
msgid ""
":class:`DocTest`: A collection of :class:`Example`\\ s, typically extracted "
"from a single docstring or text file."
msgstr ""

#: library/doctest.rst:1186
msgid ""
"Additional processing classes are defined to find, parse, and run, and check "
"doctest examples:"
msgstr ""

#: library/doctest.rst:1189
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:1193
msgid ""
":class:`DocTestParser`: Creates a :class:`DocTest` object from a string "
"(such as an object's docstring)."
msgstr ""

#: library/doctest.rst:1196
msgid ""
":class:`DocTestRunner`: Executes the examples in a :class:`DocTest`, and "
"uses an :class:`OutputChecker` to verify their output."
msgstr ""

#: library/doctest.rst:1199
msgid ""
":class:`OutputChecker`: Compares the actual output from a doctest example "
"with the expected output, and decides whether they match."
msgstr ""

#: library/doctest.rst:1202
msgid ""
"The relationships among these processing classes are summarized in the "
"following diagram::"
msgstr ""

#: library/doctest.rst:1205
msgid ""
"                            list of:\n"
"+------+                   +---------+\n"
"|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results\n"
"+------+    |        ^     +---------+     |       ^    (printed)\n"
"            |        |     | Example |     |       |\n"
"            v        |     |   ...   |     v       |\n"
"           DocTestParser   | Example |   OutputChecker\n"
"                           +---------+"
msgstr ""

#: library/doctest.rst:1218
msgid "DocTest Objects"
msgstr ""

#: library/doctest.rst:1223
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:1227
msgid ""
":class:`DocTest` defines the following attributes.  They are initialized by "
"the constructor, and should not be modified directly."
msgstr ""

#: library/doctest.rst:1233
msgid ""
"A list of :class:`Example` objects encoding the individual interactive "
"Python examples that should be run by this test."
msgstr ""

#: library/doctest.rst:1239
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:1247
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:1253
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:1260
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:1267
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:1274
msgid "Example Objects"
msgstr ""

#: library/doctest.rst:1279
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:1284
msgid ""
":class:`Example` defines the following attributes.  They are initialized by "
"the constructor, and should not be modified directly."
msgstr ""

#: library/doctest.rst:1290
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:1297
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:1305
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:1314
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:1321
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:1327
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 :ref:`optionflags <doctest-options>`). By "
"default, no options are set."
msgstr ""

#: library/doctest.rst:1337
msgid "DocTestFinder objects"
msgstr ""

#: library/doctest.rst:1342
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:1347
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:1350
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:1353
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:1356
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:1360
msgid ":class:`DocTestFinder` defines the following method:"
msgstr ""

#: library/doctest.rst:1365
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:1368
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:1372
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:1376
msgid "As a default namespace, if *globs* is not specified."
msgstr ""

#: library/doctest.rst:1378
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:1382
msgid "To find the name of the file containing the object."
msgstr ""

#: library/doctest.rst:1384
msgid "To help find the line number of the object within its file."
msgstr ""

#: library/doctest.rst:1386
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:1392
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:1403
msgid "DocTestParser objects"
msgstr ""

#: library/doctest.rst:1408
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:1412
msgid ":class:`DocTestParser` defines the following methods:"
msgstr ""

#: library/doctest.rst:1417
msgid ""
"Extract all doctest examples from the given string, and collect them into a :"
"class:`DocTest` object."
msgstr ""

#: library/doctest.rst:1420
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:1427
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:1434
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:1443
msgid "DocTestRunner objects"
msgstr ""

#: library/doctest.rst:1448
msgid ""
"A processing class used to execute and verify the interactive examples in a :"
"class:`DocTest`."
msgstr ""

#: library/doctest.rst:1451
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:1457
msgid ""
"The test runner's display output can be controlled in two ways. First, an "
"output function can be passed to :meth:`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:1465
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:1469
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:1475
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:1480
msgid ":class:`DocTestRunner` defines the following methods:"
msgstr ""

#: library/doctest.rst:1485
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:1489
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:1496
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:1511
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:1507
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:1518
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:1522
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:1530
msgid ""
"Run the examples in *test* (a :class:`DocTest` object), and display the "
"results using the writer function *out*."
msgstr ""

#: library/doctest.rst:1533
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:1538
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:1542
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:1549
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:1552
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:1559
msgid "OutputChecker objects"
msgstr ""

#: library/doctest.rst:1564
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:1571
msgid ":class:`OutputChecker` defines the following methods:"
msgstr ""

#: library/doctest.rst:1575
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:1584
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:1592
msgid "Debugging"
msgstr ""

#: library/doctest.rst:1594
msgid "Doctest provides several mechanisms for debugging doctest examples:"
msgstr ""

#: library/doctest.rst:1596
msgid ""
"Several functions convert doctests to executable Python programs, which can "
"be run under the Python debugger, :mod:`pdb`."
msgstr ""

#: library/doctest.rst:1599
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:1604
msgid ""
"The :mod:`unittest` cases generated by :func:`DocTestSuite` support the :"
"meth:`debug` method defined by :class:`unittest.TestCase`."
msgstr ""

#: library/doctest.rst:1607
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:1612
msgid ""
"\"\"\"\n"
">>> def f(x):\n"
"...     g(x*2)\n"
">>> def g(x):\n"
"...     print(x+3)\n"
"...     import pdb; pdb.set_trace()\n"
">>> f(3)\n"
"9\n"
"\"\"\""
msgstr ""

#: library/doctest.rst:1622
msgid "Then an interactive Python session may look like this::"
msgstr ""

#: library/doctest.rst:1624
msgid ""
">>> import a, doctest\n"
">>> doctest.testmod(a)\n"
"--Return--\n"
"> <doctest a[1]>(3)g()->None\n"
"-> import pdb; pdb.set_trace()\n"
"(Pdb) list\n"
"  1     def g(x):\n"
"  2         print(x+3)\n"
"  3  ->     import pdb; pdb.set_trace()\n"
"[EOF]\n"
"(Pdb) p x\n"
"6\n"
"(Pdb) step\n"
"--Return--\n"
"> <doctest a[0]>(2)f()->None\n"
"-> g(x*2)\n"
"(Pdb) list\n"
"  1     def f(x):\n"
"  2  ->     g(x*2)\n"
"[EOF]\n"
"(Pdb) p x\n"
"3\n"
"(Pdb) step\n"
"--Return--\n"
"> <doctest a[2]>(1)?()->None\n"
"-> f(3)\n"
"(Pdb) cont\n"
"(0, 3)\n"
">>>"
msgstr ""

#: library/doctest.rst:1655
msgid ""
"Functions that convert doctests to Python code, and possibly run the "
"synthesized code under the debugger:"
msgstr ""

#: library/doctest.rst:1661
msgid "Convert text with examples to a script."
msgstr ""

#: library/doctest.rst:1663
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:1668
msgid ""
"import doctest\n"
"print(doctest.script_from_examples(r\"\"\"\n"
"    Set x and y to 1 and 2.\n"
"    >>> x, y = 1, 2\n"
"\n"
"    Print their sum:\n"
"    >>> print(x+y)\n"
"    3\n"
"\"\"\"))"
msgstr ""

#: library/doctest.rst:1678
msgid "displays::"
msgstr ""

#: library/doctest.rst:1680
msgid ""
"# Set x and y to 1 and 2.\n"
"x, y = 1, 2\n"
"#\n"
"# Print their sum:\n"
"print(x+y)\n"
"# Expected:\n"
"## 3"
msgstr ""

#: library/doctest.rst:1688
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:1695
msgid "Convert the doctest for an object to a script."
msgstr ""

#: library/doctest.rst:1697
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:1704
msgid ""
"import a, doctest\n"
"print(doctest.testsource(a, \"a.f\"))"
msgstr ""

#: library/doctest.rst:1707
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:1713
msgid "Debug the doctests for an object."
msgstr ""

#: library/doctest.rst:1715
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:1720
msgid ""
"A shallow copy of ``module.__dict__`` is used for both local and global "
"execution context."
msgstr ""

#: library/doctest.rst:1723
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:1734
msgid "Debug the doctests in a string."
msgstr ""

#: library/doctest.rst:1736
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:1739
msgid ""
"Optional argument *pm* has the same meaning as in function :func:`debug` "
"above."
msgstr ""

#: library/doctest.rst:1741
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:1746
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:1754
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:1761
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:1764
msgid ""
"There are two exceptions that may be raised by :class:`DebugRunner` "
"instances:"
msgstr ""

#: library/doctest.rst:1769
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:1773
msgid ":exc:`DocTestFailure` defines the following attributes:"
msgstr ""

#: library/doctest.rst:1802
msgid "The :class:`DocTest` object that was being run when the example failed."
msgstr ""

#: library/doctest.rst:1807
msgid "The :class:`Example` that failed."
msgstr ""

#: library/doctest.rst:1788
msgid "The example's actual output."
msgstr ""

#: library/doctest.rst:1793
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:1797
msgid ":exc:`UnexpectedException` defines the following attributes:"
msgstr ""

#: library/doctest.rst:1812
msgid ""
"A tuple containing information about the unexpected exception, as returned "
"by :func:`sys.exc_info`."
msgstr ""

#: library/doctest.rst:1819
msgid "Soapbox"
msgstr ""

#: library/doctest.rst:1821
msgid ""
"As mentioned in the introduction, :mod:`doctest` has grown to have three "
"primary uses:"
msgstr ""

#: library/doctest.rst:1824
msgid "Checking examples in docstrings."
msgstr ""

#: library/doctest.rst:1826
msgid "Regression testing."
msgstr ""

#: library/doctest.rst:1828
msgid "Executable documentation / literate testing."
msgstr ""

#: library/doctest.rst:1830
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:1834
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:1842
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:1860
msgid ""
"Regression testing is best confined to dedicated objects or files.  There "
"are several options for organizing tests:"
msgstr ""

#: library/doctest.rst:1863
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:1868
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:1872
msgid ""
"Define a ``__test__`` dictionary mapping from regression test topics to "
"docstrings containing test cases."
msgstr ""

#: library/doctest.rst:1875
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:1880
msgid ""
"if __name__ == '__main__':\n"
"    import doctest\n"
"    flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST\n"
"    if len(sys.argv) > 1:\n"
"        name = sys.argv[1]\n"
"        if name in globals():\n"
"            obj = globals()[name]\n"
"        else:\n"
"            obj = __test__[name]\n"
"        doctest.run_docstring_examples(obj, globals(), name=name,\n"
"                                       optionflags=flags)\n"
"    else:\n"
"        fail, total = doctest.testmod(optionflags=flags)\n"
"        print(\"{} failures out of {} tests\".format(fail, total))"
msgstr ""

#: library/doctest.rst:1897
msgid "Footnotes"
msgstr ""

#: library/doctest.rst:1898
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 ""

#: library/doctest.rst:339
msgid ">>>"
msgstr ""

#: library/doctest.rst:339
msgid "interpreter prompt"
msgstr ""

#: library/doctest.rst:577
msgid "..."
msgstr ""

#: library/doctest.rst:505
msgid "^ (caret)"
msgstr ""

#: library/doctest.rst:505
msgid "marker"
msgstr ""

#: library/doctest.rst:557
msgid "<BLANKLINE>"
msgstr ""

#: library/doctest.rst:707
msgid "in doctests"
msgstr ""

#: library/doctest.rst:707
msgid "# (hash)"
msgstr ""

#: library/doctest.rst:707
msgid "+ (plus)"
msgstr ""

#: library/doctest.rst:707
msgid "- (minus)"
msgstr ""