mapFolding 0.8.0__py3-none-any.whl → 0.8.1__py3-none-any.whl

mapFolding/someAssemblyRequired/transformationTools.py

@@ -1,20 +1,36 @@
-"""As of 2025-03-15
-Tools for transforming Python code from one format to another.
-
-Scope:
-- What is necessary to transform the baseline algorithm into optimized formats used by the official package.
-
-Aspirations:
-- Each tool is abstracted or generic enough to be used beyond the scope of the official package.
-- Each tool is designed to be used in a modular fashion, allowing for the creation of new tools by combining existing tools.
-- If a tool has a default setting, the setting shall be the setting used by the official package.
 """
+Tools for transforming Python code through abstract syntax tree (AST) manipulation.
+
+This module provides a comprehensive set of utilities for programmatically analyzing,
+transforming, and generating Python code through AST manipulation. It implements
+a highly flexible framework that enables:
+
+1. Precise identification of code patterns through composable predicates
+2. Targeted modification of code structures while preserving semantics
+3. Code generation with proper syntax and import management
+4. Analysis of code dependencies and relationships
+5. Clean transformation of one algorithmic implementation to another
+
+The utilities are organized into several key components:
+- Predicate factories (ifThis): Create composable functions for matching AST patterns
+- Node transformers: Modify AST structures in targeted ways
+- Code generation helpers (Make): Create well-formed AST nodes programmatically
+- Import tracking: Maintain proper imports during code transformation
+- Analysis tools: Extract and organize code information
+
+While these tools were developed to transform the baseline algorithm into optimized formats,
+they are designed as general-purpose utilities applicable to a wide range of code
+transformation scenarios beyond the scope of this package.
+"""
+from autoflake import fix_code as autoflake_fix_code
 from collections import defaultdict
-from collections.abc import Callable, Container, Generator, Sequence
-from contextlib import contextmanager
+from collections.abc import Callable, Container, Sequence
+from copy import deepcopy
 from inspect import getsource as inspect_getsource
+from mapFolding.filesystem import writeStringToHere
 from mapFolding.theSSOT import (
 	getSourceAlgorithm,
+	raiseIfNoneGitHubIssueNumber3,
 	theDataclassIdentifier,
 	theDataclassInstance,
 	theDataclassInstanceTaskDistribution,
@@ -32,9 +48,10 @@ from mapFolding.theSSOT import (
 	theSourceParallelCallable,
 	theSourceSequentialCallable,
 )
-from pathlib import PurePosixPath
+from os import PathLike
+from pathlib import Path, PurePath, PurePosixPath
 from types import ModuleType
-from typing import Any, Generic, cast, TypeAlias, TypeGuard, TypeVar
+from typing import Any, cast, Generic, TypeAlias, TypeGuard, TypeVar
 from Z0Z_tools import updateExtendPolishDictionaryLists
 import ast
 import dataclasses
@@ -56,24 +73,15 @@ Namespace: uppercase, should only appear in camelCase and means "namespace", low
 
 # Would `LibCST` be better than `ast` in some cases? https://github.com/hunterhogan/mapFolding/issues/7
 
-nodeType = TypeVar('nodeType', bound=ast.AST)
-ast_Identifier: TypeAlias = str
 ast_expr_Slice: TypeAlias = ast.expr
-strDotStrCuzPyStoopid: TypeAlias = str
-strORlist_ast_type_paramORintORNone: TypeAlias = Any
-list_ast_type_paramORintORNone: TypeAlias = Any
-strORintORNone: TypeAlias = Any
+ast_Identifier: TypeAlias = str
 astClassHasAttributeDOTname: TypeAlias = ast.FunctionDef | ast.ClassDef | ast.AsyncFunctionDef
 astMosDef = TypeVar('astMosDef', bound=astClassHasAttributeDOTname)
-
-@contextmanager
-def listAsNode(ImaList: list[ast.stmt]) -> Generator[ast.Module, None, None]:
-	"""Convert a list of AST nodes into a module for use in node walking tools."""
-	ImaModule = ast.Module(ImaList)
-	try:
-		yield ImaModule
-	finally:
-		ImaList = ImaModule.body
+list_ast_type_paramORintORNone: TypeAlias = Any
+nodeType = TypeVar('nodeType', bound=ast.AST)
+strDotStrCuzPyStoopid: TypeAlias = str
+strORintORNone: TypeAlias = Any
+strORlist_ast_type_paramORintORNone: TypeAlias = Any
 
 class NodeCollector(Generic[nodeType], ast.NodeVisitor):
 	"""A node visitor that collects data via one or more actions when a predicate is met."""
@@ -87,255 +95,189 @@ class NodeCollector(Generic[nodeType], ast.NodeVisitor):
 				action(cast(nodeType, node))
 		self.generic_visit(node)
 
-ImaViolationOfTheLiskovSubstitutionPrinciple: TypeAlias = ast.AST
 class NodeReplacer(Generic[nodeType], ast.NodeTransformer):
 	"""A node transformer that replaces or removes AST nodes based on a condition."""
 	def __init__(self, findThis: Callable[[ast.AST], TypeGuard[nodeType] | bool], doThat: Callable[[nodeType], ast.AST | Sequence[ast.AST] | None]) -> None:
 		self.findThis = findThis
 		self.doThat = doThat
 
-	def visit(self, node: ImaViolationOfTheLiskovSubstitutionPrinciple) -> ast.AST | Sequence[ast.AST] | None:
+	def visit(self, node: ast.AST) -> ast.AST | Sequence[ast.AST] | None:
 		if self.findThis(node):
 			return self.doThat(cast(nodeType, node))
 		return super().visit(node)
 
 class ifThis:
 	@staticmethod
-	def ast_IdentifierIsIn(container: Container[ast_Identifier]) -> Callable[[ast_Identifier], TypeGuard[ast_Identifier]]:
-		return lambda node: node in container # type: ignore
-
+	def ast_IdentifierIsIn(container: Container[ast_Identifier]) -> Callable[[ast_Identifier], TypeGuard[ast_Identifier] | bool]:
+		return lambda node: node in container
 	@staticmethod
-	def CallDoesNotCallItself(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Call]]:
+	def CallDoesNotCallItself(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Call] | bool]:
 		"""If `namespace` is not applicable to your case, then call with `namespace=""`."""
-		return lambda node: ifThis.matchesMeButNotAnyDescendant(ifThis.CallReallyIs(namespace, identifier))(node) # type: ignore
-
+		return lambda node: ifThis.matchesMeButNotAnyDescendant(ifThis.CallReallyIs(namespace, identifier))(node)
 	@staticmethod
-	def CallDoesNotCallItselfAndNameDOTidIsIn(container: Container[ast_Identifier]) -> Callable[[ast.AST], TypeGuard[ast.Call]]:
-		return lambda node: ifThis.isCall(node) and ifThis.isName(node.func) and ifThis.ast_IdentifierIsIn(container)(node.func.id) and ifThis.CallDoesNotCallItself("", node.func.id)(node) # type: ignore
-
+	def CallDoesNotCallItselfAndNameDOTidIsIn(container: Container[ast_Identifier]) -> Callable[[ast.AST], TypeGuard[ast.Call] | bool]:
+		return lambda node: ifThis.isCall(node) and ifThis.isName(node.func) and ifThis.ast_IdentifierIsIn(container)(node.func.id) and ifThis.CallDoesNotCallItself("", node.func.id)(node)
 	@staticmethod
-	def CallReallyIs(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Call]]:
-		return ifThis.isAnyOf(ifThis.isCall_Identifier(identifier), ifThis.isCallNamespace_Identifier(namespace, identifier)) # type: ignore
-
+	def CallReallyIs(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Call] | bool]:
+		return ifThis.isAnyOf(ifThis.isCall_Identifier(identifier), ifThis.isCallNamespace_Identifier(namespace, identifier))
 	@staticmethod
 	def is_keyword(node: ast.AST) -> TypeGuard[ast.keyword]:
 		return isinstance(node, ast.keyword)
-
 	@staticmethod
 	def is_keywordAndValueIsConstant(node: ast.AST) -> TypeGuard[ast.keyword]:
 		return ifThis.is_keyword(node) and ifThis.isConstant(node.value)
-
 	@staticmethod
-	def is_keyword_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.keyword]]:
-		return lambda node: ifThis.is_keyword(node) and node.arg == identifier # type: ignore
-
+	def is_keyword_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.keyword] | bool]:
+		def workhorse(node: ast.AST) -> TypeGuard[ast.keyword] | bool:
+			return ifThis.is_keyword(node) and node.arg == identifier
+		return workhorse
 	@staticmethod
-	def is_keyword_IdentifierEqualsConstantValue(identifier: ast_Identifier, ConstantValue: Any) -> Callable[[ast.AST], TypeGuard[ast.keyword]]:
-		return lambda node: (ifThis.is_keyword_Identifier(identifier)(node) and ifThis.is_keywordAndValueIsConstant(node) and ifThis.isConstantEquals(ConstantValue)(node.value)) # type: ignore
-
+	def is_keyword_IdentifierEqualsConstantValue(identifier: ast_Identifier, ConstantValue: Any) -> Callable[[ast.AST], TypeGuard[ast.keyword] | bool]:
+		return lambda node: ifThis.is_keyword_Identifier(identifier)(node) and ifThis.is_keywordAndValueIsConstant(node) and ifThis.isConstantEquals(ConstantValue)(node.value)
 	@staticmethod
 	def isAllOf(*thesePredicates: Callable[[ast.AST], bool]) -> Callable[[ast.AST], bool]:
 		return lambda node: all(predicate(node) for predicate in thesePredicates)
-
 	@staticmethod
 	def isAnnAssign(node: ast.AST) -> TypeGuard[ast.AnnAssign]:
 		return isinstance(node, ast.AnnAssign)
-
 	@staticmethod
 	def isAnnAssignAndAnnotationIsName(node: ast.AST) -> TypeGuard[ast.AnnAssign]:
 		return ifThis.isAnnAssign(node) and ifThis.isName(node.annotation)
-
 	@staticmethod
 	def isAnnAssignAndTargetIsName(node: ast.AST) -> TypeGuard[ast.AnnAssign]:
 		return ifThis.isAnnAssign(node) and ifThis.isName(node.target)
-
 	@staticmethod
-	def isAnnAssignTo(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.AnnAssign]]:
-		return lambda node: ifThis.isAnnAssign(node) and ifThis.NameReallyIs_Identifier(identifier)(node.target) # type: ignore
-
+	def isAnnAssignTo(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.AnnAssign] | bool]:
+		return lambda node: ifThis.isAnnAssign(node) and ifThis.NameReallyIs_Identifier(identifier)(node.target)
 	@staticmethod
 	def isAnyAssignmentTo(identifier: ast_Identifier) -> Callable[[ast.AST], bool]:
 		return ifThis.isAnyOf(ifThis.isAssignOnlyTo(identifier), ifThis.isAnnAssignTo(identifier), ifThis.isAugAssignTo(identifier))
-
 	@staticmethod
 	def isAnyCompare(node: ast.AST) -> TypeGuard[ast.Compare] | TypeGuard[ast.BoolOp]:
 		return ifThis.isCompare(node) or ifThis.isBoolOp(node)
-
 	@staticmethod
 	def isAnyOf(*thesePredicates: Callable[[ast.AST], bool]) -> Callable[[ast.AST], bool]:
 		return lambda node: any(predicate(node) for predicate in thesePredicates)
-
 	@staticmethod
 	def isAssign(node: ast.AST) -> TypeGuard[ast.Assign]:
 		return isinstance(node, ast.Assign)
-
 	@staticmethod
-	def isAssignAndValueIsCall_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Assign]]:
-		return lambda node: ifThis.isAssign(node) and ifThis.isCall_Identifier(identifier)(node.value) # type: ignore
-
-	# @staticmethod
-	# def isAssignAndValueIsCallNamespace_Identifier(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Assign]]:
-	# 	return lambda node: ifThis.isAssign(node) and ifThis.isCallNamespace_Identifier(namespace, identifier)(node.value)
-
+	def isAssignAndValueIsCall_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Assign] | bool]:
+		return lambda node: ifThis.isAssign(node) and ifThis.isCall_Identifier(identifier)(node.value)
 	@staticmethod
-	def isAssignAndValueIsCallNamespace_Identifier(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Assign]]:
+	def isAssignAndValueIsCallNamespace_Identifier(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Assign] | bool]:
 		return ifThis.isAssignAndValueIs(ifThis.isCallNamespace_Identifier(namespace, identifier))
-
 	@staticmethod
-	def isAssignOnlyTo(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Assign]]:
-		return lambda node: ifThis.isAssign(node) and ifThis.NameReallyIs_Identifier(identifier)(node.targets[0]) # type: ignore
-
+	def isAssignOnlyTo(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Assign] | bool]:
+		return lambda node: ifThis.isAssign(node) and ifThis.NameReallyIs_Identifier(identifier)(node.targets[0])
 	@staticmethod
-	def isAssignAndTargets0Is(targets0Predicate: Callable[[ast.AST], bool]) -> Callable[[ast.AST], TypeGuard[ast.Assign]]:
+	def isAssignAndTargets0Is(targets0Predicate: Callable[[ast.AST], bool]) -> Callable[[ast.AST], TypeGuard[ast.Assign] | bool]:
 		"""node is Assign and node.targets[0] matches `targets0Predicate`."""
-		return lambda node: ifThis.isAssign(node) and targets0Predicate(node.targets[0]) # type: ignore
-
+		return lambda node: ifThis.isAssign(node) and targets0Predicate(node.targets[0])
 	@staticmethod
-	def isAssignAndValueIs(valuePredicate: Callable[[ast.AST], bool]) -> Callable[[ast.AST], TypeGuard[ast.Assign]]:
-		"""node is Assign and node.value matches `valuePredicate`.
-
+	def isAssignAndValueIs(valuePredicate: Callable[[ast.AST], bool]) -> Callable[[ast.AST], TypeGuard[ast.Assign] | bool]:
+		"""node is ast.Assign and node.value matches `valuePredicate`.
 		Parameters:
 			valuePredicate: Function that evaluates the value of the assignment
-
 		Returns:
-			A predicate that matches assignments with values meeting the criteria
+			predicate: matches assignments with values meeting the criteria
 		"""
-		return lambda node: ifThis.isAssign(node) and valuePredicate(node.value) # type: ignore
-
+		return lambda node: ifThis.isAssign(node) and valuePredicate(node.value)
 	@staticmethod
 	def isAttribute(node: ast.AST) -> TypeGuard[ast.Attribute]:
 		return isinstance(node, ast.Attribute)
-
 	@staticmethod
 	def isAugAssign(node: ast.AST) -> TypeGuard[ast.AugAssign]:
 		return isinstance(node, ast.AugAssign)
-
 	@staticmethod
-	def isAugAssignTo(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.AugAssign]]:
-		return lambda node: ifThis.isAugAssign(node) and ifThis.NameReallyIs_Identifier(identifier)(node.target) # type: ignore
-
+	def isAugAssignTo(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.AugAssign] | bool]:
+		return lambda node: ifThis.isAugAssign(node) and ifThis.NameReallyIs_Identifier(identifier)(node.target)
 	@staticmethod
 	def isBoolOp(node: ast.AST) -> TypeGuard[ast.BoolOp]:
 		return isinstance(node, ast.BoolOp)
-
 	@staticmethod
 	def isCall(node: ast.AST) -> TypeGuard[ast.Call]:
 		return isinstance(node, ast.Call)
-
 	@staticmethod
-	def isCall_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Call]]:
-		return lambda node: ifThis.isCall(node) and ifThis.isName_Identifier(identifier)(node.func) # type: ignore
-
+	def isCall_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Call] | bool]:
+		return lambda node: ifThis.isCall(node) and ifThis.isName_Identifier(identifier)(node.func)
 	@staticmethod
-	def isCallNamespace_Identifier(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Call]]:
-		return lambda node: ifThis.isCall(node) and ifThis.is_nameDOTnameNamespace_Identifier(namespace, identifier)(node.func) # type: ignore
-
+	def isCallNamespace_Identifier(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Call] | bool]:
+		return lambda node: ifThis.isCall(node) and ifThis.is_nameDOTnameNamespace_Identifier(namespace, identifier)(node.func)
 	@staticmethod
 	def isCallToName(node: ast.AST) -> TypeGuard[ast.Call]:
 		return ifThis.isCall(node) and ifThis.isName(node.func)
-
 	@staticmethod
 	def isClassDef(node: ast.AST) -> TypeGuard[ast.ClassDef]:
 		return isinstance(node, ast.ClassDef)
-
 	@staticmethod
-	def isClassDef_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.ClassDef]]:
-		return lambda node: ifThis.isClassDef(node) and node.name == identifier # type: ignore
-
+	def isClassDef_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.ClassDef] | bool]:
+		return lambda node: ifThis.isClassDef(node) and node.name == identifier
 	@staticmethod
 	def isCompare(node: ast.AST) -> TypeGuard[ast.Compare]:
 		return isinstance(node, ast.Compare)
-
 	@staticmethod
 	def isConstant(node: ast.AST) -> TypeGuard[ast.Constant]:
 		return isinstance(node, ast.Constant)
-
 	@staticmethod
-	def isConstantEquals(value: Any) -> Callable[[ast.AST], TypeGuard[ast.Constant]]:
-		return lambda node: ifThis.isConstant(node) and node.value == value # type: ignore
-
+	def isConstantEquals(value: Any) -> Callable[[ast.AST], TypeGuard[ast.Constant] | bool]:
+		return lambda node: ifThis.isConstant(node) and node.value == value
 	@staticmethod
 	def isExpr(node: ast.AST) -> TypeGuard[ast.Expr]:
 		return isinstance(node, ast.Expr)
-
 	@staticmethod
 	def isFunctionDef(node: ast.AST) -> TypeGuard[ast.FunctionDef]:
 		return isinstance(node, ast.FunctionDef)
-
 	@staticmethod
-	def isFunctionDef_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.FunctionDef]]:
-		return lambda node: ifThis.isFunctionDef(node) and node.name == identifier # type: ignore
-
+	def isFunctionDef_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.FunctionDef] | bool]:
+		return lambda node: ifThis.isFunctionDef(node) and node.name == identifier
 	@staticmethod
 	def isImport(node: ast.AST) -> TypeGuard[ast.Import]:
 		return isinstance(node, ast.Import)
-
-# A "name" is roughly ast._Identifier
-
-# A Name can be a "name"
-# ast.Name()
-
-# These classes can be a "name": I will call the group 'ClassQuizas'
-# The technical mechanism is `type[ast.ClassQuizas.value] == ast.Name`
-# or, and this is the annoying part,
-# `type[ast.ClassQuizas.value] == ast.ClassQuizas and type[ast.ClassQuizas.value.value] == ast.ClassQuizas and ... == ast.Name`
-# ast.Attribute()
-# ast.Subscript()
-# ast.Starred()
-
 	@staticmethod
 	def isName(node: ast.AST) -> TypeGuard[ast.Name]:
+		"""TODO
+		ast.Name()
+		ast.Attribute()
+		ast.Subscript()
+		ast.Starred()
+		"""
 		return isinstance(node, ast.Name)
-
 	@staticmethod
-	def isName_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Name]]:
-		return lambda node: ifThis.isName(node) and node.id == identifier # type: ignore
-
+	def isName_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Name] | bool]:
+		return lambda node: ifThis.isName(node) and node.id == identifier
 	@staticmethod
 	def is_nameDOTname(node: ast.AST) -> TypeGuard[ast.Attribute]:
 		return ifThis.isAttribute(node) and ifThis.isName(node.value)
-
 	@staticmethod
-	def is_nameDOTnameNamespace(namespace: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Attribute]]:
-		return lambda node: (ifThis.is_nameDOTname(node) and ifThis.isName_Identifier(namespace)(node.value)) # type: ignore
-
+	def is_nameDOTnameNamespace(namespace: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Attribute] | bool]:
+		return lambda node: ifThis.is_nameDOTname(node) and ifThis.isName_Identifier(namespace)(node.value)
 	@staticmethod
-	def is_nameDOTnameNamespace_Identifier(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Attribute]]:
-		return lambda node: (ifThis.is_nameDOTnameNamespace(namespace)(node) and node.attr == identifier) # type: ignore
-
-	@staticmethod
-	def isAnyNestedName(node: ast.AST):
-		return ifThis.isAnyOf()
-
+	def is_nameDOTnameNamespace_Identifier(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Attribute] | bool]:
+		return lambda node: ifThis.is_nameDOTname(node) and ifThis.isName_Identifier(namespace)(node.value) and node.attr == identifier
 	@staticmethod
 	def NameReallyIs_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], bool]:
 		# The following logic is incomplete.
 		return ifThis.isAnyOf(ifThis.isName_Identifier(identifier), ifThis.isSubscriptIsName_Identifier(identifier))
-
 	@staticmethod
 	def isReturn(node: ast.AST) -> TypeGuard[ast.Return]:
 		return isinstance(node, ast.Return)
-
 	@staticmethod
 	def isReturnAnyCompare(node: ast.AST) -> TypeGuard[ast.Return]:
 		return ifThis.isReturn(node) and node.value is not None and ifThis.isAnyCompare(node.value)
-
 	@staticmethod
 	def isReturnUnaryOp(node: ast.AST) -> TypeGuard[ast.Return]:
 		return ifThis.isReturn(node) and node.value is not None and ifThis.isUnaryOp(node.value)
-
 	@staticmethod
 	def isSubscript(node: ast.AST) -> TypeGuard[ast.Subscript]:
 		return isinstance(node, ast.Subscript)
-
 	@staticmethod
 	def isSubscript_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Subscript]]:
 		"""node is `ast.Subscript` and the top-level `ast.Name` is `identifier`
 		Parameters:
 			identifier: The identifier to look for in the value chain
-
 		Returns:
-			A predicate function that checks if a node matches the criteria
+			predicate: function that checks if a node matches the criteria
 		"""
 		def predicate(node: ast.AST) -> TypeGuard[ast.Subscript]:
 			if not ifThis.isSubscript(node):
