syncraft 0.2.2__tar.gz → 0.2.4__tar.gz

syncraft-0.2.4/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: syncraft
+Version: 0.2.4
+Summary: Parser combinator library
+Author-email: Michael Afmokt <michael@esacca.com>
+License-Expression: MIT
+Keywords: parser,combinator,sql,sqlite,generator,printer
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=14.1.0
+Requires-Dist: rstr>=3.2.2
+Requires-Dist: sqlglot>=27.7.0
+Dynamic: license-file
+
+# Syncraft
+
+Syncraft is a parser/generator combinator library for Python. It helps you
+
+- Build grammars
+- Parse SQL statement to AST
+- Search AST by grammar
+- Convert AST to dataclass
+- Check constraints over the AST/dataclass
+- Change dataclass and convert back to AST
+
+
+## Installation
+
+### pip
+```bash
+pip install syncraft
+```
+
+### uv
+```bash
+uv add syncraft
+```
+
+Python 3.10+ is required.
+
+## Quickstart
+
+!. Define grammar 
+
+```python
+from dataclasses import dataclass
+from syncraft import literal, parse, generate
+
+A = literal("a")
+B = literal("b")
+syntax = A + B  # sequence
+
+ast, _ = parse(syntax, "a b", dialect="sqlite")
+gen, _ = generate(syntax, ast)
+assert ast == gen
+```
+
+Collect parsed pieces into dataclasses using marks and `.to()`:
+
+```python
+from dataclasses import dataclass
+from syncraft import literal
+
+@dataclass
+class Pair:
+		first: any
+		second: any
+
+A = literal("a").mark("first")
+B = literal("b").mark("second")
+syntax = (A + B).to(Pair)
+
+ast, _ = parse(syntax, "a b", dialect="sqlite")
+value, invert = ast.bimap()
+# value is Pair(first=VAR(a), second=VAR(b))
+round_tripped, _ = generate(syntax, invert(value))
+assert round_tripped == ast
+```
+
+Use the built‑in SQLite grammar snippets to parse statements:
+
+```python
+from syncraft import parse
+from syncraft.sqlite3 import select_stmt
+
+ast, _ = parse(select_stmt, "select a from t where a > 1", dialect="sqlite")
+```
+
+## Core ideas
+
+- Syntax describes structure and transforms values; Algebra executes it.
+- AST types: Then, Choice, Many, Marked, Collect, Nothing, Token.
+- Operators: `+` (both), `>>` (keep right), `//` (keep left), `|` (choice), `~` (optional), `many()`, `sep_by()`, `between()`.
+- Error model supports backtracking and commit (`cut()`).
+
+## Documentation
+
+- Tutorials and API reference are built with MkDocs. Local preview:
+	1) install dev deps (see `pyproject.toml` dev group)
+	2) activate your venv and run `mkdocs serve`
+
+- Version injection: pages can use `{{ version }}`. It is provided by mkdocs-macros via `docs/main.py`, which resolves the version in this order:
+	- `[project].version` from `pyproject.toml`
+	- installed package metadata (`importlib.metadata.version('syncraft')`)
+	- fallback `"0.0.0"`
+
+  The macros plugin is configured in `mkdocs.yml` with `module_name: docs/main`.
+
+## Contributing / Roadmap
+
+- Improve performance and add benchmarks
+- Expand tutorials and SQLite coverage examples

syncraft-0.2.4/README.md

