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

pyglove/core/coding/permissions.py

@@ -0,0 +1,100 @@
+# 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.
+"""Python code permissions."""
+
+import contextlib
+import enum
+from typing import Optional
+
+from pyglove.core import utils
+
+
+class CodePermission(enum.Flag):
+  """Permissions for code execution."""
+
+  # Allows assignment.
+  ASSIGN = enum.auto()
+
+  # Allows conditions.
+  CONDITION = enum.auto()
+
+  # Allows loops.
+  LOOP = enum.auto()
+
+  # Call functions or methods.
+  CALL = enum.auto()
+
+  # Allows exception.
+  EXCEPTION = enum.auto()
+
+  # Allows class definitions.
+  CLASS_DEFINITION = enum.auto()
+
+  # Allows function definitions.
+  FUNCTION_DEFINITION = enum.auto()
+
+  # Allows import.
+  IMPORT = enum.auto()
+
+  @classmethod
+  @property
+  def BASIC(cls) -> 'CodePermission':    # pylint: disable=invalid-name
+    """Returns basic permissions."""
+    return CodePermission.ASSIGN | CodePermission.CALL
+
+  @classmethod
+  @property
+  def ALL(cls) -> 'CodePermission':    # pylint: disable=invalid-name
+    """Returns all permissions."""
+    return (
+        CodePermission.BASIC | CodePermission.CONDITION | CodePermission.LOOP |
+        CodePermission.EXCEPTION | CodePermission.CLASS_DEFINITION |
+        CodePermission.FUNCTION_DEFINITION | CodePermission.IMPORT)
+
+
+_TLS_CODE_RUN_PERMISSION = '__code_run_permission__'
+
+
+@contextlib.contextmanager
+def permission(perm: CodePermission):
+  """Context manager for controling the permission for code execution.
+
+  When the `permission` context manager is nested, the outtermost permission
+  will be used. This design allows users to control permission at the top level.
+
+  Args:
+    perm: Code execution permission.
+
+  Yields:
+    Actual permission applied.
+  """
+
+  outter_perm = utils.thread_local_get(_TLS_CODE_RUN_PERMISSION, None)
+
+  # Use the top-level permission as the actual permission
+  if outter_perm is not None:
+    perm = outter_perm
+
+  utils.thread_local_set(_TLS_CODE_RUN_PERMISSION, perm)
+
+  try:
+    yield perm
+  finally:
+    if outter_perm is None:
+      utils.thread_local_del(_TLS_CODE_RUN_PERMISSION)
+
+
+def get_permission() -> Optional[CodePermission]:
+  """Gets the current permission for code execution."""
+  return utils.thread_local_get(_TLS_CODE_RUN_PERMISSION, None)

pyglove/core/coding/permissions_test.py

@@ -0,0 +1,93 @@
+# 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 unittest
+from pyglove.core.coding import permissions
+
+
+class CodePermissionTest(unittest.TestCase):
+
+  def assert_set(
+      self,
+      permission: permissions.CodePermission,
+      flag: permissions.CodePermission,
+  ):
+    self.assertEqual(permission & flag, flag)
+
+  def assert_not_set(
+      self,
+      permission: permissions.CodePermission,
+      flag: permissions.CodePermission,
+  ):
+    self.assertFalse(permission & flag)
+
+  def test_basic(self):
+    self.assert_set(
+        permissions.CodePermission.BASIC, permissions.CodePermission.ASSIGN
+    )
+    self.assert_set(
+        permissions.CodePermission.BASIC, permissions.CodePermission.CALL
+    )
+    self.assert_set(
+        permissions.CodePermission.BASIC, permissions.CodePermission.CALL
+    )
+
+  def test_all(self):
+    self.assert_set(
+        permissions.CodePermission.ALL, permissions.CodePermission.BASIC
+    )
+    self.assert_set(
+        permissions.CodePermission.ALL, permissions.CodePermission.CONDITION
+    )
+    self.assert_set(
+        permissions.CodePermission.ALL, permissions.CodePermission.LOOP
+    )
+    self.assert_set(
+        permissions.CodePermission.ALL, permissions.CodePermission.EXCEPTION
+    )
+    self.assert_set(
+        permissions.CodePermission.ALL,
+        permissions.CodePermission.CLASS_DEFINITION,
+    )
+    self.assert_set(
+        permissions.CodePermission.ALL,
+        permissions.CodePermission.FUNCTION_DEFINITION,
+    )
+    self.assert_set(
+        permissions.CodePermission.ALL, permissions.CodePermission.IMPORT
+    )
+
+  def test_xor(self):
+    self.assert_not_set(
+        permissions.CodePermission.ALL ^ permissions.CodePermission.BASIC,
+        permissions.CodePermission.BASIC,
+    )
+    self.assert_set(
+        permissions.CodePermission.ALL ^ permissions.CodePermission.BASIC,
+        permissions.CodePermission.CONDITION,
+    )
+
+  def test_permission_control(self):
+    self.assertIsNone(permissions.get_permission())
+    with permissions.permission(permissions.CodePermission.BASIC):
+      self.assertEqual(
+          permissions.get_permission(), permissions.CodePermission.BASIC
+      )
+      with permissions.permission(permissions.CodePermission.ALL):
+        self.assertEqual(
+            permissions.get_permission(), permissions.CodePermission.BASIC
+        )
+
+
+if __name__ == '__main__':
+  unittest.main()

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.dev202501082350.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: pyglove
-Version: 0.4.5.dev202501060809
+Version: 0.4.5.dev202501082350
 Summary: PyGlove: A library for manipulating Python objects.
 Home-page: https://github.com/google/pyglove
 Author: PyGlove Authors
