Struct PythonStructuralSpec 

pub struct PythonStructuralSpec;

Trait Implementations

impl Debug for PythonStructuralSpec

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for PythonStructuralSpec

fn default() -> Self

Returns the “default value” for a type.

impl StructuralSpec for PythonStructuralSpec

fn qualified_path_root<'tree>(&self, token: Node<'tree>) -> Option<Node<'tree>>

Python’s one qualified-path chain is dotted_name, which is flat rather than left-nested: its named children are the segments in order.

fn occurrence_namespace( &self, role: OccurrenceRole, declares: Option<NormalizedKind>, ) -> Option<Namespace>

Python only classifies a scope segment inside a dotted_name, and every non-tail segment of a dotted name is a module.

fn language(&self) -> Language

fn supports_boolean_literal_value(&self) -> bool

Whether this adapter can state the exact language-neutral value of every boolean-literal fact it extracts. The default is deliberately unsupported so a third-party adapter cannot silently answer an exact value query from kind alone.

fn supports_string_literal_parenthesized(&self) -> bool

Whether this adapter publishes parenthesized-expression state for all normalized string-literal facts.

fn supports_string_literal_value(&self) -> bool

Whether this adapter can decode supported string-literal source forms into their language-neutral value. Individual unsupported forms may still return None, which exact-value queries report as incomplete.

fn string_literal_value(&self, node: Node<'_>, source: &str) -> Option<String>

Exact decoded value of a node normalized as NormalizedKind::StringLiteral. The adapter must read the grammar’s string-content and escape nodes rather than trimming source text.

fn supports_assignment_shape(&self) -> bool

Whether this adapter records directly paired tuple/list assignment shapes for the supported syntax it recognizes.

fn assignment_shape(&self, node: Node<'_>) -> Option<AssignmentShape>

Paired direct sequence sides of a multiple assignment, if both sides have a supported tuple/list shape.

fn supports_integer_literal_value(&self) -> bool

Whether this adapter publishes integer literal values and permission bits.

fn integer_literal_value( &self, node: Node<'_>, source: &str, ) -> Option<IntegerLiteralValue>

Canonical decimal value, when queryable, and low 32 bits for a grammar-backed integer literal.

fn supports_duplicate_dictionary_keys(&self) -> bool

Whether this adapter can classify duplicate keys in dictionary literals, including reporting unsupported key forms as incomplete.

fn duplicate_dictionary_key(&self, node: Node<'_>, source: &str) -> Option<bool>

Whether a Python dictionary entry repeats an earlier key by decoded literal value. None means the key syntax is outside the supported literal subset.

fn string_literal_parenthesized(&self, node: Node<'_>) -> Option<bool>

Whether a normalized string-literal expression has parenthesized expression wrappers around it.

fn reference_edge_support(&self) -> &ReferenceEdgeSupport

Which parts of the reference-edge domain this adapter answers: whether forward (site-to-target) and inverse (target-to-site) edge projections exist for it, and which classification axes those edges carry.

fn identity_route_support(&self) -> &IdentityRouteSupport

Which parts of the identity/route surface this adapter answers: whether it can group and decode qualified paths, resolve segment prefixes, project canonical identities, group physical occurrences, and which indirection relations it supplies route edges for. Self::occurrence_role_support: the tables are total, so a default would let a new adapter (or a new axis or relation) advertise support nobody implemented. Adapters that answer nothing yet return super::routes::NO_IDENTITY_ROUTE_SUPPORT.

fn path_segment_tokens<'tree>(&self, root: Node<'tree>) -> Vec<Node<'tree>>

Every segment token of the qualified-path chain rooted at root, in source order, read from the grammar’s own chain structure (AST fields, never text splitting). Includes segment tokens that are not facts (Rust’s crate/self/super path keywords), so ordinals state the real position of each segment within the path.

fn curated_export_surface( &self, root: Node<'_>, source: &str, ) -> CuratedExportSurface

The public surface the file rooted at root curates by listing names rather than by marking each declaration (Python’s module-level __all__), gathered once per file so Self::indirection_relation can read it per token.

fn indirection_relation( &self, token: Node<'_>, source: &str, surface: &CuratedExportSurface, ) -> Option<RouteHopKind>

The indirection relation an import/export token participates in: Import for a plain import, Export for an export of a local declaration, ReExport for an export whose subject comes from elsewhere (pub use, export ... from, a name on Python’s __all__). Read from the token’s enclosing statement through AST fields, plus the file’s surface from Self::curated_export_surface.

fn scope_formation(&self, kind: NormalizedKind) -> ScopeFormation

How a fact of normalized kind kind participates in this language’s lexical scope tree: whether it opens a scope at all, and whether the binders written directly inside it are lexical bindings or members.

fn kind_table(&self) -> &'static [(&'static str, NormalizedKind)]

Grammar-specific node-type name → normalized kind. Compiled once per extraction into an id-indexed lookup via Language::id_for_node_kind; a per-language test must assert every entry resolves (id != 0) so grammar bumps that rename nodes fail loudly.

fn refine_kind( &self, node: Node<'_>, kind: NormalizedKind, _enclosing: Option<NormalizedKind>, _source: &str, _context: &CallSiteContext, ) -> NormalizedKind

Context-sensitive refinement applied after table lookup. enclosing is the kind of the nearest enclosing normalized node, and context is the per-file CallSiteContext from Self::call_site_context, for refinements that depend on file-wide facts (Ruby’s value-position bare calls).

fn should_extract(&self, node: Node<'_>, kind: NormalizedKind) -> bool

Whether this normalized node should become a fact at all. Use this for grammar nodes whose normalized kind is conditional on fields, such as variable declarators that are assignments only when they have values.

fn supports_kind(&self, kind: NormalizedKind) -> bool

Whether this adapter can produce facts satisfying kind.

fn occurrence_role_support(&self) -> &OccurrenceRoleSupport

Which occurrence roles this adapter classifies during Self::extract.

fn lexical_environment_support(&self) -> &LexicalEnvironmentSupport

Which parts of a file’s lexical environment this adapter answers: its scope tree, the interval each binding is in effect over, the local names its imports introduce, its package clause, and what its resolver reports about the candidates it considered.

fn materialization_support(&self) -> &DeclarationMaterializationSupport

Which parts of a file’s declaration-materialization story this adapter answers: the origin and state of its declarations, its generation sites and their generated sets, its export declarations, the link from a declaration-only signature to its implementation, and which declarations are gated by a preprocessing configuration.

fn source_export_facts( &self, root: Node<'_>, source: &str, ) -> Option<SourceExportFacts>

Source export declarations derived directly from a prepared parse tree.

fn binding_activation( &self, binder: Node<'_>, scope: Range, ) -> Option<BindingActivation>

What binding binder introduces into the scope whose range is scope, and over which byte interval it is in effect.

fn embedded_leaf_facts( &self, node: Node<'_>, kind: NormalizedKind, source: &str, cancellation: Option<&CancellationToken>, ) -> Vec<EmbeddedLeafFact>

fn comparison_operator_spans( &self, node: Node<'_>, step: &mut dyn FnMut() -> bool, ) -> Option<Vec<Span>>

Complete comparison operator spans from this grammar node. Unknown by default. This transient shape is only a negative candidate proof: it does not publish singular roles or correlated operand pairs. Each span must be both the exact name and text spelling used by an un-normalized Operator role; otherwise the adapter must return None. Call step before inspecting each child or growing the result and once before returning a complete answer; a stopped callback must return None.

fn extract(&self, node: Node<'_>, kind: NormalizedKind, sink: &mut RoleSink<'_>)

Attach the fact’s name and role edges by reading AST fields of node.

fn parser_included_ranges(&self, _source: &str) -> Option<Vec<Range>>

Byte ranges of source the parser may read, or None to parse the whole file.

fn reparse_grammar_gap( &self, _source: &str, _tree: &Tree, _cancellation: Option<&CancellationToken>, ) -> Option<Tree>

A tree re-parsed around syntax the bundled grammar cannot represent, or None when tree stands as parsed.

fn refine_kind_with_parents<'tree>( &self, node: Node<'tree>, kind: NormalizedKind, enclosing: Option<NormalizedKind>, source: &str, context: &CallSiteContext, _parents: &ParentIndex<'tree>, ) -> NormalizedKind

Context-sensitive refinement with the parent index owned by the structural walk. Adapters that need ancestry can override this hook so each question is an indexed lookup rather than a tree-sitter re-descent.

fn generator_construct( &self, _node: Node<'_>, _kind: NormalizedKind, _source: &str, ) -> Option<&'static str>

A grammar-backed construct label for semantic generator rules.

fn call_site_context(&self, _root: Node<'_>, _source: &str) -> CallSiteContext

Per-file knowledge this adapter needs before it can classify any call site, gathered once from the file’s own parse tree.

fn call_site_facts( &self, _node: Node<'_>, _source: &str, _context: &CallSiteContext, ) -> Option<CallSiteFacts>

What this adapter’s grammar says about the call site at node, whose normalized kind satisfies NormalizedKind::Call.

fn supports_role(&self, _role: Role) -> bool

Whether this adapter can model role precisely enough to evaluate a query that asks for it.

fn string_literal_value_may_be_absent( &self, _node: Node<'_>, _source: &str, ) -> bool

Whether this normalized string-literal node has a known reason to lack a decoded UTF-8 value, such as a byte string or parser-reported invalid literal syntax. This per-node exception must not mask a missing decoder for an otherwise supported valid literal.

fn supports_async_callable_value(&self) -> bool

Whether this adapter records AST-backed async modifiers for every callable fact it extracts. The default is unsupported so an unknown property cannot silently become a clean miss.

fn boolean_literal_value(&self, node: Node<'_>) -> Option<bool>

Exact value of a node normalized as NormalizedKind::BooleanLiteral. This default reads tree-sitter’s underlying grammar symbol identity, which remains structured even when a grammar aliases both tokens to a common named boolean_literal node. For grammars that retain a named wrapper, it reads that wrapper’s sole non-extra child. It never reads source text.

fn async_callable_value(&self, _node: Node<'_>) -> Option<bool>

Exact async property of a normalized callable. The default leaves the property unknown; adapters must read callable modifiers from AST nodes.

fn binding_scope_selection( &self, _binder: Node<'_>, _candidate: BindingScopeCandidate<'_>, ) -> BindingScopeSelection

Select the owner of a binder from its nearest scope and successive parents. The producer owns that iterative walk; adapters classify only this candidate. Unknown ownership withholds the binding and leaves intervals incomplete.

fn declaration_binding_activation( &self, _declaration_name: Node<'_>, _scope: Range, ) -> Option<BindingActivation>

What lexical binding, if any, a declaration-name token introduces.

fn import_binder_activation( &self, _declaration: Range, scope: Range, _scope_kind: Option<NormalizedKind>, ) -> ImportActivation

The interval the local name of the import declaration spanning declaration is in effect over, inside the scope whose range is scope and whose normalized kind is scope_kind (None for the synthesized whole-file scope).

fn declaration_ambient_use(&self, _node: Node<'_>) -> Option<AmbientUseRole>

The contextual role the declaration at node carries: whether importing it can consume it without the importing file spelling the imported name.

fn segment_generic_arity(&self, _token: Node<'_>) -> Option<u32>

The number of generic (type) arguments the source spells at token’s segment position, read from the grammar’s argument-list field. None means no generic arguments are spelled there — which is a statement about the source text, not about the declaration’s own arity.

fn decode_spelling(&self, _raw: &str) -> Option<String>

The spelling raw denotes once the grammar’s identifier escaping is removed (Rust’s r#type is the identifier type).

fn embedded_syntax_kinds(&self) -> &'static [&'static str]

Parse source-backed facts hidden inside an otherwise opaque node.

fn embedded_syntax( &self, _node: Node<'_>, _source: &str, ) -> Vec<EmbeddedSyntaxTree>