Merged revisions 62490 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r62490 | benjamin.peterson | 2008-04-24 20:29:10 -0500 (Thu, 24 Apr 2008) | 2 lines
reformat some documentation of classes so methods and attributes are under the class directive
........
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index ee03572..aa662c0 100644
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -1113,48 +1113,48 @@
names.
-:class:`DocTest` defines the following member variables. They are initialized
-by the constructor, and should not be modified directly.
+ :class:`DocTest` defines the following member variables. They are initialized by
+ the constructor, and should not be modified directly.
-.. attribute:: DocTest.examples
+ .. attribute:: examples
- A list of :class:`Example` objects encoding the individual interactive Python
- examples that should be run by this test.
+ A list of :class:`Example` objects encoding the individual interactive Python
+ examples that should be run by this test.
-.. attribute:: DocTest.globs
+ .. attribute:: globs
- 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.
+ 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.
-.. attribute:: DocTest.name
+ .. attribute:: name
- A string name identifying the :class:`DocTest`. Typically, this is the name of
- the object or file that the test was extracted from.
+ A string name identifying the :class:`DocTest`. Typically, this is the name
+ of the object or file that the test was extracted from.
-.. attribute:: DocTest.filename
+ .. attribute:: filename
- 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.
+ 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.
-.. attribute:: DocTest.lineno
+ .. attribute:: lineno
- 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.
+ 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.
-.. attribute:: DocTest.docstring
+ .. attribute:: docstring
- 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.
+ 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.
.. _doctest-example:
@@ -1170,53 +1170,53 @@
of the same names.
-:class:`Example` defines the following member variables. They are initialized
-by the constructor, and should not be modified directly.
+ :class:`Example` defines the following member variables. They are initialized by
+ the constructor, and should not be modified directly.
-.. attribute:: Example.source
+ .. attribute:: source
- 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.
+ 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.
-.. attribute:: Example.want
+ .. attribute:: want
- 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.
+ 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.
-.. attribute:: Example.exc_msg
+ .. attribute:: exc_msg
- 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.
+ 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.
-.. attribute:: Example.lineno
+ .. attribute:: lineno
- 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.
+ 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.
-.. attribute:: Example.indent
+ .. attribute:: indent
- The example's indentation in the containing string, i.e., the number of space
- characters that precede the example's first prompt.
+ The example's indentation in the containing string, i.e., the number of space
+ characters that precede the example's first prompt.
-.. attribute:: Example.options
+ .. attribute:: 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
- :class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set.
+ A dictionary mapping from option flags to ``True`` or ``False``, which is used
+ to override default options for this example. Any option flags not contained
+ in this dictionary are left at their default value (as specified by the
+ :class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set.
.. _doctest-doctestfinder:
@@ -1246,44 +1246,44 @@
:meth:`DocTestFinder.find` will include tests for objects with empty docstrings.
-:class:`DocTestFinder` defines the following method:
+ :class:`DocTestFinder` defines the following method:
-.. method:: DocTestFinder.find(obj[, name][, module][, globs][, extraglobs])
+ .. method:: find(obj[, name][, module][, globs][, extraglobs])
- Return a list of the :class:`DocTest`\ s that are defined by *obj*'s docstring,
- or by any of its contained objects' docstrings.
+ Return a list of the :class:`DocTest`\ s that are defined by *obj*'s
+ docstring, or by any of its contained objects' docstrings.
- 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.
+ 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.
- 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:
+ 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:
- * As a default namespace, if *globs* is not specified.
+ * As a default namespace, if *globs* is not specified.
- * To prevent the DocTestFinder from extracting DocTests from objects that are
- imported from other modules. (Contained objects with modules other than
- *module* are ignored.)
+ * To prevent the DocTestFinder from extracting DocTests from objects that are
+ imported from other modules. (Contained objects with modules other than
+ *module* are ignored.)
- * To find the name of the file containing the object.
+ * To find the name of the file containing the object.
- * To help find the line number of the object within its file.
+ * To help find the line number of the object within its file.
- 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.
+ 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.
- 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 ``{}``.
+ 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 ``{}``.
.. _doctest-doctestparser:
@@ -1298,32 +1298,32 @@
them to create a :class:`DocTest` object.
-:class:`DocTestParser` defines the following methods:
+ :class:`DocTestParser` defines the following methods:
-.. method:: DocTestParser.get_doctest(string, globs, name, filename, lineno)
+ .. method:: get_doctest(string, globs, name, filename, lineno)
- Extract all doctest examples from the given string, and collect them into a
- :class:`DocTest` object.
+ Extract all doctest examples from the given string, and collect them into a
+ :class:`DocTest` object.
- *globs*, *name*, *filename*, and *lineno* are attributes for the new
- :class:`DocTest` object. See the documentation for :class:`DocTest` for more
- information.
+ *globs*, *name*, *filename*, and *lineno* are attributes for the new
+ :class:`DocTest` object. See the documentation for :class:`DocTest` for more
+ information.
-.. method:: DocTestParser.get_examples(string[, name])
+ .. method:: get_examples(string[, name])
- 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.
+ 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.
-.. method:: DocTestParser.parse(string[, name])
+ .. method:: parse(string[, name])
- 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.
+ 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.
.. _doctest-doctestrunner:
@@ -1366,81 +1366,81 @@
For more information, see section :ref:`doctest-options`.
-:class:`DocTestParser` defines the following methods:
+ :class:`DocTestParser` defines the following methods:
-.. method:: DocTestRunner.report_start(out, test, example)
+ .. method:: report_start(out, test, example)
- 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.
+ 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.
- *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`.
+ *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`.
-.. method:: DocTestRunner.report_success(out, test, example, got)
+ .. method:: report_success(out, test, example, got)
- 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.
+ 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.
- *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`.
+ *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`.
-.. method:: DocTestRunner.report_failure(out, test, example, got)
+ .. method:: report_failure(out, test, example, got)
- 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.
+ 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.
- *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`.
+ *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`.
-.. method:: DocTestRunner.report_unexpected_exception(out, test, example, exc_info)
+ .. method:: report_unexpected_exception(out, test, example, exc_info)
- 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.
+ 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.
- *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`.
+ *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`.
-.. method:: DocTestRunner.run(test[, compileflags][, out][, clear_globs])
+ .. method:: run(test[, compileflags][, out][, clear_globs])
- Run the examples in *test* (a :class:`DocTest` object), and display the results
- using the writer function *out*.
+ Run the examples in *test* (a :class:`DocTest` object), and display the
+ results using the writer function *out*.
- 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*.
+ 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*.
- *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*.
+ *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*.
- 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.
+ 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.
-.. method:: DocTestRunner.summarize([verbose])
+ .. method:: summarize([verbose])
- Print a summary of all the test cases that have been run by this DocTestRunner,
- and return a :term:`named tuple` ``TestResults(failed, attempted)``.
+ Print a summary of all the test cases that have been run by this DocTestRunner,
+ and return a :term:`named tuple` ``TestResults(failed, attempted)``.
- The optional *verbose* argument controls how detailed the summary is. If the
- verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is used.
-
+ The optional *verbose* argument controls how detailed the summary is. If the
+ verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is
+ used.
.. _doctest-outputchecker:
@@ -1457,22 +1457,22 @@
the differences between two outputs.
-:class:`OutputChecker` defines the following methods:
+ :class:`OutputChecker` defines the following methods:
-.. method:: OutputChecker.check_output(want, got, optionflags)
+ .. method:: check_output(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 section
- :ref:`doctest-options` for more information about option flags.
+ 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.
-.. method:: OutputChecker.output_difference(example, got, optionflags)
+ .. method:: output_difference(example, got, optionflags)
- 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*.
+ 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*.
.. _doctest-debugging: