mapFolding 0.8.6__py3-none-any.whl → 0.9.0__py3-none-any.whl

mapFolding/__init__.py

@@ -11,36 +11,83 @@ Core modules:
 - basecamp: Public API with simplified interfaces for end users
 - theDao: Core computational algorithm using a functional state-transformation approach
 - beDRY: Core utility functions implementing consistent data handling, validation, and
-  resource management across the package's computational assembly-line
+    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
+    computation results with robust error handling and fallback mechanisms
 - oeis: Interface to the Online Encyclopedia of Integer Sequences for known results
 
 Extended functionality:
 - someAssemblyRequired: Code transformation framework that optimizes the core algorithm
-  through AST manipulation, dataclass transformation, and compilation techniques
+    through AST manipulation, dataclass transformation, and compilation techniques
+    - The system converts readable code into high-performance implementations through
+      a systematic analysis and transformation pipeline
+    - Provides tools to "shatter" complex dataclasses into primitive components,
+      enabling compatibility with Numba and other optimization frameworks
+    - Creates specialized implementations tailored for specific input parameters
+
+Testing and extension:
+- tests: Comprehensive test suite designed for both verification and extension
+    - Provides fixtures and utilities that simplify testing of custom implementations
+    - Enables users to validate their own recipes and job configurations with minimal code
+    - Offers standardized testing patterns that maintain consistency across the codebase
+    - See tests/__init__.py for detailed documentation on extending the test suite
 
 Special directories:
 - .cache/: Stores cached data from external sources like OEIS to improve performance
 - syntheticModules/: Contains dynamically generated, optimized implementations of the
-  core algorithm created by the code transformation framework
+    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 2x19 and 2x20 maps (OEIS A001415)
+    - reference/jobsCompleted/: Contains successful computations for previously unknown values,
+        including first-ever calculations for 2x19 and 2x20 maps (OEIS A001415)
 
 This package balances algorithm readability and understandability with
 high-performance computation capabilities, allowing users to compute map folding
 totals for larger dimensions than previously feasible while also providing
 a foundation for exploring advanced code transformation techniques.
 """
-from mapFolding.basecamp import countFolds
-from mapFolding.oeis import clearOEIScache, getOEISids, OEIS_for_n, oeisIDfor_n
 
 __all__ = [
-    'clearOEIScache',
-    'countFolds',
-    'getOEISids',
-    'OEIS_for_n',
-    'oeisIDfor_n',
+        'clearOEIScache',
+        'countFolds',
+        'getOEISids',
+        'OEIS_for_n',
+        'oeisIDfor_n',
 ]
+
+from mapFolding.theSSOT import (
+    Array1DElephino,
+    Array1DFoldsTotal,
+    Array1DLeavesTotal,
+    Array3D,
+    ComputationState,
+    DatatypeElephino,
+    DatatypeFoldsTotal,
+    DatatypeLeavesTotal,
+    NumPyElephino,
+    NumPyFoldsTotal,
+    NumPyIntegerType,
+    NumPyLeavesTotal,
+    raiseIfNoneGitHubIssueNumber3,
+    The,
+)
+
+from mapFolding.theDao import countInitialize, doTheNeedful
+
+from mapFolding.beDRY import (
+    outfitCountFolds,
+    setProcessorLimit,
+    validateListDimensions,
+)
+
+from mapFolding.toolboxFilesystem import (
+    getPathFilenameFoldsTotal,
+    getPathRootJobDEFAULT,
+    saveFoldsTotal,
+    saveFoldsTotalFAILearly,
+    writeStringToHere,
+)
+
+from mapFolding.basecamp import countFolds
+
+from mapFolding.oeis import clearOEIScache, getFoldsTotalKnown, getOEISids, OEIS_for_n, oeisIDfor_n

mapFolding/basecamp.py

@@ -13,9 +13,16 @@ implementation, and optional persistence of results.
 """
 
 from collections.abc import Sequence
