pygx 0.2.0__py3-none-any.whl

pygx/__init__.py

@@ -0,0 +1,600 @@
+# Copyright 2026 Daiyi Peng.
+#
+# Derived from PyGlove (https://github.com/google/pyglove), originally
+# authored by Daiyi Peng et al. as "PyGlove Authors" and released
+# under the Apache License, Version 2.0.
+#
+# 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.
+
+"""Package pygx.
+
+This package is the facade of the public PyGX library, which includes modules
+for symbolic type definition and manipulation, symbolic typing and constraints,
+symbolic value generation and etc. It only has a handful of dependencies such
+as enum, six, yaml.
+
+Top-level sub-packages:
+
+  pygx
+   |__ symbolic        :  Symbolic program constructs and operations.
+   |__ typing          :  Runtime type check and value validation.
+   |__ geno            :  Genome types for program generation/manipulation.
+   |__ hyper           :  Encoding/Decoding between a program and a genome.
+   |__ tuning          :  Interface for program tuning with a local backend.
+   |__ detouring       :  Detouring classes creation without symbolic types.
+   |__ patching        :  Patching a program with URL-like strings.
+   |__ formatting      :  String formatting primitives (Formattable, format,
+                          print, colored, ...).
+   |__ topology        :  Tree topology primitives (KeyPath, MISSING_VALUE,
+                          MaybePartial, traverse, transform, merge, ...).
+   |__ wire            :  Wire formats for serialization (WireConvertible,
+                          to_json, from_json, registered_types, ...).
+   |__ contextual      :  Context-scoped value overrides.
+   |__ error_handling  :  catch_errors, match_error, ErrorInfo.
+   |__ views           :  Object visualization.
+   |__ io              :  IO abstractions.
+   |__ coding          :  Code generation, parsing, execution.
+   |__ instrument      :  Instrumentation utilities (logging, monitoring,
+                          timing).
+   |__ importing       :  Module dependency inspection and reload helpers.
+   |__ concurrent      :  Concurrent execution with retry and progress.
+   |__ algo            :  Algorithm sub-packages (scalars, mutfun, evolution,
+                          early_stopping).
+"""
+
+__all__ = [
+    'symbolic',
+    'active_core',
+    'allow_empty_field_description',
+    'allow_repeated_class_registration',
+    'set_origin_stacktrace_limit',
+    'allow_partial',
+    'allow_writable_accessors',
+    'auto_call_functors',
+    'notify_on_change',
+    'notify_once',
+    'enable_type_debug',
+    'is_type_debug_enabled',
+    'warn_on_field_override_no_annotation',
+    'is_warn_on_field_override_no_annotation_enabled',
+    'warn_on_capability_narrowing',
+    'is_warn_on_capability_narrowing_enabled',
+    'track_origin',
+    'as_sealed',
+    'Symbolic',
+    'PureSymbolic',
+    'Dict',
+    'dict',
+    'List',
+    'list',
+    'Object',
+    'ClassWrapper',
+    'Functor',
+    'Inferentiable',
+    'InferredValue',
+    'Ref',
+    'maybe_ref',
+    'ErrorInfo',
+    'members',
+    'field',
+    'symbolize',
+    'functor',
+    'functor_class',
+    'wrap',
+    'wrap_module',
+    'compound',
+    'compound_class',
+    'boilerplate_class',
+    'ContextualObject',
+    'apply_wrappers',
+    'eq',
+    'ne',
+    'lt',
+    'gt',
+    'hash',
+    'clone',
+    'TraverseAction',
+    'traverse',
+    'query',
+    'contains',
+    'is_abstract',
+    'is_pure_symbolic',
+    'is_deterministic',
+    'Diff',
+    'diff',
+    'from_json',
+    'from_json_str',
+    'to_json',
+    'to_json_str',
+    'serialize',
+    'deserialize',
+    'save',
+    'load',
+    'open_jsonl',
+    'get_load_handler',
+    'set_load_handler',
+    'get_save_handler',
+    'set_save_handler',
+    'Origin',
+    'FieldUpdate',
+    'Insertion',
+    'WritePermissionError',
+    'SymbolicModeError',
+    'typing',
+    'KeySpec',
+    'ValueSpec',
+    'Field',
+    'Schema',
+    'CustomTyping',
+    'validate',
+    'signature',
+    'schema',
+    'geno',
+    'DNA',
+    'DNASpec',
+    'DNAGenerator',
+    'random_dna',
+    'hyper',
+    'template',
+    'oneof',
+    'manyof',
+    'permutate',
+    'floatv',
+    'evolve',
+    'one_of',
+    'sublist_of',
+    'float_value',
+    'search_space',
+    'dna_spec',
+    'materialize',
+    'iter',
+    'random_sample',
+    'tuning',
+    'sample',
+    'poll_result',
+    'detouring',
+    'detour',
+    'patching',
+    'patch',
+    'patcher',
+    'patch_on_key',
+    'patch_on_path',
+    'patch_on_value',
+    'patch_on_type',
+    'patch_on_member',
+    'ObjectFactory',
+    'from_uri',
+    'formatting',
+    'topology',
+    'wire',
+    'contextual',
+    'error_handling',
+    'KeyPath',
+    'KeyPathSet',
+    'MISSING_VALUE',
+    'MissingValue',
+    'Formattable',
+    'repr_format',
+    'str_format',
+    'MaybePartial',
+    'WireConvertible',
+    'WireValue',
+    'WireFormat',
+    'JsonFormat',
+    'YamlFormat',
+    'register_format',
+    'get_format',
+    'DocStr',
+    'registered_types',
+    'is_partial',
+    'format',
+    'print',
+    'docstr',
+    'catch_errors',
+    'match_error',
+    'timeit',
+    'colored',
+    'decolor',
+    'views',
+    'view',
+    'view_options',
+    'View',
+    'Html',
+    'to_html',
+    'to_html_str',
+    'controls',
+    'io',
+    'coding',
+    'instrument',
+    'logging',
+    'monitoring',
+    'importing',
+    'reload',
+    'concurrent',
+    'algo',
+]
+
+# pylint: disable=invalid-name,wrong-import-position
+# pylint: disable=g-bad-import-order
+# pylint: disable=unused-import
+# pylint: disable=reimported
+# pylint: disable=g-import-not-at-top
+# pylint: disable=redefined-builtin
+# pylint: disable=import-outside-toplevel
+
+
+#
+# Active symbolic core (the PYGX_CORE differential switch).
+#
+
+from pygx import _core as _core
+
+# Validate $PYGX_CORE eagerly so a typo fails at import rather than silently
+# falling back to the oracle. See pygx/_core.py and
+# docs/design/dual-core-design.md.
+active_core = _core.active_core
+active_core()
+
+#
+# Symbols from 'symbolic' sub-module.
+#
+
+from pygx import symbolic as symbolic
+
+# Global flags.
+allow_empty_field_description = symbolic.allow_empty_field_description
+allow_repeated_class_registration = symbolic.allow_repeated_class_registration
+set_origin_stacktrace_limit = symbolic.set_origin_stacktrace_limit
+
+# Context manager for scoped flags.
+allow_partial = symbolic.allow_partial
+allow_writable_accessors = symbolic.allow_writable_accessors
+auto_call_functors = symbolic.auto_call_functors
+notify_on_change = symbolic.notify_on_change
+notify_once = symbolic.notify_once
+enable_type_debug = symbolic.enable_type_debug
+is_type_debug_enabled = symbolic.is_type_debug_enabled
+warn_on_field_override_no_annotation = (
+    symbolic.warn_on_field_override_no_annotation
+)
+is_warn_on_field_override_no_annotation_enabled = (
+    symbolic.is_warn_on_field_override_no_annotation_enabled
+)
+warn_on_capability_narrowing = symbolic.warn_on_capability_narrowing
+is_warn_on_capability_narrowing_enabled = (
+    symbolic.is_warn_on_capability_narrowing_enabled
+)
+track_origin = symbolic.track_origin
+as_sealed = symbolic.as_sealed
+
+# Symbolic types.
+Symbolic = symbolic.Symbolic
+PureSymbolic = symbolic.PureSymbolic
+
+Dict = symbolic.Dict
+dict = Dict  # pylint: disable=redefined-builtin
+
+List = symbolic.List
+list = List  # pylint: disable=redefined-builtin
+
+Object = symbolic.Object
+ClassWrapper = symbolic.ClassWrapper
+Functor = symbolic.Functor
+
+# Inferentiable base classes.
+Inferentiable = symbolic.Inferential
+InferredValue = symbolic.InferredValue
+
+# Reference types.
+Ref = symbolic.Ref
+maybe_ref = symbolic.maybe_ref
+
+# Decorator for declaring symbolic. members for `pg.Object`.
+members = symbolic.members
+
+# Field descriptor for `pg.Object` dataclass-like fields (PEP 681).
+field = symbolic.field
+
+#
+# Methods for making symbolic types.
+#
+
+# Function/Decorator for symbolizing existing types.
+symbolize = symbolic.symbolize
+
+# Decorator for converting a function into `pg.Functor`.
+functor = symbolic.functor
+
+# Method for making a functor class out from a function.
+functor_class = symbolic.functor_class
+
+# Function for wrapping a single class.
+wrap = symbolic.wrap
+
+# Function for wrapping multiple classes under a module.
+wrap_module = symbolic.wrap_module
+
+# Decorator for creating compound class.
+compound = symbolic.compound
+
+# Function for making compound class.
+compound_class = symbolic.compound_class
+
+# Method for declaring a boilerplated class from a symbolic instance.
+boilerplate_class = symbolic.boilerplate_class
+
+# Methods for contextual objects.
+ContextualObject = symbolic.ContextualObject
+
+#
+# Context manager for swapping wrapped class with their wrappers.
+#
+
+apply_wrappers = symbolic.apply_wrappers
+
+
+# Methods for symbolic operations.
+eq = symbolic.eq
+ne = symbolic.ne
+lt = symbolic.lt
+gt = symbolic.gt
+hash = symbolic.hash  # pylint: disable=redefined-builtin
+clone = symbolic.clone
+
+# Methods for querying symbolic types.
+TraverseAction = symbolic.TraverseAction
+traverse = symbolic.traverse
+query = symbolic.query
+contains = symbolic.contains
+
+is_abstract = symbolic.is_abstract
+is_pure_symbolic = symbolic.is_pure_symbolic
+is_deterministic = symbolic.is_deterministic
+
+# Method for differentiating symbolic types.
+Diff = symbolic.Diff
+diff = symbolic.diff
+
+# Methods for serializing/deserializing symbolic types.
+from_json = symbolic.from_json
+from_json_str = symbolic.from_json_str
+to_json = symbolic.to_json
+to_json_str = symbolic.to_json_str
+save = symbolic.save
+load = symbolic.load
+open_jsonl = symbolic.open_jsonl
+get_load_handler = symbolic.get_load_handler
+set_load_handler = symbolic.set_load_handler
+get_save_handler = symbolic.get_save_handler
+set_save_handler = symbolic.set_save_handler
+
+# Auxiliary classes:
+Origin = symbolic.Origin
+FieldUpdate = symbolic.FieldUpdate
+Insertion = symbolic.Insertion
+WritePermissionError = symbolic.WritePermissionError
+SymbolicModeError = symbolic.SymbolicModeError
+
+#
+# Symbols from 'typing' sub-module.
+#
+
+from pygx import typing as typing
+
+# Promote the following concepts to top level as they may be used in pytype
+# annotation frequently.
+KeySpec = typing.KeySpec
+ValueSpec = typing.ValueSpec
+Field = typing.Field
+Schema = typing.Schema
+CustomTyping = typing.CustomTyping
+
+# The TypeAdapter-style one-liner (#520): validate a bare value against a
+# type annotation (`pg.validate([1, 2], list[int])`).
+validate = typing.validate
+
+signature = typing.signature
+schema = typing.schema
+
+
+#
+# Symbols from 'geno' sub-module.
+#
+
+from pygx import geno as geno
+
+DNA = geno.DNA
+DNASpec = geno.DNASpec
+DNAGenerator = geno.DNAGenerator
+
+random_dna = geno.random_dna
+
+
+#
+# Symbols from 'hyper' sub-module.
+#
+
+from pygx import hyper as hyper
+
+# Methods for creating hyper values.
+template = hyper.template
+
+oneof = hyper.oneof
+manyof = hyper.manyof
+permutate = hyper.permutate
+floatv = hyper.floatv
+evolve = hyper.evolve
+
+# Aliases for backward compatibility.
+one_of = hyper.one_of
+sublist_of = hyper.sublist_of
+float_value = hyper.float_value
+search_space = hyper.search_space
+
+# Helper methods for operating with hyper values.
+dna_spec = hyper.search_space
+materialize = hyper.materialize
+
+iter = hyper.iterate  # pylint: disable=redefined-builtin
+random_sample = hyper.random_sample
+
+
+#
+# Symbols from 'tuning' sub-module.
+#
+
+from pygx import tuning as tuning
+
+sample = tuning.sample
+poll_result = tuning.poll_result
+
+
+#
+# Symbols from 'detouring' sub-module.
+#
+
+from pygx import detouring as detouring
+
+detour = detouring.detour
+
+
+#
+# Symbols from 'patching' sub-module.
+#
+
+from pygx import patching as patching
+
+patch = patching.patch
+patcher = patching.patcher
+patch_on_key = patching.patch_on_key
+patch_on_path = patching.patch_on_path
+patch_on_value = patching.patch_on_value
+patch_on_type = patching.patch_on_type
+patch_on_member = patching.patch_on_member
+ObjectFactory = patching.ObjectFactory
+
+# ``pg.from_uri`` builds a symbolic object from a URI string. Distinct from
+# ``pg.patching.from_uri``, which resolves a URI to a registered ``Patcher``.
+from_uri = symbolic.from_uri
+
+#
+# Cross-cutting low-level submodules (no `pg.utils` anymore).
+#
+
+from pygx import contextual as contextual
+from pygx import error_handling as error_handling
+from pygx import formatting as formatting
+from pygx import topology as topology
+from pygx import wire as wire
+
+KeyPath = topology.KeyPath
+KeyPathSet = topology.KeyPathSet
+MISSING_VALUE = topology.MISSING_VALUE
+MissingValue = topology.MissingValue
+
+Formattable = formatting.Formattable
+repr_format = formatting.repr_format
+str_format = formatting.str_format
+
+MaybePartial = topology.MaybePartial
+WireConvertible = wire.WireConvertible
+WireValue = wire.WireValue
+WireFormat = wire.WireFormat
+JsonFormat = wire.JsonFormat
+YamlFormat = wire.YamlFormat
+register_format = wire.register_format
+get_format = wire.get_format
+serialize = wire.serialize
+deserialize = wire.deserialize
+DocStr = typing.DocStr
+
+registered_types = wire.registered_types
+
+is_partial = topology.is_partial
+format = formatting.format  # pylint: disable=redefined-builtin
+print = formatting.printv  # pylint: disable=redefined-builtin
+docstr = typing.docstr
+catch_errors = error_handling.catch_errors
+match_error = error_handling.match_error
+ErrorInfo = error_handling.ErrorInfo
+
+colored = formatting.colored
+decolor = formatting.decolor
+
+# Symbols from 'views' sub-module.
+
+from pygx import views as views
+
+view = views.view
+view_options = views.view_options
+View = views.View
+Html = views.Html
+to_html = views.to_html
+to_html_str = views.to_html_str
+
+#
+# Symbols from `io` sub-module.
+#
+
+#
+# Symbols from `coding` sub-module.
+#
+from pygx import coding as coding
+
+#
+# Symbols from `instrument` sub-package.
+#
+from pygx import instrument as instrument
+from pygx import io as io
+
+# `controls` is lazily attached to `pygx.views.html` via a module-level
+# `__getattr__` (see `pygx/views/html/__init__.py`) to avoid the circular
+# dependency between `pygx.views.html` and `pygx.symbolic`. Re-export here so
+# `pg.controls` keeps working.
+from pygx.views.html import controls as controls
+
+# Top-level shortcuts for the instrumentation modules.
+logging = instrument.logging
+monitoring = instrument.monitoring
+timeit = instrument.timeit
+
+#
+# Symbols from `importing` sub-package.
+#
+from pygx import importing as importing
+
+reload = importing.reload
+
+
+#
+# Algorithm sub-packages.
+#
+# `pygx.algo` and `pygx.concurrent` are bound to lazy-loading proxies:
+# importing the four algo subpackages eagerly costs ~70 ms but is rarely
+# needed by code that just uses pygx's symbolic/typing/io machinery. The
+# proxy executes the subpackage's body on first non-introspection attribute
+# access; users who actually need them can either `import pygx.algo`
+# directly or simply access `pg.algo.X`.
+
+# Placeholder for Google-internal imports.
+
+algo = importing.lazy_load('pygx.algo')
+concurrent = importing.lazy_load('pygx.concurrent')
+
+
+# pylint: enable=g-import-not-at-top
+# pylint: enable=reimported
+# pylint: enable=unused-import
+# pylint: enable=g-bad-import-order
+
+__version__ = '0.2.0'