:mod:`xdoctest.utils.util_stream`
=================================

.. py:module:: xdoctest.utils.util_stream

.. autoapi-nested-parse::

   Functions for capturing and redirecting IO streams.

   The :class:`CaptureStdout` captures all text sent to stdout and optionally
   prevents it from actually reaching stdout.

   The :class:`TeeStringIO` does the same thing but for arbitrary streams. It is
   how the former is implemented.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   xdoctest.utils.util_stream.TeeStringIO
   xdoctest.utils.util_stream.CaptureStream
   xdoctest.utils.util_stream.CaptureStdout



.. py:class:: TeeStringIO(redirect=None)

   Bases: :class:`io.StringIO`

   An IO object that writes to itself and another IO stream.

   :ivar redirect: The other stream to write to.

   :vartype redirect: io.IOBase

   .. rubric:: Example

   >>> redirect = io.StringIO()
   >>> self = TeeStringIO(redirect)

   .. method:: isatty(self)


      Returns true of the redirect is a terminal.

      .. rubric:: Notes

      Needed for IPython.embed to work properly when this class is used
      to override stdout / stderr.


   .. method:: fileno(self)


      Returns underlying file descriptor of the redirected IOBase object
      if one exists.


   .. method:: encoding(self)
      :property:


      Gets the encoding of the `redirect` IO object

      .. rubric:: Example

      >>> redirect = io.StringIO()
      >>> assert TeeStringIO(redirect).encoding is None
      >>> assert TeeStringIO(None).encoding is None
      >>> assert TeeStringIO(sys.stdout).encoding is sys.stdout.encoding
      >>> redirect = io.TextIOWrapper(io.StringIO())
      >>> assert TeeStringIO(redirect).encoding is redirect.encoding


   .. method:: write(self, msg)


      Write to this and the redirected stream


   .. method:: flush(self)


      Flush to this and the redirected stream



.. py:class:: CaptureStream

   Bases: :class:`object`

   Generic class for capturing streaming output from stdout or stderr


.. py:class:: CaptureStdout(supress=True, enabled=True)

   Bases: :class:`xdoctest.utils.util_stream.CaptureStream`

   Context manager that captures stdout and stores it in an internal stream

   :Parameters: * **supress** (*bool, default=True*) -- if True, stdout is not printed while captured
                * **enabled** (*bool, default=True*) -- does nothing if this is False

   .. rubric:: Example

   >>> self = CaptureStdout(supress=True)
   >>> print('dont capture the table flip (╯°□°）╯︵ ┻━┻')
   >>> with self:
   ...     text = 'capture the heart ♥'
   ...     print(text)
   >>> print('dont capture look of disapproval ಠ_ಠ')
   >>> assert isinstance(self.text, six.text_type)
   >>> assert self.text == text + '\n', 'failed capture text'

   .. rubric:: Example

   >>> self = CaptureStdout(supress=False)
   >>> with self:
   ...     print('I am captured and printed in stdout')
   >>> assert self.text.strip() == 'I am captured and printed in stdout'

   .. rubric:: Example

   >>> self = CaptureStdout(supress=True, enabled=False)
   >>> with self:
   ...     print('dont capture')
   >>> assert self.text is None

   .. method:: log_part(self)


      Log what has been captured so far


   .. method:: start(self)



   .. method:: stop(self)


      .. rubric:: Example

      >>> CaptureStdout(enabled=False).stop()
      >>> CaptureStdout(enabled=True).stop()


   .. method:: __enter__(self)



   .. method:: __del__(self)



   .. method:: close(self)



   .. method:: __exit__(self, type_, value, trace)




