PR: Implement Support to Load Environment Variables from File

colour/__init__.py

@@ -45,11 +45,30 @@
 """
 
 import contextlib
+import json
 import os
 import sys
 
 import numpy as np
 
+# Loading the "colour-science" JEnv file.
+_JENV_FILE_PATH = os.path.join(
+    os.path.expanduser("~"),
+    ".colour-science",
+    "colour-science.jenv",
+)
+
+if os.path.exists(_JENV_FILE_PATH):
+    with open(_JENV_FILE_PATH) as _JENV_FILE:
+        for _KEY, _VALUE in json.loads(_JENV_FILE.read()).items():
+            os.environ[_KEY] = str(_VALUE)
+
+    del _JENV_FILE, _KEY, _VALUE
+
+del _JENV_FILE_PATH
+
+# ruff: noqa: E402
+
 from colour import plotting  # noqa: F401
 
 from .adaptation import (

colour/utilities/__init__.py

@@ -42,6 +42,7 @@
     is_trimesh_installed,
     is_xxhash_installed,
     required,
+    as_bool,
     is_iterable,
     is_string,
     is_numeric,
@@ -170,6 +171,7 @@
     "is_trimesh_installed",
     "is_xxhash_installed",
     "required",
+    "as_bool",
     "is_iterable",
     "is_string",
     "is_numeric",

colour/utilities/common.py

@@ -80,6 +80,7 @@
     "is_trimesh_installed",
     "is_xxhash_installed",
     "required",
+    "as_bool",
     "is_iterable",
     "is_string",
     "is_numeric",
@@ -96,7 +97,7 @@
 ]
 
 _CACHING_ENABLED: bool = not os.environ.get(
-    "COLOUR_SCIENCE__COLOUR__DISABLE_CACHING", False
+    "COLOUR_SCIENCE__DISABLE_CACHING", False
 )
 """
 Global variable storing the current *Colour* caching enabled state.
@@ -1090,6 +1091,41 @@ def wrapped(*args: Any, **kwargs: Any) -> Any:
     return wrapper
 
 
+def as_bool(a: str) -> bool:
+    """
+    Convert given string to bool.
+
+    The following string values evaluate to *True*: "1", "On", and "True".
+
+    Parameters
+    ----------
+    a
+        String to convert to bool.
+
+    Returns
+    -------
+    :class:`bool`
+        Whether the given string is *True*.
+
+    Examples
+    --------
+    >>> as_bool("1")
+    True
+    >>> as_bool("On")
+    True
+    >>> as_bool("True")
+    True
+    >>> as_bool("0")
+    False
+    >>> as_bool("Off")
+    False
+    >>> as_bool("False")
+    False
+    """
+
+    return a.lower() in ["1", "on", "true"]
+
+
 def is_iterable(a: Any) -> bool:
     """
     Return whether given variable :math:`a` is iterable.

colour/utilities/tests/test_common.py

@@ -14,6 +14,7 @@
 from colour.utilities import (
     CacheRegistry,
     CanonicalMapping,
+    as_bool,
     attest,
     batch,
     caching_enable,
@@ -49,6 +50,7 @@
     "TestAttest",
     "TestBatch",
     "TestMultiprocessingPool",
+    "TestAsBool",
     "TestIsIterable",
     "TestIsString",
     "TestIsNumeric",
@@ -311,6 +313,30 @@ def test_multiprocessing_pool(self):
             )
 
 
+class TestAsBool(unittest.TestCase):
+    """
+    Define :func:`colour.utilities.common.as_bool` definition unit tests
+    methods.
+    """
+
+    def test_as_bool(self):
+        """Test :func:`colour.utilities.common.as_bool` definition."""
+
+        self.assertTrue(as_bool("1"))
+
+        self.assertTrue(as_bool("On"))
+
+        self.assertTrue(as_bool("True"))
+
+        self.assertFalse(as_bool("0"))
+
+        self.assertFalse(as_bool("Off"))
+
+        self.assertFalse(as_bool("False"))
+
+        self.assertFalse(as_bool(""))
+
+
 class TestIsIterable(unittest.TestCase):
     """
     Define :func:`colour.utilities.common.is_iterable` definition unit tests

colour/utilities/verbose.py

@@ -32,7 +32,7 @@
     Type,
     cast,
 )
-from colour.utilities import is_string, optional
+from colour.utilities import as_bool, is_string, optional
 
 __author__ = "Colour Developers"
 __copyright__ = "Copyright 2013 Colour Developers"
