make return types picklable

[q-rosiebloxsom]

This is a quick one to help anyone using GrandCypher results downstream.

Fix pickling of query result keys (AttributeRef, IDRef, EntityRef)

Problem

The str subclasses in grandcypher/types.py that are used as result dictionary keys don't survive pickle round-trips. This breaks any downstream code that serialises GrandCypher query results — e.g. PySpark map(), multiprocessing, joblib, or caching.

AttributeRef — crashes on unpickle:

AttributeRef.__new__ takes two arguments (entity_name, attribute), but pickle's default str reconstruction only passes the single string value:

>>> pickle.loads(pickle.dumps(AttributeRef('a', 'name')))
TypeError: AttributeRef.__new__() missing 1 required positional argument: 'attribute'

IDRef — silently corrupts on unpickle:

IDRef.__new__ wraps its argument as f"ID({entity_name})". Pickle reconstructs with str(self) which is already "ID(a)", so __new__ wraps it again:

>>> pickle.loads(pickle.dumps(IDRef('a')))
'ID(ID(a))'

Root cause

Python's str pickle path calls cls.__new__(cls, str_value) on unpickle. This works when __new__ takes exactly one argument matching the string value (as with EntityRef), but breaks when:

• __new__ takes extra arguments (AttributeRef)
• __new__ transforms the argument (IDRef prepends "ID(")

Fix

Added __getnewargs__ to all three ref classes (AttributeRef, IDRef, EntityRef). This method tells pickle which arguments to pass to __new__ during reconstruction, so the original constructor arguments are preserved across serialisation.

Changes

• grandcypher/types.py — added __getnewargs__ to EntityRef, AttributeRef, and IDRef
• grandcypher/test_types.py (new) — pickle round-trip tests for each ref class individually, plus an end-to-end test that pickles the full result dict from a GrandCypher.run() query

[codspeed-hq]

Merging this PR will not alter performance

✅ 99 untouched benchmarks

---

_{Comparing q-rosiebloxsom:make-results-picklable (3782fa0) with master (18a2af5)}

[j6k4m8]

Great feature!