===========
ui.terminal
===========

.. toctree::
   :hidden:



.. index:: ui.terminal
.. module:: ui.terminal
   :noindex:

Terminal output support.


Module Members
==============

| :class:`~OutputAdaptor`
| :class:`~Terminal`


Classes
-------


.. class:: OutputAdaptor(f)

   Adaptor for terminal or file outputs.

   For objects like :class:`TermOutput` this is a transparent proxy. For
   objects like ``sys.stdout`` it redirects calls to :meth:`addstr` to
   the ``write`` method.


.. property:: columns
   :noindex:

   The number of columns on the output.

   This defaults to 80 if the adapted class does not have a colums
   attribute.


   .. method:: addstr(text, style=None)
      :noindex:

      Add text to the output.

      If the adapted output object provides and ``addstr`` method then it is
      invoked. Otherwise the object's ``write`` method ic called. See
      :meth:`TermOutput.addstr` for argument details.


.. class:: Terminal(\*\*kwargs)

   A reporter that outputs to a simple (not curses based) terminal.

   This will produce colored output if possible, but assumes the output
   otherwise goes to a simple scrolling terminal.


   **Arguments**

     width
       The width to assume for formatting the output. This can be
       modified by the :meth:`setWidth` method.

   .. graphviz::

         digraph foo {
         rankdir=BT;
         ranksep=0.3;
         node[fontsize=10 margin=0.01 height=0.2 width=0.4];
         edge[arrowsize=0.6 arrowhead=onormal];
         "cstest.ui.terminal.Terminal" [color=blue height=0.4 width=0.6];
             "cstest.ui.terminal.Terminal" -> "cstest.ui.format.TestAnnouncer";
             "cstest.ui.terminal.Terminal" -> "cstest.core.reporting.WriteBuffer";
             "cstest.ui.terminal.Terminal" -> "cstest.services.api.Reporter";
         }

   Base classes: cstest.ui.format.TestAnnouncer cstest.core.reporting.WriteBuffer cstest.services.api.Reporter


.. property:: _pad
   :noindex:

   Leading spaces used to indent output.


   .. method:: endTest(suite, test, status)
      :noindex:

      Invoked when a test has completed without any errors.

      This is invoked before :meth:`leaveTest`.


      **Arguments**

        *suite*, *test*
          The test just executed and its parent suite.

        *status*
          A :class:`Status` instance. Its value will typically be 'PASS' and
          it will not carry any run-time exception information.

   .. method:: enterSuite(suite, test)
      :noindex:

      Invoked when a suite is about to be 'entered'.

      This is invoked when a test is about to be run and no previous test has
      been executed or the previous test is in a different suite. Since
      suites may be nested, this may be invoked more than one before the test
      is invoked.


      **Arguments**

        *suite*, *test*
          The suite being entered and the test that is going to be run. The
          test is not necessarily an immediate member of the suite; the suite
          may be the test's grandparent, great-grandparent suite, *etc*.

   .. method:: enterTest(suite, test)
      :noindex:

      Invoked to indicate that 'test-mode' is being entered.

      This is invoked immediately before the test method is invoked.
      Typical uses for this are to adjust the indentation level for future
      output and to announce that the test is starting.


      **Arguments**

        *suite*, *test*
          The test being executed and its parent suite.

   .. method:: flush()
      :noindex:

      Flush all buffered styled-text.


   .. method:: leaveSuite(suite, test)
      :noindex:

      Invoked when a suite has been 'left'.

      This is pretty much the inverse of :meth:`enterSuite`. Calls to this
      are triggered when the next test to executed is in a differetn suite or
      no further tests are left.


      **Arguments**

        *suite*, *test*
          The suite that has been left and an 'associated' test. The test
          parameter is probably not os much use. It exists primarily to make
          the signature match :meth:`enterSuite`, :meth:`enterTest`, *etc*.
          Normall the test is the next test that will be executed, but when
          not test remain to be executed it will be the last test that was
          invoked.

   .. method:: leaveTest(suite, test)
      :noindex:

      Invoked to indicate that 'test-mode' has been left.

      This is invoked after the test's result and any errors have beeb
      reported.


      **Arguments**

        *suite*, *test*
          The test just executed and its parent suite.

   .. method:: reportFixtureFailure(suite, test, problemReport)
      :noindex:

      Invoked when a fixture function terminated with an error.

      This is invoked when any setUp, tearDown, suiteSetUp or suiteTearDown
      method raises any unhandled exception.


      **Arguments**

        *suite*, *test*
          The test just executed and its parent suite.

        *problemReport*
          TODO.

   .. method:: reportTestFailure(suite, test, problemReport)
      :noindex:

      Invoked when a test has terminated with an error.

      This is invoked before :meth:`leaveTest`.


      **Arguments**

        *suite*, *test*
          The test just executed and its parent suite.

        *problemReport*
          TODO.