mapFolding 0.8.6__py3-none-any.whl → 0.9.1__py3-none-any.whl

mapFolding/someAssemblyRequired/transformationTools.py

@@ -1,27 +1,23 @@
 """
-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.
+AST Transformation Tools for Python Code Generation
+
+This module provides tools for manipulating and transforming Python abstract syntax trees
+to generate optimized code. It implements a system that:
+
+1. Extracts functions and classes from existing modules.
+2. Reshapes and transforms them through AST manipulation.
+3. Manages dependencies and imports.
+4. Generates optimized code with specialized implementations.
+
+The module is particularly focused on transforming general-purpose Python code into
+high-performance implementations, especially through dataclass decomposition and
+function inlining for Numba compatibility.
+
+At its core, the module implements a transformation assembly-line where code flows from
+readable, maintainable implementations to highly optimized versions while preserving
+logical structure and correctness.
 """
+
 from autoflake import fix_code as autoflake_fix_code
 from collections.abc import Callable, Mapping
 from copy import deepcopy
@@ -31,8 +27,8 @@ from mapFolding.someAssemblyRequired import (
 	ast_Identifier,
 	be,
 	DOT,
+	grab,
 	ifThis,
-	ImaAnnotationType,
 	importLogicalPath2Callable,
 	IngredientsFunction,
 	IngredientsModule,
@@ -41,75 +37,124 @@ from mapFolding.someAssemblyRequired import (
 	NodeChanger,
 	NodeTourist,
 	parseLogicalPath2astModule,
+	RecipeSynthesizeFlow,
 	ShatteredDataclass,
 	str_nameDOTname,
 	Then,
-	TypeCertified,
-	又,
+	个,
 )
-from mapFolding.theSSOT import ComputationState, The, raiseIfNoneGitHubIssueNumber3
+from mapFolding.theSSOT import ComputationState, raiseIfNoneGitHubIssueNumber3, The
 from os import PathLike
 from pathlib import Path, PurePath
 from typing import Any, Literal, overload
 import ast
 import dataclasses
 import pickle
+import python_minifier
 
 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 and wraps it in an IngredientsFunction object along with its import context.
+
+	Parameters:
+		astModule: The AST module containing the function definition.
+		identifierFunctionDef: The name of the function to extract.
+
+	Returns:
+		An IngredientsFunction object containing the function definition and its imports.
+
+	Raises:
+		raiseIfNoneGitHubIssueNumber3: If the function definition is not found.
+	"""
 	astFunctionDef = extractFunctionDef(astModule, identifierFunctionDef)
 	if not astFunctionDef: raise raiseIfNoneGitHubIssueNumber3
 	return IngredientsFunction(astFunctionDef, LedgerOfImports(astModule))
 
 def extractClassDef(module: ast.AST, identifier: ast_Identifier) -> ast.ClassDef | None:
-	return NodeTourist(ifThis.isClassDef_Identifier(identifier), Then.getIt).captureLastMatch(module)
+	"""
+	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:
+		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:
-	return NodeTourist(ifThis.isFunctionDef_Identifier(identifier), Then.getIt).captureLastMatch(module)
+	"""
+	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: The matching function definition AST node, or None if not found.
+	"""
+	return NodeTourist(ifThis.isFunctionDef_Identifier(identifier), Then.extractIt).captureLastMatch(module)
+
+def makeDictionaryFunctionDef(module: ast.Module) -> dict[ast_Identifier, ast.FunctionDef]:
+	"""
+	Create a dictionary mapping function names to their AST definitions.
+
+	This function creates a dictionary that maps function names to their AST function
+	definition nodes for all functions defined in the given module.
 
-def makeDictionaryFunctionDef(module: ast.AST) -> dict[ast_Identifier, ast.FunctionDef]:
+	Parameters:
+		module: The AST module to extract function definitions from.
+
+	Returns:
+		A dictionary mapping function identifiers to their AST function definition nodes.
+	"""
 	dictionaryIdentifier2FunctionDef: dict[ast_Identifier, ast.FunctionDef] = {}
-	NodeTourist(be.FunctionDef, Then.updateKeyValueIn(DOT.name, Then.getIt, dictionaryIdentifier2FunctionDef)).visit(module)
+	NodeTourist(lambda node: isinstance(node, ast.FunctionDef), Then.updateKeyValueIn(DOT.name, Then.extractIt, dictionaryIdentifier2FunctionDef)).visit(module) # type: ignore
 	return dictionaryIdentifier2FunctionDef
 
-def makeDictionary4InliningFunction(identifierToInline: ast_Identifier, dictionaryFunctionDef: dict[ast_Identifier, ast.FunctionDef], FunctionDefToInline: ast.FunctionDef | None = None) -> dict[str, ast.FunctionDef]:
+def inlineFunctionDef(identifierToInline: ast_Identifier, module: ast.Module) -> ast.FunctionDef:
 	"""
-	Creates a dictionary of function definitions required for inlining a target function.
-	This function analyzes a target function and recursively collects all function definitions
-	that are called within it (and any functions called by those functions), preparing them for inlining.
+	Inline function calls within a function definition to create a self-contained function.
+
+	This function takes a function identifier and a module, finds the function definition,
+	and then recursively inlines all function calls within that function with their
+	implementation bodies. This produces a fully inlined function that doesn't depend
+	on other function definitions from the module.
+
 	Parameters:
-	----------
-	identifierToInline : ast_Identifier
-		The identifier of the function to be inlined.
-	dictionaryFunctionDef : dict[ast_Identifier, ast.FunctionDef]
-		A dictionary mapping function identifiers to their AST function definitions.
-	FunctionDefToInline : ast.FunctionDef | None, optional
-		The AST function definition to inline. If None, it will be retrieved from dictionaryFunctionDef using identifierToInline.
+		identifierToInline: The name of the function to inline.
+		module: The AST module containing the function and its dependencies.
+
 	Returns:
-	-------
-	dict[str, ast.FunctionDef]
-		A dictionary mapping function names to their AST function definitions, containing all functions needed for inlining.
+		A modified function definition with all function calls inlined.
+
 	Raises:
-	------
-	ValueError
-		If the function to inline is not found in the dictionary, or if recursion is detected during analysis.
-	Notes:
-	-----
-	The function performs a recursive analysis to find all dependent functions needed for inlining.
-	It detects and prevents recursive function calls that could cause infinite inlining.
+		ValueError: If the function to inline is not found in the module.
 	"""
-	if FunctionDefToInline is None:
-		try:
-			FunctionDefToInline = dictionaryFunctionDef[identifierToInline]
-		except KeyError as ERRORmessage:
-			raise ValueError(f"FunctionDefToInline not found in dictionaryIdentifier2FunctionDef: {identifierToInline = }") from ERRORmessage
+	dictionaryFunctionDef: dict[ast_Identifier, ast.FunctionDef] = makeDictionaryFunctionDef(module)
+	try:
+		FunctionDefToInline = dictionaryFunctionDef[identifierToInline]
+	except KeyError as ERRORmessage:
+		raise ValueError(f"FunctionDefToInline not found in dictionaryIdentifier2FunctionDef: {identifierToInline = }") from ERRORmessage
 
 	listIdentifiersCalledFunctions: list[ast_Identifier] = []
-	findIdentifiersToInline = NodeTourist(ifThis.isCallToName, lambda node: Then.appendTo(listIdentifiersCalledFunctions)(DOT.id(DOT.func(node)))) # pyright: ignore[reportArgumentType]
+	findIdentifiersToInline = NodeTourist(ifThis.isCallToName, lambda node: Then.appendTo(listIdentifiersCalledFunctions)(DOT.id(DOT.func(node)))) # type: ignore
 	findIdentifiersToInline.visit(FunctionDefToInline)
 
 	dictionary4Inlining: dict[ast_Identifier, ast.FunctionDef] = {}
 	for identifier in sorted(set(listIdentifiersCalledFunctions).intersection(dictionaryFunctionDef.keys())):
-		dictionary4Inlining[identifier] = dictionaryFunctionDef[identifier]
+		if NodeTourist(ifThis.matchesMeButNotAnyDescendant(ifThis.isCall_Identifier(identifier)), Then.extractIt).captureLastMatch(module) is not None:
+			dictionary4Inlining[identifier] = dictionaryFunctionDef[identifier]
 
 	keepGoing = True
 	while keepGoing:
@@ -117,17 +162,30 @@ def makeDictionary4InliningFunction(identifierToInline: ast_Identifier, dictiona
 		listIdentifiersCalledFunctions.clear()
 		findIdentifiersToInline.visit(Make.Module(list(dictionary4Inlining.values())))
 
-		# NOTE: This is simple not comprehensive recursion protection. # TODO think about why I dislike `ifThis.CallDoesNotCallItself`
-		if identifierToInline in listIdentifiersCalledFunctions: raise ValueError(f"Recursion found: {identifierToInline = }.")
-
 		listIdentifiersCalledFunctions = sorted((set(listIdentifiersCalledFunctions).difference(dictionary4Inlining.keys())).intersection(dictionaryFunctionDef.keys()))
 		if len(listIdentifiersCalledFunctions) > 0:
 			keepGoing = True
 			for identifier in listIdentifiersCalledFunctions:
-				if identifier in dictionaryFunctionDef:
-					dictionary4Inlining[identifier] = dictionaryFunctionDef[identifier]
-
-	return dictionary4Inlining
+				if NodeTourist(ifThis.matchesMeButNotAnyDescendant(ifThis.isCall_Identifier(identifier)), Then.extractIt).captureLastMatch(module) is not None:
+					FunctionDefTarget = dictionaryFunctionDef[identifier]
+					if len(FunctionDefTarget.body) == 1:
+						inliner = NodeChanger(ifThis.isCall_Identifier(identifier), Then.replaceWith(FunctionDefTarget.body[0].value)) # type: ignore
+						for astFunctionDef in dictionary4Inlining.values():
+							inliner.visit(astFunctionDef)
+					else:
+						inliner = NodeChanger(ifThis.isAssignAndValueIs(ifThis.isCall_Identifier(identifier)),Then.replaceWith(FunctionDefTarget.body[0:-1]))
+						for astFunctionDef in dictionary4Inlining.values():
+							inliner.visit(astFunctionDef)
+
+	for identifier, FunctionDefTarget in dictionary4Inlining.items():
+		if len(FunctionDefTarget.body) == 1:
+			inliner = NodeChanger(ifThis.isCall_Identifier(identifier), Then.replaceWith(FunctionDefTarget.body[0].value)) # type: ignore
+			inliner.visit(FunctionDefToInline)
+		else:
+			inliner = NodeChanger(ifThis.isAssignAndValueIs(ifThis.isCall_Identifier(identifier)),Then.replaceWith(FunctionDefTarget.body[0:-1]))
+			inliner.visit(FunctionDefToInline)
+	ast.fix_missing_locations(FunctionDefToInline)
+	return FunctionDefToInline
 
 @overload
 def makeInitializedComputationState(mapShape: tuple[int, ...], writeJob: Literal[True], *,  pathFilename: PathLike[str] | PurePath | None = None, **keywordArguments: Any) -> Path: ...
@@ -164,11 +222,28 @@ def makeInitializedComputationState(mapShape: tuple[int, ...], writeJob: bool =
 	else:
 		pathFilenameJob = getPathFilenameFoldsTotal(stateUniversal.mapShape).with_suffix('.pkl')
 
+	# Fix code scanning alert - Consider possible security implications associated with pickle module. #17
 	pathFilenameJob.write_bytes(pickle.dumps(stateUniversal))
 	return pathFilenameJob
 
 @dataclasses.dataclass
 class DeReConstructField2ast:
+	"""
+	Transform a dataclass field into AST node representations for code generation.
+
+	This class extracts and transforms a dataclass Field object into various AST node
+	representations needed for code generation. It handles the conversion of field
+	attributes, type annotations, and metadata into AST constructs that can be used
+	to reconstruct the field in generated code.
+
+	The class is particularly important for decomposing dataclass fields (like those in
+	ComputationState) to enable their use in specialized contexts like Numba-optimized
+	functions, where the full dataclass cannot be directly used but its contents need
+	to be accessible.
+
+	Each field is processed according to its type and metadata to create appropriate
+	variable declarations, type annotations, and initialization code as AST nodes.
+	"""
 	dataclassesDOTdataclassLogicalPathModule: dataclasses.InitVar[str_nameDOTname]
 	dataclassClassDef: dataclasses.InitVar[ast.ClassDef]
 	dataclassesDOTdataclassInstance_Identifier: dataclasses.InitVar[ast_Identifier]
@@ -190,10 +265,10 @@ class DeReConstructField2ast:
 	astName: ast.Name = dataclasses.field(init=False)
 	ast_keyword_field__field: ast.keyword = dataclasses.field(init=False)
 	ast_nameDOTname: ast.Attribute = dataclasses.field(init=False)
-	astAnnotation: ImaAnnotationType = dataclasses.field(init=False)
+	astAnnotation: ast.expr = dataclasses.field(init=False)
 	ast_argAnnotated: ast.arg = dataclasses.field(init=False)
-	astAnnAssignConstructor: ast.AnnAssign = dataclasses.field(init=False)
-	Z0Z_hack: tuple[ast.AnnAssign, str] = dataclasses.field(init=False)
+	astAnnAssignConstructor: ast.AnnAssign|ast.Assign = dataclasses.field(init=False)
+	Z0Z_hack: tuple[ast.AnnAssign|ast.Assign, str] = dataclasses.field(init=False)
 
 	def __post_init__(self, dataclassesDOTdataclassLogicalPathModule: str_nameDOTname, dataclassClassDef: ast.ClassDef, dataclassesDOTdataclassInstance_Identifier: ast_Identifier, field: dataclasses.Field[Any]) -> None:
 		self.compare = field.compare
@@ -211,52 +286,95 @@ class DeReConstructField2ast:
 		self.ast_keyword_field__field = Make.keyword(self.name, self.astName)
 		self.ast_nameDOTname = Make.Attribute(Make.Name(dataclassesDOTdataclassInstance_Identifier), self.name)
 
-		sherpa = NodeTourist(ifThis.isAnnAssign_targetIs(ifThis.isName_Identifier(self.name)), 又.annotation(Then.getIt)).captureLastMatch(dataclassClassDef)
+		sherpa = NodeTourist(ifThis.isAnnAssign_targetIs(ifThis.isName_Identifier(self.name)), Then.extractIt(DOT.annotation)).captureLastMatch(dataclassClassDef) # type: ignore
 		if sherpa is None: raise raiseIfNoneGitHubIssueNumber3
 		else: self.astAnnotation = sherpa
 
 		self.ast_argAnnotated = Make.arg(self.name, self.astAnnotation)
+		"""
+from ast import Module, Expr, Subscript, Name, Tuple, Load
+Subscript(
+value=Name(id='ndarray', ctx=Load()),
+slice=Tuple(
+	elts=[
+	Subscript(
+		value=Name(id='tuple', ctx=Load()),
+		slice=Name(id='int', ctx=Load()),
+		ctx=Load()),
+	Subscript(
+		value=Name(id='dtype', ctx=Load()),
+		slice=Name(id='NumPyLeavesTotal', ctx=Load()),
+		ctx=Load())],
+	ctx=Load()),
+ctx=Load()
+)
 
+		"""
 		dtype = self.metadata.get('dtype', None)
 		if dtype:
 			moduleWithLogicalPath: str_nameDOTname = 'numpy'
-			annotation = 'ndarray'
-			self.ledger.addImportFrom_asStr(moduleWithLogicalPath, annotation)
+			annotationType = 'ndarray'
+			self.ledger.addImportFrom_asStr(moduleWithLogicalPath, annotationType)
+			self.ledger.addImportFrom_asStr(moduleWithLogicalPath, 'dtype')
+			axesSubscript = Make.Subscript(Make.Name('tuple'), Make.Name('uint8'))
+			dtype_asnameName: ast.Name = self.astAnnotation # type: ignore
+			if dtype_asnameName.id == 'Array3D':
+				axesSubscript = Make.Subscript(Make.Name('tuple'), Make.Tuple([Make.Name('uint8'), Make.Name('uint8'), Make.Name('uint8')]))
+			ast_expr = Make.Subscript(Make.Name(annotationType), Make.Tuple([axesSubscript, Make.Subscript(Make.Name('dtype'), dtype_asnameName)]))
 			constructor = 'array'
 			self.ledger.addImportFrom_asStr(moduleWithLogicalPath, constructor)
 			dtypeIdentifier: ast_Identifier = dtype.__name__
-			dtype_asnameName: ast.Name = self.astAnnotation
-			# dtypeIdentifier_asname: ast_Identifier = moduleWithLogicalPath + '_' + dtypeIdentifier
 			self.ledger.addImportFrom_asStr(moduleWithLogicalPath, dtypeIdentifier, dtype_asnameName.id)
-			self.astAnnAssignConstructor = Make.AnnAssign(self.astName, Make.Name(annotation), Make.Call(Make.Name(constructor), list_astKeywords=[Make.keyword('dtype', dtype_asnameName)]))
-			# self.astAnnAssignConstructor = Make.AnnAssign(self.astName, Make.Name(annotation), Make.Call(Make.Name(constructor), list_astKeywords=[Make.keyword('dtype', Make.Name(dtypeIdentifier_asname))]))
-			# self.astAnnAssignConstructor = Make.AnnAssign(self.astName, self.astAnnotation, Make.Call(Make.Name(constructor), list_astKeywords=[Make.keyword('dtype', Make.Name(dtypeIdentifier_asname))]))
+			self.astAnnAssignConstructor = Make.AnnAssign(self.astName, ast_expr, Make.Call(Make.Name(constructor), list_astKeywords=[Make.keyword('dtype', dtype_asnameName)]))
+			self.astAnnAssignConstructor = Make.Assign([self.astName], Make.Call(Make.Name(constructor), list_astKeywords=[Make.keyword('dtype', dtype_asnameName)]))
 			self.Z0Z_hack = (self.astAnnAssignConstructor, 'array')
-		elif be.Name(self.astAnnotation):
+		elif isinstance(self.astAnnotation, ast.Name):
 			self.astAnnAssignConstructor = Make.AnnAssign(self.astName, self.astAnnotation, Make.Call(self.astAnnotation, [Make.Constant(-1)]))
-			# self.ledger.addImportFrom_asStr(dataclassesDOTdataclassLogicalPathModule, self.astAnnotation.id)
 			self.Z0Z_hack = (self.astAnnAssignConstructor, 'scalar')
-		elif be.Subscript(self.astAnnotation):
+		elif isinstance(self.astAnnotation, ast.Subscript):
 			elementConstructor: ast_Identifier = self.metadata['elementConstructor']
 			self.ledger.addImportFrom_asStr(dataclassesDOTdataclassLogicalPathModule, elementConstructor)
 			takeTheTuple: ast.Tuple = deepcopy(self.astAnnotation.slice) # type: ignore
 			self.astAnnAssignConstructor = Make.AnnAssign(self.astName, self.astAnnotation, takeTheTuple)
 			self.Z0Z_hack = (self.astAnnAssignConstructor, elementConstructor)
-		if be.Name(self.astAnnotation):
+		if isinstance(self.astAnnotation, ast.Name):
 			self.ledger.addImportFrom_asStr(dataclassesDOTdataclassLogicalPathModule, self.astAnnotation.id) # pyright: ignore [reportUnknownArgumentType, reportUnknownMemberType, reportIJustCalledATypeGuardMethod_WTF]
 
 def shatter_dataclassesDOTdataclass(logicalPathModule: str_nameDOTname, dataclass_Identifier: ast_Identifier, instance_Identifier: ast_Identifier) -> ShatteredDataclass:
 	"""
+	Decompose a dataclass definition into AST components for manipulation and code generation.
+
+	This function breaks down a complete dataclass (like ComputationState) into its constituent
+	parts as AST nodes, enabling fine-grained manipulation of its fields for code generation.
+	It extracts all field definitions, annotations, and metadata, organizing them into a
+	ShatteredDataclass that provides convenient access to AST representations needed for
+	different code generation contexts.
+
+	The function identifies a special "counting variable" (marked with 'theCountingIdentifier'
+	metadata) which is crucial for map folding algorithms, ensuring it's properly accessible
+	in the generated code.
+
+	This decomposition is particularly important when generating optimized code (e.g., for Numba)
+	where dataclass instances can't be directly used but their fields need to be individually
+	manipulated and passed to computational functions.
+
 	Parameters:
-		logicalPathModule: gimme string cuz python is stoopid
-		dataclass_Identifier: The identifier of the dataclass to be dismantled.
-		instance_Identifier: In the synthesized module/function/scope, the identifier that will be used for the instance.
+		logicalPathModule: The fully qualified module path containing the dataclass definition.
+		dataclass_Identifier: The name of the dataclass to decompose.
+		instance_Identifier: The variable name to use for the dataclass instance in generated code.
+
+	Returns:
+		A ShatteredDataclass containing AST representations of all dataclass components,
+		with imports, field definitions, annotations, and repackaging code.
+
+	Raises:
+		ValueError: If the dataclass cannot be found in the specified module or if no counting variable is identified in the dataclass.
 	"""
 	Official_fieldOrder: list[ast_Identifier] = []
 	dictionaryDeReConstruction: dict[ast_Identifier, DeReConstructField2ast] = {}
 
 	dataclassClassDef = extractClassDef(parseLogicalPath2astModule(logicalPathModule), dataclass_Identifier)
-	if not isinstance(dataclassClassDef, ast.ClassDef): raise ValueError(f"I could not find {dataclass_Identifier=} in {logicalPathModule=}.")
+	if not isinstance(dataclassClassDef, ast.ClassDef): raise ValueError(f"I could not find `{dataclass_Identifier = }` in `{logicalPathModule = }`.")
 
 	countingVariable = None
 	for aField in dataclasses.fields(importLogicalPath2Callable(logicalPathModule, dataclass_Identifier)): # pyright: ignore [reportArgumentType]
@@ -266,7 +384,7 @@ def shatter_dataclassesDOTdataclass(logicalPathModule: str_nameDOTname, dataclas
 			countingVariable = dictionaryDeReConstruction[aField.name].name
 
 	if countingVariable is None:
-		raise ValueError(f"I could not find the counting variable in {dataclass_Identifier=} in {logicalPathModule=}.")
+		raise ValueError(f"I could not find the counting variable in `{dataclass_Identifier = }` in `{logicalPathModule = }`.")
 
 	shatteredDataclass = ShatteredDataclass(
 		countingVariableAnnotation=dictionaryDeReConstruction[countingVariable].astAnnotation,
@@ -290,6 +408,31 @@ def shatter_dataclassesDOTdataclass(logicalPathModule: str_nameDOTname, dataclas
 	return shatteredDataclass
 
 def write_astModule(ingredients: IngredientsModule, pathFilename: PathLike[Any] | PurePath, packageName: ast_Identifier | None = None) -> None:
+	"""
+	Convert an IngredientsModule to Python source code and write it to a file.
+
+	This function renders an IngredientsModule into executable Python code,
+	applies code quality improvements like import organization via autoflake,
+	and writes the result to the specified file path.
+
+	The function performs several key steps:
+	1. Converts the AST module structure to a valid Python AST
+	2. Fixes location attributes in the AST for proper formatting
+	3. Converts the AST to Python source code
+	4. Optimizes imports using autoflake
+	5. Writes the final source code to the specified file location
+
+	This is typically the final step in the code generation pipeline,
+	producing optimized Python modules ready for execution.
+
+	Parameters:
+		ingredients: The IngredientsModule containing the module definition.
+		pathFilename: The file path where the module should be written.
+		packageName: Optional package name to preserve in import optimization.
+
+	Raises:
+		raiseIfNoneGitHubIssueNumber3: If the generated source code is empty.
+	"""
 	astModule = Make.Module(ingredients.body, ingredients.type_ignores)
 	ast.fix_missing_locations(astModule)
 	pythonSource: str = ast.unparse(astModule)
@@ -298,19 +441,47 @@ def write_astModule(ingredients: IngredientsModule, pathFilename: PathLike[Any]
 	if packageName:
 		autoflake_additional_imports.append(packageName)
 	pythonSource = autoflake_fix_code(pythonSource, autoflake_additional_imports, expand_star_imports=False, remove_all_unused_imports=True, remove_duplicate_keys = False, remove_unused_variables = False)
+	# pythonSource = python_minifier.minify(pythonSource)
 	writeStringToHere(pythonSource, pathFilename)
 
 # END of acceptable classes and functions ======================================================
+def removeUnusedParameters(ingredientsFunction: IngredientsFunction):
+	list_argCuzMyBrainRefusesToThink = ingredientsFunction.astFunctionDef.args.args + ingredientsFunction.astFunctionDef.args.posonlyargs + ingredientsFunction.astFunctionDef.args.kwonlyargs
+	list_arg_arg: list[ast_Identifier] = [ast_arg.arg for ast_arg in list_argCuzMyBrainRefusesToThink]
+	listName: list[ast.Name] = []
+	NodeTourist(be.Name, Then.appendTo(listName)).visit(ingredientsFunction.astFunctionDef)
+	list_Identifiers: list[ast_Identifier] = [astName.id for astName in listName]
+	list_IdentifiersNotUsed: list[ast_Identifier] = list(set(list_arg_arg) - set(list_Identifiers))
+
 dictionaryEstimates: dict[tuple[int, ...], int] = {
-	(2,2,2,2,2,2,2,2): 362794844160000,
-	(2,21): 1493028892051200,
-	(3,15): 9842024675968800,
+	(2,2,2,2,2,2,2,2): 798148657152000,
+	(2,21): 776374224866624,
+	(3,15): 824761667826225,
 	(3,3,3,3): 85109616000000000000000000000000,
-	(8,8): 129950723279272000,
+	(8,8): 791274195985524900,
 }
 
 # END of marginal classes and functions ======================================================
-def Z0Z_lameFindReplace(astTree, mappingFindReplaceNodes: Mapping[ast.AST, ast.AST]):
+def Z0Z_lameFindReplace(astTree: 个, mappingFindReplaceNodes: Mapping[ast.AST, ast.AST]) -> 个:
+	"""
+	Recursively replace AST nodes based on a mapping of find-replace pairs.
+
+	This function applies brute-force node replacement throughout an AST tree
+	by comparing textual representations of nodes. While not the most efficient
+	approach, it provides a reliable way to replace complex nested structures
+	when more precise targeting methods are difficult to implement.
+
+	The function continues replacing nodes until no more changes are detected
+	in the AST's textual representation, ensuring complete replacement throughout
+	the tree structure.
+
+	Parameters:
+		astTree: The AST structure to modify.
+		mappingFindReplaceNodes: A mapping from source nodes to replacement nodes.
+
+	Returns:
+		The modified AST structure with all matching nodes replaced.
+	"""
 	keepGoing = True
 	newTree = deepcopy(astTree)
 
@@ -324,54 +495,112 @@ def Z0Z_lameFindReplace(astTree, mappingFindReplaceNodes: Mapping[ast.AST, ast.A
 			astTree = deepcopy(newTree)
 	return newTree
 
-# Start of I HATE PROGRAMMING ==========================================================
-def Z0Z_makeDictionaryReplacementStatements(module: ast.AST) -> dict[ast_Identifier, ast.stmt | list[ast.stmt]]:
-	"""Return a dictionary of function names and their replacement statements."""
-	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):
-			dictionaryReplacementStatements[name] = astFunctionDef.body[0].value # type: ignore
-		elif ifThis.onlyReturnUnaryOp(astFunctionDef):
-			dictionaryReplacementStatements[name] = astFunctionDef.body[0].value # type: ignore
-		else:
-			dictionaryReplacementStatements[name] = astFunctionDef.body[0:-1]
-	return dictionaryReplacementStatements
-
-def Z0Z_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
-			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
-			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
-				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 makeNewFlow(recipeFlow: RecipeSynthesizeFlow) -> IngredientsModule:
+	# TODO a tool to automatically remove unused variables from the ArgumentsSpecification (return, and returns) _might_ be nice.
+	# Figure out dynamic flow control to synthesized modules https://github.com/hunterhogan/mapFolding/issues/4
+	listAllIngredientsFunctions = [
+	(ingredientsInitialize := astModuleToIngredientsFunction(recipeFlow.source_astModule, recipeFlow.sourceCallableInitialize)),
+	(ingredientsParallel := astModuleToIngredientsFunction(recipeFlow.source_astModule, recipeFlow.sourceCallableParallel)),
+	(ingredientsSequential := astModuleToIngredientsFunction(recipeFlow.source_astModule, recipeFlow.sourceCallableSequential)),
+	(ingredientsDispatcher := astModuleToIngredientsFunction(recipeFlow.source_astModule, recipeFlow.sourceCallableDispatcher)),
+	]
+
+	# Inline functions ========================================================
+	# NOTE Replacements statements are based on the identifiers in the _source_, so operate on the source identifiers.
+	ingredientsInitialize.astFunctionDef = inlineFunctionDef(recipeFlow.sourceCallableInitialize, recipeFlow.source_astModule)
+	ingredientsParallel.astFunctionDef = inlineFunctionDef(recipeFlow.sourceCallableParallel, recipeFlow.source_astModule)
+	ingredientsSequential.astFunctionDef = inlineFunctionDef(recipeFlow.sourceCallableSequential, recipeFlow.source_astModule)
+
+	# assignRecipeIdentifiersToCallable. =============================
+	# Consolidate settings classes through inheritance https://github.com/hunterhogan/mapFolding/issues/15
+	# How can I use dataclass settings as the SSOT for specific actions? https://github.com/hunterhogan/mapFolding/issues/16
+	# NOTE reminder: you are updating these `ast.Name` here (and not in a more general search) because this is a
+	# narrow search for `ast.Call` so you won't accidentally replace unrelated `ast.Name`.
+	listFindReplace = [(recipeFlow.sourceCallableDispatcher, recipeFlow.callableDispatcher),
+						(recipeFlow.sourceCallableInitialize, recipeFlow.callableInitialize),
+						(recipeFlow.sourceCallableParallel, recipeFlow.callableParallel),
+						(recipeFlow.sourceCallableSequential, recipeFlow.callableSequential),]
+	for ingredients in listAllIngredientsFunctions:
+		for source_Identifier, recipe_Identifier in listFindReplace:
+			updateCallName = NodeChanger(ifThis.isCall_Identifier(source_Identifier), grab.funcAttribute(Then.replaceWith(Make.Name(recipe_Identifier))))
+			updateCallName.visit(ingredients.astFunctionDef)
+
+	ingredientsDispatcher.astFunctionDef.name = recipeFlow.callableDispatcher
+	ingredientsInitialize.astFunctionDef.name = recipeFlow.callableInitialize
+	ingredientsParallel.astFunctionDef.name = recipeFlow.callableParallel
+	ingredientsSequential.astFunctionDef.name = recipeFlow.callableSequential
+
+	# Assign identifiers per the recipe. ==============================
+	listFindReplace = [(recipeFlow.sourceDataclassInstance, recipeFlow.dataclassInstance),
+		(recipeFlow.sourceDataclassInstanceTaskDistribution, recipeFlow.dataclassInstanceTaskDistribution),
+		(recipeFlow.sourceConcurrencyManagerNamespace, recipeFlow.concurrencyManagerNamespace),]
+	for ingredients in listAllIngredientsFunctions:
+		for source_Identifier, recipe_Identifier in listFindReplace:
+			updateName = NodeChanger(ifThis.isName_Identifier(source_Identifier) , grab.idAttribute(Then.replaceWith(recipe_Identifier)))
+			update_arg = NodeChanger(ifThis.isArgument_Identifier(source_Identifier), grab.argAttribute(Then.replaceWith(recipe_Identifier)))
+			updateName.visit(ingredients.astFunctionDef)
+			update_arg.visit(ingredients.astFunctionDef)
+
+	updateConcurrencyManager = NodeChanger(ifThis.isCallAttributeNamespace_Identifier(recipeFlow.sourceConcurrencyManagerNamespace, recipeFlow.sourceConcurrencyManagerIdentifier)
+										, grab.funcAttribute(Then.replaceWith(Make.Attribute(Make.Name(recipeFlow.concurrencyManagerNamespace), recipeFlow.concurrencyManagerIdentifier))))
+	updateConcurrencyManager.visit(ingredientsDispatcher.astFunctionDef)
+
+	# shatter Dataclass =======================================================
+	instance_Identifier = recipeFlow.dataclassInstance
+	getTheOtherRecord_damn = recipeFlow.dataclassInstanceTaskDistribution
+	shatteredDataclass = shatter_dataclassesDOTdataclass(recipeFlow.logicalPathModuleDataclass, recipeFlow.sourceDataclassIdentifier, instance_Identifier)
+	ingredientsDispatcher.imports.update(shatteredDataclass.ledger)
+
+	# How can I use dataclass settings as the SSOT for specific actions? https://github.com/hunterhogan/mapFolding/issues/16
+	# Change callable parameters and Call to the callable at the same time ====
+	# sequentialCallable =========================================================
+	if recipeFlow.removeDataclassSequential:
+		ingredientsSequential.astFunctionDef.args = Make.argumentsSpecification(args=shatteredDataclass.list_argAnnotated4ArgumentsSpecification)
+		astCallSequentialCallable = Make.Call(Make.Name(recipeFlow.callableSequential), shatteredDataclass.listName4Parameters)
+		changeReturnSequentialCallable = NodeChanger(be.Return, Then.replaceWith(Make.Return(shatteredDataclass.fragments4AssignmentOrParameters)))
+		ingredientsSequential.astFunctionDef.returns = shatteredDataclass.signatureReturnAnnotation
+		replaceAssignSequentialCallable = NodeChanger(ifThis.isAssignAndValueIs(ifThis.isCall_Identifier(recipeFlow.callableSequential)), Then.replaceWith(Make.Assign(listTargets=[shatteredDataclass.fragments4AssignmentOrParameters], value=astCallSequentialCallable)))
+
+		unpack4sequentialCallable = NodeChanger(ifThis.isAssignAndValueIs(ifThis.isCall_Identifier(recipeFlow.callableSequential)), Then.insertThisAbove(shatteredDataclass.listUnpack))
+		repack4sequentialCallable = NodeChanger(ifThis.isAssignAndValueIs(ifThis.isCall_Identifier(recipeFlow.callableSequential)), Then.insertThisBelow([shatteredDataclass.repack]))
+
+		changeReturnSequentialCallable.visit(ingredientsSequential.astFunctionDef)
+		replaceAssignSequentialCallable.visit(ingredientsDispatcher.astFunctionDef)
+		unpack4sequentialCallable.visit(ingredientsDispatcher.astFunctionDef)
+		repack4sequentialCallable.visit(ingredientsDispatcher.astFunctionDef)
+
+		ingredientsSequential.astFunctionDef = Z0Z_lameFindReplace(ingredientsSequential.astFunctionDef, shatteredDataclass.map_stateDOTfield2Name)
+
+	# parallelCallable =========================================================
+	if recipeFlow.removeDataclassParallel:
+		ingredientsParallel.astFunctionDef.args = Make.argumentsSpecification(args=shatteredDataclass.list_argAnnotated4ArgumentsSpecification)
+		replaceCall2concurrencyManager = NodeChanger(ifThis.isCallAttributeNamespace_Identifier(recipeFlow.concurrencyManagerNamespace, recipeFlow.concurrencyManagerIdentifier), Then.replaceWith(Make.Call(Make.Attribute(Make.Name(recipeFlow.concurrencyManagerNamespace), recipeFlow.concurrencyManagerIdentifier), listArguments=[Make.Name(recipeFlow.callableParallel)] + shatteredDataclass.listName4Parameters)))
+
+		# NOTE I am dissatisfied with this logic for many reasons, including that it requires separate NodeCollector and NodeReplacer instances.
+		astCallConcurrencyResult: list[ast.Call] = []
+		get_astCallConcurrencyResult = NodeTourist(ifThis.isAssignAndTargets0Is(ifThis.isSubscript_Identifier(getTheOtherRecord_damn)), getIt(astCallConcurrencyResult))
+		get_astCallConcurrencyResult.visit(ingredientsDispatcher.astFunctionDef)
+		replaceAssignParallelCallable = NodeChanger(ifThis.isAssignAndTargets0Is(ifThis.isSubscript_Identifier(getTheOtherRecord_damn)), grab.valueAttribute(Then.replaceWith(astCallConcurrencyResult[0])))
+		replaceAssignParallelCallable.visit(ingredientsDispatcher.astFunctionDef)
+		changeReturnParallelCallable = NodeChanger(be.Return, Then.replaceWith(Make.Return(shatteredDataclass.countingVariableName)))
+		ingredientsParallel.astFunctionDef.returns = shatteredDataclass.countingVariableAnnotation
+
+		unpack4parallelCallable = NodeChanger(ifThis.isAssignAndValueIs(ifThis.isCallAttributeNamespace_Identifier(recipeFlow.concurrencyManagerNamespace, recipeFlow.concurrencyManagerIdentifier)), Then.insertThisAbove(shatteredDataclass.listUnpack))
+
+		unpack4parallelCallable.visit(ingredientsDispatcher.astFunctionDef)
+		replaceCall2concurrencyManager.visit(ingredientsDispatcher.astFunctionDef)
+		changeReturnParallelCallable.visit(ingredientsParallel.astFunctionDef)
+
+		ingredientsParallel.astFunctionDef = Z0Z_lameFindReplace(ingredientsParallel.astFunctionDef, shatteredDataclass.map_stateDOTfield2Name)
+
+	# Module-level transformations ===========================================================
+	ingredientsModuleNumbaUnified = IngredientsModule(ingredientsFunction=listAllIngredientsFunctions, imports=LedgerOfImports(recipeFlow.source_astModule))
+	ingredientsModuleNumbaUnified.removeImportFromModule('numpy')
+
+	return ingredientsModuleNumbaUnified
+
+def getIt(astCallConcurrencyResult: list[ast.Call]) -> Callable[[ast.AST], ast.AST]:
+	def workhorse(node: ast.AST) -> ast.AST:
+		NodeTourist(be.Call, Then.appendTo(astCallConcurrencyResult)).visit(node)
+		return node
+	return workhorse