Skip to content

Tool API PR 2: kinds by class, DynamicCells and DynamicReferenceProxy, _is_derived(), node _get_repr() (T1–T3, T7, F1, F6, F11) - #284

Merged
fumitoh merged 16 commits into
mainfrom
claude/stoic-bardeen-qpv3a0
Oct 18, 2026
Merged

fumitoh merged 16 commits into
mainfrom
claude/stoic-bardeen-qpv3a0

Conversation

@fumitoh

@fumitoh fumitoh commented Oct 18, 2026

Copy link
Copy Markdown
Owner

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 that type(obj).__module__ is a str starting with modelx.. There are 12 kinds: Model, UserSpace, ItemSpace, DynamicSpace, Cells, DynamicCells, Macro, ReferenceProxy, DynamicReferenceProxy, PandasData, ExcelRange and ModuleData. No _kind member is added. The recipe is a doctest in the new "Kinds of objects" section of toolapi.rst, and test_kind.py checks it on every kind.

T2, decisions 15 and 16: dynamic classes.

  • DynamicCells(Cells) is the interface of DynamicCellsImpl.
  • ReferenceProxy.__new__(cls, impl=None) returns a DynamicReferenceProxy for 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.copy keeps working and keeps the class.
  • The attrdict 'type' stays 'Cells' and 'Reference', so spyder-modelx shows these objects as before.
  • repr() and .info show the new names, for example <DynamicCells Model1.Proj[1].bar()>.
  • The Space flags _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 __SpaceN appears 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_bases of an ItemSpace or a DynamicSpace is now its one base. It used to name Spaces that are not its bases. ordered_preds returns [] for a non-node.

F11, decision 13: extattrs resolve on the class only.

  • A requested name is looked up on type(self), never on the object, so it can no longer reach and call a user's Reference, Cells or Space of that name.
  • The refs view of an ItemSpace no longer raises for a non-str key.
  • RefView._baseattrs_private no longer raises RuntimeError.
  • The class lookup keeps the namespaces of the MRO of modelx and built-in classes, so it costs about what 0.33's getattr did (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

  • A Cells of an ItemSpace or DynamicSpace is now a DynamicCells. isinstance(c, Cells) is still True, but type(c) is Cells and type(c).__name__ == 'Cells' are False.
  • In the same way, a Reference proxy made through a dynamic Space is now a DynamicReferenceProxy.
  • repr() and the .info header print the new names.
  • The three Space flags are gone. The class gives the same answer on every live Space, and a deleted Space now answers by its class instead of raising.
  • is_derived() returns None, instead of raising or returning True, on the item-copy proxies described under reference-proxy-identity.

For your approval

  • Decision 11. Keep ReferenceProxy.is_derived() permanently as an alias of _is_derived(), because modelx-bridge 0.10 calls it. Keep ItemSpace.argvalues as it is, but off the snapshot wire.
  • Decision 13. Extattrs resolve on the class only. A ReferenceProxy also looks on Interface, for properties and functions only. On 0.33, spyder's tree request called user functions 20 times in one walk; it now calls none.

Consequences downstream

  • modelx-mcp needs a release before modelx 0.34. On this branch its suite gives 973 passed and 2 failed: test_basicterm_s.py:605 and :607. Both pick nodes by type(...).__name__ == "Cells" (line 609), which leaves out DynamicCells.
  • modelx-bridge 0.10.0 pins 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

  • modelx suite: pytest modelx/tests -n 3 on CPython 3.11.15 gives 1,871 passed and 8 skipped. QuantLib's export/test_lifelib.py::test_assets was deselected; it fails on main too.
  • lifelib-app bridge suite (modelx-bridge 0.10) on this branch: 835 passed, 0 failed.
  • Docs: a clean sphinx-build -E gives the same 3 warnings as main and no new ones.
  • Python 3.9: every changed file parses as 3.9 syntax.
  • Review: four reviews (correctness, plan, docs, perf) found no defects. Their nits are fixed in the last three commits.
  • Speed (one CPU, min of 3 interleaved runs, main → this branch):
    • Cells Properties request: 3.7–4.0 → 4.1–4.5 µs;
    • BasicTerm_SE tree walk with 50 ItemSpaces: 21.6 → 18.8–20.3 ms;
    • making a proxy: 0.09 → 0.20–0.25 µs. No formula reads a proxy.

The branch also carries the design commits for decisions 14–16.


Generated by Claude Code

claude added 16 commits October 17, 2026 15:22
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
@fumitoh
fumitoh merged commit fec516d into main Oct 18, 2026
19 checks passed
fumitoh pushed a commit that referenced this pull request Oct 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants