mapFolding 0.12.2__py3-none-any.whl → 0.13.0__py3-none-any.whl

mapFolding/someAssemblyRequired/toolkitNumba.py

@@ -26,13 +26,14 @@ system to produce standalone modules optimized for specific map dimensions and c
 """
 
 from astToolkit import identifierDotAttribute, IngredientsFunction, Make
-from collections.abc import Callable, Sequence
-from numba.core.compiler import CompilerBase as numbaCompilerBase
-from typing import Any, cast, Final, NotRequired, TypedDict
+from typing import cast, Final, NotRequired, TYPE_CHECKING, TypedDict
 import ast
 import dataclasses
 import warnings
 
+if TYPE_CHECKING:
+	from collections.abc import Sequence
+
 class ParametersNumba(TypedDict):
 	"""
 	Configuration parameters for Numba compilation decorators.
@@ -56,6 +57,7 @@ class ParametersNumba(TypedDict):
 	optional via `NotRequired`, allowing flexible configuration while requiring explicit
 	decisions on critical performance and correctness parameters.
 	"""
+
 	_dbg_extend_lifetimes: NotRequired[bool]
 	_dbg_optnone: NotRequired[bool]
 	_nrt: NotRequired[bool]
@@ -67,7 +69,7 @@ class ParametersNumba(TypedDict):
 	forceinline: NotRequired[bool]
 	forceobj: NotRequired[bool]
 	inline: NotRequired[str]
-	locals: NotRequired[dict[str, Any]]
+	# locals: NotRequired[dict[str, Any]]
 	looplift: NotRequired[bool]
 	no_cfunc_wrapper: NotRequired[bool]
 	no_cpython_wrapper: NotRequired[bool]
@@ -75,11 +77,11 @@ class ParametersNumba(TypedDict):
 	nogil: NotRequired[bool]
 	nopython: NotRequired[bool]
 	parallel: NotRequired[bool]
-	pipeline_class: NotRequired[type[numbaCompilerBase]]
-	signature_or_function: NotRequired[Any | Callable[..., Any] | str | tuple[Any, ...]]
+	# pipeline_class: NotRequired[type[numbaCompilerBase]]
+	# signature_or_function: NotRequired[Any | Callable[..., Any] | str | tuple[Any, ...]]
 	target: NotRequired[str]
 
-parametersNumbaDefault: Final[ParametersNumba] = { '_nrt': True, 'boundscheck': False, 'cache': True, 'error_model': 'numpy', 'fastmath': True, 'forceinline': True, 'inline': 'always', 'looplift': False, 'no_cfunc_wrapper': False, 'no_cpython_wrapper': False, 'nopython': True, 'parallel': False, }
+parametersNumbaDefault: Final[ParametersNumba] = { '_nrt': True, 'boundscheck': False, 'cache': True, 'error_model': 'numpy', 'fastmath': True, 'forceinline': True, 'inline': 'always', 'looplift': False, 'no_cfunc_wrapper': False, 'no_cpython_wrapper': False, 'nopython': True, 'parallel': False }
 """
 Comprehensive Numba configuration for maximum performance optimization.
 
@@ -132,54 +134,69 @@ While Numba offers multiple decorators (`@jit`, `@njit`, `@vectorize`), this too
 on the general-purpose `@jit` decorator with configurable parameters for flexibility.
 """
 
-def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, parametersNumba: ParametersNumba | None = None) -> IngredientsFunction:
-	"""
-	Transform a Python function into a Numba-accelerated version with appropriate decorators.
+def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, parametersNumba: ParametersNumba | None = None) -> IngredientsFunction:  # noqa: C901
+	"""Transform a Python function into a Numba-accelerated version with appropriate decorators.
 
-	This function applies Numba's @jit decorator to an existing function definition within
-	an IngredientsFunction container. It handles the complete transformation pipeline:
+	(AI generated docstring)
 
-	1. Removes any existing decorators that might conflict with Numba
-	2. Constructs type signatures for Numba compilation when possible
-	3. Applies the @jit decorator with specified or default parameters
-	4. Updates import requirements to include necessary Numba modules
+	This function applies Numba's `@jit` decorator to an existing function definition within
+	an `IngredientsFunction` container. It handles the complete transformation assembly line
+	including removing any existing decorators that might conflict with Numba, constructing
+	type signatures for Numba compilation when possible, applying the `@jit` decorator with
+	specified or default parameters, and updating import requirements to include necessary
+	Numba modules.
 
 	The transformation preserves function semantics while enabling significant performance
 	improvements through just-in-time compilation. Type inference is attempted for
 	function parameters and return values to enable optimized compilation paths.
-	Parameters:
-		ingredientsFunction: Container holding the function definition and associated metadata
-		parametersNumba: Optional Numba configuration; uses parametersNumbaDefault if None
-	Returns:
-		Modified IngredientsFunction with Numba decorator applied and imports updated
+
+	Parameters
+	----------
+	ingredientsFunction : IngredientsFunction
+		Container holding the function definition and associated metadata.
+	parametersNumba : ParametersNumba | None = None
+		Optional Numba configuration; uses `parametersNumbaDefault` if `None`.
+
+	Returns
+	-------
+	ingredientsFunction : IngredientsFunction
+		Modified `IngredientsFunction` with Numba decorator applied and imports updated.
+
 	"""
 	def Z0Z_UnhandledDecorators(astCallable: ast.FunctionDef) -> ast.FunctionDef:
-		"""
-		Remove existing decorators from function definition to prevent conflicts with Numba.
+		"""Remove existing decorators from function definition to prevent conflicts with Numba.
+
+		(AI generated docstring)
 
 		Numba compilation can be incompatible with certain Python decorators, so this
 		function strips all existing decorators from a function definition before
-		applying the Numba @jit decorator. Removed decorators are logged as warnings
+		applying the Numba `@jit` decorator. Removed decorators are logged as warnings
 		for debugging purposes.
 
 		TODO: Implement more sophisticated decorator handling that can preserve
 		compatible decorators and intelligently handle decorator composition.
 
-		Parameters:
-			astCallable: Function definition AST node to process
+		Parameters
+		----------
+		astCallable : ast.FunctionDef
+			Function definition AST node to process.
+
+		Returns
+		-------
+		astCallable : ast.FunctionDef
+			Function definition with decorator list cleared.
 
-		Returns:
-			astCallable: Function definition with decorator list cleared
 		"""
-		# TODO: more explicit handling of decorators. I'm able to ignore this because I know `algorithmSource` doesn't have any decorators.
+		# TODO more explicit handling of decorators. I'm able to ignore this because I know `algorithmSource` doesn't have any decorators.
 		for decoratorItem in astCallable.decorator_list.copy():
 			astCallable.decorator_list.remove(decoratorItem)
-			warnings.warn(f"Removed decorator {ast.unparse(decoratorItem)} from {astCallable.name}")
+			warnings.warn(f"Removed decorator {ast.unparse(decoratorItem)} from {astCallable.name}", stacklevel=2)
 		return astCallable
 
 	def makeSpecialSignatureForNumba(signatureElement: ast.arg) -> ast.Subscript | ast.Name | None: # pyright: ignore[reportUnusedFunction]
-		"""
-		Generate Numba-compatible type signatures for function parameters.
+		"""Generate Numba-compatible type signatures for function parameters.
+
+		(AI generated docstring)
 
 		This function analyzes function parameter type annotations and converts them into
 		Numba-compatible type signature expressions. It handles various annotation patterns
@@ -189,20 +206,25 @@ def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, paramete
 		The generated signatures enable Numba to perform more efficient compilation by
 		providing explicit type information rather than relying solely on type inference.
 
-		Parameters:
-			signatureElement: Function parameter with type annotation to convert
+		Parameters
+		----------
+		signatureElement : ast.arg
+			Function parameter with type annotation to convert.
+
+		Returns
+		-------
+		ast.Subscript | ast.Name | None
+			Numba-compatible type signature AST node, or None if conversion not possible.
 
-		Returns:
-			Numba-compatible type signature AST node, or None if conversion not possible
 		"""
 		if isinstance(signatureElement.annotation, ast.Subscript) and isinstance(signatureElement.annotation.slice, ast.Tuple):
 			annotationShape: ast.expr = signatureElement.annotation.slice.elts[0]
 			if isinstance(annotationShape, ast.Subscript) and isinstance(annotationShape.slice, ast.Tuple):
 				shapeAsListSlices: list[ast.Slice] = [ast.Slice() for _axis in range(len(annotationShape.slice.elts))]
-				shapeAsListSlices[-1] = ast.Slice(step=ast.Constant(value=1))
-				shapeAST: ast.Slice | ast.Tuple = ast.Tuple(elts=list(shapeAsListSlices), ctx=ast.Load())
+				shapeAsListSlices[-1] = Make.Slice(step=Make.Constant(1))
+				shapeAST: ast.Slice | ast.Tuple = Make.Tuple(list(shapeAsListSlices))
 			else:
-				shapeAST = ast.Slice(step=ast.Constant(value=1))
+				shapeAST = Make.Slice(step=Make.Constant(1))
 
 			annotationDtype: ast.expr = signatureElement.annotation.slice.elts[1]
 			if (isinstance(annotationDtype, ast.Subscript) and isinstance(annotationDtype.slice, ast.Attribute)):
@@ -214,9 +236,9 @@ def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, paramete
 			Z0Z_hacky_dtype: str = ndarrayName
 			datatype_attr = datatypeAST or Z0Z_hacky_dtype
 			ingredientsFunction.imports.addImportFrom_asStr(datatypeModuleDecorator, datatype_attr)
-			datatypeNumba = ast.Name(id=datatype_attr, ctx=ast.Load())
+			datatypeNumba = Make.Name(datatype_attr)
 
-			return ast.Subscript(value=datatypeNumba, slice=shapeAST, ctx=ast.Load())
+			return Make.Subscript(datatypeNumba, slice=shapeAST)
 
 		elif isinstance(signatureElement.annotation, ast.Name):
 			return signatureElement.annotation
@@ -235,14 +257,15 @@ def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, paramete
 
 	if ingredientsFunction.astFunctionDef.returns and isinstance(ingredientsFunction.astFunctionDef.returns, ast.Name):
 		theReturn: ast.Name = ingredientsFunction.astFunctionDef.returns
-		list_argsDecorator = [cast(ast.expr, ast.Call(func=ast.Name(id=theReturn.id, ctx=ast.Load())
-							, args=list_arg4signature_or_function if list_arg4signature_or_function else [], keywords=[] ) )]
+		list_argsDecorator = [cast("ast.expr", Make.Call(Make.Name(theReturn.id)
+							, list_arg4signature_or_function if list_arg4signature_or_function else [], [] ) )]
 	elif list_arg4signature_or_function:
-		list_argsDecorator = [cast(ast.expr, ast.Tuple(elts=list_arg4signature_or_function, ctx=ast.Load()))]
+		list_argsDecorator = [cast("ast.expr", Make.Tuple(list_arg4signature_or_function))]
 
 	ingredientsFunction.astFunctionDef = Z0Z_UnhandledDecorators(ingredientsFunction.astFunctionDef)
 	if parametersNumba is None:
 		parametersNumba = parametersNumbaDefault
+
 	listDecoratorKeywords: list[ast.keyword] = [Make.keyword(parameterName, Make.Constant(parameterValue)) for parameterName, parameterValue in parametersNumba.items()] # pyright: ignore[reportArgumentType]
 
 	decoratorModule = Z0Z_numbaDataTypeModule
@@ -257,8 +280,9 @@ def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, paramete
 
 @dataclasses.dataclass
 class SpicesJobNumba:
-	"""
-	Configuration container for Numba-specific job processing options.
+	"""Configuration container for Numba-specific job processing options.
+
+	(AI generated docstring)
 
 	This dataclass encapsulates configuration settings that control how Numba
 	compilation and execution is applied to job processing functions. It provides
@@ -269,11 +293,17 @@ class SpicesJobNumba:
 	Numba's specialized requirements, enabling consistent application of
 	optimization settings across different computational contexts.
 
-	Attributes:
-		useNumbaProgressBar: Enable progress bar display for long-running computations
-		numbaProgressBarIdentifier: Progress bar implementation identifier
-		parametersNumba: Numba compilation parameters with sensible defaults
+	Attributes
+	----------
+	useNumbaProgressBar : bool
+		Enable progress bar display for long-running computations.
+	numbaProgressBarIdentifier : str
+		Progress bar implementation identifier.
+	parametersNumba : ParametersNumba
+		Numba compilation parameters with sensible defaults.
+
 	"""
+
 	useNumbaProgressBar: bool = True
 	"""Enable progress bar display for Numba-compiled functions with long execution times."""
 

mapFolding/someAssemblyRequired/transformationTools.py

@@ -27,18 +27,17 @@ through specialized compilation paths essential for computationally intensive ma
 """
 
 from astToolkit import (
-	Be, ClassIsAndAttribute, extractClassDef, identifierDotAttribute, IngredientsFunction, Make,
-	NodeChanger, parseLogicalPath2astModule, Then,
-)
+	Be, extractClassDef, identifierDotAttribute, IngredientsFunction, Make, NodeChanger, parseLogicalPath2astModule, Then)
 from astToolkit.transformationTools import unparseFindReplace
+from hunterMakesPy import importLogicalPath2Identifier
 from mapFolding.someAssemblyRequired import DeReConstructField2ast, IfThis, ShatteredDataclass
-from Z0Z_tools import importLogicalPath2Callable
 import ast
 import dataclasses
 
 def shatter_dataclassesDOTdataclass(logicalPathModule: identifierDotAttribute, dataclassIdentifier: str, instanceIdentifier: str) -> ShatteredDataclass:
-	"""
-	Decompose a dataclass definition into AST components for manipulation and code generation.
+	"""Decompose a dataclass definition into AST components for manipulation and code generation.
+
+	(AI generated docstring)
 
 	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.
@@ -54,35 +53,44 @@ def shatter_dataclassesDOTdataclass(logicalPathModule: identifierDotAttribute, d
 	where dataclass instances can't be directly used but their fields need to be individually
 	manipulated and passed to computational functions.
 
-	Parameters:
-		logicalPathModule: The fully qualified module path containing the dataclass definition.
-		dataclassIdentifier: The name of the dataclass to decompose.
-		instanceIdentifier: The variable name to use for the dataclass instance in generated code.
-
-	Returns:
-		shatteredDataclass: A ShatteredDataclass containing AST representations of all dataclass components,
-			with imports, field definitions, annotations, and repackaging code.
+	Parameters
+	----------
+	logicalPathModule : identifierDotAttribute
+		The fully qualified module path containing the dataclass definition.
+	dataclassIdentifier : str
+		The name of the dataclass to decompose.
+	instanceIdentifier : str
+		The variable name to use for the dataclass instance in generated code.
+
+	Returns
+	-------
+	ShatteredDataclass
+		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.
 
-	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[str] = []
 	dictionaryDeReConstruction: dict[str, DeReConstructField2ast] = {}
 
 	dataclassClassDef: ast.ClassDef | None = extractClassDef(parseLogicalPath2astModule(logicalPathModule), dataclassIdentifier)
-	if not isinstance(dataclassClassDef, ast.ClassDef):
-		raise ValueError(f"I could not find `{dataclassIdentifier = }` in `{logicalPathModule = }`.")
+	if not dataclassClassDef:
+		message = f"I could not find `{dataclassIdentifier = }` in `{logicalPathModule = }`."
+		raise ValueError(message)
 
 	countingVariable = None
-	for aField in dataclasses.fields(importLogicalPath2Callable(logicalPathModule, dataclassIdentifier)): # pyright: ignore [reportArgumentType]
+	for aField in dataclasses.fields(importLogicalPath2Identifier(logicalPathModule, dataclassIdentifier)): # pyright: ignore [reportArgumentType]
 		Official_fieldOrder.append(aField.name)
 		dictionaryDeReConstruction[aField.name] = DeReConstructField2ast(logicalPathModule, dataclassClassDef, instanceIdentifier, aField)
 		if aField.metadata.get('theCountingIdentifier', False):
 			countingVariable = dictionaryDeReConstruction[aField.name].name
 	if countingVariable is None:
-		# import warnings
-		# warnings.warn(message=f"I could not find the counting variable in `{dataclassIdentifier = }` in `{logicalPathModule = }`.", category=UserWarning)
-		raise ValueError(f"I could not find the counting variable in `{dataclassIdentifier = }` in `{logicalPathModule = }`.")
+		message = f"I could not find the counting variable in `{dataclassIdentifier = }` in `{logicalPathModule = }`."
+		raise ValueError(message)
 
 	shatteredDataclass = ShatteredDataclass(
 		countingVariableAnnotation=dictionaryDeReConstruction[countingVariable].astAnnotation,
@@ -106,8 +114,9 @@ def shatter_dataclassesDOTdataclass(logicalPathModule: identifierDotAttribute, d
 	return shatteredDataclass
 
 def removeDataclassFromFunction(ingredientsTarget: IngredientsFunction, shatteredDataclass: ShatteredDataclass) -> IngredientsFunction:
-	"""
-	Transform a function that operates on dataclass instances to work with individual field parameters.
+	"""Transform a function that operates on dataclass instances to work with individual field parameters.
+
+	(AI generated docstring)
 
 	This function performs the core transformation required for Numba compatibility by removing dataclass
 	dependencies from function signatures and implementations. It modifies the target function to:
@@ -121,12 +130,18 @@ def removeDataclassFromFunction(ingredientsTarget: IngredientsFunction, shattere
 	implementations, as Numba cannot handle dataclass instances directly but can efficiently
 	process individual primitive values and tuples.
 
-	Parameters:
-		ingredientsTarget: The function definition and its dependencies to be transformed.
-		shatteredDataclass: The decomposed dataclass components providing AST mappings and transformations.
+	Parameters
+	----------
+	ingredientsTarget : IngredientsFunction
+		The function definition and its dependencies to be transformed.
+	shatteredDataclass : ShatteredDataclass
+		The decomposed dataclass components providing AST mappings and transformations.
+
+	Returns
+	-------
+	IngredientsFunction
+		The modified function ingredients with dataclass dependencies removed.
 
-	Returns:
-		ingredientsTarget: The modified function ingredients with dataclass dependencies removed.
 	"""
 	ingredientsTarget.astFunctionDef.args = Make.arguments(list_arg=shatteredDataclass.list_argAnnotated4ArgumentsSpecification)
 	ingredientsTarget.astFunctionDef.returns = shatteredDataclass.signatureReturnAnnotation
@@ -136,8 +151,9 @@ def removeDataclassFromFunction(ingredientsTarget: IngredientsFunction, shattere
 	return ingredientsTarget
 
 def unpackDataclassCallFunctionRepackDataclass(ingredientsCaller: IngredientsFunction, targetCallableIdentifier: str, shatteredDataclass: ShatteredDataclass) -> IngredientsFunction:
-	"""
-	Transform a caller function to interface with a dataclass-free target function.
+	"""Transform a caller function to interface with a dataclass-free target function.
+
+	(AI generated docstring)
 
 	This function complements `removeDataclassFromFunction` by modifying calling code to work with
 	the transformed target function. It implements the unpacking and repacking pattern required
@@ -153,18 +169,25 @@ def unpackDataclassCallFunctionRepackDataclass(ingredientsCaller: IngredientsFun
 	field-based implementations, maintaining the original interface while enabling performance
 	optimizations in the target function.
 
-	Parameters:
-		ingredientsCaller: The calling function definition and its dependencies to be transformed.
-		targetCallableIdentifier: The name of the target function being called.
-		shatteredDataclass: The decomposed dataclass components providing unpacking and repacking logic.
+	Parameters
+	----------
+	ingredientsCaller : IngredientsFunction
+		The calling function definition and its dependencies to be transformed.
+	targetCallableIdentifier : str
+		The name of the target function being called.
+	shatteredDataclass : ShatteredDataclass
+		The decomposed dataclass components providing unpacking and repacking logic.
+
+	Returns
+	-------
+	IngredientsFunction
+		The modified caller function with appropriate unpacking and repacking around the target call.
 
-	Returns:
-		ingredientsCaller: The modified caller function with appropriate unpacking and repacking around the target call.
 	"""
 	astCallTargetCallable = Make.Call(Make.Name(targetCallableIdentifier), shatteredDataclass.listName4Parameters)
-	replaceAssignTargetCallable = NodeChanger(ClassIsAndAttribute.valueIs(ast.Assign, IfThis.isCallIdentifier(targetCallableIdentifier)), Then.replaceWith(Make.Assign([shatteredDataclass.fragments4AssignmentOrParameters], value=astCallTargetCallable)))
-	unpack4targetCallable = NodeChanger(ClassIsAndAttribute.valueIs(ast.Assign, IfThis.isCallIdentifier(targetCallableIdentifier)), Then.insertThisAbove(shatteredDataclass.listUnpack))
-	repack4targetCallable = NodeChanger(ClassIsAndAttribute.valueIs(ast.Assign, IfThis.isCallIdentifier(targetCallableIdentifier)), Then.insertThisBelow([shatteredDataclass.repack]))
+	replaceAssignTargetCallable = NodeChanger(Be.Assign.valueIs(IfThis.isCallIdentifier(targetCallableIdentifier)), Then.replaceWith(Make.Assign([shatteredDataclass.fragments4AssignmentOrParameters], value=astCallTargetCallable)))
+	unpack4targetCallable = NodeChanger(Be.Assign.valueIs(IfThis.isCallIdentifier(targetCallableIdentifier)), Then.insertThisAbove(shatteredDataclass.listUnpack))
+	repack4targetCallable = NodeChanger(Be.Assign.valueIs(IfThis.isCallIdentifier(targetCallableIdentifier)), Then.insertThisBelow([shatteredDataclass.repack]))
 	replaceAssignTargetCallable.visit(ingredientsCaller.astFunctionDef)
 	unpack4targetCallable.visit(ingredientsCaller.astFunctionDef)
 	repack4targetCallable.visit(ingredientsCaller.astFunctionDef)

{tests → mapFolding/tests}/__init__.py

@@ -4,7 +4,7 @@ This test suite provides comprehensive validation of map folding computations,
 file system operations, OEIS integration, task division, and foundational
 utilities. The tests are designed to support multiple audiences and use cases.
 
-Test Module Organization:
+Test Module Organization (in mapFolding/tests/):
 - conftest.py: Testing infrastructure and shared fixtures
 - test_computations.py: Core mathematical validation and algorithm testing
 - test_filesystem.py: File operations and path management
@@ -25,4 +25,4 @@ ensure consistent error reporting across all tests.
 For AI Assistants:
 The testing framework emphasizes readable, predictable patterns that maintain
 mathematical correctness while supporting code evolution and optimization.
-"""
+"""