testsuite.utils
===============

.. py:module:: testsuite.utils

.. autoapi-nested-parse::

   Miscellaneous helpers.



Attributes
----------

.. autoapisummary::

   testsuite.utils.EnumType


Classes
-------

.. autoapisummary::

   testsuite.utils.DummyColors
   testsuite.utils.ColorConfig
   testsuite.utils.CleanupMode


Functions
---------

.. autoapisummary::

   testsuite.utils.isatty
   testsuite.utils.enum_to_cmdline_args_map
   testsuite.utils.dump_environ
   testsuite.utils.indent
   testsuite.utils.safe_dir_walk


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

.. py:function:: isatty(stream: IO[AnyStr]) -> bool

   Return whether stream is a TTY.

   This is a safe predicate: it works if stream is None or if it does not even
   support TTY detection: in these cases, be conservative (consider it's not a
   TTY).


.. py:class:: DummyColors

   Stub to replace colorama's Fore/Style when colors are disabled.


   .. py:method:: __getattr__(name: str) -> str


.. py:class:: ColorConfig(colors_enabled: Optional[bool] = None)

   Proxy for color management.

   This embeds colorama's Fore/Style, or DummyColors instances when colors are
   disabled.


   .. py:attribute:: Fore
      :type:  colorama.ansi.AnsiFore | DummyColors


   .. py:attribute:: Style
      :type:  colorama.ansi.AnsiStyle | DummyColors


.. py:class:: CleanupMode(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Mode for working space cleanups.


   .. py:attribute:: NONE


   .. py:attribute:: PASSING


   .. py:attribute:: ALL


   .. py:method:: default() -> CleanupMode
      :classmethod:



   .. py:method:: descriptions() -> Dict[CleanupMode, str]
      :classmethod:



.. py:data:: EnumType

.. py:function:: enum_to_cmdline_args_map(enum_cls: Type[EnumType]) -> Dict[str, EnumType]

   Turn enum alternatives into command-line arguments.

   This helps exposing enums for options on the command-line. This turns
   alternative names into lower case and replaces underscores with dashes.


.. py:function:: dump_environ(filename: str, env: e3.env.Env) -> None

   Dump environment variables into a sourceable file.


.. py:function:: indent(text: str, prefix: str = '  ') -> str

   Prepend ``prefix`` to every line in ``text``.

   :param text: Text to transform.
   :param prefix: String to prepend.


.. py:function:: safe_dir_walk(top: str) -> Iterator[tuple[str, list[str], list[str]]]

   Traverse a directory hierarchy following symlinks in a safe way.

   This is essentially a wrapper around os.walk() to safely follow symbolic
   links that keeps track of the directories traversed to avoid infinite
   recursion in case of symbolic link loops.