@@ -349,26 +291,21 @@ class ifThis:
 				return False
 			return checkNodeDOTvalue(node.value)
 		return predicate
-
 	@staticmethod
-	def isSubscriptIsName_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Subscript]]:
-		return lambda node: ifThis.isSubscript(node) and ifThis.isName_Identifier(identifier)(node.value) # type: ignore
-
+	def isSubscriptIsName_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Subscript] | bool]:
+		return lambda node: ifThis.isSubscript(node) and ifThis.isName_Identifier(identifier)(node.value)
 	@staticmethod
-	def isSubscript_Identifier_Identifier(identifier: ast_Identifier, sliceIdentifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Subscript]]:
-		return lambda node: ifThis.isSubscript(node) and ifThis.isName_Identifier(identifier)(node.value) and ifThis.isName_Identifier(sliceIdentifier)(node.slice) # type: ignore
-
+	def isSubscript_Identifier_Identifier(identifier: ast_Identifier, sliceIdentifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Subscript] | bool]:
+		return lambda node: ifThis.isSubscript(node) and ifThis.isName_Identifier(identifier)(node.value) and ifThis.isName_Identifier(sliceIdentifier)(node.slice)
 	@staticmethod
 	def isUnaryOp(node: ast.AST) -> TypeGuard[ast.UnaryOp]:
 		return isinstance(node, ast.UnaryOp)
-
-	# Does this work?
+	# TODO Does this work?
 	@staticmethod
 	def matchesAtLeast1Descendant(predicate: Callable[[ast.AST], bool]) -> Callable[[ast.AST], bool]:
 		"""Create a predicate that returns True if any descendant of the node matches the given predicate."""
 		return lambda node: not ifThis.matchesNoDescendant(predicate)(node)
-
-	# Does this work?
+	# TODO Does this work?
 	@staticmethod
 	def matchesMeAndMyDescendantsExactlyNTimes(predicate: Callable[[ast.AST], bool], nTimes: int) -> Callable[[ast.AST], bool]:
 		"""Create a predicate that returns True if exactly 'count' nodes in the tree match the predicate."""
@@ -376,12 +313,10 @@ class ifThis:
 			matches = sum(1 for descendant in ast.walk(node) if predicate(descendant))
 			return matches == nTimes
 		return countMatchingNodes
-
 	@staticmethod
 	def matchesMeButNotAnyDescendant(predicate: Callable[[ast.AST], bool]) -> Callable[[ast.AST], bool]:
 		"""Create a predicate that returns True if the node matches but none of its descendants match the predicate."""
 		return lambda node: predicate(node) and ifThis.matchesNoDescendant(predicate)(node)
-
 	@staticmethod
 	def matchesNoDescendant(predicate: Callable[[ast.AST], bool]) -> Callable[[ast.AST], bool]:
 		"""Create a predicate that returns True if no descendant of the node matches the given predicate."""
@@ -391,13 +326,11 @@ class ifThis:
 					return False
 			return True
 		return checkNoMatchingDescendant
-
 	@staticmethod
-	def OnlyReturnAnyCompare(astFunctionDef: ast.AST) -> TypeGuard[ast.FunctionDef]:
+	def onlyReturnAnyCompare(astFunctionDef: ast.AST) -> TypeGuard[ast.FunctionDef]:
 		return ifThis.isFunctionDef(astFunctionDef) and len(astFunctionDef.body) == 1 and ifThis.isReturnAnyCompare(astFunctionDef.body[0])
-
 	@staticmethod
-	def OnlyReturnUnaryOp(astFunctionDef: ast.AST) -> TypeGuard[ast.FunctionDef]:
+	def onlyReturnUnaryOp(astFunctionDef: ast.AST) -> TypeGuard[ast.FunctionDef]:
 		return ifThis.isFunctionDef(astFunctionDef) and len(astFunctionDef.body) == 1 and ifThis.isReturnUnaryOp(astFunctionDef.body[0])
 
 class Make:
@@ -405,29 +338,23 @@ class Make:
 	def ast_arg(identifier: ast_Identifier, annotation: ast.expr | None = None, **keywordArguments: strORintORNone) -> ast.arg:
 		"""keywordArguments: type_comment:str|None, lineno:int, col_offset:int, end_lineno:int|None, end_col_offset:int|None"""
 		return ast.arg(identifier, annotation, **keywordArguments)
-
 	@staticmethod
 	def ast_keyword(keywordArgument: ast_Identifier, value: ast.expr, **keywordArguments: int) -> ast.keyword:
 		return ast.keyword(arg=keywordArgument, value=value, **keywordArguments)
-
 	@staticmethod
 	def astAlias(name: ast_Identifier, asname: ast_Identifier | None = None) -> ast.alias:
 		return ast.alias(name, asname)
-
 	@staticmethod
 	def astAnnAssign(target: ast.Name | ast.Attribute | ast.Subscript, annotation: ast.expr, value: ast.expr | None = None, **keywordArguments: int) -> ast.AnnAssign:
 		"""`simple: int`: uses a clever int-from-boolean to assign the correct value to the `simple` attribute. So, don't add it as a parameter."""
 		return ast.AnnAssign(target, annotation, value, simple=int(isinstance(target, ast.Name)), **keywordArguments)
-
 	@staticmethod
 	def astAssign(listTargets: Any, value: ast.expr, **keywordArguments: strORintORNone) -> ast.Assign:
 		"""keywordArguments: type_comment:str|None, lineno:int, col_offset:int, end_lineno:int|None, end_col_offset:int|None"""
 		return ast.Assign(targets=listTargets, value=value, **keywordArguments)
