Merge pull request #52 from jbweston/feature/stderr

show output to stderr

Author: akhmerov

doc/source/index.rst

@@ -56,7 +56,7 @@ much richer output than mere text; plots, for example:
     from matplotlib import pyplot
     %matplotlib inline
 
-    x = np.linspace(0, 2 * np.pi)
+    x = np.linspace(1E-3, 2 * np.pi)
 
     pyplot.plot(x, np.sin(x) / x)
     pyplot.plot(x, np.cos(x))
@@ -155,16 +155,40 @@ a list of error types; if an error is raised that is not in the list then execut
       :raises: KeyError, ValueError
 
       a = {'hello': 'world!'}
-      a['jello']
+      a['hello']
 
 produces:
 
 .. jupyter-execute::
   :raises: KeyError, ValueError
 
   a = {'hello': 'world!'}
-  a['jello']
+  a['hello']
 
+Additionally, any output sent to the ``stderr`` stream of a cell will result in jupyter-sphinx
+raising an exception. This behaviour can be suppressed (and the ``stderr`` stream printed as regular
+output) by providing the ``stderr`` option::
+
+  .. jupyter-execute::
+      :stderr:
+
+      import sys
+
+      print("hello, world!", file=sys.stderr)
+
+produces:
+
+.. jupyter-execute::
+    :stderr:
+
+    import sys
+
+    print("hello, world!", file=sys.stderr)
+
+.. warning::
+
+    Note that output written to ``stderr`` is not displayed any differently than output written
+    to ``stdout``.
 
 Controlling the execution environment
 -------------------------------------

jupyter_sphinx/execute.py

@@ -147,6 +147,7 @@ class JupyterCell(Directive):
         'hide-output': directives.flag,
         'code-below': directives.flag,
         'raises': csv_option,
+        'stderr': directives.flag,
     }
 
     def run(self):
@@ -180,6 +181,7 @@ def run(self):
             hide_output=('hide-output' in self.options),
             code_below=('code-below' in self.options),
             raises=self.options.get('raises'),
+            stderr=('stderr' in self.options),
         )]
 
 
@@ -291,6 +293,15 @@ def apply(self):
                     raise ExtensionError('Cell raised uncaught exception:\n{}'
                                          .format('\n'.join(errors[0]['traceback'])))
 
+            # Raise error if cells print to stderr
+            for node, cell in zip(nodes, notebook.cells):
+                stderr = [output for output in cell.outputs
+                          if output['output_type'] == 'stream'
+                             and output['name'] == 'stderr']
+                if stderr and not node.attributes['stderr']:
+                    raise ExtensionError('Cell printed to stderr:\n{}'
+                                         .format(stderr[0]['text']))
+
             # Highlight the code cells now that we know what language they are
             for node in nodes:
                 source = node.children[0]
@@ -379,7 +390,6 @@ def cell_output_to_nodes(cell, data_priority, dir):
         output_type = output['output_type']
         if (
             output_type == 'stream'
-            and output['name'] == 'stdout'
         ):
             to_add.append(docutils.nodes.literal_block(
                 text=output['text'],

tests/test_execute.py

@@ -155,7 +155,7 @@ def test_raises(doctree):
     '''
     tree = doctree(source)
     cell, = tree.traverse(JupyterCellNode)
-    'ValueError' in cell.children[1].rawsource
+    assert 'ValueError' in cell.children[1].rawsource
 
     source = '''
     .. jupyter-execute::
@@ -165,7 +165,7 @@ def test_raises(doctree):
     '''
     tree = doctree(source)
     cell, = tree.traverse(JupyterCellNode)
-    'ValueError' in cell.children[1].rawsource
+    assert 'ValueError' in cell.children[1].rawsource
 
 
 def test_widgets(doctree):
@@ -191,3 +191,38 @@ def test_javascript(doctree):
     node, = list(tree.traverse(raw))
     text, = node.children
     assert 'world' in text
+
+
+def test_stdout(doctree):
+    source = """
+    .. jupyter-execute::
+
+        print('hello world')
+    """
+    tree = doctree(source)
+    cell, = tree.traverse(JupyterCellNode)
+    assert len(cell.children) == 2
+    assert cell.children[1].rawsource.strip() == "hello world"
+
+
+def test_stderr(doctree):
+    source = """
+    .. jupyter-execute::
+
+        import sys
+        print('hello world', file=sys.stderr)
+    """
+    with pytest.raises(ExtensionError):
+        tree = doctree(source)
+
+    source = """
+    .. jupyter-execute::
+        :stderr:
+
+        import sys
+        print('hello world', file=sys.stderr)
+    """
+    tree = doctree(source)
+    cell, = tree.traverse(JupyterCellNode)
+    assert len(cell.children) == 2
+    assert cell.children[1].rawsource.strip() == "hello world"