[Python-checkins] python/dist/src/Lib doctest.py,1.59,1.60

edloper at users.sourceforge.net edloper at users.sourceforge.net
Thu Aug 12 04:27:47 CEST 2004


Update of /cvsroot/python/python/dist/src/Lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv8446/dist/src/Lib

Modified Files:
	doctest.py 
Log Message:
- Changed option directives to be example-specific.  (i.e., they now
  modify option flags for a single example; they do not turn options
  on or off.)
- Added "indent" and "options" attributes for Example
- Got rid of add_newlines param to DocTestParser._parse_example (it's
  no longer needed; Example's constructor now takes care of it).
- Added some docstrings


Index: doctest.py
===================================================================
RCS file: /cvsroot/python/python/dist/src/Lib/doctest.py,v
retrieving revision 1.59
retrieving revision 1.60
diff -C2 -d -r1.59 -r1.60
*** doctest.py	12 Aug 2004 02:02:24 -0000	1.59
--- doctest.py	12 Aug 2004 02:27:44 -0000	1.60
***************
*** 368,384 ****
      output.  `Example` defines the following attributes:
  
!       - source:  A single Python statement, always ending with a newline.
          The constructor adds a newline if needed.
  
!       - want:  The expected output from running the source code (either
          from stdout, or a traceback in case of exception).  `want` ends
          with a newline unless it's empty, in which case it's an empty
          string.  The constructor adds a newline if needed.
  
!       - lineno:  The line number within the DocTest string containing
          this Example where the Example begins.  This line number is
          zero-based, with respect to the beginning of the DocTest.
      """
!     def __init__(self, source, want, lineno):
          # Normalize inputs.
          if not source.endswith('\n'):
--- 368,394 ----
      output.  `Example` defines the following attributes:
  
!       - source: A single Python statement, always ending with a newline.
          The constructor adds a newline if needed.
  
!       - want: The expected output from running the source code (either
          from stdout, or a traceback in case of exception).  `want` ends
          with a newline unless it's empty, in which case it's an empty
          string.  The constructor adds a newline if needed.
  
!       - lineno: The line number within the DocTest string containing
          this Example where the Example begins.  This line number is
          zero-based, with respect to the beginning of the DocTest.
+ 
+       - indent: The example's indentation in the DocTest string.
+         I.e., the number of space characters that preceed the
+         example's first prompt.
+ 
+       - options: 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
+         DocTestRunner's optionflags).  By default, no options are set.
      """
!     def __init__(self, source, want, lineno, indent=0, options=None):
          # Normalize inputs.
          if not source.endswith('\n'):
***************
*** 390,393 ****
--- 400,406 ----
          self.want = want
          self.lineno = lineno
+         self.indent = indent
+         if options is None: options = {}
+         self.options = options
  
  class DocTest:
***************
*** 516,526 ****
              # Update lineno (lines before this example)
              lineno += string.count('\n', charno, m.start())
- 
              # Extract source/want from the regexp match.
              (source, want) = self._parse_example(m, name, lineno)
              if self._IS_BLANK_OR_COMMENT(source):
                  continue
!             examples.append( Example(source, want, lineno) )
! 
              # Update lineno (lines inside this example)
              lineno += string.count('\n', m.start(), m.end())
--- 529,542 ----
              # Update lineno (lines before this example)
              lineno += string.count('\n', charno, m.start())
              # Extract source/want from the regexp match.
              (source, want) = self._parse_example(m, name, lineno)
+             # Extract extra options from the source.
+             options = self._find_options(source, name, lineno)
+             # If it contains no real source, then ignore it.
              if self._IS_BLANK_OR_COMMENT(source):
                  continue
!             # Create an Example, and add it to the list.
!             examples.append( Example(source, want, lineno,
!                                      len(m.group('indent')), options) )
              # Update lineno (lines inside this example)
              lineno += string.count('\n', m.start(), m.end())
***************
*** 579,583 ****
  
              # Extract source/want from the regexp match.
!             (source, want) = self._parse_example(m, name, lineno, False)
              # Display the source
              output.append(source)
--- 595,599 ----
  
              # Extract source/want from the regexp match.
!             (source, want) = self._parse_example(m, name, lineno)
              # Display the source
              output.append(source)
***************
*** 601,605 ****
          return '\n'.join(output)
  
!     def _parse_example(self, m, name, lineno, add_newlines=True):
          # Get the example's indentation level.
          indent = len(m.group('indent'))
--- 617,631 ----
          return '\n'.join(output)
  
!     def _parse_example(self, m, name, lineno):
!         """
!         Given a regular expression match from `_EXAMPLE_RE` (`m`),
!         return a pair `(source, want)`, where `source` is the matched
!         example's source code (with prompts and indentation stripped);
!         and `want` is the example's expected output (with indentation
!         stripped).
! 
!         `name` is the string's name, and `lineno` is the line number
!         where the example starts; both are used for error messages.
!         """
          # Get the example's indentation level.
          indent = len(m.group('indent'))
***************
*** 611,616 ****
          self._check_prefix(source_lines[1:], ' '*indent+'.', name, lineno)
          source = '\n'.join([sl[indent+4:] for sl in source_lines])
-         if len(source_lines) > 1 and add_newlines:
-             source += '\n'
  
          # Divide want into lines; check that it's properly
--- 637,640 ----
***************
*** 620,629 ****
                             lineno+len(source_lines))
          want = '\n'.join([wl[indent:] for wl in want_lines])
