mapFolding 0.8.3__py3-none-any.whl → 0.8.5__py3-none-any.whl

mapFolding/someAssemblyRequired/_toolboxContainers.py

@@ -0,0 +1,334 @@
+"""
+Container classes for AST transformations and code synthesis.
+
+This module provides container classes used in the AST transformation process
+and code synthesis workflows. It acts as a dependency boundary to prevent
+circular imports while providing reusable data structures.
+"""
+from collections import defaultdict
+from collections.abc import Sequence
+from mapFolding.someAssemblyRequired import ImaAnnotationType, ast_Identifier, be, Make, parseLogicalPath2astModule, str_nameDOTname
+from mapFolding.theSSOT import callableDispatcherHARDCODED, The
+from pathlib import Path, PurePosixPath
+from Z0Z_tools import updateExtendPolishDictionaryLists
+import ast
+import dataclasses
+
+class LedgerOfImports:
+	# TODO When resolving the ledger of imports, remove self-referential imports
+	# TODO TypeIgnore :/
+
+	def __init__(self, startWith: ast.AST | None = None) -> None:
+		self.dictionaryImportFrom: dict[str_nameDOTname, list[tuple[ast_Identifier, ast_Identifier | None]]] = defaultdict(list)
+		self.listImport: list[str_nameDOTname] = []
+		if startWith:
+			self.walkThis(startWith)
+
+	def addAst(self, astImport____: ast.Import | ast.ImportFrom) -> None:
+		assert isinstance(astImport____, (ast.Import, ast.ImportFrom)), f"I received {type(astImport____) = }, but I can only accept {ast.Import} and {ast.ImportFrom}."
+		if be.Import(astImport____):
+			for alias in astImport____.names:
+				self.listImport.append(alias.name)
+		elif be.ImportFrom(astImport____):
+			# TODO fix the mess created by `None` means '.'. I need a `str_nameDOTname` to replace '.'
+			if astImport____.module is None:
+				astImport____.module = '.'
+			for alias in astImport____.names:
+				self.dictionaryImportFrom[astImport____.module].append((alias.name, alias.asname))
+
+	def addImport_asStr(self, moduleIdentifier: str_nameDOTname) -> None:
+		self.listImport.append(moduleIdentifier)
+
+	def addImportFrom_asStr(self, moduleIdentifier: ast_Identifier, name: ast_Identifier, asname: ast_Identifier | None = None) -> None:
+		self.dictionaryImportFrom[moduleIdentifier].append((name, asname))
+
+	def exportListModuleIdentifiers(self) -> list[ast_Identifier]:
+		listModuleIdentifiers: list[ast_Identifier] = list(self.dictionaryImportFrom.keys())
+		listModuleIdentifiers.extend(self.listImport)
+		return sorted(set(listModuleIdentifiers))
+
+	def makeList_ast(self) -> list[ast.ImportFrom | ast.Import]:
+		listImportFrom: list[ast.ImportFrom] = []
+		for moduleIdentifier, listOfNameTuples in sorted(self.dictionaryImportFrom.items()):
+			listOfNameTuples = sorted(list(set(listOfNameTuples)), key=lambda nameTuple: nameTuple[0])
+			list_alias: list[ast.alias] = []
+			for name, asname in listOfNameTuples:
+				list_alias.append(Make.alias(name, asname))
+			listImportFrom.append(Make.ImportFrom(moduleIdentifier, list_alias))
+		list_astImport: list[ast.Import] = [Make.Import(moduleIdentifier) for moduleIdentifier in sorted(set(self.listImport))]
+		return listImportFrom + list_astImport
+
+	def update(self, *fromLedger: 'LedgerOfImports') -> None:
+		"""Update this ledger with imports from one or more other ledgers.
+		Parameters:
+			*fromLedger: One or more other `LedgerOfImports` objects from which to merge.
+		"""
+		self.dictionaryImportFrom = updateExtendPolishDictionaryLists(self.dictionaryImportFrom, *(ledger.dictionaryImportFrom for ledger in fromLedger), destroyDuplicates=True, reorderLists=True)
+		for ledger in fromLedger:
+			self.listImport.extend(ledger.listImport)
+
+	def walkThis(self, walkThis: ast.AST) -> None:
+		for nodeBuffalo in ast.walk(walkThis):
+			if isinstance(nodeBuffalo, (ast.Import, ast.ImportFrom)):
+				self.addAst(nodeBuffalo)
+
+@dataclasses.dataclass
+class IngredientsFunction:
+	"""Everything necessary to integrate a function into a module should be here.
+	Parameters:
+		astFunctionDef: hint `Make.astFunctionDef()`
+	"""
+	astFunctionDef: ast.FunctionDef
+	imports: LedgerOfImports = dataclasses.field(default_factory=LedgerOfImports)
+	type_ignores: list[ast.TypeIgnore] = dataclasses.field(default_factory=list)
+
+@dataclasses.dataclass
+class IngredientsModule:
+	"""Everything necessary to create one _logical_ `ast.Module` should be here.
+	Extrinsic qualities should _probably_ be handled externally.
+
+	Parameters:
+		ingredientsFunction (None): One or more `IngredientsFunction` that will appended to `listIngredientsFunctions`.
+	"""
+	ingredientsFunction: dataclasses.InitVar[Sequence[IngredientsFunction] | IngredientsFunction | None] = None
+
+	# init var with an existing module? method to deconstruct an existing module?
+
+	# `body` attribute of `ast.Module`
+	"""NOTE
+	- Bare statements in `prologue` and `epilogue` are not 'protected' by `if __name__ == '__main__':` so they will be executed merely by loading the module.
+	- The dataclass has methods for modifying `prologue`, `epilogue`, and `launcher`.
+	- However, `prologue`, `epilogue`, and `launcher` are `ast.Module` (as opposed to `list[ast.stmt]`), so that you may use tools such as `ast.walk` and `ast.NodeVisitor` on the fields.
+	"""
+	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([],[])
+	"""`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)
+
+	def __post_init__(self, ingredientsFunction: Sequence[IngredientsFunction] | IngredientsFunction | None = None) -> None:
+		if ingredientsFunction is not None:
+			if isinstance(ingredientsFunction, IngredientsFunction):
+				self.appendIngredientsFunction(ingredientsFunction)
+			else:
+				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 be.Module(astModule):
+			list_body.extend(astModule.body)
+			listTypeIgnore.extend(astModule.type_ignores)
+		if type_ignores is not None:
+			listTypeIgnore.extend(type_ignores)
+		if statement is not None:
+			if isinstance(statement, Sequence):
+				list_body.extend(statement)
+			else:
+				list_body.append(statement)
+		self_astModule.body.extend(list_body)
+		self_astModule.type_ignores.extend(listTypeIgnore)
+		ast.fix_missing_locations(self_astModule)
+
+	def appendPrologue(self, astModule: ast.Module | None = None, statement: Sequence[ast.stmt] | ast.stmt | None = None, type_ignores: list[ast.TypeIgnore] | None = None) -> None:
+		"""Append one or more statements to `prologue`."""
+		self._append_astModule(self.prologue, astModule, statement, type_ignores)
+
+	def appendEpilogue(self, astModule: ast.Module | None = None, statement: Sequence[ast.stmt] | ast.stmt | None = None, type_ignores: list[ast.TypeIgnore] | None = None) -> None:
+		"""Append one or more statements to `epilogue`."""
+		self._append_astModule(self.epilogue, astModule, statement, type_ignores)
+
+	def appendLauncher(self, astModule: ast.Module | None = None, statement: Sequence[ast.stmt] | ast.stmt | None = None, type_ignores: list[ast.TypeIgnore] | None = None) -> None:
+		"""Append one or more statements to `launcher`."""
+		self._append_astModule(self.launcher, astModule, statement, type_ignores)
+
+	def appendIngredientsFunction(self, *ingredientsFunction: IngredientsFunction) -> None:
+		"""Append one or more `IngredientsFunction`."""
+		for allegedIngredientsFunction in ingredientsFunction:
+			if isinstance(allegedIngredientsFunction, IngredientsFunction):
+				self.listIngredientsFunctions.append(allegedIngredientsFunction)
+			else:
+				raise ValueError(f"I received `{type(allegedIngredientsFunction) = }`, but I can only accept `{IngredientsFunction}`.")
+
+	@property
+	def list_astImportImportFrom(self) -> list[ast.Import | ast.ImportFrom]:
+		"""List of `ast.Import` and `ast.ImportFrom` statements."""
+		sherpaLedger = LedgerOfImports()
+		listLedgers: list[LedgerOfImports] = [self.imports]
+		for ingredientsFunction in self.listIngredientsFunctions:
+			listLedgers.append(ingredientsFunction.imports)
+		sherpaLedger.update(*listLedgers)
+		return sherpaLedger.makeList_ast()
+
+	@property
+	def body(self) -> list[ast.stmt]:
+		list_stmt: list[ast.stmt] = []
+		list_stmt.extend(self.list_astImportImportFrom)
+		list_stmt.extend(self.prologue.body)
+		for ingredientsFunction in self.listIngredientsFunctions:
+			list_stmt.append(ingredientsFunction.astFunctionDef)
+		list_stmt.extend(self.epilogue.body)
+		list_stmt.extend(self.launcher.body)
+		# TODO `launcher`, if it exists, must start with `if __name__ == '__main__':` and be indented
+		return list_stmt
+
+	@property
+	def type_ignores(self) -> list[ast.TypeIgnore]:
+		listTypeIgnore: list[ast.TypeIgnore] = self.supplemental_type_ignores
+		# listTypeIgnore.extend(self.imports.makeListAst())
+		listTypeIgnore.extend(self.prologue.type_ignores)
+		for ingredientsFunction in self.listIngredientsFunctions:
+			listTypeIgnore.extend(ingredientsFunction.type_ignores)
+		listTypeIgnore.extend(self.epilogue.type_ignores)
+		listTypeIgnore.extend(self.launcher.type_ignores)
+		return listTypeIgnore
+
+@dataclasses.dataclass
+class RecipeSynthesizeFlow:
+	"""Settings for synthesizing flow."""
+	# ========================================
+	# Source
+	# ========================================
+	source_astModule = parseLogicalPath2astModule(The.logicalPathModuleSourceAlgorithm)
+
+	# Figure out dynamic flow control to synthesized modules https://github.com/hunterhogan/mapFolding/issues/4
+	sourceCallableDispatcher: ast_Identifier = The.sourceCallableDispatcher
+	sourceCallableInitialize: ast_Identifier = The.sourceCallableInitialize
+	sourceCallableParallel: ast_Identifier = The.sourceCallableParallel
+	sourceCallableSequential: ast_Identifier = The.sourceCallableSequential
+
+	sourceDataclassIdentifier: ast_Identifier = The.dataclassIdentifier
+	sourceDataclassInstance: ast_Identifier = The.dataclassInstance
+	sourceDataclassInstanceTaskDistribution: ast_Identifier = The.dataclassInstanceTaskDistribution
+	sourceLogicalPathModuleDataclass: str_nameDOTname = The.logicalPathModuleDataclass
+
+	sourceConcurrencyManagerNamespace = The.sourceConcurrencyManagerNamespace
+	sourceConcurrencyManagerIdentifier = The.sourceConcurrencyManagerIdentifier
+
+	# ========================================
+	# Logical identifiers (as opposed to physical identifiers)
+	# ========================================
+	# Package ================================
+	packageIdentifier: ast_Identifier | None = The.packageName
+
+	# Qualified logical path ================================
+	logicalPathModuleDataclass: str_nameDOTname = sourceLogicalPathModuleDataclass
+	logicalPathFlowRoot: ast_Identifier | None = 'syntheticModules'
+	""" `logicalPathFlowRoot` likely corresponds to a physical filesystem directory."""
+
+	# Module ================================
+	moduleDispatcher: ast_Identifier = 'numbaCount_doTheNeedful'
+	moduleInitialize: ast_Identifier = moduleDispatcher
+	moduleParallel: ast_Identifier = moduleDispatcher
+	moduleSequential: ast_Identifier = moduleDispatcher
+
+	# Function ================================
+	callableDispatcher: ast_Identifier = sourceCallableDispatcher
+	callableInitialize: ast_Identifier = sourceCallableInitialize
+	callableParallel: ast_Identifier = sourceCallableParallel
+	callableSequential: ast_Identifier = sourceCallableSequential
+	concurrencyManagerNamespace: ast_Identifier = sourceConcurrencyManagerNamespace
+	concurrencyManagerIdentifier: ast_Identifier = sourceConcurrencyManagerIdentifier
+	dataclassIdentifier: ast_Identifier = sourceDataclassIdentifier
+
+	# Variable ================================
+	dataclassInstance: ast_Identifier = sourceDataclassInstance
+	dataclassInstanceTaskDistribution: ast_Identifier = sourceDataclassInstanceTaskDistribution
+
+	# ========================================
+	# Computed
+	# ========================================
+	"""
+theFormatStrModuleSynthetic = "{packageFlow}Count"
+theFormatStrModuleForCallableSynthetic = theFormatStrModuleSynthetic + "_{callableTarget}"
+theModuleDispatcherSynthetic: ast_Identifier = theFormatStrModuleForCallableSynthetic.format(packageFlow=packageFlowSynthetic, callableTarget=The.sourceCallableDispatcher)
+theLogicalPathModuleDispatcherSynthetic: str = '.'.join([The.packageName, The.moduleOfSyntheticModules, theModuleDispatcherSynthetic])
+
+	"""
+	# logicalPathModuleDispatcher: str = '.'.join([Z0Z_flowLogicalPathRoot, moduleDispatcher])
+	# ========================================
+	# Filesystem (names of physical objects)
+	# ========================================
+	pathPackage: PurePosixPath | None = PurePosixPath(The.pathPackage)
+	fileExtension: str = The.fileExtension
+
+	def _makePathFilename(self, filenameStem: str,
+			pathRoot: PurePosixPath | None = None,
+			logicalPathINFIX: str_nameDOTname | 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.logicalPathFlowRoot)
+	@property
+	def pathFilenameInitialize(self) -> PurePosixPath:
+		return self._makePathFilename(filenameStem=self.moduleInitialize, logicalPathINFIX=self.logicalPathFlowRoot)
+	@property
+	def pathFilenameParallel(self) -> PurePosixPath:
+		return self._makePathFilename(filenameStem=self.moduleParallel, logicalPathINFIX=self.logicalPathFlowRoot)
+	@property
+	def pathFilenameSequential(self) -> PurePosixPath:
+		return self._makePathFilename(filenameStem=self.moduleSequential, logicalPathINFIX=self.logicalPathFlowRoot)
+
+	def __post_init__(self) -> None:
+		if ((self.concurrencyManagerIdentifier is not None and self.concurrencyManagerIdentifier != self.sourceConcurrencyManagerIdentifier) # `submit` # type: ignore
+			or ((self.concurrencyManagerIdentifier is None) != (self.concurrencyManagerNamespace is None))): # type: ignore
+			import warnings
+			warnings.warn(f"If your synthesized module is weird, check `{self.concurrencyManagerIdentifier=}` and `{self.concurrencyManagerNamespace=}`. (ChildProcessError? 'Yeah! Children shouldn't be processing stuff, man.')", category=ChildProcessError, stacklevel=2) # pyright: ignore[reportCallIssue, reportArgumentType] Y'all Pynatics need to be less shrill and focus on making code that doesn't need 8000 error categories.
+
+		# self.logicalPathModuleDispatcher!=logicalPathModuleDispatcherHARDCODED or
+		if self.callableDispatcher!=callableDispatcherHARDCODED:
+			print(f"fyi: `{self.callableDispatcher=}` but\n\t`{callableDispatcherHARDCODED=}`.")
+
+dummyAssign = Make.Assign([Make.Name("dummyTarget")], Make.Constant(None))
+dummySubscript = Make.Subscript(Make.Name("dummy"), Make.Name("slice"))
+dummyTuple = Make.Tuple([Make.Name("dummyElement")])
+
+@dataclasses.dataclass
+class ShatteredDataclass:
+	countingVariableAnnotation: ImaAnnotationType
+	"""Type annotation for the counting variable extracted from the dataclass."""
+	countingVariableName: ast.Name
+	"""AST name node representing the counting variable identifier."""
+	field2AnnAssign: dict[ast_Identifier, ast.AnnAssign] = dataclasses.field(default_factory=dict)
+	"""Maps field names to their corresponding AST call expressions."""
+	Z0Z_field2AnnAssign: dict[ast_Identifier, tuple[ast.AnnAssign, str]] = dataclasses.field(default_factory=dict)
+	fragments4AssignmentOrParameters: ast.Tuple = dummyTuple
+	"""AST tuple used as target for assignment to capture returned fragments."""
+	ledger: LedgerOfImports = dataclasses.field(default_factory=LedgerOfImports)
+	"""Import records for the dataclass and its constituent parts."""
+	list_argAnnotated4ArgumentsSpecification: list[ast.arg] = dataclasses.field(default_factory=list)
+	"""Function argument nodes with annotations for parameter specification."""
+	list_keyword_field__field4init: list[ast.keyword] = dataclasses.field(default_factory=list)
+	"""Keyword arguments for dataclass initialization with field=field format."""
+	listAnnotations: list[ImaAnnotationType] = dataclasses.field(default_factory=list)
+	"""Type annotations for each dataclass field."""
+	listName4Parameters: list[ast.Name] = dataclasses.field(default_factory=list)
+	"""Name nodes for each dataclass field used as function parameters."""
+	listUnpack: list[ast.AnnAssign] = dataclasses.field(default_factory=list)
+	"""Annotated assignment statements to extract fields from dataclass."""
+	map_stateDOTfield2Name: dict[ast.expr, ast.Name] = dataclasses.field(default_factory=dict)
+	"""Maps AST expressions to Name nodes for find-replace operations."""
+	repack: ast.Assign = dummyAssign
+	"""AST assignment statement that reconstructs the original dataclass instance."""
+	signatureReturnAnnotation: ast.Subscript = dummySubscript
+	"""tuple-based return type annotation for function definitions."""

mapFolding/someAssemblyRequired/_toolboxPython.py

@@ -0,0 +1,62 @@
+from collections.abc import Callable, Sequence
+from inspect import getsource as inspect_getsource
+from mapFolding.someAssemblyRequired import ast_Identifier, str_nameDOTname, 个
+from os import PathLike
+from pathlib import Path, PurePath
+from types import ModuleType
+from typing import Any, cast, Generic, TypeGuard
+import ast
+import importlib
+import importlib.util
+
+# TODO Identify the logic that narrows the type and can help the user during static type checking.
+
+class NodeTourist(ast.NodeVisitor, Generic[个]):
+    def __init__(self, findThis: Callable[[个], TypeGuard[个] | bool], doThat: Callable[[个], 个 | None]) -> None:
+        self.findThis = findThis
+        self.doThat = doThat
+        self.nodeCaptured: 个 | None = None
+
+    def visit(self, node: 个) -> None: # pyright: ignore [reportGeneralTypeIssues]
+        if self.findThis(node):
+            nodeActionReturn = self.doThat(node)
+            if nodeActionReturn is not None:
+                self.nodeCaptured = nodeActionReturn
+        self.generic_visit(cast(ast.AST, node))
+
+    def captureLastMatch(self, node: 个) -> 个 | None: # pyright: ignore [reportGeneralTypeIssues]
+        self.nodeCaptured = None
+        self.visit(node)
+        return self.nodeCaptured
+
+class NodeChanger(ast.NodeTransformer, Generic[个]):
+    def __init__(self, findThis: Callable[[个], bool], doThat: Callable[[个], Sequence[个] | 个 | None]) -> None:
+        self.findThis = findThis
+        self.doThat = doThat
+
+    def visit(self, node: 个) -> Sequence[个] | 个 | None: # pyright: ignore [reportGeneralTypeIssues]
+        if self.findThis(node):
+            return self.doThat(node)
+        return super().visit(cast(ast.AST, node))
+
+def importLogicalPath2Callable(logicalPathModule: str_nameDOTname, identifier: ast_Identifier, packageIdentifierIfRelative: ast_Identifier | None = None) -> Callable[..., Any]:
+    moduleImported: ModuleType = importlib.import_module(logicalPathModule, packageIdentifierIfRelative)
+    return getattr(moduleImported, identifier)
+
+def importPathFilename2Callable(pathFilename: PathLike[Any] | PurePath, identifier: ast_Identifier, moduleIdentifier: ast_Identifier | None = None) -> Callable[..., Any]:
+    pathFilename = Path(pathFilename)
+
+    importlibSpecification = importlib.util.spec_from_file_location(moduleIdentifier or pathFilename.stem, pathFilename)
+    if importlibSpecification is None or importlibSpecification.loader is None: raise ImportError(f"I received\n\t`{pathFilename = }`,\n\t`{identifier = }`, and\n\t`{moduleIdentifier = }`.\n\tAfter loading, \n\t`importlibSpecification` {'is `None`' if importlibSpecification is None else 'has a value'} and\n\t`importlibSpecification.loader` is unknown.")
+
+    moduleImported_jk_hahaha: ModuleType = importlib.util.module_from_spec(importlibSpecification)
+    importlibSpecification.loader.exec_module(moduleImported_jk_hahaha)
+    return getattr(moduleImported_jk_hahaha, identifier)
+
+def parseLogicalPath2astModule(logicalPathModule: str_nameDOTname, packageIdentifierIfRelative: ast_Identifier|None=None, mode:str='exec') -> ast.AST:
+    moduleImported: ModuleType = importlib.import_module(logicalPathModule, packageIdentifierIfRelative)
+    sourcePython: str = inspect_getsource(moduleImported)
+    return ast.parse(sourcePython, mode=mode)
+
+def parsePathFilename2astModule(pathFilename: PathLike[Any] | PurePath, mode:str='exec') -> ast.AST:
+    return ast.parse(Path(pathFilename).read_text(), mode=mode)

mapFolding/someAssemblyRequired/getLLVMforNoReason.py

@@ -18,9 +18,9 @@ mapFolding/reference/jobsCompleted/[2x19]/[2x19].ll
 
 This file demonstrates the low-level optimizations that made this previously
 intractable calculation possible. The IR reveals how the abstract algorithm was
-transformed into efficient machine code through Numba's compilation pipeline.
+transformed into efficient machine code through Numba's compilation assembly-line.
 
-While originally part of a tighter integration with the code generation pipeline,
+While originally part of a tighter integration with the code generation assembly-line,
 this module now operates as a standalone utility that can be applied to any module
 containing Numba-compiled functions.
 """

mapFolding/someAssemblyRequired/newInliner.py

@@ -0,0 +1,22 @@
+from collections.abc import Callable
+from copy import deepcopy
+from mapFolding.someAssemblyRequired import ast_Identifier, RecipeSynthesizeFlow, Then, be, ifThis, DOT, 又, NodeChanger
+from mapFolding.someAssemblyRequired.transformationTools import makeDictionary4InliningFunction, makeDictionaryFunctionDef
+from typing import cast
+import ast
+
+def inlineFunctionDef(astFunctionDef: ast.FunctionDef, dictionary4Inlining: dict[ast_Identifier, ast.FunctionDef]) -> ast.FunctionDef:
+
+	return astFunctionDef
+
+# Test code
+testFlow: RecipeSynthesizeFlow = RecipeSynthesizeFlow()
+dictionary4Inlining: dict[ast_Identifier, ast.FunctionDef] = makeDictionary4InliningFunction(
+	testFlow.sourceCallableSequential,
+	(dictionaryFunctionDef := makeDictionaryFunctionDef(testFlow.source_astModule)))
+
+astFunctionDef = dictionaryFunctionDef[testFlow.sourceCallableSequential]
+
+astFunctionDefTransformed = inlineFunctionDef(
+	astFunctionDef,
+	dictionary4Inlining)

