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

mapFolding/__init__.py

@@ -10,8 +10,11 @@ transformation tools.
 Core modules:
 - basecamp: Public API with simplified interfaces for end users
 - theDao: Core computational algorithm using a functional state-transformation approach
-- beDRY: Utility functions for common operations and parameter management
+- beDRY: Core utility functions implementing consistent data handling, validation, and
+  resource management across the package's computational assembly-line
 - theSSOT: Single Source of Truth for configuration, types, and state management
+- toolboxFilesystem: Cross-platform file management services for storing and retrieving
+  computation results with robust error handling and fallback mechanisms
 - oeis: Interface to the Online Encyclopedia of Integer Sequences for known results
 
 Extended functionality:
@@ -24,13 +27,13 @@ Special directories:
   core algorithm created by the code transformation framework
 - reference/: Historical implementations and educational resources for algorithm exploration
   - reference/jobsCompleted/: Contains successful computations for previously unknown values,
-    including first-ever calculations for 2×19 and 2×20 maps (OEIS A001415)
+    including first-ever calculations for 2x19 and 2x20 maps (OEIS A001415)
 
 This package strives to balance algorithm readability and understandability with
 high-performance computation capabilities, allowing users to compute map folding
 totals for larger dimensions than previously feasible.
 """
-from mapFolding.basecamp import countFolds as countFolds
+from mapFolding.basecamp import countFolds
 from mapFolding.oeis import clearOEIScache, getOEISids, OEIS_for_n, oeisIDfor_n
 
 __all__ = [

mapFolding/basecamp.py

@@ -13,14 +13,14 @@ implementation, and optional persistence of results.
 """
 
 from collections.abc import Sequence
-from mapFolding.beDRY import outfitCountFolds, setCPUlimit, validateListDimensions
-from mapFolding.filesystem import getPathFilenameFoldsTotal, saveFoldsTotal
 from mapFolding.theSSOT import ComputationState, getPackageDispatcher, The
+from mapFolding.beDRY import outfitCountFolds, setProcessorLimit, validateListDimensions
+from mapFolding.toolboxFilesystem import getPathFilenameFoldsTotal, saveFoldsTotal, saveFoldsTotalFAILearly
 from os import PathLike
-from pathlib import Path
+from pathlib import PurePath
 
 def countFolds(listDimensions: Sequence[int]
-				, pathLikeWriteFoldsTotal: str | PathLike[str] | None = None
+				, pathLikeWriteFoldsTotal: PathLike[str] | PurePath | None = None
 				, computationDivisions: int | str | None = None
 				, CPUlimit: int | float | bool | None = None
 				) -> int:
@@ -54,16 +54,22 @@ def countFolds(listDimensions: Sequence[int]
 		If you want to compute a large `foldsTotal`, dividing the computation into tasks is usually a bad idea. Dividing the algorithm into tasks is inherently inefficient: efficient division into tasks means there would be no overlap in the work performed by each task. When dividing this algorithm, the amount of overlap is between 50% and 90% by all tasks: at least 50% of the work done by every task must be done by _all_ tasks. If you improve the computation time, it will only change by -10 to -50% depending on (at the very least) the ratio of the map dimensions and the number of leaves. If an undivided computation would take 10 hours on your computer, for example, the computation will still take at least 5 hours but you might reduce the time to 9 hours. Most of the time, however, you will increase the computation time. If logicalCores >= leavesTotal, it will probably be faster. If logicalCores <= 2 * leavesTotal, it will almost certainly be slower for all map dimensions.
 	"""
 	mapShape: tuple[int, ...] = validateListDimensions(listDimensions)
-	concurrencyLimit: int = setCPUlimit(CPUlimit, The.concurrencyPackage)
+	concurrencyLimit: int = setProcessorLimit(CPUlimit, The.concurrencyPackage)
 	computationStateInitialized: ComputationState = outfitCountFolds(mapShape, computationDivisions, concurrencyLimit)
 
+	if pathLikeWriteFoldsTotal is not None:
+		pathFilenameFoldsTotal = getPathFilenameFoldsTotal(computationStateInitialized.mapShape, pathLikeWriteFoldsTotal)
+		saveFoldsTotalFAILearly(pathFilenameFoldsTotal)
+	else:
+		pathFilenameFoldsTotal = None
+
 	dispatcherCallableProxy = getPackageDispatcher()
 	computationStateComplete: ComputationState = dispatcherCallableProxy(computationStateInitialized)
+	# computationStateComplete: ComputationState = The.dispatcher(computationStateInitialized)
 
 	computationStateComplete.getFoldsTotal()
 
-	if pathLikeWriteFoldsTotal is not None:
-		pathFilenameFoldsTotal: Path = getPathFilenameFoldsTotal(computationStateComplete.mapShape, pathLikeWriteFoldsTotal)
+	if pathFilenameFoldsTotal is not None:
 		saveFoldsTotal(pathFilenameFoldsTotal, computationStateComplete.foldsTotal)
 
 	return computationStateComplete.foldsTotal

mapFolding/beDRY.py

@@ -1,34 +1,60 @@
 """
-Utility functions for maintaining DRY (Don't Repeat Yourself) principles in the mapFolding package.
+Core utility functions implementing DRY (Don't Repeat Yourself) principles for the mapFolding package.
 
-This module provides a collection of helper functions that abstract common operations needed
-throughout the package, preventing code duplication and ensuring consistency. The functions
-manage core aspects of the computation process, including:
+This module serves as the foundation for consistent data management and parameter validation
+across the entire mapFolding computation assembly-line. It provides critical utility functions that:
 
-1. Resource allocation and system limits management
-2. Data structure initialization and manipulation
-3. Parameter validation and interpretation
-4. Construction of specialized arrays and matrices for the folding algorithm
+1. Calculate and validate fundamental computational parameters such as leaves total and task divisions.
+2. Generate specialized connection graphs that define the folding algorithm's constraints.
+3. Provide centralized resource allocation and system limits management.
+4. Construct and manage uniform data structures for the computation state.
+5. Ensure parameter validation and safe type conversion.
 
-The functions in this module serve as a relatively stable API for other modules to use,
-particularly for initializing computation state, validating inputs, and creating data
-structures needed by the folding algorithms.
+The functions in this module maintain a clear separation between data initialization and algorithm
+implementation, enabling the package to support multiple computational strategies (sequential,
+parallel, and JIT-compiled) while ensuring consistent input handling and state management.
+
+These utilities form a stable internal API that other modules depend on, particularly theSSOT
+(Single Source of Truth), theDao (core algorithm), and the synthetic module generators that
+produce optimized implementations.
 """
 from collections.abc import Sequence
-from mapFolding.theSSOT import ComputationState
-from numpy import dtype as numpy_dtype, integer, ndarray
+from mapFolding.theSSOT import ComputationState, numpyIntegerType
+from numpy import dtype as numpy_dtype, int64 as numpy_int64, ndarray
 from sys import maxsize as sysMaxsize
-from typing import Any, TypeVar
+from typing import Any
 from Z0Z_tools import defineConcurrencyLimit, intInnit, oopsieKwargsie
 import numpy
 
-numpyIntegerType = TypeVar('numpyIntegerType', bound=integer[Any])
-
 def getLeavesTotal(mapShape: tuple[int, ...]) -> int:
+	"""
+	Calculate the total number of leaves in a map with the given dimensions.
+
+	The total number of leaves is the product of all dimensions in the map shape.
+	This value is foundational for initializing the computation state and determining
+	task divisions.
+
+	Parameters
+	----------
+	mapShape
+		A tuple of integers representing the dimensions of the map.
+
+	Returns
+	-------
+	leavesTotal
+		The total number of leaves in the map, calculated as the product of all dimensions.
+
+	Raises
+	------
+	OverflowError
+		If the product of dimensions would exceed the system's maximum integer size.
+		This check prevents silent numeric overflow issues that could lead to incorrect results.
+	"""
 	productDimensions = 1
 	for dimension in mapShape:
+		# NOTE this check is one-degree short of absurd, but three lines of early absurdity is better than invalid output later. I'd add more checks if I could think of more.
 		if dimension > sysMaxsize // productDimensions:
-			raise OverflowError(f"I received {dimension=} in {mapShape=}, but the product of the dimensions exceeds the maximum size of an integer on this system.")
+			raise OverflowError(f"I received `{dimension = }` in `{mapShape = }`, but the product of the dimensions exceeds the maximum size of an integer on this system.")
 		productDimensions *= dimension
 	return productDimensions
 
@@ -38,18 +64,14 @@ def getTaskDivisions(computationDivisions: int | str | None, concurrencyLimit: i
 
 	Parameters
 	----------
-	computationDivisions (None)
+	computationDivisions: None
 		Specifies how to divide computations:
 		- `None`: no division of the computation into tasks; sets task divisions to 0.
-		- int: direct set the number of task divisions; cannot exceed the map's total leaves.
+		- int: directly set the number of task divisions; cannot exceed the map's total leaves.
 		- `'maximum'`: divides into `leavesTotal`-many `taskDivisions`.
-		- `'cpu'`: limits the divisions to the number of available CPUs, i.e. `concurrencyLimit`.
+		- `'cpu'`: limits the divisions to the number of available CPUs: i.e., `concurrencyLimit`.
 	concurrencyLimit
 		Maximum number of concurrent tasks allowed.
-	CPUlimit
-		for error reporting.
-	listDimensions
-		for error reporting.
 
 	Returns
 	-------
@@ -59,41 +81,74 @@ def getTaskDivisions(computationDivisions: int | str | None, concurrencyLimit: i
 	Raises
 	------
 	ValueError
-		If computationDivisions is an unsupported type or if resulting task divisions exceed total leaves.
+		If `computationDivisions` is an unsupported type or if resulting task divisions exceed total leaves.
 
 	Notes
 	-----
 	Task divisions should not exceed total leaves or the folds will be over-counted.
 	"""
 	taskDivisions = 0
-	if not computationDivisions:
-		pass
-	elif isinstance(computationDivisions, int):
-		taskDivisions = computationDivisions
-	elif isinstance(computationDivisions, str): # type: ignore
-		# 'Unnecessary isinstance call; "str" is always an instance of "str", so sayeth Pylance'. Yeah, well "User is not always an instance of "correct input" so sayeth the programmer.
-		computationDivisions = computationDivisions.lower()
-		if computationDivisions == 'maximum':
-			taskDivisions = leavesTotal
-		elif computationDivisions == 'cpu':
-			taskDivisions = min(concurrencyLimit, leavesTotal)
-	else:
-		raise ValueError(f"I received {computationDivisions} for the parameter, `computationDivisions`, but the so-called programmer didn't implement code for that.")
+	match computationDivisions:
+		case None | 0 | False:
+			pass
+		case int() as intComputationDivisions:
+			taskDivisions = intComputationDivisions
+		case str() as strComputationDivisions:
+			strComputationDivisions = strComputationDivisions.lower()
+			match strComputationDivisions:
+				case 'maximum':
+					taskDivisions = leavesTotal
+				case 'cpu':
+					taskDivisions = min(concurrencyLimit, leavesTotal)
+				case _:
+					raise ValueError(f"I received '{strComputationDivisions}' for the parameter, `computationDivisions`, but the string value is not supported.")
+		case _:
+			raise ValueError(f"I received {computationDivisions} for the parameter, `computationDivisions`, but the type {type(computationDivisions).__name__} is not supported.")
 
 	if taskDivisions > leavesTotal:
-		raise ValueError(f"Problem: `taskDivisions`, ({taskDivisions}), is greater than `leavesTotal`, ({leavesTotal}), which will cause duplicate counting of the folds.\n\nChallenge: you cannot directly set `taskDivisions` or `leavesTotal`. They are derived from parameters that may or may not still be named `computationDivisions`, `CPUlimit` , and `listDimensions` and from dubious-quality Python code.")
+		raise ValueError(f"Problem: `{taskDivisions = }`, is greater than `{leavesTotal = }`, which will cause duplicate counting of the folds.\n\nChallenge: you cannot directly set `taskDivisions` or `leavesTotal`: they are derived from parameters that may or may not be named `computationDivisions`, `CPUlimit` , and `listDimensions` and from my dubious-quality Python code.")
 	return int(max(0, taskDivisions))
 
-def makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: type[numpyIntegerType]) -> ndarray[tuple[int, int, int], numpy_dtype[numpyIntegerType]]:
+def _makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int) -> ndarray[tuple[int, int, int], numpy_dtype[numpy_int64]]:
+	"""
+	Implementation of connection graph generation for map folding.
+
+	This is the internal implementation that calculates all possible connections between
+	leaves in a map folding problem based on Lunnon's algorithm. The function constructs a
+	three-dimensional array representing which leaves can be connected to each other for each
+	dimension of the map.
+
+	Parameters
+	----------
+	mapShape
+		A tuple of integers representing the dimensions of the map.
+	leavesTotal
+		The total number of leaves in the map.
+
+	Returns
+	-------
+	connectionGraph
+		A 3D NumPy array with shape (`dimensionsTotal`, `leavesTotal`+1, `leavesTotal`+1)
+		where each entry [d,i,j] represents the leaf that would be connected to leaf j
+		when inserting leaf i in dimension d.
+
+	Notes
+	-----
+	This is an implementation detail and shouldn't be called directly by external code.
+	Use `getConnectionGraph` instead, which applies proper typing.
+
+	The algorithm calculates a coordinate system first, then determines connections
+	based on parity rules, boundary conditions, and dimensional constraints.
+	"""
 	dimensionsTotal = len(mapShape)
-	cumulativeProduct = numpy.multiply.accumulate([1] + list(mapShape), dtype=datatype)
-	arrayDimensions = numpy.array(mapShape, dtype=datatype)
-	coordinateSystem = numpy.zeros((dimensionsTotal, leavesTotal + 1), dtype=datatype)
+	cumulativeProduct = numpy.multiply.accumulate([1] + list(mapShape), dtype=numpy_int64)
+	arrayDimensions = numpy.array(mapShape, dtype=numpy_int64)
+	coordinateSystem = numpy.zeros((dimensionsTotal, leavesTotal + 1), dtype=numpy_int64)
 	for indexDimension in range(dimensionsTotal):
 		for leaf1ndex in range(1, leavesTotal + 1):
 			coordinateSystem[indexDimension, leaf1ndex] = (((leaf1ndex - 1) // cumulativeProduct[indexDimension]) % arrayDimensions[indexDimension] + 1)
 
-	connectionGraph = numpy.zeros((dimensionsTotal, leavesTotal + 1, leavesTotal + 1), dtype=datatype)
+	connectionGraph = numpy.zeros((dimensionsTotal, leavesTotal + 1, leavesTotal + 1), dtype=numpy_int64)
 	for indexDimension in range(dimensionsTotal):
 		for activeLeaf1ndex in range(1, leavesTotal + 1):
 			for connectee1ndex in range(1, activeLeaf1ndex + 1):
@@ -110,39 +165,132 @@ def makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: t
 					connectionGraph[indexDimension, activeLeaf1ndex, connectee1ndex] = connectee1ndex + cumulativeProduct[indexDimension]
 	return connectionGraph
 
+def getConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: type[numpyIntegerType]) -> ndarray[tuple[int, int, int], numpy_dtype[numpyIntegerType]]:
+	"""
+	Create a properly typed connection graph for the map folding algorithm.
+
+	This function serves as a typed wrapper around the internal implementation that
+	generates connection graphs. It provides the correct type information for the
+	returned array, ensuring consistency throughout the computation assembly-line.
+
+	Parameters
+	----------
+	mapShape
+		A tuple of integers representing the dimensions of the map.
+	leavesTotal
+		The total number of leaves in the map.
+	datatype
+		The NumPy integer type to use for the array elements, ensuring proper
+		memory usage and compatibility with the computation state.
+
+	Returns
+	-------
+	connectionGraph
+		A 3D NumPy array with shape (`dimensionsTotal`, `leavesTotal`+1, `leavesTotal`+1)
+		with the specified `datatype`, representing all possible connections between leaves.
+	"""
+	connectionGraph = _makeConnectionGraph(mapShape, leavesTotal)
+	connectionGraph = connectionGraph.astype(datatype)
+	return connectionGraph
+
 def makeDataContainer(shape: int | tuple[int, ...], datatype: type[numpyIntegerType]) -> ndarray[Any, numpy_dtype[numpyIntegerType]]:
+	"""
+	Create a typed NumPy array container with initialized values.
+
+	This function centralizes the creation of data containers used throughout the
+	computation assembly-line, enabling easy switching between different container types
+	or implementation strategies if needed in the future.
+
+	Parameters
+	----------
+	shape
+		Either an integer (for 1D arrays) or a tuple of integers (for multi-dimensional arrays)
+		specifying the dimensions of the array.
+	datatype
+		The NumPy integer type to use for the array elements, ensuring proper type
+		consistency and memory efficiency.
+
+	Returns
+	-------
+	container
+		A NumPy array of zeros with the specified shape and `datatype`.
+	"""
 	return numpy.zeros(shape, dtype=datatype)
 
 def outfitCountFolds(mapShape: tuple[int, ...], computationDivisions: int | str | None = None, concurrencyLimit: int = 1) -> ComputationState:
+	"""
+	Initialize a `ComputationState` with validated parameters for map folding calculation.
+
+	This function serves as the central initialization point for creating a properly
+	configured `ComputationState` object, ensuring consistent calculation of the fundamental
+	parameters (`leavesTotal` and `taskDivisions`) across the entire package.
+
+	Parameters
+	----------
+	mapShape
+		A tuple of integers representing the dimensions of the map.
+	computationDivisions: None
+		Controls how to divide the computation into parallel tasks. I know it is annoying,
+		but please see `getTaskDivisions` for details, so that you and I both know you have the most
+		accurate information.
+	concurrencyLimit: 1
+		Maximum number of concurrent processes to use during computation.
+
+	Returns
+	-------
+	computationStateInitialized
+		A fully initialized `ComputationState` object that's ready for computation.
+
+	Notes
+	-----
+	This function maintains the Single Source of Truth principle for `leavesTotal`
+	and `taskDivisions` calculation, ensuring these values are derived consistently
+	throughout the package.
+	"""
 	leavesTotal = getLeavesTotal(mapShape)
 	taskDivisions = getTaskDivisions(computationDivisions, concurrencyLimit, leavesTotal)
 	computationStateInitialized = ComputationState(mapShape, leavesTotal, taskDivisions, concurrencyLimit)
 	return computationStateInitialized
 
-def setCPUlimit(CPUlimit: Any | None, concurrencyPackage: str | None = None) -> int:
-	"""Sets CPU limit for concurrent operations.
+def setProcessorLimit(CPUlimit: Any | None, concurrencyPackage: str | None = None) -> int:
+	"""
+	Sets processor limit for concurrent operations.
 
-	If the concurrency is managed by `numba`, the maximum number of CPUs is retrieved from `numba.get_num_threads()` and not by polling the hardware. Therefore, if there are
-	numba environment variables limiting the number of available CPUs, that will effect this function. That _should_ be a good thing: you control the number of CPUs available
-	to numba. But if you're not aware of that, you might be surprised by the results.
+	Parameters
+	----------
+	CPUlimit: None
+		Controls processor usage limits:
+		- `False`, `None`, or `0`: No limits on processor usage; uses all available processors. All other values will potentially limit processor usage.
+		- `True`: Yes, limit the processor usage; limits to 1 processor.
+		- Integer `>= 1`: Limits usage to the specified number of processors.
+		- Decimal value (`float`) between 0 and 1: Fraction of total processors to use.
+		- Decimal value (`float`) between -1 and 0: Fraction of processors to _not_ use.
+		- Integer `<= -1`: Subtract the absolute value from total processors.
+	concurrencyPackage: None
+		Specifies which concurrency package to use:
+		- `None` or `'multiprocessing'`: Uses standard `multiprocessing`.
+		- `'numba'`: Uses Numba's threading system.
 
-	If you are designing custom modules that use numba, note that you must call `numba.set_num_threads()` (i.e., this function) before executing an `import` statement
-	on a Numba-jitted function. Otherwise, the `numba.set_num_threads()` call will have no effect on the imported function.
+	Returns
+	-------
+	concurrencyLimit
+		The actual concurrency limit that was set.
 
-	Parameters:
-		CPUlimit: whether and how to limit the CPU usage. See notes for details.
-	Returns:
-		concurrencyLimit: The actual concurrency limit that was set
-	Raises:
-		TypeError: If CPUlimit is not of the expected types
+	Raises
+	------
+	TypeError
+		If `CPUlimit` is not of the expected types.
+	NotImplementedError
+		If `concurrencyPackage` is not supported.
 
-	Limits on CPU usage `CPUlimit`:
-		- `False`, `None`, or `0`: No limits on CPU usage; uses all available CPUs. All other values will potentially limit CPU usage.
-		- `True`: Yes, limit the CPU usage; limits to 1 CPU.
-		- Integer `>= 1`: Limits usage to the specified number of CPUs.
-		- Decimal value (`float`) between 0 and 1: Fraction of total CPUs to use.
-		- Decimal value (`float`) between -1 and 0: Fraction of CPUs to *not* use.
-		- Integer `<= -1`: Subtract the absolute value from total CPUs.
+	Notes
+	-----
+	If using `'numba'` as the concurrency package, the maximum number of processors is
+	retrieved from `numba.get_num_threads()` rather than by polling the hardware.
+	If Numba environment variables limit available processors, that will affect this function.
+
+	When using Numba, this function must be called before importing any Numba-jitted
+	function for this processor limit to affect the Numba-jitted function.
 	"""
 	if not (CPUlimit is None or isinstance(CPUlimit, (bool, int, float))):
 		CPUlimit = oopsieKwargsie(CPUlimit)
@@ -157,19 +305,44 @@ def setCPUlimit(CPUlimit: Any | None, concurrencyPackage: str | None = None) ->
 			set_num_threads(concurrencyLimit)
 			concurrencyLimit = get_num_threads()
 		case _:
-			raise NotImplementedError(f"I received {concurrencyPackage=} but I don't know what to do with that.")
+			raise NotImplementedError(f"I received `{concurrencyPackage = }` but I don't know what to do with that.")
 	return concurrencyLimit
 
 def validateListDimensions(listDimensions: Sequence[int]) -> tuple[int, ...]:
+	"""
+	Validate and normalize dimensions for a map folding problem.
+
+	This function serves as the gatekeeper for dimension inputs, ensuring that all
+	map dimensions provided to the package meet the requirements for valid computation.
+	It performs multiple validation steps and normalizes the dimensions into a consistent format.
+
+	Parameters
+	----------
+	listDimensions
+		A sequence of integers representing the dimensions of the map.
+
+	Returns
+	-------
+	tuple[int, ...]
+		A sorted tuple of positive integers representing the validated dimensions.
+
+	Raises
+	------
+	ValueError
+		If the input is empty or contains negative values.
+	NotImplementedError
+		If fewer than two positive dimensions are provided, as this would not
+		represent a valid map folding problem.
+	"""
 	if not listDimensions:
-		raise ValueError("listDimensions is a required parameter.")
+		raise ValueError("`listDimensions` is a required parameter.")
 	listValidated: list[int] = intInnit(listDimensions, 'listDimensions')
 	listNonNegative: list[int] = []
 	for dimension in listValidated:
 		if dimension < 0:
-			raise ValueError(f"Dimension {dimension} must be non-negative")
+			raise ValueError(f"`{dimension = }` in `{listDimensions = }`, must be a non-negative integer.")
 		listNonNegative.append(dimension)
 	dimensionsValid = [dimension for dimension in listNonNegative if dimension > 0]
 	if len(dimensionsValid) < 2:
-		raise NotImplementedError(f"This function requires listDimensions, {listDimensions}, to have at least two dimensions greater than 0. You may want to look at https://oeis.org/.")
+		raise NotImplementedError(f"This function requires `{listDimensions = }` to have at least two dimensions greater than 0. You may want to look at https://oeis.org/.")
 	return tuple(sorted(dimensionsValid))

mapFolding/oeis.py

@@ -17,6 +17,7 @@ literature and extend sequences beyond their currently known terms.
 from collections.abc import Callable
 from datetime import datetime, timedelta
 from mapFolding.theSSOT import The
+from mapFolding.toolboxFilesystem import writeStringToHere
 from pathlib import Path
 from typing import Any, Final, TYPE_CHECKING
 import argparse
@@ -31,9 +32,9 @@ import warnings
 if TYPE_CHECKING:
 	from typing import TypedDict
 else:
-	TypedDict = dict
+	TypedDict = dict[Any, Any]
 
-cacheDays = 7
+cacheDays = 30
 
 """
 Section: make `settingsOEIS`"""
@@ -174,8 +175,7 @@ def getOEISofficial(pathFilenameCache: pathlib.Path, url: str) -> None | str:
 	if not tryCache:
 		httpResponse: urllib.response.addinfourl = urllib.request.urlopen(url)
 		oeisInformation = httpResponse.read().decode('utf-8')
-		pathFilenameCache.parent.mkdir(parents=True, exist_ok=True)
-		pathFilenameCache.write_text(oeisInformation)
+		writeStringToHere(oeisInformation, pathFilenameCache)
 
 	if not oeisInformation:
 		warnings.warn(f"Failed to retrieve OEIS sequence information for {pathFilenameCache.stem}.")

mapFolding/reference/hunterNumba.py

@@ -19,7 +19,7 @@ Performance considerations:
 - Incorporates lessons from multiple implementation strategies
 
 Note: This serves as a reference for manually-optimized code before the development of
-the automated transformation pipeline in the main package.
+the automated transformation assembly-line in the main package.
 """
 
 from typing import Any

mapFolding/someAssemblyRequired/__init__.py

@@ -14,7 +14,7 @@ Core capabilities:
 4. Performance Optimization - Apply domain-specific optimizations for numerical computation
 5. Code Generation - Generate specialized implementations with appropriate imports and syntax
 
-The transformation pipeline supports multiple optimization targets, from general-purpose
+The transformation assembly-line supports multiple optimization targets, from general-purpose
 acceleration to generating highly-specialized variants optimized for specific input parameters.
 This multi-level transformation approach allows for both development flexibility and
 runtime performance, preserving algorithm readability in the source while enabling
@@ -24,23 +24,43 @@ These tools were developed for map folding computation optimization but are desi
 general-purpose utilities applicable to a wide range of code transformation scenarios,
 particularly for numerically-intensive algorithms that benefit from just-in-time compilation.
 """
-from mapFolding.someAssemblyRequired.transformationTools import (
-	ast_Identifier as ast_Identifier,
-	extractClassDef as extractClassDef,
-	extractFunctionDef as extractFunctionDef,
-	ifThis as ifThis,
-	IngredientsFunction as IngredientsFunction,
-	IngredientsModule as IngredientsModule,
-	inlineThisFunctionWithTheseValues as inlineThisFunctionWithTheseValues,
-	LedgerOfImports as LedgerOfImports,
-	Make as Make,
-	makeDictionaryReplacementStatements as makeDictionaryReplacementStatements,
-	NodeCollector as NodeCollector,
-	NodeReplacer as NodeReplacer,
-	RecipeSynthesizeFlow as RecipeSynthesizeFlow,
-	strDotStrCuzPyStoopid as strDotStrCuzPyStoopid,
-	Then as Then,
-	write_astModule as write_astModule,
-	Z0Z_executeActionUnlessDescendantMatches as Z0Z_executeActionUnlessDescendantMatches,
-	Z0Z_replaceMatchingASTnodes as Z0Z_replaceMatchingASTnodes,
+from mapFolding.someAssemblyRequired._theTypes import (
+	ast_expr_Slice,
+	ast_Identifier,
+	astClassHasDOTnameNotName,
+	astClassHasDOTtarget,
+	astClassHasDOTvalue,
+	astClassOptionallyHasDOTnameNotName,
+	astMosDef,
+	Ima_funcTypeUNEDITED,
+	Ima_targetTypeUNEDITED,
+	ImaAnnotationType,
+	ImaAnnotationTypeVar,
+	intORlist_ast_type_paramORstr_orNone,
+	intORstr_orNone,
+	list_ast_type_paramORstr_orNone,
+	str_nameDOTname,
+	TypeCertified,
+	个,
 	)
+
+from mapFolding.someAssemblyRequired._toolboxPython import (
+	importLogicalPath2Callable,
+	importPathFilename2Callable,
+	NodeChanger,
+	NodeTourist,
+	parseLogicalPath2astModule,
+	parsePathFilename2astModule,
+	)
+
+from mapFolding.someAssemblyRequired._toolboxAntecedents import be, DOT, ifThis, 又
+from mapFolding.someAssemblyRequired._tool_Make import Make
+from mapFolding.someAssemblyRequired._tool_Then import Then
+
+from mapFolding.someAssemblyRequired._toolboxContainers import (
+	IngredientsFunction,
+	IngredientsModule,
+	LedgerOfImports,
+	RecipeSynthesizeFlow,
+	ShatteredDataclass,
+)

mapFolding/someAssemblyRequired/_theTypes.py

@@ -0,0 +1,53 @@
+"""It's still wrong, but typing information is being transmitted between functions, methods, and modules."""
+from typing import Any, TYPE_CHECKING, TypeAlias as typing_TypeAlias, TypeVar as typing_TypeVar
+import ast
+
+stuPyd: typing_TypeAlias = str
+
+if TYPE_CHECKING:
+	"""	3.12 new: ast.ParamSpec, ast.type_param, ast.TypeAlias, ast.TypeVar, ast.TypeVarTuple
+		3.11 new: ast.TryStar"""
+	astClassHasDOTnameNotName: typing_TypeAlias = ast.alias | ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.ParamSpec | ast.TypeVar | ast.TypeVarTuple
+	astClassHasDOTvalue: typing_TypeAlias = ast.AnnAssign | ast.Assign | ast.Attribute | ast.AugAssign | ast.Await | ast.Constant | ast.DictComp | ast.Expr | ast.FormattedValue | ast.keyword | ast.MatchValue | ast.NamedExpr | ast.Return | ast.Starred | ast.Subscript | ast.TypeAlias | ast.Yield | ast.YieldFrom
+else:
+	astClassHasDOTnameNotName = stuPyd
+	astClassHasDOTvalue = stuPyd
+
+astClassOptionallyHasDOTnameNotName: typing_TypeAlias = ast.ExceptHandler | ast.MatchAs | ast.MatchStar
+astClassHasDOTtarget: typing_TypeAlias = ast.AnnAssign | ast.AsyncFor | ast.AugAssign | ast.comprehension | ast.For | ast.NamedExpr
+
+ast_expr_Slice: typing_TypeAlias = ast.expr
+ast_Identifier: typing_TypeAlias = str
+intORlist_ast_type_paramORstr_orNone: typing_TypeAlias = Any
+intORstr_orNone: typing_TypeAlias = Any
+list_ast_type_paramORstr_orNone: typing_TypeAlias = Any
+str_nameDOTname: typing_TypeAlias = stuPyd
+ImaAnnotationType: typing_TypeAlias = ast.Attribute | ast.Constant | ast.Name | ast.Subscript
+ImaAnnotationTypeVar = typing_TypeVar('ImaAnnotationTypeVar', ast.Attribute, ast.Constant, ast.Name, ast.Subscript)
+
+Ima_funcTypeUNEDITED: typing_TypeAlias = ast.Attribute | ast.Await | ast.BinOp | ast.BoolOp | ast.Call | ast.Compare | ast.Constant | ast.Dict | ast.DictComp | ast.FormattedValue | ast.GeneratorExp | ast.IfExp | ast.JoinedStr | ast.Lambda | ast.List | ast.ListComp | ast.Name | ast.NamedExpr | ast.Set | ast.SetComp | ast.Slice | ast.Starred | ast.Subscript | ast.Tuple | ast.UnaryOp | ast.Yield | ast.YieldFrom
+Ima_targetTypeUNEDITED: typing_TypeAlias = ast.AST
+
+# TODO understand whatever the fuck `typing.TypeVar` is _supposed_ to fucking do.
+TypeCertified = typing_TypeVar('TypeCertified', bound = ast.AST, covariant=True)
+astMosDef = typing_TypeVar('astMosDef', bound=astClassHasDOTnameNotName)
+
+个 = typing_TypeVar('个', bound= ast.AST | ast_Identifier, covariant=True)
+
+Ima_ast_boolop: typing_TypeAlias = ast.boolop | ast.And | ast.Or
+Ima_ast_cmpop: typing_TypeAlias = ast.cmpop | ast.Eq | ast.NotEq | ast.Lt | ast.LtE | ast.Gt | ast.GtE | ast.Is | ast.IsNot | ast.In | ast.NotIn
+Ima_ast_excepthandler: typing_TypeAlias = ast.excepthandler | ast.ExceptHandler
+Ima_ast_expr_context: typing_TypeAlias = ast.expr_context | ast.Load | ast.Store | ast.Del
+Ima_ast_expr: typing_TypeAlias = ast.expr | ast.Attribute | ast.Await | ast.BinOp | ast.BoolOp | ast.Call | ast.Compare | ast.Constant | ast.Dict | ast.DictComp | ast.FormattedValue | ast.GeneratorExp | ast.IfExp | ast.JoinedStr | ast.Lambda | ast.List | ast.ListComp | ast.Name | ast.NamedExpr | ast.Set | ast.SetComp | ast.Slice | ast.Starred | ast.Subscript | ast.Tuple | ast.UnaryOp | ast.Yield | ast.YieldFrom
+Ima_ast_mod: typing_TypeAlias = ast.mod | ast.Expression | ast.FunctionType | ast.Interactive | ast.Module
+Ima_ast_operator: typing_TypeAlias = ast.operator | ast.Add | ast.Sub | ast.Mult | ast.MatMult | ast.Div | ast.Mod | ast.Pow | ast.LShift | ast.RShift | ast.BitOr | ast.BitXor | ast.BitAnd | ast.FloorDiv
+Ima_ast_orphan = ast.alias | ast.arg | ast.arguments | ast.comprehension | ast.keyword | ast.match_case | ast.withitem
+iMa_ast_pattern: typing_TypeAlias = ast.pattern | ast.MatchAs | ast.MatchClass | ast.MatchMapping | ast.MatchOr | ast.MatchSequence | ast.MatchSingleton | ast.MatchStar | ast.MatchValue
+Ima_ast_type_ignore: typing_TypeAlias = ast.type_ignore | ast.TypeIgnore
+Ima_ast_unaryop: typing_TypeAlias = ast.unaryop | ast.Invert | ast.Not | ast.UAdd | ast.USub
+if TYPE_CHECKING:
+	Ima_ast_stmt: typing_TypeAlias = ast.stmt | ast.AnnAssign | ast.Assert | ast.Assign | ast.AsyncFor | ast.AsyncFunctionDef | ast.AsyncWith | ast.AugAssign | ast.Break | ast.ClassDef | ast.Continue | ast.Delete | ast.Expr | ast.For | ast.FunctionDef | ast.Global | ast.If | ast.Import | ast.ImportFrom | ast.Match | ast.Nonlocal | ast.Pass | ast.Raise | ast.Return | ast.Try | ast.TryStar | ast.TypeAlias | ast.While | ast.With
+	Ima_ast_type_param: typing_TypeAlias = ast.type_param | ast.ParamSpec | ast.TypeVar | ast.TypeVarTuple
+else:
+	Ima_ast_stmt = stuPyd
+	Ima_ast_type_param = stuPyd