vex-ast 0.1.0__tar.gz → 0.2.1__tar.gz

vex_ast-0.2.1/LICENSE

@@ -0,0 +1 @@
+HX2's Vex AST © 2025 by charkwayteowy is licensed under CC BY-NC 4.0

vex_ast-0.2.1/MANIFEST.in

@@ -0,0 +1,20 @@
+include LICENSE
+include README.md
+include requirements.txt
+include pytest.ini
+include pyproject.toml
+
+# Include all documentation files
+recursive-include vex_ast *README.md
+recursive-include vex_ast *READMEAPI.md
+
+# Include test files
+recursive-include tests *.py
+
+# Exclude cache files
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *.so
+global-exclude .DS_Store
+global-exclude .env
+global-exclude .coverage

{vex_ast-0.1.0 → vex_ast-0.2.1}/PKG-INFO

@@ -1,13 +1,14 @@
 Metadata-Version: 2.4
 Name: vex_ast
-Version: 0.1.0
+Version: 0.2.1
 Summary: A Python package for generating Abstract Syntax Trees for VEX V5 code.
-Home-page: https://github.com/teowy/vex_ast
+Home-page: https://github.com/heartx2/vex_ast
 Author: Chaze
-Author-email: chazelexander@example.com
+Author-email: Chaze <chazelexander@gmail.com>
+License: HX2's Vex AST © 2025 by charkwayteowy is licensed under CC BY-NC 4.0
+Project-URL: Repository, https://github.com/heartx2/vex_ast
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
@@ -17,14 +18,11 @@ Classifier: Topic :: Software Development :: Compilers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: license-file
 Dynamic: requires-python
-Dynamic: summary
 
 # VEX AST Generator
 
@@ -60,7 +58,7 @@ The core library is within the `vex_ast` directory:
 
 1.  **Clone the repository:**
     ```bash
-    git clone https://github.com/yourusername/vex_ast.git # Replace with actual URL
+    git clone https://github.com/heartx2/vex_ast # Replace with actual URL
     cd vex_ast
     ```
 
@@ -173,4 +171,4 @@ Contributions are welcome! Please follow the established coding standards and en
 
 ## License
 
