[Python-checkins] python/dist/src/Doc/lib libdoctest.tex,1.23,1.24
tim_one at users.sourceforge.net
tim_one at users.sourceforge.net
Fri Aug 13 00:31:27 CEST 2004
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv20362/Doc/lib
Modified Files:
libdoctest.tex
Log Message:
Excruciatingly slow progress on the docs. Option flags / directive names
are documented now, and ripped out a bunch of "private name" convolutions.
Index: libdoctest.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdoctest.tex,v
retrieving revision 1.23
retrieving revision 1.24
diff -C2 -d -r1.23 -r1.24
*** libdoctest.tex 10 Aug 2004 15:41:03 -0000 1.23
--- libdoctest.tex 12 Aug 2004 22:31:25 -0000 1.24
***************
*** 215,219 ****
examples start with a clean slate.
! Optional argument \var{extraglobs} gives a dicti merged into the
globals used to execute examples. This works like
\method{dict.update()}: if \var{globs} and \var{extraglobs} have a
--- 215,219 ----
examples start with a clean slate.
! Optional argument \var{extraglobs} gives a dict merged into the
globals used to execute examples. This works like
\method{dict.update()}: if \var{globs} and \var{extraglobs} have a
***************
*** 235,277 ****
passed).
! Optional argument \var{optionflags} or's together module constants,
! and defaults to 0.
!
! % Possible values:
! %
! % DONT_ACCEPT_TRUE_FOR_1
! % By default, if an expected output block contains just "1",
! % an actual output block containing just "True" is considered
! % to be a match, and similarly for "0" versus "False". When
! % DONT_ACCEPT_TRUE_FOR_1 is specified, neither substitution
! % is allowed.
! %
! % DONT_ACCEPT_BLANKLINE
! % 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. When
! % DONT_ACCEPT_BLANKLINE is specified, this substitution is
! % not allowed.
! %
! % NORMALIZE_WHITESPACE
! % When NORMALIZE_WHITESPACE is specified, all sequences of
! % whitespace are treated as equal. I.e., any sequence of
! % whitespace within the expected output will match any
! % sequence of whitespace within the actual output.
! %
! % ELLIPSIS
! % When ELLIPSIS is specified, then an ellipsis marker
! % ("...") in the expected output can match any substring in
! % the actual output.
! %
! % UNIFIED_DIFF
! % When UNIFIED_DIFF is specified, failures that involve
! % multi-line expected and actual outputs will be displayed
! % using a unified diff.
! %
! % CONTEXT_DIFF
! % When CONTEXT_DIFF is specified, failures that involve
! % multi-line expected and actual outputs will be displayed
! % using a context diff.
Optional argument \var{raise_on_error} defaults to false. If true,
--- 235,240 ----
passed).
! Optional argument \var{optionflags} or's together option flags. See
! see section \ref{doctest-options}.
Optional argument \var{raise_on_error} defaults to false. If true,
***************
*** 300,306 ****
\versionchanged[The parameter \var{optionflags} was added]{2.3}
- \versionchanged[Many new module constants for use with \var{optionflags}
- were added]{2.4}
-
\versionchanged[The parameters \var{extraglobs} and \var{raise_on_error}
were added]{2.4}
--- 263,266 ----
***************
*** 310,325 ****
\subsection{Which Docstrings Are Examined?}
! See the docstrings in \file{doctest.py} for all the details. They're
! unsurprising: the module docstring, and all function, class and method
! docstrings are searched. Optionally, the tester can be directed to
! exclude docstrings attached to objects with private names. Objects
! imported into the module are not searched.
In addition, if \code{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
! \code{M.__test__} are searched even if the tester has been
! directed to skip over private names in the rest of the module.
! In output, a key \code{K} in \code{M.__test__} appears with name
\begin{verbatim}
--- 270,282 ----
\subsection{Which Docstrings Are Examined?}
! The module docstring, and all function, class and method docstrings are
! searched. Objects imported into the module are not searched.
In addition, if \code{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
! \code{M.__test__} are searched, and strings are treated as if they
! were docstrings. In output, a key \code{K} in \code{M.__test__} appears
! with name
\begin{verbatim}
***************
*** 328,334 ****
Any classes found are recursively searched similarly, to test docstrings in
! their contained methods and nested classes. While private names reached
! from \module{M}'s globals can be optionally skipped, all names reached from
! \code{M.__test__} are searched.
\subsection{What's the Execution Context?}
--- 285,293 ----
Any classes found are recursively searched similarly, to test docstrings in
! their contained methods and nested classes.
!
! \versionchanged[A "private name" concept is deprecated and no longer
! documented.]{2.4}
!
\subsection{What's the Execution Context?}
***************
*** 364,367 ****
--- 323,390 ----
value of the example).
+ \subsection{Option Flags and Directive Names\label{doctest-options}}
+
+ 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 or'ed together and passed to various functions. The names can
+ also be used in doctest directives.
+
+ \begin{datadesc}{DONT_ACCEPT_TRUE_FOR_1}
+ By default, if an expected output block contains just \code{1},
+ an actual output block containing just \code{1} or just
+ \code{True} is considered to be a match, and similarly for \code{0}
+ versus \code{False}. When \constant{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.
+ \end{datadesc}
+
+ \begin{datadesc}{DONT_ACCEPT_BLANKLINE}
+ By default, if an expected output block contains a line
+ containing only the string \code{<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
+ \constant{DONT_ACCEPT_BLANKLINE} is specified, this substitution
+ is not allowed.
+ \end{datadesc}
+
+ \begin{datadesc}{NORMALIZE_WHITESPACE}
+ 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.
+ \constant{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.
+ \end{datadesc}
+
+ \begin{datadesc}{ELLIPSIS}
+ When specified, an ellipsis marker (\code{...}) in the expected output
+ can match any substring in the actual output. This includes
+ substrings that span line boundaries, so it's best to keep usage of
+ this simple. Complicated uses can lead to the same kinds of
+ surprises that \code{.*} is prone to in regular expressions.
+ \end{datadesc}
+
+ \begin{datadesc}{UNIFIED_DIFF}
+ When specified, failures that involve multi-line expected and
+ actual outputs are displayed using a unified diff.
+ \end{datadesc}
+
+ \begin{datadesc}{CONTEXT_DIFF}
+ When specified, failures that involve multi-line expected and
+ actual outputs will be displayed using a context diff.
+ \end{datadesc}
+
+
+ \versionchanged[Constants \constant{DONT_ACCEPT_BLANKLINE},
+ \constant{NORMALIZE_WHITESPACE}, \constant{ELLIPSIS},
+ \constant{UNIFIED_DIFF}, and \constant{CONTEXT_DIFF}
+ were added, and \code{<BLANKLINE>} in expected output matches
+ an empty line in actual output by default.]{2.4}
+
\subsection{Advanced Usage}
More information about the Python-checkins
mailing list