mapFolding/someAssemblyRequired/synthesizeNumbaJob.py

@@ -0,0 +1,158 @@
+"""Synthesize one file to compute `foldsTotal` of `mapShape`."""
+from mapFolding.toolboxFilesystem import getPathFilenameFoldsTotal
+from mapFolding.someAssemblyRequired import ast_Identifier, be, ifThis, Make, NodeChanger, Then, IngredientsFunction, IngredientsModule
+from mapFolding.someAssemblyRequired.toolboxNumba import RecipeJob, SpicesJobNumba, decorateCallableWithNumba
+from mapFolding.someAssemblyRequired.transformationTools import astModuleToIngredientsFunction, write_astModule
+from mapFolding.someAssemblyRequired.transformationTools import makeInitializedComputationState
+from mapFolding.theSSOT import The
+from typing import cast
+from Z0Z_tools import autoDecodingRLE
+from pathlib import PurePosixPath
+import ast
+
+list_IdentifiersNotUsedAllHARDCODED = ['concurrencyLimit', 'foldsTotal', 'mapShape',]
+list_IdentifiersNotUsedParallelSequentialHARDCODED = ['indexLeaf']
+list_IdentifiersNotUsedSequentialHARDCODED = ['foldGroups', 'taskDivisions', 'taskIndex',]
+
+list_IdentifiersReplacedHARDCODED = ['groupsOfFolds',]
+
+list_IdentifiersStaticValuesHARDCODED = ['dimensionsTotal', 'leavesTotal',]
+
+list_IdentifiersNotUsedHARDCODED = list_IdentifiersStaticValuesHARDCODED + list_IdentifiersReplacedHARDCODED + list_IdentifiersNotUsedAllHARDCODED + list_IdentifiersNotUsedParallelSequentialHARDCODED + list_IdentifiersNotUsedSequentialHARDCODED
+
+def addLauncherNumbaProgress(ingredientsModule: IngredientsModule, ingredientsFunction: IngredientsFunction, job: RecipeJob, spices: SpicesJobNumba) -> tuple[IngredientsModule, IngredientsFunction]:
+
+	linesLaunch: str = f"""
+if __name__ == '__main__':
+	with ProgressBar(total={job.foldsTotalEstimated}, update_interval=2) as statusUpdate:
+		{job.countCallable}(statusUpdate)
+		foldsTotal = statusUpdate.n * {job.state.leavesTotal}
+		print('map {job.state.mapShape} =', foldsTotal)
+		writeStream = open('{job.pathFilenameFoldsTotal.as_posix()}', 'w')
+		writeStream.write(str(foldsTotal))
+		writeStream.close()
+"""
+	numba_progressPythonClass: ast_Identifier = 'ProgressBar'
+	numba_progressNumbaType: ast_Identifier = 'ProgressBarType'
+	ingredientsModule.imports.addImportFrom_asStr('numba_progress', numba_progressPythonClass)
+	ingredientsModule.imports.addImportFrom_asStr('numba_progress', numba_progressNumbaType)
+
+	ast_argNumbaProgress = ast.arg(arg=spices.numbaProgressBarIdentifier, annotation=ast.Name(id=numba_progressPythonClass, ctx=ast.Load()))
+	ingredientsFunction.astFunctionDef.args.args.append(ast_argNumbaProgress)
+
+	findThis = ifThis.isAugAssign_targetIs(ifThis.isName_Identifier(job.shatteredDataclass.countingVariableName.id))
+	doThat = Then.replaceWith(Make.Expr(Make.Call(Make.Attribute(Make.Name(spices.numbaProgressBarIdentifier),'update'),[Make.Constant(1)])))
+	countWithProgressBar = NodeChanger(findThis, doThat)
+	countWithProgressBar.visit(ingredientsFunction.astFunctionDef)
+
+	ingredientsModule.appendLauncher(ast.parse(linesLaunch))
+
+	return ingredientsModule, ingredientsFunction
+
+def move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsFunction: IngredientsFunction, job: RecipeJob) -> IngredientsFunction:
+	ingredientsFunction.imports.update(job.shatteredDataclass.ledger)
+
+	list_IdentifiersNotUsed = list_IdentifiersNotUsedHARDCODED
+
+	list_argCauseMyBrainRefusesToDoThisTheRightWay = ingredientsFunction.astFunctionDef.args.args + ingredientsFunction.astFunctionDef.args.posonlyargs + ingredientsFunction.astFunctionDef.args.kwonlyargs
+	for ast_arg in list_argCauseMyBrainRefusesToDoThisTheRightWay:
+		if ast_arg.arg in job.shatteredDataclass.field2AnnAssign:
+			if ast_arg.arg in list_IdentifiersNotUsed:
+				pass
+			else:
+				ImaAnnAssign, elementConstructor = job.shatteredDataclass.Z0Z_field2AnnAssign[ast_arg.arg]
+				match elementConstructor:
+					case 'scalar':
+						ImaAnnAssign.value.args[0].value = int(job.state.__dict__[ast_arg.arg])  # type: ignore
+					case 'array':
+						# print(ast.dump(ImaAnnAssign))
+						dataAsStrRLE: str = autoDecodingRLE(job.state.__dict__[ast_arg.arg], addSpaces=True)
+						dataAs_astExpr: ast.expr = cast(ast.Expr, ast.parse(dataAsStrRLE).body[0]).value
+						ImaAnnAssign.value.args = [dataAs_astExpr]  # type: ignore
+					case _:
+						list_exprDOTannotation: list[ast.expr] = []
+						list_exprDOTvalue: list[ast.expr] = []
+						for dimension in job.state.mapShape:
+							list_exprDOTannotation.append(Make.Name(elementConstructor))
+							list_exprDOTvalue.append(Make.Call(Make.Name(elementConstructor), [Make.Constant(dimension)]))
+						ImaAnnAssign.annotation.slice.elts = list_exprDOTannotation # type: ignore
+						ImaAnnAssign.value.elts = list_exprDOTvalue # type: ignore
+
+				ingredientsFunction.astFunctionDef.body.insert(0, ImaAnnAssign)
+
+			findThis = ifThis.is_arg_Identifier(ast_arg.arg)
+			remove_arg = NodeChanger(findThis, Then.removeIt)
+			remove_arg.visit(ingredientsFunction.astFunctionDef)
+
+	ast.fix_missing_locations(ingredientsFunction.astFunctionDef)
+	return ingredientsFunction
+
+def makeJobNumba(job: RecipeJob, spices: SpicesJobNumba):
+		# get the raw ingredients: data and the algorithm
+	ingredientsCount: IngredientsFunction = astModuleToIngredientsFunction(job.source_astModule, job.countCallable)
+
+	# Change the return so you can dynamically determine which variables are not used
+	removeReturnStatement = NodeChanger(be.Return, Then.removeIt)
+	removeReturnStatement.visit(ingredientsCount.astFunctionDef)
+	ingredientsCount.astFunctionDef.returns = Make.Constant(value=None)
+
+	# Remove `foldGroups` and any other unused statements, so you can dynamically determine which variables are not used
+	findThis = ifThis.isAssignAndTargets0Is(ifThis.isSubscript_Identifier('foldGroups'))
+	doThat = Then.removeIt
+	remove_foldGroups = NodeChanger(findThis, doThat)
+	remove_foldGroups.visit(ingredientsCount.astFunctionDef)
+
+	# replace identifiers with static values with their values, so you can dynamically determine which variables are not used
+	list_IdentifiersStaticValues = list_IdentifiersStaticValuesHARDCODED
+	for identifier in list_IdentifiersStaticValues:
+		findThis = ifThis.isName_Identifier(identifier)
+		doThat = Then.replaceWith(Make.Constant(int(job.state.__dict__[identifier])))
+		NodeChanger(findThis, doThat).visit(ingredientsCount.astFunctionDef)
+
+	# This launcher eliminates the use of one identifier, so run it now and you can dynamically determine which variables are not used
+	if spices.useNumbaProgressBar:
+		ingredientsModule = IngredientsModule()
+		ingredientsModule, ingredientsCount = addLauncherNumbaProgress(ingredientsModule, ingredientsCount, job, spices)
+		spices.parametersNumba['nogil'] = True
+
+	ingredientsCount = move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsCount, job)
+
+	ingredientsCount.astFunctionDef.decorator_list = [] # TODO low-priority, handle this more elegantly
+	# TODO when I add the function signature in numba style back to the decorator, the logic needs to handle `ProgressBarType:`
+	ingredientsCount = decorateCallableWithNumba(ingredientsCount, spices.parametersNumba)
+
+	ingredientsModule.appendIngredientsFunction(ingredientsCount)
+
+		# add imports, make str, remove unused imports
+		# put on disk
+	write_astModule(ingredientsModule, job.pathFilenameModule, job.packageIdentifier)
+
+	"""
+	Overview
+	- the code starts life in theDao.py, which has many optimizations;
+		- `makeNumbaOptimizedFlow` increase optimization especially by using numba;
+		- `makeJobNumba` increases optimization especially by limiting its capabilities to just one set of parameters
+	- the synthesized module must run well as a standalone interpreted-Python script
+	- the next major optimization step will (probably) be to use the module synthesized by `makeJobNumba` to compile a standalone executable
+	- Nevertheless, at each major optimization step, the code is constantly being improved and optimized, so everything must be well organized (read: semantic) and able to handle a range of arbitrary upstream and not disrupt downstream transformations
+
+	Necessary
+	- Move the function's parameters to the function body,
+	- initialize identifiers with their state types and values,
+
+	Optimizations
+	- replace static-valued identifiers with their values
+	- narrowly focused imports
+
+	Minutia
+	- do not use `with` statement inside numba jitted code, except to use numba's obj mode
+	"""
+
+if __name__ == '__main__':
+	mapShape = (3,4)
+	state = makeInitializedComputationState(mapShape)
+	pathModule = PurePosixPath(The.pathPackage, 'jobs')
+	pathFilenameFoldsTotal = PurePosixPath(getPathFilenameFoldsTotal(state.mapShape, pathModule))
+	aJob = RecipeJob(state, pathModule=pathModule, pathFilenameFoldsTotal=pathFilenameFoldsTotal)
+	spices = SpicesJobNumba()
+	makeJobNumba(aJob, spices)