-This project is licensed under the MIT License - see the LICENSE file for details (You'll need to add a LICENSE file).
+HX2's Vex AST © 2025 by charkwayteowy is licensed under CC BY-NC 4.0

{vex_ast-0.1.0 → vex_ast-0.2.1}/README.md

@@ -32,7 +32,7 @@ The core library is within the `vex_ast` directory:
 
 1.  **Clone the repository:**
     ```bash
-    git clone https://github.com/yourusername/vex_ast.git # Replace with actual URL
+    git clone https://github.com/heartx2/vex_ast # Replace with actual URL
     cd vex_ast
     ```
 
@@ -145,4 +145,4 @@ Contributions are welcome! Please follow the established coding standards and en
 
 ## License
 
-This project is licensed under the MIT License - see the LICENSE file for details (You'll need to add a LICENSE file).
+HX2's Vex AST © 2025 by charkwayteowy is licensed under CC BY-NC 4.0

vex_ast-0.2.1/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vex_ast"
+version = "0.2.1"
+description = "A Python package for generating Abstract Syntax Trees for VEX V5 code."
+readme = "README.md"
+authors = [
+    {name = "Chaze", email = "chazelexander@gmail.com"},
+]
+license = {file = "LICENSE"}
+requires-python = ">=3.8"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Compilers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Repository = "https://github.com/heartx2/vex_ast"  # Replace with actual URL

vex_ast-0.2.1/pytest.ini

@@ -0,0 +1,8 @@
+[pytest]
+minversion = 6.0
+testpaths = tests
+python_files = test_*.py
+addopts = 
+# You can add markers here later, e.g.,
+# markers =
+#     slow: marks tests as slow (deselect with '-m "not slow"')

vex_ast-0.2.1/requirements.txt

@@ -0,0 +1,5 @@
+pytest
+pytest-cov
+mypy
+black
+flake8

{vex_ast-0.1.0 → vex_ast-0.2.1}/setup.py

@@ -2,21 +2,17 @@ from setuptools import setup, find_packages
 
 setup(
     name='vex_ast',
-    version='0.1.0',
+    version='0.2.1',
     description='A Python package for generating Abstract Syntax Trees for VEX V5 code.',
     long_description=open('README.md').read(),
     long_description_content_type='text/markdown',
-    author='Chaze',  # Replace with your actual name
-    author_email='chazelexander@example.com',  # Replace with your actual email
-    url='https://github.com/teowy/vex_ast',  # Replace with your actual repository URL
-    packages=find_packages(exclude=['tests*']),
-    install_requires=[
-        # Add runtime dependencies here if any
-    ],
+    author='Chaze',
+    author_email='chazelexander@gmail.com',
+    url='https://github.com/heartx2/vex_ast',
+    packages=find_packages(),
     classifiers=[
         'Development Status :: 3 - Alpha',
         'Intended Audience :: Developers',
-        'License :: OSI Approved :: MIT License',
         'Programming Language :: Python :: 3',
         'Programming Language :: Python :: 3.8',
         'Programming Language :: Python :: 3.9',

vex_ast-0.2.1/tests/conftest.py

@@ -0,0 +1,11 @@
+# tests/conftest.py
+import os
+import sys
+import pytest
+
+# Get the absolute path to the project root directory
+project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
+
+# Add the project root to the Python path if it's not already there
+if project_root not in sys.path:
+    sys.path.insert(0, project_root)

vex_ast-0.2.1/vex_ast/README.md

@@ -0,0 +1,51 @@
+VEX AST Package (vex_ast)
+
+This directory is the root of the vex_ast Python package. It orchestrates the different components of the VEX AST generation and processing system.
+
+Purpose
+
+The vex_ast package provides a unified interface for parsing VEX V5 Python code into an Abstract Syntax Tree (AST) and tools for working with that AST.
+
+Structure
+
+The package is organized into several sub-packages:
+
+ast/: Contains the definitions for all AST node types, representing the structure of the parsed code. See vex_ast/ast/README.md.
+
+parser/: Includes the parsing logic responsible for converting source code text into an AST instance. See vex_ast/parser/README.md.
+
+visitors/: Provides implementations of the Visitor pattern for traversing, analyzing, or transforming the AST. See vex_ast/visitors/README.md.
+
+utils/: Contains utility classes and functions, primarily for error handling and source location tracking. See vex_ast/utils/README.md.
+
+Core Exports
+
+The main components are exposed through the vex_ast/__init__.py file, making them easily accessible:
+
+parse_string(source, ...): Parses Python code from a string.
+
+parse_file(filepath, ...): Parses Python code from a file.
+
+Program: The root node type of the generated AST.
+
+PrintVisitor: A visitor to generate a string representation of the AST.
+
+NodeCounter: A visitor to count nodes in the AST.
+
+VariableCollector: A visitor to collect variable names used in the AST.
+
+ErrorHandler: Class for managing errors during parsing and processing.
+
+VexSyntaxError, VexAstError: Custom exception types.
+
+Workflow
+
+The typical workflow involves:
+
+Using parse_string or parse_file from this package to generate an AST (Program object) from source code.
+
+Instantiating one or more visitors from vex_ast.visitors (or custom ones).
+
+Calling the visit method of the visitor with the root Program node to perform analysis, transformation, or other operations on the AST.
+
+Using the ErrorHandler to manage and inspect any errors encountered during the process.

vex_ast-0.2.1/vex_ast/READMEAPI.md

@@ -0,0 +1,318 @@
+# VEX AST (`vex_ast`) - Public API Reference
+
+This document describes the main functions and classes exposed by the `vex_ast` package, intended for users who want to parse VEX V5 Python code and interact with the resulting Abstract Syntax Tree (AST).
+
+## Overview
+
+The core workflow typically involves:
+
+1.  Parsing source code (from a string or file) using `parse_string` or `parse_file`. This requires an optional `ErrorHandler` instance.
+2.  Receiving a `Program` object, which is the root of the generated AST.
+3.  Instantiating one or more `AstVisitor` subclasses (like `PrintVisitor`, `NodeCounter`, `VariableCollector`, or custom ones).
+4.  Calling the visitor's `visit()` method with the `Program` node to traverse the AST and perform actions.
+5.  Checking the `ErrorHandler` instance for any reported errors during parsing or visiting.
+
+---
+
+## Parsing Functions
+
+These functions are the entry points for converting source code into an AST.
+
+### `parse_string`
+
+Parses VEX V5 Python code provided as a string.
+
+**Signature:**
+
+```python
+def parse_string(
+    source: str,
+    filename: str = "<string>",
+    error_handler: Optional[ErrorHandler] = None
+) -> Program:
+
+
+Arguments:
+
+source (str): The string containing the Python code to parse.
+
+filename (str, optional): The name to associate with the source code, used in error messages and source locations. Defaults to "<string>".
+
+error_handler (Optional[ErrorHandler], optional): An instance of ErrorHandler to collect parsing errors. If None, a default ErrorHandler is created internally (which will raise VexSyntaxError on the first syntax error). It's recommended to provide your own handler to manage errors more flexibly.
+
+Returns:
+
+Program: The root node of the generated Abstract Syntax Tree.
+
+Raises:
+
+VexSyntaxError: If a syntax error is encountered during parsing and the error_handler is configured to raise errors immediately (or if no handler is provided).
+
+VexAstError: For other internal parsing or AST conversion issues if the error_handler is configured to raise errors.
+
+parse_file
+
+Parses VEX V5 Python code read from a specified file.
+
+Signature:
+
+def parse_file(
+    filepath: str,
+    error_handler: Optional[ErrorHandler] = None
+) -> Program:
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+
+Arguments:
+
+filepath (str): The path to the Python file to be parsed.
+
+error_handler (Optional[ErrorHandler], optional): An instance of ErrorHandler to collect parsing errors. See parse_string for details.
+
+Returns:
+
+Program: The root node of the generated Abstract Syntax Tree.
+
+Raises:
+
+FileNotFoundError: If the specified filepath does not exist.
+
+IOError: If there is an error reading the file.
+
+VexSyntaxError: If a syntax error is encountered (see parse_string).
+
+VexAstError: For other internal parsing errors (see parse_string).
+
+Core AST Node
+Program
+
+Represents the root node of the entire Abstract Syntax Tree.
+
+Description:
+
+The Program node is the object returned by parse_string and parse_file. It serves as the entry point for traversing the AST using visitors.
+
+Key Attribute:
+
+body (List[IStatement]): A list containing the top-level statements (like function definitions, assignments, expression statements) found in the parsed code.
+
+Usage:
+
+You typically don't instantiate Program directly. You receive it from a parsing function and pass it to the visit() method of an AstVisitor.
+
+ast_root: Program = parse_string("x = 1")
+printer = PrintVisitor()
+printer.visit(ast_root) # Pass the Program node to the visitor
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+Standard Visitors
+
+Visitors provide mechanisms to traverse and process the AST. You instantiate a visitor and then call its visit method on an AST node (usually the Program root).
+
+PrintVisitor
+
+Generates a formatted, indented string representation of the AST structure. Useful for debugging and inspection.
+
+Instantiation:
+
+printer = PrintVisitor()
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+
+Core Method:
+
+visit(node: IAstNode) -> str: Traverses the AST starting from node (typically the Program root) and returns a multi-line string representing the tree.
+
+Example:
+
+ast_root = parse_string("y = a + 5")
+visitor = PrintVisitor()
+ast_string_representation = visitor.visit(ast_root)
+print(ast_string_representation)
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+NodeCounter
+
+Counts the number of nodes in the AST.
+
+Instantiation:
+
+counter = NodeCounter()
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+
+Core Method:
+
+visit(node: IAstNode) -> int: Traverses the AST starting from node and returns the total count of nodes visited.
+
+Additional Attribute:
+
+counts_by_type (Dict[str, int]): After calling visit, this dictionary holds the counts for each specific node type encountered (e.g., {'Assignment': 1, 'BinaryOperation': 1, ...}).
+
+Example:
+
+ast_root = parse_string("def f():\n  return 10")
+visitor = NodeCounter()
+total_nodes = visitor.visit(ast_root)
+print(f"Total nodes: {total_nodes}")
+print(f"Nodes by type: {visitor.counts_by_type}")
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+VariableCollector
+
+Collects the names of all variables referenced (read from) in the AST. Does not include variables only assigned to or function/class names being defined.
+
+Instantiation:
+
+collector = VariableCollector()
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+
+Core Method:
+
+visit(node: IAstNode) -> Set[str]: Traverses the AST starting from node and returns a set containing the names of all referenced variables (identifiers used in a Load context).
+
+Example:
+
+code = """
+x = 10
+y = x + z
+def my_func(p):
+    q = p
+"""
+ast_root = parse_string(code)
+visitor = VariableCollector()
+referenced_vars = visitor.visit(ast_root)
+print(f"Referenced variables: {referenced_vars}") # Output: {'x', 'z', 'p'}
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+Error Handling
+
+Components for managing and reporting errors during parsing and processing.
+
+ErrorHandler
+
+Manages the collection and reporting of errors.
+
+Instantiation:
+
+# Option 1: Collect errors, don't raise exceptions immediately
+handler = ErrorHandler(raise_on_error=False)
+
+# Option 2: Raise VexSyntaxError/VexAstError on the first error
+handler = ErrorHandler(raise_on_error=True) # Default behavior if omitted
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+
+Key Methods:
+
+get_errors() -> List[Error]: Returns a list of all Error objects collected so far.
+
+has_errors() -> bool: Returns True if any errors have been collected, False otherwise. Useful after parsing with raise_on_error=False.
+
+clear_errors() -> None: Removes all collected errors.
+
+add_observer(observer: ErrorObserver) -> None: (Advanced) Registers a custom object to be notified whenever an error is added.
+
+remove_observer(observer: ErrorObserver) -> None: (Advanced) Unregisters an observer.
+
+Usage:
+
+Typically, you create an ErrorHandler instance and pass it to parse_string or parse_file.
+
+error_handler = ErrorHandler(raise_on_error=False)
+try:
+    ast = parse_string("x = 1 + ", error_handler=error_handler)
+    if error_handler.has_errors():
+        print("Parsing completed with non-fatal errors:")
+        for err in error_handler.get_errors():
+            print(f"- {err}")
+    else:
+        print("Parsing successful.")
+        # Proceed with AST processing...
+except VexAstError as e:
+     # This shouldn't happen if raise_on_error=False, but good practice
+     print(f"Unexpected VexAstError: {e}")
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+ErrorType
+
+An Enum used within Error objects to categorize the type of error.
+
+Values:
+
+LEXER_ERROR
+
+PARSER_ERROR
+
+TYPE_ERROR
+
+SEMANTIC_ERROR
+
+INTERNAL_ERROR
+
+Usage:
+
+You typically check the error_type attribute of Error objects retrieved from ErrorHandler.get_errors().
+
+VexSyntaxError
+
+Exception raised specifically for syntax errors encountered during parsing when the ErrorHandler is configured to raise errors.
+
+Inheritance: VexSyntaxError -> VexAstError -> Exception
+
+Attribute:
+
+location (Optional[SourceLocation]): May contain the location (line, column) where the syntax error occurred.
+
+VexAstError
+
+The base exception class for all errors originating from the vex_ast library. VexSyntaxError is a subclass.
+
+This reference covers the main components needed to use the vex_ast library effectively for parsing and basic AST interaction. For more advanced use cases, you might need to delve into the specific AST node types in vex_ast.ast or create custom visitors inheriting from vex_ast.visitors.AstVisitor.
+
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+IGNORE_WHEN_COPYING_END

{vex_ast-0.1.0 → vex_ast-0.2.1}/vex_ast/__init__.py

@@ -4,13 +4,25 @@ VEX AST Generator Package.
 Provides tools for parsing VEX V5 code and generating an Abstract Syntax Tree (AST).
 """
 
+# Core functionality
 from .ast.core import Program
-from .ast.navigator import AstNavigator
 from .parser.python_parser import parse_string, parse_file
+
+# AST Navigation
+from .ast.navigator import AstNavigator, create_navigator
+
+# Visitors
 from .visitors.printer import PrintVisitor
 from .visitors.analyzer import NodeCounter, VariableCollector
-from .utils.errors import ErrorHandler, ErrorType, VexSyntaxError
-from .registry import registry_api, initialize as initialize_registry
+
+# Error handling
+from .utils.errors import ErrorHandler, ErrorType, VexSyntaxError, VexAstError, Error
+
+# Registry
+from .registry.api import registry_api
+from .registry import initialize
+
+# Serialization
 from .serialization.json_serializer import serialize_ast_to_dict, serialize_ast_to_json
 from .serialization.json_deserializer import deserialize_ast_from_dict, deserialize_ast_from_json
 from .serialization.schema import generate_ast_schema, export_schema_to_file
@@ -18,18 +30,7 @@ from .serialization.schema import generate_ast_schema, export_schema_to_file
 __version__ = "0.2.0"
 
 # Initialize the registry with default functions
-initialize_registry()
-
-def create_navigator(ast: Program) -> AstNavigator:
-    """Create an AST navigator for the given AST.
-    
-    Args:
-        ast: The AST to navigate
-        
-    Returns:
-        An AST navigator for traversing and querying the AST
-    """
-    return AstNavigator(ast)
+initialize()
 
 __all__ = [
     # Core functionality
@@ -50,10 +51,12 @@ __all__ = [
     "ErrorHandler",
     "ErrorType",
     "VexSyntaxError",
+    "VexAstError",
+    "Error",
     
     # Registry
     "registry_api",
-    "initialize_registry",
+    "initialize",
     
     # Serialization
     "serialize_ast_to_dict",
@@ -62,4 +65,4 @@ __all__ = [
     "deserialize_ast_from_json",
     "generate_ast_schema",
     "export_schema_to_file"
-]
+]