@@ -341,7 +341,7 @@ def filter_warnings(
         Whether to filter *Colour* warnings, this also filters *Colour* usage
         and runtime warnings according to the action value.
     python_warnings
-        Whether to filter *Python* warnings  according to the action value.
+        Whether to filter *Python* warnings according to the action value.
 
     Examples
     --------
@@ -392,7 +392,38 @@ def filter_warnings(
 
 
 # Defaulting to filter *Colour* runtime warnings.
-filter_warnings(colour_runtime_warnings=True)
+filter_warnings(
+    colour_runtime_warnings=as_bool(
+        os.environ.get("COLOUR_SCIENCE__FILTER_RUNTIME_WARNINGS", "True")
+    )
+)
+
+if (
+    os.environ.get("COLOUR_SCIENCE__FILTER_USAGE_WARNINGS") is not None
+):  # pragma: no cover
+    filter_warnings(
+        colour_usage_warnings=as_bool(
+            os.environ["COLOUR_SCIENCE__FILTER_USAGE_WARNINGS"]
+        )
+    )
+
+if (
+    os.environ.get("COLOUR_SCIENCE__FILTER_COLOUR_WARNINGS") is not None
+):  # pragma: no cover
+    filter_warnings(
+        colour_usage_warnings=as_bool(
+            os.environ["COLOUR_SCIENCE__FILTER_WARNINGS"],
+        )
+    )
+
+if (
+    os.environ.get("COLOUR_SCIENCE__FILTER_PYTHON_WARNINGS") is not None
+):  # pragma: no cover
+    filter_warnings(
+        colour_usage_warnings=as_bool(
+            os.environ["COLOUR_SCIENCE__FILTER_PYTHON_WARNINGS"]
+        )
+    )
 
 
 @contextmanager

docs/advanced.rst

@@ -1,5 +1,5 @@
-Advanced Concepts
-=================
+Advanced Usage
+==============
 
 This page describes some advanced usage scenarios of **Colour**.
 
@@ -18,8 +18,8 @@ runtime:
     `float64` (default). Changing the float dtype might result in various
     **Colour** `functionality breaking entirely <https://github.com/numpy/numpy/issues/6860>`__.
     *With great power comes great responsibility*.
--   ``COLOUR_SCIENCE__COLOUR__DISABLE_CACHING``: Disable the caches that can
-    be disabled, useful for debugging purposes.
+-   ``COLOUR_SCIENCE__DISABLE_CACHING``: Disable the caches that can be
+    disabled, useful for debugging purposes.
 -   ``COLOUR_SCIENCE__COLOUR__IMPORT_VAAB_COLOUR``: Import
     `vaab/colour <https://github.com/vaab/colour>`__ injection into
     **Colour** namespace. This solves the clash with
@@ -29,6 +29,25 @@ runtime:
     :func:`warnings.showwarning` definition to be replaced with the
     :func:`colour.utilities.show_warning` definition and thus providing
     complete traceback from the point where the warning occurred.
+-   ``COLOUR_SCIENCE__FILTER_RUNTIME_WARNINGS``: Filter *Colour* runtime
+    warnings.
+-   ``COLOUR_SCIENCE__FILTER_USAGE_WARNINGS``: Filter *Colour* usage warnings.
+-   ``COLOUR_SCIENCE__FILTER_COLOUR_WARNINGS``: Filter *Colour* warnings, this
+    also filters *Colour* usage and runtime warnings.
+-   ``COLOUR_SCIENCE__FILTER_PYTHON_WARNINGS``: Filter *Python* warnings.
+
+JEnv File
+---------
+
+**Colour** will also read the ``~/.colour-science/colour-science.jenv`` JSON
+file if it exists. The syntax is that of a mapping of environment variable and
+values as follows:
+
+.. code-block:: json
+
+    {
+      "COLOUR_SCIENCE__COLOUR__SHOW_WARNINGS_WITH_TRACEBACK": "True"
+    }
 
 Caching
 -------

docs/basics.rst

@@ -1,5 +1,5 @@
-Basic Concepts
-==============
+Basic Usage
+===========
 
 This page puts an emphasis on basic concepts of **Colour**, those are important
 to understand.

docs/colour.utilities.rst

@@ -73,6 +73,7 @@ Common
     is_trimesh_installed
     is_xxhash_installed
     required
+    as_bool
     is_iterable
     is_string
     is_numeric