php-parser-py 1.2.4__py3-none-win_amd64.whl

php_parser_py/__init__.py

@@ -0,0 +1,33 @@
+"""php-parser-py: Python wrapper for PHP-Parser using cpg2py.
+
+This package provides a Python interface to PHP-Parser, enabling AST parsing
+and manipulation of PHP code.
+"""
+
+from __future__ import annotations
+
+__version__ = "1.2.2"
+__all__ = [
+    "AST",
+    "Edge",
+    "Modifier",
+    "Node",
+    "Parser",
+    "Printer",
+    "StandardPrinter",
+    "ExtendedPrinter",
+    "PrintMode",
+    "PrintRequest",
+    "ParseError",
+    "RunnerError",
+    "NodeNotInFileError",
+    "parse_code",
+    "parse_file",
+    "parse_project",
+]
+
+from ._exceptions import NodeNotInFileError, ParseError, RunnerError
+from ._graph import AST, Edge, Modifier, Node
+from ._parser import Parser, parse_code, parse_file, parse_project
+from ._printer import ExtendedPrinter, Printer, StandardPrinter
+from ._types import PrintMode, PrintRequest

php_parser_py/_exceptions.py

@@ -0,0 +1,58 @@
+"""Exception classes for php-parser-py."""
+
+from __future__ import annotations
+
+
+class ParseError(Exception):
+    """Raised when PHP-Parser reports a syntax error.
+
+    Attributes:
+        message: Error message from PHP-Parser.
+        line: Line number where the error occurred, if available.
+    """
+
+    def __init__(self, message: str, line: int | None = None) -> None:
+        """Initialize ParseError.
+
+        Args:
+            message: Error message from PHP-Parser.
+            line: Line number where the error occurred, if available.
+        """
+        super().__init__(message)
+        self.message = message
+        self.line = line
+
+
+class NodeNotInFileError(Exception):
+    """Raised when a node has no containing file (e.g. project node or orphan).
+
+    Use when get_file(node_id) is called and the node is not under any file node.
+    """
+
+    def __init__(self, node_id: str, message: str | None = None) -> None:
+        self.node_id = node_id
+        self.message = message or f"Node {node_id!r} is not under any file node."
+        super().__init__(self.message)
+
+
+class RunnerError(Exception):
+    """Raised when PHP process execution fails.
+
+    Attributes:
+        message: Error message describing the failure.
+        stderr: Standard error output from the PHP process.
+        exit_code: Exit code returned by the PHP process.
+    """
+
+    def __init__(self, message: str, stderr: str = "", exit_code: int = 1) -> None:
+        """Initialize RunnerError.
+
+        Args:
+            message: Error message describing the failure.
+            stderr: Standard error output from the PHP process.
+            exit_code: Exit code returned by the PHP process.
+        """
+        super().__init__(message)
+        self.message = message
+        self.stderr = stderr
+        self.exit_code = exit_code

php_parser_py/_graph/__init__.py

@@ -0,0 +1,19 @@
+"""Graph layer: AST querying, node/edge wrappers, and mutation."""
+
+# pylint: disable=duplicate-code  # __all__ mirrors the package re-export list.
+
+from __future__ import annotations
+
+__all__ = [
+    "AST",
+    "Edge",
+    "Modifier",
+    "Node",
+    "NodeId",
+]
+
+from ._ast import AST
+from ._edge import Edge
+from ._modifier import Modifier
+from ._node import Node
+from ._node_id import NodeId

php_parser_py/_graph/_ast.py

