Cease all use of Colorama on non-Windows systems. (#345)

coredumperror · hynek · web-flow · commit d20fd093432a · 2021-08-11T06:30:29.000+02:00
* Color codes are no longer defined as empty if colorama isn't installed.

* Removed all use of colorama on non-Windows systems.

* Updated the changelog.

* Fixes suggested by hynek

* Add pragma: no cover to if _IS_WINDOWS: check.

Co-authored-by: Hynek Schlawack &lt;hs@ox.cx&gt;

Co-authored-by: Hynek Schlawack &lt;hs@ox.cx&gt;
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -34,7 +34,8 @@ Changes:
   This only works if ``format_exc_info`` is **absent** in the processor chain.
 - ``structlog.threadlocal.get_threadlocal()`` and ``structlog.contextvars.get_threadlocal()`` can now be used to get a copy of the current thread-local/context-local context that has been bound using ``structlog.threadlocal.bind_threadlocal()`` and ``structlog.contextvars.bind_contextvars()``.
 - ``structlog.threadlocal.get_merged_threadlocal(bl)`` and ``structlog.contextvars.get_merged_contextvars(bl)`` do the same, but also merge the context from a bound logger *bl*.
-
+- All use of ``colorama`` on non-Windows systems has been excised.
+  Colors will now be enabled by default on non-Windows systems even if colorama is not installed, as it's not necessary on such systems.
 
 ----
 
diff --git a/docs/development.rst b/docs/development.rst
@@ -3,7 +3,7 @@ Development
 
 To make development a more pleasurable experience, ``structlog`` comes with the `structlog.dev` module.
 
-The highlight is `structlog.dev.ConsoleRenderer` that offers nicely aligned and colorful (requires the `colorama package <https://pypi.org/project/colorama/>`_ installed) console output.
+The highlight is `structlog.dev.ConsoleRenderer` that offers nicely aligned and colorful (requires the `colorama package <https://pypi.org/project/colorama/>`_ if on Windows) console output.
 If the `better-exceptions <https://github.com/Qix-/better-exceptions>`_ package is installed, it will also pretty-print exceptions with helpful contextual data.
 
 .. figure:: _static/console_renderer.png
diff --git a/docs/getting-started.rst b/docs/getting-started.rst
@@ -34,7 +34,8 @@ Here, ``structlog`` takes full advantage of its hopefully useful default setting
 - All keywords are formatted using `structlog.dev.ConsoleRenderer`.
   That in turn uses `repr` to serialize all values to strings.
   Thus, it's easy to add support for logging of your own objects\ [*]_.
-- If you have `colorama <https://pypi.org/project/colorama/>`_ installed, it's rendered in nice `colors <development>`.
+- On Windows, if you have `colorama <https://pypi.org/project/colorama/>`_ installed, it's rendered in nice `colors <development>`.
+  Other OSes do not need colorama for nice colors.
 - If you have `better-exceptions <https://github.com/qix-/better-exceptions>`_ installed, exceptions will be rendered in colors and with additional helpful information.
 
 It should be noted that even in most complex logging setups the example would still look just like that thanks to `configuration`.
diff --git a/src/structlog/_config.py b/src/structlog/_config.py
@@ -23,7 +23,7 @@
 
 from ._log_levels import make_filtering_bound_logger
 from ._loggers import PrintLoggerFactory
-from .dev import ConsoleRenderer, _has_colorama, set_exc_info
+from .dev import ConsoleRenderer, _use_colors, set_exc_info
 from .processors import StackInfoRenderer, TimeStamper, add_log_level
 from .types import BindableLogger, Context, Processor, WrappedLogger
 
@@ -39,7 +39,7 @@
     set_exc_info,
     TimeStamper(fmt="%Y-%m-%d %H:%M.%S", utc=False),
     ConsoleRenderer(
-        colors=_has_colorama and sys.stdout is not None and sys.stdout.isatty()
+        colors=_use_colors and sys.stdout is not None and sys.stdout.isatty()
     ),
 ]
 _BUILTIN_DEFAULT_CONTEXT_CLASS = cast(Type[Context], dict)
diff --git a/src/structlog/dev.py b/src/structlog/dev.py
@@ -47,8 +47,6 @@ def _pad(s: str, length: int) -> str:
 
 
 if colorama is not None:
-    _has_colorama = True
-
     RESET_ALL = colorama.Style.RESET_ALL
     BRIGHT = colorama.Style.BRIGHT
     DIM = colorama.Style.DIM
@@ -60,11 +58,27 @@ def _pad(s: str, length: int) -> str:
     GREEN = colorama.Fore.GREEN
     RED_BACK = colorama.Back.RED
 else:
-    _has_colorama = False
-
-    RESET_ALL = (
-        BRIGHT
-    ) = DIM = RED = BLUE = CYAN = MAGENTA = YELLOW = GREEN = RED_BACK = ""
+    # These are the same values as the colorama color codes. Redefining them
+    # here allows users to specify that they want color without having to
+    # install colorama, which is only supposed to be necessary in Windows.
+    RESET_ALL = "\033[0m"
+    BRIGHT = "\033[1m"
+    DIM = "\033[2m"
+    RED = "\033[31m"
+    BLUE = "\033[34m"
+    CYAN = "\033[36m"
+    MAGENTA = "\033[35m"
+    YELLOW = "\033[33m"
+    GREEN = "\033[32m"
+    RED_BACK = "\033[41m"
+
+
+if _IS_WINDOWS:  # pragma: no cover
+    # On Windows, use colors by default only if colorama is installed.
+    _use_colors = colorama is not None
+else:
+    # On other OSes, use colors by default.
+    _use_colors = True
 
 
 class _Styles(Protocol):
@@ -174,34 +188,39 @@ class ConsoleRenderer:
        `structlog.processors.format_exc_info` processor together with
        `ConsoleRenderer` anymore! It will keep working, but you can't have
        pretty exceptions and a warning will be raised if you ask for them.
+    .. versionchanged:: 21.3 The colors keyword now defaults to True on
+       non-Windows systems, and either True or False in Windows depending on
+       whether colorama is installed.
     """
 
     def __init__(
         self,
         pad_event: int = _EVENT_WIDTH,
-        colors: bool = _has_colorama,
+        colors: bool = _use_colors,
         force_colors: bool = False,
         repr_native_str: bool = False,
         level_styles: Optional[Styles] = None,
         pretty_exceptions: bool = (better_exceptions is not None),
     ):
-        self._force_colors = self._init_colorama = False
         styles: Styles
-        if colors is True:
-            if colorama is None:
-                raise SystemError(
-                    _MISSING.format(
-                        who=self.__class__.__name__ + " with `colors=True`",
-                        package="colorama",
-                    )
-                )
-
+        if colors:
             if _IS_WINDOWS:  # pragma: no cover
-                _init_colorama(self._force_colors)
-            else:
-                self._init_colorama = True
+                # On Windows, we can't do colorful output without colorama.
+                if colorama is None:
+                    classname = self.__class__.__name__
+                    raise SystemError(
+                        _MISSING.format(
+                            who=classname + " with `colors=True`",
+                            package="colorama",
+                        )
+                    )
+                # Colorama must be init'd on Windows, but must NOT be
+                # init'd on other OSes, because it can break colors.
                 if force_colors:
-                    self._force_colors = True
+                    colorama.deinit()
+                    colorama.init(strip=False)
+                else:
+                    colorama.init()
 
             styles = _ColorfulStyles
         else:
@@ -241,10 +260,6 @@ def __call__(
         self, logger: WrappedLogger, name: str, event_dict: EventDict
     ) -> str:
 
-        # Initialize lazily to prevent import side-effects.
-        if self._init_colorama:
-            _init_colorama(self._force_colors)
-            self._init_colorama = False
         sio = StringIO()
 
         ts = event_dict.pop("timestamp", None)
@@ -366,14 +381,6 @@ def get_default_level_styles(colors: bool = True) -> Any:
         }
 
 
-def _init_colorama(force: bool) -> None:
-    if force:
-        colorama.deinit()
-        colorama.init(strip=False)
-    else:
-        colorama.init()
-
-
 _SENTINEL = object()
 
 
diff --git a/tests/test_dev.py b/tests/test_dev.py
@@ -26,7 +26,7 @@ def test_negative(self):
 
 @pytest.fixture(name="cr")
 def _cr():
-    return dev.ConsoleRenderer(colors=dev._has_colorama)
+    return dev.ConsoleRenderer(colors=dev._use_colors)
 
 
 @pytest.fixture(name="styles")
@@ -47,11 +47,14 @@ def _unpadded(styles):
 
 
 class TestConsoleRenderer:
-    @pytest.mark.skipif(dev._has_colorama, reason="Colorama must be missing.")
+    @pytest.mark.skipif(dev.colorama, reason="Colorama must be missing.")
+    @pytest.mark.skipif(
+        not dev._IS_WINDOWS, reason="Must be running on Windows."
+    )
     def test_missing_colorama(self):
         """
         ConsoleRenderer(colors=True) raises SystemError on initialization if
-        colorama is missing.
+        colorama is missing and _IS_WINDOWS is True.
         """
         with pytest.raises(SystemError) as e:
             dev.ConsoleRenderer(colors=True)
@@ -117,11 +120,11 @@ def test_init_accepts_overriding_levels(self, styles, padded):
         Stdlib levels are rendered aligned, in brackets, and color coded.
         """
         my_styles = dev.ConsoleRenderer.get_default_level_styles(
-            colors=dev._has_colorama
+            colors=dev._use_colors
         )
         my_styles["MY_OH_MY"] = my_styles["critical"]
         cr = dev.ConsoleRenderer(
-            colors=dev._has_colorama, level_styles=my_styles
+            colors=dev._use_colors, level_styles=my_styles
         )
 
         # this would blow up if the level_styles override failed
@@ -234,7 +237,7 @@ def test_pad_event_param(self, styles):
         """
         `pad_event` parameter works.
         """
-        rv = dev.ConsoleRenderer(42, dev._has_colorama)(
+        rv = dev.ConsoleRenderer(42, dev._use_colors)(
             None, None, {"event": "test", "foo": "bar"}
         )
 
@@ -350,7 +353,7 @@ def test_colorama_force_colors(self, styles, padded):
         If force_colors is True, use colors even if the destination is non-tty.
         """
         cr = dev.ConsoleRenderer(
-            colors=dev._has_colorama, force_colors=dev._has_colorama
+            colors=dev._use_colors, force_colors=dev._use_colors
         )
 
         rv = cr(
@@ -374,7 +377,7 @@ def test_colorama_force_colors(self, styles, padded):
             + styles.reset
         ) == rv
 
-        assert not dev._has_colorama or dev._ColorfulStyles is cr._styles
+        assert not dev._use_colors or dev._ColorfulStyles is cr._styles
 
     @pytest.mark.parametrize("rns", [True, False])
     def test_repr_native_str(self, rns):
