Pyglove

This release contains refinements of object behaviors, including typing, formatting, serialization, hashing and etc. Besides, it introduces `pg.io` as an abstracted interface for operating with different file systems.

New Sub-packages

- Introduced `pg.io` for abstracted IO operations. ([b367568](https://github.com/google/pyglove/commit/b367568dfcd790cb06289332b86d20fa3a105d01), [3938023](https://github.com/google/pyglove/commit/3938023c25ff94cb74214caf829124c50f079abb))

Enhancements

* Typing
- `pg.typing.Object`: Improve forward reference resolution from string annotations. ([574f90b](https://github.com/google/pyglove/commit/574f90b356da8c0504ab895cee2ff1b4c5f87f53), [516500f](https://github.com/google/pyglove/commit/516500f6dd5dd41b3fd5709b48ab8db80fd78160), [7026760](https://github.com/google/pyglove/commit/70267603d83406b161531eee7c56382417ebb124), [37e49c3](https://github.com/google/pyglove/commit/37e49c3bef6a4f8c38b01f53c7f4240780f7acda))

* Object Formatting:
- Introduce `__str_format_args__` and `__repr_format_args__` attributes for customize str/repr behavior for `pg.Formattable`. ([7e0a98b](https://github.com/google/pyglove/commit/7e0a98bbcfa4817509bd7e0c11dcff12f304b035))
- Introduced `pg.str_format` and `pg.repr_format` context manager to control repr/str formatting for symbolic objects. ([0a2ea6](https://github.com/google/pyglove/commit/0a2ea674acca4b54091dc8625e8f82dc3e8c0b18))
- Add argument `markdown` for `pg.str_format` and `pg.repr_format` to quote the formatted object. ([fd6ea8d](https://github.com/google/pyglove/commit/fd6ea8dd035d1dc07164c58f0dabe1ad8c063c05))
- Added argument `use_inferred` for `pg.Symbolic` formatting. ([fdd3d3d](https://github.com/google/pyglove/commit/fdded3d9b7903080b9c6d74c3c4950bec52e4f36))
- Escape strings with `'` and `\n` in `pg.format`. ([0489642](https://github.com/google/pyglove/commit/04896427989564fd16220f2afad269479fe8f821))
- Better formatting for field docstr of multiple lines. ([900d677](https://github.com/google/pyglove/commit/900d677e9d1189731b28808e89f3915584ef2421))

* Object Serialization:
- Support module alias for deserialization. ([536bde1](https://github.com/google/pyglove/commit/536bde1c40af82736ac0e8044b1eecd88bf37376))
- Support `use_inferred` flag for `pg.to_json` and `pg.save`. ([e223f6d](https://github.com/google/pyglove/commit/e223f6da466e00ee9f216103f54d432d06c07a93))

* Object Behaviors:
- `pg.List.__iter__` to honor inferrable values. ([a4dacb5](https://github.com/google/pyglove/commit/a4dacb51300a22a8e0736e041668061be7330438))
- Enabled symbolic comparison/hashing on Python functions and methods. ([occc11b](https://github.com/google/pyglove/commit/0ccc11b076306c9b98373c8581e7e985626810dd))
- Tune `pg.Symbolic.set_accessor_writable` behavior to only affect current node instead the entire sub-tree. ([ee6009b](https://github.com/google/pyglove/commit/ee6009b970d03d8a25aa0e4e3b3eaf70e7e1981f))

Bug Fixes

* `pg.symbolic`
- Fix `pg.Dict.sym_hash` behavior for child symbolic objects whose `use_symbolic_comparison` is False. ([58b60c3](https://github.com/google/pyglove/commit/58b60c3e46ec973288aebc688fb0d28faf008c85))
- Fix the default value inspection for `pg.Symbolic.sym_nondefaults` and `pg.format`. ([121b5ef](https://github.com/google/pyglove/commit/121b5ef36e9e886ef6dd574ecad796df3c30ad78))

This release contains major updates on `pg.symbolic` and `pg.typing`.

Enhancements
* `pg.symbolic`
- (*Major*)`pg.to_json`/`pg.from_json`: supported serialization of Python types, annotations, functions/methods and opaque objects ([6529a3c](https://github.com/google/pyglove/commit/6529a3c3e26948cd0375f847b660c5f50acd24f8), [7777e8f](https://github.com/google/pyglove/commit/7777e8f29d7e28273d0872a8f867102e79ec928a), [4911073](https://github.com/google/pyglove/commit/4911073ea5f8d56c013adb18c3aaff2470b66e8f))
- (*Major*) Added `pg.Inferential` for symbolic value inference ([5ef667c](https://github.com/google/pyglove/commit/5ef667c63403eb34826967e9e4e2a35e91054827)).
- (*Major*) Added symbolic reference `pg.Ref`, which allows referencing symbolic values in a symbolic tree ([b28dc68](https://github.com/google/pyglove/commit/b28dc6892b6976fead4221e84378210873b6b913)).
- `pg.Functor`: supported functor creation through subclasssing ([4950819](https://github.com/google/pyglove/commit/49508199ea54edacf3435457b7de3966b558341f)).
- `pg.Symbolic.rebind`: supported `notify_parents` flag ([cd0029c](https://github.com/google/pyglove/commit/cd0029c8d9e9ef7b3fe9bd6a85de13681269d582)).
- `pg.symbolic.Origin`: added `root` property and `history` method ([2686b29](https://github.com/google/pyglove/commit/2686b2932a76a9a1e4c3606d90b54e2e5afd09fe)).
- `pg.Symbolic.sym_*`: have consistent value for `default` ([90afe73](https://github.com/google/pyglove/commit/90afe73756b23ca564377d90954d1289210d5939)).

* `pg.typing`
- (*Major*) `pg.typing.ValueSpec` can be used as a drop-in replacement for standard Python annotations. E.g. `pg.typing.List[int]` ([ddbade7](https://github.com/google/pyglove/commit/ddbade72cf81a2523cfc48cdaff84a3d205b697d), [c2eca16](https://github.com/google/pyglove/commit/c2eca160dbbf2b8b9a26d4c28578507ee7e199b9), [79ec73](https://github.com/google/pyglove/commit/79ec73b355c9680323f06296c809fa117a3e8085)).
- (*Major*) `pg.Schema`, `pg.typing.Field` and `pg.typing.KeySpec` and `pg.typing.ValueSpec` are now serializable ([7777e8f](https://github.com/google/pyglove/commit/7777e8f29d7e28273d0872a8f867102e79ec928a)).
- Added `pg.typing.Annotated`, `pg.typing.Sequence` and `pg.typing.Optional` ([ddbade7](https://github.com/google/pyglove/commit/ddbade72cf81a2523cfc48cdaff84a3d205b697d)).
- Added `pg.typing.ValueSpec.transform` for transforming the user input values during apply ([a83c2ee](https://github.com/google/pyglove/commit/a83c2ee837b932405625e5edd644bc3844d0379f), [0a9b034](https://github.com/google/pyglove/commit/0a9b034753405c4b84cfdf917ec7f53831f4a762)).
- Added `pg.typing.callable_eq` for comparing two callable objects ([7777e8f](https://github.com/google/pyglove/commit/7777e8f29d7e28273d0872a8f867102e79ec928a)).
- Added implicit conversion from `int` to `float` ([caa3c93](https://github.com/google/pyglove/commit/caa3c935a9c87496c6cb278ec41e32870e3133e7))

* `pg.object_utils`
- `pg.format`: supported `include_keys` argument ([6703406](https://github.com/google/pyglove/commit/670340682dac48b54fbd4de251209953ebc630ce)).
- `pg.object_utils.thread_local_value_scope`: fixed an unexpected behavior when all items in the stack are poped up ([a560ff7](https://github.com/google/pyglove/commit/a560ff7976648ef73b3996238351ddac6ca3bccc)).
- Added `pg.catch_errors` context manager ([a438fc0](https://github.com/google/pyglove/commit/a438fc00744d6970d643d85d406b8f60dfbc2b7d)).

Bug Fixes
* `pg.symbolic`
- `pg.Object.from_json`: propagate `allow_partial` flag to child. ([1cc5aab](https://github.com/google/pyglove/commit/1cc5aab0aaa00b747b6e9e3d2d5dc950505b9bc9))

* `pg.typing`
- `pg.typing.ForwardRef`: fixed issue during deep copying ([ddbade7](https://github.com/google/pyglove/commit/ddbade72cf81a2523cfc48cdaff84a3d205b697d)).

* `pg.ext.early_stopping`
- Fix an issue in state recovery for `pg.early_stopping.StepWise` ([808ca8e](https://github.com/google/pyglove/commit/808ca8e62bde3967e92486e581c3d1a2d94994e1)).

Deprecated/Renamed APIs

* `pg.symbolic`
- Renamed `pg.Object.schema` to `pg.Object.__schema__`, `pg.Object.type_name` to `pg.Object.__type_name__`, `pg.Object.serialization_key` to `pg.JSONConvertible.__serialization_key__` ([bdffd58](https://github.com/google/pyglove/commit/bdffd582280f58e7265f7dec6eba28b8b983784e))
- Renamed `pg.Functor.signature` to `pg.Functor.__signature__`.
- Removed `pg.ContextualValue`, `pg.symbolic.GetAttributeContext`, `pg.Symbolic.sym_contextual_getattr/hasattr` ([5ef667c](https://github.com/google/pyglove/commit/5ef667c63403eb34826967e9e4e2a35e91054827)).

* `pg.typing`
- Merged `pg.typing.get_first_applicable_converter` into `pg.typing.get_converter` ([dd1c253](https://github.com/google/pyglove/commit/dd1c2533912bdf074b642dce7c66c7884ee3bb91)).

Enhancements

- `pg.symbolic`
- Overriding `pg.Object.__init__` now requires to apply a `pg.explicit_method_override`, which prevents users from accidentally override common Python methods that are managed PyGlove. ([870ed11](https://github.com/google/pyglove/commit/870ed11798703e56e9c9523af5b52bd92ec320a4))
- `pg.compound` now supports generic types as the base class .([4f659ab](https://github.com/google/pyglove/commit/4f659ab39af97f1978fd5eb4b5c7e7b68e1bf14a))
- `pg.compound` also could use abstract class as the base class for Python 3.10 and above. ([c206676](https://github.com/google/pyglove/commit/c206676645556792cc421f19fb2b3136db5addb9))
- `pg.compound` allow contextual attribute access from the decomposed object. ([c206676](https://github.com/google/pyglove/commit/c206676645556792cc421f19fb2b3136db5addb9))

This is a light release with a few enhancements/bug fixes for `pg.typing` and `pg.symbolic`.

Enhancements

- `pg.typing`
- `pg.typing.Object`,`pg.typing.Type` and type converters support `Generic` annotations. ([4eabef3](https://github.com/google/pyglove/commit/4eabef38f59218e2f854523369894d7c5794f31f))
- `pg.Object` now supports `Callable[<input-type>, <output-type>]` and `Dict[str, <value-type>]` annotations. ([ab4a850](https://github.com/google/pyglove/commit/ab4a850162ca0ada5bcdbdd71a1a0c2f76882364))

- `pg.symbolic`
- Introducing `pg.use_init_args` for reordering the init arguments for the subclasses of `pg.Object`. ([627990e](https://github.com/google/pyglove/commit/627990eb121cf810daf2811f2858a3268e9bb09b))

Bug Fixes:

- `pg.typing`
- `Tuple[<elem_type>, ...]` now can be correctly recognized. ([9e2a772](https://github.com/google/pyglove/commit/9e2a7728a71d7b629e8569828ef949b24e612c0c))

- `pg.symbolic`
- `pg.eq` and `pg.ne` will no longer evaluate contextual value during member comparisons. ([77a4bb1](https://github.com/google/pyglove/commit/77a4bb138f6bf3bb439d60cba4a9a5a593c36e5a))
- `pg.diff(x, y, mode='diff')` will return `pg.Diff(left=pg.Diff.MISSING, right=pg.Diff.MISSING)` when `x` == `y`, whose string representation is 'No diff'. ([e31fa99](https://github.com/google/pyglove/commit/e31fa995e11d2de5e6bf0ca36a9364aac3e8a92a))

New Features

- `pg.symbolic`
- *Major*: Introduce `pg.compound` for maximizing compositional power of SOOP. ([001702a](https://github.com/google/pyglove/commit/001702ac6711fac7377133f5152bd4a556b5ff83))
- *Major*: Introduce `pg.ContextualValue` and allow symbolic fields to be contextual. ([1b7386b](https://github.com/google/pyglove/commit/1b7386bca701ff4fb740954ea9de1bcd4d92cc48), [f50831a](https://github.com/google/pyglove/commit/f50831a8a9368f320e4093c995020e39310f943c), [77f0732](https://github.com/google/pyglove/commit/77f073221adf0311fc2259586a43d4d5006c7cdf))

- `pg.object_utils`
- Introduce `pg.docstr` for DocStr inspection. ([29f02ad](https://github.com/google/pyglove/commit/
29f02ade5a844dbc23c8f0fb527bd6592957a2bd))

- `pg.mutfun`
- Introduce `pg.mutfun.If` ([88b60f8](https://github.com/google/pyglove/commit/88b60f892f2e32242809dba63f5361679f7df748))
- Introduce `pg.mutfun.While` ([15b477b](https://github.com/google/pyglove/commit/15b477bce9c9687efce2346989b2cd03eac5be9f))


Enhancements

- `pg.symbolic`
- *Major*: Introduce symbolic member declaration via field annotations, which replaces `pg.members` as the recommended way for symbolic field declaration ([27a7392](https://github.com/google/pyglove/commit/27a739253bb860e42c7266fba03e63c7b5e236d7), [564cb1b](https://github.com/google/pyglove/commit/564cb1ba51b288c2d74cea16b437a75d8d076451))

- *Major*: Introduce `auto_typing` for `pg.symbolize` and `pg.functor`. ([5b57191](https://github.com/google/pyglove/commit/5b571912003419e311da13dacb26e9c71f0c9e86))

- Introduce context manager `pg.auto_call_functors`, which allows functor invocation right after __init__. This makes functors compatible with regular functions. ([a00e787](https://github.com/google/pyglove/commit/a00e7879b3f1488fa4292df95131e61a2178f7d6))

- Introduce `auto_doc` argument for `pg.symbolze`. ([e8b2520](https://github.com/google/pyglove/commit/e8b25208248dc0800dacb7f028eaf61eacdbdc83))

- Support `python_format` argument for `pg.Symbolic.format`. ([c3005c06](https://github.com/google/pyglove/commit/c3005c6ba6cad64d43dbb93602eb94b592de4be4))

- `pg.Object` to allow member methods to work as the default value for callable symbolic attributes. ([9b2bd3b](https://github.com/google/pyglove/commit/9b2bd3bba0a1c1111de6c4d8760c48205e713b76))

- Add `pg.Object._begin_annotation_inference` and `pg.Object._end_annotation_inference` as events for intercepting annotation inference during class creation. ([af410fe](https://github.com/google/pyglove/commit/af410fef0b1d13cc0884e05faebd3bdc3a70d01a))

- `pg.typing`
- *Major*: `pg.typing.Object` to support forward declaration. ([9235f55](https://github.com/google/pyglove/commit/9235f55f54759dcba82bff2564afa40b50b2403d))

- `pg.object_utils`
- Introduce `pg.object_utils.thread_local_xxx` APIs for thread local state managements. ([4ee6572](https://github.com/google/pyglove/commit/4ee6572016f39eaa6f58dda1f36d7656d730604c), [e6a9066](https://github.com/google/pyglove/commit/e6a90664d272a8907ed56caa4e80371c70031424))


Bug Fixes

- `pg.typing`
- Fill `pg.typing.Signature.return_value` when the return annotation is not present. ([3fe60e0](https://github.com/google/pyglove/commit/3fe60e0c9f6ff63072af7254b7c9cc25aabe5dc6))
- Fix `pg.ValueSpec.from_annotation` on union type. ([27a7392](https://github.com/google/pyglove/commit/27a739253bb860e42c7266fba03e63c7b5e236d7))

- `pg.symbolic`
- Improve `init_arg_list` inference: subclasses with new fields should not inherit base class' `init_arg_list`. ([25e4c23](https://github.com/google/pyglove/commit/25e4c2349a1eb3f675e13435ffeda92cd0a9ac24))
- Fix `sym_parent` None check. ([48f23c8](https://github.com/google/pyglove/commit/48f23c8ff6f71924d854fdf3808531ac42b7d365))

- `pg.ext.evolution`
- Fix `pg.evolution.mutators.Uniform` for misaligned subchoice DNASpec after sorting the subchoices. ([c4ad652](https://github.com/google/pyglove/commit/c4ad6529b37b5533caec98c2e0d1be5e4a73e180))

- `pg.ext.early_stopping`
- Fix gating index matching logic in `pg.early_stopping.StepWise`. ([a5e0532](https://github.com/google/pyglove/commit/a5e05326f3b683caae0c593af78ccccfa4a885db))


Code Improvement

- `pg.symbolic`
- Revise `pg.Object` symbolic fields default value setting logic. ([e64d516](https://github.com/google/pyglove/commit/e64d516d1ab10b13c70ed36a47c8910b53e408d6))
- Revise schema and signature inference for `pg.Object`, `pg.Functor` and `pg.ClassWrapper`. ([8141116](https://github.com/google/pyglove/commit/8141116e49569032603c7255c9c4a88a37ab567e))

Removed APIs

- Removed `pg.generators` namespace. ([ac40ae5](https://github.com/google/pyglove/commit/ac40ae53a9bfc135350252fc81f0a2df8befd5d1))


Examples
- Add Mnist NAS example for PyTorch. ([be7dd7d](https://github.com/google/pyglove/commit/be7dd7d5a9150f95d89a54c05afdcb3a053f788b), [653bab7](https://github.com/google/pyglove/commit/653bab7bf2cbe41b563fcd219280616d3bef67a3))

New Features

* Introducing extension module `pg.mutfun` for evolving low-level functions. ([c67a1e7](https://github.com/google/pyglove/commit/c67a1e7c7b30fb059ba1658ef34083d39c0dfc61), [3c6cd7f](https://github.com/google/pyglove/commit/3c6cd7f5268ecbbd2439848747a0db6c16c32e75), [ba937c0](https://github.com/google/pyglove/commit/ba937c0c4233157456413d9c835f697bfffa4bc2))

* Add `pg.registered_types` for accessing all registered `JSONConvertible` sub-classes. ([c67a1e7](https://github.com/google/pyglove/commit/c67a1e7c7b30fb059ba1658ef34083d39c0dfc61))

Enhancements

`pg.Symbolic`:
* Added property `sym_root`. ([528aefc](https://github.com/google/pyglove/commit/528aefc056506e67802ae6e4ec90f7cf8b772be8))
* Added methods `sym_ancestor` and `sym_descendants`. ([40bc014](https://github.com/google/pyglove/commit/40bc01473b8395e4429a20e85908e6efc9a97aae))

`pg.sample`:
* Sampling of abstract search spaces (`pg.DNASpec`) is now supported ([87707c2](https://github.com/google/pyglove/commit/87707c2b042c2aeecae9cd69912a7a3cb313d2ec))

Module `pg.typing`:
* PyType annotation could be used as value spec in `pg.members`/`pg.symbolize`. ([e95505d](https://github.com/google/pyglove/commit/e95505d4a6cc72493fe1dcbc70c9a91e1bddc6c0))

Module `pg.object_utils`:
* Pushed up shared `JSONConvertible` features to `pg.object_utils` module. ([55bc482](https://github.com/google/pyglove/commit/55bc482061bfb58fd1eae257006815e0f5a113a4))

API changes.

* Removed `pg.schema` (an alias for `pg.members`). ([e25dbd9](https://github.com/google/pyglove/commit/e25dbd938953c86e1ea2630a8cbf84e690513648))