astToolkit 0.1.2__tar.gz → 0.1.3__tar.gz

asttoolkit-0.1.3/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: astToolkit
+Version: 0.1.3
+Summary: AST manipulation and transformation tools for Python code
+Author-email: Hunter Hogan <HunterHogan@pm.me>
+License: CC-BY-NC-4.0
+Project-URL: Donate, https://www.patreon.com/integrated
+Project-URL: Homepage, https://github.com/hunterhogan/astToolkit
+Project-URL: Issues, https://github.com/hunterhogan/astToolkit/issues
+Project-URL: Repository, https://github.com/hunterhogan/astToolkit.git
+Keywords: ast,abstract syntax tree,code generation,code transformation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: autoflake
+Requires-Dist: python_minifier
+Requires-Dist: tomli
+Requires-Dist: Z0Z_tools
+Provides-Extra: testing
+Requires-Dist: mypy; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: pytest-cov; extra == "testing"
+Requires-Dist: pytest-xdist; extra == "testing"
+Requires-Dist: pyupgrade; extra == "testing"
+Requires-Dist: trove_classifiers; extra == "testing"
+Dynamic: license-file
+
+# astToolkit
+
+## Do You Want This Package?
+
+astToolkit provides a powerfully composable system for manipulating Python Abstract Syntax Trees. Use it when:
+
+- You need to programmatically analyze, transform, or generate Python code.
+- You want type-safe operations that help prevent AST manipulation errors.
+- You prefer working with a consistent, fluent API rather than raw AST nodes.
+- You desire the ability to compose complex AST transformations from simple, reusable parts.
+
+Don't use it for simple text-based code manipulation—use regex or string operations instead.
+
+## Usage
+
+### Core Atomic Operations
+
+astToolkit provides four core classes that perform "atomic" operations on every AST class and attribute:
+
+```python
+from astToolkit import Be, DOT, Grab, Make
+import ast
+
+# Create an AST node
+node = Make.Name("example")
+
+print(f"{ast.dump(node) = }\n")
+
+# Access node properties safely with type checking
+myNameDOTidIs = DOT.id(node)
+
+print(f"{myNameDOTidIs = }\n")
+
+# Check node type with type guard functions
+CallNode = Make.Call(node)
+print(f"{ast.dump(CallNode) = }\n")
+
+print(f"{Be.Name(CallNode) = }")
+print(f"{Be.Name(node) = }")
+
+print(f"{Be.Call(CallNode) = }\n{Be.Name(DOT.func(CallNode)) = }\n")
+
+# Transform node attributes while preserving structure
+action = lambda idValue: f"modified_{idValue}"
+doThis = Grab.idAttribute(action)
+nodeAfterAction = doThis(node)
+print(f"{ast.dump(node) = }")
+```
+
+### AST Traversal and Transformation
+
+The real power lies in composable traversal and transformation using `NodeTourist` and `NodeChanger`:
+
+```python
+
+"""
+The AI assistant's example was stupid and wrong. I'm too sick right
+now to make a better one.
+"""
+
+```
+
+### Extending `IfThis` and `Then` Classes
+
+Extend these classes to create custom predicate and action functions:
+
+```python
+from astToolkit import ast_Identifier, Be, IfThis as astToolkit_IfThis
+from collections.abc import Callable
+from typing import Any, TypeGuard
+import ast
+
+class IfThis(astToolkit_IfThis):
+  @staticmethod
+  def isAttributeNamespace_IdentifierGreaterThan0(
+      namespace: ast_Identifier,
+      identifier: ast_Identifier
+      ) -> Callable[[ast.AST], TypeGuard[ast.Compare] | bool]:
+
+    return lambda node: (
+        Be.Compare(node)
+        and IfThis.isAttributeNamespace_Identifier(namespace, identifier)(node.left)
+        and Be.Gt(node.ops[0])
+        and IfThis.isConstant_value(0)(node.comparators[0]))
+
+  @staticmethod
+  def isIfAttributeNamespace_IdentifierGreaterThan0(
+      namespace: ast_Identifier,
+      identifier: ast_Identifier
+      ) -> Callable[[ast.AST], TypeGuard[ast.If] | bool]:
+
+    return lambda node: (
+        Be.If(node)
+        and IfThis.isAttributeNamespace_IdentifierGreaterThan0(namespace, identifier)(node.test))
+
+  @staticmethod
+  def isWhileAttributeNamespace_IdentifierGreaterThan0(
+      namespace: ast_Identifier,
+      identifier: ast_Identifier
+      ) -> Callable[[ast.AST], TypeGuard[ast.While] | bool]:
+
+    return lambda node: (
+        Be.While(node)
+        and IfThis.isAttributeNamespace_IdentifierGreaterThan0(namespace, identifier)(node.test))
+
+  # Or, make the comparison value a parameter
+  @staticmethod
+  def isAttributeNamespace_IdentifierGreaterThanThis(
+      namespace: ast_Identifier,
+      identifier: ast_Identifier,
+      value: Any
+      ) -> Callable[[ast.AST], TypeGuard[ast.Compare] | bool]:
+
+    return lambda node: (
+        Be.Compare(node)
+        and IfThis.isAttributeNamespace_Identifier(namespace, identifier)(node.left)
+        and Be.Gt(node.ops[0])
+        and IfThis.isConstant_value(value)(node.comparators[0]))
+```
+
+### Easy-to-use Tools for Annoying Tasks
+
+- extractClassDef
+- extractFunctionDef
+- parseLogicalPath2astModule
+- parsePathFilename2astModule
+
+### Easy-to-use Tools for More Complicated Tasks
+
+- removeUnusedParameters
+- write_astModule
+
+### The `toolFactory`
+
+Hypothetically, you could customize every aspect of the classes `Be`, `DOT`, `GRAB`, and `Make` and more than 100 `TypeAlias` in the toolFactory directory/package.
+
+## Installation
+
+```bash
+pip install astToolkit
+```
+
+## Technical Details
+
+### Architecture
+
+astToolkit implements a layered architecture designed for composability and type safety:
+
+1. **Core "Atomic" Classes** - The foundation of the system:
+   - `Be`: Type guards that return `TypeGuard[ast.NodeType]` for safe type narrowing.
+   - `DOT`: Read-only accessors that retrieve node attributes with proper typing.
+   - `Grab`: Transformation functions that modify specific attributes while preserving node structure.
+   - `Make`: Factory methods that create properly configured AST nodes with consistent interfaces.
+
+2. **Traversal and Transformation** - Built on the visitor pattern:
+   - `NodeTourist`: Extends `ast.NodeVisitor` to extract information from nodes that match predicates.
+   - `NodeChanger`: Extends `ast.NodeTransformer` to selectively transform nodes that match predicates.
+
+3. **Composable APIs** - The predicate-action pattern:
+   - `IfThis`: Generates predicate functions that identify nodes based on structure, content, or relationships.
+   - `Then`: Creates action functions that specify what to do with matched nodes (extract, replace, modify).
+
+4. **Higher-level Tools** - Built from the core components:
+   - `_toolkitAST.py`: Functions for common operations like extracting function definitions or importing modules.
+   - `transformationTools.py`: Advanced utilities like function inlining and code generation.
+   - `IngredientsFunction` and `IngredientsModule`: Containers for holding AST components and their dependencies.
+
+5. **Type System** - Over 120 specialized types for AST components:
+   - Custom type annotations for AST node attributes.
+   - Union types that accurately model Python's AST structure.
+   - Type guards that enable static type checkers to understand dynamic type narrowing.
+
+## My Recovery
+
+[![Static Badge](https://img.shields.io/badge/2011_August-Homeless_since-blue?style=flat)](https://HunterThinks.com/support)
+[![YouTube Channel Subscribers](https://img.shields.io/youtube/channel/subscribers/UC3Gx7kz61009NbhpRtPP7tw)](https://www.youtube.com/@HunterHogan)
+
+[![CC-BY-NC-4.0](https://github.com/hunterhogan/astToolkit/blob/main/CC-BY-NC-4.0.svg)](https://creativecommons.org/licenses/by-nc/4.0/)

asttoolkit-0.1.3/README.md

@@ -0,0 +1,178 @@
+# astToolkit
+
+## Do You Want This Package?
+
+astToolkit provides a powerfully composable system for manipulating Python Abstract Syntax Trees. Use it when:
+
+- You need to programmatically analyze, transform, or generate Python code.
+- You want type-safe operations that help prevent AST manipulation errors.
+- You prefer working with a consistent, fluent API rather than raw AST nodes.
+- You desire the ability to compose complex AST transformations from simple, reusable parts.
+
+Don't use it for simple text-based code manipulation—use regex or string operations instead.
+
+## Usage
+
+### Core Atomic Operations
+
+astToolkit provides four core classes that perform "atomic" operations on every AST class and attribute:
+
+```python
+from astToolkit import Be, DOT, Grab, Make
+import ast
+
+# Create an AST node
+node = Make.Name("example")
+
+print(f"{ast.dump(node) = }\n")
+
+# Access node properties safely with type checking
+myNameDOTidIs = DOT.id(node)
+
+print(f"{myNameDOTidIs = }\n")
+
+# Check node type with type guard functions
+CallNode = Make.Call(node)
+print(f"{ast.dump(CallNode) = }\n")
+
+print(f"{Be.Name(CallNode) = }")
+print(f"{Be.Name(node) = }")
+
+print(f"{Be.Call(CallNode) = }\n{Be.Name(DOT.func(CallNode)) = }\n")
+
+# Transform node attributes while preserving structure
+action = lambda idValue: f"modified_{idValue}"
+doThis = Grab.idAttribute(action)
+nodeAfterAction = doThis(node)
+print(f"{ast.dump(node) = }")
+```
+
+### AST Traversal and Transformation
+
+The real power lies in composable traversal and transformation using `NodeTourist` and `NodeChanger`:
+
+```python
+
+"""
+The AI assistant's example was stupid and wrong. I'm too sick right
+now to make a better one.
+"""
+
+```
+
+### Extending `IfThis` and `Then` Classes
+
+Extend these classes to create custom predicate and action functions:
+
+```python
+from astToolkit import ast_Identifier, Be, IfThis as astToolkit_IfThis
+from collections.abc import Callable
+from typing import Any, TypeGuard
+import ast
+
+class IfThis(astToolkit_IfThis):
+  @staticmethod
+  def isAttributeNamespace_IdentifierGreaterThan0(
+      namespace: ast_Identifier,
+      identifier: ast_Identifier
+      ) -> Callable[[ast.AST], TypeGuard[ast.Compare] | bool]:
+
+    return lambda node: (
+        Be.Compare(node)
+        and IfThis.isAttributeNamespace_Identifier(namespace, identifier)(node.left)
+        and Be.Gt(node.ops[0])
+        and IfThis.isConstant_value(0)(node.comparators[0]))
+
+  @staticmethod
+  def isIfAttributeNamespace_IdentifierGreaterThan0(
+      namespace: ast_Identifier,
+      identifier: ast_Identifier
+      ) -> Callable[[ast.AST], TypeGuard[ast.If] | bool]:
+
+    return lambda node: (
+        Be.If(node)
+        and IfThis.isAttributeNamespace_IdentifierGreaterThan0(namespace, identifier)(node.test))
+
+  @staticmethod
+  def isWhileAttributeNamespace_IdentifierGreaterThan0(
+      namespace: ast_Identifier,
+      identifier: ast_Identifier
+      ) -> Callable[[ast.AST], TypeGuard[ast.While] | bool]:
+
+    return lambda node: (
+        Be.While(node)
+        and IfThis.isAttributeNamespace_IdentifierGreaterThan0(namespace, identifier)(node.test))
+
+  # Or, make the comparison value a parameter
+  @staticmethod
+  def isAttributeNamespace_IdentifierGreaterThanThis(
+      namespace: ast_Identifier,
+      identifier: ast_Identifier,
+      value: Any
+      ) -> Callable[[ast.AST], TypeGuard[ast.Compare] | bool]:
+
+    return lambda node: (
+        Be.Compare(node)
+        and IfThis.isAttributeNamespace_Identifier(namespace, identifier)(node.left)
+        and Be.Gt(node.ops[0])
+        and IfThis.isConstant_value(value)(node.comparators[0]))
+```
+
+### Easy-to-use Tools for Annoying Tasks
+
+- extractClassDef
+- extractFunctionDef
+- parseLogicalPath2astModule
+- parsePathFilename2astModule
+
+### Easy-to-use Tools for More Complicated Tasks
+
+- removeUnusedParameters
+- write_astModule
+
+### The `toolFactory`
+
+Hypothetically, you could customize every aspect of the classes `Be`, `DOT`, `GRAB`, and `Make` and more than 100 `TypeAlias` in the toolFactory directory/package.
+
+## Installation
+
+```bash
+pip install astToolkit
+```
+
+## Technical Details
+
+### Architecture
+
+astToolkit implements a layered architecture designed for composability and type safety:
+
+1. **Core "Atomic" Classes** - The foundation of the system:
+   - `Be`: Type guards that return `TypeGuard[ast.NodeType]` for safe type narrowing.
+   - `DOT`: Read-only accessors that retrieve node attributes with proper typing.
+   - `Grab`: Transformation functions that modify specific attributes while preserving node structure.
+   - `Make`: Factory methods that create properly configured AST nodes with consistent interfaces.
+
+2. **Traversal and Transformation** - Built on the visitor pattern:
+   - `NodeTourist`: Extends `ast.NodeVisitor` to extract information from nodes that match predicates.
+   - `NodeChanger`: Extends `ast.NodeTransformer` to selectively transform nodes that match predicates.
+
+3. **Composable APIs** - The predicate-action pattern:
+   - `IfThis`: Generates predicate functions that identify nodes based on structure, content, or relationships.
+   - `Then`: Creates action functions that specify what to do with matched nodes (extract, replace, modify).
+
+4. **Higher-level Tools** - Built from the core components:
+   - `_toolkitAST.py`: Functions for common operations like extracting function definitions or importing modules.
+   - `transformationTools.py`: Advanced utilities like function inlining and code generation.
+   - `IngredientsFunction` and `IngredientsModule`: Containers for holding AST components and their dependencies.
+
+5. **Type System** - Over 120 specialized types for AST components:
+   - Custom type annotations for AST node attributes.
+   - Union types that accurately model Python's AST structure.
+   - Type guards that enable static type checkers to understand dynamic type narrowing.
+
+## My Recovery
+
+[![Static Badge](https://img.shields.io/badge/2011_August-Homeless_since-blue?style=flat)](https://HunterThinks.com/support)
+[![YouTube Channel Subscribers](https://img.shields.io/youtube/channel/subscribers/UC3Gx7kz61009NbhpRtPP7tw)](https://www.youtube.com/@HunterHogan)
+
+[![CC-BY-NC-4.0](https://github.com/hunterhogan/astToolkit/blob/main/CC-BY-NC-4.0.svg)](https://creativecommons.org/licenses/by-nc/4.0/)

{asttoolkit-0.1.2 → asttoolkit-0.1.3}/astToolkit/__init__.py

@@ -21,13 +21,9 @@ from astToolkit._types import (
 
 from astToolkit._astTypes import *  # noqa: F403
 
-from astToolkit._toolboxPython import (
-	importLogicalPath2Callable as importLogicalPath2Callable,
-	importPathFilename2Callable as importPathFilename2Callable,
+from astToolkit._toolkitNodeVisitor import (
 	NodeChanger as NodeChanger,
 	NodeTourist as NodeTourist,
-	parseLogicalPath2astModule as parseLogicalPath2astModule,
-	parsePathFilename2astModule as parsePathFilename2astModule,
 )
 
 from astToolkit._toolBe import Be as Be
@@ -38,14 +34,16 @@ from astToolkit._toolMake import Make as Make
 from astToolkit._toolIfThis import IfThis as IfThis
 from astToolkit._toolThen import Then as Then
 
-from astToolkit._toolboxContainers import (
+from astToolkit._toolkitContainers import (
 	IngredientsFunction as IngredientsFunction,
 	IngredientsModule as IngredientsModule,
 	LedgerOfImports as LedgerOfImports,
 )
 
-from astToolkit._toolboxAST import (
+from astToolkit._toolkitAST import (
 	astModuleToIngredientsFunction as astModuleToIngredientsFunction,
 	extractClassDef as extractClassDef,
 	extractFunctionDef as extractFunctionDef,
+	parseLogicalPath2astModule as parseLogicalPath2astModule,
+	parsePathFilename2astModule as parsePathFilename2astModule,
 )

asttoolkit-0.1.3/astToolkit/_toolkitAST.py

@@ -0,0 +1,113 @@
+import importlib
+from inspect import getsource as inspect_getsource
+from os import PathLike
+from pathlib import Path, PurePath
+from types import ModuleType
+from typing import Any, Literal
+from astToolkit import ast_Identifier, IfThis, IngredientsFunction, LedgerOfImports, NodeTourist, Then, str_nameDOTname
+from astToolkit import FREAKOUT
+import ast
+
+def astModuleToIngredientsFunction(astModule: ast.AST, identifierFunctionDef: ast_Identifier) -> IngredientsFunction:
+	"""
+	Extract a function definition from an AST module and create an `IngredientsFunction`.
+
+	This function finds a function definition with the specified identifier in the given AST module, extracts it, and
+	stores all module imports in the `LedgerOfImports`.
+
+	Parameters:
+		astModule: The AST module containing the function definition.
+		identifierFunctionDef: The name of the function to extract.
+
+	Returns:
+		ingredientsFunction: `IngredientsFunction` object containing the `ast.FunctionDef` and _all_ imports from the
+		source module.
+
+	Raises:
+		FREAKOUT: If the function definition is not found.
+	"""
+	astFunctionDef = extractFunctionDef(astModule, identifierFunctionDef)
+	if not astFunctionDef: raise FREAKOUT
+	return IngredientsFunction(astFunctionDef, LedgerOfImports(astModule))
+
+def extractClassDef(module: ast.AST, identifier: ast_Identifier) -> ast.ClassDef | None:
+	"""
+	Extract a class definition with a specific name from an AST module.
+
+	This function searches through an AST module for a class definition that matches the provided identifier and returns
+	it if found.
+
+	Parameters:
+		module: The AST module to search within.
+		identifier: The name of the class to find.
+
+	Returns:
+		astClassDef|None: The matching class definition AST node, or `None` if not found.
+	"""
+	return NodeTourist(IfThis.isClassDef_Identifier(identifier), Then.extractIt).captureLastMatch(module)
+
+def extractFunctionDef(module: ast.AST, identifier: ast_Identifier) -> ast.FunctionDef | None:
+	"""
+	Extract a function definition with a specific name from an AST module.
+
+	This function searches through an AST module for a function definition that matches the provided identifier and
+	returns it if found.
+
+	Parameters:
+		module: The AST module to search within.
+		identifier: The name of the function to find.
+
+	Returns:
+		astFunctionDef|None: The matching function definition AST node, or `None` if not found.
+	"""
+	return NodeTourist(IfThis.isFunctionDef_Identifier(identifier), Then.extractIt).captureLastMatch(module)
+
+def parseLogicalPath2astModule(logicalPathModule: str_nameDOTname, packageIdentifierIfRelative: ast_Identifier | None = None, mode: Literal['exec'] = 'exec') -> ast.Module:
+	"""
+	Parse a logical Python module path into an `ast.Module`.
+
+	This function imports a module using its logical path (e.g., 'package.subpackage.module') and converts its source
+	code into an Abstract Syntax Tree (AST) Module object.
+
+	Parameters
+	----------
+	logicalPathModule
+		The logical path to the module using dot notation (e.g., 'package.module').
+	packageIdentifierIfRelative : None
+		The package identifier to use if the module path is relative, defaults to None.
+	mode : Literal['exec']
+		The mode parameter for `ast.parse`. Default is `Literal['exec']`. Options are `Literal['exec']`, `"exec"` (which
+		is _not_ the same as `Literal['exec']`), `Literal['eval']`, `Literal['func_type']`, `Literal['single']`. See
+		`ast.parse` documentation for some details and much confusion.
+
+	Returns
+	-------
+	astModule
+		An AST Module object representing the parsed source code of the imported module.
+	"""
+	moduleImported: ModuleType = importlib.import_module(logicalPathModule, packageIdentifierIfRelative)
+	sourcePython: str = inspect_getsource(moduleImported)
+	return ast.parse(sourcePython, mode)
+
+def parsePathFilename2astModule(pathFilename: PathLike[Any] | PurePath, mode: Literal['exec'] = 'exec') -> ast.Module:
+	"""
+	Parse a file from a given path into an `ast.Module`.
+
+	This function reads the content of a file specified by `pathFilename` and parses it into an Abstract Syntax Tree
+	(AST) Module using Python's ast module.
+
+	Parameters
+	----------
+	pathFilename
+		The path to the file to be parsed. Can be a string path, PathLike object, or PurePath object.
+	mode : Literal['exec']
+		The mode parameter for `ast.parse`. Default is `Literal['exec']`. Options are `Literal['exec']`, `"exec"` (which
+		is _not_ the same as `Literal['exec']`), `Literal['eval']`, `Literal['func_type']`, `Literal['single']`. See
+		`ast.parse` documentation for some details and much confusion.
+
+	Returns
+	-------
+	astModule
+		The parsed abstract syntax tree module.
+	"""
+	return ast.parse(Path(pathFilename).read_text(), mode)

asttoolkit-0.1.2/astToolkit/_toolboxContainers.py → asttoolkit-0.1.3/astToolkit/_toolkitContainers.py

@@ -160,7 +160,7 @@ class IngredientsFunction:
 	"""
 	astFunctionDef: ast.FunctionDef
 	imports: LedgerOfImports = dataclasses.field(default_factory=LedgerOfImports)
-	type_ignores: list[ast.TypeIgnore] = dataclasses.field(default_factory=list)
+	type_ignores: list[ast.TypeIgnore] = dataclasses.field(default_factory=lambda: list[ast.TypeIgnore]())
 
 @dataclasses.dataclass
 class IngredientsModule:
@@ -198,16 +198,16 @@ class IngredientsModule:
 	"""
 	imports: LedgerOfImports = dataclasses.field(default_factory=LedgerOfImports)
 	"""Modify this field using the methods in `LedgerOfImports`."""
-	prologue: ast.Module = Make.Module([],[])
-	"""Statements after the imports and before the functions in listIngredientsFunctions."""
-	listIngredientsFunctions: list[IngredientsFunction] = dataclasses.field(default_factory=list)
-	epilogue: ast.Module = Make.Module([],[])
-	"""Statements after the functions in listIngredientsFunctions and before `launcher`."""
-	launcher: ast.Module = Make.Module([],[])
+	prologue: ast.Module = Make.Module([])
+	"""Statements after the imports and before the functions in `listIngredientsFunctions`."""
+	listIngredientsFunctions: list[IngredientsFunction] = dataclasses.field(default_factory=lambda: list[IngredientsFunction]())
+	epilogue: ast.Module = Make.Module([])
+	"""Statements after the functions in `listIngredientsFunctions` and before `launcher`."""
+	launcher: ast.Module = Make.Module([])
 	"""`if __name__ == '__main__':`"""
 
 	# `ast.TypeIgnore` statements to supplement those in other fields; `type_ignores` is a parameter for `ast.Module` constructor
-	supplemental_type_ignores: list[ast.TypeIgnore] = dataclasses.field(default_factory=list)
+	supplemental_type_ignores: list[ast.TypeIgnore] = dataclasses.field(default_factory=lambda: list[ast.TypeIgnore]())
 
 	def __post_init__(self, ingredientsFunction: Sequence[IngredientsFunction] | IngredientsFunction | None = None) -> None:
 		if ingredientsFunction is not None:
@@ -217,7 +217,6 @@ class IngredientsModule:
 				self.appendIngredientsFunction(*ingredientsFunction)
 
 	def _append_astModule(self, self_astModule: ast.Module, astModule: ast.Module | None, statement: Sequence[ast.stmt] | ast.stmt | None, type_ignores: list[ast.TypeIgnore] | None) -> None:
-		"""Append one or more statements to `prologue`."""
 		list_body: list[ast.stmt] = []
 		listTypeIgnore: list[ast.TypeIgnore] = []
 		if astModule is not None and isinstance(astModule, ast.Module):

asttoolkit-0.1.3/astToolkit/_toolkitNodeVisitor.py

@@ -0,0 +1,69 @@
+"""
+Core AST Traversal and Transformation Utilities for Python Code Manipulation
+
+This module provides the foundation for traversing and modifying Python Abstract Syntax Trees (ASTs). It contains two
+primary classes:
+
+1. NodeTourist: Implements the visitor pattern to traverse an AST and extract information from nodes that match specific
+	predicates without modifying the AST.
+
+2. NodeChanger: Extends ast.NodeTransformer to selectively transform AST nodes that match specific predicates, enabling
+	targeted code modifications.
+
+The module also provides utilities for importing modules, loading callables from files, and parsing Python code into AST
+structures, creating a complete workflow for code analysis and transformation.
+"""
+
+from collections.abc import Callable
+from typing import Any
+import ast
+
+# TODO Identify the logic that narrows the type and can help the user during static type checking.
+
+class NodeTourist(ast.NodeVisitor):
+	"""
+	Visit and extract information from AST nodes that match a predicate.
+
+	NodeTourist implements the visitor pattern to traverse an AST, applying a predicate function to each node and
+	capturing nodes or their attributes when they match. Unlike NodeChanger, it doesn't modify the AST but collects
+	information during traversal.
+
+	This class is particularly useful for analyzing AST structures, extracting specific nodes or node properties, and
+	gathering information about code patterns.
+	"""
+	def __init__(self, findThis: Callable[..., Any], doThat: Callable[..., Any]) -> None:
+		self.findThis = findThis
+		self.doThat = doThat
+		self.nodeCaptured: Any | None = None
+
+	def visit(self, node: ast.AST) -> None:
+		if self.findThis(node):
+			nodeActionReturn = self.doThat(node)
+			if nodeActionReturn is not None:
+				self.nodeCaptured = nodeActionReturn
+		self.generic_visit(node)
+
+	def captureLastMatch(self, node: ast.AST) -> Any | None:
+		self.nodeCaptured = None
+		self.visit(node)
+		return self.nodeCaptured
+
+class NodeChanger(ast.NodeTransformer):
+	"""
+	Transform AST nodes that match a predicate by applying a transformation function.
+
+	NodeChanger is an AST node transformer that applies a targeted transformation to nodes matching a specific
+	predicate. It traverses the AST and only modifies nodes that satisfy the predicate condition, leaving other nodes
+	unchanged.
+
+	This class extends ast.NodeTransformer and implements the visitor pattern to systematically process and transform an
+	AST tree.
+	"""
+	def __init__(self, findThis: Callable[..., Any], doThat: Callable[..., Any]) -> None:
+		self.findThis = findThis
+		self.doThat = doThat
+
+	def visit(self, node: ast.AST) -> ast.AST:
+		if self.findThis(node):
+			return self.doThat(node)
+		return super().visit(node)