Skip to content

Commit f1478ec

Browse files
authored
Merge pull request #2 from CoreTrace/feat/canonical-symbol-resolution
Feat/canonical symbol resolution
2 parents 24847bc + 85cf608 commit f1478ec

12 files changed

Lines changed: 349 additions & 9 deletions

File tree

‎README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,13 @@ Currently supported inside functions: arguments, assignments, names, constants,
2626
operations, unary operations, comparisons, calls, attribute access, indexing, and returns.
2727
Unsupported syntax produces a source-located diagnostic and a non-zero exit status.
2828

29+
Module-level imports are resolved to canonical symbols. Import aliases do not change an
30+
API's identity, so all of the following resolve to `python.os.system`:
31+
32+
```python
33+
import os
34+
from os import system
35+
from os import system as run
36+
```
37+
38+
Relative and wildcard imports are not supported yet and produce source-located diagnostics.

‎examples/canonical_symbols.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
import os as operating_system
2+
3+
4+
def execute(command):
5+
operating_system.system(command)

‎src/coretrace_python/cli.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
import sys
55
from pathlib import Path
66

7+
from coretrace_python.frontend.imports import ImportResolutionError
78
from coretrace_python.frontend.lowering import LoweringError, lower_module
89
from coretrace_python.frontend.parser import ParseError, parse_file
910
from coretrace_python.ir.printer import format_module
@@ -32,7 +33,7 @@ def main(argv: list[str] | None = None) -> int:
3233
try:
3334
tree = parse_file(args.path)
3435
module = lower_module(tree, filename=str(args.path))
35-
except (OSError, ParseError, LoweringError) as error:
36+
except (OSError, ParseError, ImportResolutionError, LoweringError) as error:
3637
print(f"error: {error}", file=sys.stderr)
3738
return 1
3839

@@ -42,4 +43,3 @@ def main(argv: list[str] | None = None) -> int:
4243

4344
if __name__ == "__main__":
4445
raise SystemExit(main())
45-
Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
"""Collection of module-level import bindings."""
2+
3+
from __future__ import annotations
4+
5+
import ast
6+
from collections.abc import Iterator, Mapping
7+
from dataclasses import dataclass
8+
9+
from coretrace_python.ir.symbol import SymbolId
10+
11+
12+
class ImportResolutionError(Exception):
13+
"""A source-located import that cannot be represented safely."""
14+
15+
16+
@dataclass(frozen=True)
17+
class ImportBindings(Mapping[str, SymbolId]):
18+
"""Map names visible in a module to their canonical identities."""
19+
20+
_bindings: dict[str, SymbolId]
21+
22+
def __getitem__(self, name: str) -> SymbolId:
23+
return self._bindings[name]
24+
25+
def __iter__(self) -> Iterator[str]:
26+
return iter(self._bindings)
27+
28+
def __len__(self) -> int:
29+
return len(self._bindings)
30+
31+
def resolve(self, name: str) -> SymbolId | None:
32+
return self._bindings.get(name)
33+
34+
35+
def _error(filename: str, node: ast.AST, message: str) -> ImportResolutionError:
36+
line = getattr(node, "lineno", 1)
37+
column = getattr(node, "col_offset", 0) + 1
38+
return ImportResolutionError(f"{filename}:{line}:{column}: {message}")
39+
40+
41+
def collect_imports(tree: ast.Module, filename: str = "<unknown>") -> ImportBindings:
42+
"""Collect supported top-level imports without importing any modules."""
43+
44+
bindings: dict[str, SymbolId] = {}
45+
for statement in tree.body:
46+
if isinstance(statement, ast.Import):
47+
for alias in statement.names:
48+
if alias.asname is None:
49+
local_name = alias.name.partition(".")[0]
50+
canonical_path = local_name
51+
else:
52+
local_name = alias.asname
53+
canonical_path = alias.name
54+
bindings[local_name] = SymbolId.from_python_path(canonical_path)
55+
elif isinstance(statement, ast.ImportFrom):
56+
if statement.level:
57+
raise _error(filename, statement, "relative imports are not supported yet")
58+
if statement.module is None:
59+
raise _error(filename, statement, "import module is missing")
60+
for alias in statement.names:
61+
if alias.name == "*":
62+
raise _error(filename, statement, "wildcard imports are not supported")
63+
local_name = alias.asname or alias.name
64+
canonical_path = f"{statement.module}.{alias.name}"
65+
bindings[local_name] = SymbolId.from_python_path(canonical_path)
66+
return ImportBindings(bindings)
67+

‎src/coretrace_python/frontend/lowering.py‎

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
import ast
44
from dataclasses import dataclass, field
55

6+
from coretrace_python.frontend.imports import ImportBindings, collect_imports
7+
from coretrace_python.frontend.symbols import SymbolId
68
from coretrace_python.ir.model import (
79
BasicBlock,
810
BinaryOp,
@@ -18,8 +20,10 @@
1820
Return,
1921
SourceLocation,
2022
StoreLocal,
23+
Symbol,
2124
UnaryOp,
2225
Value,
26+
ValueInstruction,
2327
)
2428

2529

@@ -60,6 +64,7 @@ class LoweringError(Exception):
6064
@dataclass
6165
class _FunctionLowerer:
6266
filename: str
67+
imports: ImportBindings
6368
next_value_id: int = 0
6469
locals: dict[str, Value] = field(default_factory=dict)
6570
block: BasicBlock = field(default_factory=lambda: BasicBlock("entry"))
@@ -86,12 +91,28 @@ def new_value(self) -> Value:
8691
self.next_value_id += 1
8792
return value
8893

89-
def emit(self, instruction):
94+
def emit(self, instruction: ValueInstruction) -> Value:
9095
self.block.instructions.append(instruction)
9196
return instruction.result
9297

98+
def emit_effect(self, instruction: StoreLocal | Return) -> None:
99+
self.block.instructions.append(instruction)
100+
101+
def imported_symbol(self, node: ast.expr) -> SymbolId | None:
102+
if isinstance(node, ast.Name):
103+
if node.id in self.locals or node.id in self.parameters:
104+
return None
105+
return self.imports.resolve(node.id)
106+
if isinstance(node, ast.Attribute):
107+
parent = self.imported_symbol(node.value)
108+
return parent.attribute(node.attr) if parent is not None else None
109+
return None
110+
93111
def expression(self, node: ast.expr) -> Value:
94112
location = self.location(node)
113+
imported_symbol = self.imported_symbol(node)
114+
if imported_symbol is not None:
115+
return self.emit(Symbol(self.new_value(), location, imported_symbol))
95116
if isinstance(node, ast.Name):
96117
if node.id in self.locals:
97118
return self.emit(LoadLocal(self.new_value(), location, node.id))
@@ -159,12 +180,12 @@ def statement(self, node: ast.stmt) -> None:
159180
self.fail(node, "only assignment to one local name is supported")
160181
name = node.targets[0].id
161182
value = self.expression(node.value)
162-
self.emit(StoreLocal(None, self.location(node), name, value))
183+
self.emit_effect(StoreLocal(None, self.location(node), name, value))
163184
self.locals[name] = value
164185
return
165186
if isinstance(node, ast.Return):
166187
value = self.expression(node.value) if node.value is not None else None
167-
self.emit(Return(None, self.location(node), value))
188+
self.emit_effect(Return(None, self.location(node), value))
168189
return
169190
if isinstance(node, ast.Expr):
170191
self.expression(node.value)
@@ -190,10 +211,13 @@ def function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> FunctionIR:
190211

191212

192213
def lower_module(tree: ast.Module, filename: str = "<unknown>") -> ModuleIR:
214+
imports = collect_imports(tree, filename)
193215
functions: list[FunctionIR] = []
194216
for statement in tree.body:
195217
if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
196-
functions.append(_FunctionLowerer(filename).function(statement))
218+
functions.append(_FunctionLowerer(filename, imports).function(statement))
219+
elif isinstance(statement, (ast.Import, ast.ImportFrom)):
220+
continue
197221
elif isinstance(statement, ast.Expr) and isinstance(statement.value, ast.Constant):
198222
# Permit module docstrings.
199223
continue
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
"""Frontend support for canonical Python symbols."""
2+
3+
from coretrace_python.ir.symbol import SymbolId
4+
5+
__all__ = ["SymbolId"]

‎src/coretrace_python/ir/model.py‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
from dataclasses import dataclass
55
from typing import TypeAlias
66

7+
from coretrace_python.ir.symbol import SymbolId
8+
79

810
@dataclass(frozen=True)
911
class SourceLocation:
@@ -37,6 +39,13 @@ class Global:
3739
name: str
3840

3941

42+
@dataclass(frozen=True)
43+
class Symbol:
44+
result: Value
45+
location: SourceLocation
46+
symbol_id: SymbolId
47+
48+
4049
@dataclass(frozen=True)
4150
class BinaryOp:
4251
result: Value
@@ -109,19 +118,20 @@ class StoreLocal:
109118
value: Value
110119

111120

112-
Instruction: TypeAlias = (
121+
ValueInstruction: TypeAlias = (
113122
Constant
114123
| Global
124+
| Symbol
115125
| BinaryOp
116126
| UnaryOp
117127
| Compare
118128
| Call
119129
| GetAttr
120130
| GetItem
121131
| LoadLocal
122-
| StoreLocal
123-
| Return
124132
)
133+
EffectInstruction: TypeAlias = StoreLocal | Return
134+
Instruction: TypeAlias = ValueInstruction | EffectInstruction
125135

126136

127137
@dataclass(frozen=True)

‎src/coretrace_python/ir/printer.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
ModuleIR,
1414
Return,
1515
StoreLocal,
16+
Symbol,
1617
UnaryOp,
1718
Value,
1819
)
@@ -27,6 +28,8 @@ def _instruction(instruction: Instruction) -> str:
2728
return f"{_value(instruction.result)} = const {instruction.value!r}"
2829
if isinstance(instruction, Global):
2930
return f"{_value(instruction.result)} = global {instruction.name!r}"
31+
if isinstance(instruction, Symbol):
32+
return f"{_value(instruction.result)} = symbol @{instruction.symbol_id}"
3033
if isinstance(instruction, BinaryOp):
3134
return (
3235
f"{_value(instruction.result)} = binary.{instruction.operator} "

‎src/coretrace_python/ir/symbol.py‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
"""Canonical symbol identities stored in PyIR."""
2+
3+
from __future__ import annotations
4+
5+
from dataclasses import dataclass
6+
7+
8+
@dataclass(frozen=True, order=True)
9+
class SymbolId:
10+
"""A stable, import-style-independent name for a Python object."""
11+
12+
canonical_name: str
13+
14+
def __post_init__(self) -> None:
15+
if not self.canonical_name.startswith("python."):
16+
raise ValueError("canonical Python symbols must start with 'python.'")
17+
18+
@classmethod
19+
def from_python_path(cls, path: str) -> SymbolId:
20+
normalized_path = path.removeprefix("python.")
21+
if not normalized_path or normalized_path.startswith("."):
22+
raise ValueError("a Python symbol path cannot be empty")
23+
return cls(f"python.{normalized_path}")
24+
25+
def attribute(self, name: str) -> SymbolId:
26+
if not name or "." in name:
27+
raise ValueError("an attribute name must be one non-empty component")
28+
return SymbolId(f"{self.canonical_name}.{name}")
29+
30+
def __str__(self) -> str:
31+
return self.canonical_name
32+

‎tests/test_imports.py‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
from __future__ import annotations
2+
3+
import pytest
4+
5+
from coretrace_python.frontend.imports import (
6+
ImportBindings,
7+
ImportResolutionError,
8+
collect_imports,
9+
)
10+
from coretrace_python.frontend.parser import parse_source
11+
from coretrace_python.ir.symbol import SymbolId
12+
13+
14+
def bindings_for(source: str) -> ImportBindings:
15+
return collect_imports(parse_source(source, "imports.py"), "imports.py")
16+
17+
18+
def test_collects_plain_and_aliased_imports() -> None:
19+
bindings = bindings_for("import os\nimport subprocess as sp\n")
20+
assert bindings["os"] == SymbolId("python.os")
21+
assert bindings["sp"] == SymbolId("python.subprocess")
22+
23+
24+
def test_plain_dotted_import_binds_its_top_level_package() -> None:
25+
bindings = bindings_for("import xml.etree.ElementTree\n")
26+
assert bindings["xml"] == SymbolId("python.xml")
27+
28+
29+
def test_collects_from_imports() -> None:
30+
bindings = bindings_for("from os import system as run\n")
31+
assert bindings["run"] == SymbolId("python.os.system")
32+
33+
34+
def test_wildcard_import_is_rejected_with_location() -> None:
35+
with pytest.raises(
36+
ImportResolutionError,
37+
match=r"imports.py:1:1: wildcard imports are not supported",
38+
):
39+
bindings_for("from os import *\n")

0 commit comments

Comments
 (0)