I've got a Python module with docstrings in class methods, and a real-world example in the module docstring. The distinction is that the method-docstrings have been carefully crafted to be utterly repeatable tests, while the real-world example is just a copy'n'paste of the history from a Linux shell - which happened to invoke the python interpreter.
E.g.
"""
Real-world example:
# python2.5
Python 2.5 (release25-maint, Jul 20 2008, 20:47:25)
[GCC 4.1.2 20061115 (prerelease) (Debian 4.1.1-21)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> from packagename import module
>>> module.show_real_world_usage()
'Hello world!'
"""
class SomeClass(object):
def someMethod(self):
"""
>>> 1 == 1
True
"""
I want to run the doctest in SomeClass.someMethod, but not in the module's docstrings.
Doctest's +SKIP directive only works per line, which would mean adding 10s of lines to my real-world example. Ugly!
Is there a way to make doctest skip an entire block? A bit like <!-- ... --> in HTML?
Wrap the example in a function and then skip the function call:
"""
>>> def example():
... from packagename import module
... module.show_real_world_usage()
...
>>> example() # doctest: +SKIP
'Hello world!'
"""
My solution has been to trim the the 3-character >>> and ... leaders where I want doctest to skip over them, making them 2-characters.
So
"""
>>> from packagename import module
>>> module.show_real_world_usage()
'Hello world!'
"""
has become
"""
>> from packagename import module
>> module.show_real_world_usage()
'Hello world!'
"""
Epydoc doesn't display this as nicely as it does doctests, but I can live with this. A skip-until-further-notice directive in doctest would be welcome though.
A small workaround building upon RobM's answer preserves the display/formatting by starting the example with a >>> like that:
"""
>>>
>> from packagename import module
>> module.show_real_world_usage()
'Hello world!'
"""
If it's not an actual doctest by any means, you can just assign the value to a variable. For example,
example_usage = """
Real-world example:
# python2.5
...
"""
will cause that "test" to not be evaluated.
It might be better to use __example_usage__ (or something else surrounded by double-underscores) so that it's clear that's a "magic" variable and not a variable to be used within the context of the script.
