Python doctest: Skip entire block?

Question

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?

score 24 · Answer 1 · edited Oct 30 '18 at 17:57

24

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!'
"""

edited Oct 30 '18 at 17:57

Alexander Pacha

9,187
3
68
108

answered Oct 01 '11 at 19:09

lambacck

9,768
3
34
46

score 6 · Accepted Answer · answered Nov 27 '09 at 16:00

6

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.

answered Nov 27 '09 at 16:00

RobM

8,373
3
45
37

A workaround regarding the display can be found here: https://stackoverflow.com/a/55002297/5350621 – David Mar 05 '19 at 11:56
The examples cannot be copy-pasted into an IPython REPL and work, afterwards. – ankostis Jun 21 '19 at 15:29
this won't play nice with searches. No doubt other workflows too – joel Oct 22 '20 at 19:18

score 2 · Answer 3 · answered Nov 27 '09 at 14:28

2

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.

answered Nov 27 '09 at 14:28

Mark Rushakoff

249,864
45
407
398

3

Neat, but then it's also invisible to help() and epydoc. – RobM Nov 27 '09 at 14:32
I'm not sure about `help()`, but you can just add a new field in epydoc: http://epydoc.sourceforge.net/epydoc.html#adding-new-fields – Mark Rushakoff Nov 27 '09 at 14:35
[Dunder names should be reserved for system-defined names.](https://docs.python.org/3/reference/lexical_analysis.html#reserved-classes-of-identifiers). I would make it a simple private instead: `_example_usage` – wjandrea Jul 18 '20 at 00:22

score 2 · Answer 4 · answered Mar 05 '19 at 11:55

2

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!' 
"""

answered Mar 05 '19 at 11:55

David

1,909
1
20
32

hiro protagonist · Answer 5 · 2022-10-08T10:38:52.847

1

with xdoctest you can use this >>> # doctest: +SKIP as first line:

def some_function():
    """
    Some documentation
    
    Examples:
        
        >>> # doctest: +SKIP
        >>> do_something() 
        >>> do_something_else()
        >>> and_do_this()
    """

unfortunately doctest itself crashes (and sphinx prints that as >>> instead of completely ignoring it).

edited Oct 08 '22 at 10:38

answered Oct 04 '22 at 12:25

hiro protagonist

44,693
14
86
111

score 0 · Answer 6 · answered Mar 24 '22 at 14:05

I went for the # doctest: +SKIP on every line

def doc_test_test():
    """Doc tests
    
    Examples:
        
        >>> do_something1() # doctest: +SKIP
        >>> do_something2() # doctest: +SKIP
        >>> do_something3() # doctest: +SKIP
    """
    pass

Python doctest: Skip entire block?

6 Answers6

Linked