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

pyglove/core/typing/value_specs_test.py

@@ -18,7 +18,7 @@ import sys
 import typing
 import unittest
 
-from pyglove.core import object_utils
+from pyglove.core import utils
 from pyglove.core.typing import annotation_conversion   # pylint: disable=unused-import
 from pyglove.core.typing import callable_signature
 from pyglove.core.typing import class_schema
@@ -36,11 +36,10 @@ class ValueSpecTest(unittest.TestCase):
   """Base class for value spec test."""
 
   def assert_json_conversion(self, v):
-    self.assertEqual(object_utils.from_json(v.to_json()), v)
+    self.assertEqual(utils.from_json(v.to_json()), v)
 
   def assert_json_conversion_key(self, v, key):
-    self.assertEqual(
-        v.to_json()[object_utils.JSONConvertible.TYPE_NAME_KEY], key)
+    self.assertEqual(v.to_json()[utils.JSONConvertible.TYPE_NAME_KEY], key)
 
 
 class BoolTest(ValueSpecTest):
@@ -1039,9 +1038,9 @@ class ListTest(ValueSpecTest):
     self.assertEqual(vs.List(vs.Int().noneable()).apply([1, None]), [1, None])
     # Automatic conversion: str -> KeyPath is a registered conversion.
     # See 'type_conversion.py'.
-    l = vs.List(vs.Object(object_utils.KeyPath)).apply(['a.b.c'])
-    self.assertIsInstance(l[0], object_utils.KeyPath)
-    self.assertEqual(l, [object_utils.KeyPath.parse('a.b.c')])
+    l = vs.List(vs.Object(utils.KeyPath)).apply(['a.b.c'])
+    self.assertIsInstance(l[0], utils.KeyPath)
+    self.assertEqual(l, [utils.KeyPath.parse('a.b.c')])
     self.assertEqual(
         vs.List(vs.Int()).apply(
             typed_missing.MISSING_VALUE, allow_partial=True),
@@ -2046,7 +2045,7 @@ class DictTest(ValueSpecTest):
     x = vs.Dict([
         ('a', int, 'field 1', dict(x=1)),
     ]).freeze(dict(a=1))
-    y = object_utils.from_json(x.to_json())
+    y = utils.from_json(x.to_json())
     self.assert_json_conversion(
         vs.Dict([
             ('a', int, 'field 1', dict(x=1)),
@@ -2089,7 +2088,7 @@ class ObjectTest(ValueSpecTest):
     class C(A):
       pass
 
-    class D(C, object_utils.MaybePartial):
+    class D(C, utils.MaybePartial):
 
       def missing_values(self):
         return {'SOME_KEY': 'SOME_VALUE'}
@@ -2378,7 +2377,7 @@ class CallableTest(ValueSpecTest):
 
   def test_value_type(self):
     self.assertIsNone(vs.Callable().value_type)
-    self.assertEqual(vs.Functor().annotation, object_utils.Functor)
+    self.assertEqual(vs.Functor().annotation, utils.Functor)
 
   def test_forward_refs(self):
     self.assertEqual(vs.Callable().forward_refs, set())
@@ -2584,7 +2583,7 @@ class CallableTest(ValueSpecTest):
 
   def test_apply_on_functor(self):
 
-    class FunctorWithRegularArgs(object_utils.Functor):
+    class FunctorWithRegularArgs(utils.Functor):
 
       __signature__ = Signature(
           callable_type=callable_signature.CallableType.FUNCTION,
@@ -2630,7 +2629,7 @@ class CallableTest(ValueSpecTest):
 
   def test_apply_on_functor_with_varargs(self):
 
-    class FunctorWithVarArgs(object_utils.Functor):
+    class FunctorWithVarArgs(utils.Functor):
 
       __signature__ = Signature(
           callable_type=callable_signature.CallableType.FUNCTION,
@@ -2781,7 +2780,7 @@ class CallableTest(ValueSpecTest):
         )
     )
     x = vs.Callable([vs.Int()], default=lambda x: x + 1).noneable()
-    y = object_utils.from_json(x.to_json())
+    y = utils.from_json(x.to_json())
     self.assert_json_conversion(
         vs.Callable([vs.Int()], default=lambda x: x + 1).noneable()
     )

pyglove/core/utils/__init__.py

@@ -0,0 +1,159 @@
+# Copyright 2022 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.
+# pylint: disable=line-too-long
+"""Utility library that provides common traits for objects in Python.
+
+Overview
+--------
+
+``pg.utils`` sits at the bottom of all PyGlove modules and empowers other
+modules with the following features:
+
+  +---------------------+--------------------------------------------+
+  | Functionality       | API                                        |
+  +=====================+============================================+
+  | Formatting          | :class:`pg.Formattable`,                   |
+  |                     |                                            |
+  |                     | :func:`pg.format`,                         |
+  |                     |                                            |
+  |                     | :func:`pg.print`,                          |
+  |                     |                                            |
+  |                     | :func:`pg.utils.kvlist_str`,        |
+  |                     |                                            |
+  |                     | :func:`pg.utils.quote_if_str`,      |
+  |                     |                                            |
+  |                     | :func:`pg.utils.message_on_path`    |
+  +---------------------+--------------------------------------------+
+  | Serialization       | :class:`pg.JSONConvertible`,               |
+  |                     |                                            |
+  |                     | :func:`pg.registered_types`,               |
+  |                     |                                            |
+  |                     | :func:`pg.utils.to_json`,           |
+  |                     |                                            |
+  |                     | :func:`pg.utils.from_json`,         |
+  +---------------------+--------------------------------------------+
+  | Partial construction| :class:`pg.MaybePartial`,                  |
+  |                     |                                            |
+  |                     | :const:`pg.MISSING_VALUE`.                 |
+  +---------------------+--------------------------------------------+
+  | Hierarchical key    | :class:`pg.KeyPath`                        |
+  | representation      |                                            |
+  +---------------------+--------------------------------------------+
+  | Hierarchical object | :func:`pg.utils.traverse`           |
+  | traversal           |                                            |
+  +---------------------+--------------------------------------------+
+  | Hierarchical object | :func:`pg.utils.transform`,         |
+  | transformation      |                                            |
+  |                     | :func:`pg.utils.merge`,             |
+  |                     |                                            |
+  |                     | :func:`pg.utils.canonicalize`,      |
+  |                     |                                            |
+  |                     | :func:`pg.utils.flatten`            |
+  +---------------------+--------------------------------------------+
+  | Docstr handling     | :class:`pg.docstr`,                        |
+  +---------------------+--------------------------------------------+
+  | Error handling     | :class:`pg.catch_errors`,                   |
+  +---------------------+--------------------------------------------+
+"""
+# pylint: enable=line-too-long
+# pylint: disable=g-bad-import-order
+# pylint: disable=g-importing-member
+
+# Handling JSON conversion.
+from pyglove.core.utils.json_conversion import Nestable
+from pyglove.core.utils.json_conversion import JSONValueType
+
+from pyglove.core.utils.json_conversion import JSONConvertible
+from pyglove.core.utils.json_conversion import from_json
+from pyglove.core.utils.json_conversion import to_json
+from pyglove.core.utils.json_conversion import registered_types
+
+# Handling formatting.
+from pyglove.core.utils.formatting import Formattable
+from pyglove.core.utils.formatting import format  # pylint: disable=redefined-builtin
+from pyglove.core.utils.formatting import printv as print  # pylint: disable=redefined-builtin
+from pyglove.core.utils.formatting import kvlist_str
+from pyglove.core.utils.formatting import quote_if_str
+from pyglove.core.utils.formatting import maybe_markdown_quote
+from pyglove.core.utils.formatting import comma_delimited_str
+from pyglove.core.utils.formatting import camel_to_snake
+from pyglove.core.utils.formatting import auto_plural
+from pyglove.core.utils.formatting import BracketType
+from pyglove.core.utils.formatting import bracket_chars
+from pyglove.core.utils.formatting import RawText
+
+# Context managers for defining the default format for __str__ and __repr__.
+from pyglove.core.utils.formatting import str_format
+from pyglove.core.utils.formatting import repr_format
+
+# Value location.
+from pyglove.core.utils.value_location import KeyPath
+from pyglove.core.utils.value_location import KeyPathSet
+from pyglove.core.utils.value_location import StrKey
+from pyglove.core.utils.value_location import message_on_path
+
+# Value markers.
+from pyglove.core.utils.missing import MissingValue
+from pyglove.core.utils.missing import MISSING_VALUE
+
+# Handling hierarchical.
+from pyglove.core.utils.hierarchical import traverse
+from pyglove.core.utils.hierarchical import transform
+from pyglove.core.utils.hierarchical import flatten
+from pyglove.core.utils.hierarchical import canonicalize
+from pyglove.core.utils.hierarchical import merge
+from pyglove.core.utils.hierarchical import merge_tree
+from pyglove.core.utils.hierarchical import is_partial
+from pyglove.core.utils.hierarchical import try_listify_dict_with_int_keys
+
+# Common traits.
+from pyglove.core.utils.common_traits import MaybePartial
+from pyglove.core.utils.common_traits import Functor
+
+from pyglove.core.utils.common_traits import explicit_method_override
+from pyglove.core.utils.common_traits import ensure_explicit_method_override
+
+# Handling thread local values.
+from pyglove.core.utils.thread_local import thread_local_value_scope
+from pyglove.core.utils.thread_local import thread_local_has
+from pyglove.core.utils.thread_local import thread_local_set
+from pyglove.core.utils.thread_local import thread_local_get
+from pyglove.core.utils.thread_local import thread_local_del
+from pyglove.core.utils.thread_local import thread_local_increment
+from pyglove.core.utils.thread_local import thread_local_decrement
+from pyglove.core.utils.thread_local import thread_local_push
+from pyglove.core.utils.thread_local import thread_local_pop
+from pyglove.core.utils.thread_local import thread_local_peek
+
+# Handling docstrings.
+from pyglove.core.utils.docstr_utils import DocStr
+from pyglove.core.utils.docstr_utils import DocStrStyle
+from pyglove.core.utils.docstr_utils import DocStrEntry
+from pyglove.core.utils.docstr_utils import DocStrExample
+from pyglove.core.utils.docstr_utils import DocStrArgument
+from pyglove.core.utils.docstr_utils import DocStrReturns
+from pyglove.core.utils.docstr_utils import DocStrRaises
+from pyglove.core.utils.docstr_utils import docstr
+
+# Handling exceptions.
+from pyglove.core.utils.error_utils import catch_errors
+from pyglove.core.utils.error_utils import CatchErrorsContext
+from pyglove.core.utils.error_utils import ErrorInfo
+
+# Timing.
+from pyglove.core.utils.timing import timeit
+from pyglove.core.utils.timing import TimeIt
+
+# pylint: enable=g-importing-member
+# pylint: enable=g-bad-import-order

pyglove/core/{object_utils → utils}/common_traits_test.py

@@ -11,10 +11,8 @@
 # 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.
-"""Tests for pyglove.object_utils.common_traits."""
-
 import unittest
-from pyglove.core.object_utils import common_traits
+from pyglove.core.utils import common_traits
 
 
 class ExplicitlyOverrideTest(unittest.TestCase):

pyglove/core/{object_utils → utils}/docstr_utils_test.py

@@ -11,11 +11,9 @@
 # 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.
-"""Tests for pyglove.object_utils.docstr_utils."""
-
 import inspect
 import unittest
-from pyglove.core.object_utils import docstr_utils
+from pyglove.core.utils import docstr_utils
 
 
 class DocStrTest(unittest.TestCase):

pyglove/core/{object_utils → utils}/error_utils.py

@@ -21,8 +21,8 @@ import sys
 import traceback
 from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple, Type, Union
 
-from pyglove.core.object_utils import formatting
-from pyglove.core.object_utils import json_conversion
+from pyglove.core.utils import formatting
+from pyglove.core.utils import json_conversion
 
 
 @dataclasses.dataclass(frozen=True)
@@ -102,7 +102,7 @@ def catch_errors(
 
   Examples::
 
-    with pg.object_utils.catch_errors(
+    with pg.utils.catch_errors(
         [
             RuntimeErrror,
             (ValueError, 'Input is wrong.')

pyglove/core/{object_utils → utils}/error_utils_test.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 import inspect
 import unittest
-from pyglove.core.object_utils import error_utils
+from pyglove.core.utils import error_utils
 
 
 class ErrorInfoTest(unittest.TestCase):

pyglove/core/{object_utils → utils}/formatting.py

@@ -18,7 +18,7 @@ import enum
 import io
 import sys
 from typing import Any, Callable, ContextManager, Dict, List, Optional, Sequence, Set, Tuple
-from pyglove.core.object_utils import thread_local
+from pyglove.core.utils import thread_local
 
 
 _TLS_STR_FORMAT_KWARGS = '_str_format_kwargs'

pyglove/core/{object_utils → utils}/formatting_test.py

@@ -11,11 +11,10 @@
 # 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.
-"""Tests for pyglove.object_utils.formatting."""
 import inspect
 import unittest
 
-from pyglove.core.object_utils import formatting
+from pyglove.core.utils import formatting
 
 
 class Foo(formatting.Formattable):

pyglove/core/{object_utils → utils}/hierarchical.py

@@ -14,9 +14,9 @@
 """Operating hierarchical object."""
 
 from typing import Any, Callable, Dict, List, Optional, Tuple, Union
-from pyglove.core.object_utils import common_traits
-from pyglove.core.object_utils.missing import MISSING_VALUE
-from pyglove.core.object_utils.value_location import KeyPath
+from pyglove.core.utils import common_traits
+from pyglove.core.utils.missing import MISSING_VALUE
+from pyglove.core.utils.value_location import KeyPath
 
 
 def traverse(value: Any,
@@ -33,7 +33,7 @@ def traverse(value: Any,
       print(path)
 
     tree = {'a': [{'c': [1, 2]}, {'d': {'g': (3, 4)}}], 'b': 'foo'}
-    pg.object_utils.traverse(tree, preorder_visit)
+    pg.utils.traverse(tree, preorder_visit)
 
     # Should print:
     # 'a'
@@ -48,10 +48,10 @@ def traverse(value: Any,
 
   Args:
     value: A maybe hierarchical value to traverse.
-    preorder_visitor_fn: Preorder visitor function.
-      Function signature is (path, value) -> should_continue.
-    postorder_visitor_fn: Postorder visitor function.
-      Function signature is (path, value) -> should_continue.
+    preorder_visitor_fn: Preorder visitor function. Function signature is (path,
+      value) -> should_continue.
+    postorder_visitor_fn: Postorder visitor function. Function signature is
+      (path, value) -> should_continue.
     root_path: The key path of the root value.
 
   Returns:
@@ -111,7 +111,7 @@ def transform(value: Any,
         'e': 'bar',
         'f': 4
     }
-    output = pg.object_utils.transform(inputs, _remove_int)
+    output = pg.utils.transform(inputs, _remove_int)
     assert output == {
         'a': {
             'c': ['bar'],
@@ -123,11 +123,11 @@ def transform(value: Any,
   Args:
     value: Any python value type. If value is a list of dict, transformation
       will occur recursively.
-    transform_fn: Transform function in signature
-      (path, value) -> new value
-      If new value is MISSING_VALUE, key will be deleted.
+    transform_fn: Transform function in signature (path, value) -> new value If
+      new value is MISSING_VALUE, key will be deleted.
     root_path: KeyPath of the root.
     inplace: If True, perform transformation in place.
+
   Returns:
     Transformed value.
   """
@@ -186,7 +186,7 @@ def flatten(src: Any, flatten_complex_keys: bool = True) -> Any:
         'b': 'hi',
         'c': None
     }
-    output = pg.object_utils.flatten(inputs)
+    output = pg.utils.flatten(inputs)
     assert output == {
         'a.e': 1,
         'a.f[0].g': 2,
@@ -200,9 +200,9 @@ def flatten(src: Any, flatten_complex_keys: bool = True) -> Any:
   Args:
     src: source value to flatten.
     flatten_complex_keys: if True, complex keys such as 'x.y' will be flattened
-    as 'x'.'y'. For example:
-      {'a': {'b.c': 1}} will be flattened into {'a.b.c': 1} if this flag is on,
-      otherwise it will be flattened as {'a[b.c]': 1}.
+      as 'x'.'y'. For example: {'a': {'b.c': 1}} will be flattened into
+      {'a.b.c': 1} if this flag is on, otherwise it will be flattened as
+      {'a[b.c]': 1}.
 
   Returns:
     For primitive value types, `src` itself will be returned.
@@ -464,7 +464,7 @@ def merge(value_list: List[Any],
             'f': 10
         }
     }
-    output = pg.object_utils.merge([original, patch])
+    output = pg.utils.merge([original, patch])
     assert output == {
         'a': 1,
         # b is updated.
@@ -486,14 +486,12 @@ def merge(value_list: List[Any],
       value. The merge process will keep input values intact.
     merge_fn: A function to handle value merge that will be called for updated
       or added keys. If a branch is added/updated, the root of branch will be
-      passed to merge_fn.
-      the signature of function is:
-      `(path, left_value, right_value) -> final_value`
-      If a key is only present in src dict, old_value is MISSING_VALUE;
-      If a key is only present in dest dict, new_value is MISSING_VALUE;
-      otherwise both new_value and old_value are filled.
-      If final_value is MISSING_VALUE for a path, it will be removed from its
-      parent collection.
+      passed to merge_fn. the signature of function is: `(path, left_value,
+      right_value) -> final_value` If a key is only present in src dict,
+      old_value is MISSING_VALUE; If a key is only present in dest dict,
+      new_value is MISSING_VALUE; otherwise both new_value and old_value are
+      filled. If final_value is MISSING_VALUE for a path, it will be removed
+      from its parent collection.
 
   Returns:
     A merged value.

pyglove/core/{object_utils → utils}/hierarchical_test.py

@@ -11,12 +11,10 @@
 # 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.
-"""Tests for pyglove.object_utils.hierarchical."""
-
 import unittest
-from pyglove.core.object_utils import common_traits
-from pyglove.core.object_utils import hierarchical
-from pyglove.core.object_utils import value_location
+from pyglove.core.utils import common_traits
+from pyglove.core.utils import hierarchical
+from pyglove.core.utils import value_location
 
 
 class TraverseTest(unittest.TestCase):

pyglove/core/{object_utils → utils}/json_conversion_test.py

@@ -11,13 +11,11 @@
 # 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.
-"""Tests for pyglove.object_utils.json_conversion."""
-
 import abc
 import typing
 import unittest
-from pyglove.core.object_utils import json_conversion
 from pyglove.core.typing import inspect as pg_inspect
+from pyglove.core.utils import json_conversion
 
 
 class X:

pyglove/core/{object_utils → utils}/missing.py

@@ -14,8 +14,8 @@
 """Representing missing value for a field."""
 
 from typing import Any, Dict
-from pyglove.core.object_utils import formatting
-from pyglove.core.object_utils import json_conversion
+from pyglove.core.utils import formatting
+from pyglove.core.utils import json_conversion
 
 
 class MissingValue(formatting.Formattable, json_conversion.JSONConvertible):

pyglove/core/{object_utils → utils}/missing_test.py

@@ -11,11 +11,9 @@
 # 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.
-"""Tests for pyglove.object_utils.missing."""
-
 import unittest
-from pyglove.core.object_utils import json_conversion
-from pyglove.core.object_utils import missing
+from pyglove.core.utils import json_conversion
+from pyglove.core.utils import missing
 
 
 class MissingValueTest(unittest.TestCase):

pyglove/core/{object_utils → utils}/thread_local_test.py

@@ -11,13 +11,11 @@
 # 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.
-"""Tests for pyglove.object_utils.thread_local."""
-
 import threading
 import time
 import unittest
 
-from pyglove.core.object_utils import thread_local
+from pyglove.core.utils import thread_local
 
 
 class ThreadLocalTest(unittest.TestCase):

pyglove/core/{object_utils → utils}/timing.py

@@ -18,9 +18,9 @@ import dataclasses
 import time
 from typing import Any, Dict, List, Optional
 
-from pyglove.core.object_utils import error_utils
-from pyglove.core.object_utils import json_conversion
-from pyglove.core.object_utils import thread_local
+from pyglove.core.utils import error_utils
+from pyglove.core.utils import json_conversion
+from pyglove.core.utils import thread_local
 
 
 class TimeIt:

pyglove/core/{object_utils → utils}/timing_test.py

@@ -11,12 +11,11 @@
 # 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 time
 import unittest
 
-from pyglove.core.object_utils import json_conversion
-from pyglove.core.object_utils import timing
+from pyglove.core.utils import json_conversion
+from pyglove.core.utils import timing
 
 
 class TimeItTest(unittest.TestCase):

pyglove/core/{object_utils → utils}/value_location.py

@@ -17,7 +17,7 @@ import abc
 import copy as copy_lib
 import operator
 from typing import Any, Callable, Iterable, Iterator, List, Optional, Union
-from pyglove.core.object_utils import formatting
+from pyglove.core.utils import formatting
 
 
 class KeyPath(formatting.Formattable):
@@ -822,7 +822,7 @@ class StrKey(metaclass=abc.ABCMeta):
 
   Example::
 
-    class MyKey(pg.object_utils.StrKey):
+    class MyKey(pg.utils.StrKey):
 
       def __init__(self, name):
         self.name = name

pyglove/core/{object_utils → utils}/value_location_test.py

@@ -11,11 +11,9 @@
 # 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.
-"""Tests for pyglove.object_utils.value_location."""
-
 import unittest
-from pyglove.core.object_utils import formatting
-from pyglove.core.object_utils import value_location
+from pyglove.core.utils import formatting
+from pyglove.core.utils import value_location
 
 
 KeyPath = value_location.KeyPath