dbrownell-parserlib 0.8.4__tar.gz → 0.9.1__tar.gz

{dbrownell_parserlib-0.8.4 → dbrownell_parserlib-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dbrownell-parserlib
-Version: 0.8.4
+Version: 0.9.1
 Summary: Functionality useful when creating parsers.
 Author: Dave Brownell
 Author-email: Dave Brownell <github@DavidBrownell.com>
@@ -85,7 +85,7 @@ Use `BuildAntlrGrammar` to generate the lexer and parser:
 ```python
 from pathlib import Path
 
-from dbrownell_ParserLib import BuildAntlrGrammar
+from dbrownell_ParserLib.antlr.build_antlr_grammar import BuildAntlrGrammar
 
 
 BuildAntlrGrammar(
@@ -101,11 +101,9 @@ Implement a visitor that converts ANTLR parse trees to Expression objects:
 ```python
 from dataclasses import dataclass
 
-from dbrownell_ParserLib import (
-    Expression,
-    InsignificantWhitespaceAntlrVisitorMixin,
-    TerminalExpression,
-)
+from dbrownell_ParserLib.antlr.antlr_visitor_mixins import InsignificantWhitespaceAntlrVisitorMixin
+from dbrownell_ParserLib.expression import Expression
+from dbrownell_ParserLib.terminal_expression import TerminalExpression
 
 from CalculatorVisitor import CalculatorVisitor as GeneratedVisitor
 
@@ -147,7 +145,7 @@ class CalculatorVisitor(InsignificantWhitespaceAntlrVisitorMixin, GeneratedVisit
 Use `CreateAntlrParser` to build a callable parser:
 
 ```python
-from dbrownell_ParserLib import CreateAntlrParser
+from dbrownell_ParserLib.antlr.antlr_parser import CreateAntlrParser
 
 
 parser = CreateAntlrParser(
@@ -162,7 +160,7 @@ parser = CreateAntlrParser(
 Parse single files, multiple files, or entire workspaces:
 
 ```python
-from dbrownell_ParserLib import Error
+from dbrownell_ParserLib.errors import Error
 
 
 # Parse a single file
@@ -187,7 +185,7 @@ Use the visitor pattern to process your AST:
 ```python
 from contextlib import contextmanager
 
-from dbrownell_ParserLib import ExpressionVisitorHelper, VisitResult
+from dbrownell_ParserLib.visitors import ExpressionVisitorHelper, VisitResult
 
 
 class EvaluatorVisitor(ExpressionVisitorHelper):

{dbrownell_parserlib-0.8.4 → dbrownell_parserlib-0.9.1}/README.md

@@ -63,7 +63,7 @@ Use `BuildAntlrGrammar` to generate the lexer and parser:
 ```python
 from pathlib import Path
 
-from dbrownell_ParserLib import BuildAntlrGrammar
+from dbrownell_ParserLib.antlr.build_antlr_grammar import BuildAntlrGrammar
 
 
 BuildAntlrGrammar(
@@ -79,11 +79,9 @@ Implement a visitor that converts ANTLR parse trees to Expression objects:
 ```python
 from dataclasses import dataclass
 
-from dbrownell_ParserLib import (
-    Expression,
-    InsignificantWhitespaceAntlrVisitorMixin,
-    TerminalExpression,
-)
+from dbrownell_ParserLib.antlr.antlr_visitor_mixins import InsignificantWhitespaceAntlrVisitorMixin
+from dbrownell_ParserLib.expression import Expression
+from dbrownell_ParserLib.terminal_expression import TerminalExpression
 
 from CalculatorVisitor import CalculatorVisitor as GeneratedVisitor
 
@@ -125,7 +123,7 @@ class CalculatorVisitor(InsignificantWhitespaceAntlrVisitorMixin, GeneratedVisit
 Use `CreateAntlrParser` to build a callable parser:
 
 ```python
-from dbrownell_ParserLib import CreateAntlrParser
+from dbrownell_ParserLib.antlr.antlr_parser import CreateAntlrParser
 
 
 parser = CreateAntlrParser(
@@ -140,7 +138,7 @@ parser = CreateAntlrParser(
 Parse single files, multiple files, or entire workspaces:
 
 ```python
-from dbrownell_ParserLib import Error
+from dbrownell_ParserLib.errors import Error
 
 
 # Parse a single file
@@ -165,7 +163,7 @@ Use the visitor pattern to process your AST:
 ```python
 from contextlib import contextmanager
 
-from dbrownell_ParserLib import ExpressionVisitorHelper, VisitResult
+from dbrownell_ParserLib.visitors import ExpressionVisitorHelper, VisitResult
 
 
 class EvaluatorVisitor(ExpressionVisitorHelper):

{dbrownell_parserlib-0.8.4 → dbrownell_parserlib-0.9.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dbrownell-parserlib"
-version = "0.8.4"
+version = "0.9.1"
 #          ^^^^^
 # Wheel names will be generated according to this value. Do not manually modify this value; instead
 # update it according to committed changes by running this command from the root of the repository:

dbrownell_parserlib-0.9.1/src/dbrownell_ParserLib/__init__.py

@@ -0,0 +1,6 @@
+# noqa: D104
+
+from importlib.metadata import version
+
+
+__version__ = version("dbrownell_ParserLib")

dbrownell_parserlib-0.9.1/src/dbrownell_ParserLib/antlr/__init__.py

@@ -0,0 +1 @@
+# noqa: D104

{dbrownell_parserlib-0.8.4 → dbrownell_parserlib-0.9.1}/src/dbrownell_ParserLib/antlr/antlr_parser.py

@@ -17,7 +17,7 @@ from dbrownell_Common import ExecuteTasks
 from dbrownell_Common.Streams.DoneManager import DoneManager  # noqa: TC002
 from plum import dispatch, overload
 
-from dbrownell_ParserLib.errors import Error, PythonError
+from dbrownell_ParserLib.errors import Error, ErrorException, PythonError
 from dbrownell_ParserLib.region import Location, Region
 
 
@@ -25,17 +25,6 @@ from dbrownell_ParserLib.region import Location, Region
 # |
 # |  Public Types
 # |
-# ----------------------------------------------------------------------
-class AntlrParserException(Exception):  # noqa: N818
-    """Exception raised by the ANTLR parser or a visitor processing the AST."""
-
-    # ----------------------------------------------------------------------
-    def __init__(self, error: Error) -> None:
-        super().__init__(str(error))
-
-        self.error = error
-
-
 # ----------------------------------------------------------------------
 class AntlrParser(ABC):
     """Abstract base class for parsers created with `CreateAntlrParser`."""
@@ -451,7 +440,7 @@ class _AntlrParser(AntlrParser):
 
                     result = visitor
 
-                except AntlrParserException as ex:
+                except ErrorException as ex:
                     result = ex.error
                 except Exception as ex:
                     result = PythonError.Create(ex)
@@ -486,7 +475,7 @@ class _ErrorListener(antlr4.DiagnosticErrorListener):
 
         location = Location(line, column + 1)
         error = Error(f"Syntax error: {msg}", Region(self._source, location, location))
-        ex = AntlrParserException(error)
+        ex = ErrorException(error)
 
         if e is None:
             raise ex

dbrownell_parserlib-0.9.1/src/dbrownell_ParserLib/errors.py

@@ -0,0 +1,232 @@
+"""Contains functionality associated with errors and exceptions."""
+
+import re
+import textwrap
+import traceback
+
+from abc import abstractmethod
+from dataclasses import dataclass, field, InitVar, make_dataclass
+from enum import Enum
+from functools import cached_property, singledispatch
+from io import StringIO
+from pathlib import Path
+from typing import Self
+
+from dbrownell_ParserLib.region import Location, Region
+
+
+# ----------------------------------------------------------------------
+# |
+# |  Public Types
+# |
+# ----------------------------------------------------------------------
+@dataclass(frozen=True)
+class Error:
+    """Base class for all errors generated by this library."""
+
+    # ----------------------------------------------------------------------
+    message: str
+
+    region_or_regions: InitVar[Region | list[Region]]
+    regions: list[Region] = field(init=False)
+
+    # ----------------------------------------------------------------------
+    @classmethod
+    def CreateAsException(cls, *args, **kwargs) -> ErrorException:
+        """Create an `ErrorException` with an `Error` based on the provided arguments."""
+
+        return ErrorException(cls(*args, **kwargs))
+
+    # ----------------------------------------------------------------------
+    def __post_init__(self, region_or_regions: Region | list[Region]) -> None:
+        regions = [region_or_regions] if isinstance(region_or_regions, Region) else region_or_regions
+
+        if not regions:
+            msg = "At least one region must be provided"
+            raise ValueError(msg)
+
+        object.__setattr__(self, "regions", regions)
+
+    # ----------------------------------------------------------------------
+    def __str__(self) -> str:
+        return self._string
+
+    # ----------------------------------------------------------------------
+    # ----------------------------------------------------------------------
+    # ----------------------------------------------------------------------
+    @cached_property
+    def _string(self) -> str:
+        if len(self.regions) == 1 and "\n" not in self.message:
+            return f"{self.message} ({self.regions[0]})"
+
+        return textwrap.dedent(
+            """\
+            {}
+
+            {}
+            """,
+        ).format(self.message.rstrip(), "\n".join(f"    - {region}" for region in self.regions))
+
+
+# ----------------------------------------------------------------------
+@dataclass(frozen=True)
+class PythonError(Error):
+    """An `Error` based on a Python exception."""
+
+    # ----------------------------------------------------------------------
+    ex: Exception
+
+    # ----------------------------------------------------------------------
+    @classmethod
+    def Create(
+        cls,
+        ex: Exception,
+    ) -> Self:
+        """Create a `PythonError` from a Python exception."""
+
+        regions: list[Region] = []
+
+        # I haven't been able to find a reliable way to get the exception's callstack so it is being
+        # parsed manually here. There has got to be a better way to do this.
+        sink = StringIO()
+
+        traceback.print_exception(ex, file=sink)
+        sink_str = sink.getvalue()
+
+        regex = re.compile(r"^\s*File \"(?P<filename>.+?)\", line (?P<line>\d+),.+$", re.MULTILINE)
+
+        for line in sink_str.splitlines():
+            match = regex.match(line)
+            if not match:
+                continue
+
+            line_number = int(match.group("line"))
+
+            regions.append(
+                Region(
+                    Path(match.group("filename")),
+                    Location(line_number, 1),
+                    Location(line_number, 1),
+                ),
+            )
+
+        regions.reverse()
+
+        return cls(
+            textwrap.dedent(
+                """\
+                Python Exception
+                ----------------
+                {}
+                """,
+            ).format(str(ex)),
+            regions,
+            ex,
+        )
+
+
+# ----------------------------------------------------------------------
+class ErrorException(Exception):  # noqa: N818
+    """Python exception that contains an `Error` object."""
+
+    # ----------------------------------------------------------------------
+    def __init__(self, error: Error) -> None:
+        super().__init__(str(error))
+        self.error = error
+
+
+# ----------------------------------------------------------------------
+# |
+# |  Public Functions
+# |
+# ----------------------------------------------------------------------
+class _CreatedError(Error):
+    """Abstract base class for errors created via `CreateErrorType`."""
+
+    # ----------------------------------------------------------------------
+    @classmethod
+    @abstractmethod
+    def Create(cls, region_or_regions: Region | list[Region], *args, **kwargs) -> Self: ...
+
+
+# ----------------------------------------------------------------------
+def CreateErrorType(
+    message_template: str,
+    **error_attributes: type,
+) -> type[_CreatedError]:
+    """Create a new `Error` type with the provided message template and attributes.
+
+    Example:
+        MyError = CreateErrorType(
+            "This is an error with attribute {attr1} and {attr2}",
+            attr1=str,
+            attr2=int,
+        )
+
+    """
+
+    dynamic_fields_class = make_dataclass(
+        "DynamicFields",
+        error_attributes.items(),
+        bases=(_CreatedError,),
+        frozen=True,
+    )
+
+    # ----------------------------------------------------------------------
+    @dataclass(frozen=True)
+    class NewError(dynamic_fields_class):  # ty: ignore[unsupported-base]
+        # ----------------------------------------------------------------------
+        @classmethod
+        def Create(
+            cls,
+            region_or_regions: Region | list[Region],
+            *args,
+            **kwargs,
+        ) -> Self:
+            """Create a new instance of this error type."""
+
+            kvps = {k: _ArgToString(v) for k, v in zip(error_attributes.keys(), args, strict=False)}
+
+            for k, v in kwargs.items():
+                kvps[k] = _ArgToString(v)
+
+            return cls(
+                message_template.format(**kvps),  # ty: ignore[too-many-positional-arguments]
+                region_or_regions,
+                *args,
+                **kwargs,
+            )
+
+        # ----------------------------------------------------------------------
+        @classmethod
+        def CreateAsException(cls, *args, **kwargs) -> ErrorException:
+            return ErrorException(cls.Create(*args, **kwargs))
+
+    # ----------------------------------------------------------------------
+
+    return NewError
+
+
+# ----------------------------------------------------------------------
+# |
+# |  Private Functions
+# |
+# ----------------------------------------------------------------------
+@singledispatch
+def _ArgToString(value: object) -> str:
+    return str(value)
+
+
+@_ArgToString.register
+def _(value: str) -> str:
+    return value
+
+
+@_ArgToString.register
+def _(value: Enum) -> str:
+    return value.name
+
+
+@_ArgToString.register
+def _(value: list) -> str:
+    return "[{}]".format(", ".join("'{}'".format(_ArgToString(v)) for v in value))

dbrownell_parserlib-0.8.4/src/dbrownell_ParserLib/__init__.py

@@ -1,44 +0,0 @@
-# noqa: D104
-
-from importlib.metadata import version
-
-from dbrownell_ParserLib.antlr import (
-    AntlrParser,
-    AntlrParserException,
-    AntlrVisitorMixinBase,
-    BuildAntlrGrammar,
-    CreateAntlrParser,
-    InsignificantWhitespaceAntlrVisitorMixin,
-    SignificantWhitespaceAntlrVisitorMixin,
-)
-from dbrownell_ParserLib.errors import Error, PythonError
-from dbrownell_ParserLib.expression import Expression
-from dbrownell_ParserLib.location import Location
-from dbrownell_ParserLib.region import Region
-from dbrownell_ParserLib.terminal_expression import TerminalExpression
-from dbrownell_ParserLib.visitors import ExpressionVisitor, ExpressionVisitorHelper, VisitResult
-
-
-# ----------------------------------------------------------------------
-__all__ = [
-    "AntlrParser",
-    "AntlrParserException",
-    "AntlrVisitorMixinBase",
-    "BuildAntlrGrammar",
-    "CreateAntlrParser",
-    "Error",
-    "Expression",
-    "ExpressionVisitor",
-    "ExpressionVisitorHelper",
-    "InsignificantWhitespaceAntlrVisitorMixin",
-    "Location",
-    "PythonError",
-    "Region",
-    "SignificantWhitespaceAntlrVisitorMixin",
-    "TerminalExpression",
-    "VisitResult",
-    "__version__",
-]
-
-
-__version__ = version("dbrownell_ParserLib")

dbrownell_parserlib-0.8.4/src/dbrownell_ParserLib/antlr/__init__.py

@@ -1,20 +0,0 @@
-# noqa: D104
-from dbrownell_ParserLib.antlr.build_antlr_grammar import BuildAntlrGrammar
-from dbrownell_ParserLib.antlr.antlr_parser import AntlrParser, AntlrParserException, CreateAntlrParser
-from dbrownell_ParserLib.antlr.antlr_visitor_mixins import (
-    AntlrVisitorMixinBase,
-    InsignificantWhitespaceAntlrVisitorMixin,
-    SignificantWhitespaceAntlrVisitorMixin,
-)
-
-
-# ----------------------------------------------------------------------
-__all__ = [
-    "AntlrParser",
-    "AntlrParserException",
-    "AntlrVisitorMixinBase",
-    "BuildAntlrGrammar",
-    "CreateAntlrParser",
-    "InsignificantWhitespaceAntlrVisitorMixin",
-    "SignificantWhitespaceAntlrVisitorMixin",
-]

dbrownell_parserlib-0.8.4/src/dbrownell_ParserLib/errors.py

@@ -1,112 +0,0 @@
-"""Contains functionality associated with errors and exceptions."""
-
-import re
-import textwrap
-import traceback
-
-from dataclasses import dataclass, field, InitVar
-from functools import cached_property
-from io import StringIO
-from pathlib import Path
-from typing import Self
-
-from dbrownell_ParserLib.region import Location, Region
-
-
-# ----------------------------------------------------------------------
-@dataclass(frozen=True)
-class Error:
-    """Base class for all errors generated by this library."""
-
-    # ----------------------------------------------------------------------
-    message: str
-
-    region_or_regions: InitVar[Region | list[Region]]
-    regions: list[Region] = field(init=False)
-
-    # ----------------------------------------------------------------------
-    def __post_init__(self, region_or_regions: Region | list[Region]) -> None:
-        regions = [region_or_regions] if isinstance(region_or_regions, Region) else region_or_regions
-
-        if not regions:
-            msg = "At least one region must be provided"
-            raise ValueError(msg)
-
-        object.__setattr__(self, "regions", regions)
-
-    # ----------------------------------------------------------------------
-    def __str__(self) -> str:
-        return self._string
-
-    # ----------------------------------------------------------------------
-    # ----------------------------------------------------------------------
-    # ----------------------------------------------------------------------
-    @cached_property
-    def _string(self) -> str:
-        if len(self.regions) == 1 and "\n" not in self.message:
-            return f"{self.message} ({self.regions[0]})"
-
-        return textwrap.dedent(
-            """\
-            {}
-
-            {}
-            """,
-        ).format(self.message.rstrip(), "\n".join(f"    - {region}" for region in self.regions))
-
-
-# ----------------------------------------------------------------------
-@dataclass(frozen=True)
-class PythonError(Error):
-    """An `Error` based on a Python exception."""
-
-    # ----------------------------------------------------------------------
-    ex: Exception
-
-    # ----------------------------------------------------------------------
-    @classmethod
-    def Create(
-        cls,
-        ex: Exception,
-    ) -> Self:
-        """Create a `PythonError` from a Python exception."""
-
-        regions: list[Region] = []
-
-        # I haven't been able to find a reliable way to get the exception's callstack so it is being
-        # parsed manually here. There has got to be a better way to do this.
-        sink = StringIO()
-
-        traceback.print_exception(ex, file=sink)
-        sink_str = sink.getvalue()
-
-        regex = re.compile(r"^\s*File \"(?P<filename>.+?)\", line (?P<line>\d+),.+$", re.MULTILINE)
-
-        for line in sink_str.splitlines():
-            match = regex.match(line)
-            if not match:
-                continue
-
-            line_number = int(match.group("line"))
-
-            regions.append(
-                Region(
-                    Path(match.group("filename")),
-                    Location(line_number, 1),
-                    Location(line_number, 1),
-                ),
-            )
-
-        regions.reverse()
-
-        return cls(
-            textwrap.dedent(
-                """\
-                Python Exception
-                ----------------
-                {}
-                """,
-            ).format(str(ex)),
-            regions,
-            ex,
-        )