refactor(parser): introduce icp function for creating InteractiveContextParser instances for clean handling of set_grammar

Author: incrementaliser

src/dylan/gui/parse_session.py

@@ -120,7 +120,8 @@ def __init__(self) -> None:
     def set_grammar(self, path_str: str, *, repairing: bool) -> str:
         """Load grammar from a filesystem directory *path_str*; return log text and set ``self.parser``.
 
-        Bundled grammar nicknames (e.g. ``\"ttr\"``) are only accepted by :func:`dynamicsyntax.set_grammar`;
+        Bundled grammar nicknames (e.g. ``\"ttr\"``) are only accepted on a parser from
+        :func:`dynamicsyntax.icp` via :meth:`InteractiveContextParser.set_grammar`;
         this GUI/session path expects a real directory from the file picker.
         """
         p = Path(path_str.strip())

src/dylan/parser/interactive_context_parser.py

@@ -19,7 +19,7 @@
 from dylan.formula.formula import Formula
 from dylan.formula.ttr_formula import TTRFormula
 from dylan.formula.ttr_record_type import TTRRecordType
-from dylan.nlp.types import Dialogue, WAIT_TOKEN, RELEASE_TURN_TOKEN, Utterance
+from dylan.nlp.types import DEFAULT_SPEAKER, Dialogue, WAIT_TOKEN, RELEASE_TURN_TOKEN, Utterance
 from dylan.parser.dag_parser import DAGParser
 from dylan.tree.label.labels import Requirement, TypeLabel
 from dylan.tree.node_address import NodeAddress
@@ -87,27 +87,108 @@ class InteractiveContextParser(DAGParser):
 
     def __init__(
         self,
-        resource_dir: str | Path,
+        resource_dir: str | Path | None = None,
+        *,
         repairing: bool = False,
         top_n: int | tuple[str, ...] = 3,
         participants: tuple[str, ...] = (DEFAULT_NAME,),
     ) -> None:
-        p = Path(resource_dir)
+        """Construct a parser with optional *resource_dir* (filesystem directory or bundled grammar id)."""
+        participants_resolved = participants if participants else (DEFAULT_NAME,)
         if not isinstance(top_n, int):
-            participants = top_n
+            participants_resolved = top_n  # type: ignore[assignment]
             top_n = 3
-        super().__init__(Lexicon(p, top_n), Grammar(p), SpeechActInferenceGrammar(p))
+        self._top_n = top_n
+        self._participants = participants_resolved
+        self._default_repairing = repairing
+
+        if resource_dir is None:
+            self._init_shell_unloaded()
+            return
+
+        p = Path(resource_dir) if isinstance(resource_dir, str) else resource_dir
+        if p.is_dir():
+            self._apply_resource_dir(p, repairing=repairing)
+            return
+
+        self._init_shell_unloaded()
+        self.set_grammar(resource_dir, repairing=repairing)
+
+    def _init_shell_unloaded(self) -> None:
+        """Initialise placeholder lexicon/grammar with no dialogue ``context`` until :meth:`set_grammar`."""
+        DAGParser.__init__(
+            self,
+            Lexicon(None, self._top_n),
+            Grammar(None),
+            SpeechActInferenceGrammar(Path(".")),
+        )
+        self.context = None
+        self.forced_restart = False
+        self.forced_repair = False
+        self.right_edge_indicators = []
+        self.acks = ["uhu"]
+        self.repairanda = ["uhh", "errm", "err", "er", "uh", "erm", "uhm", "um", "oh"]
+        self.forced_repairanda = ["sorry", "oops", "wait", "erm"]
+        self.restarters = ["yeah"]
+
+    def _apply_resource_dir(self, path: Path, *, repairing: bool) -> None:
+        """Load lexicon and grammars from *path* and wire a fresh :class:`Context`."""
+        parts = self._participants if self._participants else (DEFAULT_NAME,)
+        DAGParser.__init__(
+            self,
+            Lexicon(path, self._top_n),
+            Grammar(path),
+            SpeechActInferenceGrammar(path),
+        )
         dag = WordLevelContextDAG()
