Capture stdout and stderr with the CaptureManager. (#35)

Author: tobiasraabe

.pre-commit-config.yaml

@@ -3,7 +3,7 @@ repos:
     rev: v3.2.0
     hooks:
     -   id: check-added-large-files
-        args: ['--maxkb=10']
+        args: ['--maxkb=25']
     -   id: check-merge-conflict
     -   id: check-yaml
         exclude: meta.yaml

docs/changes.rst

@@ -13,6 +13,7 @@ all releases are available on `Anaconda.org <https://anaconda.org/pytask/pytask>
 - :gh:`32` fixes ``pytask clean``.
 - :gh:`33` adds a module to apply common parameters to the command line interface.
 - :gh:`34` skips ``pytask_collect_task_teardown`` if task is None.
+- :gh:`35` adds the ability to capture stdout and stderr with the CaptureManager.
 
 
 0.0.8 - 2020-10-04

docs/explanations/why_another_build_system.rst

@@ -5,27 +5,20 @@ There are a lot of build systems out there with existing communities who accumul
 lot of experience over time. So why go through the hassle of creating another build
 system?
 
-One reason was pure curiosity. `Waf <https://waf.io>`_ has been used for some time as a
-build system for research projects. Although, it has several limitations (difficult
-interface, no debugging, cryptic error messages, a bus factor of one), it is also a
-mature library. At some point annoyance won over comfort and I (`@tobiasraabe
-<https://github.com/tobiasraabe>`_) started to write pytask.
-
-Another reason is that pytask is created having a particular audience in mind. Many
-researchers are not computer scientists first, but acquired some programming skills
-throughout their careers. This means a build system must be extremely user-friendly or
-provide a `steep learning curve <https://english.stackexchange.com/a/6226>`_, because it
-is only a tool. Since pytask resembles pytest in some ways, users have an easier time
-switching to pytask and feel more comfortable.
-
-The third reason is that pytest seems to provide the ideal architecture for a build
+pytask is created having a particular audience in mind. Many researchers are not
+computer scientists first, but acquired some programming skills throughout their
+careers. This means a build system must be extremely user-friendly or provide a `steep
+learning curve <https://english.stackexchange.com/a/6226>`_, because it is only a tool.
+Since pytask resembles pytest in some ways, users have an easier time switching to
+pytask and feel more comfortable.
+
+The second reason is that pytest seems to provide the ideal architecture for a build
 system. Its plugin-based design allows for customization at every level. A build system
 is a tool which can be deployed in many different environments whose requirements are
 not foreseeable by the developer. If it is easy for users / developers to write plugins
 which extend the functionality of pytask it is more valuable. If there is any question
 whether pytest's architecture is really suited for this, one should look at the success
-of pytest, its wide-spread adoption, and its over 800 plugins (even if most of them
-might be dead).
+of pytest, its wide-spread adoption, and its over 800 plugins.
 
 
 Alternatives

docs/tutorials/how_to_capture.rst

@@ -0,0 +1,88 @@
+How to capture
+==============
+
+Default stdout/stderr/stdin capturing behavior
+----------------------------------------------
+
+During task execution any output sent to ``stdout`` and ``stderr`` is captured.  If a
+task its according captured output will usually be shown along with the failure
+traceback.
+
+In addition, ``stdin`` is set to a "null" object which will fail on attempts to read
+from it because it is rarely desired to wait for interactive input when running
+automated tasks.
+
+By default capturing is done by intercepting writes to low level file descriptors. This
+allows to capture output from simple print statements as well as output from a
+subprocess started by a task.
+
+
+Setting capturing methods or disabling capturing
+------------------------------------------------
+
+There are three ways in which ``pytask`` can perform capturing:
+
+* ``fd`` (file descriptor) level capturing (default): All writes going to the operating
+  system file descriptors 1 and 2 will be captured.
+
+* ``sys`` level capturing: Only writes to Python files ``sys.stdout`` and ``sys.stderr``
+  will be captured.  No capturing of writes to file descriptors is performed.
+
+* ``tee-sys`` capturing: Python writes to ``sys.stdout`` and ``sys.stderr`` will be
+  captured, however the writes will also be passed-through to the actual ``sys.stdout``
+  and ``sys.stderr``.
+
+You can influence output capturing mechanisms from the command line:
+
+.. code-block:: console
+
+    pytask -s                  # disable all capturing
+    pytask --capture=sys       # replace sys.stdout/stderr with in-mem files
+    pytask --capture=fd        # also point filedescriptors 1 and 2 to temp file
+    pytask --capture=tee-sys   # combines 'sys' and '-s', capturing sys.stdout/stderr
+                               # and passing it along to the actual sys.stdout/stderr
+
+
+Using print statements for debugging
+------------------------------------
+
+One primary benefit of the default capturing of stdout/stderr output is that you can use
+print statements for debugging:
+
+.. code-block:: python
+
+    # content of task_capture.py
+
+
+    def task_func1():
+        assert True
+
+
+    def task_func2():
+        print("Debug statement")
+        assert False
+
+and running this module will show you precisely the output of the failing function and
+hide the other one:
+
+.. code-block:: console
+
+    $ pytask -s
+    ========================= Start pytask session =========================
+    Platform: win32 -- Python 3.x.x, pytask 0.x.x, pluggy 0.13.x
+    Root: .
+    Collected 2 task(s).
+
+    F.
+    =============================== Failures ===============================
+    _________________ Task task_capture.py::task_func2 failed ______________
+
+    Traceback (most recent call last):
+      File "task_capture.py", line 7, in task_func2
+        assert False
+    AssertionError
+
+    ---------------------- Captured stdout during call ---------------------
+    Debug statement.
+
+    ==================== 1 succeeded, 1 failed in 0.01s ====================

docs/tutorials/index.rst

@@ -18,3 +18,4 @@ organize and start your own project.
    how_to_clean
    how_to_collect
    how_to_make_tasks_persist
+   how_to_capture