-
 	@staticmethod
 	def astArgumentsSpecification(posonlyargs: list[ast.arg]=[], args: list[ast.arg]=[], vararg: ast.arg|None=None, kwonlyargs: list[ast.arg]=[], kw_defaults: list[ast.expr|None]=[None], kwarg: ast.arg|None=None, defaults: list[ast.expr]=[]) -> ast.arguments:
 		return ast.arguments(posonlyargs, args, vararg, kwonlyargs, kw_defaults, kwarg, defaults)
-
 	@staticmethod
 	def astAttribute(value: ast.expr, attribute: ast_Identifier, context: ast.expr_context = ast.Load(), **keywordArguments: int) -> ast.Attribute:
 		"""
@@ -436,47 +363,37 @@ class Make:
 			attribute: the `str` after the dot
 			context (ast.Load()): Load/Store/Del"""
 		return ast.Attribute(value, attribute, context, **keywordArguments)
-
 	@staticmethod
 	def astCall(caller: ast.Name | ast.Attribute, listArguments: Sequence[ast.expr] | None = None, list_astKeywords: Sequence[ast.keyword] | None = None) -> ast.Call:
 		return ast.Call(func=caller, args=list(listArguments) if listArguments else [], keywords=list(list_astKeywords) if list_astKeywords else [])
-
 	@staticmethod
 	def astClassDef(name: ast_Identifier, listBases: list[ast.expr]=[], list_keyword: list[ast.keyword]=[], body: list[ast.stmt]=[], decorator_list: list[ast.expr]=[], **keywordArguments: list_ast_type_paramORintORNone) -> ast.ClassDef:
 		"""keywordArguments: type_params:list[ast.type_param], lineno:int, col_offset:int, end_lineno:int|None, end_col_offset:int|None"""
 		return ast.ClassDef(name=name, bases=listBases, keywords=list_keyword, body=body, decorator_list=decorator_list, **keywordArguments)
-
 	@staticmethod
 	def astConstant(value: Any, **keywordArguments: strORintORNone) -> ast.Constant:
 		"""value: str|int|float|bool|None|bytes|bytearray|memoryview|complex|list|tuple|dict|set, or any other type that can be represented as a constant in Python.
 		keywordArguments: kind:str, lineno:int, col_offset:int, end_lineno:int|None, end_col_offset:int|None"""
 		return ast.Constant(value, **keywordArguments)
-
 	@staticmethod
 	def astFunctionDef(name: ast_Identifier, argumentsSpecification: ast.arguments=ast.arguments(), body: list[ast.stmt]=[], decorator_list: list[ast.expr]=[], returns: ast.expr|None=None, **keywordArguments: strORlist_ast_type_paramORintORNone) -> ast.FunctionDef:
 		"""keywordArguments: type_comment:str|None, type_params:list[ast.type_param], lineno:int, col_offset:int, end_lineno:int|None, end_col_offset:int|None"""
 		return ast.FunctionDef(name=name, args=argumentsSpecification, body=body, decorator_list=decorator_list, returns=returns, **keywordArguments)
-
 	@staticmethod
 	def astImport(moduleName: ast_Identifier, asname: ast_Identifier | None = None, **keywordArguments: int) -> ast.Import:
 		return ast.Import(names=[Make.astAlias(moduleName, asname)], **keywordArguments)
-
 	@staticmethod
 	def astImportFrom(moduleName: ast_Identifier, list_astAlias: list[ast.alias], **keywordArguments: int) -> ast.ImportFrom:
 		return ast.ImportFrom(module=moduleName, names=list_astAlias, level=0, **keywordArguments)
-
 	@staticmethod
 	def astModule(body: list[ast.stmt], type_ignores: list[ast.TypeIgnore] = []) -> ast.Module:
 		return ast.Module(body, type_ignores)
-
 	@staticmethod
 	def astName(identifier: ast_Identifier, context: ast.expr_context = ast.Load(), **keywordArguments: int) -> ast.Name:
 		return ast.Name(identifier, context, **keywordArguments)
-
 	@staticmethod
 	def itDOTname(nameChain: ast.Name | ast.Attribute, dotName: str) -> ast.Attribute:
 		return ast.Attribute(value=nameChain, attr=dotName, ctx=ast.Load())
-
 	@staticmethod
 	# TODO rewrite with all parameters
 	def nameDOTname(identifier: ast_Identifier, *dotName: str) -> ast.Name | ast.Attribute:
@@ -486,20 +403,15 @@ class Make:
 		for suffix in dotName:
 			nameDOTname = Make.itDOTname(nameDOTname, suffix)
 		return nameDOTname
-
 	@staticmethod
 	def astReturn(value: ast.expr | None = None, **keywordArguments: int) -> ast.Return:
 		return ast.Return(value, **keywordArguments)
-
 	@staticmethod
 	def astSubscript(value: ast.expr, slice: ast_expr_Slice, context: ast.expr_context = ast.Load(), **keywordArguments: int) -> ast.Subscript:
 		return ast.Subscript(value, slice, ctx=context, **keywordArguments)
-
 	@staticmethod
 	def astTuple(elements: Sequence[ast.expr], context: ast.expr_context = ast.Load(), **keywordArguments: int) -> ast.Tuple:
-	# def astTuple(elements: Sequence[ast.expr], context: ast.expr_context | None = None, **keywordArguments: int) -> ast.Tuple:
 		"""context: Load/Store/Del"""
-		# context = context or ast.Load()
 		return ast.Tuple(elts=list(elements), ctx=context, **keywordArguments)
 
 class LedgerOfImports:
@@ -513,8 +425,7 @@ class LedgerOfImports:
 			self.walkThis(startWith)
 
 	def addAst(self, astImport_: ast.Import | ast.ImportFrom) -> None:
-		if not isinstance(astImport_, (ast.Import, ast.ImportFrom)):
-			raise ValueError(f"Expected ast.Import or ast.ImportFrom, got {type(astImport_)}")
+		assert isinstance(astImport_, (ast.Import, ast.ImportFrom)), f"Expected ast.Import or ast.ImportFrom, got {type(astImport_)}"
 		if isinstance(astImport_, ast.Import):
 			for alias in astImport_.names:
 				self.listImport.append(alias.name)
@@ -594,8 +505,6 @@ class Then:
 	def Z0Z_appendAnnAssignOf_nameDOTnameTo(identifier: ast_Identifier, list_nameDOTname: list[ast.AnnAssign]) -> Callable[[ast.AnnAssign], None]:
 		return lambda node: list_nameDOTname.append(Make.astAnnAssign(node.target, node.annotation, Make.nameDOTname(identifier, node.target.id))) # type: ignore
 
-	# TODO When resolving the ledger of imports, remove self-referential imports
-
 @dataclasses.dataclass
 class IngredientsFunction:
 	"""Everything necessary to integrate a function into a module should be here."""
@@ -606,11 +515,6 @@ class IngredientsFunction:
 class IngredientsModule:
 	"""Everything necessary to create one _logical_ `ast.Module` should be here.
 	Extrinsic qualities should _probably_ be handled externally."""
-	# If an `ast.Module` had a logical name that would be reasonable, but Python is firmly opposed
-	# to a reasonable namespace, therefore, Hunter, you were silly to add a `name` field to this
-	# dataclass for building an `ast.Module`.
-	# name: ast_Identifier
-	# Hey, genius, note that this is dataclasses.InitVar
 	ingredientsFunction: dataclasses.InitVar[Sequence[IngredientsFunction] | IngredientsFunction | None] = None
 
 	# init var with an existing module? method to deconstruct an existing module?
@@ -676,7 +580,7 @@ class RecipeSynthesizeFlow:
 
 	# ========================================
 	# Filesystem
-	pathPackage: PurePosixPath = PurePosixPath(thePathPackage)
+	pathPackage: PurePosixPath | None = PurePosixPath(thePathPackage)
 	fileExtension: str = theFileExtension
 
 	# ========================================
@@ -686,7 +590,7 @@ class RecipeSynthesizeFlow:
 	formatStrModuleForCallableSynthetic: str = theFormatStrModuleForCallableSynthetic
 
 	# Package
-	packageName: ast_Identifier = thePackageName
+	packageName: ast_Identifier | None = thePackageName
 
 	# Module
 	# Figure out dynamic flow control to synthesized modules https://github.com/hunterhogan/mapFolding/issues/4
@@ -708,6 +612,26 @@ class RecipeSynthesizeFlow:
 	# Variable
 	dataclassInstance: str = sourceDataclassInstance
 
+	def _makePathFilename(self, filenameStem: str,
+			pathRoot: PurePosixPath | None = None,
+			logicalPathINFIX: strDotStrCuzPyStoopid | None = None,
+			fileExtension: str | None = None,
+			) -> PurePosixPath:
+		"""filenameStem: (hint: the name of the logical module)"""
+		if pathRoot is None:
+			pathRoot = self.pathPackage or PurePosixPath(Path.cwd())
+		if logicalPathINFIX:
+			whyIsThisStillAThing: list[str] = logicalPathINFIX.split('.')
+			pathRoot = pathRoot.joinpath(*whyIsThisStillAThing)
+		if fileExtension is None:
+			fileExtension = self.fileExtension
+		filename: str = filenameStem + fileExtension
+		return pathRoot.joinpath(filename)
+
+	@property
+	def pathFilenameDispatcher(self) -> PurePosixPath:
+		return self._makePathFilename(filenameStem=self.moduleDispatcher, logicalPathINFIX=self.Z0Z_flowLogicalPathRoot)
+
 def extractClassDef(identifier: ast_Identifier, module: ast.Module) -> ast.ClassDef | None:
 	sherpa: list[ast.ClassDef] = []
 	extractor = NodeCollector(ifThis.isClassDef_Identifier(identifier), [Then.appendTo(sherpa)])
@@ -732,9 +656,9 @@ def makeDictionaryReplacementStatements(module: ast.Module) -> dict[ast_Identifi
 	dictionaryFunctionDef: dict[ast_Identifier, ast.FunctionDef] = makeDictionaryFunctionDef(module)
 	dictionaryReplacementStatements: dict[ast_Identifier, ast.stmt | list[ast.stmt]] = {}
 	for name, astFunctionDef in dictionaryFunctionDef.items():
-		if ifThis.OnlyReturnAnyCompare(astFunctionDef):
+		if ifThis.onlyReturnAnyCompare(astFunctionDef):
 			dictionaryReplacementStatements[name] = astFunctionDef.body[0].value # type: ignore
-		elif ifThis.OnlyReturnUnaryOp(astFunctionDef):
+		elif ifThis.onlyReturnUnaryOp(astFunctionDef):
 			dictionaryReplacementStatements[name] = astFunctionDef.body[0].value # type: ignore
 		else:
 			dictionaryReplacementStatements[name] = astFunctionDef.body[0:-1]
@@ -761,3 +685,96 @@ def Z0Z_executeActionUnlessDescendantMatches(exclusionPredicate: Callable[[ast.A
 		if not Z0Z_descendantContainsMatchingNode(node, exclusionPredicate):
 			actionFunction(node)
 	return wrappedAction
+
+def inlineThisFunctionWithTheseValues(astFunctionDef: ast.FunctionDef, dictionaryReplacementStatements: dict[str, ast.stmt | list[ast.stmt]]) -> ast.FunctionDef:
+	class FunctionInliner(ast.NodeTransformer):
+		def __init__(self, dictionaryReplacementStatements: dict[str, ast.stmt | list[ast.stmt]]) -> None:
+			self.dictionaryReplacementStatements = dictionaryReplacementStatements
+
+		def generic_visit(self, node: ast.AST) -> ast.AST:
+			"""Visit all nodes and replace them if necessary."""
+			return super().generic_visit(node)
+
+		def visit_Expr(self, node: ast.Expr) -> ast.AST | list[ast.stmt]:
+			if ifThis.CallDoesNotCallItselfAndNameDOTidIsIn(self.dictionaryReplacementStatements)(node.value):
+				return self.dictionaryReplacementStatements[node.value.func.id] # type: ignore[attr-defined]
+			return node
+
+		def visit_Assign(self, node: ast.Assign) -> ast.AST | list[ast.stmt]:
+			if ifThis.CallDoesNotCallItselfAndNameDOTidIsIn(self.dictionaryReplacementStatements)(node.value):
+				return self.dictionaryReplacementStatements[node.value.func.id] # type: ignore[attr-defined]
+			return node
+
+		def visit_Call(self, node: ast.Call) -> ast.AST | list[ast.stmt]:
+			if ifThis.CallDoesNotCallItselfAndNameDOTidIsIn(self.dictionaryReplacementStatements)(node):
+				replacement = self.dictionaryReplacementStatements[node.func.id] # type: ignore[attr-defined]
+				if not isinstance(replacement, list):
+					return replacement
+			return node
+
+	keepGoing = True
+	ImaInlineFunction = deepcopy(astFunctionDef)
+	while keepGoing:
+		ImaInlineFunction = deepcopy(astFunctionDef)
+		FunctionInliner(deepcopy(dictionaryReplacementStatements)).visit(ImaInlineFunction)
+		if ast.unparse(ImaInlineFunction) == ast.unparse(astFunctionDef):
+			keepGoing = False
+		else:
+			astFunctionDef = deepcopy(ImaInlineFunction)
+			ast.fix_missing_locations(astFunctionDef)
+	return ImaInlineFunction
+
+def Z0Z_replaceMatchingASTnodes(astTree: ast.AST, mappingFindReplaceNodes: dict[ast.AST, ast.AST]) -> ast.AST:
+	class TargetedNodeReplacer(ast.NodeTransformer):
+		def __init__(self, mappingFindReplaceNodes: dict[ast.AST, ast.AST]) -> None:
+			self.mappingFindReplaceNodes = mappingFindReplaceNodes
+
+		def visit(self, node: ast.AST) -> ast.AST:
+			for nodeFind, nodeReplace in self.mappingFindReplaceNodes.items():
+				if self.nodesMatchStructurally(node, nodeFind):
+					return nodeReplace
+			return self.generic_visit(node)
+
+		def nodesMatchStructurally(self, nodeSubject: ast.AST | list[Any] | Any, nodePattern: ast.AST | list[Any] | Any) -> bool:
+			if nodeSubject is None or nodePattern is None:
+				return nodeSubject is None and nodePattern is None
+
+			if type(nodeSubject) != type(nodePattern):
+				return False
+
+			if isinstance(nodeSubject, ast.AST):
+				for field, fieldValueSubject in ast.iter_fields(nodeSubject):
+					if field in ('lineno', 'col_offset', 'end_lineno', 'end_col_offset', 'ctx'):
+						continue
+					attrPattern = getattr(nodePattern, field, None)
+					if not self.nodesMatchStructurally(fieldValueSubject, attrPattern):
+						return False
+				return True
+
+			if isinstance(nodeSubject, list) and isinstance(nodePattern, list):
+				nodeSubjectList: list[Any] = nodeSubject
+				nodePatternList: list[Any] = nodePattern
+				return len(nodeSubjectList) == len(nodePatternList) and all(
+					self.nodesMatchStructurally(elementSubject, elementPattern)
+					for elementSubject, elementPattern in zip(nodeSubjectList, nodePatternList)
+				)
+
+			return nodeSubject == nodePattern
+
+	astTreeCurrent, astTreePrevious = None, astTree
+	while astTreeCurrent is None or ast.unparse(astTreeCurrent) != ast.unparse(astTreePrevious):
+		astTreePrevious = astTreeCurrent if astTreeCurrent else astTree
+		astTreeCurrent = TargetedNodeReplacer(mappingFindReplaceNodes).visit(astTreePrevious)
+
+	return astTreeCurrent
+
+def write_astModule(ingredients: IngredientsModule, pathFilename: str | PathLike[Any] | PurePath, packageName: ast_Identifier | None = None) -> None:
+	astModule = ingredients.export()
+	ast.fix_missing_locations(astModule)
+	pythonSource: str = ast.unparse(astModule)
+	if not pythonSource: raise raiseIfNoneGitHubIssueNumber3
+	autoflake_additional_imports: list[str] = ingredients.imports.exportListModuleNames()
+	if packageName:
+		autoflake_additional_imports.append(packageName)
+	pythonSource = autoflake_fix_code(pythonSource, autoflake_additional_imports, expand_star_imports=False, remove_all_unused_imports=False, remove_duplicate_keys = False, remove_unused_variables = False)
+	writeStringToHere(pythonSource, pathFilename)