Merge origin/main into pre-commit-ci-update-config

Author: saulshanabrook

.github/workflows/update-changelog.yml

@@ -0,0 +1,52 @@
+name: Update Changelog
+
+on:
+  pull_request:
+    types: [opened, edited]
+
+jobs:
+  update-changelog:
+    # Only run if this is not a PR from a fork to avoid permission issues
+    # and not a commit made by GitHub Action to avoid infinite loops
+    if: github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # Checkout the PR head ref
+          ref: ${{ github.event.pull_request.head.ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      
+      - name: Update changelog
+        run: |
+          python modify_changelog.py update_changelog \
+            "${{ github.event.pull_request.number }}" \
+            "${{ github.event.pull_request.title }}"
+      
+      - name: Check for changes
+        id: changes
+        run: |
+          if git diff --quiet docs/changelog.md; then
+            echo "changed=false" >> $GITHUB_OUTPUT
+          else
+            echo "changed=true" >> $GITHUB_OUTPUT
+          fi
+      
+      - name: Commit and push changes
+        if: steps.changes.outputs.changed == 'true'
+        run: |
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+          git add docs/changelog.md
+          git commit -m "Add changelog entry for PR #${{ github.event.pull_request.number }}"
+          git push

.github/workflows/version.yml

@@ -39,7 +39,7 @@ jobs:
       - run: |
           git config user.name github-actions[bot]
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-          VERSION=$(python increment_version.py $TYPE)
+          VERSION=$(python modify_changelog.py bump_version $TYPE)
           git checkout -b "version-$VERSION"
           git commit -am "Version $VERSION"
           git push -u origin HEAD

docs/changelog.md

@@ -4,11 +4,17 @@ _This project uses semantic versioning_
 
 ## UNRELEASED
 
+- Add ability to parse egglog expressions into Python values [#319](https://github.com/egraphs-good/egglog-python/pull/319)
+  - Deprecates `.eval()` method on primitives in favor of `.value` which can be used with pattern matching.
+- Support methods like on expressions [#315](https://github.com/egraphs-good/egglog-python/pull/315)
+- Automatically Create Changelog Entry for PRs [#313](https://github.com/egraphs-good/egglog-python/pull/313)
 - Upgrade egglog which includes new backend.
   - Fixes implementation of the Python Object sort to work with objects with dupliating hashes but the same value.
     Also changes the representation to be an index into a list instead of the ID, making egglog programs more deterministic.
   - Prefix constant declerations and unbound variables to not shadow let variables
   - BREAKING: Remove `simplify` since it was removed upstream. You can manually replace it with an insert, run, then extract.
+- Change how anonymous functions are converted to remove metaprogramming and lift only the unbound variables as args
+- Add support for getting the "value" of a function type with `.eval()`, i.e. `assert UnstableFn(f).eval() == f`.
 
 ## 10.0.2 (2025-06-22)
 

docs/reference/contributing.md

@@ -84,6 +84,10 @@ or bug fixes.
 
 When you are ready to submit your changes, please open a pull request. The CI will run the tests and check the code style.
 
+#### Changelog Automation
+
+When you open a pull request, a GitHub Action automatically adds an entry to the UNRELEASED section of the changelog using your PR title and number. This ensures the changelog stays up-to-date without manual intervention.
+
 ## Documentation
 
 We use the [Diátaxis framework](https://diataxis.fr/) to organize our documentation. The "explanation" section has

docs/reference/egglog-translation.md

@@ -340,7 +340,7 @@ and also will make sure the variables won't be used outside of the scope of the
 # egg: (rewrite (Mul a b) (Mul b a))
 # egg: (rewrite (Add a b) (Add b a))
 
-@egraph.register
+@EGraph().register
 def _math(a: Math, b: Math):
     yield rewrite(a * b).to(b * a)
     yield rewrite(a + b).to(b + a)

docs/reference/python-integration.md

@@ -6,17 +6,88 @@ file_format: mystnb
 
 Alongside [the support for builtin `egglog` functionality](./egglog-translation.md), `egglog` also provides functionality to more easily integrate with the Python ecosystem.
 
-## Retrieving Primitive Values
+## Retrieving Values
 
-If you have a egglog primitive, you can turn it into a Python object by using `egraph.eval(...)` method:
+If you have an egglog value, you might want to convert it from an expression to a native Python object. This is done through a number of helper functions:
+
+For a primitive value (like `i64`, `f64`, `Bool`, `String`, or `PyObject`), use `get_literal_value(expr)` or the `.value` property:
 
 ```{code-cell} python
 from __future__ import annotations
 
 from egglog import *
 
-egraph = EGraph()
-assert egraph.eval(i64(1) + 20) == 21
+assert get_literal_value(i64(42)) == 42
+assert get_literal_value(i64(42) + i64(1)) == None # This is because i64(42) + i64(1) is a call expression, not a literal
+assert i64(42).value == 42
+assert get_literal_value(f64(3.14)) == 3.14
+assert Bool(True).value is True
+assert String("hello").value == "hello"
+assert PyObject([1,2,3]).value == [1,2,3]
+```
+
+To check if an expression is a let value and get its name, use `get_let_name(expr)`:
+
+```{code-cell} python
+x = EGraph().let("my_var", i64(1))
+assert get_let_name(x) == "my_var"
+```
+
+To check if an expression is a variable and get its name, use `get_var_name(expr)`:
+
+```{code-cell} python
+from egglog import var, get_var_name
+v = var("x", i64)
+assert get_var_name(v) == "x"
+```
+
+For a callable (method, function, classmethod, or constructor), use `get_callable_fn(expr)` to get the underlying Python function:
+
+```{code-cell} python
+expr = i64(1) + i64(2)
+fn = get_callable_fn(expr)
+assert fn == i64.__add__
+```
+
+To get the arguments to a callable, use `get_callable_args(expr)`. If you want to match against a specific callable, use `get_callable_args(expr, fn)`, where `fn` is the Python function you want to match against. This will return `None` if the callable does not match the function, and if it does match, the args will be properly typed:
+
+```{code-cell} python
+assert get_callable_args(expr) == (i64(1), i64(2))
+
+assert get_callable_args(expr, i64.__add__) == (i64(1), i64(2))
+assert get_callable_args(expr, i64.__sub__) == None
+```
+
+### Pattern Matching
+
+You can use Python's structural pattern matching (`match`/`case`) to destructure egglog primitives:
+
+```{code-cell} python
+x = i64(5)
+match i64(5):
+    case i64(i):
+        print(f"Integer literal: {i}")
+```
+
+You can add custom support for pattern matching against your classes by adding `__match_args__` to your class:
+
+```python
+class MyExpr(Expr):
+    def __init__(self, value: StringLike): ...
+
+    __match_args__ = ("value",)
+
+    @method(preserve=True)
+    @property
+    def value(self) -> str:
+        match get_callable_args(self, MyExpr):
+            case (String(value),):
+                return value
+        raise ExprValueError(self, "MyExpr")
+
+match MyExpr("hello"):
+    case MyExpr(value):
+        print(f"Matched MyExpr with value: {value}")
 ```
 
 ## Python Object Sort
@@ -53,10 +124,10 @@ Creating hashable objects is safer, since while the rule might create new Python
 
 ### Retrieving Python Objects
 
-Like other primitives, we can retrieve the Python object from the e-graph by using the `egraph.eval(...)` method:
+Like other primitives, we can retrieve the Python object from the e-graph by using the `.value` property:
 
 ```{code-cell} python
-assert egraph.eval(lst) == [1, 2, 3]
+assert lst.value == [1, 2, 3]
 ```
 
 ### Builtin methods
@@ -66,29 +137,29 @@ Currently, we only support a few methods on `PyObject`s, but we plan to add more
 Conversion to/from a string:
 
 ```{code-cell} python
-egraph.eval(PyObject('hi').to_string())
+EGraph().extract(PyObject('hi').to_string())
 ```
 
 ```{code-cell} python
-egraph.eval(PyObject.from_string("1"))
+EGraph().extract(PyObject.from_string("1"))
 ```
 
 Conversion from an int:
 
 ```{code-cell} python
-egraph.eval(PyObject.from_int(1))
+EGraph().extract(PyObject.from_int(1))
 ```
 
 We also support evaluating arbitrary Python code, given some locals and globals. This technically allows us to implement any Python method:
 
 ```{code-cell} python
-egraph.eval(py_eval("1 + 2"))
+EGraph().extract(py_eval("1 + 2"))
 ```
 
 Executing Python code is also supported. In this case, the return value will be the updated globals dict, which will be copied first before using.
 
 ```{code-cell} python
-egraph.eval(py_exec("x = 1 + 2"))
+EGraph().extract(py_exec("x = 1 + 2"))
 ```
 
 Alongside this, we support a function `dict_update` method, which can allow you to combine some local egglog expressions alongside, say, the locals and globals of the Python code you are evaluating.
@@ -100,7 +171,7 @@ def my_add(a, b):
 
 amended_globals = PyObject(globals()).dict_update("one", 1)
 evalled = py_eval("my_add(one,  2)", locals(), amended_globals)
-assert egraph.eval(evalled) == 3
+assert EGraph().extract(evalled).value == 3
 ```
 
 ### Simpler Eval
@@ -116,7 +187,7 @@ def my_add(a, b):
     return a + b
 
 evalled = py_eval_fn(lambda a: my_add(a, 2))(1)
-assert egraph.eval(evalled) == 3
+assert EGraph().extract(evalled).value == 3
 ```
 
 ## Functions
@@ -263,10 +334,12 @@ class Boolean(Expr):
         # Run until the e-graph saturates
         egraph.run(10)
         # Extract the Python object from the e-graph
-        return egraph.eval(self.to_py())
-
-    def to_py(self) -> PyObject:
-        ...
+        value = EGraph().extract(self)
+        if value == TRUE:
+            return True
+        elif value == FALSE:
+            return False
+        raise ExprValueError(self, "Boolean expression must be TRUE or FALSE")
 
     def __or__(self, other: Boolean) -> Boolean:
         ...
@@ -278,8 +351,6 @@ FALSE = egraph.constant("FALSE", Boolean)
 @egraph.register
 def _bool(x: Boolean):
     return [
-        set_(TRUE.to_py()).to(PyObject(True)),
-        set_(FALSE.to_py()).to(PyObject(False)),
         rewrite(TRUE | x).to(TRUE),
         rewrite(FALSE | x).to(x),
     ]
@@ -303,6 +374,11 @@ Note that the following list of methods are only supported as "preserved" since
 - `__iter_`
 - `__index__`
 
+If you want to register additional methods as always preserved and defined on the `Expr` class itself, if needed
+instead of the normal mechanism which relies on `__getattr__`, you can call `egglog.define_expr_method(name: str)`,
+with the name of a method. This is only needed for third party code that inspects the type object itself to see if a
+method is defined instead of just attempting to call it.
+
 ### Reflected methods
 
 Note that reflected methods (i.e. `__radd__`) are handled as a special case. If defined, they won't create their own egglog functions.