@@ -0,0 +1,227 @@
+"""AST representation for PHP code using cpg2py's graph framework."""
+
+from __future__ import annotations
+
+import copy
+
+from cpg2py import AbcGraphQuerier, Storage
+
+from .._exceptions import NodeNotInFileError
+from .._types import PARENT_OF_EDGE, PROJECT_ROOT_ID
+from ._edge import Edge
+from ._node import Node
+from ._node_id import NodeId
+
+
+class AST(AbcGraphQuerier[Node, Edge]):
+    """Represents a PHP Abstract Syntax Tree as a queryable graph.
+
+    Extends cpg2py's AbcGraphQuerier with Node and Edge type parameters.
+    Query-only: traversal, node/edge lookup, and file resolution. JSON
+    reconstruction lives in ``Mapping.serialize``.
+
+    The AST structure follows a hierarchy:
+    - Project node (ID: "project") - root of the AST
+    - File nodes (ID: hex hash) - children of project
+    - Statement nodes (ID: {hex}_{counter}) - children of files
+
+    Uses the cpg2py graph API (nodes, edges, succ, prev, ancestors,
+    descendants); storage is only used for node/edge existence and Node/Edge
+    construction.
+
+    Attributes:
+        _root_node_id: ID of the root project node (always "project").
+    """
+
+    def __init__(self, storage: Storage, root_node_id: str = PROJECT_ROOT_ID) -> None:
+        """Initialize AST with populated storage.
+
+        Args:
+            storage: cpg2py Storage containing AST nodes and edges.
+            root_node_id: ID of the root node. Defaults to "project".
+        """
+        super().__init__(storage)
+        self._root_node_id = root_node_id
+
+    @property
+    def storage(self) -> Storage:
+        """Block public access to the writable graph store.
+
+        AST is query-only and mutation is copy-on-write via ``Modifier``;
+        exposing the live ``Storage`` would reopen the in-place mutation path.
+        Internal collaborators use the private ``_graph`` accessor instead.
+
+        Raises:
+            AttributeError: Always; the storage is not part of the public API.
+        """
+        raise AttributeError(
+            "AST.storage is not public; mutate via Modifier (copy-on-write)."
+        )
+
+    @property
+    def _graph(self) -> Storage:
+        """Return the underlying graph store for internal reads."""
+        return super().storage
+
+    @property
+    def project_root_id(self) -> str:
+        """Return the root node ID of this AST."""
+        return self._root_node_id
+
+    def copy(self) -> AST:
+        """Return a new AST backed by a deep copy of this graph.
+
+        Node IDs, the edge set, and all node/edge properties are duplicated
+        verbatim, preserving the ``{file_hash}_{counter}`` ID namespace and the
+        root node ID. The returned AST shares no mutable state with this one:
+        mutating either graph leaves the other unchanged.
+
+        Returns:
+            A new AST whose storage is an independent copy of this graph.
+        """
+        storage = Storage()
+        self._copy_nodes_into(storage)
+        self._copy_edges_into(storage)
+        return AST(storage, root_node_id=self._root_node_id)
+
+    def _copy_nodes_into(self, storage: Storage) -> None:
+        """Duplicate every node and its properties into ``storage``."""
+        for node_id in self._graph.get_nodes():
+            storage.add_node(node_id)
+            props = self._graph.get_node_props(node_id)
+            if props:
+                storage.set_node_props(node_id, copy.deepcopy(props))
+
+    def _copy_edges_into(self, storage: Storage) -> None:
+        """Duplicate every edge and its properties into ``storage``."""
+        for edge_id in self._graph.get_edges():
+            storage.add_edge(edge_id)
+            props = self._graph.get_edge_props(edge_id)
+            if props:
+                storage.set_edge_props(edge_id, copy.deepcopy(props))
+
+    def node(self, whose_id_is: str) -> Node:
+        """Return node wrapper by ID.
+
+        Args:
+            whose_id_is: Node ID string.
+
+        Returns:
+            Node instance for the given ID.
+
+        Raises:
+            KeyError: If the node ID is not in the graph.
+        """
+        if not self._graph.contains_node(whose_id_is):
+            raise KeyError(f"Node not found: {whose_id_is!r}")
+        return Node(self._graph, whose_id_is)
+
+    def edge(self, fid: str, tid: str, eid: str) -> Edge:
+        """Return edge wrapper by IDs.
+
+        Args:
+            fid: From node ID.
+            tid: To node ID.
+            eid: Edge type.
+
+        Returns:
+            Edge instance for the given (from, to, type).
+
+        Raises:
+            KeyError: If the edge is not in the graph.
+        """
+        edge_id = (fid, tid, eid)
+        if not self._graph.contains_edge(edge_id):
+            raise KeyError(f"Edge not found: {edge_id!r}")
+        return Edge(self._graph, fid, tid, eid)
+
+    def project_node(self) -> Node:
+        """Return the project node (root of the AST).
+
+        The project node has ID "project" and is always present when the AST
+        was created by parse_file or parse_project.
+
+        Returns:
+            Project Node instance.
+
+        Raises:
+            KeyError: If the root node is not in the graph.
+        """
+        if not self._graph.contains_node(self._root_node_id):
+            raise KeyError(f"Project node not found: {self._root_node_id!r}")
+        return Node(self._graph, self._root_node_id)
+
+    def file_nodes(self) -> list[Node]:
+        """Return all file nodes in the project.
+
+        Returns:
+            List of File Node instances.
+        """
+        try:
+            project = self.project_node()
+        except KeyError:
+            return []
+
+        # succ() follows every edge type; a caller-added project->file edge
+        # of another type must not list the file twice.
+        children = self.succ(project, lambda e: e.type == PARENT_OF_EDGE)
+        file_nodes = [n for n in children if n.node_type == "File"]
+        return sorted(file_nodes, key=lambda n: n.get("absolutePath", ""))
+
+    def get_file_node(self, node_id: str) -> Node:
+        """Get the file node that contains the given node.
+
+        Uses the AST ID convention: file node ID is the file hash (e.g. 8-char hex);
+        nodes inside that file have ID ``file_hash + "_" + increment`` (e.g. ``a1b2c3d4_1``).
+        Resolves by structure first, then falls back to ancestors() traversal.
+
+        Args:
+            node_id: ID of any node in the AST.
+
+        Returns:
+            File Node instance containing the given node.
+
+        Raises:
+            KeyError: If the node ID is not in the graph.
+            NodeNotInFileError: If the node is not under any file (e.g. project node).
+        """
+        node = self.node(node_id)
+        if node.node_type == "File":
+            return node
+
+        if node_id == self._root_node_id:
+            raise NodeNotInFileError(node_id, "Project node has no containing file.")
+
+        result = self._try_file_by_id_prefix(node_id)
+        if result is not None:
+            return result
+
+        return self._find_file_ancestor(node)
+
+    def _try_file_by_id_prefix(self, node_id: str) -> Node | None:
+        """Try to find the file node via the ``NodeId`` prefix convention.
+
+        Returns None when the ID does not match the convention or the file is
+        not present.
+        """
+        parsed = NodeId.parse(node_id)
+        if parsed is None or not parsed.file_hash:
+            return None
+
+        try:
+            candidate = self.node(parsed.file_hash)
+        except KeyError:
+            return None
+        return candidate if candidate.node_type == "File" else None
+
+    def _find_file_ancestor(self, node: Node) -> Node:
+        """Find first File ancestor of a node via traversal.
+
+        Raises NodeNotInFileError if no File ancestor exists.
+        """
+        for ancestor in self.ancestors(node):
+            if ancestor.node_type == "File":
+                result: Node = ancestor
+                return result
+
+        raise NodeNotInFileError(node.id, "No File node among ancestors.")

php_parser_py/_graph/_edge.py

@@ -0,0 +1,102 @@
+"""Edge class for AST relationships."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cpg2py import AbcEdgeQuerier, Storage
+
+from .._types import PARENT_OF_EDGE
+
+
+class Edge(AbcEdgeQuerier):
+    """Represents an edge between AST nodes with generic property access.
+
+    Extends cpg2py's AbcEdgeQuerier. Edge type is fixed (e.g. "PARENT_OF");
+    other data is stored as arbitrary properties via Storage. For PARENT_OF
+    edges in our PHP AST mapping, we use properties "field" and "index" to
+    represent the PHP-Parser subnode key and array position—access them via
+    edge.get("field"), edge.get("index") or edge["field"], edge["index"];
+    they are not special-cased on this class.
+
+    Attributes:
+        _storage: cpg2py Storage instance containing edge data.
+        _edge_id: Tuple of (from_id, to_id, edge_type).
+    """
+
+    def __init__(
+        self, graph: Storage, f_nid: str, t_nid: str, e_type: str = PARENT_OF_EDGE
+    ) -> None:
+        """Initialize Edge with storage and edge identifiers.
+
+        Args:
+            graph: cpg2py Storage containing the graph.
+            f_nid: From node ID.
+            t_nid: To node ID.
+            e_type: Edge type (default: "PARENT_OF").
+        """
+        super().__init__(graph, f_nid, t_nid, e_type)
+        self._storage = graph
+        self._edge_id = (str(f_nid), str(t_nid), str(e_type))
+
+    # Core properties
+
+    @property
+    def type(self) -> str:
+        """Return the edge type (e.g. "PARENT_OF")."""
+        return self._edge_id[2]
+
+    @property
+    def all_properties(self) -> dict[str, Any]:
+        """Return all edge properties.
+
+        Returns:
+            Dictionary of edge properties.
+        """
+        return self._storage.get_edge_props(self._edge_id) or {}
+
+    # Dict-like access methods
+
+    def __getitem__(self, key: str) -> Any:
+        """Access edge properties using dict-like syntax.
+
+        Enables edge["field"], edge["index"], etc.
+
+        Args:
+            key: Property name to access.
+
+        Returns:
+            Property value.
+
+        Raises:
+            KeyError: If property doesn't exist.
+        """
+        props = self.all_properties
+        if key not in props:
+            raise KeyError(f"Property '{key}' not found in edge {self._edge_id}")
+        return props[key]
+
+    def __contains__(self, key: str) -> bool:
+        """Check if property exists using 'in' operator.
+
+        Enables: if "index" in edge: ...
+
+        Args:
+            key: Property name to check.
+
+        Returns:
+            True if property exists, False otherwise.
+        """
+        return key in self.all_properties
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get property value with default fallback.
+
+        Args:
+            key: Property name to access.
+            default: Default value if property doesn't exist.
+
+        Returns:
+            Property value or default.
+        """
+        return self.all_properties.get(key, default)

php_parser_py/_graph/_modifier.py

@@ -0,0 +1,143 @@
+"""Modifier class for AST graph mutation operations."""
+
+from __future__ import annotations
+
+from .._types import PARENT_OF_EDGE
+from ._ast import AST
+from ._edge import Edge
+from ._node import Node
+
+
+class Modifier:
+    """Encapsulates all graph mutation operations for an AST.
+
+    The only approved way to add, remove, or structurally modify nodes and
+    edges in the AST graph. Callers must never use Storage directly.
+
+    AST (AbcGraphQuerier) is a query interface; graph mutation is a separate
+    concern handled by this class. Mutation is copy-on-write: the constructor
+    deep-copies the source AST, and every operation writes through the copy.
+    The source AST is never modified. Callers read mutations via the ``ast``
+    property, which exposes the modified copy.
+
+    Attributes:
+        _ast: The modified-copy AST, independent of the source.
+        _storage: The copy's internal Storage that operations write through.
+    """
+
+    def __init__(self, ast: AST) -> None:
+        """Deep-copy an AST so that mutation leaves the source unchanged.
+
+        Args:
+            ast: Source AST to copy. The instance is never modified.
+        """
+        self._ast = ast.copy()
+        self._storage = self._ast._graph
+
+    @property
+    def ast(self) -> AST:
+        """Return the modified-copy AST holding all mutations."""
+        return self._ast
+
+    # -- Node Operations --
+
+    def add_node(self, node_id: str, node_type: str, **props: object) -> Node:
+        """Create a new node in the graph with the given type and properties.
+
+        Args:
+            node_id: Unique node ID string.
+            node_type: PHP-Parser node type (e.g. "Stmt_Break").
+            **props: Additional node properties to set.
+
+        Returns:
+            Node instance for the newly created node.
+
+        Raises:
+            ValueError: If node_id already exists in the graph.
+        """
+        if self._storage.contains_node(node_id):
+            raise ValueError(f"Node already exists: {node_id!r}")
+
+        self._storage.add_node(node_id)
+        all_props: dict[str, object] = {"nodeType": node_type, **props}
+        self._storage.set_node_props(node_id, all_props)
+        return Node(self._storage, node_id)
+
+    def remove_node(self, node_id: str) -> None:
+        """Remove a node and all its connected edges from the graph.
+
+        Args:
+            node_id: Node ID to remove.
+
+        Raises:
+            KeyError: If node_id is not in the graph.
+        """
+        if not self._storage.contains_node(node_id):
+            raise KeyError(f"Node not found: {node_id!r}")
+        # Storage.remove_node drops only the removed node's adjacency list;
+        # remove_edge is the only API that also cleans the other endpoint.
+        incident = dict.fromkeys(
+            (*self._storage.in_edges(node_id), *self._storage.out_edges(node_id))
+        )
+        for edge_id in incident:
+            self._storage.remove_edge(edge_id)
+        self._storage.remove_node(node_id)
+
+    # -- Edge Operations --
+
+    def add_edge(
+        self,
+        from_id: str,
+        to_id: str,
+        edge_type: str = PARENT_OF_EDGE,
+        **props: object,
+    ) -> Edge:
+        """Create a new edge between two existing nodes.
+
+        Args:
+            from_id: Source node ID.
+            to_id: Target node ID.
+            edge_type: Edge type. Defaults to "PARENT_OF".
+            **props: Edge properties (e.g. field="stmts", index=0).
+
+        Returns:
+            Edge instance for the newly created edge.
+
+        Raises:
+            KeyError: If either node does not exist.
+            ValueError: If edge already exists.
+        """
+        if not self._storage.contains_node(from_id):
+            raise KeyError(f"Source node not found: {from_id!r}")
+        if not self._storage.contains_node(to_id):
+            raise KeyError(f"Target node not found: {to_id!r}")
+
+        edge_id = (from_id, to_id, edge_type)
+        if self._storage.contains_edge(edge_id):
+            raise ValueError(f"Edge already exists: {edge_id!r}")
+
+        self._storage.add_edge(edge_id)
+        if props:
+            self._storage.set_edge_props(edge_id, props)
+        return Edge(self._storage, from_id, to_id, edge_type)
+
+    def remove_edge(
+        self,
+        from_id: str,
+        to_id: str,
+        edge_type: str = PARENT_OF_EDGE,
+    ) -> None:
+        """Remove an edge from the graph.
+
+        Args:
+            from_id: Source node ID.
+            to_id: Target node ID.
+            edge_type: Edge type. Defaults to "PARENT_OF".
+
+        Raises:
+            KeyError: If edge is not in the graph.
+        """
+        edge_id = (from_id, to_id, edge_type)
+        if not self._storage.contains_edge(edge_id):
+            raise KeyError(f"Edge not found: {edge_id!r}")
+        self._storage.remove_edge(edge_id)