pyglove 0.4.5.dev202501060809__py3-none-any.whl → 0.4.5.dev202501080809__py3-none-any.whl

pyglove/core/utils/__init__.py

@@ -155,5 +155,10 @@ from pyglove.core.utils.error_utils import ErrorInfo
 from pyglove.core.utils.timing import timeit
 from pyglove.core.utils.timing import TimeIt
 
+# Text color.
+from pyglove.core.utils.text_color import colored
+from pyglove.core.utils.text_color import colored_block
+from pyglove.core.utils.text_color import decolor
+
 # pylint: enable=g-importing-member
 # pylint: enable=g-bad-import-order

pyglove/core/utils/text_color.py

@@ -0,0 +1,128 @@
+# Copyright 2025 The PyGlove Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Utility library for text coloring."""
+
+import re
+from typing import List, Optional
+
+try:
+  import termcolor      # pylint: disable=g-import-not-at-top
+except ImportError:
+  termcolor = None
+
+
+# Regular expression for ANSI color characters.
+_ANSI_COLOR_REGEX = re.compile(r'\x1b\[[0-9;]*m')
+
+
+def decolor(text: str) -> str:
+  """De-colors a string that may contains ANSI color characters."""
+  return re.sub(_ANSI_COLOR_REGEX, '', text)
+
+
+def colored(
+    text: str,
+    color: Optional[str] = None,
+    background: Optional[str] = None,
+    styles: Optional[List[str]] = None,
+) -> str:
+  """Returns the colored text with ANSI color characters.
+
+  Args:
+    text: A string that may or may not already has ANSI color characters.
+    color: A string for text colors. Applicable values are:
+      'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'.
+    background: A string for background colors. Applicable values are:
+      'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'.
+    styles: A list of strings for applying styles on the text.
+      Applicable values are:
+      'bold', 'dark', 'underline', 'blink', 'reverse', 'concealed'.
+
+  Returns:
+    A string with ANSI color characters embracing the entire text.
+  """
+  if not termcolor:
+    return text
+  return termcolor.colored(
+      text,
+      color=color,
+      on_color=('on_' + background) if background else None,
+      attrs=styles
+  )
+
+
+def colored_block(
+    text: str,
+    block_start: str,
+    block_end: str,
+    color: Optional[str] = None,
+    background: Optional[str] = None,
+    styles: Optional[List[str]] = None,
+) -> str:
+  """Apply colors to text blocks.
+
+  Args:
+    text: A string that may or may not already has ANSI color characters.
+    block_start: A string that signals the start of a block. E.g. '{{'
+    block_end: A string that signals the end of a block. E.g. '}}'.
+    color: A string for text colors. Applicable values are:
+      'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'.
+    background: A string for background colors. Applicable values are:
+      'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'.
+    styles: A list of strings for applying styles on the text.
+      Applicable values are:
+      'bold', 'dark', 'underline', 'blink', 'reverse', 'concealed'.
+
+  Returns:
+    A string with ANSI color characters embracing the matched text blocks.
+  """
+  if not color and not background and not styles:
+    return text
+
+  s = []
+  start_index = 0
+  end_index = 0
+  previous_color = None
+
+  def write_nonblock_text(text: str, previous_color: Optional[str]):
+    if previous_color:
+      s.append(previous_color)
+    s.append(text)
+
+  while start_index < len(text):
+    start_index = text.find(block_start, end_index)
+    if start_index == -1:
+      write_nonblock_text(text[end_index:], previous_color)
+      break
+
+    # Deal with text since last block.
+    since_last_block = text[end_index:start_index]
+    write_nonblock_text(since_last_block, previous_color)
+    colors = re.findall(_ANSI_COLOR_REGEX, since_last_block)
+    if colors:
+      previous_color = colors[-1]
+
+    # Match block.
+    end_index = text.find(block_end, start_index + len(block_start))
+    if end_index == -1:
+      write_nonblock_text(text[start_index:], previous_color)
+      break
+    end_index += len(block_end)
+
+    # Write block text.
+    block = text[start_index:end_index]
+    block = colored(
+        block, color=color, background=background, styles=styles)
+    s.append(block)
+  return ''.join(s)

pyglove/core/utils/text_color_test.py

@@ -0,0 +1,94 @@
+# Copyright 2025 The PyGlove Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import inspect
+import os
+import unittest
+from pyglove.core.utils import text_color
+
+
+class TextColorTest(unittest.TestCase):
+
+  def setUp(self):
+    super().setUp()
+    os.environ.pop('ANSI_COLORS_DISABLED', None)
+    os.environ.pop('NO_COLOR', None)
+    os.environ['FORCE_COLOR'] = '1'
+
+  def test_colored_block_without_colors_and_styles(self):
+    self.assertEqual(text_color.colored_block('foo', '{{', '}}'), 'foo')
+
+  def test_colored_block(self):
+    original_text = inspect.cleandoc("""
+        Hi << foo >>
+        <# print x if x is present #>
+        <% if x %>
+        << x >>
+        <% endif %>
+        """)
+
+    colored_text = text_color.colored_block(
+        text_color.colored(original_text, color='blue'),
+        '<<', '>>',
+        color='white',
+        background='blue',
+    )
+    origin_color = '\x1b[34m'
+    reset = '\x1b[0m'
+    block_color = text_color.colored(
+        'TEXT', color='white', background='blue'
+    ).split('TEXT')[0]
+    self.assertEqual(
+        colored_text,
+        f'{origin_color}Hi {block_color}<< foo >>{reset}{origin_color}\n'
+        '<# print x if x is present #>\n<% if x %>\n'
+        f'{block_color}<< x >>{reset}{origin_color}\n'
+        f'<% endif %>{reset}'
+    )
+    self.assertEqual(text_color.decolor(colored_text), original_text)
+
+  def test_colored_block_without_full_match(self):
+    self.assertEqual(
+        text_color.colored_block(
+            'Hi {{ foo',
+            '{{', '}}',
+            color='white',
+            background='blue',
+        ),
+        'Hi {{ foo'
+    )
+
+  def test_colored_block_without_termcolor(self):
+    termcolor = text_color.termcolor
+    text_color.termcolor = None
+    original_text = inspect.cleandoc("""
+        Hi {{ foo }}
+        {# print x if x is present #}
+        {% if x %}
+        {{ x }}
+        {% endif %}
+        """)
+
+    colored_text = text_color.colored_block(
+        text_color.colored(original_text, color='blue'),
+        '{{', '}}',
+        color='white',
+        background='blue',
+    )
+    self.assertEqual(colored_text, original_text)
+    self.assertEqual(text_color.decolor(colored_text), original_text)
+    text_color.termcolor = termcolor
+
+
+if __name__ == '__main__':
+  unittest.main()

{pyglove-0.4.5.dev202501060809.dist-info → pyglove-0.4.5.dev202501080809.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyglove
-Version: 0.4.5.dev202501060809
+Version: 0.4.5.dev202501080809
 Summary: PyGlove: A library for manipulating Python objects.
 Home-page: https://github.com/google/pyglove
 Author: PyGlove Authors
@@ -22,6 +22,7 @@ Classifier: Topic :: Software Development :: Libraries
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: docstring-parser>=0.12
+Requires-Dist: termcolor>=1.1.0
 
 <div align="center">
 <img src="https://raw.githubusercontent.com/google/pyglove/main/docs/_static/logo_light.svg#gh-light-mode-only" width="320px" alt="logo"></img>

{pyglove-0.4.5.dev202501060809.dist-info → pyglove-0.4.5.dev202501080809.dist-info}/RECORD

@@ -119,7 +119,7 @@ pyglove/core/typing/typed_missing.py,sha256=-l1omAu0jBZv5BnsFYXBqfvQwVBnmPh_X1wc
 pyglove/core/typing/typed_missing_test.py,sha256=TCNsb1SRpFaVdxYn2mB_yaLuja8w5Qn5NP7uGiZVBWs,2301
 pyglove/core/typing/value_specs.py,sha256=Yxdrz4aURMBrtqUW4to-2Vptc6Z6oqQrLyMBiAZt2bc,102302
 pyglove/core/typing/value_specs_test.py,sha256=MsScWDRaN_8pfRDO9MCp9HdUHVm_8wHWyKorWVSnhE4,127165
-pyglove/core/utils/__init__.py,sha256=hQqQ0B7YWhwG09sGG5wtLyKMKs2g3P2NDCaxsC7JpSY,8012
+pyglove/core/utils/__init__.py,sha256=cegrJtHy0h7DIUFcQN67TZJf9_f28OR-NrKbKKjPkeE,8183
 pyglove/core/utils/common_traits.py,sha256=PWxOgPhG5H60ZwfO8xNAEGRjFUqqDZQBWQYomOfvdy8,3640
 pyglove/core/utils/common_traits_test.py,sha256=DIuZB_1xfmeTVfWnGOguDQcDAM_iGgBOe8C-5CsIqBc,1122
 pyglove/core/utils/docstr_utils.py,sha256=5BY40kXozPKVGOB0eN8jy1P5_GHIzqFJ9FXAu_kzxaw,5119
@@ -134,6 +134,8 @@ pyglove/core/utils/json_conversion.py,sha256=I0mWn87aAEdaAok9nDvT0ZrmplU40eNmEDU
 pyglove/core/utils/json_conversion_test.py,sha256=zA_cy7ixVL3sTf6i9BCXMlSH56Aa3JnjHnjyqYJ_9XU,11845
 pyglove/core/utils/missing.py,sha256=9gslt1lXd1qSEIuAFxUWu30oD-YdYcnm13eau1S9uqY,1445
 pyglove/core/utils/missing_test.py,sha256=D6-FuVEwCyJemUiPLcwLmwyptqI5Bx0Pfipc2juhKSE,1335
+pyglove/core/utils/text_color.py,sha256=xcCTCxY2qFNZs_jismMGus8scEXKBpYGAhpAgnz-MHk,4112
+pyglove/core/utils/text_color_test.py,sha256=3HtZpUB5XPr7A_5Fg4ZSMfNWeDRiQgSzmg9b1tctMI4,2801
 pyglove/core/utils/thread_local.py,sha256=i-CnyY3VREtLfAj4_JndBnsKuQLIgwG29ma8dAyRxbI,4839
 pyglove/core/utils/thread_local_test.py,sha256=AOqsdNsA-cYMvJckqxb25ql3Y5kDW0qLfBW1cl85Bnw,6757
 pyglove/core/utils/timing.py,sha256=fXdwEYXR84qZBC7hxbXbwztW2UKliJZLqCDvhz1qw_A,7241
@@ -197,8 +199,8 @@ pyglove/ext/scalars/randoms.py,sha256=LkMIIx7lOq_lvJvVS3BrgWGuWl7Pi91-lA-O8x_gZs
 pyglove/ext/scalars/randoms_test.py,sha256=nEhiqarg8l_5EOucp59CYrpO2uKxS1pe0hmBdZUzRNM,2000
 pyglove/ext/scalars/step_wise.py,sha256=IDw3tuTpv0KVh7AN44W43zqm1-E0HWPUlytWOQC9w3Y,3789
 pyglove/ext/scalars/step_wise_test.py,sha256=TL1vJ19xVx2t5HKuyIzGoogF7N3Rm8YhLE6JF7i0iy8,2540
-pyglove-0.4.5.dev202501060809.dist-info/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
-pyglove-0.4.5.dev202501060809.dist-info/METADATA,sha256=XsKRBqdRTJo7Y5ub7MMg1wY-rKZsQmpP7bIAbACBdo4,6828
-pyglove-0.4.5.dev202501060809.dist-info/WHEEL,sha256=A3WOREP4zgxI0fKrHUG8DC8013e3dK3n7a6HDbcEIwE,91
-pyglove-0.4.5.dev202501060809.dist-info/top_level.txt,sha256=wITzJSKcj8GZUkbq-MvUQnFadkiuAv_qv5qQMw0fIow,8
-pyglove-0.4.5.dev202501060809.dist-info/RECORD,,
+pyglove-0.4.5.dev202501080809.dist-info/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
+pyglove-0.4.5.dev202501080809.dist-info/METADATA,sha256=1rkODhRd0zayZYQ5lczr0q5i4XDQ2BQFAYnLRmS_39g,6860
+pyglove-0.4.5.dev202501080809.dist-info/WHEEL,sha256=A3WOREP4zgxI0fKrHUG8DC8013e3dK3n7a6HDbcEIwE,91
+pyglove-0.4.5.dev202501080809.dist-info/top_level.txt,sha256=wITzJSKcj8GZUkbq-MvUQnFadkiuAv_qv5qQMw0fIow,8
+pyglove-0.4.5.dev202501080809.dist-info/RECORD,,