openscad-parser 1.0.1__tar.gz → 2.2.0__tar.gz

{openscad_parser-1.0.1 → openscad_parser-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscad_parser
-Version: 1.0.1
+Version: 2.2.0
 Summary: A PEG parser to read OpenSCAD language source code, with optional AST tree generation.
 Keywords: openscad,openscad parser,parser
 Author: Revar Desmera
@@ -21,9 +21,10 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: arpeggio>=2.0.3
 Requires-Dist: pytest>=7.0.0 ; extra == 'dev'
+Requires-Dist: pyyaml>=6.0 ; extra == 'yaml'
 Maintainer: Revar Desmera
 Maintainer-email: Revar Desmera <revarbat@gmail.com>
-Requires-Python: >=3.7
+Requires-Python: >=3.11
 Project-URL: Bug Tracker, https://github.com/belfryscad/openscad_parser/issues
 Project-URL: Documentation, https://github.com/belfryscad/openscad_parser/WRITING_DOCS.md
 Project-URL: Homepage, https://github.com/belfryscad/openscad_parser
@@ -31,6 +32,7 @@ Project-URL: Releases, https://github.com/belfryscad/openscad_parser/releases
 Project-URL: Repository, https://github.com/belfryscad/openscad_parser
 Project-URL: Usage, https://github.com/belfryscad/openscad_parser/README.rst
 Provides-Extra: dev
+Provides-Extra: yaml
 Description-Content-Type: text/x-rst
 
 OpenSCAD Parser
@@ -53,6 +55,7 @@ Features
 - Source position tracking for all AST nodes
 - AST tree can contain comment nodes (single-line and multi-line)
 - AST tree uses dataclasses and can be pickled/unpickled for caching/serialization
+- JSON and YAML serialization/deserialization of AST trees
 
 Installation
 ------------
@@ -145,6 +148,13 @@ Use ``getASTfromFile()`` to parse an OpenSCAD file. This function includes autom
 
 The cache is automatically invalidated when the file is modified, ensuring you always get up-to-date results.
 
+**Include Processing:** By default, ``getASTfromFile()`` processes ``include <file>`` statements before parsing (``process_includes=True``). This means the AST will NOT contain ``IncludeStatement`` nodes - instead, the included file contents are expanded into the AST. Set ``process_includes=False`` to preserve ``IncludeStatement`` nodes in the AST::
+
+    # Get AST with IncludeStatement nodes preserved
+    ast_with_includes = getASTfromFile("my_model.scad", process_includes=False)
+
+**Note:** Unlike ``include`` statements, ``use <file>`` statements are ALWAYS parsed into ``UseStatement`` AST nodes, regardless of the ``process_includes`` setting. This is because ``use`` statements only affect module and function lookup at runtime, not source inclusion.
+
 Parsing Library Files
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -466,27 +476,43 @@ Main Functions
     :returns: AST node or list of AST nodes (for top-level statements)
     :rtype: ASTNode | list[ASTNode] | None
 
-``getASTfromFile(file: str)``
+``getASTfromFile(file: str, include_comments: bool = False, process_includes: bool = True)``
     Parse an OpenSCAD source file and return its AST. Includes automatic caching
     that invalidates when the file's modification timestamp changes.
 
     :param file: The OpenSCAD source file to be parsed
+    :param include_comments: If True, include comments in the AST (default: False)
+    :param process_includes: If True, process include statements and replace with file contents (default: True).
+        When False, the AST will contain IncludeStatement nodes where includes appear.
     :returns: List of AST nodes (for top-level statements)
     :rtype: list[ASTNode] | None
     :raises FileNotFoundError: If the specified file does not exist
     :raises Exception: If there is an error while reading the file
 
-``getASTfromLibraryFile(currfile: str, libfile: str)``
+    **Note:** When ``process_includes=True`` (default), the AST will NOT contain ``IncludeStatement`` nodes
+    because includes are processed before parsing. When ``process_includes=False``, ``IncludeStatement``
+    nodes will appear in the AST where ``include <file>`` statements exist in the source code.
+    
+    Unlike ``include`` statements, ``use <file>`` statements are ALWAYS parsed into ``UseStatement``
+    AST nodes regardless of the ``process_includes`` setting, since ``use`` only affects runtime
+    lookup, not source inclusion.
+
+``getASTfromLibraryFile(currfile: str, libfile: str, include_comments: bool = False, process_includes: bool = True)``
     Find and parse an OpenSCAD library file using OpenSCAD's search path rules.
     Searches in: current file directory, OPENSCADPATH, and platform default paths.
 
     :param currfile: Full path to the current OpenSCAD file (can be empty string)
     :param libfile: Partial or full path to the library file to find
+    :param include_comments: If True, include comments in the AST (default: False)
+    :param process_includes: If True, process include statements (default: True).
+        When False, the AST will contain IncludeStatement nodes where includes appear.
     :returns: Tuple of (AST nodes list, absolute file path). The AST list is None if empty or not valid.
     :rtype: tuple[list[ASTNode] | None, str]
     :raises FileNotFoundError: If the library file cannot be found
     :raises Exception: If there is an error while reading or parsing the file
 
+    **Note:** The ``process_includes`` parameter affects the AST structure (see ``getASTfromFile`` documentation).
+
 ``parse_ast(parser, code, file="")``
     Parse OpenSCAD code and generate an AST (lower-level API).
 
@@ -501,6 +527,65 @@ Main Functions
 
     This function removes all cached AST trees from memory.
 
+Serialization Functions
+~~~~~~~~~~~~~~~~~~~~~~~
+
+``ast_to_dict(ast: ASTNode | Sequence[ASTNode] | None, include_position: bool = True)``
+    Convert an AST to a Python dictionary (JSON-serializable).
+
+    :param ast: An AST node, sequence of AST nodes, or None
+    :param include_position: If True, include source position information (default: True)
+    :returns: A dictionary representation of the AST, a list of dictionaries, or None
+    :rtype: dict[str, Any] | list[dict[str, Any]] | None
+
+``ast_to_json(ast: ASTNode | Sequence[ASTNode] | None, include_position: bool = True, indent: int | None = 2)``
+    Serialize an AST to a JSON string.
+
+    :param ast: An AST node, sequence of AST nodes, or None
+    :param include_position: If True, include source position information (default: True)
+    :param indent: Indentation level for pretty-printing. Use None for compact output (default: 2)
+    :returns: A JSON string representation of the AST
+    :rtype: str
+
+``ast_from_dict(data: dict[str, Any] | list[dict[str, Any]] | None)``
+    Reconstruct an AST from a Python dictionary.
+
+    :param data: A dictionary, list of dictionaries, or None (as returned by ast_to_dict)
+    :returns: An AST node, list of AST nodes, or None
+    :rtype: ASTNode | list[ASTNode] | None
+    :raises ValueError: If the data contains an unknown node type or is malformed
+
+``ast_from_json(json_str: str)``
+    Deserialize an AST from a JSON string.
+
+    :param json_str: A JSON string (as returned by ast_to_json)
+    :returns: An AST node, list of AST nodes, or None
+    :rtype: ASTNode | list[ASTNode] | None
+    :raises ValueError: If the JSON contains an unknown node type or is malformed
+    :raises json.JSONDecodeError: If the string is not valid JSON
+
+``ast_to_yaml(ast: ASTNode | Sequence[ASTNode] | None, include_position: bool = True)``
+    Serialize an AST to a YAML string.
+
+    Requires PyYAML to be installed: ``pip install openscad_parser[yaml]``
+
+    :param ast: An AST node, sequence of AST nodes, or None
+    :param include_position: If True, include source position information (default: True)
+    :returns: A YAML string representation of the AST
+    :rtype: str
+    :raises ImportError: If PyYAML is not installed
+
+``ast_from_yaml(yaml_str: str)``
+    Deserialize an AST from a YAML string.
+
+    Requires PyYAML to be installed: ``pip install openscad_parser[yaml]``
+
+    :param yaml_str: A YAML string (as returned by ast_to_yaml)
+    :returns: An AST node, list of AST nodes, or None
+    :rtype: ASTNode | list[ASTNode] | None
+    :raises ImportError: If PyYAML is not installed
+    :raises ValueError: If the YAML contains an unknown node type or is malformed
+
 AST Node Classes
 ~~~~~~~~~~~~~~~~
 
@@ -557,6 +642,95 @@ All AST nodes include source position information::
 
 The ``Position`` class provides lazy evaluation of line/column numbers from character positions.
 
+Serialization
+-------------
+
+AST trees can be serialized to JSON or YAML formats and deserialized back to AST nodes. This is useful for caching, storage, or transferring AST data between processes.
+
+JSON Serialization
+~~~~~~~~~~~~~~~~~~
+
+Serialize an AST to JSON::
+
+    from openscad_parser.ast import getASTfromString, ast_to_json, ast_from_json
+
+    # Parse code to AST
+    ast = getASTfromString("cube(10);")
+
+    # Serialize to JSON string
+    json_str = ast_to_json(ast, include_position=True, indent=2)
+
+    # Deserialize back to AST
+    ast_restored = ast_from_json(json_str)
+
+The ``ast_to_json()`` function accepts:
+- ``ast``: An AST node, sequence of AST nodes, or None
+- ``include_position``: If True, include source position information (default: True)
+- ``indent``: Indentation level for pretty-printing. Use None for compact output (default: 2)
+
+Dictionary Serialization
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also work with Python dictionaries directly::
+
+    from openscad_parser.ast import getASTfromString, ast_to_dict, ast_from_dict
+
+    ast = getASTfromString("x = 42;")
+
+    # Convert to dictionary
+    data = ast_to_dict(ast, include_position=True)
+
+    # Convert back to AST
+    ast_restored = ast_from_dict(data)
+
+YAML Serialization
+~~~~~~~~~~~~~~~~~~
+
+For YAML serialization, you need to install PyYAML::
+
+    pip install openscad_parser[yaml]
+
+Then serialize to YAML::
+
+    from openscad_parser.ast import getASTfromString, ast_to_yaml, ast_from_yaml
+
+    ast = getASTfromString("cube(10);")
+
+    # Serialize to YAML string
+    yaml_str = ast_to_yaml(ast, include_position=True)
+
+    # Deserialize back to AST
+    ast_restored = ast_from_yaml(yaml_str)
+
+The ``ast_to_yaml()`` function accepts:
+- ``ast``: An AST node, sequence of AST nodes, or None
+- ``include_position``: If True, include source position information (default: True)
+
+Serialization Functions
+~~~~~~~~~~~~~~~~~~~~~~~
+
+All serialization functions can be imported directly from ``openscad_parser.ast`` (recommended)::
+
+    from openscad_parser.ast import (
+        ast_to_dict,
+        ast_to_json,
+        ast_to_yaml,
+        ast_from_dict,
+        ast_from_json,
+        ast_from_yaml,
+    )
+
+They are also available from ``openscad_parser.ast.serialization``::
+
+    from openscad_parser.ast.serialization import (
+        ast_to_dict,
+        ast_to_json,
+        ast_to_yaml,
+        ast_from_dict,
+        ast_from_json,
+        ast_from_yaml,
+    )
+
 Error Handling
 --------------
 

{openscad_parser-1.0.1 → openscad_parser-2.2.0}/README.rst

@@ -18,6 +18,7 @@ Features
 - Source position tracking for all AST nodes
 - AST tree can contain comment nodes (single-line and multi-line)
 - AST tree uses dataclasses and can be pickled/unpickled for caching/serialization
+- JSON and YAML serialization/deserialization of AST trees
 
 Installation
 ------------
@@ -110,6 +111,13 @@ Use ``getASTfromFile()`` to parse an OpenSCAD file. This function includes autom
 
 The cache is automatically invalidated when the file is modified, ensuring you always get up-to-date results.
 
+**Include Processing:** By default, ``getASTfromFile()`` processes ``include <file>`` statements before parsing (``process_includes=True``). This means the AST will NOT contain ``IncludeStatement`` nodes - instead, the included file contents are expanded into the AST. Set ``process_includes=False`` to preserve ``IncludeStatement`` nodes in the AST::
+
+    # Get AST with IncludeStatement nodes preserved
+    ast_with_includes = getASTfromFile("my_model.scad", process_includes=False)
+
+**Note:** Unlike ``include`` statements, ``use <file>`` statements are ALWAYS parsed into ``UseStatement`` AST nodes, regardless of the ``process_includes`` setting. This is because ``use`` statements only affect module and function lookup at runtime, not source inclusion.
+
 Parsing Library Files
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -431,27 +439,43 @@ Main Functions
     :returns: AST node or list of AST nodes (for top-level statements)
     :rtype: ASTNode | list[ASTNode] | None
 
-``getASTfromFile(file: str)``
+``getASTfromFile(file: str, include_comments: bool = False, process_includes: bool = True)``
     Parse an OpenSCAD source file and return its AST. Includes automatic caching
     that invalidates when the file's modification timestamp changes.
 
     :param file: The OpenSCAD source file to be parsed
+    :param include_comments: If True, include comments in the AST (default: False)
+    :param process_includes: If True, process include statements and replace with file contents (default: True).
+        When False, the AST will contain IncludeStatement nodes where includes appear.
     :returns: List of AST nodes (for top-level statements)
     :rtype: list[ASTNode] | None
     :raises FileNotFoundError: If the specified file does not exist
     :raises Exception: If there is an error while reading the file
 
-``getASTfromLibraryFile(currfile: str, libfile: str)``
+    **Note:** When ``process_includes=True`` (default), the AST will NOT contain ``IncludeStatement`` nodes
+    because includes are processed before parsing. When ``process_includes=False``, ``IncludeStatement``
+    nodes will appear in the AST where ``include <file>`` statements exist in the source code.
+    
+    Unlike ``include`` statements, ``use <file>`` statements are ALWAYS parsed into ``UseStatement``
+    AST nodes regardless of the ``process_includes`` setting, since ``use`` only affects runtime
+    lookup, not source inclusion.
+
+``getASTfromLibraryFile(currfile: str, libfile: str, include_comments: bool = False, process_includes: bool = True)``
     Find and parse an OpenSCAD library file using OpenSCAD's search path rules.
     Searches in: current file directory, OPENSCADPATH, and platform default paths.
 
     :param currfile: Full path to the current OpenSCAD file (can be empty string)
     :param libfile: Partial or full path to the library file to find
+    :param include_comments: If True, include comments in the AST (default: False)
+    :param process_includes: If True, process include statements (default: True).
+        When False, the AST will contain IncludeStatement nodes where includes appear.
     :returns: Tuple of (AST nodes list, absolute file path). The AST list is None if empty or not valid.
     :rtype: tuple[list[ASTNode] | None, str]
     :raises FileNotFoundError: If the library file cannot be found
     :raises Exception: If there is an error while reading or parsing the file
 
+    **Note:** The ``process_includes`` parameter affects the AST structure (see ``getASTfromFile`` documentation).
+
 ``parse_ast(parser, code, file="")``
     Parse OpenSCAD code and generate an AST (lower-level API).
 
@@ -466,6 +490,65 @@ Main Functions
 
     This function removes all cached AST trees from memory.
 
+Serialization Functions
+~~~~~~~~~~~~~~~~~~~~~~~
+
+``ast_to_dict(ast: ASTNode | Sequence[ASTNode] | None, include_position: bool = True)``
+    Convert an AST to a Python dictionary (JSON-serializable).
+
+    :param ast: An AST node, sequence of AST nodes, or None
+    :param include_position: If True, include source position information (default: True)
+    :returns: A dictionary representation of the AST, a list of dictionaries, or None
+    :rtype: dict[str, Any] | list[dict[str, Any]] | None
+
+``ast_to_json(ast: ASTNode | Sequence[ASTNode] | None, include_position: bool = True, indent: int | None = 2)``
+    Serialize an AST to a JSON string.
+
+    :param ast: An AST node, sequence of AST nodes, or None
+    :param include_position: If True, include source position information (default: True)
+    :param indent: Indentation level for pretty-printing. Use None for compact output (default: 2)
+    :returns: A JSON string representation of the AST
+    :rtype: str
+
+``ast_from_dict(data: dict[str, Any] | list[dict[str, Any]] | None)``
+    Reconstruct an AST from a Python dictionary.
+
+    :param data: A dictionary, list of dictionaries, or None (as returned by ast_to_dict)
+    :returns: An AST node, list of AST nodes, or None
+    :rtype: ASTNode | list[ASTNode] | None
+    :raises ValueError: If the data contains an unknown node type or is malformed
+
+``ast_from_json(json_str: str)``
+    Deserialize an AST from a JSON string.
+
+    :param json_str: A JSON string (as returned by ast_to_json)
+    :returns: An AST node, list of AST nodes, or None
+    :rtype: ASTNode | list[ASTNode] | None
+    :raises ValueError: If the JSON contains an unknown node type or is malformed
+    :raises json.JSONDecodeError: If the string is not valid JSON
+
+``ast_to_yaml(ast: ASTNode | Sequence[ASTNode] | None, include_position: bool = True)``
+    Serialize an AST to a YAML string.
+
+    Requires PyYAML to be installed: ``pip install openscad_parser[yaml]``
+
+    :param ast: An AST node, sequence of AST nodes, or None
+    :param include_position: If True, include source position information (default: True)
+    :returns: A YAML string representation of the AST
+    :rtype: str
+    :raises ImportError: If PyYAML is not installed
+
+``ast_from_yaml(yaml_str: str)``
+    Deserialize an AST from a YAML string.
+
+    Requires PyYAML to be installed: ``pip install openscad_parser[yaml]``
+
+    :param yaml_str: A YAML string (as returned by ast_to_yaml)
+    :returns: An AST node, list of AST nodes, or None
+    :rtype: ASTNode | list[ASTNode] | None
+    :raises ImportError: If PyYAML is not installed
+    :raises ValueError: If the YAML contains an unknown node type or is malformed
+
 AST Node Classes
 ~~~~~~~~~~~~~~~~
 
@@ -522,6 +605,95 @@ All AST nodes include source position information::
 
 The ``Position`` class provides lazy evaluation of line/column numbers from character positions.
 
+Serialization
+-------------
+
+AST trees can be serialized to JSON or YAML formats and deserialized back to AST nodes. This is useful for caching, storage, or transferring AST data between processes.
+
+JSON Serialization
+~~~~~~~~~~~~~~~~~~
+
+Serialize an AST to JSON::
+
+    from openscad_parser.ast import getASTfromString, ast_to_json, ast_from_json
+
+    # Parse code to AST
+    ast = getASTfromString("cube(10);")
+
+    # Serialize to JSON string
+    json_str = ast_to_json(ast, include_position=True, indent=2)
+
+    # Deserialize back to AST
+    ast_restored = ast_from_json(json_str)
+
+The ``ast_to_json()`` function accepts:
+- ``ast``: An AST node, sequence of AST nodes, or None
+- ``include_position``: If True, include source position information (default: True)
+- ``indent``: Indentation level for pretty-printing. Use None for compact output (default: 2)
+
+Dictionary Serialization
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also work with Python dictionaries directly::
+
+    from openscad_parser.ast import getASTfromString, ast_to_dict, ast_from_dict
+
+    ast = getASTfromString("x = 42;")
+
+    # Convert to dictionary
+    data = ast_to_dict(ast, include_position=True)
+
+    # Convert back to AST
+    ast_restored = ast_from_dict(data)
+
+YAML Serialization
+~~~~~~~~~~~~~~~~~~
+
+For YAML serialization, you need to install PyYAML::
+
+    pip install openscad_parser[yaml]
+
+Then serialize to YAML::
+
+    from openscad_parser.ast import getASTfromString, ast_to_yaml, ast_from_yaml
+
+    ast = getASTfromString("cube(10);")
+
+    # Serialize to YAML string
+    yaml_str = ast_to_yaml(ast, include_position=True)
+
+    # Deserialize back to AST
+    ast_restored = ast_from_yaml(yaml_str)
+
+The ``ast_to_yaml()`` function accepts:
+- ``ast``: An AST node, sequence of AST nodes, or None
+- ``include_position``: If True, include source position information (default: True)
+
+Serialization Functions
+~~~~~~~~~~~~~~~~~~~~~~~
+
+All serialization functions can be imported directly from ``openscad_parser.ast`` (recommended)::
+
+    from openscad_parser.ast import (
+        ast_to_dict,
+        ast_to_json,
+        ast_to_yaml,
+        ast_from_dict,
+        ast_from_json,
+        ast_from_yaml,
+    )
+
+They are also available from ``openscad_parser.ast.serialization``::
+
+    from openscad_parser.ast.serialization import (
+        ast_to_dict,
+        ast_to_json,
+        ast_to_yaml,
+        ast_from_dict,
+        ast_from_json,
+        ast_from_yaml,
+    )
+
 Error Handling
 --------------
 

{openscad_parser-1.0.1 → openscad_parser-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "openscad_parser"
-version = "1.0.1"
+version = "2.2.0"
 description = "A PEG parser to read OpenSCAD language source code, with optional AST tree generation."
 readme = "README.rst"
 authors = [
@@ -14,7 +14,7 @@ maintainers = [
   { name="Revar Desmera", email="revarbat@gmail.com" },
 ]
 license = "MIT"
-requires-python = ">=3.7"
+requires-python = ">=3.11"
 classifiers = [
     "Development Status :: 4 - Beta",
     "Environment :: Console",
@@ -39,6 +39,9 @@ dependencies = [
 dev = [
     "pytest>=7.0.0",
 ]
+yaml = [
+    "PyYAML>=6.0",
+]
 
 [project.urls]
 "Homepage" = "https://github.com/belfryscad/openscad_parser"

openscad_parser-2.2.0/src/openscad_parser/__init__.py

@@ -0,0 +1,38 @@
+#######################################################################
+# Arpeggio PEG Grammar for OpenSCAD
+#######################################################################
+
+from __future__ import unicode_literals
+
+from arpeggio import ParserPython
+from .grammar import openscad_language, openscad_language_with_comments, comment, whitespace_only
+
+
+# --- The parser ---
+
+def getOpenSCADParser(reduce_tree=False, debug=False, include_comments=False):
+    """Create an OpenSCAD parser instance.
+    
+    Args:
+        reduce_tree: If True, reduce the parse tree (default: False)
+        debug: If True, enable debug output (default: False)
+        include_comments: If True, include comments in the AST instead of skipping them (default: False)
+    
+    Returns:
+        ParserPython instance configured for OpenSCAD parsing
+    """
+    if include_comments:
+        # When including comments, use whitespace-only rule and include comments in grammar
+        return ParserPython(
+            openscad_language_with_comments, whitespace_only, reduce_tree=reduce_tree,
+            memoization=True, autokwd=True, debug=debug
+        )
+    else:
+        # Default behavior: comments are skipped as whitespace
+        return ParserPython(
+            openscad_language, comment, reduce_tree=reduce_tree,
+            memoization=True, autokwd=True, debug=debug
+        )
+
+
+# vim: set ts=4 sw=4 expandtab: