ast-pattern-engine 1.0.0__tar.gz → 1.0.2__tar.gz

ast_pattern_engine-1.0.2/.github/workflows/ci.yml

@@ -0,0 +1,86 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main", "dev" ]
+  pull_request:
+    branches: [ "main", "dev" ]
+
+jobs:
+  format-and-lint:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+
+    - name: Auto-format with Ruff
+      run: uv run ruff format
+
+    - name: Lint with Ruff
+      run: uv run ruff check --exit-zero
+
+    - name: Commit formatting changes
+      uses: stefanzweifel/git-auto-commit-action@v5
+      with:
+        commit_message: "style: auto-format with ruff"
+
+  test:
+    runs-on: ubuntu-latest
+    needs: format-and-lint
+    if: always()
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        ref: ${{ github.ref }}
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      run: uv sync --all-extras --all-groups
+
+    - name: Run tests with pytest
+      run: uv run pytest --cov=src --cov-report=xml
+
+    - name: Upload coverage reports to Codecov
+      uses: codecov/codecov-action@v5
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  deploy-docs:
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+
+    - name: Install Docs Dependencies
+      run: uv sync --only-group docs
+
+    - name: Deploy Docs
+      run: uv run mkdocs gh-deploy --force

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ast-pattern-engine
-Version: 1.0.0
+Version: 1.0.2
 Summary: A library for regex-inspired fine-grained AST pattern matching and replacing
 Project-URL: Homepage, https://github.com/80sVectorz/ast_pattern_engine
 Project-URL: Repository, https://github.com/80sVectorz/ast_pattern_engine
@@ -21,6 +21,13 @@ Provides-Extra: dev
 Requires-Dist: pytest; extra == 'dev'
 Description-Content-Type: text/markdown
 