@@ -0,0 +1,98 @@
+# Syncraft
+
+Syncraft is a parser/generator combinator library for Python. It helps you
+
+- Build grammars
+- Parse SQL statement to AST
+- Search AST by grammar
+- Convert AST to dataclass
+- Check constraints over the AST/dataclass
+- Change dataclass and convert back to AST
+
+
+## Installation
+
+### pip
+```bash
+pip install syncraft
+```
+
+### uv
+```bash
+uv add syncraft
+```
+
+Python 3.10+ is required.
+
+## Quickstart
+
+!. Define grammar 
+
+```python
+from dataclasses import dataclass
+from syncraft import literal, parse, generate
+
+A = literal("a")
+B = literal("b")
+syntax = A + B  # sequence
+
+ast, _ = parse(syntax, "a b", dialect="sqlite")
+gen, _ = generate(syntax, ast)
+assert ast == gen
+```
+
+Collect parsed pieces into dataclasses using marks and `.to()`:
+
+```python
+from dataclasses import dataclass
+from syncraft import literal
+
+@dataclass
+class Pair:
+		first: any
+		second: any
+
+A = literal("a").mark("first")
+B = literal("b").mark("second")
+syntax = (A + B).to(Pair)
+
+ast, _ = parse(syntax, "a b", dialect="sqlite")
+value, invert = ast.bimap()
+# value is Pair(first=VAR(a), second=VAR(b))
+round_tripped, _ = generate(syntax, invert(value))
+assert round_tripped == ast
+```
+
+Use the built‑in SQLite grammar snippets to parse statements:
+
+```python
+from syncraft import parse
+from syncraft.sqlite3 import select_stmt
+
+ast, _ = parse(select_stmt, "select a from t where a > 1", dialect="sqlite")
+```
+
+## Core ideas
+
+- Syntax describes structure and transforms values; Algebra executes it.
+- AST types: Then, Choice, Many, Marked, Collect, Nothing, Token.
+- Operators: `+` (both), `>>` (keep right), `//` (keep left), `|` (choice), `~` (optional), `many()`, `sep_by()`, `between()`.
+- Error model supports backtracking and commit (`cut()`).
+
+## Documentation
+
+- Tutorials and API reference are built with MkDocs. Local preview:
+	1) install dev deps (see `pyproject.toml` dev group)
+	2) activate your venv and run `mkdocs serve`
+
+- Version injection: pages can use `{{ version }}`. It is provided by mkdocs-macros via `docs/main.py`, which resolves the version in this order:
+	- `[project].version` from `pyproject.toml`
+	- installed package metadata (`importlib.metadata.version('syncraft')`)
+	- fallback `"0.0.0"`
+
+  The macros plugin is configured in `mkdocs.yml` with `module_name: docs/main`.
+
+## Contributing / Roadmap
+
+- Improve performance and add benchmarks
+- Expand tutorials and SQLite coverage examples

