Non-blocking IO Streams
=======================

The utility module fussy.nbio provides a basic mechanism to stream data
through a series of processes.

The nbio module allows you to fairly easily create (potentially long)
chains of processes which can all be run in parallel. The pipe internally 
uses non-blocking IO and generators to allow it to prevent buffer full 
deadlocks.

.. doctest::

    >>> from fussy.nbio import Process as P
    >>> import requests
    >>> response = requests.get( 'http://www.vrplumber.com' )
    >>> pipe = response.iter_content | P( 'gzip -c' )
    >>> result = pipe()
    >>> assert result.startswith( '\x1f\x8b' )

Create a process and read output:

.. doctest::

    >>> from fussy.nbio import Process as P
    >>> pipe = P( 'echo "Hello world"' )
    >>> pipe()
    'Hello world\n'

Pipe the output through another process:

.. doctest::

    >>> from fussy.nbio import Process as P
    >>> pipe = P( 'echo "Hello world"' ) | P( 'cat' )
    >>> pipe()
    'Hello world\n'

Pipe a generator into a pipe:

.. doctest::

    >>> from fussy.nbio import Process as P
    >>> def gen():
    ...     for i in range( 20 ):
    ...         yield str(i)
    ... 
    >>> pipe = gen() | P( 'cat' )
    >>> pipe()
    '012345678910111213141516171819'

Pipe a pipe into a function (note: the output also gets added to the pipe's output):

    >>> from fussy.nbio import Process as P
    >>> result = []
    >>> pipe = P( 'echo "Hello world"' ) | result.append
    >>> pipe()
    'Hello world\n'
    >>> result
    ['Hello world\n']

Pipe a pipe to our current stdout:

.. code-block:: python

    >>> from fussy.nbio import Process as P
    >>> pipe = P( 'echo "Hello world"' ) | '-'
    >>> pipe()
    Hello world
    ''

Module: fussy.nbio
------------------

.. automodule:: fussy.nbio
    :members:
    :special-members: