mapFolding 0.8.2__py3-none-any.whl → 0.8.4__py3-none-any.whl

mapFolding/someAssemblyRequired/transformDataStructures.py

@@ -20,149 +20,216 @@ While developed for transforming map folding computation state objects, the util
 designed to be applicable to various data structure transformation scenarios.
 """
 
-from collections.abc import Sequence
-from importlib import import_module as importlib_import_module
-from inspect import getsource as inspect_getsource
-from mapFolding.beDRY import outfitCountFolds, validateListDimensions
+from collections.abc import Callable
+from copy import deepcopy
+from mapFolding.beDRY import outfitCountFolds
 from mapFolding.filesystem import getPathFilenameFoldsTotal
 from mapFolding.someAssemblyRequired import (
 	ast_Identifier,
+	be,
 	extractClassDef,
 	ifThis,
-	LedgerOfImports,
+	ImaAnnotationType,
+	importLogicalPath2Callable,
 	Make,
-	NodeCollector,
-	strDotStrCuzPyStoopid,
+	NodeTourist,
+	parseLogicalPath2astModule,
+	str_nameDOTname,
 	Then,
-	Z0Z_executeActionUnlessDescendantMatches,
+	又,
 )
-from mapFolding.theSSOT import ComputationState, The
-from pathlib import Path
-from types import ModuleType
+from mapFolding.someAssemblyRequired._toolboxContainers import LedgerOfImports
+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
 
-# Would `LibCST` be better than `ast` in some cases? https://github.com/hunterhogan/mapFolding/issues/7
-
-countingIdentifierHARDCODED = 'groupsOfFolds'
+# Create dummy AST elements for use as defaults
+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:
-	astAssignDataclassRepack: ast.Assign
-	astSubscriptPrimitiveTupleAnnotations4FunctionDef_returns: ast.Subscript
-	astTuple4AssignTargetsToFragments: ast.Tuple
-	countingVariableAnnotation: ast.expr
+	countingVariableAnnotation: ImaAnnotationType
+	"""Type annotation for the counting variable extracted from the dataclass."""
 	countingVariableName: ast.Name
-	ledgerDataclassANDFragments: LedgerOfImports = dataclasses.field(default_factory=LedgerOfImports)
-	list_ast_argAnnotated4ArgumentsSpecification: list[ast.arg] = dataclasses.field(default_factory=list)
-	list_keyword4DataclassInitialization: list[ast.keyword] = dataclasses.field(default_factory=list)
-	listAnnAssign4DataclassUnpack: list[ast.AnnAssign] = dataclasses.field(default_factory=list)
-	listAnnotations: list[ast.expr] = dataclasses.field(default_factory=list)
-	listNameDataclassFragments4Parameters: list[ast.Name] = dataclasses.field(default_factory=list)
-
-def shatter_dataclassesDOTdataclass(logicalPathModule: strDotStrCuzPyStoopid, dataclass_Identifier: ast_Identifier, instance_Identifier: ast_Identifier) -> ShatteredDataclass:
+	"""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."""
+
+@dataclasses.dataclass
+class DeReConstructField2ast:
+	dataclassesDOTdataclassLogicalPathModule: dataclasses.InitVar[str_nameDOTname]
+	dataclassClassDef: dataclasses.InitVar[ast.ClassDef]
+	dataclassesDOTdataclassInstance_Identifier: dataclasses.InitVar[ast_Identifier]
+	field: dataclasses.InitVar[dataclasses.Field[Any]]
+
+	ledger: LedgerOfImports = dataclasses.field(default_factory=LedgerOfImports)
+
+	name: ast_Identifier = dataclasses.field(init=False)
+	typeBuffalo: type[Any] | str | Any = dataclasses.field(init=False)
+	default: Any | None = dataclasses.field(init=False)
+	default_factory: Callable[..., Any] | None = dataclasses.field(init=False)
+	repr: bool = dataclasses.field(init=False)
+	hash: bool | None = dataclasses.field(init=False)
+	init: bool = dataclasses.field(init=False)
+	compare: bool = dataclasses.field(init=False)
+	metadata: dict[Any, Any] = dataclasses.field(init=False)
+	kw_only: bool = dataclasses.field(init=False)
+
+	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)
+	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)
+
+	def __post_init__(self, dataclassesDOTdataclassLogicalPathModule: str_nameDOTname, dataclassClassDef: ast.ClassDef, dataclassesDOTdataclassInstance_Identifier: ast_Identifier, field: dataclasses.Field[Any]) -> None:
+		self.compare = field.compare
+		self.default = field.default if field.default is not dataclasses.MISSING else None
+		self.default_factory = field.default_factory if field.default_factory is not dataclasses.MISSING else None
+		self.hash = field.hash
+		self.init = field.init
+		self.kw_only = field.kw_only if field.kw_only is not dataclasses.MISSING else False
+		self.metadata = dict(field.metadata)
+		self.name = field.name
+		self.repr = field.repr
+		self.typeBuffalo = field.type
+
+		self.astName = Make.Name(self.name)
+		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)
+		if sherpa is None: raise raiseIfNoneGitHubIssueNumber3
+		else: self.astAnnotation = sherpa
+
+		self.ast_argAnnotated = Make.arg(self.name, self.astAnnotation)
+
+		dtype = self.metadata.get('dtype', None)
+		if dtype:
+			constructor = 'array'
+			self.astAnnAssignConstructor = Make.AnnAssign(self.astName, self.astAnnotation, Make.Call(Make.Name(constructor), list_astKeywords=[Make.keyword('dtype', Make.Name(dtype.__name__))]))
+			self.ledger.addImportFrom_asStr('numpy', constructor)
+			self.ledger.addImportFrom_asStr('numpy', dtype.__name__)
+			self.Z0Z_hack = (self.astAnnAssignConstructor, 'array')
+		elif be.Name(self.astAnnotation):
+			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):
+			elementConstructor: ast_Identifier = self.metadata['elementConstructor']
+			self.ledger.addImportFrom_asStr(dataclassesDOTdataclassLogicalPathModule, elementConstructor)
+			takeTheTuple: ast.Tuple = deepcopy(self.astAnnotation.slice)
+			self.astAnnAssignConstructor = Make.AnnAssign(self.astName, self.astAnnotation, takeTheTuple)
+			self.Z0Z_hack = (self.astAnnAssignConstructor, elementConstructor)
+		if be.Name(self.astAnnotation):
+			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:
 	"""
 	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.
 	"""
-	# TODO learn whether dataclasses.make_dataclass would be useful to transform the target dataclass into the `ShatteredDataclass`
-
-	module: ast.Module = ast.parse(inspect_getsource(importlib_import_module(logicalPathModule)))
-	astName_dataclassesDOTdataclass = Make.astName(dataclass_Identifier)
-
-	dataclass = extractClassDef(dataclass_Identifier, module)
-	if not isinstance(dataclass, ast.ClassDef):
-		raise ValueError(f"I could not find {dataclass_Identifier=} in {logicalPathModule=}.")
-
-	ledgerDataclassANDFragments = LedgerOfImports()
-	list_ast_argAnnotated4ArgumentsSpecification: list[ast.arg] = []
-	list_keyword4DataclassInitialization: list[ast.keyword] = []
-	listAnnAssign4DataclassUnpack: list[ast.AnnAssign] = []
-	listAnnotations: list[ast.expr] = []
-	listNameDataclassFragments4Parameters: list[ast.Name] = []
-
-	# TODO get the value from `groupsOfFolds: DatatypeFoldsTotal = dataclasses.field(default=DatatypeFoldsTotal(0), metadata={'theCountingIdentifier': True})`
-	countingVariable = countingIdentifierHARDCODED
-
-	addToLedgerPredicate = ifThis.isAnnAssignAndAnnotationIsName
-	addToLedgerAction = Then.Z0Z_ledger(logicalPathModule, ledgerDataclassANDFragments)
-	addToLedger = NodeCollector(addToLedgerPredicate, [addToLedgerAction])
-
-	exclusionPredicate = ifThis.is_keyword_IdentifierEqualsConstantValue('init', False)
-	appendKeywordAction = Then.Z0Z_appendKeywordMirroredTo(list_keyword4DataclassInitialization)
-	filteredAppendKeywordAction = Z0Z_executeActionUnlessDescendantMatches(exclusionPredicate, appendKeywordAction) # type: ignore
-
-	NodeCollector(
-		ifThis.isAnnAssignAndTargetIsName,
-			[Then.Z0Z_appendAnnAssignOf_nameDOTnameTo(instance_Identifier, listAnnAssign4DataclassUnpack)
-			, Then.append_targetTo(listNameDataclassFragments4Parameters) # type: ignore
-			, lambda node: addToLedger.visit(node)
-			, filteredAppendKeywordAction
-			, lambda node: list_ast_argAnnotated4ArgumentsSpecification.append(Make.ast_arg(node.target.id, node.annotation)) # type: ignore
-			, lambda node: listAnnotations.append(node.annotation) # type: ignore
-			]
-		).visit(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=}.")
+
+	countingVariable = None
+	for aField in dataclasses.fields(importLogicalPath2Callable(logicalPathModule, dataclass_Identifier)): # pyright: ignore [reportArgumentType]
+		Official_fieldOrder.append(aField.name)
+		dictionaryDeReConstruction[aField.name] = DeReConstructField2ast(logicalPathModule, dataclassClassDef, instance_Identifier, aField)
+		if aField.metadata.get('theCountingIdentifier', False):
+			countingVariable = dictionaryDeReConstruction[aField.name].name
+
+	if countingVariable is None:
+		raise ValueError(f"I could not find the counting variable in {dataclass_Identifier=} in {logicalPathModule=}.")
 
 	shatteredDataclass = ShatteredDataclass(
-	astAssignDataclassRepack = Make.astAssign(listTargets=[Make.astName(instance_Identifier)], value=Make.astCall(astName_dataclassesDOTdataclass, list_astKeywords=list_keyword4DataclassInitialization))
-	, astSubscriptPrimitiveTupleAnnotations4FunctionDef_returns = Make.astSubscript(Make.astName('tuple'), Make.astTuple(listAnnotations))
-	, astTuple4AssignTargetsToFragments = Make.astTuple(listNameDataclassFragments4Parameters, ast.Store())
-	, countingVariableAnnotation = next(ast_arg.annotation for ast_arg in list_ast_argAnnotated4ArgumentsSpecification if ast_arg.arg == countingVariable) or Make.astName('Any')
-	, countingVariableName = Make.astName(countingVariable)
-	, ledgerDataclassANDFragments = ledgerDataclassANDFragments
-	, list_ast_argAnnotated4ArgumentsSpecification = list_ast_argAnnotated4ArgumentsSpecification
-	, list_keyword4DataclassInitialization = list_keyword4DataclassInitialization
-	, listAnnAssign4DataclassUnpack = listAnnAssign4DataclassUnpack
-	, listAnnotations = listAnnotations
-	, listNameDataclassFragments4Parameters = listNameDataclassFragments4Parameters
-	)
-
-	shatteredDataclass.ledgerDataclassANDFragments.addImportFromStr(logicalPathModule, dataclass_Identifier)
-	return shatteredDataclass
+		countingVariableAnnotation=dictionaryDeReConstruction[countingVariable].astAnnotation,
+		countingVariableName=dictionaryDeReConstruction[countingVariable].astName,
+		field2AnnAssign={dictionaryDeReConstruction[field].name: dictionaryDeReConstruction[field].astAnnAssignConstructor for field in Official_fieldOrder},
+		Z0Z_field2AnnAssign={dictionaryDeReConstruction[field].name: dictionaryDeReConstruction[field].Z0Z_hack for field in Official_fieldOrder},
+		list_argAnnotated4ArgumentsSpecification=[dictionaryDeReConstruction[field].ast_argAnnotated for field in Official_fieldOrder],
+		list_keyword_field__field4init=[dictionaryDeReConstruction[field].ast_keyword_field__field for field in Official_fieldOrder if dictionaryDeReConstruction[field].init],
+		listAnnotations=[dictionaryDeReConstruction[field].astAnnotation for field in Official_fieldOrder],
+		listName4Parameters=[dictionaryDeReConstruction[field].astName for field in Official_fieldOrder],
+		listUnpack=[Make.AnnAssign(dictionaryDeReConstruction[field].astName, dictionaryDeReConstruction[field].astAnnotation, dictionaryDeReConstruction[field].ast_nameDOTname) for field in Official_fieldOrder],
+		map_stateDOTfield2Name={dictionaryDeReConstruction[field].ast_nameDOTname: dictionaryDeReConstruction[field].astName for field in Official_fieldOrder},
+		)
+	shatteredDataclass.fragments4AssignmentOrParameters = Make.Tuple(shatteredDataclass.listName4Parameters, ast.Store())
+	shatteredDataclass.repack = Make.Assign(listTargets=[Make.Name(instance_Identifier)], value=Make.Call(Make.Name(dataclass_Identifier), list_astKeywords=shatteredDataclass.list_keyword_field__field4init))
+	shatteredDataclass.signatureReturnAnnotation = Make.Subscript(Make.Name('tuple'), Make.Tuple(shatteredDataclass.listAnnotations))
+
+	shatteredDataclass.ledger.update(*(dictionaryDeReConstruction[field].ledger for field in Official_fieldOrder))
+	shatteredDataclass.ledger.addImportFrom_asStr(logicalPathModule, dataclass_Identifier)
 
-def getSourceAlgorithmVESTIGIAL() -> ModuleType:
-	moduleImported: ModuleType = importlib_import_module(The.logicalPathModuleSourceAlgorithm)
-	return moduleImported
+	return shatteredDataclass
 
 @overload
-def makeStateJobOUTDATED(listDimensions: Sequence[int], *, writeJob: Literal[True], **keywordArguments: Any) -> Path: ...
+def makeInitializedComputationState(mapShape: tuple[int, ...], writeJob: Literal[True], *,  pathFilename: PathLike[str] | PurePath | None = None, **keywordArguments: Any) -> Path: ...
 @overload
-def makeStateJobOUTDATED(listDimensions: Sequence[int], *, writeJob: Literal[False], **keywordArguments: Any) -> ComputationState: ...
-def makeStateJobOUTDATED(listDimensions: Sequence[int], *, writeJob: bool = True, **keywordArguments: Any) -> ComputationState | Path:
+def makeInitializedComputationState(mapShape: tuple[int, ...], writeJob: Literal[False] = False, **keywordArguments: Any) -> ComputationState: ...
+def makeInitializedComputationState(mapShape: tuple[int, ...], writeJob: bool = False, *,  pathFilename: PathLike[str] | PurePath | None = None, **keywordArguments: Any) -> ComputationState | Path:
 	"""
