expand

Python: Expand one outbound edge from a canonical handle (single hop).

The traversal primitive that walks ONE edge from a source handle and returns adjacent symbols as lightweight Stubs. Use resolve()/inspect() first to obtain a canonical handle, then call expand() to traverse.

Supported edges (the complete static/outbound set):

• members — class/module → direct members (attributes, methods, nested classes). stubs: [] means the class/module was found but has no members; that is NOT the same as unsupported. Static-surface ceiling: members are read from source; runtime-injected members (metaclass / setattr / __getattr__ / type() / __init_subclass__) are NOT captured — e.g. a Django Model shows none of its metaclass-injected _meta / objects / DoesNotExist.

• callees — function/method → forward static call targets. Includes project symbols and stdlib/external symbols reachable via Jedi's goto. Dynamic calls (un-inferable parameters, getattr, lambdas, etc.) are counted in unresolved_call_sites rather than invented.

• imported_by — module → the project modules that import it (module Stubs), computed by static AST import-graph reversal (no reverse symbol search). Covers importers anywhere in the project including tests and standalone scripts. Non-module handles return the unsupported branch with reason: "not_yet_implemented" (symbol-level imported_by is not yet implemented). Ceiling: runtime-dynamic imports (importlib/__import__ with computed targets) are not detected.

• subclasses — class → the project classes that directly subclass it (class Stubs), computed by an AST class-graph walk + forward goto (no reverse symbol search). Returns the DIRECT (depth-1) subclasses only (#422) — one hop, symmetric with superclasses; the full transitive closure is served by trace(follow=["subclasses"], max_depth=k, max_nodes=N), which carries the cap + truncated contract. A class result includes a static transitive_hint field pointing to that trace route. subclasses is an expand-only edge: inspect does NOT measure it (dropped in #392); a cheap direct count is gated on the Pyright reference backend / class-graph cache (#333/#397), because even the direct count is a reverse query needing the same project-wide scan as callers/references. stubs: [] means the class has no project subclasses (measured-none). A non-class handle also returns the supported branch with stubs: [] (and no transitive_hint) — only a class CAN be subclassed, so [] is true by definition, not an absence-vs-zero lie. Static-surface ceiling: the result is complete only over literal class B(A): subclassing; dynamically-created subclasses (type('B', (A,), {}), factory-built classes, __init_subclass__ registration) are NOT captured.

• superclasses — class → its base classes (class Stubs), resolved by Jedi from the class definition (no reverse search). A non-class handle returns stubs: [] ([] true by definition, as with subclasses).

• imports — module → the symbols/modules it imports (Stubs), computed by static AST + forward goto. stubs: [] is measured-none. A non-module handle returns the unsupported branch with reason: "not_yet_implemented" (mirrors imported_by).

• enclosing_scope — symbol → its immediate lexical enclosing scope (the inverse of members), resolved by Jedi parent(): a method → its class, a nested def/class → its enclosing def/class, a top-level def/class/variable → its module. At most ONE Stub. A module returns stubs: [] (a module has no enclosing lexical scope — packages are not lexical scopes); [] is therefore measured-empty, never unsupported.

Unsupported edges return the unsupported branch (never raise):

• Inbound/reference edges (callers, references, overrides, …) require the Pyright reference backend (#333) and return unsupported: true, reason: "deferred_reference_backend".

• Wrong-kind handles (e.g. imported_by on a non-module) return the unsupported branch with reason: "not_yet_implemented".

• Unrecognised edge names return reason: "unknown_edge".

Response shape — discriminated union:

Supported branch ("unsupported" key absent): ::

{ "source": str,                 # canonical source handle
  "edge":   str,
  "stubs":  [Stub, ...],         # [] == measured-empty (NOT unsupported)
  "unresolved_call_sites": int   # callees ONLY; absent for members }

Unsupported branch ("stubs" key absent): ::

{ "source": str,
  "edge":   str,
  "unsupported": True,
  "reason":  str,               # deferred_reference_backend |
                                # not_yet_implemented | unknown_edge
  "detail":  str }              # human-readable explanation

Each Stub carries: handle, kind, scope, line_start, line_end, and signature when Jedi yields one (always for class/function/method; also any name whose inferred type is callable).

Relationship to deprecated tools: members supersedes the deprecated find_subclasses/find_symbol pattern for enumerating class members. callees supersedes manual get_call_hierarchy usage for forward edges. Both deprecated tools remain registered until Phase B migration.

Args: handle: Canonical Python dotted-name string (from resolve/inspect). edge: The outbound edge to expand (e.g. "members", "callees"). project_path: Project root path (default: current directory).

Returns: ExpandResult dict — supported branch or unsupported branch (see above). Never raises; unresolvable source handles yield graceful supported-empty results consistent with inspect()'s minimal-node contract.