tpy-lang 0.3.0.dev0__py3-none-any.whl

tpyc/frontend_ir/resolver_adapter.py

@@ -0,0 +1,151 @@
+"""Parser-shaped adapter so the real `TypeResolver` works on
+plugin-lowered modules unchanged.
+
+`TypeResolver` reads a handful of attributes off its owning `Parser`
+(see the TypeResolver docstring for the contract): `registry`,
+`_imports`, `_type_param_scope`, `_module_class_names`,
+`_module_type_alias_names`, `_module_aliases`, `_reverse_module_aliases`,
+`_nested_type_scope`, `_local_defs`, `_bare_module_imports`. Plus
+three methods: `_resolve_type_name`, `_raise_unresolved_import_error`,
+`_warn_at_loc`.
+
+`_PluginParserAdapter` implements that contract for plugin modules
+without instantiating a real `Parser`. Plugin lowering populates it
+from the IR (imports, module name, directives); the rest of the
+parser-internal bookkeeping is empty-but-correct frozensets/dicts.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from ..parse import SourceLocation
+from ..parse.imports import (
+    ImportProcessor, get_builtins_exports, get_tpy_exports, get_typing_exports,
+)
+from ..parse.nodes import ParseError
+from ..parse.type_resolver import TypeResolver
+from ..typesys import TypeRegistry
+
+
+class _PluginParserAdapter:
+    """Parser-shaped object consumed by `TypeResolver`.
+
+    Constructed once per plugin-lowered module. Lowering fills the
+    import-related attributes from the IR; the parser-only bookkeeping
+    fields stay at safe defaults (empty frozensets, empty dicts) because
+    plugin modules have no parse-time class scan, no Python `ast` to
+    consult, and no `# tpy:` directive scanning.
+    """
+
+    def __init__(
+        self,
+        module_name: str,
+        is_entry_point: bool,
+        shared_modules: 'dict | None' = None,
+    ) -> None:
+        self.registry = TypeRegistry(shared_modules=shared_modules)
+        self._imports = ImportProcessor(self._warn, module_name=module_name)
+        self._imports.imports = {}
+        self._module_name = module_name
+        self._is_entry_point = is_entry_point
+
+        # Parser-only bookkeeping. Plugin lowering produces no `ast` to
+        # walk, so all of these stay empty -- TypeResolver still consults
+        # them but they correctly answer "nothing here" in every case.
+        self._local_defs: frozenset[str] = frozenset()
+        self._module_class_names: frozenset[str] = frozenset()
+        self._module_type_alias_names: frozenset[str] = frozenset()
+        self._module_aliases: dict[str, str] = {}
+        self._reverse_module_aliases: dict[str, str] = {}
+        self._bare_module_imports: set[str] = set()
+        self._nested_type_scope: dict[str, str] = {}
+        self._type_param_scope: dict[str, object] | None = None
+
+        # Parser-side warnings collected by `_warn_at_loc`. Plugin
+        # lowering does not currently surface these back, but holding
+        # them avoids reaching into a `None`.
+        self._warnings: list[tuple[str, SourceLocation | None]] = []
+
+    # ------------------------------------------------------------------
+    # Methods TypeResolver calls on the parser
+
+    def _resolve_type_name(self, local_name: str) -> tuple[str, str] | None:
+        """Mirror `Parser._resolve_type_name` for plugin-lowered modules.
+
+        Plugin modules have no `_local_defs` (no Python ast to scan) and
+        no locally-registered builtins, so the parser version's first
+        branch and last branch are no-ops here. The remaining logic --
+        consult the import name index, fall back to ambient builtins --
+        applies unchanged.
+        """
+        source = self._imports.get_import_source(local_name)
+        if source:
+            return source
+        # `get_builtins_exports` is the Python `builtins` surface (`int`,
+        # `str`, ...). Plugin modules can reference these without an
+        # explicit import, exactly as Python source can.
+        if local_name in get_builtins_exports():
+            return ("builtins", local_name)
+        return None
+
+    def _raise_unresolved_import_error(
+        self,
+        raw_name: str,
+        node: object | None = None,
+        *,
+        loc: SourceLocation | None = None,
+    ) -> None:
+        """Mirror the parser's import-hint diagnostic."""
+        if raw_name in get_typing_exports():
+            raise ParseError(
+                f"'{raw_name}' requires: from typing import {raw_name}",
+                loc=loc,
+            )
+        if raw_name in get_tpy_exports():
+            raise ParseError(
+                f"'{raw_name}' requires: from tpy import {raw_name}",
+                loc=loc,
+            )
+
+    def _warn_at_loc(self, message: str, loc: SourceLocation | None) -> None:
+        self._warnings.append((message, loc))
+
+    # Helper used as ImportProcessor's `warn_fn`.
+    def _warn(self, message: str, node: object | None = None,
+              *, loc: SourceLocation | None = None) -> None:
+        self._warnings.append((message, loc))
+
+
+def make_plugin_resolver(
+    module_name: str,
+    is_entry_point: bool = False,
+    shared_modules: 'dict | None' = None,
+    *,
+    imports: 'dict[str, set[tuple[str, str]] | None] | None' = None,
+    name_index: 'Iterable[tuple[str, str, str]]' = (),
+) -> TypeResolver:
+    """Build a `TypeResolver` for a plugin-lowered module.
+
+    `imports` and `name_index` mirror the parser's two-tier import
+    bookkeeping:
+      - `imports`: module-name -> set of `(original, local)` tuples
+        (or None for whole-module imports). Mirrors `TpyModule.imports`.
+      - `name_index`: each entry is `(local_name, source_module,
+        original_name)`. Mirrors what `ImportProcessor._index_import`
+        would have produced during parsing.
+
+    The two tables exist for distinct lookup needs in TypeResolver --
+    `imports` is consulted for whole-module imports while resolving
+    qualified names; `name_index` is consulted for the bare-name path.
+    """
+    adapter = _PluginParserAdapter(
+        module_name=module_name,
+        is_entry_point=is_entry_point,
+        shared_modules=shared_modules,
+    )
+    if imports is not None:
+        adapter._imports.imports = imports
+    for local, src_mod, orig in name_index:
+        adapter._imports.index_imported_name(local, src_mod, orig)
+    return TypeResolver(adapter)