@@ -22,6 +22,17 @@ 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
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: summary
 
 <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.dev202501082350.dist-info}/RECORD

@@ -1,10 +1,18 @@
 pyglove/__init__.py,sha256=YPUWALRDu4QuI7N3TUmVaVr513hUt0qXrjY582I1q5c,1352
-pyglove/core/__init__.py,sha256=eT7QvwXj-ers44ufDvIuy3J2PAckk5b4EVGbRiX_E-M,9284
+pyglove/core/__init__.py,sha256=629Ml4RzdBdtd_1Cz4HZoCde_ilOG2lAW02E90hStWw,9333
 pyglove/core/logging.py,sha256=Sr5nLyUQmc4CAEYAq8qbP3ghpjmpz2sOuhq2A0tgQ6I,2456
 pyglove/core/logging_test.py,sha256=3z_c6wnxbqDbwUmSOAZzeDPXvzoweYL5QHUQVMJ5Xgo,1917
-pyglove/core/coding/__init__.py,sha256=nVKjJQYhvzJNr1zj0GuCsz_ltGLqhQEtBQj0zPiOkqA,998
+pyglove/core/coding/__init__.py,sha256=Qn72755xebwK9_fYp7FAIkER49L1bLkxzEjYR6GFKrA,1470
+pyglove/core/coding/errors.py,sha256=vstDb52lk5uJef2k_0_1dqvGv8eDYNq37IrqjGJ-cNc,3302
+pyglove/core/coding/errors_test.py,sha256=fwOR8vLiRvLadubsccyE19hLHj-kThlCQt88qmUYk9M,2311
+pyglove/core/coding/execution.py,sha256=fCJdONSwQhobtSrvjIySZ-t3qy6l1TdTM0qWFzIVWTM,10874
+pyglove/core/coding/execution_test.py,sha256=MMYhkgjssGet_wQNUu-8moKZZkxNqfDxBiW3ahI0qrg,8417
 pyglove/core/coding/function_generation.py,sha256=2fCqcdcizVYtGYE6QGpw5m1kuH9Fp0OF4BjyJ4en6tw,1636
 pyglove/core/coding/function_generation_test.py,sha256=kbSwmZF8Vog0R0OTSpuzPblEbMLoRJ1TigeIrwDhHS8,2161
+pyglove/core/coding/parsing.py,sha256=JXTdzFS9iB5-JVi9_-rDFORj_EZEtr7In8HBGHp09no,4084
+pyglove/core/coding/parsing_test.py,sha256=XB-bd2Huj36GKmvmFjp3jRwr7NqhRd1Ag-AGNxr_ekk,3575
+pyglove/core/coding/permissions.py,sha256=kd_gO1csXHpySsvazxmKBVe7dfLpX5GquRtu9q4ToRE,2729
+pyglove/core/coding/permissions_test.py,sha256=GTEnCClTZWdFmqHk3U5P8mzOmIINtUeEkeJZApnaWVI,2935
 pyglove/core/detouring/__init__.py,sha256=ck_n2VSuU31HNVYQkbG4Zvnx90mNYtSVc2StN3rXbU8,1891
 pyglove/core/detouring/class_detour.py,sha256=ejuUr7UfRU3l9PrDxD0dpKmt2iqdDU6liHdebA1jEfQ,13312
 pyglove/core/detouring/class_detour_test.py,sha256=9aAK6qPiT0_HJe5oUpqMVTpoHv0wr_h6c4gWYKMTJoM,5507
@@ -119,7 +127,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 +142,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 +207,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.dev202501082350.dist-info/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
+pyglove-0.4.5.dev202501082350.dist-info/METADATA,sha256=6v2kvpijILMgnzjttU4tyQxGMOQcY_kcT7YW_xU4KMY,7067
+pyglove-0.4.5.dev202501082350.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+pyglove-0.4.5.dev202501082350.dist-info/top_level.txt,sha256=wITzJSKcj8GZUkbq-MvUQnFadkiuAv_qv5qQMw0fIow,8
+pyglove-0.4.5.dev202501082350.dist-info/RECORD,,

{pyglove-0.4.5.dev202501060809.dist-info → pyglove-0.4.5.dev202501082350.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.7.0)
+Generator: setuptools (75.8.0)
 Root-Is-Purelib: true
 Tag: py3-none-any