diff options
| -rw-r--r-- | Doc/lib/libdoctest.tex | 29 | ||||
| -rw-r--r-- | Lib/doctest.py | 33 |
2 files changed, 41 insertions, 21 deletions
diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex index e8983c9..6c72dbc 100644 --- a/Doc/lib/libdoctest.tex +++ b/Doc/lib/libdoctest.tex @@ -361,17 +361,28 @@ The fine print: \item Output to stdout is captured, but not output to stderr (exception tracebacks are captured via a different means). -\item If you continue a line via backslashing in an interactive session, or - for any other reason use a backslash, you need to double the backslash in - the docstring version. This is simply because you're in a string, and so - the backslash must be escaped for it to survive intact. Like: +\item 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 backslahses exactly as you type + them: \begin{verbatim} ->>> if "yes" == \\ -... "y" + \\ -... "es": -... print 'yes' -yes +>>> def f(x): +... r'''Backslashes in a raw docstring: m\n''' +>>> print f.__doc__ +Backslashes in a raw docstring: m\n +\end{verbatim} + + Otherwise, the backslash will be interpreted as part of the string. + E.g., the "\textbackslash" above would be interpreted as a newline + character. Alternatively, you can double each backslash in the + doctest version (and not use a raw string): + +\begin{verbatim} +>>> def f(x): +... '''Backslashes in a raw docstring: m\\n''' +>>> print f.__doc__ +Backslashes in a raw docstring: m\n \end{verbatim} \item The starting column doesn't matter: diff --git a/Lib/doctest.py b/Lib/doctest.py index 5020684..acde9c1 100644 --- a/Lib/doctest.py +++ b/Lib/doctest.py @@ -4,7 +4,7 @@ # Provided as-is; use at your own risk; no warranty; no promises; enjoy! -"""Module doctest -- a framework for running examples in docstrings. +r"""Module doctest -- a framework for running examples in docstrings. NORMAL USAGE @@ -200,17 +200,26 @@ Bummers: + Output to stdout is captured, but not output to stderr (exception tracebacks are captured via a different means). -+ If you continue a line via backslashing in an interactive session, or for - any other reason use a backslash, you need to double the backslash in the - docstring version. This is simply because you're in a string, and so the - backslash must be escaped for it to survive intact. Like: - ->>> if "yes" == \\ -... "y" + \\ -... "es": # in the source code you'll see the doubled backslashes -... print 'yes' -yes - ++ 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 backslahses exactly as you type + them: + + >>> def f(x): + ... r'''Backslashes in a raw docstring: m\n''' + >>> print f.__doc__ + Backslashes in a raw docstring: m\n + + Otherwise, the backslash will be interpreted as part of the string. + E.g., 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): + + >>> def f(x): + ... '''Backslashes in a raw docstring: m\\n''' + >>> print f.__doc__ + Backslashes in a raw docstring: m\n + The starting column doesn't matter: >>> assert "Easy!" |