Doctest processing
==================

Imports in doctest sections inside docstrings are also handled

    >>> from findimports import find_imports

    >>> with open('marmalade.py', 'w') as f: _ = f.write('''
    ... import doctest
    ... def example():
    ...     """
    ...         >>> import sys
    ...     """
    ... class Example:
    ...     """
    ...         >>> import gc
    ...     """
    ... ''')

    >>> for imp in find_imports('marmalade.py'):
    ...     print(imp)
    ImportInfo('doctest', 'marmalade.py', 2, None)
    ImportInfo('sys', 'marmalade.py', 5, None)
    ImportInfo('gc', 'marmalade.py', 9, None)

Note that we carefully adjust line numbers to make sure they match reality.


Module docstrings
-----------------

Module docstrings are special in that the corresponding module AST node has
no line number.  We don't crash:

    >>> with open('jam.py', 'w') as f: _ = f.write('''
    ... """
    ...         >>> import sys
    ... """
    ... ''')

    >>> for imp in find_imports('jam.py'):
    ...     print(imp)
    ImportInfo('sys', 'jam.py', 3, None)


Doctest errors
--------------

Doctest errors abort processing, after showing where the erroneous docstring
is

    >>> with open('peanut_butter.py', 'w') as f: _ = f.write('''
    ... def example():
    ...     """
    ...         >>> import sys
    ...     missing blank line after doctest section
    ...     """
    ... ''')

    >>> try:
    ...     for imp in find_imports('peanut_butter.py'):
    ...         print(imp)
    ... except:
    ...     import traceback
    ...     traceback.print_exc()
    ... # doctest: +ELLIPSIS
    peanut_butter.py:2: error while parsing doctest
    Traceback (most recent call last):
      ...
    ValueError: line 3 of the docstring for <string> has inconsistent leading whitespace: 'missing blank line after doctest section'

    >>> with open('jelly.py', 'w') as f: _ = f.write('''
    ... def example1():
    ...     """
    ...         >>> if something:
    ...         >>> import sys
    ...     """
    ... def example1():
    ...     """
    ...         >>> import os
    ...     """
    ... ''')

    >>> for imp in find_imports('jelly.py'):
    ...     print(imp)
    jelly.py:2: syntax error in doctest
    ImportInfo('sys', 'jelly.py', 5, None)
    ImportInfo('os', 'jelly.py', 9, None)


Nested docstrings
-----------------

This is probably overkill, but we handle them recursively:

    >>> with open('sandwitch.py', 'w') as f: _ = f.write('''
    ... def example():
    ...     """
    ...         >>> class Example:
    ...         ...    '>>> import sys'
    ...     """
    ... ''')
    >>> for imp in find_imports('sandwitch.py'):
    ...     print(imp)
    ImportInfo('sys', 'sandwitch.py', 5, None)