tpyc/frontend_plugin.py

@@ -0,0 +1,209 @@
+"""Frontend plugin contract + loader.
+
+See `docs/FRONTEND_PLUGIN_DESIGN.md` for the contract specification.
+
+M1 scope: plugin discovery + WorkspaceContext + registry. Decorator
+manifests are accepted but unused (no registry yet). Subprocess-helper
+SubprocessPlugin is future work.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import ClassVar, Iterable
+
+from .diagnostics import Diagnostic, DiagnosticLevel
+from .frontend_ir.nodes import API_VERSION, FrontendModule
+
+
+@dataclass(frozen=True)
+class WorkspaceContext:
+    """Read-only view of the compile-time environment exposed to plugins.
+
+    M1 carries only the fields hello-world needs: `options` (routed
+    `--dsl-opt` values for this plugin), `no_stdlib` (mirror of the
+    compiler flag), and `read_file` for opening the entry source.
+    `find_files` and `resolve_module` from the design doc are deferred
+    until a plugin needs them.
+
+    `stdlib_search_dirs` is the subset of `search_dirs` that holds
+    TPy's implicit stdlib (`lib/tpy/`). Plugins that translate a
+    `uses`- or `import`-style directive in their source language can
+    consult this to keep stdlib invisible to bare imports while still
+    leaving an escape hatch (e.g. `uses py.math` in Pascal) that
+    routes through the full search path.
+    """
+    api_version: int
+    entry_point: Path
+    search_dirs: tuple[Path, ...]
+    stdlib_search_dirs: tuple[Path, ...]
+    options: dict[str, str]
+    no_stdlib: bool
+
+    def read_file(self, path: Path) -> str:
+        return Path(path).read_text()
+
+
+@dataclass
+class FrontendOutput:
+    """Return value from `FrontendPlugin.parse()`."""
+    module: FrontendModule
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+
+
+class FrontendPluginError(Exception):
+    """Fatal error raised by a plugin when it cannot produce IR.
+
+    Carries one `Diagnostic`; the compiler catches it and reports the
+    diagnostic as `PLUGIN_REPORTED`.
+    """
+    def __init__(self, diagnostic: Diagnostic):
+        super().__init__(diagnostic.message)
+        self.diagnostic = diagnostic
+
+
+class FrontendPlugin(ABC):
+    """Base class for frontend plugins.
+
+    Subclasses set the ClassVar metadata and implement `parse()`.
+    Plugin modules expose the subclass (not an instance) as the module
+    attribute `PLUGIN`; the compiler instantiates it once per `tpyc`
+    invocation with the routed options dict.
+    """
+    api_version: ClassVar[int] = API_VERSION
+    name: ClassVar[str] = ""
+    extensions: ClassVar[tuple[str, ...]] = ()
+    decorator_manifest: ClassVar[tuple] = ()
+
+    def __init__(self, options: dict[str, str]) -> None:
+        self.options = options
+
+    @abstractmethod
+    def parse(self, ctx: WorkspaceContext,
+              module_name: str, file_path: Path) -> FrontendOutput:
+        ...
+
+    def library_paths(self) -> tuple[Path, ...]:
+        """Extra directories the plugin contributes to TPy's module
+        search path. The CLI prepends these to `lib_dirs` after the
+        user's `-L` so plugin-shipped libraries (e.g. the Pascal
+        stdlib under `pascal/lib/`) resolve without the user having
+        to pass `-L` for each one. Returns an empty tuple by default.
+        """
+        return ()
+
+
+@dataclass
+class FrontendRegistry:
+    """Maps file extensions to plugin instances."""
+    by_extension: dict[str, FrontendPlugin] = field(default_factory=dict)
+    plugins: list[FrontendPlugin] = field(default_factory=list)
+
+    def register(self, plugin: FrontendPlugin) -> None:
+        for ext in plugin.extensions:
+            if ext in self.by_extension:
+                existing = self.by_extension[ext]
+                raise FrontendPluginError(Diagnostic(
+                    level=DiagnosticLevel.ERROR,
+                    message=(f"extension {ext!r} claimed by both "
+                             f"{existing.name!r} and {plugin.name!r}"),
+                ))
+            self.by_extension[ext] = plugin
+        self.plugins.append(plugin)
+
+    def for_path(self, path: Path) -> FrontendPlugin | None:
+        return self.by_extension.get(path.suffix)
+
+    def claims_extension(self, ext: str) -> bool:
+        return ext in self.by_extension
+
+    def all_extensions(self) -> frozenset[str]:
+        return frozenset(self.by_extension.keys())
+
+
+def resolve_plugin_class(spec: str) -> type[FrontendPlugin]:
+    """Load a plugin module and return its `PLUGIN` class without
+    instantiating it. Used when the caller needs to read `name` /
+    `extensions` / `api_version` ClassVars (e.g. to route
+    `--dsl-opt` values to the right plugin, or to learn which
+    source extensions a plugin claims) before deciding what
+    options dict to pass to `__init__`.
+
+    Steps follow `docs/FRONTEND_PLUGIN_DESIGN.md` "Loading and
+    registration":
+      1. If spec resolves to an existing .py file, import via spec_from_file_location.
+      2. Else, treat spec as an importable module name.
+      3. Fetch `PLUGIN`; validate it is a FrontendPlugin subclass.
+      4. Validate api_version is supported.
+    """
+    spec_path = Path(spec)
+    module = None
+    if spec_path.suffix == ".py" and spec_path.exists():
+        module_name = f"_tpyc_plugin_{spec_path.stem}"
+        loader_spec = importlib.util.spec_from_file_location(module_name, spec_path)
+        if loader_spec is None or loader_spec.loader is None:
+            raise _plugin_load_error(
+                f"cannot load plugin file: {spec}")
+        module = importlib.util.module_from_spec(loader_spec)
+        loader_spec.loader.exec_module(module)
+    else:
+        try:
+            module = importlib.import_module(spec)
+        except ImportError as e:
+            raise _plugin_load_error(
+                f"cannot import plugin module {spec!r}: {e}")
+
+    plugin_cls = getattr(module, "PLUGIN", None)
+    if plugin_cls is None:
+        raise _plugin_load_error(
+            f"plugin module {spec!r} has no PLUGIN attribute")
+    if not (isinstance(plugin_cls, type) and issubclass(plugin_cls, FrontendPlugin)):
+        raise _plugin_load_error(
+            f"plugin module {spec!r}: PLUGIN must be a FrontendPlugin subclass, "
+            f"got {plugin_cls!r}")
+    if plugin_cls.api_version != API_VERSION:
+        raise _plugin_load_error(
+            f"plugin {plugin_cls.name!r} declares api_version="
+            f"{plugin_cls.api_version}; compiler supports {API_VERSION}")
+    return plugin_cls
+
+
+def load_plugin(spec: str, options: dict[str, str]) -> FrontendPlugin:
+    """Resolve the plugin class and instantiate it with `options`.
+    Equivalent to `resolve_plugin_class(spec)(options)`; kept for
+    callers that don't need to inspect the class before
+    construction.
+    """
+    return resolve_plugin_class(spec)(options)
+
+
+def route_dsl_opts(
+    flags: Iterable[str], known_plugin_names: Iterable[str],
+) -> dict[str, dict[str, str]]:
+    """Split `--dsl-opt name.key=value` strings into per-plugin dicts.
+
+    Returns `{plugin_name: {key: value, ...}}`. Raises FrontendPluginError
+    when an option does not match `name.key=value` or `name` is not a
+    registered plugin.
+    """
+    known = set(known_plugin_names)
+    out: dict[str, dict[str, str]] = {n: {} for n in known}
+    for raw in flags:
+        if "=" not in raw or "." not in raw.split("=", 1)[0]:
+            raise _plugin_load_error(
+                f"--dsl-opt must be 'name.key=value'; got {raw!r}")
+        head, value = raw.split("=", 1)
+        name, key = head.split(".", 1)
+        if name not in known:
+            raise _plugin_load_error(
+                f"--dsl-opt {raw!r}: no plugin named {name!r}")
+        out[name][key] = value
+    return out
+
+
+def _plugin_load_error(msg: str) -> FrontendPluginError:
+    return FrontendPluginError(Diagnostic(level=DiagnosticLevel.ERROR, message=msg))

tpyc/install_docs.py

@@ -0,0 +1,81 @@
+"""Install TurboPython agent docs into a target project."""
+
+import io
+from contextlib import redirect_stdout
+from pathlib import Path
+import shutil
+
+from . import get_docs_dir
+from .dump_types import dump_builtin_types
+
+# (source name in wheel/repo, target name in user project)
+# In dev layout, get_docs_dir() resolves to the repo's docs/ which contains
+# more files than we ship -- we iterate this explicit allowlist to avoid
+# copying design docs.
+_DOC_FILES: list[tuple[str, str]] = [
+    ("TPY_FOR_AGENTS.md", "TPY_FOR_AGENTS.md"),
+    ("LANGUAGE_FEATURES.md", "TPY_LANGUAGE_FEATURES.md"),
+    ("STDLIB_ROADMAP.md", "TPY_STDLIB_ROADMAP.md"),
+]
+
+_API_REFERENCE_FILENAME = "TPY_API_REFERENCE.md"
+
+
+def install_agent_docs(target_dir: Path) -> list[Path]:
+    """Copy agent docs into target_dir, overwriting any existing copies.
+
+    Creates target_dir if missing. Returns the list of written paths.
+    Raises NotADirectoryError if target_dir exists as a regular file.
+    """
+    if target_dir.exists() and not target_dir.is_dir():
+        raise NotADirectoryError(
+            f"Cannot install agent docs into {target_dir}: "
+            f"path exists and is not a directory"
+        )
+    target_dir.mkdir(parents=True, exist_ok=True)
+    src = get_docs_dir()
+    written: list[Path] = []
+    for src_name, dst_name in _DOC_FILES:
+        dst = target_dir / dst_name
+        shutil.copyfile(src / src_name, dst)
+        written.append(dst)
+
+    # Generated reference: API surface reflected from the installed stubs.
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        dump_builtin_types()
+    dst = target_dir / _API_REFERENCE_FILENAME
+    dst.write_text(buf.getvalue(), encoding="utf-8")
+    written.append(dst)
+
+    return written
+
+
+def agents_md_snippet(target_dir: Path) -> str:
+    """Return the copy-pasteable section to append to AGENTS.md/CLAUDE.md.
+
+    target_dir should be the path as the user typed it (typically relative),
+    so the snippet references paths that make sense in the user's project.
+    """
+    path_prefix = target_dir.as_posix().rstrip("/")
+    return f"""\
+## TurboPython (TPy) documentation
+
+This project uses TurboPython (tpyc) to compile Python source to C++.
+When writing or modifying `.py` files compiled by tpyc:
+
+- Start with `{path_prefix}/TPY_FOR_AGENTS.md` -- concise bootstrap
+  covering the Python-to-TPy delta, ownership rules, and idiomatic
+  patterns. Read this before writing TPy code.
+- Consult `{path_prefix}/TPY_LANGUAGE_FEATURES.md` for depth on specific
+  features. Only sections marked **Working** are usable today.
+- Check `{path_prefix}/TPY_STDLIB_ROADMAP.md` before using a Python stdlib
+  module -- coverage is partial and some modules are missing or blocked.
+- Look up concrete API surface in `{path_prefix}/TPY_API_REFERENCE.md` --
+  auto-generated from the installed stubs (builtins, `tplib.*`, and
+  bundled stdlib modules). Reflects exactly what's callable in this
+  version, with signatures and methods.
+
+These files are bundled from the installed tpyc toolchain. Refresh with
+`tpyc --install-agent-docs {path_prefix}` after upgrading tpyc.
+"""