release 0.6.10

* added documentation for interactive mode and captured out filter
* updated history
* changed version number

HISTORY.rst

@@ -1,11 +1,17 @@
 Release History
 ---------------
 
-0.6.10 (2016-??-??)
+0.6.10 (2016-08-08)
 +++++++++++++++++++
 * Bugfix: fixed a problem when trying  to set the loglevel to DEBUG
+* Bugfix: fixed a random crash of the heartbeat thread (see #101).
+* Feature: added --force/-f option to disable errors and warnings concerning
+           suspicious changes. (thanks to Yannic Kilcher)
 * Feature: experiments can now be run in Jupyter notebook, but will fail with
            an error by default, which can be deactivated using interactive=True
+* Feature: added support for adding a captured out filter, and a filter that
+           and applies backspaces and linefeeds before saving like a terminal
+           would. (thanks to Kevin McGuinness)
 
 0.6.9 (2016-01-16)
 ++++++++++++++++++

docs/conf.py

@@ -32,6 +32,7 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/experiment.rst

@@ -22,7 +22,7 @@ the source-file of the experiment.
 
 Instead of ``@ex.main`` it is recommended to use ``@ex.automain``. This will
 automatically run the experiment if you execute the file. It is equivalent to
-the following.
+the following:
 
 .. code-block:: python
 
@@ -59,6 +59,20 @@ it from there an run it like this:
 
     r = ex.run()
 
+.. warning::
+
+    By default, Sacred experiments **will fail** if run in an interactive
+    environment like a REPL or a Jupyter Notebook.
+    This is an intended security measure since in these environments
+    reproducibility cannot be ensured.
+    If needed, this safeguard can be deactivated by passing
+    ``interactive=True`` to the experiment like this:
+
+     .. code-block:: python
+
+        ex = Experiment('jupyter_ex', interactive=True)
+
+
 The ``run`` function accepts ``config_updates`` to specify how the configuration
 should be changed for this run. It should be (possibly nested) dictionary
 containing all the values that you wish to update. For more information see
@@ -189,6 +203,29 @@ collection called ``experiments``. You can also add this observer from the
 
 For more information see :doc:`observers`
 
+Capturing stdout / stderr
+-------------------------
+By default sacred captures everything that is written to ``sys.stdout`` and
+``sys.stderr`` and transmits that information to the observers.
+Sometimes this is unwanted, for example when the output contains lots of
+live-updated progressbars and such.
+To prevent the captured out from recording each and every update that is
+written to the console one can add a *captured out filter* to the experiment
+like this:
+
+.. code-block:: python
+
+    from sacred.utils import apply_backspaces_and_linefeeds
+
+    ex.captured_out_filter = apply_backspaces_and_linefeeds
+
+Here ``apply_backspaces_and_linefeeds`` is a simple function that interprets
+all backspace and linefeed characters like in a terminal and returns the
+modified text.
+Any function that takes a string as input and outputs a (modified) string can
+be used as a ``captured_out_filter``.
+For a simple example see `examples/captured_out_filter.py <https://github.com/IDSIA/sacred/tree/master/examples/captured_out_filter.py>`_.
+
 
 .. _debugging:
 

sacred/__about__.py

@@ -11,7 +11,7 @@
 
 __all__ = ("__version__", "__author__", "__author_email__", "__url__")
 
-__version__ = "0.6.9"
+__version__ = "0.6.10"
 
 __author__ = 'Klaus Greff'
 __author_email__ = '[email protected]'

tox.ini

@@ -34,7 +34,7 @@ deps =
     mccabe
     flake8-docstrings
 commands =
-    flake8 --max-complexity 8 sacred
+    flake8 --max-complexity 10 sacred
 
 [testenv:coverage]
 passenv = TRAVIS TRAVIS_JOB_ID TRAVIS_BRANCH