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

mapFolding/{filesystem.py → toolboxFilesystem.py}

@@ -5,20 +5,29 @@ This module provides functions for standardized handling of files related to the
 package, with a focus on saving, retrieving, and naming computation results. It implements
 consistent naming conventions and path resolution strategies to ensure that:
 
-1. Computation results are stored in a predictable location
-2. Filenames follow a consistent pattern based on map dimensions
-3. Results can be reliably retrieved for future reference
-4. The system handles file operations safely with appropriate error handling
-
-The module serves as the interface between the computational components of the package
-and the filesystem, abstracting away the details of file operations and path management.
+1. Computation results are stored in a predictable location.
+2. Filenames follow a consistent pattern based on map dimensions.
+3. Results can be reliably retrieved for future reference.
+4. The system handles file operations safely with appropriate error handling.
+
+The module serves as the standardized interface between the computational components
+of the package and the filesystem, abstracting away the details of file operations
+and path management. It provides robust fallback mechanisms to preserve computation
+results even in the face of filesystem errors, which is critical for long-running
+computations that may take days to complete.
+
+The functions here adhere to a consistent approach to path handling:
+- Cross-platform compatibility through the use of `pathlib`.
+- Default locations determined intelligently based on the runtime environment.
+- Progressive fallback strategies for saving critical computation results.
+- Preemptive filesystem validation to detect issues before computation begins.
 """
 from mapFolding.theSSOT import The
 from os import PathLike
 from pathlib import Path, PurePath
 from sys import modules as sysModules
-from typing import Any
 import os
+import platformdirs
 
 def getFilenameFoldsTotal(mapShape: tuple[int, ...]) -> str:
 	"""
@@ -40,13 +49,13 @@ def getFilenameFoldsTotal(mapShape: tuple[int, ...]) -> str:
 		- Safe filesystem characters
 		- Unique extension (.foldsTotal)
 		- Python-safe strings (no starting with numbers, no reserved words)
-		- The 'p' prefix preserves compatibility with Lunnan's original code.
+		- The 'p' prefix comes from Lunnan's original code.
 	"""
 	return 'p' + 'x'.join(str(dimension) for dimension in sorted(mapShape)) + '.foldsTotal'
 
 def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal: PathLike[str] | PurePath | None = None) -> Path:
 	"""
-	Get a standardized path and filename for the computed foldsTotal value.
+	Get a standardized path and filename for the computed `foldsTotal` value.
 
 	This function resolves paths for storing computation results, handling different
 	input types including directories, absolute paths, or relative paths. It ensures
@@ -58,7 +67,7 @@ def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal
 			If None, uses default path. If a directory, appends standardized filename.
 
 	Returns:
-		pathFilenameFoldsTotal: Absolute path and filename for storing the foldsTotal value.
+		pathFilenameFoldsTotal: Absolute path and filename for storing the `foldsTotal` value.
 
 	Notes:
 		The function creates any necessary directories in the path if they don't exist.
@@ -78,15 +87,40 @@ def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal
 	pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
 	return pathFilenameFoldsTotal
 
-# TODO learn how to see this from the user's perspective
 def getPathRootJobDEFAULT() -> Path:
-	pathJobDEFAULT = The.pathPackage / "jobs"
+	"""
+	Get the default root directory for map folding computation jobs.
+
+	This function determines the appropriate default directory for storing computation
+	results based on the current runtime environment. It uses platform-specific
+	directories for normal environments and adapts to special environments like
+	Google Colab.
+
+	Returns:
+		pathJobDEFAULT: Path to the default directory for storing computation results
+
+	Notes:
+		- For standard environments, uses `platformdirs` to find appropriate user data directory.
+		- For Google Colab, uses a specific path in Google Drive.
+		- Creates the directory if it doesn't exist.
+	"""
+	pathJobDEFAULT = Path(platformdirs.user_data_dir(appname=The.packageName, appauthor=False, ensure_exists=True))
 	if 'google.colab' in sysModules:
-		pathJobDEFAULT = Path("/content/drive/MyDrive") / "jobs"
+		pathJobDEFAULT = Path("/content/drive/MyDrive") / The.packageName
 	pathJobDEFAULT.mkdir(parents=True, exist_ok=True)
 	return pathJobDEFAULT
 
 def _saveFoldsTotal(pathFilename: PathLike[str] | PurePath, foldsTotal: int) -> None:
+	"""
+	Internal helper function to save a `foldsTotal` value to a file.
+
+	This is a low-level function used by the public `saveFoldsTotal` function.
+	It handles the basic file operation without extensive error handling.
+
+	Parameters:
+		pathFilename: Path where the `foldsTotal` value should be saved
+		foldsTotal: The integer value to save
+	"""
 	pathFilenameFoldsTotal = Path(pathFilename)
 	pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
 	pathFilenameFoldsTotal.write_text(str(foldsTotal))
@@ -105,17 +139,17 @@ def saveFoldsTotal(pathFilename: PathLike[str] | PurePath, foldsTotal: int) -> N
 
 	Notes:
 		If the primary save fails, the function will attempt alternative save methods:
-		1. Print the value prominently to stdout
-		2. Create a fallback file in the current working directory
-		3. As a last resort, simply print the value
+		1. Print the value prominently to `stdout`.
+		2. Create a fallback file in the current working directory.
+		3. As a last resort, simply print the value.
 	"""
 	try:
 		_saveFoldsTotal(pathFilename, foldsTotal)
 	except Exception as ERRORmessage:
 		try:
-			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
+			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal = }\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
 			print(ERRORmessage)
-			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
+			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal = }\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
 			randomnessPlanB = (int(str(foldsTotal).strip()[-1]) + 1) * ['YO_']
 			filenameInfixUnique = ''.join(randomnessPlanB)
 			pathFilenamePlanB = os.path.join(os.getcwd(), 'foldsTotal' + filenameInfixUnique + '.txt')
@@ -128,25 +162,56 @@ def saveFoldsTotal(pathFilename: PathLike[str] | PurePath, foldsTotal: int) -> N
 	return None
 
 def saveFoldsTotalFAILearly(pathFilename: PathLike[str] | PurePath) -> None:
+	"""
+	Preemptively test file write capabilities before beginning computation.
+
+	This function performs validation checks on the target file location before
+	a potentially long-running computation begins. It tests several critical
+	aspects of filesystem functionality to ensure results can be saved:
+
+	1. Checks if the file already exists to prevent accidental overwrites.
+	2. Verifies that parent directories exist.
+	3. Tests if the system can write a test value to the file.
+	4. Confirms that the written value can be read back correctly.
+
+	Parameters:
+		pathFilename: The path and filename where computation results will be saved.
+
+	Raises:
+		FileExistsError: If the target file already exists.
+		FileNotFoundError: If parent directories don't exist or if write tests fail.
+
+	Notes:
+		This function helps prevent a situation where a computation runs for
+		hours or days only to discover at the end that results cannot be saved.
+	"""
 	if Path(pathFilename).exists():
-		raise FileExistsError(f"{pathFilename=} exists: a battle of overwriting might cause tears.")
+		raise FileExistsError(f"`{pathFilename = }` exists: a battle of overwriting might cause tears.")
 	if not Path(pathFilename).parent.exists():
-		raise FileNotFoundError(f"I received {pathFilename=} 0.000139 seconds ago from a function that promised it created the parent directory, but the parent directory does not exist. Fix that now, so your computation doesn't get deleted later. And be compassionate to others.")
+		raise FileNotFoundError(f"I received `{pathFilename = }` 0.000139 seconds ago from a function that promised it created the parent directory, but the parent directory does not exist. Fix that now, so your computation doesn't get deleted later. And be compassionate to others.")
 	foldsTotal = 149302889205120
 	_saveFoldsTotal(pathFilename, foldsTotal)
 	if not Path(pathFilename).exists():
-		raise FileNotFoundError(f"I just wrote a test file to {pathFilename=}, but it does not exist. Fix that now, so your computation doesn't get deleted later. And continually improve your empathy skills.")
+		raise FileNotFoundError(f"I just wrote a test file to `{pathFilename = }`, but it does not exist. Fix that now, so your computation doesn't get deleted later. And continually improve your empathy skills.")
 	foldsTotalRead = int(Path(pathFilename).read_text())
 	if foldsTotalRead != foldsTotal:
-		raise FileNotFoundError(f"I wrote a test file to {pathFilename=} with contents of {str(foldsTotal)=}, but I read {foldsTotalRead=} from the file. Python says the values are not equal. Fix that now, so your computation doesn't get corrupted later. And be pro-social.")
+		raise FileNotFoundError(f"I wrote a test file to `{pathFilename = }` with contents of `{str(foldsTotal) = }`, but I read `{foldsTotalRead = }` from the file. Python says the values are not equal. Fix that now, so your computation doesn't get corrupted later. And be pro-social.")
 
 def writeStringToHere(this: str, pathFilename: PathLike[str] | PurePath) -> None:
 	"""
 	Write a string to a file, creating parent directories if needed.
 
+	This utility function provides a consistent interface for writing string content
+	to files across the package. It handles path creation and ensures proper
+	string conversion.
+
 	Parameters:
-		this: The string content to write to the file
-		pathFilename: The target file path where the string should be written
+		this: The string content to write to the file.
+		pathFilename: The target file path where the string should be written.
+
+	Notes:
+		This function creates all parent directories in the path if they don't exist,
+		making it safe to use with newly created directory structures.
 	"""
 	pathFilename = Path(pathFilename)
 	pathFilename.parent.mkdir(parents=True, exist_ok=True)

{mapfolding-0.8.4.dist-info → mapfolding-0.8.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapFolding
-Version: 0.8.4
+Version: 0.8.5
 Summary: Map folding algorithm with code transformation framework for optimizing numerical computations
 Author-email: Hunter Hogan <HunterHogan@pm.me>
 License: CC-BY-NC-4.0
@@ -35,6 +35,7 @@ Requires-Dist: more_itertools
 Requires-Dist: numba_progress
 Requires-Dist: numba
 Requires-Dist: numpy
+Requires-Dist: platformdirs
 Requires-Dist: python_minifier
 Requires-Dist: tomli
 Requires-Dist: Z0Z_tools
@@ -132,7 +133,7 @@ The package provides a sophisticated transformation framework that bridges the g
   - Study the functional state-transformation approach in `theDao.py` with clear, isolated functions
   - Explore the semantic decomposition in `reference/flattened.py` to understand algorithm sections
 
-- **Code Transformation Pipeline**:
+- **Code Transformation Assembly-line**:
   - **AST Manipulation**: Analyzes and transforms the algorithm's abstract syntax tree
   - **Dataclass "Shattering"**: Decomposes complex state objects into primitive components
   - **Optimization Applications**: Applies domain-specific optimizations for numerical computation

mapfolding-0.8.5.dist-info/RECORD

@@ -0,0 +1,48 @@
+mapFolding/__init__.py,sha256=LBgk-iW95pzqkFGY8PbcnU0oHy0AXwJGo18mM0g8wEw,2227
+mapFolding/basecamp.py,sha256=-__EJ2to84ssS4Fm0CAuQjRnghI9VA4cXZoWGYud1r0,4782
+mapFolding/beDRY.py,sha256=2GPO4A8XcxoEJXB_3sro4ZFQ5gcU7ywc1-c8HLEvEv0,15280
+mapFolding/noHomeYet.py,sha256=UKZeWlyn0SKlF9dhYoud7E6gWXpiSEekZOOoJp88WeI,1362
+mapFolding/oeis.py,sha256=EzEnbRi_4qt8Na2tiMcvL23FXpcJEkXTwuXDYDFH_XI,12631
+mapFolding/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mapFolding/theDao.py,sha256=MVopt1LzhdIQYA97SEoq9bdzct6hbK0lEyPxBAAlVTc,9934
+mapFolding/theSSOT.py,sha256=i3R_G702U7VQOil61ky60JGGsSEOk_x1555rg8yI0Tc,11978
+mapFolding/toolboxFilesystem.py,sha256=WoqRjXqTXy5GYNmbfzWtzv1uufm7vYcgT4zJ9ffhRYY,9982
+mapFolding/reference/__init__.py,sha256=UIEU8BJR_YDzjFQcLel3XtHzOCJiOUGlGiWzOzbvhik,2206
+mapFolding/reference/flattened.py,sha256=QK1xG9SllqCoi68e86Hyl9d9ATUAAFNpTQI-3zmcp5I,16072
+mapFolding/reference/hunterNumba.py,sha256=iLfyqwGdAh6c5GbapnKsWhAsNsR3O-fyGGHAdohluLw,7258
+mapFolding/reference/irvineJavaPort.py,sha256=UEfIX4QbPLl5jnyfYIyX5YRR3_rYvPUikK8jLehsFko,4076
+mapFolding/reference/jaxCount.py,sha256=TuDNKOnyhQfuixKmIxO9Algv7dvy7KMGhgsV3h96FGE,14853
+mapFolding/reference/lunnanNumpy.py,sha256=mMgrgbrBpe4nmo72ThEI-MGH0OwEHmfMPczSXHp2qKo,4357
+mapFolding/reference/lunnanWhile.py,sha256=ZL8GAQtPs5nJZSgoDl5USrLSS_zs03y98y1Z9E4jOmQ,3799
+mapFolding/reference/rotatedEntryPoint.py,sha256=5ughpKUT2JQhoAKgoDUdYNjgWQYPGV8v-7dWEAdDmfE,10274
+mapFolding/reference/total_countPlus1vsPlusN.py,sha256=yJZAVLVdoXqHag2_N6_6CT-Q6HXBgRro-eny93-Rlpw,9307
+mapFolding/reference/jobsCompleted/__init__.py,sha256=TU93ZGUW1xEkT6d9mQFn_rp5DvRy0ZslEB2Q6MF5ZDc,2596
+mapFolding/reference/jobsCompleted/[2x19]/p2x19.py,sha256=_tvYtfzMWVo2VtUbIAieoscb4N8FFflgTdW4-ljBUuA,19626
+mapFolding/reference/jobsCompleted/p2x19/p2x19.py,sha256=eZEw4Me4ocTt6VXoK2-Sbd5SowZtxRIbN9dZmc7OCVg,6395
+mapFolding/someAssemblyRequired/__init__.py,sha256=c2GFI2HSId2_R_aoJWBID-P9AMF3zoHJzOc10XS6DHc,2669
+mapFolding/someAssemblyRequired/_theTypes.py,sha256=SG82WTtQy83BmInlHZHY8Nh3Kp161NcEFSA6-UU5wuE,4623
+mapFolding/someAssemblyRequired/_tool_Make.py,sha256=8ezrMDAdUY6m1raFp-G8vNXrHEr8IGfnZJ-aMVKzGf0,7092
+mapFolding/someAssemblyRequired/_tool_Then.py,sha256=QxuoBqj4iOeKWITjV3DcV8c25fLx3Q6mhUORD7-mCzc,2758
+mapFolding/someAssemblyRequired/_toolboxAntecedents.py,sha256=GEAuniYRj6yOtrJO_6sGZMzsVARdejts8NXhR_0np_c,21914
+mapFolding/someAssemblyRequired/_toolboxContainers.py,sha256=iPLZbFcGB6dKtX3WkopnM-2OtMcVuxXQT46iFhzpdfY,17815
+mapFolding/someAssemblyRequired/_toolboxPython.py,sha256=za30092eT00tj5ctqUCRrEuq5DGeJZN-vV9T4Dro-1w,3483
+mapFolding/someAssemblyRequired/getLLVMforNoReason.py,sha256=9RPU6vK_eUg64GtVFI_nZnvUryXw8gfHJs9NyDYHIvg,2745
+mapFolding/someAssemblyRequired/newInliner.py,sha256=Tm9PSzt66oIXPVrN9VdQwEYBba2iEOF5X3aEsOOF-FE,946
+mapFolding/someAssemblyRequired/synthesizeNumbaJob.py,sha256=0L5ccqBusof6MzKatKnpUmFUNkAtbapzl_Fxmofi4DE,8684
+mapFolding/someAssemblyRequired/toolboxNumba.py,sha256=rluEmsSJOQCl2L6LlJzIc3AfeRxU6cp-sCf-rQFW-og,22613
+mapFolding/someAssemblyRequired/transformationTools.py,sha256=iIvRxSL45qTyl0d0ztHa9BP1MrOikfXE4HBqLlNMENc,20081
+mapFolding/syntheticModules/__init__.py,sha256=evVFqhCGa-WZKDiLcnQWjs-Bj34eRnfSLqz_d7dFYZY,83
+mapFolding/syntheticModules/numbaCount_doTheNeedful.py,sha256=3thXThbv2Xo0t_cRGzMbHPFXTBmLClmKejR_Ibu_jOo,15697
+mapfolding-0.8.5.dist-info/licenses/LICENSE,sha256=NxH5Y8BdC-gNU-WSMwim3uMbID2iNDXJz7fHtuTdXhk,19346
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/conftest.py,sha256=LfogHLu7PULSECwhLQgGCgqSvDMBc5b9RGWBls3YBrM,11364
+tests/test_computations.py,sha256=XjCej6M6lesfKB_ulWq3O-ryXBsJuuwnJ6_XjKOvgDY,3552
+tests/test_filesystem.py,sha256=YEHNU6tUCTj9C65cKs3ETgt3OZTGVnNjxgu4aH6C9uU,3164
+tests/test_oeis.py,sha256=uxvwmgbnylSDdsVJfuAT0LuYLbIVFwSgdLxHm-xUGBM,5043
+tests/test_other.py,sha256=O05PFAK70Skf-k99Wcg4ASLpMpBH-WkELtk6MnynDx0,4293
+tests/test_tasks.py,sha256=S-6PNfM__Npw0zVojgzn5M-6ODBKDyRH5ccMTqQF9C4,2865
+mapfolding-0.8.5.dist-info/METADATA,sha256=vrusTb9uu8FQ3UksfFkVZ3txtYPNufYa3db-Rk6H1y0,9359
+mapfolding-0.8.5.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+mapfolding-0.8.5.dist-info/entry_points.txt,sha256=F3OUeZR1XDTpoH7k3wXuRb3KF_kXTTeYhu5AGK1SiOQ,146
+mapfolding-0.8.5.dist-info/top_level.txt,sha256=1gP2vFaqPwHujGwb3UjtMlLEGN-943VSYFR7V4gDqW8,17
+mapfolding-0.8.5.dist-info/RECORD,,

tests/conftest.py

@@ -1,13 +1,11 @@
 from collections.abc import Callable, Generator, Sequence
 from mapFolding.beDRY import getLeavesTotal, validateListDimensions, makeDataContainer
 from mapFolding.oeis import oeisIDsImplemented, settingsOEIS
-from mapFolding.someAssemblyRequired import importLogicalPath2Callable
-from mapFolding.someAssemblyRequired.synthesizeNumbaFlow import makeNumbaFlow
-from mapFolding.someAssemblyRequired._toolboxContainers import RecipeSynthesizeFlow
+from mapFolding.someAssemblyRequired import importLogicalPath2Callable, RecipeSynthesizeFlow
 from mapFolding.theSSOT import ComputationState, The, getPackageDispatcher
 from pathlib import Path, PurePosixPath
 from types import ModuleType
-from typing import Any, ContextManager
+from typing import Any
 import importlib
 import importlib.util
 import numpy
@@ -215,34 +213,35 @@ def useAlgorithmSourceDispatcher(useThisDispatcher: Callable[..., Any]) -> Gener
 
 @pytest.fixture
 def syntheticDispatcherFixture(useThisDispatcher: Callable[..., Any], pathTmpTesting: Path) -> Callable[..., Any]:
-    """Generate synthetic Numba-optimized dispatcher module and patch the dispatcher"""
-    # Configure synthesis flow to use test directory
-    TESTINGrecipeFlow = RecipeSynthesizeFlow(
-        pathPackage=PurePosixPath(pathTmpTesting.absolute()),
-        logicalPathFlowRoot=None,
-        moduleDispatcher="test_dispatcher",
+	"""Generate synthetic Numba-optimized dispatcher module and patch the dispatcher"""
+	from mapFolding.someAssemblyRequired.toolboxNumba import makeNumbaFlow
+
+	TESTINGrecipeFlow = RecipeSynthesizeFlow(
+		pathPackage=PurePosixPath(pathTmpTesting.absolute()),
+		logicalPathFlowRoot=None,
+		moduleDispatcher="test_dispatcher",
 # Figure out dynamic flow control to synthesized modules https://github.com/hunterhogan/mapFolding/issues/4
-        # dispatcherCallable="dispatcherSynthetic",
-    )
-
-    # Generate optimized module in test directory
-    makeNumbaFlow(TESTINGrecipeFlow)
-
-    # Import synthesized dispatcher
-    importlibSpecificationDispatcher = importlib.util.spec_from_file_location(
-        TESTINGrecipeFlow.moduleDispatcher,
-        Path(TESTINGrecipeFlow.pathFilenameDispatcher),
-    )
-    if importlibSpecificationDispatcher is None or importlibSpecificationDispatcher.loader is None:
-        raise ImportError("Failed to load synthetic dispatcher module")
-
-    moduleSpecificationDispatcher = importlib.util.module_from_spec(importlibSpecificationDispatcher)
-    importlibSpecificationDispatcher.loader.exec_module(moduleSpecificationDispatcher)
-    callableDispatcherSynthetic = getattr(moduleSpecificationDispatcher, TESTINGrecipeFlow.callableDispatcher)
-
-    # Patch dispatcher and return callable
-    useThisDispatcher(callableDispatcherSynthetic)
-    return callableDispatcherSynthetic
+		# dispatcherCallable="dispatcherSynthetic",
+	)
+
+	# Generate optimized module in test directory
+	makeNumbaFlow(TESTINGrecipeFlow)
+
+	# Import synthesized dispatcher
+	importlibSpecificationDispatcher = importlib.util.spec_from_file_location(
+		TESTINGrecipeFlow.moduleDispatcher,
+		Path(TESTINGrecipeFlow.pathFilenameDispatcher),
+	)
+	if importlibSpecificationDispatcher is None or importlibSpecificationDispatcher.loader is None:
+		raise ImportError("Failed to load synthetic dispatcher module")
+
+	moduleSpecificationDispatcher = importlib.util.module_from_spec(importlibSpecificationDispatcher)
+	importlibSpecificationDispatcher.loader.exec_module(moduleSpecificationDispatcher)
+	callableDispatcherSynthetic = getattr(moduleSpecificationDispatcher, TESTINGrecipeFlow.callableDispatcher)
+
+	# Patch dispatcher and return callable
+	useThisDispatcher(callableDispatcherSynthetic)
+	return callableDispatcherSynthetic
 
 def uniformTestMessage(expected: Any, actual: Any, functionName: str, *arguments: Any) -> str:
 	"""Format assertion message for any test comparison."""

tests/test_computations.py

@@ -1,10 +1,9 @@
 from mapFolding.basecamp import countFolds
-from mapFolding.filesystem import getPathFilenameFoldsTotal
+from mapFolding.toolboxFilesystem import getPathFilenameFoldsTotal
 from mapFolding.beDRY import validateListDimensions
 from mapFolding.noHomeYet import getFoldsTotalKnown
 from mapFolding.oeis import settingsOEIS, oeisIDfor_n
-from mapFolding.someAssemblyRequired.synthesizeNumbaJob import makeJobNumba, Z0Z_RecipeJob
-from mapFolding.someAssemblyRequired.transformDataStructures import makeInitializedComputationState
+from mapFolding.someAssemblyRequired.transformationTools import makeInitializedComputationState
 from pathlib import Path, PurePosixPath
 from tests.conftest import standardizedEqualToCallableReturn, registrarRecordsTmpObject
 from types import ModuleType
@@ -35,6 +34,8 @@ def test_syntheticSequential(syntheticDispatcherFixture: None, listDimensionsTes
 
 @pytest.mark.parametrize('pathFilenameTmpTesting', ['.py'], indirect=True)
 def test_writeJobNumba(oneTestCuzTestsOverwritingTests: list[int], pathFilenameTmpTesting: Path) -> None:
+	from mapFolding.someAssemblyRequired.toolboxNumba import RecipeJob, SpicesJobNumba
+	from mapFolding.someAssemblyRequired.synthesizeNumbaJob import makeJobNumba
 	mapShape = validateListDimensions(oneTestCuzTestsOverwritingTests)
 	state = makeInitializedComputationState(mapShape)
 
@@ -42,12 +43,12 @@ def test_writeJobNumba(oneTestCuzTestsOverwritingTests: list[int], pathFilenameT
 	pathFilenameFoldsTotal = pathFilenameModule.with_suffix('.foldsTotalTesting')
 	registrarRecordsTmpObject(pathFilenameFoldsTotal)
 
-	jobTest = Z0Z_RecipeJob(state
+	jobTest = RecipeJob(state
 						, pathModule=PurePosixPath(pathFilenameModule.parent)
 						, moduleIdentifier=pathFilenameModule.stem
 						, pathFilenameFoldsTotal=PurePosixPath(pathFilenameFoldsTotal))
-
-	makeJobNumba(jobTest)
+	spices = SpicesJobNumba()
+	makeJobNumba(jobTest, spices)
 
 	Don_Lapre_Road_to_Self_Improvement = importlib.util.spec_from_file_location("__main__", pathFilenameModule)
 	if Don_Lapre_Road_to_Self_Improvement is None:

tests/test_filesystem.py

@@ -1,7 +1,7 @@
 from contextlib import redirect_stdout
-from mapFolding.filesystem import getFilenameFoldsTotal, getPathFilenameFoldsTotal, saveFoldsTotal
+from mapFolding.toolboxFilesystem import getFilenameFoldsTotal, getPathFilenameFoldsTotal, saveFoldsTotal
 from mapFolding.beDRY import validateListDimensions
-from mapFolding.filesystem import getPathRootJobDEFAULT
+from mapFolding.toolboxFilesystem import getPathRootJobDEFAULT
 from pathlib import Path
 import io
 import pytest

tests/test_other.py

@@ -1,5 +1,5 @@
 from collections.abc import Callable
-from mapFolding.beDRY import getLeavesTotal, setCPUlimit, validateListDimensions
+from mapFolding.beDRY import getLeavesTotal, setProcessorLimit, validateListDimensions
 from mapFolding.theSSOT import The
 from tests.conftest import standardizedEqualToCallableReturn
 from typing import Any, Literal
@@ -81,4 +81,4 @@ def testOopsieKwargsie(nameOfTest: str, callablePytest: Callable[[], None]) -> N
 ])
 def test_setCPUlimitNumba(CPUlimit: None | float | bool | Literal[4] | Literal[-2] | Literal[0] | Literal[1], expectedLimit: Any | int) -> None:
 	numba.set_num_threads(multiprocessing.cpu_count())
-	standardizedEqualToCallableReturn(expectedLimit, setCPUlimit, CPUlimit, 'numba')
+	standardizedEqualToCallableReturn(expectedLimit, setProcessorLimit, CPUlimit, 'numba')

tests/test_tasks.py

@@ -1,6 +1,6 @@
 from collections.abc import Callable
 from mapFolding.basecamp import countFolds
-from mapFolding.beDRY import getTaskDivisions, setCPUlimit, validateListDimensions, getLeavesTotal
+from mapFolding.beDRY import getTaskDivisions, setProcessorLimit, validateListDimensions, getLeavesTotal
 from mapFolding.noHomeYet import getFoldsTotalKnown
 from tests.conftest import standardizedEqualToCallableReturn
 from typing import Literal
@@ -49,4 +49,4 @@ def test_getTaskDivisions(computationDivisions: None | list[str] | Literal['maxi
 ])
 def test_setCPUlimitMalformedParameter(expected: type[ValueError] | Literal[2], parameter: list[int] | tuple[int] | set[int] | dict[str, int] | Literal['2']) -> None:
 	"""Test that invalid CPUlimit types are properly handled."""
-	standardizedEqualToCallableReturn(expected, setCPUlimit, parameter)
+	standardizedEqualToCallableReturn(expected, setProcessorLimit, parameter)

mapFolding/someAssemblyRequired/ingredientsNumba.py

@@ -1,199 +0,0 @@
-"""
-Numba-specific ingredients for optimized code generation.
-
-This module provides specialized tools, constants, and types specifically designed
-for transforming Python code into Numba-accelerated implementations. It implements:
-
-1. A range of Numba jit decorator configurations for different optimization scenarios
-2. Functions to identify and manipulate Numba decorators in abstract syntax trees
-3. Utilities for applying appropriate Numba typing to transformed code
-4. Parameter management for Numba compilation options
-
-The configurations range from conservative options that prioritize compatibility and
-error detection to aggressive optimizations that maximize performance at the cost of
-flexibility. While this module specifically targets Numba, its design follows the pattern
-of generic code transformation tools in the package, allowing similar approaches to be
-applied to other acceleration technologies.
-
-This module works in conjunction with transformation tools to convert the general-purpose
-algorithm implementation into a highly-optimized Numba version.
-"""
-
-from collections.abc import Callable, Sequence
-from mapFolding.someAssemblyRequired import Make
-from mapFolding.someAssemblyRequired._toolboxContainers import IngredientsFunction
-from numba.core.compiler import CompilerBase as numbaCompilerBase
-from typing import Any, cast, Final, TYPE_CHECKING
-import ast
-
-try:
-	from typing import NotRequired
-except Exception:
-	from typing_extensions import NotRequired
-
-if TYPE_CHECKING:
-	from typing import TypedDict
-else:
-	TypedDict = dict
-
-class ParametersNumba(TypedDict):
-	_dbg_extend_lifetimes: NotRequired[bool]
-	_dbg_optnone: NotRequired[bool]
-	_nrt: NotRequired[bool]
-	boundscheck: NotRequired[bool]
-	cache: bool
-	debug: NotRequired[bool]
-	error_model: str
-	fastmath: bool
-	forceinline: bool
-	forceobj: NotRequired[bool]
-	inline: str
-	locals: NotRequired[dict[str, Any]]
-	looplift: bool
-	no_cfunc_wrapper: bool
-	no_cpython_wrapper: bool
-	no_rewrites: NotRequired[bool]
-	nogil: NotRequired[bool]
-	nopython: bool
-	parallel: bool
-	pipeline_class: NotRequired[type[numbaCompilerBase]]
-	signature_or_function: NotRequired[Any | Callable[..., Any] | str | tuple[Any, ...]]
-	target: NotRequired[str]
-
-parametersNumbaFailEarly: Final[ParametersNumba] = {
-		'_nrt': True,
-		'boundscheck': True,
-		'cache': True,
-		'error_model': 'python',
-		'fastmath': False,
-		'forceinline': True,
-		'inline': 'always',
-		'looplift': False,
-		'no_cfunc_wrapper': False,
-		'no_cpython_wrapper': False,
-		'nopython': True,
-		'parallel': False,
-}
-"""For a production function: speed is irrelevant, error discovery is paramount, must be compatible with anything downstream."""
-
-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."""
-
-parametersNumbaParallelDEFAULT: Final[ParametersNumba] = {
-		**parametersNumbaDefault,
-		'_nrt': True,
-		'parallel': True, }
-"""Middle of the road: fast, lean, but will talk to non-jitted functions."""
-
-parametersNumbaSuperJit: Final[ParametersNumba] = {
-		**parametersNumbaDefault,
-		'no_cfunc_wrapper': True,
-		'no_cpython_wrapper': True, }
-"""Speed, no helmet, no talking to non-jitted functions."""
-
-parametersNumbaSuperJitParallel: Final[ParametersNumba] = {
-		**parametersNumbaSuperJit,
-		'_nrt': True,
-		'parallel': True, }
-"""Speed, no helmet, concurrency, no talking to non-jitted functions."""
-
-parametersNumbaMinimum: Final[ParametersNumba] = {
-		'_nrt': True,
-		'boundscheck': True,
-		'cache': True,
-		'error_model': 'numpy',
-		'fastmath': True,
-		'forceinline': False,
-		'inline': 'always',
-		'looplift': False,
-		'no_cfunc_wrapper': False,
-		'no_cpython_wrapper': False,
-		'nopython': False,
-		'forceobj': True,
-		'parallel': False, }
-
-Z0Z_numbaDataTypeModule = 'numba'
-Z0Z_decoratorCallable = 'jit'
-
-def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, parametersNumba: ParametersNumba | None = None) -> IngredientsFunction:
-	def Z0Z_UnhandledDecorators(astCallable: ast.FunctionDef) -> ast.FunctionDef:
-		# 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: # type: ignore
-		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())
-			else:
-				shapeAST = ast.Slice(step=ast.Constant(value=1))
-
-			annotationDtype: ast.expr = signatureElement.annotation.slice.elts[1]
-			if (isinstance(annotationDtype, ast.Subscript) and isinstance(annotationDtype.slice, ast.Attribute)):
-				datatypeAST = annotationDtype.slice.attr
-			else:
-				datatypeAST = None
-
-			ndarrayName = signatureElement.arg
-			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())
-
-			return ast.Subscript(value=datatypeNumba, slice=shapeAST, ctx=ast.Load())
-
-		elif isinstance(signatureElement.annotation, ast.Name):
-			return signatureElement.annotation
-		return None
-
-	datatypeModuleDecorator: str = Z0Z_numbaDataTypeModule
-	list_argsDecorator: Sequence[ast.expr] = []
-
-	list_arg4signature_or_function: list[ast.expr] = []
-	for parameter in ingredientsFunction.astFunctionDef.args.args:
-		# Efficient translation of Python scalar types to Numba types https://github.com/hunterhogan/mapFolding/issues/8
-		# For now, let Numba infer them.
-		continue
-		# signatureElement: ast.Subscript | ast.Name | None = makeSpecialSignatureForNumba(parameter)
-		# if signatureElement:
-		# 	list_arg4signature_or_function.append(signatureElement)
-
-	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=[] ) )]
-	elif list_arg4signature_or_function:
-		list_argsDecorator = [cast(ast.expr, ast.Tuple(elts=list_arg4signature_or_function, ctx=ast.Load()))]
-
-	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()]
-
-	decoratorModule: str = Z0Z_numbaDataTypeModule
-	decoratorCallable: str = Z0Z_decoratorCallable
-	ingredientsFunction.imports.addImportFrom_asStr(decoratorModule, decoratorCallable)
-	# Leave this line in so that global edits will change it.
-	astDecorator: ast.Call = Make.Call(Make.Name(decoratorCallable), list_argsDecorator, listDecoratorKeywords)
-	astDecorator: ast.Call = Make.Call(Make.Name(decoratorCallable), list_astKeywords=listDecoratorKeywords)
-
-	ingredientsFunction.astFunctionDef.decorator_list = [astDecorator]
-	return ingredientsFunction