-	Creates a computation state job for map folding calculations and optionally saves it to disk.
+	Initializes a computation state and optionally saves it to disk.
 
-	This function initializes a computation state for map folding calculations based on the given dimensions,
-	sets up the initial counting configuration, and can optionally save the state to a pickle file.
+	This function initializes a computation state using the source algorithm.
 
-	Parameters:
-		listDimensions: List of integers representing the dimensions of the map to be folded.
-		writeJob (True): Whether to save the state to disk.
-		**keywordArguments: Additional keyword arguments to pass to the computation state initialization.
+	Hint: If you want an uninitialized state, call `outfitCountFolds` directly.
 
+	Parameters:
+		mapShape: List of integers representing the dimensions of the map to be folded.
+		writeJob (False): Whether to save the state to disk.
+		pathFilename (getPathFilenameFoldsTotal.pkl): The path and filename to save the state. If None, uses a default path.
+		**keywordArguments: computationDivisions:int|str|None=None,concurrencyLimit:int=1.
 	Returns:
 		stateUniversal|pathFilenameJob: The computation state for the map folding calculations, or
 			the path to the saved state file if writeJob is True.
 	"""
-	mapShape = validateListDimensions(listDimensions)
 	stateUniversal: ComputationState = outfitCountFolds(mapShape, **keywordArguments)
 
-	moduleSource: ModuleType = getSourceAlgorithmVESTIGIAL()
-	# TODO `countInitialize` is hardcoded
-	stateUniversal = moduleSource.countInitialize(stateUniversal)
+	initializeState = importLogicalPath2Callable(The.logicalPathModuleSourceAlgorithm, The.sourceCallableInitialize)
+	stateUniversal = initializeState(stateUniversal)
 
 	if not writeJob:
 		return stateUniversal
 
-	pathFilenameChopChop = getPathFilenameFoldsTotal(stateUniversal.mapShape, None)
-	suffix = pathFilenameChopChop.suffix
-	pathJob = Path(str(pathFilenameChopChop)[0:-len(suffix)])
-	pathJob.mkdir(parents=True, exist_ok=True)
-	pathFilenameJob = pathJob / 'stateJob.pkl'
+	if pathFilename:
+		pathFilenameJob = Path(pathFilename)
+		pathFilenameJob.parent.mkdir(parents=True, exist_ok=True)
+	else:
+		pathFilenameJob = getPathFilenameFoldsTotal(stateUniversal.mapShape).with_suffix('.pkl')
 
 	pathFilenameJob.write_bytes(pickle.dumps(stateUniversal))
 	return pathFilenameJob