{syncraft-0.2.2 → syncraft-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "syncraft"
-version = "0.2.2"
+version = "0.2.4"
 description = "Parser combinator library"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -18,6 +18,11 @@ dependencies = [
 [dependency-groups]
 dev = [
     "pytest>=8.4.1",
+    "mkdocs>=1.6.0",
+    "mkdocs-material>=9.5.0",
+    "mkdocstrings>=0.25.0",
+    "mkdocstrings-python>=1.10.0",
+    "mkdocs-macros-plugin>=1.0.5",
 ]
 
 

syncraft-0.2.4/syncraft/__init__.py

@@ -0,0 +1,59 @@
+from .syntax import (
+	Syntax,
+	choice,
+	lazy,
+	success,
+	fail,
+    run,
+)
+from .parser import (
+	parse,
+	sqlglot,
+	token,
+	identifier,
+	variable,
+	literal,
+	number,
+	string,
+	regex,
+	until,
+)
+from .generator import (
+	generate,
+)
+from .finder import (
+	find,
+	matches,
+	anything,
+)
+from .constraint import (
+	Constraint,
+	Quantifier,
+	forall,
+	exists,
+)
+from .ast import (
+	AST,
+	Token,
+	Then,
+	ThenKind,
+	Choice,
+	ChoiceKind,
+	Many,
+	Marked,
+	Collect,
+)
+
+__all__ = [
+	# syntax & core
+	"Syntax", "choice", "lazy", "success", "fail", "run",
+	# parsing/generation helpers
+	"parse", "sqlglot", "token", "identifier", "variable", "literal", "number", "string", "regex", "until",
+	"generate",
+	# finder
+	"find", "matches", "anything",
+	# constraints
+	"Constraint", "Quantifier", "forall", "exists",
+	# ast
+	"AST", "Token", "Then", "ThenKind", "Choice", "ChoiceKind", "Many", "Marked", "Collect",
+]

{syncraft-0.2.2 → syncraft-0.2.4}/syncraft/algebra.py

@@ -93,8 +93,38 @@ class Algebra(Generic[A, S]):
     def __call__(self, input: S, use_cache: bool) -> Either[Any, Tuple[A, S]]:
         return self.run(input, use_cache=use_cache)
 
-    
     def run(self, input: S, use_cache: bool) -> Either[Any, Tuple[A, S]]:
+        """Execute this algebra on the given state with optional memoization.
+
+        This is the core evaluation entry point used by all combinators. It
+        supports per-"parser" memoization and protects against infinite
+        recursion by detecting left-recursive re-entrance.
+
+        Args:
+            input: The initial state to run against. Must be hashable as it's
+                used as a cache key.
+            use_cache: When True, memoize results for ``(self.run_f, input)``
+                so repeated calls short-circuit. When False, the cache entry is
+                cleared after the run to effectively disable the cache. 
+
+        Returns:
+            Either[Error, Tuple[A, S]]: On success, ``Right((value, next_state))``.
+            On failure, ``Left(Error)``. Errors produced downstream are
+            automatically enriched with ``this=self`` and ``state=input`` to
+            preserve context. If an exception escapes the user code, it's
+            captured and returned as ``Left(Error)`` with a traceback in
+            ``stack``.
+
+        Notes:
+            - Left recursion: if a re-entrant call is observed on the same
+              ``input`` while an evaluation is in progress, a ``Left(Error)``
+              is returned indicating left-recursion was detected.
+            - Memoization scope: results are cached per ``run_f`` (the concrete
+              compiled function of this algebra) and keyed by the input state.
+            - Commitment: downstream combinators (e.g. ``cut``) may set the
+              ``committed`` flag in ``Error``; ``run`` preserves that flag but
+              does not set it itself.
+        """
         cache = self._cache[self.run_f]
         assert cache is not None, "Cache should be initialized in __post_init__"
         if input in cache:
@@ -136,12 +166,31 @@ class Algebra(Generic[A, S]):
         
     @classmethod
     def lazy(cls, thunk: Callable[[], Algebra[A, S]]) -> Algebra[A, S]:
+        """Lazily construct an algebra at run time.
+
+        Useful for recursive definitions. The thunk is evaluated when this
+        algebra runs, and the resulting algebra is executed.
+
+        Args:
+            thunk: Zero-argument function returning the underlying algebra.
+
+        Returns:
+            An algebra that defers to the thunk-provided algebra.
+        """
         def lazy_run(input: S, use_cache:bool) -> Either[Any, Tuple[A, S]]:
             return thunk().run(input, use_cache)
         return cls(lazy_run, name=cls.__name__ + '.lazy')
     
     @classmethod
     def fail(cls, error: Any) -> Algebra[Any, S]:
+        """Return an algebra that always fails with ``error``.
+
+        Args:
+            error: The error payload to wrap in ``Left``.
+
+        Returns:
+            An algebra producing ``Left(Error(...))`` without consuming input.
+        """
         def fail_run(input: S, use_cache:bool) -> Either[Any, Tuple[Any, S]]:
             return Left(Error(
                 error=error,
@@ -152,12 +201,35 @@ class Algebra(Generic[A, S]):
     
     @classmethod
     def success(cls, value: Any) -> Algebra[Any, S]:
+        """Return an algebra that always succeeds with ``value``.
+
+        The input state is passed through unchanged.
+
+        Args:
+            value: The constant value to return.
+
+        Returns:
+            ``Right((value, input))`` for any input state.
+        """
         def success_run(input: S, use_cache:bool) -> Either[Any, Tuple[Any, S]]:
             return Right((value, input))
         return cls(success_run, name=cls.__name__ + '.success')
     
     @classmethod
     def factory(cls, name: str, *args: Any, **kwargs: Any) -> Algebra[A, S]:
+        """Call a named class method to construct an algebra.
+
+        Args:
+            name: Name of a classmethod/staticmethod on this class.
+            *args: Positional args passed to the method.
+            **kwargs: Keyword args passed to the method.
+
+        Returns:
+            The algebra returned by the method.
+
+        Raises:
+            ValueError: If the method is missing or not callable.
+        """
         method = getattr(cls, name, None)
         if method is None or not callable(method):
             raise ValueError(f"Method {name} is not defined in {cls.__name__}")
@@ -166,6 +238,14 @@ class Algebra(Generic[A, S]):
 
 
     def cut(self) -> Algebra[A, S]:
+        """Commit this branch by marking failures as committed.
+
+        Converts downstream errors into committed errors (``committed=True``),
+        which prevents alternatives from being tried in ``or_else``.
+
+        Returns:
+            An algebra that commits errors produced by this one.
+        """
         def commit_error(e: Any) -> Error:
             match e:
                 case Error():
@@ -188,6 +268,15 @@ class Algebra(Generic[A, S]):
                     ], 
                     Either[Any, Tuple[B, S]]], 
                     ctx: Optional[Any] = None) -> Algebra[A | B, S]:
+        """Run a handler only when this algebra fails.
+
+        Args:
+            func: Callback ``(alg, input, left, ctx) -> Either`` executed on failure.
+            ctx: Optional context object passed to the callback.
+
+        Returns:
+            An algebra that intercepts failures and can recover or transform them.
+        """
         assert callable(func), "func must be callable"
         def fail_run(input: S, use_cache:bool) -> Either[Any, Tuple[A | B, S]]:
             result = self.run(input, use_cache)
@@ -206,6 +295,15 @@ class Algebra(Generic[A, S]):
                         ], 
                         Either[Any, Tuple[B, S]]], 
                         ctx: Optional[Any] = None) -> Algebra[A | B, S]:
+        """Run a handler only when this algebra succeeds.
+
+        Args:
+            func: Callback ``(alg, input, right, ctx) -> Either`` executed on success.
+            ctx: Optional context object passed to the callback.
+
+        Returns:
+            An algebra that can transform or post-process successes.
+        """
         assert callable(func), "func must be callable"
         def success_run(input: S, use_cache:bool) -> Either[Any, Tuple[A | B, S]]:
             result = self.run(input, use_cache)
@@ -244,24 +342,29 @@ class Algebra(Generic[A, S]):
         return lazy_self
 
 ######################################################## map on state ###########################################
-    def post_state(self, f: Callable[[S], S]) -> Algebra[A, S]:
-        def post_state_run(input: S, use_cache:bool) -> Either[Any, Tuple[A, S]]:
-            match self.run(input, use_cache):
-                case Right((value, state)):
-                    return Right((value, f(state)))
-                case Left(err):
-                    return Left(err)
-                case x:
-                    raise ValueError(f"Unexpected result from self.run {x}")
-        return self.__class__(post_state_run, name=self.name) 
+    def map_state(self, f: Callable[[S], S]) -> Algebra[A, S]:
+        """Map the input state before running this algebra.
+
+        Args:
+            f: ``S -> S`` function applied to the state prior to running.
 
-    def pre_state(self, f: Callable[[S], S]) -> Algebra[A, S]:
-        def pre_state_run(state: S, use_cache:bool) -> Either[Any, Tuple[A, S]]:
+        Returns:
+            An algebra that runs with ``f(state)``.
+        """
+        def map_state_run(state: S, use_cache:bool) -> Either[Any, Tuple[A, S]]:
             return self.run(f(state), use_cache)
-        return self.__class__(pre_state_run, name=self.name) 
+        return self.__class__(map_state_run, name=self.name) 
 
 
     def map_all(self, f: Callable[[A, S], Tuple[B, S]]) -> Algebra[B, S]:
+        """Map both the produced value and the resulting state on success.
+
+        Args:
+            f: Function mapping ``(value, state)`` to ``(new_value, new_state)``.
+
+        Returns:
+            An algebra producing the transformed value and state.
+        """
         def map_all_run(input: S, use_cache:bool) -> Either[Any, Tuple[B, S]]:
             match self.run(input, use_cache):
                 case Right((value, state)):
@@ -273,23 +376,54 @@ class Algebra(Generic[A, S]):
                     raise ValueError(f"Unexpected result from self.run {x}")
         return self.__class__(map_all_run, name=self.name) # type: ignore
 ######################################################## fundamental combinators ############################################    
-    def fmap(self, f: Callable[[A], B]) -> Algebra[B, S]:
-        def fmap_run(input: S, use_cache:bool) -> Either[Any, Tuple[B, S]]:
+    def map(self, f: Callable[[A], B]) -> Algebra[B, S]:
+        """Transform the success value, leaving the state unchanged.
+
+        Args:
+            f: Mapper from ``A`` to ``B``.
+
+        Returns:
+            An algebra that yields ``B`` with the same resulting state.
+        """
+        def map_run(input: S, use_cache:bool) -> Either[Any, Tuple[B, S]]:
             parsed = self.run(input, use_cache)
             if isinstance(parsed, Right):
                 return Right((f(parsed.value[0]), parsed.value[1]))            
             else:
                 return cast(Either[Any, Tuple[B, S]], parsed)
-        return self.__class__(fmap_run, name=self.name)  # type: ignore
+        return self.__class__(map_run, name=self.name)  # type: ignore
 
-    
-    def map(self, f: Callable[[A], B]) -> Algebra[B, S]:
-        return self.fmap(f)
-    
+        
     def bimap(self, f: Callable[[A], B], i: Callable[[B], A]) -> Algebra[B, S]:
-        return self.fmap(f).pre_state(lambda s: s.map(i))
+        """Bidirectionally map values with an inverse, updating the state.
+
+        Applies ``f`` to the success value. The state is pre-mapped with the
+        inverse ``i`` via the state's ``map`` method to preserve round-trips.
+
+        Args:
+            f: Forward mapping ``A -> B``.
+            i: Inverse mapping ``B -> A`` applied to the state.
+
+        Returns:
+            An algebra producing ``B`` while keeping value/state alignment.
+        
+        Note:
+            Different subclass of Algebra can override state.map method to change 
+            the behavior of bimap. For example, ParserState.map will return the
+            state unchanged, and GenState.map will apply the inverse map and update 
+            the next AST node for generation.
+        """
+        return self.map(f).map_state(lambda s: s.map(i))
 
     def map_error(self, f: Callable[[Optional[Any]], Any]) -> Algebra[A, S]:
+        """Transform the error payload when this algebra fails.
+
+        Args:
+            f: Function applied to the error payload inside ``Left``.
+
+        Returns:
+            An algebra that preserves successes and maps failures.
+        """
         def map_error_run(input: S, use_cache:bool) -> Either[Any, Tuple[A, S]]:
             parsed = self.run(input, use_cache)
             if isinstance(parsed, Left):
@@ -298,6 +432,17 @@ class Algebra(Generic[A, S]):
         return self.__class__(map_error_run, name=self.name)  
 
     def flat_map(self, f: Callable[[A], Algebra[B, S]]) -> Algebra[B, S]:
+        """Chain computations where the next algebra depends on the value.
+
+        On success, passes the produced value to ``f`` to obtain the next
+        algebra, then runs it with the resulting state.
+
+        Args:
+            f: Mapper from a value to the next algebra.
+
+        Returns:
+            An algebra yielding the result of the chained computation.
+        """
         def flat_map_run(input: S, use_cache:bool) -> Either[Any, Tuple[B, S]]:
             parsed = self.run(input, use_cache)
             if isinstance(parsed, Right):
@@ -308,6 +453,18 @@ class Algebra(Generic[A, S]):
 
     
     def or_else(self: Algebra[A, S], other: Algebra[B, S]) -> Algebra[Choice[A, B], S]:
+        """Try this algebra; if it fails uncommitted, try ``other``.
+
+        If the failure is committed (``committed=True``), the alternative is
+        not attempted and the error is propagated.
+
+        Args:
+            other: Fallback algebra to try from the same input state.
+
+        Returns:
+            An algebra producing ``Choice.LEFT`` for this success or
+            ``Choice.RIGHT`` for the other's success.
+        """
         def or_else_run(input: S, use_cache:bool) -> Either[Any, Tuple[Choice[A, B], S]]:
             match self.run(input, use_cache):
                 case Right((value, state)):
@@ -325,27 +482,75 @@ class Algebra(Generic[A, S]):
         return self.__class__(or_else_run, name=f'{self.name} | {other.name}')  # type: ignore
 
     def then_both(self, other: Algebra[B, S]) -> Algebra[Then[A, B], S]:
+        """Sequence two algebras and keep both values.
+
+        Returns a ``Then(kind=BOTH)`` holding the left and right values.
+
+        Args:
+            other: The algebra to run after this one.
+
+        Returns:
+            An algebra producing ``Then(left, right, kind=BOTH)``.
+        """
         def then_both_f(a: A) -> Algebra[Then[A, B], S]:
             def combine(b: B) -> Then[A, B]:
                 return Then(left=a, right=b, kind=ThenKind.BOTH)
-            return other.fmap(combine)
+            return other.map(combine)
         return self.flat_map(then_both_f).named(f'{self.name} + {other.name}')
 
     def then_left(self, other: Algebra[B, S]) -> Algebra[Then[A, B], S]:
+        """Sequence two algebras, keep the left value in the result.
+
+        Produces ``Then(kind=LEFT)`` with both values attached.
+
+        Args:
+            other: The algebra to run after this one.
+
+        Returns:
+            An algebra producing ``Then(left, right, kind=LEFT)``.
+        """
         def then_left_f(a: A) -> Algebra[Then[A, B], S]:
             def combine(b: B) -> Then[A, B]:
                 return Then(left=a, right=b, kind=ThenKind.LEFT)
-            return other.fmap(combine)
+            return other.map(combine)
         return self.flat_map(then_left_f).named(f'{self.name} // {other.name}')
 
     def then_right(self, other: Algebra[B, S]) -> Algebra[Then[A, B], S]:
+        """Sequence two algebras, keep the right value in the result.
+
+        Produces ``Then(kind=RIGHT)`` with both values attached.
+
+        Args:
+            other: The algebra to run after this one.
+
+        Returns:
+            An algebra producing ``Then(left, right, kind=RIGHT)``.
+        """
         def then_right_f(a: A) -> Algebra[Then[A, B], S]:
             def combine(b: B) -> Then[A, B]:
                 return Then(left=a, right=b, kind=ThenKind.RIGHT)
-            return other.fmap(combine)
+            return other.map(combine)
         return self.flat_map(then_right_f).named(f'{self.name} >> {other.name}')
 
     def many(self, *, at_least: int, at_most: Optional[int]) -> Algebra[Many[A], S]:
+        """Repeat this algebra and collect results into ``Many``.
+
+        Repeats greedily until failure or no progress. Enforces cardinality
+        constraints. If ``at_most`` is ``None``, there is no upper bound.
+
+        Args:
+            at_least: Minimum number of matches required (>= 1).
+            at_most: Optional maximum number of matches.
+
+        Returns:
+            On success, ``Right((Many(values), state))``.
+        Note:
+            at_most, if given, is enforced strictly, more than at_most matches 
+            is treated as an error.
+        Raises:
+            ValueError: If bounds are invalid (e.g., ``at_least<=0`` or
+            ``at_most<at_least``).
+        """
         if at_least <=0 or (at_most is not None and at_most < at_least):
             raise ValueError(f"Invalid arguments for many: at_least={at_least}, at_most={at_most}")
         def many_run(input: S, use_cache:bool) -> Either[Any, Tuple[Many[A], S]]: