Repository navigation
Tool API PR 2: kinds by class, DynamicCells and DynamicReferenceProxy, _is_derived(), node _get_repr() (T1–T3, T7, F1, F6, F11) - #284
Merged
Conversation
The owner decided on 2026-10-17 that tools tell modelx objects apart by
class name, after checking that the class is modelx's own
(type(v).__module__.startswith("modelx.")), and that no _kind class
attribute is added. The names of the ten classes T1 lists become frozen
tool API, with the promise that each lives in the modelx package; the
module paths stay internal. The module check is part of the recipe
because a Reference can hold a user's own class named Model or Cells
(fix-bridge-adoption/b01b).
T1 is rewritten as that recipe, re-measured on main at 1b90682: right for
every kind, nested items, a DynamicSpace, deleted objects and a closed
model's objects, None for user classes, views, nodes and plain values,
at 0.13-0.20 us. A frozen class name cannot be deprecated with a warning,
so a rename is a breaking change with a release note. The decision
moves one line of PR 1's toolapi.rst, which PR 2 changes.
Everything that read _kind follows: T5, T10's is_ref, F11's example, the
C3 wire table, the coverage table, section 5, the PR 2 plan and tests, and
the bridge and spyder adoption notes. The progress line records
#278 and #281 as merged and #282 and #283 as filed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
Two reviewers checked the decision 14 revision against the whole document and against the code on main and on 0.33.0, where the recipe gives identical answers. The recipe now checks that __module__ is a str before calling startswith: wrapt's pure-Python ObjectProxy copies a __module__ property into every proxy class, and the unguarded check raised AttributeError on it, so a Reference holding one would have failed to encode (names14/probe_edge.py). A frozen class name cannot warn, and the revision let a rename through with only a release note, which bypassed decision 2. It is now recommended, for the owner to confirm, that a listed name follows decision 2 without the warning step: marked deprecated two minor releases ahead, renamed only when the downstream job is green. Section 5 records the exception and section 9 adds it as risk 14. PR 1's page changes in three places, not one: the class-name example becomes an unlisted class, the imports bullet covers modelx.io, and the Deprecation section gains the exception. Costs are restated from one harness for both the recipe and _kind. Also corrected: the summary count of member sets, the section 3.0 example that used _kind, the 'IOSpec' kind left in section 4, the internal list in section 5, PR 2's file list, the bridge table that still said doc.get would send 'Reference', the section 8 transition note, the ExcelRange edge case, and what #281 did to cells.rst. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
…ed without a warning The owner chose, on 2026-10-17, the first of the two options for renaming one of the ten class names T1 lists: it follows decision 2 without the warning step. It is marked deprecated on toolapi.rst and in the release notes' "Deprecations" section at least two minor releases ahead, and renamed or split only when the downstream job is green, under "Backward Incompatible Changes". The other option, never renaming them, is not taken. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
…ve their own classes The owner decided on 2026-10-18 that only Spaces, Cells and References can be dynamic, and that a dynamic Cells and a proxy of a dynamic Reference get their own classes, DynamicCells (a subclass of Cells) and DynamicReferenceProxy (a subclass of ReferenceProxy). With decision 14 the class then answers "is it dynamic?", so no _is_dynamic() is added to Cells, ReferenceProxy, Model or Macro; the existing BaseSpace _is_dynamic(), frozen on PR 1's page, stays. T1's frozen set grows to twelve names. The attrdict 'type' that spyder-modelx reads stays 'Cells' and 'Reference' for the dynamic classes. T2 is rewritten: DynamicCellsImpl gets interface_cls = DynamicCells, and a proxy's class is chosen in ReferenceProxy.__new__ from the Reference's parent, which covers all six sites that make proxies (not five, as said in conversation). Everything that read _is_dynamic() on Cells or References follows: decision 4's and 7's bullets, T1, T3's compositions, T5, T10's resolved-slot test, the C3 wire table, the coverage table, section 5's behaviour changes, the PR 2 plan and tests, and the bridge, mcp and spyder adoption notes. The bridge keeps sending 'Cells' to the Studio, whose Explorer draws any other kind as a Space. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
A throwaway prototype of DynamicCells and DynamicReferenceProxy (d15/proto) gave the expected class at all six proxy sites. The spyder snapshots, the signature golden, the contract tests and model pickling were unchanged, and the bridge's 835 tests passed. The design now records that, and the corrections the review and the prototype found: - modelx-mcp 0.1.0's suite walks Cells by the exact name 'Cells' and fails 2 checks, so its release with the kind() walk ships before 0.34 (decision 15, section 8, risk 15). The unadopted bridge's wire changes too; the adopted bridge maps both new names before every comparison and send, at the sites now listed in section 7. - An ItemSpace's system bindings _self, _space and _model are dynamic by the rule, and are listed so. - The proxy rule is guarded with isinstance(impl, ReferenceImpl), so a pre-T5 slot stays a ReferenceProxy; the resolved-slot class check moves to PR 3's tests. - ReferenceProxy.__new__ takes impl=None, because copy.copy calls cls.__new__(cls) and the one-argument form made copying any proxy raise TypeError. - tree.get's 'dynamic' comes from T2's classes, not T4; spyder can tell dynamic Cells rows by their parent row, but not Reference rows. - PR 2 pins the S1-S3 members on both new classes in the golden and makes two more toolapi.rst changes; T10's is_ref takes both names. - Costs and measured rows are restated; rows measured before decision 15 say so. repr() and .info, which print the class name, are left for the owner to decide. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
…ew names printed The owner decided on 2026-10-18: - Decision 16: the Space flags _is_dynamic(), _is_static() and _is_root() are removed in 0.34, without deprecation. The class answers each of them (T1's check). No consumer calls them: the spyder-modelx plugin at 0406582, spymx-kernels 0.4.0 at 2b3d52c, modelx-bridge 0.10.0 and modelx-mcp 0.1.0 were searched; inside modelx only tests do. They are unfrozen tool API until 0.34.0, so a release note suffices; PR 1's page drops them before the release. _is_base(other) and _is_sub(other) stay. - Decision 15 amended: repr() and .info print the new class names, <DynamicCells ...> and <DynamicReferenceProxy ...>, listed under Backward Incompatible Changes. Decision 4, T2, T3, section 3.4, the C3 wire table, the coverage table, section 5's behaviour changes, the PR 2 plan (page changes, code, tests) and the bridge and spyder adoption notes follow. spyder's tree no longer plans to request _is_dynamic; a Space row is dynamic by its 'type'. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
A reviewer checked the decision 16 revision against the whole document and the code. Corrections: - The three Space flags are cited at their 0.33.0 lines, space.py:161-171, per the document's convention (161-178 is main). - They have had underscore names since v0.0.21, when they were renamed from public names; "public since v0.0.21" was wrong. - Decision 2's removal rule now says "frozen", matching approved choice 4, and section 5 says the unfrozen tier may be changed or removed. - The class check equals the flags on a live Space; a deleted Space now answers by its class, where _is_dynamic() raised. - The bridge's ItemSpace false negative is fixed by the Space's own class; on 0.33, tree.get's dynamic and inherited tests read the parent's class. - PR 2 also changes the Interface.info docstring example, the golden's S2 tuple and entries, and three test docstrings; the Space-table rows are cited exactly. - The C3 wire table drops the _is_dynamic row, with a note under it; the section 3.4 row no longer claims the bridge uses _is_base/_is_sub. - The summary mentions the removal, the conventions record the spymx-kernels checkout, and a measured row cites its tests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
… T1 tests) PR 2 of devnotes/ToolAPIDesign.md, T2 (decisions 15 and 16) and T1's tests and golden (decision 14). A tool tells what an object is, and whether modelx generated it inside an ItemSpace, from its class name after the module check, so dynamic Cells and References get classes of their own, and the Space flags that repeated the class go. Code: - cells.py: new DynamicCells(Cells), __slots__ = (); DynamicCellsImpl sets interface_cls = DynamicCells. Cells._baseattrs and Cells._get_attrdict write 'type' 'Cells', where Interface writes the class name, so the attrdict spyder-modelx reads keeps its values. - reference.py: new DynamicReferenceProxy(ReferenceProxy), and ReferenceProxy.__new__(cls, impl=None). ReferenceProxy(impl) gives a DynamicReferenceProxy when impl is a ReferenceImpl whose parent is not the model and is dynamic: an ItemSpace's arguments, the refs its Space formula returns, and the _self, _space and _model of an ItemSpace or a DynamicSpace in one. All six sites that make a proxy (ReferenceNode.obj, Model._get_object, Model._get_refs, BaseSpace._get_object, RefView._baseattrs and _get_attrdict) call ReferenceProxy(impl). The isinstance guard keeps a pre-T5 slot, which holds the item's copy of a Space or a Cells and not a Reference, a ReferenceProxy. The rule applies only when cls is ReferenceProxy, and impl defaults to None, because copy.copy calls cls.__new__(cls). - reference.py: ReferenceProxy defines __getstate__ and __setstate__ (the impl). Not in the plan: measured on 3.11.15 on 10188ae, copy.copy of any proxy gave a ReferenceProxy whose _impl was the tuple (None, {'_impl': impl}), and whose .value raised AttributeError, because from 3.11 object.__getstate__ answers before __getattr__, which forwarded __setstate__ to Interface's. The plan's test asks that copy.copy of both classes works; it now does on 3.10 and 3.11 alike. The state is the same impl either way, so what pickles is unchanged. - space.py: BaseSpace._is_dynamic(), _is_static() and _is_root() are removed (decision 16); _is_base and _is_sub stay. Nothing in modelx called them. - base.py: the Interface.info example of a Cells in an ItemSpace prints 'DynamicCells: Model1.Space1[1, 0].foo(t, i=0)' and 'is_derived: True', as it does (it showed 'Cells:', '[1]' and False), with a versionchanged note. repr() and .info print the class name, so a dynamic Cells shows as <DynamicCells M.P[1].h(x)> and an argument's proxy as <DynamicReferenceProxy M.P[1].i>. Tests changed where the plan says the behaviour changes: - test_repr.py::test_repr_cells_in_dynspace and test_cells_info.py::test_info_header_uses_class_name_and_signature expect DynamicCells (the latter also checks a static Cells' header). - test_space_inheritance.py::test_properties and test_tool_contracts.py use the class name instead of the removed flags. In test_tool_contracts.py the 0.33 fallback recipes (static_space, argument_names, refs_recipe) tell a dynamic Space by T1's recipe, which works on 0.33 too; test_cells_dynamic_recipe also checks that a Cells is a DynamicCells exactly when its parent is dynamic; test_space_kind_flags becomes test_space_kinds, checking T1's names and that no Space class defines the three flags. New tests: - core/base/test_kind.py (78): T1's recipe, defined there and imported by the other tool-API tests, gives the class name of every kind, nested P[1][5], P[1].Child[2] and DynamicSpaces included; proxies to scalar, global, Space-, Cells-valued, derived, dynbase, argument and formula-ref References; PandasData, ExcelRange (also as a Reference value, in iospecs and inside a formula) and ModuleData; None for 34 value types (29 stdlib, 5 numpy and pandas; minimal/m02's own list is not in the repository, so this one is new), for views, nodes and the Namespace objects and bound method a formula sees, for user classes named Model and Cells, a __module__ of None and a __module__ property as in wrapt; deleted objects and a closed model's; attrdict 'type' unchanged. - core/space/inheritance/test_tool_flags.py (43): the dynamic table. Space and Cells classes with derived, overriding and multiple inheritance; no kind defines the three flags; the proxy class at all six sites, the views' recorded by wrapping ReferenceProxy.__init__; copy.copy keeps class, value and ids; isinstance unchanged; 'type' 'Cells' and 'Reference' in a whole-model walk; repr() and .info. A separate section at the end is left for T3's _is_derived table. Signature golden (test_tool_api_surface.py, regenerated with --write): - removed: _is_dynamic, _is_static, _is_root on UserSpace, ItemSpace and DynamicSpace (9 entries), decision 16; - added: "kinds" section, T1's twelve names, each recorded from its object with its __name__ and whether the module check passes (12), decisions 14 and 15; DynamicCells members, as on Cells, from a Cells of proj[1] (12); DynamicReferenceProxy members (4) and forwarded names (12), as on ReferenceProxy, from the proxy of proj[1]'s argument i; - changed: none. Every DynamicCells and DynamicReferenceProxy entry equals its Cells or ReferenceProxy entry. The module docstring and a KINDS_RULE state decision 14's deprecation without a warning for a listed class name. spyder_surface_snapshot.json and spyder_requests_snapshot.json are unchanged, and their tests pass. Checked: full suite 1706 passed, 8 skipped, 1 failed (the 1570 of 10188ae plus 136 new; the failure is export/test_lifelib.py::test_assets, which needs QuantLib). The touched suites also pass on CPython 3.10 (227 passed, 1 skipped). Each changed file parses with feature_version=(3, 9). Mutation checks: undoing interface_cls, the __new__ rule, its isinstance guard, the state methods or the 'type' literal each fails the new tests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
PR 2 of devnotes/ToolAPIDesign.md, T3 and decision 11's alias. A tool asks a Cells and a Reference the same question with the same underscore name, and spyder-modelx's tree request, which already asks for '_is_derived', gets an answer on Reference rows. Code (reference.py): - New ReferenceProxy._is_derived(), on both proxy classes: the impl's is_derived() when the proxy's impl is a ReferenceImpl, else None. Measured on bac9baa (this branch before the change), the proxies got through an ItemSpace for a slot that holds the item's copy of a Space (P[1].rel for P.rel = P.Child: a DynamicSpaceImpl), of the ItemSpace itself (P.me = P: an ItemSpaceImpl) or of a Cells (P.relc = P.h: a DynamicCellsImpl), and the prefix slot P[1].r for P.r = PX (None), hold no ReferenceImpl. With a plain impl.is_derived(), the new whole-model walk test raised "AttributeError: 'DynamicSpaceImpl' object has no attribute 'is_derived'". The guard is an isinstance test, not a try, because a DynamicCellsImpl has is_derived() and gave its Cells' flag, True, for the proxy. The design keeps the guard after T5. - ReferenceProxy.is_derived() returns self._is_derived(); it stays for good, for modelx-bridge 0.10, and its TODO is gone (decision 11). It changes only on the kinds of proxy above, which toolapi.rst lists as known limitations: None where it raised AttributeError (Space copy, ItemSpace, prefix slot) or returned True (Cells copy). Of the probe's 43 proxies, 5 changed so (P[1].rel, P[1][5].rel, P[1].me, P[1].relc, P[1].r), and the other 38 give what they gave. - Cells._is_derived() is unchanged, and no Space class or Model gets one (decision 4). Goldens, regenerated with each module's --write: - tool_api_surface.json: 2 entries added, ReferenceProxy._is_derived and DynamicReferenceProxy._is_derived, each {"kind": "method", "signature": "(self)"}, from the new FROZEN row ("T3", PROXIES, ("_is_derived",)). Nothing else changed; is_derived keeps its kind and signature. - spyder_requests_snapshot.json: 33 keys added, all '_is_derived' on the Reference records of the 'tree' request, which asks for ['_is_derived', '__len__', '_evalrepr']. The design says these rows gain the key (T3, edge cases), which fills spyder's blank "Is Derived" cells. 8 are true: Sub's inherited dct, lst, s, self_space, the_cells, the_model, tpl and xlr; 25 are false. A key-by-key walk of the old and new files found every other value equal. The gate already ignored added keys; the golden now pins them. spyder_surface_snapshot.json is unchanged. Tests: - test_tool_flags.py, T3 section (42 new tests): _is_derived(), _is_defined() and the design's compositions (generated / inherited / own) on 13 Cells, static, overriding, derived (also from a second base and into a Space with a formula) and dynamic; _is_derived() and is_derived() on 25 References: static, derived, overriding, a Model-level Reference from the Model and through Base, Sub, P[1] and P[1].Child (False), Space bindings seen through items (their own flag, True for Q[1].k), arguments and formula refs (False, generated); the system bindings of P, P.Child, P[1] and P[1].Child (False); the pre-T5 slots P[1].rel and P[1].relc, and their nested copies, answer None and raise nothing (T5 changes these to True); no Space class, Model or Macro has _is_derived; and model._get_attrdict(['_is_derived', '_is_dynamic', '__len__', '_evalrepr'], recursive=True) does not raise, gives each record what its object answers, no '_is_derived' on Space and Model records and no '_is_dynamic' anywhere, over all eight kinds. - The fixture gains Base.q = 2 with Sub.q = 20 (an overriding Reference), Q(Base) with a Space formula, and P.relc = P.h. T2's PROXIES lists relc as a ReferenceProxy in P[1] and P[1][5]. - test_attrdict_type_unchanged (T2, previous commit) walked 'named_itemspaces', the _baseattrs key; _get_attrdict names it '_named_itemspaces'. So it reached no ItemSpace: on this fixture it saw 13 of 22 Cells records and 20 of 46 Reference records, and no dynamic one, and its check that a DynamicCells record says 'Cells' held vacuously. It now uses the new walk_records helper and checks the 'type' of all eight kinds. Its expectations are unchanged. - test_tool_contracts.py: docstrings only. member_is_derived, the 0.33 fallback recipe, now takes _is_derived() on proxies too, and its results are unchanged. - test_spyder_requests.py: the docstring's T3 example in the past tense. Mutations, each run against the four touched test modules: a plain alias with no guard fails 2 tests; no _is_derived on the proxy, 30 (the golden, the spyder requests golden and the T3 tables); an is_derived() that is not the alias, 1; a _is_derived on BaseSpace, 2; a DynamicCells record typed 'DynamicCells', 2. Full suite, CPython 3.11.15, -n 3: 1 failed, 1748 passed, 8 skipped, the baseline's QuantLib failure (export/test_lifelib.py::test_assets) and 42 new tests. The four touched modules and test_kind.py on CPython 3.10.20: 249 passed, 1 skipped. Every changed file parses with ast.parse(..., feature_version=(3, 9)). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
… (T7) PR 2 of devnotes/ToolAPIDesign.md, F1 and T7. A tool gets the display name of every object from _get_repr(fullname=True, add_params=False), and that of a node from node._get_repr(), instead of formatting '(t=3)' itself or reading a __SpaceN name. F1 (dynamic.py, ItemSpaceImpl.repr_self): - An ItemSpace shows its arguments whatever add_params is, and an item of an item is labelled by its parent's argument form, recursively. - Measured on 73630b6 (this branch before the change), model Syn: P[1] add_params=False 'Syn.__Space1' -> 'Syn.P[1]' P[1][5] default 'Syn.__Space1[5]' -> 'Syn.P[1][5]' P[1][5] add_params=False 'Syn.__Space2' -> 'Syn.P[1][5]' (P[1] was left out altogether) P[1].Child[2] add_params=False 'Syn.P[1].__Space1' -> 'Syn.P[1].Child[2]' P[1].Child[2][3] default 'Syn.P[1].__Space1[3]' -> 'Syn.P[1].Child[2][3]' Q[1, 2], N[] and MI[5] gave 'Syn.__Space1' with add_params=False, and now 'Syn.Q[1, 2]', 'Syn.N[]' and 'Syn.MI[5]'. - What is in an item of an item follows, and so do repr(), .info and the 'repr' and 'repr_parent' keys of _get_attrdict: <DynamicCells Syn.P[1][5].h(x)> was <DynamicCells Syn.__Space1[5].h(x)>, and the repr of the node P[1].node(5) is 'Syn.P[1](i=5)=<ItemSpace Syn.P[1][5]>', where it was 'Syn.__Space1(i=5)=<ItemSpace Syn.__Space1[5]>'. - A probe of 28 objects and 16 node requests, before and after: every change is in an ItemSpace or in an object inside one, and nothing outside an item changed. Only the display changes: _name, _idstr, _idtuple, _evalrepr and _get_from_name round trips are as before. - Also changes the names in the log_input debug log (_input_log.txt) for an input inside an item of an item, which output_input writes from _get_repr(fullname=True, add_params=False). No test reads such a line; test_log_input's items are single-level and unchanged. - Docstrings: Interface._get_repr and BaseNode._get_attrdict lose their known-limitation text and get versionchanged 0.34.0 notes. T7 (node.py): - New BaseNode._get_repr(fullname=True, add_value=False), versionadded 0.34.0: the node's object as obj._get_repr(fullname, add_params=False) gives it, then the arguments by parameter name, each by repr(), as in 'Syn.P[1][5].h(x=3)'. With add_value=True it adds '=' and the value's repr, after a line break when that repr spans lines. - Factored from ItemNode.__repr__ and ObjectNode.__repr__, which are gone; BaseNode.__repr__ is now _get_repr(fullname=True, add_value=True), for every node class. Against the two old bodies, copied verbatim, 37 nodes on a model with no ItemSpace (20 ItemNode, 10 ReferenceNode, 7 ObjectNode: the Model, Spaces with and without a formula, Cells, multi-line values) give equal strings. Goldens: - tool_api_surface.json, regenerated with its --write: 2 entries added, ItemNode._get_repr and ReferenceNode._get_repr, each {"kind": "method", "signature": "(self, fullname=True, add_value=False)"}, from the new FROZEN row ("T7", NODES, ("_get_repr",)). Nothing else changed. - spyder_surface_snapshot.json and spyder_requests_snapshot.json are not regenerated: rebuilt in a scratch process, both equal the committed files byte for byte (34,769 and 49,734 bytes). The design expected one change at most, a nested item's display; the spyder fixture has no item of an item, and its one ItemSpace, Params[1], already showed its arguments in every 'repr' key. New test, core/space/dynamic_spaces/test_itemspace_repr.py (53 tests), on the tool API and the public API only: - 12 ItemSpaces (P[1], P[1][5], P[1][5][7], P[1].Child[2], P[1].Child[2][3], P[1][5].Child[2], P['a'], P[B1], Q[1, 2], Q[1] as Q[1, 0], N[], MI[5]) with both add_params values and both fullname values, repr(), the .info header and the attrdict 'repr'; - 20 objects inside them and outside, Cells, DynamicSpaces and proxies; - a walk of all 60 Spaces and Cells: each display equals one built from _parent, name and argvalues, none shows __Space, no two are equal; and the 60 'repr' keys of a whole-model _get_attrdict; - that identity is unchanged; - 14 nodes (ItemNodes of Cells and of Spaces, ReferenceNodes of an argument, a global and a Space Reference read through an item), nodes with no value, a multi-line value, node lists, and node attrdicts. No existing test changed. Breaking the code on purpose nine ways (repr_self as before; parent's name for a nested item; the name again for add_params=False; the value never or always added; fullname ignored; arguments by str; no line break; default fullname=False) fails between 1 and 26 of the new and golden tests each. Tests: full suite with -n 3 on CPython 3.11.15, "1 failed, 1801 passed, 8 skipped": the previous stage's 1748 plus these 53. The failure is the baseline's export/test_lifelib.py::test_assets (QuantLib missing). The new test, the signature golden, both spyder goldens and test_repr.py pass on CPython 3.10.20 (98 passed). Changed files parse with ast.parse(feature_version=(3, 9)). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
…n-node (F6)
devnotes/ToolAPIDesign.md section 3.3 F6, assigned to PR 2, with the
section 9 row "_direct_bases on an ItemSpace or DynamicSpace can name a
Space unrelated to the item".
SpaceGraph.ordered_preds returns [] for a name that is not a node of the
inheritance graph. networkx's in_edges() took such a str for a bunch of
nodes, its characters. The idstr of a dynamic Space is never a node, so
on a model with P(Base1, Base2) and S(B), ordered_preds('P.__Space1')
gave ['Base1', 'B', 'Base2'], the bases of the Spaces named P and S, and
get_mro('P.__Space1') gave ['P.__Space1', 'Base1', 'Base0', 'B', 'Base2'].
_direct_bases of an ItemSpace or a DynamicSpace returns [dynbase], the
same list as bases. BaseSpaceImpl gains a direct_bases property that
reads the graph, as before; DynamicSpaceImpl overrides it to return
self.bases; BaseSpace._direct_bases reads impl.direct_bases. Its
docstring is rewritten, with a versionchanged 0.34.0 note.
Measured before and after, model with Base1(Base0), Base2, B, S(B),
P(i)(Base1, Base2) with Child(j)/GC and Child2(Base2), P3(i),
Q(i) whose formula returns base Base2, and Sub(i)(P):
- P[1], P[1].Child, P[1].Child.GC, P[1].Child2, P[1].Child[2],
P[1].Child[2].GC, P[1][5], P[1][5].Child and P3[1] listed
[Base1, B, Base2]; now each lists its bases' one Space (P, P.Child,
P.Child.GC, P.Child2, P.Child, P.Child.GC, P, P.Child, P3).
- Q[1] listed [B]; now [Base2]. Sub[1] listed [B]; now [Sub].
- With only P(Base1, Base2) and Child, P[1].Child listed [Base1, Base2]
(the toolapi.rst Known limitation); now [P.Child].
- With only B, S(B) and P3(i), P3[1] listed [B] (the section 9 row);
now [P3].
- Every UserSpace's _direct_bases and every Space's bases are unchanged.
The graph fix also changes the impl-level bases of dynamic Cells and
References, which read get_mro of the parent's idstr: P[1].h's
_impl.bases was [Base1.h, B.h] and is now []. No public or tool-API
member reads it: Cells.rename refuses a DynamicCells before the graph is
asked, and the inheritance sync walks UserSpaces only.
New test modelx/tests/core/space/inheritance/test_direct_bases.py (35
tests): UserSpace direct bases and the MRO difference, the table of 11
dynamic Spaces, a walk of all 13 dynamic Spaces checking _direct_bases
equals bases (so spymx's C3 recipe, bases on 0.33, agrees from 0.34),
the toolapi.rst and section 9 cases, a new list per call, and
SpaceGraph.ordered_preds/get_mro on a standalone graph. On 00a86ae, 19
of them fail and 16 pass. Breaking the fix five ways fails 3 to 15 of
them. No existing test changed.
Goldens: none changed. tool_api_surface.json, spyder_surface_snapshot.json
and spyder_requests_snapshot.json regenerated with --write are
byte-identical: no interface member was added, and spyder never
requests _direct_bases.
Full suite, CPython 3.11, -n 3: 1 failed, 1836 passed, 8 skipped (the
failure is export/test_lifelib.py::test_assets, QuantLib missing).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
… longer raise
devnotes/ToolAPIDesign.md section 3.3 F11 and section 3.5 C3 (decision
13, as the design recommends), with the section 9 rows assigned to PR 2:
"RefView._baseattrs_private raises RuntimeError" and "_get_attrdict and
_baseattrs of an ItemNode with no stored value raise ValueError".
Interface._get_attrdict_extra looks each requested name up on type(self)
and its bases, by reading their namespaces (new module function
base.get_class_attr), never on the object. A property, or another data
descriptor, is read with its getter; a value whose class defines
_get_attrdict becomes its dict; any other value is added as it is. A
function, or another method, is bound and called. Any other class
attribute is added as it is. A ReferenceProxy, which calls this as
Interface._get_attrdict_extra(proxy, ...), also looks on Interface, for
properties and functions only, as its __getattr__ forwards them. A name
the class does not define is skipped, and so is a property whose getter
raises AttributeError. Nothing reaches Model.__getattr__ or
BaseSpace.__getattr__: 0 hits in the walks, counted by wrapping both.
On 0.33 the name was read from the object with hasattr/getattr, and any
callable value was called. On a model with global References named
__len__, _is_derived, formula and parameters, a Space Reference and a
Cells named argvalues, and a Space formula returning a ref named
_is_derived, spyder's tree list called those user functions 20 times in
one whole-model walk, the list with argvalues and _is_dynamic 21 times
(and put the argvalues Cells into its Space's record), and the
Properties list called the globals formula and parameters on the Model.
Now 0 calls, and the only keys that go are the 44 whose values came from
those members.
Two choices inside the rule, both keeping what 0.33 gave for every class
attribute on these models:
- Descriptors other than property and function (slot members such as
_impl, method descriptors such as __sizeof__) follow the descriptor
protocol: data descriptors are read, the others bound and called, as
getattr on the object did. Taken literally, "any other class attribute
is taken as it is" would put the descriptor objects into the dict.
- A property's value is not called when it is callable. On 0.33
ReferenceProxy.value of a Reference to a user function called that
function. Whether the value has its own _get_attrdict is asked of its
class, so a user object's __getattr__ is not called either.
RefView's _get_attrdict and _baseattrs read the impls by key and skip a
key that is not a str. A Space formula returning {'refs': {1: 'one'}}
made the ItemSpace's refs dict raise KeyError: 1 from
BaseView.__getitem__, and so the whole-model walk; _baseattrs raised
RuntimeError. The same lines test the underscore with name[:1], not
name[0]: a global or a returned ref named '' (accepted on this release)
raised IndexError there. Such a name is listed, as it does not start
with an underscore.
RefView._baseattrs_private is defined. It was BaseView's, which asks
the value of each Reference, the builtins module of __builtins__ first,
for its _baseattrs: RuntimeError from "AttributeError: module 'builtins'
has no attribute '_baseattrs'". It now gives each str name, underscore
names included, with the Reference proxy's _baseattrs.
BaseNode._get_attrdict and _baseattrs give None for 'predslen',
'succslen' and 'precedentslen' of an ItemNode with no stored value, as
'value' and 'valid' already did, and keep the same keys. preds and succs
raised ValueError there ("... has no cached value for the given
arguments", or "... is not cached" for a Cells whose is_cached is
False). ObjectNodes, ReferenceNodes included, have no arguments and keep
giving 0. The Known-limitation sentence in _get_attrdict's docstring is
replaced by versionchanged 0.34.0 notes.
Measured on lifelib 0.17.2's BasicTerm_S, BasicTerm_SE with 1,000
ItemSpaces, BasicTerm_ME, CashValue_ME and simplelife, after a
calculation, in separate processes with ids normalised: the tree list
(59,322 records), the tree list with _is_dynamic and argvalues
(59,322), the Properties list on every object (55,016), _baseattrs
(122,430) and the node records of every stored value (128,886) are
identical to f1f63ed's. Against 10188ae they differ only in keys T2 and
T3 change: '_is_derived' added to Reference records (T3), '_is_dynamic'
gone from Space records (T2), and 'value_type' 'DynamicCells' where
the value is a dynamic Cells (T2; 20 tree, 10 Properties and 60
_baseattrs records on simplelife). The BasicTerm_SE tree walk took
442.5 ms against 458.9 ms (minimum of 3 alternating rounds of 7).
New test modelx/tests/core/base/test_extattrs.py (28 tests): the model
above, on which spyder's tree, argvalues and Properties lists call
nothing, add the names each class defines with modelx's answers, and
never reach __getattr__; against a verbatim copy of 0.33's rule as an
oracle, the exact 0.33 calls per walk and that every difference is a
dropped member key; the same dicts as the 0.33 rule, key order
included, on the spyder fixture, BasicTerm_S and simplelife; the rule's
branches (property values not called, own dicts, methods, the proxy's
Interface lookup with allow_none, getters raising AttributeError
skipped and other errors raised); non-str and empty ref keys;
_baseattrs_private on Model, UserSpace and ItemSpace refs views; nodes
with and without values, ReferenceNode and ObjectNode. On f1f63ed 19 of
them fail. Breaking the fix 17 ways fails 1 to 14 of them.
Existing test changed: the docstring of test_spyder_requests.py, which
said a node with no stored value raises ValueError. No assertion
changed.
Goldens: none changed. tool_api_surface.json, spyder_surface_snapshot.json
and spyder_requests_snapshot.json rebuilt are byte-identical.
Full suite, CPython 3.11, -n 3: 1 failed, 1864 passed, 8 skipped (the
failure is export/test_lifelib.py::test_assets, QuantLib missing).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
…pr, F1/F6/F11) The reference page, docstrings, release notes and design record for the five PR 2 commits bac9baa..b7f260f. No code changes behaviour: two docstrings change, and no test or golden changes. toolapi.rst ("API for tools"): - New "Kinds of objects" section (label toolapi-kinds, which the DynamicCells and DynamicReferenceProxy docstrings already cite). It covers: - T1's recipe as a doctest: the guarded __module__ check and the twelve names, each with the objects it covers; - what is frozen: the names and that each class is in a module of the modelx package, but not which module; - the "any Cells", "any Reference", "any IOSpec" and "any Space" tests, and DYNAMIC; - a migration table for the removed _is_dynamic(), _is_static() and _is_root(), and the capability table; - two Known limitation boxes: the pre-T5 slot is still a ReferenceProxy, and a call on a Space without a formula raises AttributeError ('NoneType' object has no attribute 'signature'). - Decision 14's three changes: - "What is not tool API" names NullFormula as its class-name example, and says a listed name is tool API only after the module check; - its imports bullet covers every modelx module path except modelx.core.errors (modelx.io.* included); - "Deprecation" gains the class-name exception: deprecated without a warning, marked two minor releases ahead, and renamed only when the downstream suites pass. The "Frozen" tier also says the golden pins the kinds, and pins the Cells and ReferenceProxy members on the two new subclasses too. - T2: the attrdict 'type' row ("except 'Cells' for a DynamicCells"), 'Reference' for both proxy classes, and 'value_type' 'DynamicCells'. Dynamic Spaces are "told apart by their class". The _is_dynamic/_is_static/_is_root entry and its 9 autosummary rows are removed, and the _get_object example prints <DynamicCells Model1.Proj[1].bar()>. - T3: a ReferenceProxy._is_derived() entry and autosummary row. is_derived() is listed as "kept for modelx-bridge 0.10; use _is_derived()". Its two Known limitation boxes (AttributeError, or True for an item's copy of a Cells) become one, saying _is_derived() is None on the two kinds of proxy that stand for no Reference. - T7: a node _get_repr(fullname=True, add_value=False) entry, with ItemNode._get_repr and ReferenceNode._get_repr rows. - F1: the _get_repr entry says an ItemSpace shows its arguments whatever add_params is, with new doctests ('Model1.Proj[1]', 'Proj[1][5]', 'Model1.Proj[1][5].bar'). Its box and the wire section's __SpaceN sentence are removed. - F6: the _direct_bases box is removed, and the entry says a dynamic Space's _direct_bases equals its bases, with a doctest. - F11: the extattrs paragraph now gives the class-only rule. Its box is removed, and a table lists the names safe to request, with those never to request. The boxes for RefView._baseattrs_private, ItemNode dicts with no value, and non-str refs keys are removed. - The prefix-reference box is adjusted to what the code does now: - is_derived() is no longer in the raising list; _is_derived() and is_derived() give None; - the message is "'NoneType' object has no attribute 'name'" (was 'interface'); - P[1].refs._baseattrs_private raises it too. The box stays because the defect stays until PR 3 (T5). - Changed entries carry versionadded/versionchanged 0.34.0 notes, each giving the 0.33 behaviour a tool that supports both must expect. cells.rst and reference.rst: autoclass sections for DynamicCells and DynamicReferenceProxy, so the :class: links from toolapi.rst and the release notes resolve. Docstrings: - Interface.info: the ItemSpace example printed "bases: []" and no parameters line, where modelx prints "bases: [Model1.Space1]" and "parameters: i, j=0". The two inline examples now read Model1.Space1[1, 0], and the text says the first line names the class. Every example in it was checked against what modelx prints. - ReferenceProxy._is_derived and refmode: link the prefix note by its own label, toolapi-prefix-ref, instead of the whole wire section. relnotes_v0_34_0.rst: - A new Enhancements section: kinds by class name; DynamicCells and DynamicReferenceProxy; ReferenceProxy._is_derived(); node _get_repr(). - Backward Incompatible Changes: the new classes, with the repr and .info strings, before and after, and the 'type'/'value_type' note; the removed Space flags and their class checks. - Bug Fixes: F1, F6, F11, the refs view's non-str and '' keys, RefView._baseattrs_private, ItemNode dicts with no value, is_derived() on the proxies that stand for no Reference, and copy.copy of a proxy. Every before/after string was re-measured on 10188ae and on HEAD (scratch probe_relnotes.py, probe_boxes.py). copy.copy of a proxy failed on CPython 3.11.15 and worked on 3.10.20, so the note says 3.11 and later. kind() took about 0.15 us on a modelx object and 0.12 us on other values, the call included (min of 7 x 1,000,000, CPython 3.11.15). devnotes/ToolAPIDesign.md: - The Progress line records PR 2 on this branch, with its commits and test counts, and that decisions 11 and 13 await the owner. - The tracker rows for decisions 4, 11 and 13-16 are updated. - A new section 9 table, "Found while implementing PR 2", has 12 rows, each assigned to the PR that takes it or marked as not changed. - "Not measured" no longer calls T2 and F11 prototypes. Checks: - A fresh Sphinx build, from a copy of the tree without the git-ignored generated stubs, gives 3 warnings: _static, installation.rst:164 and eval_formulas.rst. They are main's own; the fourth allowed one, intersphinx, did not occur because the inventory loaded. 10188ae gives the same 3. - Every new autosummary row generates a page with its docstring, and no _is_dynamic/_is_static/_is_root stub is generated. - python -m doctest on toolapi.rst: 78 passed. - Full suite with -n 3 on CPython 3.11.15: 1 failed, 1864 passed, 8 skipped. The failure is export/test_lifelib.py::test_assets (QuantLib missing), as at 10188ae. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
F11's class-only lookup walked cls.__mro__ with vars() for every requested name. That made a Cells' Properties request 3.55 -> 4.89 us and the BasicTerm_SE tree walk with 50 ItemSpaces 22.4 -> 23.8 ms against 0.33's getattr. get_mro_namespaces() keeps, by id(cls), the live mappingproxies of the MRO of a modelx or built-in class, and uses them only while cls.__mro__ is the same tuple. A later set or delete, as monkeypatch does, is seen, and so is a new __bases__. Classes of other modules are walked each time and not held. _get_attrdict_extra inlines the walk and short-cuts property, function and plain built-in values. Measured on one CPU, min of 3 interleaved runs: a Cells' Properties request 4.1-4.5 us against 0.33's 3.7-4.0 us, the tree walk 18.8-20.3 ms against 21.6-21.7 ms. Namespaces built per request and not kept gave 5.5 us and 23.0 ms. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
…ules - The item-copy note (reference.rst) states the condition as the code applies it: a non-absolute Reference of the ItemSpace's base, or of a Space inside it, whose value is inside the base, also read through a DynamicSpace in the ItemSpace (P[1].Child.up for P.Child.up = P). The Known limitations in toolapi.rst, the _is_derived and refmode docstrings and the 0.34 release note follow it. - The formula row of 'What a kind can do' says an item has its base's formula as it was when the item was made, and a new Known limitation says a formula given later does not reach items already made. - The extattrs rules name data descriptors and bound methods. - ReferenceProxy.__new__ gives the right reason for its `cls is ReferenceProxy` test, here and in design T2. - Cross-references: :class:`type`, ReferenceProxy._is_derived. - Tests: a ReferenceProxy subclass keeps its class; _is_derived() and is_derived() are None through a DynamicSpace (on 0.33 is_derived() raised AttributeError for up and side, and gave True for rw). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
fumitoh
pushed a commit
that referenced
this pull request
Oct 18, 2026
…oved Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR 2 of the tool-API plan in
devnotes/ToolAPIDesign.md§6. It implements T1, T2, T3, T7, F1, F6 and F11, plus decisions 14–16 as you decided them. Decisions 11 and 13 are implemented as recommended and need your approval (see below).What changes
T1, decision 14: kinds by class name. A tool tells what an object is from
type(obj).__name__, after a guarded check thattype(obj).__module__is a str starting withmodelx.. There are 12 kinds: Model, UserSpace, ItemSpace, DynamicSpace, Cells, DynamicCells, Macro, ReferenceProxy, DynamicReferenceProxy, PandasData, ExcelRange and ModuleData. No_kindmember is added. The recipe is a doctest in the new "Kinds of objects" section of toolapi.rst, andtest_kind.pychecks it on every kind.T2, decisions 15 and 16: dynamic classes.
DynamicCells(Cells)is the interface ofDynamicCellsImpl.ReferenceProxy.__new__(cls, impl=None)returns aDynamicReferenceProxyfor a Reference whose parent is a dynamic Space. That covers arguments, formula refs and the system bindings. All six sites that make a proxy go through it.copy.copykeeps working and keeps the class.'type'stays'Cells'and'Reference', so spyder-modelx shows these objects as before.repr()and.infoshow the new names, for example<DynamicCells Model1.Proj[1].bar()>._is_dynamic(),_is_static()and_is_root()are removed, without deprecation. Nothing in modelx, spyder-modelx, spymx-kernels 0.4.0, modelx-bridge 0.10.0 or modelx-mcp 0.1.0 calls them.T3:
ReferenceProxy._is_derived(). It returns None on a proxy that does not stand for a Reference.is_derived()stays as an alias (decision 11).T7:
BaseNode._get_repr(fullname=True, add_value=False).F1: an ItemSpace displays by its arguments, so no
__SpaceNappears in a display name. For example,Proj[1]._get_repr(fullname=True, add_params=False)was'Model1.__Space1'and is now'Model1.Proj[1]'.F6:
_direct_basesof an ItemSpace or a DynamicSpace is now its one base. It used to name Spaces that are not its bases.ordered_predsreturns [] for a non-node.F11, decision 13: extattrs resolve on the class only.
type(self), never on the object, so it can no longer reach and call a user's Reference, Cells or Space of that name.refsview of an ItemSpace no longer raises for a non-str key.RefView._baseattrs_privateno longer raises RuntimeError.getattrdid (numbers below).Release notes:
doc/source/releases/relnotes_v0_34_0.rst, under Enhancements, Backward Incompatible Changes and Bug Fixes.Behaviour changes users can see
DynamicCells.isinstance(c, Cells)is still True, buttype(c) is Cellsandtype(c).__name__ == 'Cells'are False.DynamicReferenceProxy.repr()and the.infoheader print the new names.is_derived()returns None, instead of raising or returning True, on the item-copy proxies described underreference-proxy-identity.For your approval
ReferenceProxy.is_derived()permanently as an alias of_is_derived(), because modelx-bridge 0.10 calls it. KeepItemSpace.argvaluesas it is, but off the snapshot wire.Consequences downstream
test_basicterm_s.py:605and:607. Both pick nodes bytype(...).__name__ == "Cells"(line 609), which leaves out DynamicCells.modelx<0.34. When the bridge adopts 0.34, it must map the new names to'Cells'and'ReferenceProxy'before it compares or sends them.Checks
pytest modelx/tests -n 3on CPython 3.11.15 gives 1,871 passed and 8 skipped. QuantLib'sexport/test_lifelib.py::test_assetswas deselected; it fails on main too.sphinx-build -Egives the same 3 warnings as main and no new ones.The branch also carries the design commits for decisions 14–16.
Generated by Claude Code