-        parts = participants if participants else (DEFAULT_NAME,)
         self.context = Context(dag, self.sa_grammar, *parts)
         self.context.set_repair_processing(repairing)
         self.forced_restart = False
         self.forced_repair = False
-        self.right_edge_indicators: list[str] = []
-        self.acks: list[str] = ["uhu"]
-        self.repairanda: list[str] = ["uhh", "errm", "err", "er", "uh", "erm", "uhm", "um", "oh"]
-        self.forced_repairanda: list[str] = ["sorry", "oops", "wait", "erm"]
-        self.restarters: list[str] = ["yeah"]
+        self.right_edge_indicators = []
+        self.acks = ["uhu"]
+        self.repairanda = ["uhh", "errm", "err", "er", "uh", "erm", "uhm", "um", "oh"]
+        self.forced_repairanda = ["sorry", "oops", "wait", "erm"]
+        self.restarters = ["yeah"]
+        self.init()
+
+    def set_grammar(self, grammar: str | Path, *, repairing: bool | None = None) -> None:
+        """Load grammar files from a directory path or bundled grammar id/alias into this parser."""
+        from dynamicsyntax._session import resolved_grammar_path
+
+        rep = self._default_repairing if repairing is None else repairing
+        with resolved_grammar_path(grammar) as path:
+            self._apply_resource_dir(path, repairing=rep)
+
+    def parse(
+        self,
+        sentence_or_goal: str | Formula | None = None,
+        /,
+        *,
+        speaker: str = DEFAULT_SPEAKER,
+        trace: bool = False,
+    ) -> object:
+        """Parse a surface string into a :class:`~dynamicsyntax.parse_result.ParseResult`, or run ``parse_goal``.
+
+        Pass a ``str`` for high-level sentence parsing (requires :meth:`set_grammar` first unless
+        constructed with a grammar). Pass ``None`` or a :class:`~dylan.formula.formula.Formula`
+        for the internal ``parse_goal`` path (Java ``DAGParser.parse``).
+        """
+        if isinstance(sentence_or_goal, str):
+            return self._parse_surface(sentence_or_goal, speaker=speaker, trace=trace)
+        return self.parse_goal(sentence_or_goal)
+
+    def _parse_surface(self, sentence: str, *, speaker: str, trace: bool) -> object:
+        """Run :func:`~dynamicsyntax._parse._run_parse_core` for a non-goal surface string."""
+        if self.context is None:
+            raise ValueError("grammar not loaded; call set_grammar(...) first")
+        from dynamicsyntax._parse import _run_parse_core
+        from dynamicsyntax.parse_result import ParseResult
+
+        stripped = sentence.strip()
+        if not stripped:
+            return ParseResult(ok=False, semantics=None, tree=None, sentence="", parser=self)
+        return _run_parse_core(self, stripped, speaker=speaker, trace=trace)
 
     @classmethod
     def from_loaded(
@@ -125,6 +206,9 @@ def from_loaded(
         parts = participants if participants else (DEFAULT_NAME,)
         obj.context = Context(dag, obj.sa_grammar, *parts)
         obj.context.set_repair_processing(False)
+        obj._top_n = lexicon.top_n
+        obj._participants = parts
+        obj._default_repairing = False
         obj.forced_restart = False
         obj.forced_repair = False
         obj.right_edge_indicators = []
@@ -136,10 +220,14 @@ def from_loaded(
 
     def get_name(self) -> str:
         """Return this parser's context name."""
+        if self.context is None:
+            return DEFAULT_NAME
         return self.context.get_name()
 
     def repair_initiated(self) -> bool:
         """Return whether local repair has been initiated."""
+        if self.context is None:
+            return False
         return self.context.repair_initiated()
 
     def _adjust_once(self, goal: Formula | None) -> bool:

src/dynamicsyntax/__init__.py

@@ -1,25 +1,42 @@
-"""Public facade for the *dynamicsyntax* distribution (high-level :func:`parse`)."""
+"""Public facade for the *dynamicsyntax* distribution (high-level :func:`parse` and :func:`icp`)."""
 
 from __future__ import annotations
 
 from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
 
 from dylan.action.lexicon import NotebookMultilineText
 from dylan.formula.latex.build_result import LaTeXBuildResult
 from dylan.formula.manim.models import ManimBuildResult
 from dylan.formula.ttr_record_type import TTRRecordType
-from dylan.parser.interactive_context_parser import InteractiveContextParser
+from dylan.parser.interactive_context_parser import DEFAULT_NAME, InteractiveContextParser
 
 from dynamicsyntax._manim import to_manim
 from dynamicsyntax._parse import parse
-from dynamicsyntax._session import get_datasets, get_grammars, set_grammar
+from dynamicsyntax._session import get_datasets, get_grammars
 from dynamicsyntax.parse_result import ParseResult
 
 try:
     __version__: str = version("dynamicsyntax")
 except PackageNotFoundError:  # pragma: no cover - editable checkout without metadata
     __version__ = "0.0.0"
 
+
+def icp(
+    grammar: str | Path | None = None,
+    *,
+    repairing: bool = False,
+    top_n: int | tuple[str, ...] = 3,
+    participants: tuple[str, ...] = (DEFAULT_NAME,),
+) -> InteractiveContextParser:
+    """Return an :class:`~dylan.parser.interactive_context_parser.InteractiveContextParser` (short alias ``icp``).
+
+    With no *grammar*, returns an unloaded parser; call :meth:`~dylan.parser.interactive_context_parser.InteractiveContextParser.set_grammar`
+    before :meth:`~dylan.parser.interactive_context_parser.InteractiveContextParser.parse`.
+    """
+    return InteractiveContextParser(grammar, repairing=repairing, top_n=top_n, participants=participants)
+
+
 __all__ = [
     "InteractiveContextParser",
     "LaTeXBuildResult",
@@ -30,7 +47,7 @@
     "__version__",
     "get_datasets",
     "get_grammars",
-    "set_grammar",
+    "icp",
     "parse",
     "to_manim",
 ]

src/dynamicsyntax/_parse.py

@@ -12,7 +12,7 @@
 from dylan.parser.interactive_context_parser import InteractiveContextParser
 from dylan.tree.tree import Tree
 
-from dynamicsyntax._session import resolved_grammar_path, session_parser
+from dynamicsyntax._session import resolved_grammar_path
 from dynamicsyntax.parse_trace import ParseActionStep
 from dynamicsyntax.parse_result import ParseResult
 
@@ -142,30 +142,16 @@ def _parse_at_path(grammar_path: Path, sentence: str, *, speaker: str, trace: bo
     return _parse_one(parser, sentence, speaker=speaker, trace=trace)
 
 
-@overload
-def parse(
-    sentence: str,
-    /,
-    *,
-    speaker: str = ...,
-    trace: bool = ...,
-) -> ParseResult: ...
-
-
-@overload
-def parse(
-    sentences: list[str],
-    /,
-    *,
-    speaker: str = ...,
-    trace: bool = ...,
-) -> list[ParseResult]: ...
+_GRAMMAR_REQUIRED_MSG = (
+    "grammar is required for dynamicsyntax.parse(...); use parser.parse(...) after "
+    "dynamicsyntax.icp().set_grammar(...), or pass grammar= to parse(...)"
+)
 
 
 @overload
 def parse(
     sentence: str,
-    grammar: str | Path | None,
+    grammar: str | Path,
     /,
     *,
     speaker: str = ...,
@@ -176,7 +162,7 @@ def parse(
 @overload
 def parse(
     sentences: list[str],
-    grammar: str | Path | None,
+    grammar: str | Path,
     /,
     *,
     speaker: str = ...,
@@ -197,8 +183,9 @@ def parse(
     :param sentence_or_sentences: A single whitespace-tokenised surface string, or a list of
         such strings (lowercased by the tokenizer). An empty list returns ``[]`` without using
         a grammar. Per-item blank or whitespace-only strings yield a failed result for that slot.
-    :param grammar: Bundled id or alias (e.g. ``\"ttr\"``), a grammar directory path, or
-        ``None`` to use the parser from :func:`~dynamicsyntax.set_grammar`.
+    :param grammar: Bundled id or alias (e.g. ``\"ttr\"``) or a grammar directory path. Required
+        for non-empty input; for grammar-bound parsing on a long-lived object use
+        :func:`dynamicsyntax.icp` and :meth:`~dylan.parser.interactive_context_parser.InteractiveContextParser.parse`.
     :param speaker: Dialogue participant id passed to the parser (default matches ``dylan``).
     :param trace: If ``True``, record one DS tree after ``new_sentence`` and after each word
         (for :meth:`~dynamicsyntax.parse_result.ParseResult.to_latex` ``incremental``).
@@ -207,8 +194,7 @@ def parse(
         Each result may include ``parser`` (the
         :class:`~dylan.parser.interactive_context_parser.InteractiveContextParser` used), except when
         the facade returns early for whitespace-only single-string input without a parse.
-    :raises ValueError: If *grammar* is omitted or ``None`` but no session grammar was set with
-        :func:`~dynamicsyntax.set_grammar` (non-empty sentence, or any list item non-blank after strip).
+    :raises ValueError: If *grammar* is omitted or ``None`` while any non-blank input would require parsing.
     :raises FileNotFoundError: If *grammar* is unknown or not a directory.
 
     Packaged grammars: ``dynamicsyntax/grammars/`` in the library, and the project
@@ -220,34 +206,24 @@ def parse(
         sentences = sentence_or_sentences
         if not sentences:
             return []
-        if grammar is not None:
-            with resolved_grammar_path(grammar) as grammar_path:
-                parser = InteractiveContextParser(grammar_path)
-                return [_parse_one(parser, s, speaker=speaker, trace=trace) for s in sentences]
-        parser = session_parser()
-        if parser is None:
+        if grammar is None:
             if any(s.strip() for s in sentences):
-                raise ValueError(
-                    "no grammar set; call dynamicsyntax.set_grammar(...) first or pass grammar= to parse(...)",
-                )
+                raise ValueError(_GRAMMAR_REQUIRED_MSG)
             return [
                 ParseResult(ok=False, semantics=None, tree=None, sentence="", parser=None)
                 for _ in sentences
             ]
-        return [_parse_one(parser, s, speaker=speaker, trace=trace) for s in sentences]
+        with resolved_grammar_path(grammar) as grammar_path:
+            parser = InteractiveContextParser(grammar_path)
+            return [_parse_one(parser, s, speaker=speaker, trace=trace) for s in sentences]
 
     sentence = sentence_or_sentences
     stripped = sentence.strip()
     if not stripped:
         return ParseResult(ok=False, semantics=None, tree=None, sentence="", parser=None)
 
-    if grammar is not None:
-        with resolved_grammar_path(grammar) as grammar_path:
-            return _parse_at_path(grammar_path, stripped, speaker=speaker, trace=trace)
+    if grammar is None:
+        raise ValueError(_GRAMMAR_REQUIRED_MSG)
 
-    parser = session_parser()
-    if parser is None:
-        raise ValueError(
-            "no grammar set; call dynamicsyntax.set_grammar(...) first or pass grammar= to parse(...)",
-        )
-    return _run_parse_core(parser, stripped, speaker=speaker, trace=trace)
+    with resolved_grammar_path(grammar) as grammar_path:
+        return _parse_at_path(grammar_path, stripped, speaker=speaker, trace=trace)