-from mapFolding.theSSOT import ComputationState, getPackageDispatcher, The
-from mapFolding.beDRY import outfitCountFolds, setProcessorLimit, validateListDimensions
-from mapFolding.toolboxFilesystem import getPathFilenameFoldsTotal, saveFoldsTotal, saveFoldsTotalFAILearly
+from mapFolding import (
+	ComputationState,
+	getPathFilenameFoldsTotal,
+	outfitCountFolds,
+	saveFoldsTotal,
+	saveFoldsTotalFAILearly,
+	setProcessorLimit,
+	The,
+	validateListDimensions,
+)
 from os import PathLike
 from pathlib import PurePath
 
@@ -24,18 +31,27 @@ def countFolds(listDimensions: Sequence[int]
 				, computationDivisions: int | str | None = None
 				, CPUlimit: int | float | bool | None = None
 				) -> int:
-	"""Count the total number of possible foldings for a given map dimensions.
+	"""
+	Count the total number of possible foldings for a given map dimensions.
+
+	This function serves as the main public interface to the map folding algorithm,
+	handling all parameter validation, computation state management, and result
+	persistence in a user-friendly way.
 
-	Parameters:
-		listDimensions: List of integers representing the dimensions of the map to be folded.
-		pathLikeWriteFoldsTotal (None): Path, filename, or pathFilename to write the total fold count to.
-			If a directory is provided, creates a file with a default name based on map dimensions.
-		computationDivisions (None):
-			Whether and how to divide the computational work. See notes for details.
-		CPUlimit (None): This is only relevant if there are `computationDivisions`: whether and how to limit the CPU usage. See notes for details.
-	Returns:
-		foldsTotal: Total number of distinct ways to fold a map of the given dimensions.
+	Parameters
+	----------
+	listDimensions: List of integers representing the dimensions of the map to be folded.
+	pathLikeWriteFoldsTotal (None): Path, filename, or pathFilename to write the total fold count to.
+		If a directory is provided, creates a file with a default name based on map dimensions.
+	computationDivisions (None):
+		Whether and how to divide the computational work. See notes for details.
+	CPUlimit (None): This is only relevant if there are `computationDivisions`: whether and how to limit the CPU usage. See notes for details.
+	Returns
+	-------
+	foldsTotal: Total number of distinct ways to fold a map of the given dimensions.
 
+	Notes
+	-----
 	Computation divisions:
 		- 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