+![PyPI - Version](https://img.shields.io/pypi/v/ast-pattern-engine)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ast-pattern-engine)
+![Pytest](https://img.shields.io/badge/pytest-tested-orange)
+![MIT License](https://img.shields.io/badge/License-MIT-blue)
+![Codecov](https://codecov.io/gh/80sVectorz/ast_pattern_engine/branch/main/graph/badge.svg)
+![GitHub Workflow Status](https://github.com/80sVectorz/ast_pattern_engine/actions/workflows/ci.yml/badge.svg)
+
 # AST Pattern Engine
 
 A powerful, programmatic, regex-inspired AST pattern matching and manipulation library for Python.

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/README.md

@@ -1,3 +1,10 @@
+![PyPI - Version](https://img.shields.io/pypi/v/ast-pattern-engine)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ast-pattern-engine)
+![Pytest](https://img.shields.io/badge/pytest-tested-orange)
+![MIT License](https://img.shields.io/badge/License-MIT-blue)
+![Codecov](https://codecov.io/gh/80sVectorz/ast_pattern_engine/branch/main/graph/badge.svg)
+![GitHub Workflow Status](https://github.com/80sVectorz/ast_pattern_engine/actions/workflows/ci.yml/badge.svg)
+
 # AST Pattern Engine
 
 A powerful, programmatic, regex-inspired AST pattern matching and manipulation library for Python.

ast_pattern_engine-1.0.2/docs/guide.md

@@ -0,0 +1,57 @@
+# Guide & Philosophy
+
+## Philosophy & Design
+
+Instead of having to rely on fragile direct source-code manipulation or slightly better magic string-expression-based AST manipulation engines, `ast_pattern_engine` provides an internal DSL for building explicit, structural patterns.
+
+It explicitly avoids string-based expressions because they simply don't scale well. For robust code-analysis you must have a grasp of the underlying AST structure.
+
+The package started as a component for another project and was later spun off into it's own clean package.
+Early experiences made it clear that large expressions aren't the way to go for AST manipulation.
+A staged approach is much more robust and easier to reason about.
+
+The package is intentionally kept somewhat limited to encourage using custom logic for more advanced filtering and analysis. Rather than building extremely nested gigantic expressions, it's encouraged to build small, focused patterns and visitors.
+Like casting a wide net and progressively filtering down in stages.
+
+## Primitives
+
+The library provides several primitives to build robust sequences:
+
+- `NodePattern`: Match specific AST node types and assert on their fields.
+- `Collect` / `Bind`: Extract sub-trees out of a matched pattern to use in your handlers. `Bind` assigns a name to a matched node so that it can be processed during transformation.
+- `OneOf`: Match one of several possible patterns (similar to regex `|`).
+- `Repetition`: Match a pattern sequentially 1 or more times (similar to regex `*` and `+`).
+- `Optional`: Match a pattern 0 or 1 times (similar to regex `?`).
+- `Filter`: Apply arbitrary Python lambdas to check node states during matching.
+
+## Building Patterns
+
+A typical pattern is a sequence of `Pattern` objects. For instance, finding a sequence of assignments:
+
+```python
+from ast_pattern_engine import NodePattern, Bind
+import ast
+
+# Matches an assignment of any value to "x"
+assign_to_x = NodePattern(
+    ast.Assign,
+    targets=[NodePattern(ast.Name, id="x")],
+    value=Bind("x_value")
+)
+```
+
+## Transformers and Finders
+
+Once a pattern is matched, you often want to act on it.
+
+- **Transformers** (`PatternTransformer`, `BottomUpPatternTransformer`): These visitors replace matched subtrees with new nodes generated by your handlers. A handler receives the bound variables (E.G `Bind("x")`, `Collect()) and returns the replacement nodes.
+- **Finders** (`PatternFinder`, `SingleOccurrenceFinder`): These visitors just locate where patterns occur in the tree without modifying it. Useful for analysis or linting.
+
+## Templates
+
+To reduce boilerplate when building patterns, the library includes a `templates` module with helpers for common operations:
+- `match_call(func_name, **kwargs)`
+- `match_assign(target_name, value)`
+- `match_in_expr(pattern)`
+
+Using templates allows you to write dense, readable matching rules quickly.

ast_pattern_engine-1.0.2/docs/index.md

@@ -0,0 +1,46 @@
+# AST Pattern Engine
+
+A powerful, programmatic, regex-inspired AST pattern matching and manipulation library for Python.
+
+## Quick Start
+
+Here is a simple pipeline that rewrites `dict.get("key")` calls into direct subscript access `dict["key"]`:
+
+```python
+from typing import Any
+import ast
+from ast_pattern_engine import BottomUpPatternTransformer, Bind, NodePattern
+
+source = "value = my_dict.get(other_dict.get('foo'))"
+tree = ast.parse(source)
+
+# 1. Build the explicit structural pattern
+# Matches: <obj>.get(<key>)
+pattern = [
+    NodePattern(
+        ast.Call,
+        func=NodePattern(ast.Attribute, attr="get", value=Bind("obj")),
+        args=Bind("key"),
+    )
+]
+
+# 2. Define the rewrite logic
+def rewrite_dict_get(bindings: dict[str, Any]) -> list[ast.AST]:
+    obj = bindings["obj"]
+    key = bindings["key"][0]  # args is a list
+
+    # Return the new node to replace the matched node
+    new_node = ast.Subscript(value=obj, slice=key, ctx=ast.Load())
+    return [new_node]
+
+# 3. Apply the transformer
+# We use BottomUpPatternTransformer so nested `.get()` calls
+# are safely transformed from the inside-out.
+transformer = BottomUpPatternTransformer(pattern, {"key": rewrite_dict_get})
+transformer.visit(tree)
+
+print(ast.unparse(tree))
+# Output: value = my_dict[other_dict['foo']]
+```
+
+For more in-depth examples, refer to the [Guide](guide.md) or the [API Reference](reference/core.md).

ast_pattern_engine-1.0.2/docs/reference/core.md

@@ -0,0 +1,11 @@
+# Core & Engine
+
+This page documents the core base classes and the engine used to match sequences.
+
+::: ast_pattern_engine.core
+    options:
+      show_root_heading: true
+
+::: ast_pattern_engine.engine
+    options:
+      show_root_heading: true

ast_pattern_engine-1.0.2/docs/reference/nodes.md

@@ -0,0 +1,19 @@
+# Pattern Nodes
+
+Pattern nodes are the basic building blocks to construct matching logic over an AST.
+
+## Basic Nodes
+
+Basic nodes allow matching structural properties, capturing values, and simple boolean combinations.
+
+::: ast_pattern_engine.nodes.basic
+    options:
+      show_root_heading: true
+
+## Sequence Nodes
+
+Sequence nodes allow matching groups of adjacent nodes, similar to regex patterns.
+
+::: ast_pattern_engine.nodes.sequences
+    options:
+      show_root_heading: true

ast_pattern_engine-1.0.2/docs/reference/templates.md

@@ -0,0 +1,7 @@
+## Templates
+
+Templates provide convenient helper functions for generating common patterns.
+
+::: ast_pattern_engine.templates
+    options:
+      show_root_heading: true

ast_pattern_engine-1.0.2/docs/reference/visitors.md

@@ -0,0 +1,9 @@
+# AST Visitors
+
+Visitors use the pattern matching engine to find or transform abstract syntax trees.
+
+## Finders and Transformers
+
+::: ast_pattern_engine.visitors
+    options:
+      show_root_heading: true

ast_pattern_engine-1.0.2/docs/stylesheets/extra.css

@@ -0,0 +1,26 @@
+/* Add a simple visual divider above each mkdocstrings API object */
+.doc-object {
+    border-top: 1px solid var(--md-default-fg-color--lightest);
+    margin-top: 3rem;
+    padding-top: 1rem;
+}
+
+/* Remove the divider from the very first item on the page */
+.doc-object:first-child {
+    border-top: none;
+    margin-top: 0;
+    padding-top: 0;
+}
+
+/* Ensure the heading sits neatly below the divider */
+.doc-heading,
+.doc-symbol-heading {
+    margin-top: 0 !important;
+}
+
+/* Indent the contents (docstrings, parameters, methods) of classes and functions */
+.doc-contents {
+    margin-left: 1.5rem;
+    padding-left: 1rem;
+    border-left: 2px solid var(--md-default-fg-color--lightest);
+}

ast_pattern_engine-1.0.2/mkdocs.yaml

@@ -0,0 +1,50 @@
+site_name: AST Pattern Engine
+site_url: https://80svectorz.github.io/ast_pattern_engine/
+repo_url: https://github.com/80sVectorz/ast_pattern_engine
+
+theme:
+  name: material
+  palette:
+    - scheme: slate
+      primary: teal
+      accent: teal
+  features:
+    - navigation.tabs
+    - content.code.copy
+    - toc.follow
+
+plugins:
+  - search
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          options:
+            docstring_style: google
+            show_root_heading: true
+            show_source: true
+            separate_signature: true
+            show_signature_annotations: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_style: material
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+
+extra_css:
+  - stylesheets/extra.css
+
+nav:
+  - Home: index.md
+  - Guide & Philosophy: guide.md
+  - API Reference:
+      - Core & Engine: reference/core.md
+      - Pattern Nodes: reference/nodes.md
+      - AST Visitors: reference/visitors.md
+      - QoL Templates: reference/templates.md

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ast-pattern-engine"
-version = "1.0.0"
+version = "1.0.2"
 description = "A library for regex-inspired fine-grained AST pattern matching and replacing"
 readme = "README.md"
 authors = [
@@ -40,4 +40,10 @@ pythonpath = ["src"]
 [dependency-groups]
 dev = [
     "pytest-cov>=7.1.0",
+    "ruff>=0.11.0",
 ]
+docs = [
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.7.6",
+    "mkdocstrings[python]>=1.0.4",
+]

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/src/ast_pattern_engine/core.py

@@ -8,7 +8,11 @@ class Pattern(ast.AST):
 
     # public API
     def match_node(
-        self, node: object, bindings: dict[str, object] | None = None, *, _force_list: bool = False
+        self,
+        node: object,
+        bindings: dict[str, object] | None = None,
+        *,
+        _force_list: bool = False,
     ):
         """Match *node* and return updated *bindings* or *None*."""
         raise NotImplementedError
@@ -21,7 +25,11 @@ class Pattern(ast.AST):
 
 class SequencePattern(Pattern):
     def match_node(
-        self, node: object, bindings: dict[str, object] | None = None, *, _force_list: bool = False
+        self,
+        node: object,
+        bindings: dict[str, object] | None = None,
+        *,
+        _force_list: bool = False,
     ):
         # Matching is handled by engine._match_sequence
         raise NotImplementedError(

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/src/ast_pattern_engine/engine.py

@@ -26,7 +26,9 @@ def _match_patterns(
 
     match first:
         case PatternGroup(pattern=sub_pattern, key=key):
-            res = _match_patterns(sub_pattern, nodes, pos, dict(bindings), _force_list=_force_list)
+            res = _match_patterns(
+                sub_pattern, nodes, pos, dict(bindings), _force_list=_force_list
+            )
             if res:
                 new_bindings = res[-1][0]
                 if key is not None:
@@ -40,7 +42,9 @@ def _match_patterns(
             new_bindings = dict(bindings)
             n_reps = 0
             while n_reps < (max_matches or len(nodes)) and pos < len(nodes):
-                res = _match_patterns([sub_pattern], nodes, pos, dict(new_bindings), _force_list=True)
+                res = _match_patterns(
+                    [sub_pattern], nodes, pos, dict(new_bindings), _force_list=True
+                )
                 if not res:
                     break
                 new_bindings, pos = res[-1]
@@ -54,7 +58,9 @@ def _match_patterns(
             new_pos = pos
             n_matches = 0
             for pattern in sub_patterns:
-                res = _match_patterns([pattern], nodes, pos, dict(bindings), _force_list=_force_list)
+                res = _match_patterns(
+                    [pattern], nodes, pos, dict(bindings), _force_list=_force_list
+                )
                 if res:
                     n_matches += 1
                     if n_matches == 1:
@@ -74,7 +80,9 @@ def _match_patterns(
                 out.append((new_bindings, pos))
 
         case Optional(pattern=sub_pattern, key=key):
-            res = _match_patterns([sub_pattern], nodes, pos, dict(bindings), _force_list=_force_list)
+            res = _match_patterns(
+                [sub_pattern], nodes, pos, dict(bindings), _force_list=_force_list
+            )
             if res:
                 new_bindings, new_pos = res[-1]
                 if key is not None:
@@ -88,13 +96,17 @@ def _match_patterns(
         case _:
             # single node pattern
             if pos < len(nodes):
-                res = first.match_node(nodes[pos], dict(bindings), _force_list=_force_list)
+                res = first.match_node(
+                    nodes[pos], dict(bindings), _force_list=_force_list
+                )
                 if res is not None:
                     out.append((res, pos + 1))
 
     # Match remaining patterns
     if out and remaining:
-        rem_res = _match_patterns(remaining, nodes, out[-1][1], out[-1][0], _force_list=_force_list)
+        rem_res = _match_patterns(
+            remaining, nodes, out[-1][1], out[-1][0], _force_list=_force_list
+        )
         if not rem_res:
             return []
         out.extend(rem_res)

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/src/ast_pattern_engine/nodes/basic.py

@@ -11,10 +11,10 @@ from ast_pattern_engine.visitors import SingleOccurrenceFinder
 
 
 class Bind(Pattern):
-    """Bind the current node to `name`.
+    """Bind the current node to `key`.
 
     This is syntactic sugar for:
-        >>> Collect(WildCard(), "x")
+    >>> Collect(WildCard(), "x")
 
     Args:
         key: The key to bind the node(s) or value(s) to.
@@ -23,9 +23,20 @@ class Bind(Pattern):
     key: str
 
     def __init__(self, key: str):
+        """Bind node.
+
+        Args:
+            key: The key to bind the node(s) or value(s) to.
+        """
         self.key = key
 
-    def match_node(self, node: Any, bindings: dict[str, Any] | None = None, *, _force_list: bool = False):
+    def match_node(
+        self,
+        node: Any,
+        bindings: dict[str, Any] | None = None,
+        *,
+        _force_list: bool = False,
+    ):
         bindings = bindings or {}
         if self.key in bindings:
             if not _force_list:
@@ -41,7 +52,13 @@ class WildCard(Pattern):
 
     def __init__(self): ...
 
-    def match_node(self, node: Any, bindings: dict[str, Any] | None = None, *, _force_list: bool = False):
+    def match_node(
+        self,
+        node: Any,
+        bindings: dict[str, Any] | None = None,
+        *,
+        _force_list: bool = False,
+    ):
         bindings = bindings or {}
         return bindings
 
@@ -54,11 +71,26 @@ class NodePattern(Pattern):
         **field_patterns: Patterns or exact values to match against the node's fields.
     """
 
+    node_type: type[ast.AST]
+    field_patterns: dict[str, Pattern | Any]
+
     def __init__(self, node_type: type[ast.AST], **field_patterns: Pattern | Any):
+        """NodePattern node.
+
+        Args:
+            node_type: The AST node class to match (e.g., ast.Assign).
+            **field_patterns: Patterns or exact values to match against the node's fields.
+        """
         self.node_type = node_type
         self.field_patterns = field_patterns
 
-    def match_node(self, node: Any, bindings: dict[str, Any] | None = None, *, _force_list: bool = False):
+    def match_node(
+        self,
+        node: Any,
+        bindings: dict[str, Any] | None = None,
+        *,
+        _force_list: bool = False,
+    ):
         bindings = bindings or {}
         if not isinstance(node, self.node_type):
             return None
@@ -85,9 +117,7 @@ class NodePattern(Pattern):
                             return None
                         merged[k] = self._to_list(merged[k]) + self._to_list(v)
                     else:
-                        merged[k] = (
-                            self._to_list(v) if _force_list else v
-                        )
+                        merged[k] = self._to_list(v) if _force_list else v
             else:
                 if val != pat:
                     return None
@@ -103,17 +133,24 @@ class Collect(Pattern):
     """
 
     pattern: Pattern
-    """The pattern to match."""
-
     key: str
-    """The key to bind the pattern result to."""
 
     def __init__(self, pattern: Pattern, key: str):
+        """Collect node.
+
+        Args:
+            pattern: The pattern to match.
+            key: The key to bind the pattern result to.
+        """
         self.pattern = pattern
         self.key = key
 
     def match_node(
-        self, node: Any, bindings: dict[str, Any] | None = None, *, _force_list: bool = False
+        self,
+        node: Any,
+        bindings: dict[str, Any] | None = None,
+        *,
+        _force_list: bool = False,
     ) -> None | dict[str, Any]:
         bindings = bindings or {}
         # Collect is a binding boundary — inner patterns always see _force_list=False
@@ -158,16 +195,25 @@ class Filter(Pattern):
     """
 
     predicate: Callable[[Any], bool]
-    """The predicate to match."""
-
     key: str | None
-    """The key to bind the node to."""
 
     def __init__(self, predicate: Callable[[Any], bool], key: str | None = None):
+        """Filter node.
+
+        Args:
+            predicate: A callable that returns True if the node matches.
+            key: Optional key to bind the matched node to.
+        """
         self.predicate = predicate
         self.key = key
 
-    def match_node(self, node: Any, bindings: dict[str, Any] | None = None, *, _force_list: bool = False):
+    def match_node(
+        self,
+        node: Any,
+        bindings: dict[str, Any] | None = None,
+        *,
+        _force_list: bool = False,
+    ):
         bindings = bindings or {}
         if not self.predicate(node):
             return None
@@ -189,10 +235,23 @@ class Not(Pattern):
         pattern: The pattern that must fail for this to match.
     """
 
+    pattern: Pattern
+
     def __init__(self, pattern: Pattern):
+        """Not node.
+
+        Args:
+            pattern: The pattern that must fail for this to match.
+        """
         self.pattern = pattern
 
-    def match_node(self, node: Any, bindings: dict[str, Any] | None = None, *, _force_list: bool = False):
+    def match_node(
+        self,
+        node: Any,
+        bindings: dict[str, Any] | None = None,
+        *,
+        _force_list: bool = False,
+    ):
         bindings = bindings or {}
 
         # Use _match_patterns so that SequencePatterns (like OneOf) don't
@@ -211,10 +270,23 @@ class Contains(Pattern):
         pattern: The pattern or sequence of patterns to search for in the sub-tree.
     """
 
+    pattern: Sequence[Pattern]
+
     def __init__(self, pattern: Sequence[Pattern]):
+        """Contains node.
+
+        Args:
+            pattern: The pattern or sequence of patterns to search for in the sub-tree.
+        """
         self.pattern = list(pattern)
 
-    def match_node(self, node: Any, bindings: dict[str, Any] | None = None, *, _force_list: bool = False):
+    def match_node(
+        self,
+        node: Any,
+        bindings: dict[str, Any] | None = None,
+        *,
+        _force_list: bool = False,
+    ):
         bindings = bindings or {}
         finder = SingleOccurrenceFinder(self.pattern)
         finder.visit(node)
@@ -240,17 +312,29 @@ class AllOf(Pattern):
     """
 
     patterns: Sequence[Pattern]
-    """The patterns to match."""
 
     def __init__(self, patterns: Sequence[Pattern]):
+        """AllOf node.
+
+        Args:
+            patterns: Sequence of patterns that must all match the node.
+        """
         self.patterns = list(patterns)
 
-    def match_node(self, node: Any, bindings: dict[str, Any] | None = None, *, _force_list: bool = False):
+    def match_node(
+        self,
+        node: Any,
+        bindings: dict[str, Any] | None = None,
+        *,
+        _force_list: bool = False,
+    ):
         bindings = bindings or {}
         new_bindings = dict(bindings)
 
         for pattern in self.patterns:
-            new_bindings = pattern.match_node(node, new_bindings, _force_list=_force_list)
+            new_bindings = pattern.match_node(
+                node, new_bindings, _force_list=_force_list
+            )
             if new_bindings is None:
                 return None
         return new_bindings
@@ -264,12 +348,22 @@ class AnyOf(Pattern):
     """
 
     patterns: list[Pattern]
-    """The patterns to match."""
 
     def __init__(self, patterns: Sequence[Pattern]):
+        """AnyOf node.
+
+        Args:
+            patterns: Sequence of patterns where at least one must match.
+        """
         self.patterns = list(patterns)
 
-    def match_node(self, node: Any, bindings: dict[str, Any] | None = None, *, _force_list: bool = False):
+    def match_node(
+        self,
+        node: Any,
+        bindings: dict[str, Any] | None = None,
+        *,
+        _force_list: bool = False,
+    ):
         bindings = bindings or {}
         merged = dict(bindings)
         matched_any = False

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/src/ast_pattern_engine/nodes/sequences.py

@@ -6,7 +6,11 @@ from ast_pattern_engine.core import Pattern
 
 class SequencePattern(Pattern):
     def match_node(
-        self, node: object, bindings: dict[str, object] | None = None, *, _force_list: bool = False
+        self,
+        node: object,
+        bindings: dict[str, object] | None = None,
+        *,
+        _force_list: bool = False,
     ):
         # Matching is handled by engine._match_sequence
         raise NotImplementedError(
@@ -18,16 +22,16 @@ class Repetition(SequencePattern):
     """Matches a single pattern zero or more times.
 
     Also supports specifying min and max match count thresholds
+
+    Args:
+        pattern: The pattern to match.
+        min_matches: Minimum number of matches required. Default is 1.
+        max_matches: Maximum number of allowed matches. Defaults to None.
     """
 
     pattern: Pattern
-    """The pattern to match."""
-
     min_matches: int
-    """Minimum number of matches required. Defaults to 1."""
-
     max_matches: int | None
-    """Maximum number of allowed matches. Defaults to None."""
 
     def __init__(
         self,
@@ -38,9 +42,9 @@ class Repetition(SequencePattern):
         """Repetition node.
 
         Args:
-            pattern: The AST pattern.
-            min_matches: Min number of matches required. Default is 1.
-            max_matches: Max number of allowed matches. Defaults to None.
+            pattern: The pattern to match.
+            min_matches: Minimum number of matches required. Default is 1.
+            max_matches: Maximum number of allowed matches. Defaults to None.
         """
         self.pattern = pattern
         self.min_matches = min_matches
@@ -48,13 +52,15 @@ class Repetition(SequencePattern):
 
 
 class PatternGroup(SequencePattern):
-    """Matches a compound pattern/pattern group to an AST node sequence."""
+    """Matches a compound pattern/pattern group to an AST node sequence.
 
-    pattern: Sequence[Pattern]
-    """The compound pattern to match."""
+    Args:
+        pattern: The compound pattern to match.
+        key: Optional key to bind the matched pattern to.
+    """
 
+    pattern: Sequence[Pattern]
     key: str | None
-    """Optional key to bind the matched pattern to."""
 
     def __init__(self, pattern: Sequence[Pattern], key: str | None = None) -> None:
         """PatternGroup node.
@@ -80,30 +86,34 @@ class OneOf(SequencePattern):
     """
 
     patterns: list[Pattern]
-    """The patterns to match."""
-
     strict: bool
-    """Whether to be strict and only match if *exactly* one pattern matches."""
-
     key: str | None
-    """Optional key to bind the matched pattern to."""
 
     def __init__(
         self, patterns: Sequence[Pattern], strict: bool = False, key: str | None = None
     ) -> None:
+        """OneOf node.
+
+        Args:
+            patterns: The patterns to match
+            strict: Whether to be strict and only match if *exactly* one pattern matches
+            key: Optional key to bind the matched pattern to
+        """
         self.patterns = list(patterns)
         self.strict = strict
         self.key = key
 
 
 class Optional(SequencePattern):
-    """Matches a pattern zero or one times."""
+    """Matches a pattern zero or one times.
 
-    pattern: Pattern
-    """The pattern to match."""
+    Args:
+        pattern: The pattern to match.
+        key: Optional key to bind the matched pattern to.
+    """
 
+    pattern: Pattern
     key: str | None
-    """Optional key to bind the matched pattern to."""
 
     def __init__(self, pattern: Pattern, key: str | None = None) -> None:
         """Optional node.

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/src/ast_pattern_engine/visitors.py

@@ -1,3 +1,4 @@
+from typing import TypeAlias
 import ast
 from typing import Any
 from collections.abc import Sequence, Callable
@@ -5,7 +6,7 @@ from collections.abc import Sequence, Callable
 from ast_pattern_engine.core import Pattern
 from ast_pattern_engine.engine import _match_patterns
 
-type ReplaceResult = ast.AST | list[ast.AST] | None
+ReplaceResult: TypeAlias = ast.AST | list[ast.AST] | None
 
 
 class PatternTransformer(ast.NodeTransformer):
@@ -28,6 +29,9 @@ class PatternTransformer(ast.NodeTransformer):
     Args:
         pattern: Sequence of pattern nodes matched against each candidate span.
         actions: Mapping from collect keys to replacement handlers or None.
+
+    Attributes:
+        matches: List of bindings for each match.
     """
 
     def __init__(
@@ -358,6 +362,9 @@ class BottomUpPatternTransformer(ast.NodeTransformer):
     Args:
         pattern: Sequence of pattern nodes matched against each candidate span.
         actions: Mapping from collect keys to replacement handlers or None.
+
+    Attributes:
+        matches: List of bindings for each match.
     """
 
     def __init__(
@@ -441,6 +448,10 @@ class PatternFinder(ast.NodeVisitor):
 
     Args:
         pattern: Sequence of pattern nodes to search for.
+
+    Attributes:
+        matches: List of bindings for each match.
+        visited: Set of visited node IDs.
     """
 
     def __init__(self, pattern: Sequence[Pattern]):
@@ -486,6 +497,10 @@ class SingleOccurrenceFinder(ast.NodeVisitor):
 
     Args:
         pattern: Sequence of pattern nodes to search for.
+
+    Attributes:
+        match_node: The first match node, if any.
+        match_bindings: The bindings for the first match, if any.
     """
 
     match_node: ast.AST | None
@@ -496,15 +511,15 @@ class SingleOccurrenceFinder(ast.NodeVisitor):
         self.match_node = None
         self.match_bindings = {}
         self.pattern = pattern
-        self.found = False
+        self._found_match = False
 
     def visit(self, node: ast.AST):
-        if self.found:
+        if self._found_match:
             return  # short-circuit: we've already found a match
 
         res = _match_patterns(self.pattern, [node], 0, {})
         if res:
-            self.found = True
+            self._found_match = True
             self.match_node = node
             self.match_bindings = res[0][0]
             return
@@ -515,12 +530,12 @@ class SingleOccurrenceFinder(ast.NodeVisitor):
                 for item in val:
                     if isinstance(item, ast.AST):
                         self.visit(item)
-                        if self.found:
+                        if self._found_match:
                             return
             elif isinstance(val, ast.AST):
                 self.visit(val)
-                if self.found:
+                if self._found_match:
                     return
 
     def found_match(self) -> bool:
-        return self.found
+        return self._found_match

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/tests/patterns/test_any_of.py

@@ -1,32 +1,22 @@
 import ast
 from ast_pattern_engine.nodes.basic import AnyOf, NodePattern, Collect
 
+
 def test_any_of_matches_and_conflicts():
     node = ast.parse("1").body[0].value
-    
+
     # First matches
-    pattern1 = AnyOf([
-        NodePattern(ast.Constant),
-        NodePattern(ast.Name)
-    ])
+    pattern1 = AnyOf([NodePattern(ast.Constant), NodePattern(ast.Name)])
     assert pattern1.match_node(node, {"existing": 1}) == {"existing": 1}
-    
+
     # Second matches
-    pattern2 = AnyOf([
-        NodePattern(ast.Name),
-        NodePattern(ast.Constant)
-    ])
+    pattern2 = AnyOf([NodePattern(ast.Name), NodePattern(ast.Constant)])
     assert pattern2.match_node(node, {}) == {}
-    
+
     # None matches
-    pattern3 = AnyOf([
-        NodePattern(ast.Name),
-        NodePattern(ast.Assign)
-    ])
+    pattern3 = AnyOf([NodePattern(ast.Name), NodePattern(ast.Assign)])
     assert pattern3.match_node(node, {}) is None
 
     # Match produces conflicting key
-    pattern4 = AnyOf([
-        Collect(NodePattern(ast.Constant), "c")
-    ])
+    pattern4 = AnyOf([Collect(NodePattern(ast.Constant), "c")])
     assert pattern4.match_node(node, {"c": "conflict"}) is None

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/tests/patterns/test_collect.py

@@ -1,6 +1,7 @@
 import ast
 from ast_pattern_engine.nodes.basic import Collect, NodePattern
 
+
 def test_collect_match_single_constant():
     node = ast.parse("1").body[0]
     assert isinstance(node, ast.Expr)

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/tests/patterns/test_filter.py

@@ -3,6 +3,7 @@ from ast_pattern_engine.nodes.basic import Filter
 from ast_pattern_engine.nodes.sequences import Repetition
 from ast_pattern_engine.engine import match_sequence
 
+
 def test_filter_no_key():
     node = ast.parse("1").body[0].value
     # Matches, no key bound
@@ -17,14 +18,14 @@ def test_filter_no_key():
 def test_filter_with_key_and_conflicts():
     node = ast.parse("1").body[0].value
     pattern = Filter(lambda x: isinstance(x, ast.Constant), key="my_filter")
-    
+
     # Matches and binds
     res = pattern.match_node(node, {})
     assert res == {"my_filter": node}
-    
+
     # Conflict on duplicate key without force
     assert pattern.match_node(node, {"my_filter": "existing"}) is None
-    
+
     # When inside a Repetition, ancestor forces list
     rep_pattern = Repetition(pattern)
     # Match node directly against the filter while simulating the Repetition context

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/tests/patterns/test_one_of.py

@@ -3,6 +3,7 @@ from ast_pattern_engine.nodes.basic import Collect, WildCard, NodePattern
 from ast_pattern_engine.nodes.sequences import OneOf
 from ast_pattern_engine.engine import _match_patterns, match_sequence
 
+
 def test_one_of_non_strict_returns_first_match():
     nodes = [ast.parse(src).body[0] for src in ("1", "2")]
     pattern = [
@@ -49,9 +50,9 @@ def test_one_of_strict_matches_exactly_one_pattern():
     ]
 
     result = _match_patterns(pattern, nodes, 0, {})
-    assert (
-        len(result) == 0
-    ), "Expected strict OneOf not to match because multiple sub patterns match"
+    assert len(result) == 0, (
+        "Expected strict OneOf not to match because multiple sub patterns match"
+    )
 
     # Section B: Test strict mode with exactly one matching pattern for each line
     nodes = [ast.parse(src).body[0] for src in ("1", "x=2")]

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/tests/patterns/test_pattern_group.py

@@ -3,6 +3,7 @@ from ast_pattern_engine.nodes.basic import Collect, WildCard, NodePattern
 from ast_pattern_engine.nodes.sequences import PatternGroup
 from ast_pattern_engine.engine import _match_patterns, match_sequence
 
+
 def test_pattern_group_collects_inner_bindings_under_key():
     nodes = [ast.parse(src).body[0].value for src in ("1", "2")]  # type: ignore
     pattern = [

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/tests/patterns/test_repetition.py

@@ -3,6 +3,7 @@ from ast_pattern_engine.nodes.basic import Collect, WildCard
 from ast_pattern_engine.nodes.sequences import Repetition
 from ast_pattern_engine.engine import _match_patterns
 
+
 def test_collect_inside_one_or_more_accumulates_nodes():
     nodes = [ast.parse(str(i)).body[0].value for i in range(3)]  # type: ignore
     pattern = [Repetition(Collect(WildCard(), "item"))]

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/tests/test_engine.py

@@ -2,6 +2,7 @@ import ast
 from ast_pattern_engine.nodes.basic import Collect, WildCard
 from ast_pattern_engine.engine import match_sequence
 
+
 def test_match_sequence_returns_non_overlapping_bindings():
     nodes = [ast.parse(text).body[0] for text in ("a = 1", "b = 2", "c = 3")]
     pattern = [Collect(WildCard(), "assign")]

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/tests/visitors/test_bottom_up_pattern_transformer.py

@@ -14,7 +14,7 @@ def _constant(value, template):
 
 
 def test_bottom_up_pattern_transformer_collapses_children_before_parent():
-    source = "def foo():\n" "    return (1 + 2) + (3 + 4)\n"
+    source = "def foo():\n    return (1 + 2) + (3 + 4)\n"
     tree = ast.parse(source)
     pattern = [Collect(NodePattern(ast.BinOp), "expr")]
 
@@ -60,6 +60,7 @@ def test_bu_transformer_list_manipulation():
     # Return multiple nodes (expands)
     def expand(_):
         return [_parse_stmt("pass"), _parse_stmt("pass")]
+
     transformer3 = BottomUpPatternTransformer(pattern, {"a": expand})
     res3 = transformer3.visit(ast.parse("x = 1"))
     assert len(res3.body) == 2

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/tests/visitors/test_pattern_finder.py

@@ -17,7 +17,10 @@ def test_pattern_finder_collects_node_matches():
 def test_pattern_finder_scan_list():
     tree = ast.parse("a = 1\nb = 2\nc = 3")
     # A sequence of length 2 to trigger `_scan_list` len(self.pattern) > 1 branch
-    pattern = [Collect(NodePattern(ast.Assign), "a"), Collect(NodePattern(ast.Assign), "b")]
+    pattern = [
+        Collect(NodePattern(ast.Assign), "a"),
+        Collect(NodePattern(ast.Assign), "b"),
+    ]
     finder = PatternFinder(pattern)
     finder.visit(tree)
     # Print the matches to debug

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/tests/visitors/test_pattern_transformer.py

@@ -123,7 +123,7 @@ def test_pt_nonlist_replace_errors():
 
     # Error: handler returns non-list
     def bad_handler(_):
-        return _constant_val(2) # type: ignore
+        return _constant_val(2)  # type: ignore
 
     transformer2 = PatternTransformer(pattern, {"c": bad_handler})
     with pytest.raises(TypeError, match="Handler must return list"):
@@ -133,7 +133,7 @@ def test_pt_nonlist_replace_errors():
 def test_pt_plan_errors():
     tree = ast.parse("a = 1\nb = 2")
     pattern = [Collect(NodePattern(ast.Assign), "a")]
-    
+
     # key not in bindings (should silently continue)
     transformer1 = PatternTransformer(pattern, {"missing_key": lambda b: []})
     transformer1.visit(ast.parse("a = 1"))
@@ -142,11 +142,12 @@ def test_pt_plan_errors():
     transformer2 = PatternTransformer(pattern, {"a": lambda b: []})
     # override matching to return empty list for testing
     b = {"a": []}
-    transformer2.matches.append(b) 
-    
+    transformer2.matches.append(b)
+
     # handler returns non-list
     def bad_plan_handler(_):
         return "not a list"
+
     transformer3 = PatternTransformer(pattern, {"a": bad_plan_handler})
     with pytest.raises(TypeError, match="must return `list"):
         transformer3.visit(ast.parse("a = 1"))
@@ -166,6 +167,7 @@ def test_pt_nested_replace_and_delete():
     # Replace nested nodes
     def replace_with_99(_):
         return [_constant_val(99)]
+
     transformer2 = PatternTransformer(pattern, {"c": replace_with_99})
     res2 = transformer2.visit(ast.parse("x = [1, 2, 3]"))
     assert all(elt.value == 99 for elt in res2.body[0].value.elts)
@@ -174,18 +176,20 @@ def test_pt_nested_replace_and_delete():
 def test_pt_dict_as_nodes():
     tree = ast.parse("x = 1")
     pattern = [Collect(NodePattern(ast.Assign), "a")]
-    
+
     # We force the binding to be a dict to trigger dict handling in _as_nodes
     class DictTransformer(PatternTransformer):
         def _plan(self, seq):
             # Intercept and mutate bindings
             res = super()._plan(seq)
             return res
-            
+
     transformer = DictTransformer(pattern, {"a": lambda b: [_parse_stmt("x = 2")]})
     # Override match manually
-    mtch = transformer._match_patterns = lambda p, s, i, b: [({"a": {"nested": s[i]}}, i+1)] if i < len(s) else []
-    
+    mtch = transformer._match_patterns = lambda p, s, i, b: (
+        [({"a": {"nested": s[i]}}, i + 1)] if i < len(s) else []
+    )
+
     res = transformer.visit(tree)
     assert isinstance(res.body[0], ast.Assign)
     assert res.body[0].value.value == 2
@@ -195,14 +199,14 @@ def test_pt_generic_visit_list_field_error():
     tree = ast.parse("a = 1")
     pattern = [Collect(NodePattern(ast.Assign), "a")]
     transformer = PatternTransformer(pattern, {})
-    
+
     # Force a child to not be an AST node
     class BadTransformer(PatternTransformer):
         def visit(self, node):
             if isinstance(node, ast.Assign):
                 return "Not an AST node"
             return super().visit(node)
-            
+
     bad_transformer = BadTransformer(pattern, {})
     with pytest.raises(TypeError, match="must contain AST nodes"):
         bad_transformer.visit(ast.parse("a = 1"))

{ast_pattern_engine-1.0.0 → ast_pattern_engine-1.0.2}/tests/visitors/test_single_occurrence_finder.py

@@ -29,8 +29,8 @@ def test_single_occurrence_finder_early_exit():
     tree = ast.parse("a = 1\nb = 2")
     pattern = [NodePattern(ast.Assign)]
     finder = SingleOccurrenceFinder(pattern)
-    
+
     # We manually set found to True to test early exit in visit
-    finder.found = True
+    finder._found_match = True
     finder.visit(tree)
-    assert finder.match_node is None # Didn't actually match because it early exited
+    assert finder.match_node is None  # Didn't actually match because it early exited

ast_pattern_engine-1.0.0/.github/workflows/ci.yml

@@ -1,44 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [ "main" ]
-  pull_request:
-    branches: [ "main" ]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
-
-    steps:
-    - uses: actions/checkout@v4
-    
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
-      with:
-        python-version: ${{ matrix.python-version }}
-        
-    - name: Install uv
-      uses: astral-sh/setup-uv@v5
-      with:
-        enable-cache: true
-        
-    - name: Install dependencies
-      run: uv sync --all-extras
-      
-    - name: Check formatting with Ruff
-      run: uv run ruff format --check
-      
-    - name: Lint with Ruff
-      run: uv run ruff check
-      
-    - name: Run tests with pytest
-      run: uv run pytest --cov=src --cov-report=xml
-      
-    - name: Upload coverage reports to Codecov
-      uses: codecov/codecov-action@v4
-      env:
-        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

ast_pattern_engine-1.0.0/src/ast_pattern_engine/plumbing.py

@@ -1,2 +0,0 @@
-# This module previously contained the Message/AnnounceBinding plumbing.
-# That system has been replaced by stateless _force_list context passing.