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

mapFolding/someAssemblyRequired/_toolboxContainers.py

@@ -1,23 +1,55 @@
 """
-Container classes for AST transformations and code synthesis.
+AST Container Classes for Python Code Generation and Transformation
 
-This module provides container classes used in the AST transformation process
-and code synthesis workflows. It acts as a dependency boundary to prevent
-circular imports while providing reusable data structures.
+This module provides specialized container classes that organize AST nodes, imports,
+and program structure for code generation and transformation. These classes form
+the organizational backbone of the code generation system, enabling:
+
+1. Tracking and managing imports with LedgerOfImports
+2. Packaging function definitions with their dependencies via IngredientsFunction
+3. Structuring complete modules with IngredientsModule
+4. Configuring code synthesis with RecipeSynthesizeFlow
+5. Organizing decomposed dataclass representations with ShatteredDataclass
+
+Together, these container classes implement a component-based architecture for
+programmatic generation of high-performance code. They maintain a clean separation
+between structure and content, allowing transformations to be applied systematically
+while preserving relationships between code elements.
+
+The containers work in conjunction with transformation tools that manipulate the
+contained AST nodes to implement specific optimizations and transformations.
 """
+
 from collections import defaultdict
 from collections.abc import Sequence
-from mapFolding.someAssemblyRequired import ImaAnnotationType, ast_Identifier, be, Make, parseLogicalPath2astModule, str_nameDOTname
-from mapFolding.theSSOT import callableDispatcherHARDCODED, The
+from mapFolding.someAssemblyRequired import ast_Identifier, Make, parseLogicalPath2astModule, str_nameDOTname
+from mapFolding.theSSOT import The
 from pathlib import Path, PurePosixPath
-from typing import Literal
 from Z0Z_tools import updateExtendPolishDictionaryLists
 import ast
 import dataclasses
 
+# Consolidate settings classes through inheritance https://github.com/hunterhogan/mapFolding/issues/15
 class LedgerOfImports:
+	"""
+	Track and manage import statements for programmatically generated code.
+
+	LedgerOfImports acts as a registry for import statements, maintaining a clean
+	separation between the logical structure of imports and their textual representation.
+	It enables:
+
+	1. Tracking regular imports and import-from statements
+	2. Adding imports programmatically during code transformation
+	3. Merging imports from multiple sources
+	4. Removing unnecessary or conflicting imports
+	5. Generating optimized AST import nodes for the final code
+
+	This class forms the foundation of dependency management in generated code,
+	ensuring that all required libraries are available without duplication or
+	conflict.
+	"""
 	# TODO When resolving the ledger of imports, remove self-referential imports
-	# TODO TypeIgnore :/
+	# TODO add TypeIgnore tracking to the ledger of imports
 
 	def __init__(self, startWith: ast.AST | None = None) -> None:
 		self.dictionaryImportFrom: dict[str_nameDOTname, list[tuple[ast_Identifier, ast_Identifier | None]]] = defaultdict(list)
@@ -27,10 +59,10 @@ class LedgerOfImports:
 
 	def addAst(self, astImport____: ast.Import | ast.ImportFrom) -> None:
 		assert isinstance(astImport____, (ast.Import, ast.ImportFrom)), f"I received {type(astImport____) = }, but I can only accept {ast.Import} and {ast.ImportFrom}."
-		if be.Import(astImport____):
+		if isinstance(astImport____, ast.Import):
 			for alias in astImport____.names:
 				self.listImport.append(alias.name)
-		elif be.ImportFrom(astImport____):
+		elif isinstance(astImport____, ast.ImportFrom): # type: ignore
 			# TODO fix the mess created by `None` means '.'. I need a `str_nameDOTname` to replace '.'
 			if astImport____.module is None:
 				astImport____.module = '.'
@@ -49,12 +81,11 @@ class LedgerOfImports:
 		self.dictionaryImportFrom[moduleWithLogicalPath].append((name, asname))
 
 	def removeImportFromModule(self, moduleWithLogicalPath: str_nameDOTname) -> None:
-		self.removeImportFrom(moduleWithLogicalPath, None, None)
 		"""Remove all imports from a specific module."""
+		self.removeImportFrom(moduleWithLogicalPath, None, None)
 
 	def removeImportFrom(self, moduleWithLogicalPath: str_nameDOTname, name: ast_Identifier | None, asname: ast_Identifier | None = None) -> None:
-		if moduleWithLogicalPath is None:
-			raise SyntaxError(f"I received `{moduleWithLogicalPath = }`, but it must be the name of a module.")
+		assert moduleWithLogicalPath is not None, SyntaxError(f"I received `{moduleWithLogicalPath = }`, but it must be the name of a module.")
 		if moduleWithLogicalPath in self.dictionaryImportFrom:
 			"""
 			name, 			asname				  	Meaning
@@ -108,20 +139,55 @@ class LedgerOfImports:
 			if isinstance(nodeBuffalo, (ast.Import, ast.ImportFrom)):
 				self.addAst(nodeBuffalo)
 
+# Consolidate settings classes through inheritance https://github.com/hunterhogan/mapFolding/issues/15
 @dataclasses.dataclass
 class IngredientsFunction:
-	"""Everything necessary to integrate a function into a module should be here.
+	"""
+	Package a function definition with its import dependencies for code generation.
+
+	IngredientsFunction encapsulates an AST function definition along with all the
+	imports required for that function to operate correctly. This creates a modular,
+	portable unit that can be:
+
+	1. Transformed independently (e.g., by applying Numba decorators)
+	2. Transplanted between modules while maintaining dependencies
+	3. Combined with other functions to form complete modules
+	4. Analyzed for optimization opportunities
+
+	This class forms the primary unit of function manipulation in the code generation
+	system, enabling targeted transformations while preserving function dependencies.
+
 	Parameters:
-		astFunctionDef: hint `Make.astFunctionDef()`
+		astFunctionDef: The AST representation of the function definition
+		imports: Import statements needed by the function
+		type_ignores: Type ignore comments associated with the function
 	"""
 	astFunctionDef: ast.FunctionDef
 	imports: LedgerOfImports = dataclasses.field(default_factory=LedgerOfImports)
 	type_ignores: list[ast.TypeIgnore] = dataclasses.field(default_factory=list)
 
+# Consolidate settings classes through inheritance https://github.com/hunterhogan/mapFolding/issues/15
 @dataclasses.dataclass
 class IngredientsModule:
-	"""Everything necessary to create one _logical_ `ast.Module` should be here.
-	Extrinsic qualities should _probably_ be handled externally.
+	"""
+	Assemble a complete Python module from its constituent AST components.
+
+	IngredientsModule provides a structured container for all elements needed to
+	generate a complete Python module, including:
+
+	1. Import statements aggregated from all module components
+	2. Prologue code that runs before function definitions
+	3. Function definitions with their dependencies
+	4. Epilogue code that runs after function definitions
+	5. Entry point code executed when the module runs as a script
+	6. Type ignores and other annotations
+
+	This class enables programmatic assembly of Python modules with a clear
+	separation between different structural elements, while maintaining the
+	proper ordering and relationships between components.
+
+	The modular design allows transformations to be applied to specific parts
+	of a module while preserving the overall structure.
 
 	Parameters:
 		ingredientsFunction (None): One or more `IngredientsFunction` that will appended to `listIngredientsFunctions`.
@@ -160,7 +226,7 @@ class IngredientsModule:
 		"""Append one or more statements to `prologue`."""
 		list_body: list[ast.stmt] = []
 		listTypeIgnore: list[ast.TypeIgnore] = []
-		if astModule is not None and be.Module(astModule):
+		if astModule is not None and isinstance(astModule, ast.Module): # type: ignore
 			list_body.extend(astModule.body)
 			listTypeIgnore.extend(astModule.type_ignores)
 		if type_ignores is not None:
@@ -189,10 +255,8 @@ class IngredientsModule:
 	def appendIngredientsFunction(self, *ingredientsFunction: IngredientsFunction) -> None:
 		"""Append one or more `IngredientsFunction`."""
 		for allegedIngredientsFunction in ingredientsFunction:
-			if isinstance(allegedIngredientsFunction, IngredientsFunction):
-				self.listIngredientsFunctions.append(allegedIngredientsFunction)
-			else:
-				raise ValueError(f"I received `{type(allegedIngredientsFunction) = }`, but I can only accept `{IngredientsFunction}`.")
+			assert isinstance(allegedIngredientsFunction, IngredientsFunction), ValueError(f"I received `{type(allegedIngredientsFunction) = }`, but I can only accept `{IngredientsFunction}`.")
+			self.listIngredientsFunctions.append(allegedIngredientsFunction)
 
 	def removeImportFromModule(self, moduleWithLogicalPath: str_nameDOTname) -> None:
 		self.removeImportFrom(moduleWithLogicalPath, None, None)
@@ -201,7 +265,7 @@ class IngredientsModule:
 	def removeImportFrom(self, moduleWithLogicalPath: str_nameDOTname, name: ast_Identifier | None, asname: ast_Identifier | None = None) -> None:
 		"""
 		This method modifies all `LedgerOfImports` in this `IngredientsModule` and all `IngredientsFunction` in `listIngredientsFunctions`.
-		It is not a "blacklist", so the import from could be added after this modification.
+		It is not a "blacklist", so the `import from` could be added after this modification.
 		"""
 		self.imports.removeImportFrom(moduleWithLogicalPath, name, asname)
 		for ingredientsFunction in self.listIngredientsFunctions:
@@ -240,13 +304,33 @@ class IngredientsModule:
 		listTypeIgnore.extend(self.launcher.type_ignores)
 		return listTypeIgnore
 
+# Consolidate settings classes through inheritance https://github.com/hunterhogan/mapFolding/issues/15
 @dataclasses.dataclass
 class RecipeSynthesizeFlow:
-	"""Settings for synthesizing flow."""
+	"""
+	Configure the generation of optimized Numba-accelerated code modules.
+
+	RecipeSynthesizeFlow defines the complete blueprint for transforming an original
+	Python algorithm into an optimized, accelerated implementation. It specifies:
+
+	1. Source code locations and identifiers
+	2. Target code locations and identifiers
+	3. Naming conventions for generated modules and functions
+	4. File system paths for output files
+	5. Import relationships between components
+
+	This configuration class serves as a single source of truth for the code generation
+	process, ensuring consistency across all generated artifacts while enabling
+	customization of the transformation pipeline.
+
+	The transformation process uses this configuration to extract functions from the
+	source module, transform them according to optimization rules, and output
+	properly structured optimized modules with all necessary imports.
+	"""
 	# ========================================
 	# Source
-	# ========================================
-	source_astModule = parseLogicalPath2astModule(The.logicalPathModuleSourceAlgorithm)
+	source_astModule: ast.Module = parseLogicalPath2astModule(The.logicalPathModuleSourceAlgorithm)
+	"""AST of the source algorithm module containing the original implementation."""
 
 	# Figure out dynamic flow control to synthesized modules https://github.com/hunterhogan/mapFolding/issues/4
 	sourceCallableDispatcher: ast_Identifier = The.sourceCallableDispatcher
@@ -294,18 +378,15 @@ class RecipeSynthesizeFlow:
 
 	# ========================================
 	# Computed
-	# ========================================
-	"""
-theFormatStrModuleSynthetic = "{packageFlow}Count"
-theFormatStrModuleForCallableSynthetic = theFormatStrModuleSynthetic + "_{callableTarget}"
-theModuleDispatcherSynthetic: ast_Identifier = theFormatStrModuleForCallableSynthetic.format(packageFlow=packageFlowSynthetic, callableTarget=The.sourceCallableDispatcher)
-theLogicalPathModuleDispatcherSynthetic: str = '.'.join([The.packageName, The.moduleOfSyntheticModules, theModuleDispatcherSynthetic])
-
-	"""
+	# Figure out dynamic flow control to synthesized modules https://github.com/hunterhogan/mapFolding/issues/4
+	# theFormatStrModuleSynthetic = "{packageFlow}Count"
+	# theFormatStrModuleForCallableSynthetic = theFormatStrModuleSynthetic + "_{callableTarget}"
+	# theModuleDispatcherSynthetic: ast_Identifier = theFormatStrModuleForCallableSynthetic.format(packageFlow=packageFlowSynthetic, callableTarget=The.sourceCallableDispatcher)
+	# theLogicalPathModuleDispatcherSynthetic: str = '.'.join([The.packageName, The.moduleOfSyntheticModules, theModuleDispatcherSynthetic])
 	# logicalPathModuleDispatcher: str = '.'.join([Z0Z_flowLogicalPathRoot, moduleDispatcher])