@@ -51,7 +67,8 @@ def countFolds(listDimensions: Sequence[int]
 		- Integer `<= -1`: Subtract the absolute value from total CPUs.
 
 	N.B.: You probably don't want to divide the computation into tasks.
-		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.
+
+	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 = setProcessorLimit(CPUlimit, The.concurrencyPackage)
@@ -63,9 +80,7 @@ def countFolds(listDimensions: Sequence[int]
 	else:
 		pathFilenameFoldsTotal = None
 
-	dispatcherCallableProxy = getPackageDispatcher()
-	computationStateComplete: ComputationState = dispatcherCallableProxy(computationStateInitialized)
-	# computationStateComplete: ComputationState = The.dispatcher(computationStateInitialized)
+	computationStateComplete: ComputationState = The.dispatcher(computationStateInitialized)
 
 	computationStateComplete.getFoldsTotal()
 

mapFolding/beDRY.py

@@ -19,7 +19,7 @@ These utilities form a stable internal API that other modules depend on, particu
 produce optimized implementations.
 """
 from collections.abc import Sequence
-from mapFolding.theSSOT import ComputationState, numpyIntegerType
+from mapFolding 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
@@ -165,7 +165,7 @@ def _makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int) -> ndarray
 					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]]:
+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.
 
@@ -193,7 +193,7 @@ def getConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: ty
 	connectionGraph = connectionGraph.astype(datatype)
 	return connectionGraph
 
-def makeDataContainer(shape: int | tuple[int, ...], datatype: type[numpyIntegerType]) -> ndarray[Any, numpy_dtype[numpyIntegerType]]:
+def makeDataContainer(shape: int | tuple[int, ...], datatype: type[NumPyIntegerType]) -> ndarray[Any, numpy_dtype[NumPyIntegerType]]:
 	"""
 	Create a typed NumPy array container with initialized values.
 

mapFolding/oeis.py

@@ -22,8 +22,7 @@ implementation in the package.
 from collections.abc import Callable
 from datetime import datetime, timedelta
 from functools import cache
-from mapFolding.theSSOT import The
-from mapFolding.toolboxFilesystem import writeStringToHere
+from mapFolding import writeStringToHere, The
 from pathlib import Path
 from typing import Any, Final, TYPE_CHECKING
 import argparse
@@ -162,6 +161,27 @@ def _parseBFileOEIS(OEISbFile: str, oeisID: str) -> dict[int, int]:
 	return OEISsequence
 
 def getOEISofficial(pathFilenameCache: Path, url: str) -> None | str:
+	"""
+	Retrieve OEIS sequence data from cache or online source.
+
+	This function implements a caching strategy for OEIS sequence data, first checking
+	if a local cached copy exists and is not expired. If a valid cache exists, it returns
+	the cached content; otherwise, it fetches the data from the OEIS website and
+	writes it to the cache for future use.
+
+	Parameters:
+		pathFilenameCache: Path to the local cache file.
+		url: URL to retrieve the OEIS sequence data from if cache is invalid or missing.
+
+	Returns:
+		oeisInformation: The retrieved OEIS sequence information as a string, or None if
+		the information could not be retrieved.
+
+	Notes:
+		The cache expiration period is controlled by the global `cacheDays` variable.
+		If the function fails to retrieve data from both cache and online source,
+		it will return None and issue a warning.
+	"""
 	tryCache: bool = False
 	if pathFilenameCache.exists():
 		fileAge: timedelta = datetime.now() - datetime.fromtimestamp(pathFilenameCache.stat().st_mtime)
@@ -175,6 +195,7 @@ def getOEISofficial(pathFilenameCache: Path, url: str) -> None | str:
 			tryCache = False
 
 	if not tryCache:
+		# Change http handling #13
 		httpResponse: urllib.response.addinfourl = urllib.request.urlopen(url)
 		oeisInformation = httpResponse.read().decode('utf-8')
 		writeStringToHere(oeisInformation, pathFilenameCache)
@@ -214,6 +235,27 @@ def getOEISidValues(oeisID: str) -> dict[int, int]:
 	return {-1: -1}
 
 def getOEISidInformation(oeisID: str) -> tuple[str, int]:
+	"""
+	Retrieve the description and offset for an OEIS sequence.
+
+	This function fetches the metadata for a given OEIS sequence ID, including
+	its textual description and index offset value. It uses a caching mechanism
+	to avoid redundant network requests while ensuring data freshness.
+
+	Parameters:
+		oeisID: The OEIS sequence identifier to retrieve information for.
+
+	Returns:
+		A tuple containing:
+		- description: A string describing the sequence's mathematical meaning.
+		- offset: An integer representing the starting index of the sequence.
+		  Usually 0 or 1, depending on the mathematical context.
+
+	Notes:
+		Sequence descriptions are parsed from the machine-readable format of OEIS.
+		If information cannot be retrieved, warning messages are issued and
+		fallback values are returned.
+	"""
 	oeisID = validateOEISid(oeisID)
 	pathFilenameCache: Path = pathCache / f"{oeisID}.txt"
 	url: str = f"https://oeis.org/search?q=id:{oeisID}&fmt=text"
@@ -243,6 +285,26 @@ def getOEISidInformation(oeisID: str) -> tuple[str, int]:
 	return description, offset
 
 def makeSettingsOEIS() -> dict[str, SettingsOEIS]:
+	"""
+	Construct the comprehensive settings dictionary for all implemented OEIS sequences.
+	
+	This function builds a complete configuration dictionary for all supported OEIS 
+	sequences by retrieving and combining:
+	1. Sequence values from OEIS b-files
+	2. Sequence metadata (descriptions and offsets)
+	3. Hardcoded mapping functions and test values
+	
+	The resulting dictionary provides a single authoritative source for all OEIS-related 
+	configurations used throughout the package, including:
+	- Mathematical descriptions of each sequence
+	- Functions to convert between sequence indices and map dimensions
+	- Known sequence values retrieved from OEIS
+	- Testing and benchmarking reference values
+	
+	Returns:
+		A dictionary mapping OEIS sequence IDs to their complete settings objects,
+		containing all metadata and known values needed for computation and validation.
+	"""
 	settingsTarget: dict[str, SettingsOEIS] = {}
 	for oeisID in oeisIDsImplemented:
 		valuesKnownSherpa: dict[int, int] = getOEISidValues(oeisID)
@@ -277,6 +339,25 @@ def makeDictionaryFoldsTotalKnown() -> dict[tuple[int, ...], int]:
 	return dictionaryMapDimensionsToFoldsTotalKnown
 
 def getFoldsTotalKnown(mapShape: tuple[int, ...]) -> int:
+	"""
+	Retrieve the known total number of foldings for a given map shape.
+	
+	This function looks up precalculated folding totals for specific map dimensions
+	from OEIS sequences. It serves as a rapid reference for known values without
+	requiring computation, and can be used to validate algorithm results.
+	
+	Parameters:
+		mapShape: A tuple of integers representing the dimensions of the map.
+	
+	Returns:
+		foldingsTotal: The known total number of foldings for the given map shape,
+		or -1 if the map shape doesn't match any known values in the OEIS sequences.
+	
+	Notes:
+		The function uses a cached dictionary (via makeDictionaryFoldsTotalKnown) to
+		efficiently retrieve values without repeatedly parsing OEIS data. Map shape
+		tuples are sorted internally to ensure consistent lookup regardless of dimension order.
+	"""
 	lookupFoldsTotal = makeDictionaryFoldsTotalKnown()
 	return lookupFoldsTotal.get(tuple(mapShape), -1)
 

mapFolding/someAssemblyRequired/__init__.py

@@ -1,46 +1,67 @@
 """
-Code transformation framework for algorithmic optimization.
+Code Transformation Framework for Algorithm Optimization and Testing
 
 This package implements a comprehensive framework for programmatically analyzing,
-transforming, and generating Python code. It enables sophisticated algorithm optimization
-through abstract syntax tree (AST) manipulation, allowing algorithms to be transformed
-from a readable, functional implementation into highly-optimized variants tailored for
-different execution environments or specific computational tasks.
+transforming, and generating optimized Python code. It serves as the algorithmic
+optimization engine for the mapFolding package, enabling the conversion of readable,
+functional implementations into highly-optimized variants with verified correctness.
 
-Core capabilities:
-1. AST Pattern Recognition - Precisely identify and match code patterns using composable predicates
-2. Algorithm Transformation - Convert functional state-based implementations to primitive operations
-3. Dataclass "Shattering" - Decompose complex state objects into primitive components
-4. Performance Optimization - Apply domain-specific optimizations for numerical computation
-5. Code Generation - Generate specialized implementations with appropriate imports and syntax
+## Core Architecture Components
 
-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
-maximum execution speed in production.
+1. **AST Manipulation Tools**
+   - Pattern recognition with composable predicates (ifThis)
+   - Node access with consistent interfaces (DOT)
+   - AST traversal and transformation (NodeChanger, NodeTourist)
+   - AST construction with sane defaults (Make)
+   - Node transformation operations (grab, Then)
 
-These tools were developed for map folding computation optimization but are designed as
-general-purpose utilities applicable to a wide range of code transformation scenarios,
-particularly for numerically-intensive algorithms that benefit from just-in-time compilation.
+2. **Container and Organization**
+   - Import tracking and management (LedgerOfImports)
+   - Function packaging with dependencies (IngredientsFunction)
+   - Module assembly with structured components (IngredientsModule)
+   - Recipe configuration for generating optimized code (RecipeSynthesizeFlow)
+   - Dataclass decomposition for compatibility (ShatteredDataclass)
+
+3. **Optimization Pipelines**
+   - General-purpose Numba acceleration (makeNumbaFlow)
+   - Job-specific optimization for concrete parameters (makeJobNumba)
+   - Specialized component transformation (decorateCallableWithNumba)
+
+## Integration with Testing Framework
+
+The transformation components are extensively tested through the package's test suite,
+which provides specialized fixtures and utilities for validating both the transformation
+process and the resulting optimized code:
+
+- **syntheticDispatcherFixture**: Creates and tests a complete Numba-optimized module
+  using RecipeSynthesizeFlow configuration
+
+- **test_writeJobNumba**: Tests the job-specific optimization process with RecipeJob
+
+These fixtures enable users to test their own custom recipes and job configurations
+with minimal effort. See the documentation in tests/__init__.py for details on
+extending the test suite for custom implementations.
+
+The framework balances multiple optimization levels - from general algorithmic
+improvements to parameter-specific optimizations - while maintaining the ability
+to verify correctness at each transformation stage through the integrated test suite.
 """
+
 from mapFolding.someAssemblyRequired._theTypes import (
 	ast_expr_Slice,
 	ast_Identifier,
 	astClassHasDOTnameNotName,
 	astClassHasDOTtarget,
+	astClassHasDOTvalue_expr,
+	astClassHasDOTvalue_exprNone,
+	astClassHasDOTtargetAttributeNameSubscript,
+	astClassHasDOTtarget_expr,
 	astClassHasDOTvalue,
 	astClassOptionallyHasDOTnameNotName,
-	astMosDef,
-	Ima_funcTypeUNEDITED,
-	Ima_targetTypeUNEDITED,
-	ImaAnnotationType,
-	ImaAnnotationTypeVar,
 	intORlist_ast_type_paramORstr_orNone,
 	intORstr_orNone,
 	list_ast_type_paramORstr_orNone,
 	str_nameDOTname,
-	TypeCertified,
 	个,
 	)
 
@@ -53,9 +74,9 @@ from mapFolding.someAssemblyRequired._toolboxPython import (
 	parsePathFilename2astModule,
 	)
 
-from mapFolding.someAssemblyRequired._toolboxAntecedents import be, DOT, ifThis, 又
+from mapFolding.someAssemblyRequired._toolboxAntecedents import DOT, ifThis
 from mapFolding.someAssemblyRequired._tool_Make import Make
-from mapFolding.someAssemblyRequired._tool_Then import Then
+from mapFolding.someAssemblyRequired._tool_Then import grab, Then
 
 from mapFolding.someAssemblyRequired._toolboxContainers import (
 	IngredientsFunction,

mapFolding/someAssemblyRequired/_theTypes.py

@@ -1,20 +1,24 @@
-"""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
+# TODO understand typing.
 
 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
+	astClassHasDOTvalue_expr: typing_TypeAlias = ast.Assign | ast.Attribute | ast.AugAssign | ast.Await | ast.DictComp | ast.Expr | ast.FormattedValue | ast.keyword | ast.MatchValue | ast.NamedExpr | ast.Starred | ast.Subscript | ast.TypeAlias | ast.YieldFrom
+
 else:
 	astClassHasDOTnameNotName = stuPyd
-	astClassHasDOTvalue = stuPyd
+	astClassHasDOTvalue_expr = stuPyd
 
+astClassHasDOTtargetAttributeNameSubscript: typing_TypeAlias = ast.AnnAssign | ast.AugAssign
+astClassHasDOTtarget_expr: typing_TypeAlias = ast.AsyncFor | ast.comprehension | ast.For
+astClassHasDOTtarget: typing_TypeAlias = ast.NamedExpr | astClassHasDOTtarget_expr | astClassHasDOTtargetAttributeNameSubscript
 astClassOptionallyHasDOTnameNotName: typing_TypeAlias = ast.ExceptHandler | ast.MatchAs | ast.MatchStar
-astClassHasDOTtarget: typing_TypeAlias = ast.AnnAssign | ast.AsyncFor | ast.AugAssign | ast.comprehension | ast.For | ast.NamedExpr
+astClassHasDOTvalue_exprNone: typing_TypeAlias = ast.AnnAssign | ast.Return | ast.Yield
+astClassHasDOTvalue: typing_TypeAlias = ast.Constant | ast.MatchSingleton | astClassHasDOTvalue_expr | astClassHasDOTvalue_exprNone
 
 ast_expr_Slice: typing_TypeAlias = ast.expr
 ast_Identifier: typing_TypeAlias = str
@@ -22,18 +26,10 @@ 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)
+个 = typing_TypeVar('个', bound= ast.AST, covariant=True)
 
+# All ast classes by subgroup:
 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

mapFolding/someAssemblyRequired/_tool_Make.py

@@ -1,8 +1,20 @@
+"""
+AST Node Construction Utilities for Python Code Generation
+
+This module provides the Make class with static methods for creating AST nodes
+with sane defaults. It abstracts away the complexity of constructing AST nodes
+directly, making programmatic code generation more intuitive and less error-prone.
+
+The Make class serves as a factory for creating various types of AST nodes needed
+in code generation, transformation, and analysis workflows. Each method follows
+a consistent pattern that maps cleanly to Python's syntax while handling the
+details of AST node construction.
+"""
+
 from collections.abc import Sequence
 from mapFolding.someAssemblyRequired import (
 	ast_expr_Slice,
 	ast_Identifier,
-	ImaAnnotationType,
 	intORlist_ast_type_paramORstr_orNone,
 	intORstr_orNone,
 	list_ast_type_paramORstr_orNone,
@@ -30,71 +42,86 @@ class Make:
 	@staticmethod
 	def alias(name: ast_Identifier, asname: ast_Identifier | None = None) -> ast.alias:
 		return ast.alias(name, asname)
+
 	@staticmethod
-	def AnnAssign(target: ast.Attribute | ast.Name | ast.Subscript, annotation: ImaAnnotationType, value: ast.expr | None = None, **keywordArguments: int) -> ast.AnnAssign: # `simple: int`: uses a clever int-from-boolean to assign the correct value to the `simple` attribute. So, don't make it a method parameter.
+	def AnnAssign(target: ast.Attribute | ast.Name | ast.Subscript, annotation: ast.expr, value: ast.expr | None = None, **keywordArguments: int) -> ast.AnnAssign: # `simple: int`: uses a clever int-from-boolean to assign the correct value to the `simple` attribute. So, don't make it a method parameter.
 		return ast.AnnAssign(target, annotation, value, simple=int(isinstance(target, ast.Name)), **keywordArguments)
+
 	@staticmethod
 	def arg(identifier: ast_Identifier, annotation: ast.expr | None = None, **keywordArguments: intORstr_orNone) -> ast.arg:
 		return ast.arg(identifier, annotation, **keywordArguments)
+
 	@staticmethod
 	def argumentsSpecification(posonlyargs:list[ast.arg]=[], args:list[ast.arg]=[], vararg:ast.arg|None=None, kwonlyargs:list[ast.arg]=[], kw_defaults:list[ast.expr|None]=[None], kwarg:ast.arg|None=None, defaults:list[ast.expr]=[]) -> ast.arguments:
 		return ast.arguments(posonlyargs, args, vararg, kwonlyargs, kw_defaults, kwarg, defaults)
+
 	@staticmethod
 	def Assign(listTargets: Any, value: ast.expr, **keywordArguments: intORstr_orNone) -> ast.Assign:
 		return ast.Assign(listTargets, value, **keywordArguments)
+
 	@staticmethod
 	def Attribute(value: ast.expr, *attribute: ast_Identifier, context: ast.expr_context = ast.Load(), **keywordArguments: int) -> ast.Attribute:
 		""" If two `ast_Identifier` are joined by a dot `.`, they are _usually_ an `ast.Attribute`, but see `ast.ImportFrom`.
 		Parameters:
-			value: the part before the dot (Often `ast.Name`, but also `ast.Attribute`, `ast.Starred`, and `ast.Subscript`.)
+			value: the part before the dot (e.g., `ast.Name`.)
 			attribute: an `ast_Identifier` after a dot `.`; you can pass multiple `attribute` and they will be chained together.
 		"""
-		# TODO confirm the precision of the docstring.
-		def addDOTattribute(chain, identifier: ast_Identifier, context: ast.expr_context, **keywordArguments: int) -> ast.Attribute:
+		def addDOTattribute(chain: ast.expr, identifier: ast_Identifier, context: ast.expr_context, **keywordArguments: int) -> ast.Attribute:
 			return ast.Attribute(value=chain, attr=identifier, ctx=context, **keywordArguments)
 		buffaloBuffalo = addDOTattribute(value, attribute[0], context, **keywordArguments)
 		for identifier in attribute[1:None]:
 			buffaloBuffalo = addDOTattribute(buffaloBuffalo, identifier, context, **keywordArguments)
 		return buffaloBuffalo
+
 	@staticmethod
-	# TODO are the types for `callee` comprehensive?
-	# TODO is there an easier way to create precise typings for `ast`? I mean, it's a fucking closed system: there should be a lot of mystery involved.
-	def Call(callee: ast.Attribute | ast.Name | ast.Subscript, listArguments: Sequence[ast.expr] | None = None, list_astKeywords: Sequence[ast.keyword] | None = None) -> ast.Call:
+	def Call(callee: ast.expr, listArguments: Sequence[ast.expr] | None = None, list_astKeywords: Sequence[ast.keyword] | None = None) -> ast.Call:
 		return ast.Call(func=callee, args=list(listArguments) if listArguments else [], keywords=list(list_astKeywords) if list_astKeywords else [])
+
 	@staticmethod
 	def ClassDef(name: ast_Identifier, listBases: list[ast.expr]=[], list_keyword: list[ast.keyword]=[], body: list[ast.stmt]=[], decorator_list: list[ast.expr]=[], **keywordArguments: list_ast_type_paramORstr_orNone) -> ast.ClassDef:
 		return ast.ClassDef(name, listBases, list_keyword, body, decorator_list, **keywordArguments)
+
 	@staticmethod
 	def Constant(value: Any, **keywordArguments: intORstr_orNone) -> ast.Constant:
 		"""value: str|int|float|bool|None|bytes|bytearray|memoryview|complex|list|tuple|dict|set, or any other type that can be represented as a constant in Python."""
 		return ast.Constant(value, **keywordArguments)
+
 	@staticmethod
 	def Expr(value: ast.expr, **keywordArguments: int) -> ast.Expr:
 		return ast.Expr(value, **keywordArguments)
+
 	@staticmethod
 	def FunctionDef(name: ast_Identifier, argumentsSpecification:ast.arguments=ast.arguments(), body:list[ast.stmt]=[], decorator_list:list[ast.expr]=[], returns:ast.expr|None=None, **keywordArguments: intORlist_ast_type_paramORstr_orNone) -> ast.FunctionDef:
 		return ast.FunctionDef(name, argumentsSpecification, body, decorator_list, returns, **keywordArguments)
+
 	@staticmethod
 	def Import(moduleWithLogicalPath: str_nameDOTname, asname: ast_Identifier | None = None, **keywordArguments: int) -> ast.Import:
 		return ast.Import(names=[Make.alias(moduleWithLogicalPath, asname)], **keywordArguments)
+
 	@staticmethod
 	def ImportFrom(moduleWithLogicalPath: str_nameDOTname, list_astAlias: list[ast.alias], **keywordArguments: int) -> ast.ImportFrom:
 		return ast.ImportFrom(moduleWithLogicalPath, list_astAlias, **keywordArguments)
+
 	@staticmethod
 	def keyword(keywordArgument: ast_Identifier, value: ast.expr, **keywordArguments: int) -> ast.keyword:
 		return ast.keyword(arg=keywordArgument, value=value, **keywordArguments)
+
 	@staticmethod
 	def Module(body: list[ast.stmt] = [], type_ignores: list[ast.TypeIgnore] = []) -> ast.Module:
 		return ast.Module(body, type_ignores)
+
 	@staticmethod
 	def Name(identifier: ast_Identifier, context: ast.expr_context = ast.Load(), **keywordArguments: int) -> ast.Name:
 		return ast.Name(identifier, context, **keywordArguments)
+
 	@staticmethod
 	def Return(value: ast.expr | None = None, **keywordArguments: int) -> ast.Return:
 		return ast.Return(value, **keywordArguments)
+
 	@staticmethod
 	def Subscript(value: ast.expr, slice: ast_expr_Slice, context: ast.expr_context = ast.Load(), **keywordArguments: int) -> ast.Subscript:
 		return ast.Subscript(value, slice, context, **keywordArguments)
+
 	@staticmethod
 	def Tuple(elements: Sequence[ast.expr] = [], context: ast.expr_context = ast.Load(), **keywordArguments: int) -> ast.Tuple:
 		return ast.Tuple(list(elements), context, **keywordArguments)