added live_output option to display stdout and stderr live in termina…

…l during code execution (#21)

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## v0.5.0 (dev)
 
+* Added `live_output` option for the first code chunk in a session.  This
+  shows code output (stdout and stderr) live in the terminal during code
+  execution (#21).
 * "Includes" are now skipped during internal, intermediate file
   transformations, which prevents duplicated "includes" and associated errors
   (#20).  This applies to `header-includes`, `include-before`,

README.md

@@ -327,6 +327,24 @@ session is in use).
 * `jupyter_timeout`={int} — Jupyter kernel timeout per code chunk in seconds.
   The default is 60.
 
+* `live_output`={`true`, `false`} — Show code output (stdout and stderr) live
+  in the terminal during code execution.  Output still appears in the document
+  as normal.
+
+  All output is written to stderr, so stdout only contains the document when
+  `--output` is not specified.  Output is interspersed with delimiters marking
+  the start of each session and the start of each code chunk.  The delimiters
+  for the start of each code chunk include source names and line numbers.
+
+  The output for a code chunk may be delayed until all code in the chunk has
+  finished executing, unless code output is line buffered or code manually
+  flushes stdout and stderr.  For example, with Python you may want to use
+  print functions like `print("text", flush=True)`.  Another option is to use
+  Python in line-buffered mode by setting `executable="python -u"` or
+  `executable="python3 -u"` in the first code chunk of a session.
+
+  This option currently has no effect for Jupyter kernels.
+
 
 #### Execution
 

codebraid/converters/base.py

@@ -319,7 +319,7 @@ def finalize_after_copy(self):
                             for kw in ('first_number', 'line_numbers', 'rewrap_lines', 'rewrap_width', 'expand_tabs', 'tab_size')])
     _first_chunk_execute_keywords = set(['executable', 'jupyter_kernel'])
     _first_chunk_save_keywords = set(['save', 'save_as'])
-    _first_chunk_other_keywords = set(['jupyter_timeout'])
+    _first_chunk_other_keywords = set(['jupyter_timeout', 'live_output'])
     _first_chunk_keywords = _first_chunk_execute_keywords | _first_chunk_save_keywords | _first_chunk_other_keywords
 
     keywords = _base_keywords | _layout_keywords | _first_chunk_keywords
@@ -432,6 +432,7 @@ def _option_first_chunk_int_warning(self, key, value):
     _option_jupyter_timeout = _option_first_chunk_int_warning
     _option_save = _option_first_chunk_bool_error
     _option_save_as = _option_first_chunk_string_error
+    _option_live_output = _option_first_chunk_bool_error
 
     _option_example = _option_bool_warning
     _option_lang = _option_str_error

codebraid/converters/pandoc.py

@@ -187,6 +187,7 @@ def keyval_namespace(code_chunk, options, key, value):
                                     'jupyter_timeout': keyval_int,
                                     **line_anchors,
                                     **line_numbers,
+                                    'live_output': keyval_bool,
                                     'name': keyval_generic,
                                     'outside_main': keyval_bool,
                                     **rewrap_lines,

codebraid/languages/python.bespon

@@ -18,7 +18,7 @@ source_template =
 chunk_wrapper =
     |```
     print('\n{stdout_delim}', flush=True)
-    sys.stderr.write('\n{stderr_delim}\n')
+    print('\n{stderr_delim}', file=sys.stderr, flush=True)
     {code}
     |```/
 

codebraid/version.py

@@ -1,4 +1,4 @@
 # -*- coding: utf-8 -*-
 
 from .fmtversion import get_version_plus_info
-__version__, __version_info__ = get_version_plus_info(0, 5, 0, 'dev', 7)
+__version__, __version_info__ = get_version_plus_info(0, 5, 0, 'dev', 8)