+
 	# ========================================
 	# Filesystem (names of physical objects)
-	# ========================================
 	pathPackage: PurePosixPath | None = PurePosixPath(The.pathPackage)
 	fileExtension: str = The.fileExtension
 
@@ -338,46 +419,50 @@ theLogicalPathModuleDispatcherSynthetic: str = '.'.join([The.packageName, The.mo
 	def pathFilenameSequential(self) -> PurePosixPath:
 		return self._makePathFilename(filenameStem=self.moduleSequential, logicalPathINFIX=self.logicalPathFlowRoot)
 
-	def __post_init__(self) -> None:
-		if ((self.concurrencyManagerIdentifier is not None and self.concurrencyManagerIdentifier != self.sourceConcurrencyManagerIdentifier) # `submit` # type: ignore
-			or ((self.concurrencyManagerIdentifier is None) != (self.concurrencyManagerNamespace is None))): # type: ignore
-			import warnings
-			warnings.warn(f"If your synthesized module is weird, check `{self.concurrencyManagerIdentifier=}` and `{self.concurrencyManagerNamespace=}`. (ChildProcessError? 'Yeah! Children shouldn't be processing stuff, man.')", category=ChildProcessError, stacklevel=2) # pyright: ignore[reportCallIssue, reportArgumentType] Y'all Pynatics need to be less shrill and focus on making code that doesn't need 8000 error categories.
-
-		# self.logicalPathModuleDispatcher!=logicalPathModuleDispatcherHARDCODED or
-		if self.callableDispatcher!=callableDispatcherHARDCODED:
-			print(f"fyi: `{self.callableDispatcher=}` but\n\t`{callableDispatcherHARDCODED=}`.")
-
 dummyAssign = Make.Assign([Make.Name("dummyTarget")], Make.Constant(None))
 dummySubscript = Make.Subscript(Make.Name("dummy"), Make.Name("slice"))
 dummyTuple = Make.Tuple([Make.Name("dummyElement")])
 
+# Consolidate settings classes through inheritance https://github.com/hunterhogan/mapFolding/issues/15
 @dataclasses.dataclass
 class ShatteredDataclass:
-	countingVariableAnnotation: ImaAnnotationType
+	countingVariableAnnotation: ast.expr
 	"""Type annotation for the counting variable extracted from the dataclass."""
+
 	countingVariableName: ast.Name
 	"""AST name node representing the counting variable identifier."""
+
 	field2AnnAssign: dict[ast_Identifier, ast.AnnAssign] = dataclasses.field(default_factory=dict)
 	"""Maps field names to their corresponding AST call expressions."""
+
 	Z0Z_field2AnnAssign: dict[ast_Identifier, tuple[ast.AnnAssign, str]] = dataclasses.field(default_factory=dict)
+
 	fragments4AssignmentOrParameters: ast.Tuple = dummyTuple
 	"""AST tuple used as target for assignment to capture returned fragments."""
+
 	ledger: LedgerOfImports = dataclasses.field(default_factory=LedgerOfImports)
 	"""Import records for the dataclass and its constituent parts."""
+
 	list_argAnnotated4ArgumentsSpecification: list[ast.arg] = dataclasses.field(default_factory=list)
 	"""Function argument nodes with annotations for parameter specification."""
+
 	list_keyword_field__field4init: list[ast.keyword] = dataclasses.field(default_factory=list)
 	"""Keyword arguments for dataclass initialization with field=field format."""
-	listAnnotations: list[ImaAnnotationType] = dataclasses.field(default_factory=list)
+
+	listAnnotations: list[ast.expr] = dataclasses.field(default_factory=list)
 	"""Type annotations for each dataclass field."""
+
 	listName4Parameters: list[ast.Name] = dataclasses.field(default_factory=list)
 	"""Name nodes for each dataclass field used as function parameters."""
+
 	listUnpack: list[ast.AnnAssign] = dataclasses.field(default_factory=list)
 	"""Annotated assignment statements to extract fields from dataclass."""
-	map_stateDOTfield2Name: dict[ast.expr, ast.Name] = dataclasses.field(default_factory=dict)
+
+	map_stateDOTfield2Name: dict[ast.AST, ast.Name] = dataclasses.field(default_factory=dict)
 	"""Maps AST expressions to Name nodes for find-replace operations."""
+
 	repack: ast.Assign = dummyAssign
 	"""AST assignment statement that reconstructs the original dataclass instance."""
+
 	signatureReturnAnnotation: ast.Subscript = dummySubscript
 	"""tuple-based return type annotation for function definitions."""

mapFolding/someAssemblyRequired/_toolboxPython.py

@@ -1,62 +1,183 @@
-from collections.abc import Callable, Sequence
+"""
+Core AST Traversal and Transformation Utilities for Python Code Manipulation
+
+This module provides the foundation for traversing and modifying Python Abstract
+Syntax Trees (ASTs). It contains two primary classes:
+
+1. NodeTourist: Implements the visitor pattern to traverse an AST and extract information
+   from nodes that match specific predicates without modifying the AST.
+
+2. NodeChanger: Extends ast.NodeTransformer to selectively transform AST nodes that
+   match specific predicates, enabling targeted code modifications.
+
+The module also provides utilities for importing modules, loading callables from files,
+and parsing Python code into AST structures, creating a complete workflow for code
+analysis and transformation.
+"""
+
+from collections.abc import Callable
 from inspect import getsource as inspect_getsource
-from mapFolding.someAssemblyRequired import ast_Identifier, str_nameDOTname, 个
+from mapFolding.someAssemblyRequired import ast_Identifier, str_nameDOTname
 from os import PathLike
 from pathlib import Path, PurePath
 from types import ModuleType
-from typing import Any, cast, Generic, TypeGuard
+from typing import Any, Literal
 import ast
 import importlib
 import importlib.util
 
 # TODO Identify the logic that narrows the type and can help the user during static type checking.
 
-class NodeTourist(ast.NodeVisitor, Generic[个]):
-    def __init__(self, findThis: Callable[[个], TypeGuard[个] | bool], doThat: Callable[[个], 个 | None]) -> None:
-        self.findThis = findThis
-        self.doThat = doThat
-        self.nodeCaptured: 个 | None = None
-
-    def visit(self, node: 个) -> None: # pyright: ignore [reportGeneralTypeIssues]
-        if self.findThis(node):
-            nodeActionReturn = self.doThat(node)
-            if nodeActionReturn is not None:
-                self.nodeCaptured = nodeActionReturn
-        self.generic_visit(cast(ast.AST, node))
-
-    def captureLastMatch(self, node: 个) -> 个 | None: # pyright: ignore [reportGeneralTypeIssues]
-        self.nodeCaptured = None
-        self.visit(node)
-        return self.nodeCaptured
-
-class NodeChanger(ast.NodeTransformer, Generic[个]):
-    def __init__(self, findThis: Callable[[个], bool], doThat: Callable[[个], Sequence[个] | 个 | None]) -> None:
-        self.findThis = findThis
-        self.doThat = doThat
-
-    def visit(self, node: 个) -> Sequence[个] | 个 | None: # pyright: ignore [reportGeneralTypeIssues]
-        if self.findThis(node):
-            return self.doThat(node)
-        return super().visit(cast(ast.AST, node))
+class NodeTourist(ast.NodeVisitor):
+	"""
+	Visit and extract information from AST nodes that match a predicate.
+
+	NodeTourist implements the visitor pattern to traverse an AST, applying
+	a predicate function to each node and capturing nodes or their attributes
+	when they match. Unlike NodeChanger, it doesn't modify the AST but collects
+	information during traversal.
+
+	This class is particularly useful for analyzing AST structures, extracting
+	specific nodes or node properties, and gathering information about code patterns.
+	"""
+	def __init__(self, findThis: Callable[..., Any], doThat: Callable[..., Any]) -> None:
+		self.findThis = findThis
+		self.doThat = doThat
+		self.nodeCaptured: Any | None = None
+
+	def visit(self, node: ast.AST) -> None:
+		if self.findThis(node):
+			nodeActionReturn = self.doThat(node)
+			if nodeActionReturn is not None:
+				self.nodeCaptured = nodeActionReturn
+		self.generic_visit(node)
+
+	def captureLastMatch(self, node: ast.AST) -> Any | None:
+		self.nodeCaptured = None
+		self.visit(node)
+		return self.nodeCaptured
+
+class NodeChanger(ast.NodeTransformer):
+	"""
+	Transform AST nodes that match a predicate by applying a transformation function.
+
+	NodeChanger is an AST node transformer that applies a targeted transformation
+	to nodes matching a specific predicate. It traverses the AST and only modifies
+	nodes that satisfy the predicate condition, leaving other nodes unchanged.
+
+	This class extends ast.NodeTransformer and implements the visitor pattern
+	to systematically process and transform an AST tree.
+	"""
+	def __init__(self, findThis: Callable[..., Any], doThat: Callable[..., Any]) -> None:
+		self.findThis = findThis
+		self.doThat = doThat
+
+	def visit(self, node: ast.AST) -> ast.AST:
+		if self.findThis(node):
+			return self.doThat(node)
+		return super().visit(node)
 
 def importLogicalPath2Callable(logicalPathModule: str_nameDOTname, identifier: ast_Identifier, packageIdentifierIfRelative: ast_Identifier | None = None) -> Callable[..., Any]:
-    moduleImported: ModuleType = importlib.import_module(logicalPathModule, packageIdentifierIfRelative)
-    return getattr(moduleImported, identifier)
+	"""
+	Import a callable object (function or class) from a module based on its logical path.
+
+	This function imports a module using `importlib.import_module()` and then retrieves
+	a specific attribute (function, class, or other object) from that module.
+
+	Parameters
+	----------
+	logicalPathModule : str
+		The logical path to the module, using dot notation (e.g., 'package.subpackage.module').
+	identifier : str
+		The name of the callable object to retrieve from the module.
+	packageIdentifierIfRelative : str, optional
+		The package name to use as the anchor point if `logicalPathModule` is a relative import.
+		If None, absolute import is assumed.
+
+	Returns
+	-------
+	Callable[..., Any]
+		The callable object (function, class, etc.) retrieved from the module.
+	"""
+	moduleImported: ModuleType = importlib.import_module(logicalPathModule, packageIdentifierIfRelative)
+	return getattr(moduleImported, identifier)
 
 def importPathFilename2Callable(pathFilename: PathLike[Any] | PurePath, identifier: ast_Identifier, moduleIdentifier: ast_Identifier | None = None) -> Callable[..., Any]:
-    pathFilename = Path(pathFilename)
+	"""
+	Load a callable (function, class, etc.) from a Python file.
+	This function imports a specified Python file as a module, extracts a callable object
+	from it by name, and returns that callable.
+	Parameters
+	----------
+	pathFilename : Union[PathLike[Any], PurePath]
+		Path to the Python file to import.
+	identifier : str
+		Name of the callable to extract from the imported module.
+	moduleIdentifier : Optional[str]
+		Name to use for the imported module. If None, the filename stem is used.
+	Returns
+	-------
+	Callable[..., Any]
+		The callable object extracted from the imported module.
+	Raises
+	------
+	ImportError
+		If the file cannot be imported or the importlib specification is invalid.
+	AttributeError
+		If the identifier does not exist in the imported module.
+	"""
+	pathFilename = Path(pathFilename)
+
+	importlibSpecification = importlib.util.spec_from_file_location(moduleIdentifier or pathFilename.stem, pathFilename)
+	if importlibSpecification is None or importlibSpecification.loader is None: raise ImportError(f"I received\n\t`{pathFilename = }`,\n\t`{identifier = }`, and\n\t`{moduleIdentifier = }`.\n\tAfter loading, \n\t`importlibSpecification` {'is `None`' if importlibSpecification is None else 'has a value'} and\n\t`importlibSpecification.loader` is unknown.")
+
+	moduleImported_jk_hahaha: ModuleType = importlib.util.module_from_spec(importlibSpecification)
+	importlibSpecification.loader.exec_module(moduleImported_jk_hahaha)
+	return getattr(moduleImported_jk_hahaha, identifier)
+
+def parseLogicalPath2astModule(logicalPathModule: str_nameDOTname, packageIdentifierIfRelative: ast_Identifier|None=None, mode: Literal['exec'] = 'exec') -> ast.Module:
+	"""
+	Parse a logical Python module path into an AST Module.
+
+	This function imports a module using its logical path (e.g., 'package.subpackage.module')
+	and converts its source code into an Abstract Syntax Tree (AST) Module object.
+
+	Parameters
+	----------
+	logicalPathModule : str
+		The logical path to the module using dot notation (e.g., 'package.module').
+	packageIdentifierIfRelative : ast.Identifier or None, optional
+		The package identifier to use if the module path is relative, defaults to None.
+	mode : Literal['exec'], optional
+		The parsing mode to use, defaults to 'exec'.
+
+	Returns
+	-------
+	ast.Module
+		An AST Module object representing the parsed source code of the imported module.
+	"""
+	moduleImported: ModuleType = importlib.import_module(logicalPathModule, packageIdentifierIfRelative)
+	sourcePython: str = inspect_getsource(moduleImported)
+	return ast.parse(sourcePython, mode=mode)
 
-    importlibSpecification = importlib.util.spec_from_file_location(moduleIdentifier or pathFilename.stem, pathFilename)
-    if importlibSpecification is None or importlibSpecification.loader is None: raise ImportError(f"I received\n\t`{pathFilename = }`,\n\t`{identifier = }`, and\n\t`{moduleIdentifier = }`.\n\tAfter loading, \n\t`importlibSpecification` {'is `None`' if importlibSpecification is None else 'has a value'} and\n\t`importlibSpecification.loader` is unknown.")
+def parsePathFilename2astModule(pathFilename: PathLike[Any] | PurePath, mode: Literal['exec'] = 'exec') -> ast.Module:
+	"""
+	Parse a file from a given path into an ast.Module.
 
-    moduleImported_jk_hahaha: ModuleType = importlib.util.module_from_spec(importlibSpecification)
-    importlibSpecification.loader.exec_module(moduleImported_jk_hahaha)
-    return getattr(moduleImported_jk_hahaha, identifier)
+	This function reads the content of a file specified by `pathFilename` and parses it into an
+	Abstract Syntax Tree (AST) Module using Python's ast module.
 
-def parseLogicalPath2astModule(logicalPathModule: str_nameDOTname, packageIdentifierIfRelative: ast_Identifier|None=None, mode:str='exec') -> ast.AST:
-    moduleImported: ModuleType = importlib.import_module(logicalPathModule, packageIdentifierIfRelative)
-    sourcePython: str = inspect_getsource(moduleImported)
-    return ast.parse(sourcePython, mode=mode)
+	Parameters
+	----------
+	pathFilename : PathLike[Any] | PurePath
+		The path to the file to be parsed. Can be a string path, PathLike object, or PurePath object.
+	mode : Literal['exec'], optional
+		The mode parameter for ast.parse. Default is 'exec'.
+		Options are 'exec', 'eval', or 'single'. See ast.parse documentation for details.
 
-def parsePathFilename2astModule(pathFilename: PathLike[Any] | PurePath, mode:str='exec') -> ast.AST:
-    return ast.parse(Path(pathFilename).read_text(), mode=mode)
+	Returns
+	-------
+	ast.Module
+		The parsed abstract syntax tree module.
+	"""
+	return ast.parse(Path(pathFilename).read_text(), mode=mode)