-         if len(want) > 0 and add_newlines:
-             want += '\n'
  
          return source, want
  
      def _comment_line(self, line):
          line = line.rstrip()
          if line:
--- 644,688 ----
                             lineno+len(source_lines))
          want = '\n'.join([wl[indent:] for wl in want_lines])
  
          return source, want
  
+     # This regular expression looks for option directives in the
+     # source code of an example.  Option directives are comments
+     # starting with "doctest:".  Warning: this may give false
+     # positives for string-literals that contain the string
+     # "#doctest:".  Eliminating these false positives would require
+     # actually parsing the string; but we limit them by ignoring any
+     # line containing "#doctest:" that is *followed* by a quote mark.
+     _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
+                                       re.MULTILINE)
+ 
+     def _find_options(self, source, name, lineno):
+         """
+         Return a dictionary containing option overrides extracted from
+         option directives in the given source string.
+ 
+         `name` is the string's name, and `lineno` is the line number
+         where the example starts; both are used for error messages.
+         """
+         options = {}
+         # (note: with the current regexp, this will match at most once:)
+         for m in self._OPTION_DIRECTIVE_RE.finditer(source):
+             option_strings = m.group(1).replace(',', ' ').split()
+             for option in option_strings:
+                 if (option[0] not in '+-' or
+                     option[1:] not in OPTIONFLAGS_BY_NAME):
+                     raise ValueError('line %r of the doctest for %s '
+                                      'has an invalid option: %r' %
+                                      (lineno+1, name, option))
+                 flag = OPTIONFLAGS_BY_NAME[option[1:]]
+                 options[flag] = (option[0] == '+')
+         if options and self._IS_BLANK_OR_COMMENT(source):
+             raise ValueError('line %r of the doctest for %s has an option '
+                              'directive on a line with no example: %r' %
+                              (lineno, name, source))
+         return options
+ 
      def _comment_line(self, line):
+         "Return a commented form of the given line"
          line = line.rstrip()
          if line:
***************
*** 633,636 ****
--- 692,701 ----
  
      def _check_prompt_blank(self, lines, indent, name, lineno):
+         """
+         Given the lines of a source string (including prompts and
+         leading indentation), check to make sure that every prompt is
+         followed by a space character.  If any line is not followed by
+         a space character, then raise ValueError.
+         """
          for i, line in enumerate(lines):
              if len(line) >= indent+4 and line[indent+3] != ' ':
***************
*** 641,644 ****
--- 706,713 ----
  
      def _check_prefix(self, lines, prefix, name, lineno):
+         """
+         Check that every line in the given list starts with the given
+         prefix; if any line does not, then raise a ValueError.
+         """
          for i, line in enumerate(lines):
              if line and not line.startswith(prefix):
***************
*** 1106,1135 ****
                                 re.MULTILINE | re.DOTALL)
  
-     _OPTION_DIRECTIVE_RE = re.compile('\s*doctest:\s*(?P<flags>[^#\n]*)')
- 
-     def __handle_directive(self, example):
-         """
-         Check if the given example is actually a directive to doctest
-         (to turn an optionflag on or off); and if it is, then handle
-         the directive.
- 
-         Return true iff the example is actually a directive (and so
-         should not be executed).
- 
-         """
-         m = self._OPTION_DIRECTIVE_RE.match(example.source)
-         if m is None:
-             return False
- 
-         for flag in m.group('flags').upper().split():
-             if (flag[:1] not in '+-' or
-                 flag[1:] not in OPTIONFLAGS_BY_NAME):
-                 raise ValueError('Bad doctest option directive: '+flag)
-             if flag[0] == '+':
-                 self.optionflags |= OPTIONFLAGS_BY_NAME[flag[1:]]
-             else:
-                 self.optionflags &= ~OPTIONFLAGS_BY_NAME[flag[1:]]
-         return True
- 
      def __run(self, test, compileflags, out):
          """
--- 1175,1178 ----
***************
*** 1151,1158 ****
          # Process each example.
          for example in test.examples:
!             # Check if it's an option directive.  If it is, then handle
!             # it, and go on to the next example.
!             if self.__handle_directive(example):
!                 continue
  
              # Record that we started this example.
--- 1194,1205 ----
          # Process each example.
          for example in test.examples:
!             # Merge in the example's options.
!             self.optionflags = original_optionflags
!             if example.options:
!                 for (optionflag, val) in example.options.items():
!                     if val:
!                         self.optionflags |= optionflag
!                     else:
!                         self.optionflags &= ~optionflag
  
              # Record that we started this example.
***************
*** 1350,1359 ****
      def check_output(self, want, got, optionflags):
          """
!         Return True iff the actual output (`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 the documentation for `TestRunner` for more
!         information about option flags.
          """
          # Handle the common case first, for efficiency:
--- 1397,1407 ----
      def check_output(self, want, got, optionflags):
          """
!         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 the
!         documentation for `TestRunner` for more information about
!         option flags.
          """
          # Handle the common case first, for efficiency:
***************
*** 1412,1416 ****
          """
          Return a string describing the differences between the
!         expected output (`want`) and the actual output (`got`).
          """
          # If <BLANKLINE>s are being used, then replace <BLANKLINE>
--- 1460,1467 ----
          """
          Return a string describing the differences between the
!         expected output for an example (`want`) and the actual output
!         (`got`).  `optionflags` is the set of option flags used to
!         compare `want` and `got`.  `indent` is the indentation of the
!         original example.
          """
          # If <BLANKLINE>s are being used, then replace <BLANKLINE>



More information about the Python-checkins mailing list