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

mapFolding/someAssemblyRequired/makeJobTheorem2Numba.py

@@ -1,41 +1,71 @@
-from mapFolding import getPathFilenameFoldsTotal, MapFoldingState, packageSettings
-from mapFolding.someAssemblyRequired import IfThis, raiseIfNoneGitHubIssueNumber3
+"""
+Map folding AST transformation system: Specialized job generation and optimization implementation.
+
+This module implements the specialized job generation layer of the map folding AST transformation
+system, executing the complete transformation process to convert generic map folding algorithms
+into highly optimized, standalone computation modules. Building upon the configuration orchestration
+established in the recipe system, this module applies the full sequence of transformations from
+pattern recognition through Numba compilation to produce self-contained computational solutions
+optimized for specific map dimensions and calculation contexts.
+
+The transformation implementation addresses the computational demands of map folding research where
+calculations can require hours or days to complete. The specialization process converts abstract
+algorithms with flexible parameters into concrete, statically-optimized code that leverages
+just-in-time compilation for maximum performance. Each generated module targets specific map
+shapes and calculation modes, enabling aggressive compiler optimizations based on known constraints
+and embedded constants.
+
+The optimization process executes systematic transformations including static value embedding to
+replace parameterized values with compile-time constants, dead code elimination to remove unused
+variables and code paths, parameter internalization to convert function parameters into embedded
+variables, import optimization to replace generic imports with specific implementations, Numba
+decoration with appropriate compilation directives, progress integration for long-running calculations,
+and launcher generation for standalone execution entry points.
+
+The resulting modules represent the culmination of the entire AST transformation system, producing
+self-contained Python scripts that execute independently with dramatically improved performance
+compared to original generic algorithms while maintaining mathematical correctness and providing
+essential progress feedback capabilities for large-scale computational research.
+"""
+
 from astToolkit import (
-	Be,
-	ClassIsAndAttribute,
-	extractFunctionDef,
-	IngredientsFunction,
-	IngredientsModule,
-	LedgerOfImports,
-	Make,
-	NodeChanger,
-	NodeTourist,
-	str_nameDOTname,
-	Then,
+	Be, ClassIsAndAttribute, extractFunctionDef, identifierDotAttribute, IngredientsFunction,
+	IngredientsModule, LedgerOfImports, Make, NodeChanger, NodeTourist, Then,
 )
 from astToolkit.transformationTools import write_astModule
+from mapFolding import getPathFilenameFoldsTotal, MapFoldingState, packageSettings
+from mapFolding.someAssemblyRequired import IfThis
 from mapFolding.someAssemblyRequired.RecipeJob import RecipeJobTheorem2Numba
-from mapFolding.someAssemblyRequired.toolkitNumba import decorateCallableWithNumba, parametersNumbaLight, SpicesJobNumba
+from mapFolding.someAssemblyRequired.toolkitNumba import (
+	decorateCallableWithNumba, parametersNumbaLight, SpicesJobNumba,
+)
 from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds
 from pathlib import PurePosixPath
 from typing import cast, NamedTuple
-from Z0Z_tools import autoDecodingRLE
+from Z0Z_tools import autoDecodingRLE, raiseIfNone
 import ast
-"""Synthesize one file to compute `foldsTotal` of `mapShape`."""
 
-list_IdentifiersNotUsedAllHARDCODED = ['concurrencyLimit', 'foldsTotal', 'mapShape',]
-list_IdentifiersNotUsedParallelSequentialHARDCODED = ['indexLeaf']
-list_IdentifiersNotUsedSequentialHARDCODED = ['foldGroups', 'taskDivisions', 'taskIndex',]
+# Configuration lists for code optimization and dead code elimination
+listIdentifiersNotUsedAllHARDCODED: list[str] = ['concurrencyLimit', 'foldsTotal', 'mapShape',]
+"""Identifiers that are universally unused across all optimization contexts."""
+
+listIdentifiersNotUsedParallelSequentialHARDCODED: list[str] = ['indexLeaf']
+"""Identifiers unused in both parallel and sequential execution modes."""
+
+listIdentifiersNotUsedSequentialHARDCODED: list[str] = ['foldGroups', 'taskDivisions', 'taskIndex',]
+"""Identifiers unused specifically in sequential execution mode."""
 
-list_IdentifiersReplacedHARDCODED = ['groupsOfFolds',]
+listIdentifiersReplacedHARDCODED: list[str] = ['groupsOfFolds',]
+"""Identifiers that get replaced with optimized equivalents during transformation."""
 
-list_IdentifiersStaticValuesHARDCODED = ['dimensionsTotal', 'leavesTotal',]
+listIdentifiersStaticValuesHARDCODED: list[str] = ['dimensionsTotal', 'leavesTotal',]
+"""Identifiers with compile-time constant values that can be embedded directly."""
 
-list_IdentifiersNotUsedHARDCODED = list_IdentifiersStaticValuesHARDCODED + list_IdentifiersReplacedHARDCODED + list_IdentifiersNotUsedAllHARDCODED + list_IdentifiersNotUsedParallelSequentialHARDCODED + list_IdentifiersNotUsedSequentialHARDCODED
+listIdentifiersNotUsedHARDCODED: list[str] = listIdentifiersStaticValuesHARDCODED + listIdentifiersReplacedHARDCODED + listIdentifiersNotUsedAllHARDCODED + listIdentifiersNotUsedParallelSequentialHARDCODED + listIdentifiersNotUsedSequentialHARDCODED
+"""Complete list of all identifiers that can be eliminated during optimization."""
 
 def addLauncherNumbaProgress(ingredientsModule: IngredientsModule, ingredientsFunction: IngredientsFunction, job: RecipeJobTheorem2Numba, spices: SpicesJobNumba) -> tuple[IngredientsModule, IngredientsFunction]:
-	"""
-	Add progress tracking capabilities to a Numba-optimized function.
+	"""Add progress tracking capabilities to a Numba-optimized function.
 
 	This function modifies both the module and the function to integrate Numba-compatible
 	progress tracking for long-running calculations. It performs several key transformations:
@@ -56,8 +86,9 @@ def addLauncherNumbaProgress(ingredientsModule: IngredientsModule, ingredientsFu
 		spices: Configuration specifying progress bar details.
 
 	Returns:
-		A tuple containing the modified module and function with progress tracking.
+		Modified module and function with integrated progress tracking capabilities.
 	"""
+
 	linesLaunch: str = f"""
 if __name__ == '__main__':
 	with ProgressBar(total={job.foldsTotalEstimated}, update_interval=2) as statusUpdate:
@@ -76,7 +107,7 @@ if __name__ == '__main__':
 	ast_argNumbaProgress = ast.arg(arg=spices.numbaProgressBarIdentifier, annotation=ast.Name(id=numba_progressPythonClass, ctx=ast.Load()))
 	ingredientsFunction.astFunctionDef.args.args.append(ast_argNumbaProgress)
 
-	findThis = ClassIsAndAttribute.targetIs(ast.AugAssign, IfThis.isName_Identifier(job.shatteredDataclass.countingVariableName.id))
+	findThis = ClassIsAndAttribute.targetIs(ast.AugAssign, IfThis.isNameIdentifier(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)
@@ -90,17 +121,16 @@ if __name__ == '__main__':
 	return ingredientsModule, ingredientsFunction
 
 def move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsFunction: IngredientsFunction, job: RecipeJobTheorem2Numba) -> IngredientsFunction:
-	"""
-	Convert function parameters into initialized variables with concrete values.
+	"""Convert function parameters into initialized variables with concrete values.
 
 	This function implements a critical transformation that converts function parameters
 	into statically initialized variables in the function body. This enables several
 	optimizations:
 
-	1. Eliminating parameter passing overhead.
-	2. Embedding concrete values directly in the code.
-	3. Allowing Numba to optimize based on known value characteristics.
-	4. Simplifying function signatures for specialized use cases.
+	1. Eliminating parameter passing overhead
+	2. Embedding concrete values directly in the code
+	3. Allowing Numba to optimize based on known value characteristics
+	4. Simplifying function signatures for specialized use cases
 
 	The function handles different data types (scalars, arrays, custom types) appropriately,
 	replacing abstract parameter references with concrete values from the computation state.
@@ -115,16 +145,16 @@ def move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsFunction: Ingre
 	"""
 	ingredientsFunction.imports.update(job.shatteredDataclass.imports)
 
-	list_argCuzMyBrainRefusesToThink = ingredientsFunction.astFunctionDef.args.args + ingredientsFunction.astFunctionDef.args.posonlyargs + ingredientsFunction.astFunctionDef.args.kwonlyargs
+	list_argCuzMyBrainRefusesToThink: list[ast.arg] = ingredientsFunction.astFunctionDef.args.args + ingredientsFunction.astFunctionDef.args.posonlyargs + ingredientsFunction.astFunctionDef.args.kwonlyargs
 	list_arg_arg: list[str] = [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[str] = [astName.id for astName in listName]
-	list_IdentifiersNotUsed: list[str] = list(set(list_arg_arg) - set(list_Identifiers))
+	listIdentifiers: list[str] = [astName.id for astName in listName]
+	listIdentifiersNotUsed: list[str] = list(set(list_arg_arg) - set(listIdentifiers))
 
 	for ast_arg in list_argCuzMyBrainRefusesToThink:
 		if ast_arg.arg in job.shatteredDataclass.field2AnnAssign:
-			if ast_arg.arg in list_IdentifiersNotUsed:
+			if ast_arg.arg in listIdentifiersNotUsed:
 				pass
 			else:
 				ImaAnnAssign, elementConstructor = job.shatteredDataclass.Z0Z_field2AnnAssign[ast_arg.arg]
@@ -146,7 +176,7 @@ def move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsFunction: Ingre
 
 				ingredientsFunction.astFunctionDef.body.insert(0, ImaAnnAssign)
 
-			findThis = IfThis.is_arg_Identifier(ast_arg.arg)
+			findThis = IfThis.is_argIdentifier(ast_arg.arg)
 			remove_arg = NodeChanger(findThis, Then.removeIt)
 			remove_arg.visit(ingredientsFunction.astFunctionDef)
 
@@ -154,22 +184,44 @@ def move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsFunction: Ingre
 	return ingredientsFunction
 
 def makeJobNumba(job: RecipeJobTheorem2Numba, spices: SpicesJobNumba) -> None:
+	"""Generate an optimized Numba-compiled computation module for map folding calculations.
+
+	This function orchestrates the complete code transformation pipeline to convert
+	a generic map folding algorithm into a highly optimized, specialized computation
+	module. The transformation process includes:
+
+	1. Extract and modify the source function from the generic algorithm
+	2. Replace static-valued identifiers with their concrete values
+	3. Convert function parameters to embedded initialized variables
+	4. Remove unused code paths and variables for optimization
+	5. Configure appropriate Numba decorators for JIT compilation
+	6. Add progress tracking capabilities for long-running computations
+	7. Generate standalone launcher code for direct execution
+	8. Write the complete optimized module to the filesystem
 
-	astFunctionDef = extractFunctionDef(job.source_astModule, job.countCallable)
-	if not astFunctionDef: raise raiseIfNoneGitHubIssueNumber3
+	The resulting module is a self-contained Python script that can execute
+	map folding calculations for the specific map dimensions with maximum
+	performance through just-in-time compilation.
+
+	Parameters:
+		job: Configuration recipe containing source locations, target paths, and state.
+		spices: Optimization settings including Numba parameters and progress options.
+	"""
+
+	astFunctionDef: ast.FunctionDef = raiseIfNone(extractFunctionDef(job.source_astModule, job.countCallable))
 	ingredientsCount: IngredientsFunction = IngredientsFunction(astFunctionDef, LedgerOfImports())
 
 	# Remove `foldGroups` and any other unused statements, so you can dynamically determine which variables are not used
-	findThis = ClassIsAndAttribute.targetsIs(ast.Assign, lambda list_expr: any([IfThis.isSubscript_Identifier('foldGroups')(node) for node in list_expr ]))
-	# findThis = IfThis.isAssignAndTargets0Is(IfThis.isSubscript_Identifier('foldGroups'))
+	findThis = ClassIsAndAttribute.targetsIs(ast.Assign, lambda list_expr: any([IfThis.isSubscriptIdentifier('foldGroups')(node) for node in list_expr ]))
+	# findThis = IfThis.isAssignAndTargets0Is(IfThis.isSubscriptIdentifier('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)
+	listIdentifiersStaticValues: list[str] = listIdentifiersStaticValuesHARDCODED
+	for identifier in listIdentifiersStaticValues:
+		findThis = IfThis.isNameIdentifier(identifier)
 		doThat = Then.replaceWith(Make.Constant(int(job.state.__dict__[identifier])))
 		NodeChanger(findThis, doThat).visit(ingredientsCount.astFunctionDef)
 
@@ -198,14 +250,26 @@ if __name__ == '__main__':
 		ingredientsCount.astFunctionDef.returns = job.shatteredDataclass.countingVariableAnnotation
 
 	ingredientsCount = move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsCount, job)
-
 	class DatatypeConfig(NamedTuple):
-		Z0Z_module: str_nameDOTname
+		"""Configuration for mapping framework datatypes to Numba-compatible types.
+
+		This configuration class defines how abstract datatypes used in the map folding
+		framework should be replaced with concrete Numba-compatible types during code
+		generation. Each configuration specifies the source module, target type name,
+		and optional import alias for the transformation.
+
+		Attributes:
+			fml: Framework datatype identifier to be replaced.
+			Z0Z_module: Module containing the target datatype (e.g., 'numba', 'numpy').
+			Z0Z_type_name: Concrete type name in the target module.
+			Z0Z_asname: Optional import alias for the type.
+		"""
 		fml: str
+		Z0Z_module: identifierDotAttribute
 		Z0Z_type_name: str
 		Z0Z_asname: str | None = None
 
-	listDatatypeConfigs = [
+	listDatatypeConfigs: list[DatatypeConfig] = [
 		DatatypeConfig(fml='DatatypeLeavesTotal', Z0Z_module='numba', Z0Z_type_name='uint8'),
 		DatatypeConfig(fml='DatatypeElephino', Z0Z_module='numba', Z0Z_type_name='uint16'),
 		DatatypeConfig(fml='DatatypeFoldsTotal', Z0Z_module='numba', Z0Z_type_name='uint64'),
@@ -234,7 +298,6 @@ if __name__ == '__main__':
 	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)
 	write_astModule(ingredientsModule, job.pathFilenameModule, job.packageIdentifier)
 

mapFolding/someAssemblyRequired/toolkitNumba.py

@@ -1,30 +1,61 @@
 """
-Numba-specific Tools for Generating Optimized Code
+Map folding AST transformation system: Numba integration and just-in-time compilation optimization.
 
-This module provides specialized tools for transforming standard Python code into
-Numba-accelerated implementations. It implements a comprehensive transformation
-assembly-line that:
+This module provides the compilation optimization layer of the map folding AST transformation system,
+implementing comprehensive tools for applying Numba's just-in-time compilation to functions generated
+by the core transformation tools. Building upon the dataclass decomposition and function optimization
+capabilities established in the operational core, this module completes the transformation process
+by applying aggressive performance optimizations through strategic compiler configuration.
 
-1. Converts dataclass-based algorithm implementations into Numba-compatible versions.
-2. Applies appropriate Numba decorators with optimized configuration settings.
-3. Restructures code to work within Numba's constraints.
-4. Manages type information for optimized compilation.
+The integration addresses the final stage of the transformation process where decomposed, optimized
+functions receive Numba decorators with carefully configured optimization parameters. The module
+handles the complexities of type signature generation, import management, and decorator conflict
+resolution that arise when converting high-level map folding algorithms into machine-optimized code.
 
-The module bridges the gap between readable, maintainable Python code and
-highly-optimized numerical computing implementations, enabling significant
-performance improvements while preserving code semantics and correctness.
+Two primary compilation strategies accommodate different performance and compatibility requirements:
+aggressive optimization for production numerical computing provides maximum performance through
+comprehensive compiler directives including nopython mode, bounds checking elimination, forced
+function inlining, and fastmath optimizations; lightweight optimization maintains broader compatibility
+while achieving significant performance gains through selective compiler optimizations suitable for
+development and testing environments.
+
+The strategic application of these optimization configurations enables map folding calculations that
+require hours or days to complete, transforming abstract mathematical algorithms into highly efficient
+computational modules. The compilation layer integrates seamlessly with the broader transformation
+system to produce standalone modules optimized for specific map dimensions and computational contexts.
 """
 
+from astToolkit import identifierDotAttribute, IngredientsFunction, Make
 from collections.abc import Callable, Sequence
-from mapFolding import NotRequired, TypedDict
-from astToolkit import  IngredientsFunction, Make, str_nameDOTname
-from astToolkit.transformationTools import write_astModule
 from numba.core.compiler import CompilerBase as numbaCompilerBase
-from typing import Any, cast, Final
+from typing import Any, cast, Final, NotRequired, TypedDict
 import ast
 import dataclasses
+import warnings
 
 class ParametersNumba(TypedDict):
+	"""
+	Configuration parameters for Numba compilation decorators.
+
+	This TypedDict defines all possible configuration options that can be passed to Numba's
+	`@jit` decorator to control compilation behavior. The parameters enable fine-tuned control
+	over optimization strategies, debugging features, and runtime behavior.
+
+	Key compilation modes:
+		nopython: Forces compilation without Python fallback for maximum performance
+		cache: Enables compilation result caching to disk for faster subsequent runs
+		fastmath: Allows aggressive mathematical optimizations at cost of IEEE compliance
+		parallel: Enables automatic parallelization of supported operations
+
+	Debug and development options:
+		debug: Enables debug information generation
+		boundscheck: Controls array bounds checking (disabled for performance in production)
+		error_model: Defines how numerical errors are handled ('numpy' vs 'python')
+
+	Only `cache`, `error_model`, and `fastmath` are required fields. All other fields are
+	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]
@@ -49,22 +80,121 @@ class ParametersNumba(TypedDict):
 	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, }
-"""Middle of the road: fast, lean, but will talk to non-jitted functions."""
+"""
+Comprehensive Numba configuration for maximum performance optimization.
+
+This configuration provides aggressive optimization settings suitable for production
+numerical computing code. Key characteristics:
+	Enables nopython mode for full compilation without Python fallback
+	Disables bounds checking for maximum array access performance
+	Forces function inlining with 'always' policy for reduced call overhead
+	Uses numpy error model for consistent numerical behavior
+	Enables fastmath for aggressive floating-point optimizations
+	Disables loop lifting to prevent unexpected performance penalties
+
+The configuration prioritizes execution speed over compatibility, producing highly
+optimized machine code at the cost of reduced interoperability with uncompiled
+Python functions.
+"""
+
 parametersNumbaLight: Final[ParametersNumba] = {'cache': True, 'error_model': 'numpy', 'fastmath': True, 'forceinline': True}
+"""
+Minimal Numba configuration for basic optimization with maximum compatibility.
+
+This lightweight configuration provides essential optimizations while maintaining
+broad compatibility with existing Python code. Suitable for:
+	Development and debugging phases
+	Code that needs to interoperate with non-Numba functions
+	Situations where full nopython mode causes compilation issues
+
+Key features:
+	Enables compilation caching for faster subsequent runs
+	Uses numpy error model for consistent mathematical behavior
+	Enables fastmath and function inlining for performance gains
+	Allows Python object mode fallback when needed
+"""
+
+Z0Z_numbaDataTypeModule: identifierDotAttribute = 'numba'
+"""
+Module identifier for Numba imports and type annotations.
+
+This constant specifies the module path used when importing Numba-specific types and decorators
+in generated code. It serves as the single source of truth for the Numba module reference,
+enabling consistent import statements across all generated functions.
+"""
 
-Z0Z_numbaDataTypeModule: str_nameDOTname = 'numba'
 Z0Z_decoratorCallable: str = 'jit'
+"""
+The Numba decorator function name used for just-in-time compilation.
+
+This constant identifies the specific Numba decorator applied to functions for compilation.
+While Numba offers multiple decorators (`@jit`, `@njit`, `@vectorize`), this toolkit focuses
+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.
+
+	This function applies Numba's @jit decorator to an existing function definition within
+	an IngredientsFunction container. It handles the complete transformation pipeline:
+
+	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
+
+	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
+	"""
 	def Z0Z_UnhandledDecorators(astCallable: ast.FunctionDef) -> ast.FunctionDef:
+		"""
+		Remove existing decorators from function definition to prevent conflicts with Numba.
+
+		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
+		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
+
+		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.
 		for decoratorItem in astCallable.decorator_list.copy():
-			import warnings
 			astCallable.decorator_list.remove(decoratorItem)
 			warnings.warn(f"Removed decorator {ast.unparse(decoratorItem)} from {astCallable.name}")
 		return astCallable
 
 	def makeSpecialSignatureForNumba(signatureElement: ast.arg) -> ast.Subscript | ast.Name | None: # pyright: ignore[reportUnusedFunction]
+		"""
+		Generate Numba-compatible type signatures for function parameters.
+
+		This function analyzes function parameter type annotations and converts them into
+		Numba-compatible type signature expressions. It handles various annotation patterns
+		including array types with shape and dtype information, scalar types with simple
+		name annotations, and complex subscripted types requiring special handling.
+
+		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
+
+		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):
@@ -113,7 +243,7 @@ def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, paramete
 	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()]
+	listDecoratorKeywords: list[ast.keyword] = [Make.keyword(parameterName, Make.Constant(parameterValue)) for parameterName, parameterValue in parametersNumba.items()] # pyright: ignore[reportArgumentType]
 
 	decoratorModule = Z0Z_numbaDataTypeModule
 	decoratorCallable = Z0Z_decoratorCallable
@@ -127,6 +257,28 @@ def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, paramete
 
 @dataclasses.dataclass
 class SpicesJobNumba:
+	"""
+	Configuration container for Numba-specific job processing options.
+
+	This dataclass encapsulates configuration settings that control how Numba
+	compilation and execution is applied to job processing functions. It provides
+	a centralized way to manage Numba-specific settings that affect both
+	compilation behavior and runtime features like progress reporting.
+
+	The class serves as a bridge between the generic job processing system and
+	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
+	"""
 	useNumbaProgressBar: bool = True
+	"""Enable progress bar display for Numba-compiled functions with long execution times."""
+
 	numbaProgressBarIdentifier: str = 'ProgressBarGroupsOfFolds'
+	"""Identifier for the progress bar implementation used in Numba-compiled code."""
+
 	parametersNumba: ParametersNumba = dataclasses.field(default_factory=ParametersNumba)  # pyright: ignore[reportArgumentType, reportCallIssue, reportUnknownVariableType]
+	"""Numba compilation parameters; defaults to empty dict allowing decorator defaults."""