Documentation
¶
Overview ¶
Package pyresolve implements the Python language in-process type resolver. It implements the typresolve.Resolver interface, resolving Python call expressions and type references using tree-sitter AST walking and a shared type registry built from extracted definitions.
Index ¶
- Constants
- func BuildImportMap(root *sitter.Node, content []byte) map[string]ImportInfo
- func BuildRegistry(defs []typresolve.ResolverDef) *typresolve.Registry
- func EvalExprType(ctx *ResolveContext, node *sitter.Node) *typresolve.Type
- func IsBuiltinFunc(name string) bool
- func IsBuiltinType(name string) bool
- func IterableElementType(iterType *typresolve.Type) *typresolve.Type
- func LiteralType(nodeType string) *typresolve.Type
- func LookupAttribute(reg *typresolve.Registry, typeQN string, memberName string) *typresolve.RegisteredFunc
- func LookupField(reg *typresolve.Registry, typeQN string, fieldName string) *typresolve.Type
- func ParseAnnotation(ann string, moduleQN string) *typresolve.Type
- func ProcessStatement(ctx *ResolveContext, node *sitter.Node)
- func RegisterStdlib(reg *typresolve.Registry)
- func ResolveBuiltinType(name string) *typresolve.Type
- func ResolveCallsInFile(ctx *ResolveContext, root *sitter.Node, fileHash types.Hash, repoURL string, ...) []types.Edge
- type ImportInfo
- type PythonResolver
- type ResolveContext
Constants ¶
const WildcardImport = "*"
WildcardImport is the sentinel name used when "from X import *" is encountered. Currently skipped by BuildImportMap.
Variables ¶
This section is empty.
Functions ¶
func BuildImportMap ¶
func BuildImportMap(root *sitter.Node, content []byte) map[string]ImportInfo
BuildImportMap builds a per-file import map from the Python AST root. It returns a map from the local binding name to its ImportInfo. Handles:
- import X (binds X as module)
- import X as Y (binds Y as module X)
- from X import Y (binds Y as symbol from X)
- from X import Y as Z (binds Z as symbol Y from X)
- import X.Y.Z (binds X, X.Y, X.Y.Z as modules)
Wildcard imports (from X import *) are skipped.
func BuildRegistry ¶
func BuildRegistry(defs []typresolve.ResolverDef) *typresolve.Registry
BuildRegistry builds a typresolve.Registry from ResolverDef entries. Registers functions, methods (with receiver type extracted from QN), classes, and module-level variables.
func EvalExprType ¶
func EvalExprType(ctx *ResolveContext, node *sitter.Node) *typresolve.Type
EvalExprType evaluates the type of a Python expression AST node using scope lookup, registry lookup, import resolution, and attribute dispatch. This is the Python port of py_eval_expr_type from the C reference.
func IsBuiltinFunc ¶
IsBuiltinFunc returns true if name is a Python builtin function.
func IsBuiltinType ¶
IsBuiltinType returns true if name is a Python builtin type.
func IterableElementType ¶
func IterableElementType(iterType *typresolve.Type) *typresolve.Type
IterableElementType returns the element type when iterating over a container type. For slices, returns the element type. For maps, returns the key type (iterating a dict yields keys). For single-element tuples, returns that element. Returns Unknown for other types.
func LiteralType ¶
func LiteralType(nodeType string) *typresolve.Type
LiteralType maps Python tree-sitter literal node types to builtin types. Returns nil if nodeType is not a recognized literal.
func LookupAttribute ¶
func LookupAttribute(reg *typresolve.Registry, typeQN string, memberName string) *typresolve.RegisteredFunc
LookupAttribute looks up a method on a named type, following MRO (base classes stored as EmbeddedTypes) up to maxMRODepth levels deep. Returns the registered function if found, nil otherwise.
func LookupField ¶
func LookupField(reg *typresolve.Registry, typeQN string, fieldName string) *typresolve.Type
LookupField looks up an instance field on a named type, following the MRO chain up to maxMRODepth levels deep. Returns the field's type if found, nil otherwise.
func ParseAnnotation ¶
func ParseAnnotation(ann string, moduleQN string) *typresolve.Type
ParseAnnotation parses a Python type annotation text into a typresolve.Type. It handles Optional[T], Union[A, B], X | Y (PEP 604), generic containers (list[T] -> Slice, dict[K, V] -> Map), forward reference quotes, Callable[[Args], Return], typing wrappers (ClassVar, Final, Annotated), and builtin scalar names. moduleQN is used to qualify bare unqualified names that are not builtins or typing constructs.
func ProcessStatement ¶
func ProcessStatement(ctx *ResolveContext, node *sitter.Node)
ProcessStatement processes a Python statement node to bind variables into the current scope. Handles assignment, for_statement, with_statement, and try_statement (except clause binding). This is the Python port of py_process_statement from the C reference implementation.
func RegisterStdlib ¶
func RegisterStdlib(reg *typresolve.Registry)
RegisterStdlib pre-registers Python stdlib modules, functions, classes, and methods into the provided registry. This enables call resolution and type evaluation for code that uses the standard library without requiring a full typeshed parse.
Coverage: os, sys, collections, pathlib, json, re, typing, io, builtins (methods on str, list, dict, set, int, float, bytes, tuple, bool, object).
func ResolveBuiltinType ¶
func ResolveBuiltinType(name string) *typresolve.Type
ResolveBuiltinType returns a typresolve.Builtin type if name is a Python builtin type, nil otherwise.
func ResolveCallsInFile ¶
func ResolveCallsInFile(ctx *ResolveContext, root *sitter.Node, fileHash types.Hash, repoURL string, filePath string) []types.Edge
ResolveCallsInFile walks a Python file's AST resolving call expressions and emitting edges. Uses the shared registry, per-file scope chain, and import map.
Types ¶
type ImportInfo ¶
type ImportInfo struct {
ModulePath string // full dotted module path (e.g. "django.db.models")
IsFromStyle bool // true for "from X import Y", false for "import X"
}
ImportInfo describes a single Python import binding.
func ResolveImport ¶
func ResolveImport(imports map[string]ImportInfo, name string) (ImportInfo, bool)
ResolveImport resolves an import local name to its ImportInfo. Returns the ImportInfo and true if found, or zero value and false otherwise.
type PythonResolver ¶
type PythonResolver struct {
// contains filtered or unexported fields
}
PythonResolver implements typresolve.Resolver for Python. It uses tree-sitter AST walking and a shared type registry to resolve call expressions and type references without requiring an external LSP server.
func NewPythonResolver ¶
func NewPythonResolver() *PythonResolver
NewPythonResolver creates a new PythonResolver.
func (*PythonResolver) InitWorkspace ¶
func (r *PythonResolver) InitWorkspace(ctx context.Context, defs []typresolve.ResolverDef) error
InitWorkspace builds the cross-file type registry from extracted definitions. Called once before any ResolveFile calls.
func (*PythonResolver) Language ¶
func (r *PythonResolver) Language() string
Language returns "python".
func (*PythonResolver) ResolveFile ¶
func (r *PythonResolver) ResolveFile(ctx context.Context, opts typresolve.ResolveFileOpts) ([]types.Edge, error)
ResolveFile resolves type references in a single Python file. Thread-safe after InitWorkspace completes (registry is read-only, all mutable state is stack-local).
type ResolveContext ¶
type ResolveContext struct {
Registry *typresolve.Registry
Scope *typresolve.Scope
Imports map[string]ImportInfo // from imports.go (Agent A)
ModuleQN string // current module qualified name
Content []byte // source file content
EnclosingFuncQN string // QN of enclosing function
EnclosingClassQN string // QN of enclosing class (for self/cls)
}
ResolveContext holds per-file state for Python type resolution.
Source Files