pygx-core 0.1.0__tar.gz

pygx_core-0.1.0/.cargo/config.toml

@@ -0,0 +1,7 @@
+# macOS: CPython symbols are resolved at load time (the interpreter provides
+# them), so allow undefined symbols at link time for the extension cdylib.
+[target.x86_64-apple-darwin]
+rustflags = ["-C", "link-arg=-undefined", "-C", "link-arg=dynamic_lookup"]
+
+[target.aarch64-apple-darwin]
+rustflags = ["-C", "link-arg=-undefined", "-C", "link-arg=dynamic_lookup"]

pygx_core-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+/target
+*.so
+*.dylib
+__pycache__/
+*.egg-info/

pygx_core-0.1.0/Cargo.lock

@@ -0,0 +1,182 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "inventory"
+version = "0.3.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4f0c30c76f2f4ccee3fe55a2435f691ca00c0e4bd87abe4f4a851b1d4dac39b"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pygx-core"
+version = "0.1.0"
+dependencies = [
+ "pyo3",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab53c047fcd1a1d2a8820fe84f05d6be69e9526be40cb03b73f86b6b03e6d87d"
+dependencies = [
+ "indoc",
+ "inventory",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b455933107de8642b4487ed26d912c2d899dec6114884214a0b3bb3be9261ea6"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c85c9cbfaddf651b1221594209aed57e9e5cff63c4d11d1feead529b872a089"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0a5b10c9bf9888125d917fb4d2ca2d25c8df94c7ab5a52e13313a07e050a3b02"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "03b51720d314836e53327f5871d4c0cfb4fb37cc2c4a11cc71907a86342c40f9"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"

pygx_core-0.1.0/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "pygx-core"
+version = "0.1.0"
+edition = "2021"
+publish = false
+description = "Minimal compiled core for pygx: Rust-validated symbolic storage for pg.Object."
+license = "Apache-2.0"
+readme = "README.md"
+
+# The compiled module is `pygx_core._native`. The minimal core keeps `pg.Object`
+# a Python class and only accelerates field validation + symbolic storage, so it
+# needs ONLY the high-level `pyo3` bindings — no raw `pyo3-ffi` (that was the
+# full-native attempt's heap-type machinery, deliberately dropped here).
+[lib]
+name = "_native"
+crate-type = ["cdylib"]
+
+[dependencies]
+# `multiple-pymethods`: the value-spec pyclasses split their `#[pymethods]` into
+# a macro-generated common block (shared `ValueSpecBase` surface) and a per-type
+# hand-written block (`#[new]` / getters / `from_json` / `with_type_args`).
+# Keeping them in two blocks isolates the macro-def vs call-site token hygiene
+# that a single merged block trips over (a `**kwargs` resolution clash).
+pyo3 = { version = "0.27", features = ["extension-module", "multiple-pymethods"] }
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1

pygx_core-0.1.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: pygx-core
+Version: 0.1.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Summary: Compiled native core for pygx: Rust-backed symbolic storage and construct/attribute fast paths for pg.Object.
+Keywords: pygx,symbolic,rust,pyo3
+Author-email: PyGX Authors <pygx-authors@google.com>
+License: Apache-2.0
+Requires-Python: >=3.11, <3.15
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/free-solo/pygx
+Project-URL: Repository, https://github.com/free-solo/pygx
+
+# pygx-core
+
+The compiled **native core** for [PyGX](https://github.com/free-solo/pygx): a
+Rust ([PyO3](https://pyo3.rs)) extension that backs `pg.Object` and the symbolic
+containers with native storage and construct/attribute fast paths, reaching
+dataclass/pydantic-level performance while preserving the full symbolic feature
+set.
+
+This package exposes the `pygx_core` module (the `pygx_core._native` extension).
+It never imports `pygx`; `pygx` selects it via the `PYGX_CORE` environment
+variable and integrates through a marker/callback contract.
+
+Install `pygx` to use it — `pygx-core` is its compiled accelerator, not a
+standalone library.
+
+## Compatibility
+
+Per-version wheels are published for CPython 3.11–3.14 on Linux, macOS, and
+Windows. The extension is **not** abi3 (limited-API) compatible: it installs raw
+`PyTypeObject` slots that depend on the concrete CPython type layout.
+
+## License
+
+Apache License 2.0.
+

pygx_core-0.1.0/README.md

@@ -0,0 +1,24 @@
+# pygx-core
+
+The compiled **native core** for [PyGX](https://github.com/free-solo/pygx): a
+Rust ([PyO3](https://pyo3.rs)) extension that backs `pg.Object` and the symbolic
+containers with native storage and construct/attribute fast paths, reaching
+dataclass/pydantic-level performance while preserving the full symbolic feature
+set.
+
+This package exposes the `pygx_core` module (the `pygx_core._native` extension).
+It never imports `pygx`; `pygx` selects it via the `PYGX_CORE` environment
+variable and integrates through a marker/callback contract.
+
+Install `pygx` to use it — `pygx-core` is its compiled accelerator, not a
+standalone library.
+
+## Compatibility
+
+Per-version wheels are published for CPython 3.11–3.14 on Linux, macOS, and
+Windows. The extension is **not** abi3 (limited-API) compatible: it installs raw
+`PyTypeObject` slots that depend on the concrete CPython type layout.
+
+## License
+
+Apache License 2.0.

pygx_core-0.1.0/pygx_core/__init__.py

@@ -0,0 +1,131 @@
+# Copyright 2026 Daiyi Peng.
+#
+# 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.
+"""pygx_core — the native (Rust) symbolic core for pygx.
+
+Built milestone by milestone so ``pg.Object`` and the symbolic containers reach
+dataclass/pydantic performance. The core never imports ``pygx`` (the import-cycle
+constraint); it integrates with the oracle only through markers and injected
+callbacks (see ``docs/design/rust-core/native-core-rewrite.md`` and
+``minimal-core-contract.md``).
+
+Today the public surface is just the ABI handshake; native types land per
+milestone. The compiled engine is ``pygx_core._native``.
+"""
+
+# `_native` is the compiled extension pylint cannot introspect.
+# pylint: disable=no-name-in-module,import-error
+from pygx_core._native import abi_version
+from pygx_core._native import format
+from pygx_core._native import kvlist_str
+from pygx_core._native import Any
+from pygx_core._native import Bool
+from pygx_core._native import Callable
+from pygx_core._native import ConstStrKey
+from pygx_core._native import Dict
+from pygx_core._native import Enum
+from pygx_core._native import Functor
+from pygx_core._native import Field
+from pygx_core._native import Float
+from pygx_core._native import Int
+from pygx_core._native import KeyPath
+from pygx_core._native import KeyPathSet
+from pygx_core._native import List
+from pygx_core._native import ListKey
+from pygx_core._native import Str
+from pygx_core._native import StrKey
+from pygx_core._native import Object
+from pygx_core._native import Schema
+from pygx_core._native import SymDict
+from pygx_core._native import SymFieldGetter
+from pygx_core._native import SymObject
+from pygx_core._native import Tuple
+from pygx_core._native import TupleKey
+from pygx_core._native import Type
+from pygx_core._native import Union
+
+# Underscore-prefixed: the oracle seam injects its markdown-isolation callbacks
+# (`_install_formatting_bridge`) and the value-spec pipeline's oracle handles
+# (`_install_typing_bridge`) through these; not part of the public surface.
+from pygx_core._native import (
+    _install_formatting_bridge as _install_formatting_bridge,
+)
+from pygx_core._native import (
+    _install_typing_bridge as _install_typing_bridge,
+)
+from pygx_core._native import (
+    _install_json_schema_fn as _install_json_schema_fn,
+)
+from pygx_core._native import (
+    _install_field_from_annotation as _install_field_from_annotation,
+)
+from pygx_core._native import (
+    _install_container_bridge as _install_container_bridge,
+)
+from pygx_core._native import (
+    _install_object_bridge as _install_object_bridge,
+)
+from pygx_core._native import (
+    _install_native_tp_init as _install_native_tp_init,
+)
+from pygx_core._native import (
+    _install_native_tp_getattro as _install_native_tp_getattro,
+)
+from pygx_core._native import (
+    _install_native_tp_getattro_fast as _install_native_tp_getattro_fast,
+)
+
+# flags-native — the five hot `flags.*` thread-local scope ops + their id
+# constants, driven by the `pygx/symbolic/_flags.py` seam under the rust core.
+from pygx_core._native import _flag_scope_get as _flag_scope_get
+from pygx_core._native import _flag_scope_set as _flag_scope_set
+from pygx_core._native import _flag_scope_has as _flag_scope_has
+from pygx_core._native import _flag_scope_del as _flag_scope_del
+from pygx_core._native import _FLAG_SEALED as _FLAG_SEALED
+from pygx_core._native import _FLAG_ACCESSOR_WRITABLE as _FLAG_ACCESSOR_WRITABLE
+from pygx_core._native import _FLAG_ALLOW_PARTIAL as _FLAG_ALLOW_PARTIAL
+from pygx_core._native import _FLAG_ORIGIN_TRACKING as _FLAG_ORIGIN_TRACKING
+from pygx_core._native import (
+    _FLAG_CHANGE_NOTIFICATION as _FLAG_CHANGE_NOTIFICATION,
+)
+
+__all__ = [
+    'abi_version',
+    'format',
+    'kvlist_str',
+    'Any',
+    'Bool',
+    'Callable',
+    'ConstStrKey',
+    'Dict',
+    'Enum',
+    'Field',
+    'Functor',
+    'Float',
+    'Int',
+    'KeyPath',
+    'KeyPathSet',
+    'List',
+    'ListKey',
+    'Str',
+    'StrKey',
+    'Object',
+    'Schema',
+    'SymDict',
+    'SymFieldGetter',
+    'SymObject',
+    'Tuple',
+    'TupleKey',
+    'Type',
+    'Union',
+]

pygx_core-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["maturin>=1.13,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "pygx-core"
+version = "0.1.0"
+description = "Compiled native core for pygx: Rust-backed symbolic storage and construct/attribute fast paths for pg.Object."
+readme = "README.md"
+requires-python = ">=3.11,<3.15"
+license = { text = "Apache-2.0" }
+authors = [{ name = "PyGX Authors", email = "pygx-authors@google.com" }]
+keywords = ["pygx", "symbolic", "rust", "pyo3"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Rust",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: Implementation :: CPython",
+]
+
+[project.urls]
+Homepage = "https://github.com/free-solo/pygx"
+Repository = "https://github.com/free-solo/pygx"
+
+[tool.maturin]
+# The Rust cdylib is the `pygx_core._native` extension; the thin `pygx_core`
+# Python package (./pygx_core) is the public surface. The core never imports
+# pygx — it integrates with the oracle only via markers + injected callbacks
+# (see docs/design/rust-core/minimal-core-contract.md).
+module-name = "pygx_core._native"
+python-source = "."

pygx_core-0.1.0/rebuild.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Rebuild pygx_core and install it NON-EDITABLE into the core-dev venv.
+#
+# WHY a venv + non-editable wheel (not the editable .pth + `maturin develop`):
+# a multi-file PyO3 crate OOM-crashes (SIGKILL) on import under the editable
+# `.pth` layout. A clean venv with the wheel in site-packages is stable.
+#
+# Dev loop:
+#   pygx-core/rebuild.sh                            # build wheel + reinstall
+#   .venv-coredev/bin/python -m pytest ...          # run tests under the venv
+#
+# One-time venv setup (if .venv-coredev is missing):
+#   /opt/homebrew/bin/python3.13 -m venv .venv-coredev
+#   .venv-coredev/bin/pip install -U pip maturin pytest pytest-xdist pytest-cov
+#   .venv-coredev/bin/pip install -e .              # pygx (oracle) + deps
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+VENV="${PYGX_COREDEV_VENV:-$REPO_ROOT/.venv-coredev}"
+CRATE_DIR="$REPO_ROOT/pygx-core"
+PY="$VENV/bin/python"
+
+if [[ ! -x "$PY" ]]; then
+  echo "core-dev venv not found at $VENV — see the one-time setup in this script." >&2
+  exit 1
+fi
+
+cd "$CRATE_DIR"
+rm -rf target/wheels
+# `env -u CONDA_PREFIX`: maturin warns / misbehaves when a conda env leaks in.
+env -u CONDA_PREFIX "$VENV/bin/maturin" build --release -i "$PY" >&2
+WHL="$(ls -t target/wheels/*.whl | head -1)"
+# --no-deps: the wheel declares no real index deps (the oracle pygx is the
+# sibling editable package, already installed). --force-reinstall: always pick
+# up the freshly-built extension.
+"$VENV/bin/pip" install -q --force-reinstall --no-deps "$WHL"
+echo "installed $WHL into $VENV" >&2

pygx_core-0.1.0/run-differential.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Differential harness — run the FULL oracle test suite under BOTH cores.
+#
+# This is the safety net for the native-core rewrite: the pure-Python oracle is
+# the frozen reference, and every milestone must keep the native core
+# behaviour-identical. The suite asserts oracle behaviour, so "green under both
+# PYGX_CORE values" == "no divergence". A failure under `rust` that passes under
+# `python` is a native-core regression. See
+# docs/design/rust-core/native-core-rewrite.md §6 (M0 builds this first).
+#
+# Runs in the core-dev venv (the only place the crate is built; the oracle CI
+# never builds it — see pygx-core/rebuild.sh). Rebuilds the crate first unless
+# PYGX_DIFF_SKIP_BUILD is set.
+#
+# Usage:
+#   pygx-core/run-differential.sh                 # rebuild + both cores, full suite
+#   pygx-core/run-differential.sh pygx/symbolic   # both cores, a path subset
+#   PYGX_DIFF_SKIP_BUILD=1 pygx-core/run-differential.sh   # skip the rebuild
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+VENV="${PYGX_COREDEV_VENV:-$REPO_ROOT/.venv-coredev}"
+PY="$VENV/bin/python"
+
+if [[ ! -x "$PY" ]]; then
+  echo "core-dev venv not found at $VENV — see the one-time setup in pygx-core/rebuild.sh." >&2
+  exit 1
+fi
+
+if [[ -z "${PYGX_DIFF_SKIP_BUILD:-}" ]]; then
+  echo "=== rebuilding native core ===" >&2
+  bash "$REPO_ROOT/pygx-core/rebuild.sh"
+fi
+
+cd "$REPO_ROOT"
+status=0
+for core in python rust; do
+  echo "=== PYGX_CORE=$core ===" >&2
+  if ! PYGX_CORE="$core" "$PY" -m pytest -n auto -q "$@"; then
+    echo "!!! suite FAILED under PYGX_CORE=$core" >&2
+    status=1
+  fi
+done
+
+if [[ "$status" -eq 0 ]]; then
+  echo "=== differential OK: suite green under both cores ===" >&2
+else
+  echo "=== differential FAILED: cores diverge (see above) ===" >&2
+fi
+exit "$status"